Web API 参考

本页介绍 TiRTC Web SDK 的 API，帮助你在网页中接入并播放设备的实时音视频。

如果你还没有完成前置接入，先看 集成到客户端 和 播放音视频。页面里提到的 AppId、remote_id、token、stream_id 等术语，以 名词解释 为准。当前 Web 示例里，connect({ deviceId }) 里的 deviceId 在常见设备连接场景下，就对应目标设备的 remote_id / device_id。

对象总览

对象	作用	结束方式
TiRtcInitOptions	组织 SDK 初始化参数	无需显式清理
TiRtc	初始化 SDK，等待视频播放依赖准备完成	无显式关闭 API
TiRtcConn	连接设备、断开连接、手动订阅媒体流	disconnect()
TiRtcAudioOutput	播放一条远端音频流	detach()
TiRtcVideoOutput	播放一条远端视频流	detach()

TiRtcInitOptions

TiRtc.initialize(...) 的参数对象。

字段	说明
appId	你的 AppId。建议传非空字符串。

示例：

const options = TiRtcInitOptions({
  appId: 'your-app-id',
});

TiRtc

TiRtc 管理 Web SDK 的初始化和视频播放前置准备。典型调用顺序是：initialize() -> videoOutputReady() -> 创建连接和播放对象 -> 业务结束后断开连接并 detach()。

API	说明
initialize(options): void	初始化 SDK 运行环境。调用后才能继续使用连接对象和播放对象。
videoOutputReady(): Promise<void>	等待视频解码和渲染依赖准备完成。建议在创建视频播放链路前先 await 它。

示例：

TiRtc.initialize(TiRtcInitOptions({ appId: 'your-app-id' }));
await TiRtc.videoOutputReady();

TiRtcConn

本节所有 streamId 参数按 stream_id 的公开约定使用 0..15。当前公开示例默认使用音频 10、视频 11。

方法

API	说明
TiRtcConn()	创建一个连接对象。它本身不会自动发起建连。
connect({ deviceId, token }): Promise<void>	发起到目标设备的连接。deviceId 是目标设备 ID；常见场景下，它就是 remote_id。连接成功时 Promise resolve，失败时 Promise reject。
disconnect(): void	断开当前连接，但不会自动 detach() 已创建的音频或视频输出对象。
subscribeAudio({ streamId }): void	请求远端开始发送指定 streamId 的音频流。它不会自动创建本地播放。
unsubscribeAudio({ streamId }): void	取消指定 streamId 的音频订阅。它不等于 TiRtcAudioOutput.detach()。
subscribeVideo({ streamId }): void	请求远端开始发送指定 streamId 的视频流。它不会自动创建本地播放。
unsubscribeVideo({ streamId }): void	取消指定 streamId 的视频订阅。它不等于 TiRtcVideoOutput.detach()。

TiRtcAudioOutput

TiRtcAudioOutput({ connection, streamId }) 创建一个音频输出对象。

参数	说明
connection	要绑定的 TiRtcConn
streamId	目标音频流编号，取值范围同上

API	说明
attach(): void	开始接收并播放当前绑定的远端音频流。它只决定本地播放哪一路音频；如果远端按订阅后才发流，还要配合 connection.subscribeAudio()。
detach(): void	解除当前音频播放绑定。对象本身仍可继续复用。

示例：

const audioOutput = TiRtcAudioOutput({
  connection,
  streamId: 10,
});

TiRtcVideoOutput

TiRtcVideoOutput({ connection, streamId }) 创建一个视频输出对象。

参数	说明
connection	要绑定的 TiRtcConn
streamId	目标视频流编号，取值范围同上

API	说明
attach(): void	开始接收并渲染当前绑定的远端视频流。它只决定本地播放哪一路视频；如果远端按订阅后才发流，还要配合 connection.subscribeVideo()。
detach(): void	解除当前视频播放绑定。对象本身仍可继续复用。

当前版本没有单独的 view() 或容器绑定 API。页面里需要先准备一个固定的 canvas 节点：

<canvas id="canvas"></canvas>

示例：

const videoOutput = TiRtcVideoOutput({
  connection,
  streamId: 11,
});

常见误用

• 没有先调用 TiRtc.initialize(...)，就直接创建 TiRtcConn 或播放对象。
• 没有先等待 TiRtc.videoOutputReady()，导致视频依赖还没准备好。
• 页面里没有准备固定 id="canvas" 的 canvas 节点。
• 还没连上设备就执行 attach() 或 subscribe*()。
• 只做了 attach()，没有按约定配合 subscribeAudio() / subscribeVideo()，结果一直无声或黑屏。
• 把 attach() 当成向远端发起订阅；实际上它只负责本地播放绑定。
• 音频和视频使用了和设备侧约定不一致的 streamId。
• 业务结束后只调用 disconnect()，没有对音频和视频输出分别执行 detach()。

相关文档

• 集成到客户端
• 连接设备端
• 播放音视频
• 名词解释