README

Yii2 client for opentok (http://www.tokbox.com/opentok)

安装

1. 运行 Composer 命令以安装最新版本

   composer require abushamleh/yii2-opentok "dev-master"

2. 将组件添加到 config/main.php

   'components' => [
       // ...
       'opentok' => [
           'class'      => 'abushamleh\opentok\Client',
           'api_key'    => 'your api key',
           'api_secret' => 'your secret key',
       ],
       // ...
   ],

创建会话

要创建 OpenTok 会话，请使用 OpenTok\OpenTok 类的 createSession($options) 方法。参数 $options 是一个可选数组，用于指定以下内容：

• 设置会话是否使用 OpenTok 媒体路由器或尝试直接在客户端之间发送流。

• 设置会话是否自动创建存档（意味着使用路由会话）。

• 指定位置提示。

OpenTok\Session 实例的 getSessionId() 方法返回会话 ID，您使用它来在 OpenTok 客户端库中识别会话。

use OpenTok\MediaMode;
use OpenTok\ArchiveMode;

// Create a session that attempts to use peer-to-peer streaming:
$session = Yii::$app->opentok->createSession();

// A session that uses the OpenTok Media Router, which is required for archiving:
$session = Yii::$app->opentok->createSession(array( 'mediaMode' => MediaMode::ROUTED ));

// A session with a location hint:
$session = Yii::$app->opentok->createSession(array( 'location' => '12.34.56.78' ));

// An automatically archived session:
$sessionOptions = array(
    'archiveMode' => ArchiveMode::ALWAYS,
    'mediaMode' => MediaMode::ROUTED
);
$session = Yii::$app->opentok->createSession($sessionOptions);


// Store this sessionId in the database for later use
$sessionId = $session->getSessionId();

生成令牌

会话创建后，您可以开始为连接到它的客户端生成令牌。您可以通过调用 OpenTok\OpenTok 类的 generateToken($sessionId, $options) 方法或创建会话后调用 OpenTok\Session 实例上的 generateToken($options) 方法来生成令牌。参数 $options 是一个可选数组，用于设置令牌的角色、过期时间和连接数据。为了在存档和广播中进行布局控制，还可以设置使用此令牌从连接发布的流的初始布局类列表。

use OpenTok\Session;
use OpenTok\Role;

// Generate a Token from just a sessionId (fetched from a database)
$token = Yii::$app->opentok->generateToken($sessionId);
// Generate a Token by calling the method on the Session (returned from createSession)
$token = $session->generateToken();

// Set some options in a token
$token = $session->generateToken(array(
    'role'       => Role::MODERATOR,
    'expireTime' => time()+(7 * 24 * 60 * 60), // in one week
    'data'       => 'name=Johnny',
    'initialLayoutClassList' => array('focus')
));

处理流

您可以通过调用 OpenTok\OpenTok 类的 getStream($sessionId, $streamId) 方法来获取有关流的详细信息。

use OpenTok\Session;

// Get stream info from just a sessionId (fetched from a database)
$stream = Yii::$app->opentok->getStream($sessionId, $streamId);

// Stream properties
$stream->id; // string with the stream ID
$stream->videoType; // string with the video type
$stream->name; // string with the name
$stream->layoutClassList; // array with the layout class list

您可以通过调用 OpenTok\OpenTok 类的 listStreams($sessionId) 方法来获取有关会话中所有流的详细信息。

use OpenTok\Session;

// Get list of streams from just a sessionId (fetched from a database)
$streamList = Yii::$app->opentok->listStreams($sessionId);

$streamList->totalCount(); // total count

处理存档

您只能存档使用 OpenTok 媒体路由器（媒体模式设置为路由）的会话。

您可以使用 OpenTok\OpenTok 类的 startArchive($sessionId, $name) 方法开始录制 OpenTok 会话。这将返回一个 OpenTok\Archive 实例。参数 $archiveOptions 是一个可选数组，用于指定名称、是否录制音频和/或视频、存档的期望输出模式以及适用的期望分辨率。请注意，您只能在已连接客户端的会话上开始存档。

// Create a simple archive of a session
$archive = Yii::$app->opentok->startArchive($sessionId);


// Create an archive using custom options
$archiveOptions = array(
    'name' => 'Important Presentation',     // default: null
    'hasAudio' => true,                     // default: true
    'hasVideo' => true,                     // default: true
    'outputMode' => OutputMode::COMPOSED,   // default: OutputMode::COMPOSED
    'resolution' => '1280x720'              // default: '640x480'
);
$archive = Yii::$app->opentok->startArchive($sessionId, $archiveOptions);

// Store this archiveId in the database for later use
$archiveId = $archive->id;

如果将 outputMode 选项设置为 OutputMode::INDIVIDUAL，则会导致存档中的每个流都记录到自己的单独文件中。请注意，当将 outputMode 选项设置为 OutputMode::INDIVIDUAL 时，无法指定分辨率。《OutputMode::COMPOSED》设置（默认）将导致存档中的所有流都记录到单个（组合）文件中。

请注意，您还可以通过将 ArchiveMode::ALWAYS 作为 archiveMode 键传递给 OpenTok->createSession() 方法中传递的 options 参数来创建自动存档会话（请参阅“创建会话”，如上所述）。

您可以使用 OpenTok\OpenTok 对象的 stopArchive($archiveId) 方法停止已启动的存档的录制。您也可以使用 OpenTok\Archive 实例的 stop() 方法来完成此操作。

// Stop an Archive from an archiveId (fetched from database)
Yii::$app->opentok->stopArchive($archiveId);
// Stop an Archive from an Archive instance (returned from startArchive)
$archive->stop();

要从一个存档 ID 获取 OpenTok\Archive 实例（以及所有相关信息），请使用 OpenTok\OpenTok 类的 getArchive($archiveId) 方法。

$archive = Yii::$app->opentok->getArchive($archiveId);

要删除存档，您可以通过调用OpenTok\OpenTok类的deleteArchive($archiveId)方法或OpenTok\Archive实例的delete()方法来实现。

// Delete an Archive from an archiveId (fetched from database)
Yii::$app->opentok->deleteArchive($archiveId);
// Delete an Archive from an Archive instance (returned from startArchive, getArchive)
$archive->delete();

您还可以使用您的API密钥获取您创建的所有存档列表（最多1000个）。这是通过使用OpenTok/OpenTok类的listArchives($offset, $count)方法完成的。参数$offset和$count是可选的，可以帮助您分页浏览结果。这将返回一个OpenTok\ArchiveList类的实例。

$archiveList = Yii::$app->opentok->listArchives();

// Get an array of OpenTok\Archive instances
$archives = $archiveList->getItems();
// Get the total number of Archives for this API Key
$totalCount = $archiveList->totalCount();

对于组合存档，您可以使用updateArchiveLayout($archiveId, $layoutType)方法动态更改布局。

use OpenTok\OpenTok;

$layout Layout::getPIP(); // Or use another get method of the Layout class.
Yii::$app->opentok->updateArchiveLayout($archiveId, $layout);

您可以通过在创建客户端令牌时设置layout选项，使用OpenTok->generateToken()方法或Session->generateToken()方法，为客户端的流设置初始布局类。您还可以通过调用OpenTok->updateStream()方法来更改流的布局类。

设置组合存档的布局是可选的。默认情况下，组合存档使用“最佳适应”布局（见自定义组合存档的视频布局）。

有关存档的更多信息，请参阅OpenTok存档开发者指南。

与广播一起工作

您只能为使用OpenTok媒体路由器（媒体模式设置为路由）的会话启动实时流媒体广播。

使用OpenTok\OpenTok类的startBroadcast($sessionId, $options)方法开始OpenTok会话的实时流媒体广播。这将返回一个OpenTok\Broadcast实例。参数$options是一个可选的数组，用于为广播分配布局类型。

// Start a live streaming broadcast of a session
$broadcast = Yii::$app->opentok->startBroadcast($sessionId);


// Start a live streaming broadcast of a session, setting a layout type
$options = array(
    'layout' => Layout::getBestFit()
);
$broadcast = Yii::$app->opentok->startBroadcast($sessionId, $options);

// Store the broadcast ID in the database for later use
$broadcastId = $broadcast->id;

您可以使用OpenTok\OpenTok对象的stopBroadcast($broadcastId)方法停止实时流媒体广播。您也可以使用OpenTok\Broadcast实例的stop()方法来完成此操作。

// Stop a broadcast from an broadcast ID (fetched from database)
Yii::$app->opentok->stopBroadcast($broadcastId);

// Stop a broadcast from an Broadcast instance (returned from startBroadcast)
$broadcast->stop();

要从广播ID获取OpenTok\Broadcast实例（及其所有信息），请使用OpenTok\OpenTok类的getBroadcast($broadcastId)方法。

$broadcast = Yii::$app->opentok->getBroadcast($broadcastId);

您可以使用OpenTok->updateBroadcastLayout($broadcastId, $layout)方法动态更改布局。

use OpenTok\OpenTok;

$layout Layout::getPIP(); // Or use another get method of the Layout class.
Yii::$app->opentok->updateBroadcastLayout($broadcastId, $layout);

您可以使用Layout类设置布局类型：Layout::getHorizontalPresentation()、Layout::getVerticalPresentation()、Layout::getPIP()、Layout::getBestFit()、Layout::createCustom()。

$layoutType = Layout::getHorizontalPresentation();
Yii::$app->opentok->setArchiveLayout($archiveId, $layoutType);

// For custom Layouts, you can do the following
$options = array(
    'stylesheet' => 'stream.instructor {position: absolute; width: 100%;  height:50%;}'
);

$layoutType = Layout::createCustom($options);
Yii::$app->opentok->setArchiveLayout($archiveId, $layoutType);

您可以通过在为客户端创建令牌时设置layout选项，使用OpenTok->generateToken()方法或Session->generateToken()方法，为客户端的流设置初始布局类。您还可以通过调用Yii::$app->opentok->updateStream()方法来更改流的布局类。

设置实时流媒体广播的布局是可选的。默认情况下，广播使用“最佳适应”布局（见配置OpenTok实时流媒体广播的视频布局）。

有关实时流媒体广播的更多信息，请参阅OpenTok实时流媒体广播开发者指南。

强制客户端断开连接

您的应用程序服务器可以通过调用OpenTok\OpenTok类的forceDisconnect($sessionId, $connectionId)方法从OpenTok会话中断开客户端。

use OpenTok\OpenTok;

// Force disconnect a client connection
Yii::$app->opentok->forceDisconnect($sessionId, $connectionId);

发送信号

会话创建后，您可以向会话中的每个人或特定的连接发送信号。您可以通过调用OpenTok\OpenTok类的signal($sessionId, $payload, $connectionId)方法发送信号。

$sessionId 参数是会话的会话 ID。

$payload 参数是一个关联数组，用于设置以下内容：

• data (字符串) -- 信号的字符串数据。您可以发送的最大数据量是 8kB。

• type (字符串) -- (可选) 信号的类型字符串。您可以发送的最大字符数是 128 个，并且仅允许以下字符：A-Z, a-z, 数字 (0-9), '-', '_', 和 '~'。

$connectionId 参数是一个可选的字符串，用于指定连接到会话的客户端的连接 ID。如果您指定此值，则信号将发送到指定的客户端。否则，信号将发送到连接到会话的所有客户端。

use OpenTok\OpenTok;

// Send a signal to a specific client
$signalPayload = array(
    'data' => 'some signal message',
    'type' => 'signal type'
);
$connectionId = 'da9cb410-e29b-4c2d-ab9e-fe65bf83fcaf';
Yii::$app->opentok->signal($sessionId, $signalPayload, $connectionId);

// Send a signal to everyone in the session
$signalPayload = array(
    'data' => 'some signal message',
    'type' => 'signal type'
);
Yii::$app->opentok->signal($sessionId, $signalPayload);

有关更多信息，请参阅 OpenTok 信号开发指南。

使用 SIP Interconnect

您可以使用 SIP Interconnect 功能添加来自外部第三方 SIP 网关的纯音频流。这需要 SIP URI、您希望添加纯音频流的会话 ID 以及连接到该会话 ID 的令牌。

要发起 SIP 通话，请调用 OpenTok\OpenTok 类的 dial($sessionId, $token, $sipUri, $options) 方法

$sipUri = 'sip:user@sip.partner.com;transport=tls';

$options = array(
  'headers' =>  array(
    'X-CUSTOM-HEADER' => 'headerValue'
  ),
  'auth' => array(
    'username' => 'username',
    'password' => 'password'
  ),
  'secure' => true,
  'from' => 'from@example.com'
);

Yii::$app->opentok->dial($sessionId, $token, $sipUri, $options);

有关更多信息，请参阅 OpenTok SIP Interconnect 开发指南。

强制断开连接

您的应用程序服务器可以通过调用OpenTok\OpenTok类的forceDisconnect($sessionId, $connectionId)方法从OpenTok会话中断开客户端。

use OpenTok\OpenTok;

// Force disconnect a client connection
Yii::$app->opentok->forceDisconnect($sessionId, $connectionId);

发送信号

会话创建后，您可以向会话中的每个人或特定的连接发送信号。您可以通过调用OpenTok\OpenTok类的signal($sessionId, $payload, $connectionId)方法发送信号。

$sessionId 参数是会话的会话 ID。

$payload 参数是一个关联数组，用于设置以下内容：

• data (字符串) -- 信号的字符串数据。您可以发送的最大数据量是 8kB。

• type (字符串) -- (可选) 信号的类型字符串。您可以发送的最大字符数是 128 个，并且仅允许以下字符：A-Z, a-z, 数字 (0-9), '-', '_', 和 '~'。

$connectionId 参数是一个可选的字符串，用于指定连接到会话的客户端的连接 ID。如果您指定此值，则信号将发送到指定的客户端。否则，信号将发送到连接到会话的所有客户端。

use OpenTok\OpenTok;

// Send a signal to a specific client
$signalPayload = array(
    'data' => 'some signal message',
    'type' => 'signal type'
);
$connectionId = 'da9cb410-e29b-4c2d-ab9e-fe65bf83fcaf';
Yii::$app->opentok->signal($sessionId, $signalPayload, $connectionId);

// Send a signal to everyone in the session
$signalPayload = array(
    'data' => 'some signal message',
    'type' => 'signal type'
);
Yii::$app->opentok->signal($sessionId, $signalPayload);

有关更多信息，请参阅 OpenTok 信号开发指南。

示例

此存储库包含三个示例应用程序。为了尽快开始，请克隆整个存储库并遵循说明

• HelloWorld
• 存档
• SipCall

文档

参考文档可在 https://tokbox.com/developer/sdks/php/reference/index.html 查找。