OpenTok PHP SDK 技术文档

本文档将详细说明如何安装、使用以及操作 OpenTok PHP SDK，帮助用户更好地理解和应用该 SDK。

1. 安装指南

使用 Composer 安装（推荐）

Composer 是一个用于管理 PHP 项目依赖的工具。您可以在 Composer 官网 了解更多信息。

将此软件包 (opentok/opentok) 添加到您的 composer.json 文件中，或者在命令行中运行以下命令：

$ composer require opentok/opentok ^4.0

2. 项目使用说明

初始化

此软件包遵循 PSR-4 自动加载标准。如果您使用 Composer 安装，只需要要求生成的自动加载器：

require "<项目路径>/vendor/autoload.php";

一旦 SDK 的文件被加载，您可以使用自己的 API Key 和 API Secret 初始化一个 OpenTok\OpenTok 对象。

use OpenTok\OpenTok;

$opentok = new OpenTok($apiKey, $apiSecret);

初始化选项

OpenTok\OpenTok 对象允许在特殊需求出现时覆盖某些值，例如需要指向不同的数据中心或更改底层 HTTP 客户端的超时时间。对于这些情况，您可以作为第三个参数传递一个包含额外选项的数组。

我们允许以下选项：

• apiUrl - 更改 SDK 指向的域。在需要选择特定数据中心或指向 API 的模拟版本进行测试时很有用。
• client - 自定义 API 客户端，继承自 OpenTok\Utils\Client，用于自定义 HTTP 客户端。
• timeout - 更改默认的 HTTP 超时时间，默认为无限。您可以传递秒数来更改超时时间。

use OpenTok\OpenTok;
use MyCompany\CustomOpenTokClient;

$options = [
    'apiUrl' => 'https://custom.domain.com/',
    'client' => new CustomOpenTokClient(),
    'timeout' => 10,
];
$opentok = new OpenTok($apiKey, $apiSecret, $options);

创建会话

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

• 设置会话是否使用 OpenTok 媒体路由器或将流直接发送给客户端。
• 设置会话是否自动创建存档（隐含使用路由会话）。
• 指定位置提示。

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

use OpenTok\MediaMode;
use OpenTok\ArchiveMode;

// 创建一个尝试使用点对点流媒体的会话：
$session = $opentok->createSession();

// 使用 OpenTok 媒体路由器的会话，这是存档所必需的：
$session = $opentok->createSession(array('mediaMode' => MediaMode::ROUTED));

// 带有位置提示的会话：
$session = $opentok->createSession(array('location' => '12.34.56.78'));

// 自动存档的会话：
$sessionOptions = array(
    'archiveMode' => ArchiveMode::ALWAYS,
    'mediaMode' => MediaMode::ROUTED
);
$session = $opentok->createSession($sessionOptions);

// 将此会话 ID 存储在数据库中以备后用
$sessionId = $session->getSessionId();

生成令牌

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

use OpenTok\Session;
use OpenTok\Role;

// 仅从会话 ID 生成令牌（从数据库中获取）
$token = $opentok->generateToken($sessionId);
// 通过调用会话方法（从 createSession 返回）生成令牌
$token = $session->generateToken();

// 在令牌中设置一些选项
$token = $session->generateToken(array(
    'role' => Role::MODERATOR,
    'expireTime' => time() + (7 * 24 * 60 * 60), // 一周后
    'data' => 'name=Johnny',
    'initialLayoutClassList' => array('focus')
));

处理流

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

use OpenTok\Session;

// 仅从会话 ID 获取流信息（从数据库获取）
$stream = $opentok->getStream($sessionId, $streamId);

// 流属性
$stream->id; // 流 ID 的字符串
$stream->videoType; // 视频类型的字符串
$stream->name; // 名称的字符串
$stream->layoutClassList; // 布局类列表的数组

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

use OpenTok\Session;

// 仅从会话 ID 获取流列表（从数据库获取）
$streamList = $opentok->listStreams($sessionId);

$streamList->totalCount(); // 总数

处理存档

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

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

// 创建一个简单的会话存档
$archive = $opentok->startArchive($sessionId);

// 使用自定义选项创建存档
$archiveOptions = array(
    'name' => '重要演示',
    'hasAudio' => true,
    'hasVideo' => true,
    'outputMode' => OutputMode::COMPOSED,
    'resolution' => '1280x720'
);
$archive = $opentok->startArchive($sessionId, $archiveOptions);

// 将此存档 ID 存储在数据库中以备后用
$archiveId = $archive->id;

如果将 outputMode 选项设置为 OutputMode::INDIVIDUAL，则会使得存档中的每个流都被记录到其自己的单独文件中。请注意，当您将 outputMode 选项设置为 OutputMode::INDIVIDUAL 时，不能指定分辨率。OutputMode::COMPOSED 设置（默认值）会将存档中的所有流记录到单个（组合）文件中。

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

您可以通过调用 OpenTok\OpenTok 对象的 stopArchive($archiveId) 方法来停止已开始的存档记录。您也可以使用 OpenTok\Archive 实例的 stop() 方法来停止记录。

// 使用存档 ID（从数据库获取）停止存档
$opentok->stopArchive($archiveId);
// 使用存档实例（从 startArchive 返回）停止存档
$archive->stop();

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

// 获取存档实例（从存档 ID 获取）
$archive = $opentok->getArchive($archiveId);

// 存档属性
$archive->id; // 存档 ID 的字符串
$archive->name; // 存档名称的字符串
$archive->status; // 存档状态的字符串
$archive->duration; // 存档持续时间的秒数
$archive->size; // 存档大小的字节数
$archive->createdAt; // 创建时间的 UNIX 时间戳
$archive->startedAt; // 开始时间的 UNIX 时间戳
$archive->stoppedAt; // 停止时间的 UNIX 时间戳

3. 项目 API 使用文档

OpenTok PHP SDK 提供了以下方法的 API 文档：

• createSession($options)：创建一个新的 OpenTok 会话。
• generateToken($sessionId, $options)：为指定的会话生成一个新的令牌。
• getStream($sessionId, $streamId)：获取指定会话中指定流的详细信息。
• listStreams($sessionId)：获取指定会话中所有流的列表。
• startArchive($sessionId, $archiveOptions)：开始记录指定会话的存档。
• stopArchive($archiveId)：停止记录指定的存档。
• getArchive($archiveId)：获取指定存档的详细信息。

4. 项目安装方式

请参考本文档的“安装指南”部分，了解如何使用 Composer 安装 OpenTok PHP SDK。这是推荐和官方支持的安装方式。

通过以上内容，用户应能够熟练安装、使用和操作 OpenTok PHP SDK，以满足其应用程序的需求。