声网 Web SDK 使用 AgoraRTCClient 对象来管理一个本地用户在目标频道内的行为。在加入目标频道之前,你需要先创建一个 AgoraRTCClient
对象。
调用 AgoraRTC.createClient 即可创建 AgoraRTCClient
对象。在创建 AgoraRTCClient
时,你需要指定使用的编码格式(codec
)以及频道场景(mode
)。
const client = AgoraRTC.createClient({
codec: "vp8",
mode: "rtc",
});
codec
设置支持 "vp8"
(VP8)和 "h264"
(H.264)两种视频编码格式。该设置只会影响发布端的视频编码格式,对于订阅端来说只要其支持该格式的解码,都能正常完成订阅。
举例来说,桌面端 Chrome 58 及以上版本既支持 VP8 也支持 H.264,而 Safari 12.1 以下版本不支持 VP8 编解码;如果频道中有两个主播分别发布了 VP8 和 H.264 的视频流,使用桌面端 Chrome 58 的观众可以解码这两个主播的视频,使用 Safari 12.1 以下版本浏览器的观众只能解码 H.264 的视频流。
不同浏览器和不同设备对这两种编解码格式支持都不同。下表列出不同浏览器所支持的编解码格式作为参考:
浏览器 | VP8 | H.264 |
---|---|---|
桌面端 Chrome 58+ | ✔ | ✔ |
Firefox 56+ | ✔ | ✔* |
Safari 12.1+ | ✔ | ✔ |
Safari < 12.1 | ✘ | ✔ |
Android Chrome 58+ | ✔ | ?* |
频道场景(mode
)是声网为了对不同的实时音视频场景进行针对性算法优化而提供的一种设置选项。SDK 支持两种频道场景:"rtc"
(通信场景) 和 "live"
(直播场景)。
通信场景
"rtc"
(通信场景)适用于频道内所有用户需要相互交流且用户总数不太多的场景,如多人会议和在线聊天。
直播场景
"live"
(直播场景)适用于发布端很少但是订阅端很多的场景,这种场景下 SDK 定义了两种用户角色:观众(默认)和主播。主播能够发送和接收音视频,观众不能发送、只能接收音视频。你可以通过设置 createClient
的 role 参数来指定用户角色,也可以调用 setClientRole 来动态修改用户角色。
创建 AgoraRTCClient
对象后,就可以调用 AgoraRTCClient.join 加入频道。
Promise
或 async/await
。注意 join
方法的第四个参数 uid
的设置。不传入任何值时,声网会为这个加入的本地用户自动分配一个 Number 型的用户 ID 作为其唯一的身份标识。你也可以通过该参数自行指定一个 Number 型的用户 ID。
// 自动分配数字 UID
const uid = await client.join("APPID", "CHANNEL", "TOKEN");
// 指定数字 UID
await client.join("APPID", "CHANNEL", "TOKEN", 393939);
调用 AgoraRTCClient.leave 可以离开当前频道。该方法可以在任何时候调用,包括正在加入频道时或者正在重连时。
Promise
或 async/await
。调用 leave
后,SDK 会立刻销毁与当前频道相关的对象,包括订阅的远端用户对象、远端轨道对象、记录连接状态的对象等。如果需要再次加入频道,在调用 leave
后再调用 join
即可。
await client.leave();
详见频道连接状态管理。
在加入频道的过程中,因为 SDK 使用不当或者网络异常等原因,可能会抛出以下错误:
INVALID_PARAMS
: 提供的参数错误,比如提供了格式非法的 Token。INVALID_OPERATION
: 非法操作。该错误通常是重复加入频道引起的,请确保重复加入时先调用 leave
。OPERATION_ABORTED
: 加入被中止,表示在 join
方法成功之前就调用了 leave
方法。UNEXPECTED_RESPONSE
:声网服务器返回了非预期的响应,通常是因为 App ID 或 Token 鉴权失败,例如开启了 App 证书却未传入 Token。UID_CONFLICT
: 创建了多个 AgoraRTCClient
对象,且重复使用了同一个用户 ID。