Web API 说明

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

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

对象总览

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

TiRtcInitOptions

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

字段	说明
appId	你的 AppId。建议传非空字符串。
endpoint	自定义服务入口。留空时使用 SDK 当前默认入口。

示例：

const options = TiRtcInitOptions({
  appId: 'your-app-id', // 必填：你的 AppId
  endpoint: '', // 自定义服务入口；一般保持空字符串
});

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()。
requestKeyFrame({ streamId }): void	向指定远端视频流请求关键帧。

TiRtcAudioOutput

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

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

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

示例：

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

TiRtcAudioInput

TiRtcAudioInput({ connection, streamId }) 创建一个语音输入对象，用来采集本地麦克风并发送给远端设备，常见用途是语音对讲。

参数	说明
connection	要绑定的 TiRtcConn；也可以在 attach() 时传入
streamId	本地音频发送流编号，取值范围同上；对讲示例默认使用 14

API	说明
setOptions({ sampleRate }): object	设置采集参数。sampleRate 表示麦克风采样率，默认 8000。建议在 start() 前调用。
attach({ connection, streamId }): Promise<number>	绑定连接和发送流编号。构造时如果已经传入 connection 和 streamId，这里可以直接无参调用。
start(): Promise<void>	打开麦克风并开始采集音频。建议在点击按钮等用户操作流里调用，以便浏览器能正常申请麦克风权限。
stop(): void	停止采集音频。
detach(): Promise<number>	解除当前发送绑定。

示例：

const audioInput = TiRtcAudioInput({
  connection,
  streamId: 14,
});

audioInput.setOptions({ sampleRate: 8000 });

await audioInput.start();
await audioInput.attach();

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。
• 没有在点击按钮等用户操作流里调用 TiRtcAudioInput.start()，导致浏览器拒绝麦克风权限。
• 业务结束后只调用 disconnect()，没有对音频和视频输出分别执行 detach()。

相关文档

• Web SDK 接入
• 建立与设备端的连接
• 音视频流传输与播放
• 语音对讲
• 名词解释