Web API 说明

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

如果你还没有完成前置接入，先看 Web SDK 接入和播放音视频。

本页会用到四个连接参数：AppId 标识当前客户端应用，remote_id 表示要连接的目标，token 是本次连接凭证，stream_id 是音视频流或消息流的编号。当前 Web 示例里，connect({ deviceId }) 里的 deviceId 在常见设备连接场景下，就对应目标设备的 remote_id / device_id；完整定义见名词解释。

Stream ID 约定

本页所有 streamId 参数按同一套规则使用：取值范围是 0..15，标识同一条连接、一个发送方向中的一路流。同一方向、同一路流在发送、Output / Input 绑定、订阅和接收配置中必须使用相同编号；同一发送方向内，不同音视频流使用不同编号，音频和视频不能共用编号。相反方向使用独立的编号空间，可以复用相同数值。

本文和配套 API Samples、DevTools CLI 使用 10 表示设备端音频、11 表示设备端视频、14 表示客户端对讲音频。这些只是便于直接联调的示例值，不是 SDK 保留或固定的编号。实际项目可以使用其他有效值，但要同步修改对应方向的发送端和接收端。

对象总览

对象	作用	结束方式
`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`

方法

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`	向指定远端视频流请求关键帧。
`sendStreamMessage({ streamId, timestampMs, data }): Promise<void>`	发送流消息；连接成功后调用。`streamId` 按约定使用 `0..15`，两端需要提前约定消息语义。

`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({ codec, sampleRate }): object`	设置音频编码和麦克风采样率。建议在 `start()` 前调用。
`attach({ connection, streamId }): Promise<number>`	绑定连接和发送流编号。构造时如果已经传入 `connection` 和 `streamId`，这里可以直接无参调用。
`start(): Promise<void>`	打开麦克风并开始采集音频。建议在点击按钮等用户操作流里调用，以便浏览器能正常申请麦克风权限。
`stop(): Promise<void>`	停止采集音频并释放麦克风；Promise 完成后表示麦克风已经关闭。
`detach(): Promise<number>`	解除当前发送绑定。

setOptions 参数：

参数	说明
`codec`	音频编码。支持 `g711a`（默认）、`opus`、`amr`。
`sampleRate`	麦克风采样率。支持 `8000`（默认）和 `16000`，其中 amr 仅支持 `8000`。

codec 与设备端 C SDK TIRTCMEDIA 的音频格式一一对应：g711a 对应 TIRTC_AUDIO_ALAW，opus 对应 TIRTC_AUDIO_OPUS，amr 对应 TIRTC_AUDIO_AMR。客户端和设备端必须选择相同的格式。Web Audio Input 的 amr 仅支持 8 kHz、单声道的 AMR-NB。

示例：

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

audioInput.setOptions({ codec: 'g711a', sampleRate: 8000 });

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

`TiRtcVideoOutput`

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

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

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

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

html

<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 API 说明 ​

Stream ID 约定 ​

对象总览 ​

TiRtcInitOptions ​

TiRtc ​

TiRtcConn ​

方法 ​

TiRtcAudioOutput ​

TiRtcAudioInput ​

TiRtcVideoOutput ​

常见误用 ​

相关文档 ​