4.1.0

Docs/cn/basic_call.md

@@ -80,9 +80,9 @@ const uid = await rtc.client.join(options.appId, options.channel, options.token,
 调用 `join` 方法时你需要注意以下参数：
 - `appid`: 你的 App ID。详见[前提条件](setup.md#前提条件)。
 - `channel`: 频道名，长度在 64 字节以内的字符串。在我们的示例项目中，`channel` 的值设为 `demo_channel_name`。
-- `token`: （可选）如果你的 Agora 项目开启了 App 证书，你需要在该参数中传入一个 Token，详见[使用 Token](https://docs.agora.io/cn/Agora%20Platform/token?platform=All%20Platforms#%E4%BD%BF%E7%94%A8-token)。
-  - 在测试环境，我们推荐使用控制台生成临时 Token，详见 [获取临时 Token](https://docs.agora.io/cn/Agora%20Platform/token?platform=All%20Platforms%23get-a-temporary-token#%E8%8E%B7%E5%8F%96%E4%B8%B4%E6%97%B6-token)。
-  - 在生产环境，我们推荐你在自己的服务端生成 Token，详见 [生成 Token](https://docs.agora.io/cn/Interactive%20Broadcast/token_server)。
+- `token`: （可选）如果你的 Agora 项目开启了 App 证书，你需要在该参数中传入一个 Token，详见[使用 Token](https://docs.agora.io/cn/Agora%20Platform/token#Token)。
+  - 在测试环境，我们推荐使用控制台生成临时 Token，详见[获取临时 Token](https://docs.agora.io/cn/Agora%20Platform/token?platform=All%20Platforms#get-a-temporary-token)。
+  - 在生产环境，我们推荐你在自己的服务端生成 Token，详见[生成 Token](https://docs.agora.io/cn/Interactive%20Broadcast/token_server_cpp)。
 > 在我们的示例项目中，为了叙述方便，没有开启 App 证书，所以不需要校验 Token，`token` 的值为 `null`。如果你启用了 App 证书，请确保上面传入的 `channel` 值和生成 Token 时传入的 `channel` 值保持一致。
 - `uid`：用户 ID，频道内每个用户的 UID 必须是唯一的。你可以填 `null`，Agora 会自动分配一个 UID 并在 `join` 的结果中返回。
 
@@ -121,7 +121,7 @@ console.log("publish success!");
 ```js
 rtc.client.on("user-published", async (user, mediaType) => {
   // 开始订阅远端用户。
-  await rtc.client.subscribe(user);
+  await rtc.client.subscribe(user, mediaType);
   console.log("subscribe success");
 
   // 表示本次订阅的是视频。

Docs/cn/inject_stream.md

@@ -15,7 +15,7 @@ sidebar_label: 输入在线媒体流
 
 ### 工作原理
 
-![](https://web-cdn.agora.io/docs-files/1576059223619)
+![](assets/inject-online-media-stream.png)
 
 直播频道中的主播通过 Video Inject 服务器将在线媒体流拉到 Agora SD-RTN™ 中，输入到直播频道内。
 

Docs/cn/join_and_leave.md

@@ -7,45 +7,56 @@ sidebar_label: 加入/离开频道
 在 Agora Web SDK NG 中，我们使用 [AgoraRTCClient](/api/cn/interfaces/iagorartcclient.html) 对象来管理一个本地用户在目标频道内的行为。所以在加入目标频道之前，让我们先创建一个 `AgoraRTCClient` 对象。
 
 ## 创建 AgoraRTCClient 对象
-创建 `AgoraRTCClient` 对象非常简单，直接调用 [AgoraRTC.createClient](/api/cn/interfaces/iagorartc.html#createclient) 即可。在创建 `AgoraRTCClient` 时，我们需要指定使用的编码格式以及频道场景：
+
+创建 `AgoraRTCClient` 对象非常简单，直接调用 [AgoraRTC.createClient](/api/cn/interfaces/iagorartc.html#createclient) 即可。在创建 `AgoraRTCClient` 时，我们需要指定使用的编码格式（`codec`）以及频道场景（`mode`）。
 
 ```js
 const client = AgoraRTC.createClient({
   codec: "vp8",
   mode: "live",
-
 });
 ```
 
-### 选择合适的编码格式
-Agora Web SDK NG 支持两种编码格式 `"vp8"` 和 `"h264"`，不同的浏览器和不同的设备对这两种格式的编解码支持都不同。建议您根据实际需求并结合实际的设备/浏览器选择合适的编码格式。
+### 选择视频编码格式
+
+Agora Web SDK NG 支持两种视频编码格式 `"vp8"`（VP8）和 `"h264"`（H.264），不同的浏览器和不同的设备对这两种编解码格式支持都不同。我们建议根据实际需求并结合实际的设备及浏览器选择合适的编码格式。
+
+> 对于纯音频通话，`"vp8"` 和 `"h264"` 任选其一设置即可。
 
-该配置只会影响发布端的编码格式，对于订阅端来说只要其支持该格式的解码，都能正常完成解码。比如 Desktop Chrome 57 以上即支持 VP8 也支持 H.264，如果频道中有两个主播分别发布了 VP8 和 H.264 的视频，使用 Desktop Chrome 57 的观众都可以完成订阅和解码，但是 Safari 12.1 以下的设备不支持 VP8 的编解码，那么使用 Safari 12.1 以下版本浏览器的观众就无法解码 VP8 那一路的流。
+`codec` 设置只会影响发布端的视频编码格式，对于订阅端来说只要其支持该格式的解码，都能正常完成订阅。比如桌面端 Chrome 58 及以上版本既支持 VP8 也支持 H.264，如果频道中有两个主播分别发布了 VP8 和 H.264 的视频，使用桌面端 Chrome 57 的观众可以订阅和解码这两个主播的视频，但是 Safari 12.1 以下版本不支持 VP8 编解码，使用 Safari 12.1 以下版本浏览器的观众就无法解码 VP8 的视频流。
 
-下面列出不同浏览器和平台所支持的编解码格式作为参考：
+下表列出不同浏览器和平台所支持的编解码格式作为参考：
 
-|Browser|VP8|H.264|
+|浏览器|VP8|H.264|
 |---|---|---|
-|Desktop Chrome 58+|✔|✔|
+|桌面端 Chrome 58+|✔|✔|
 |Firefox 56+|✔|✔*|
 |Safari 12.1+|✔|✔|
 |Safari < 12.1|✘|✔|
 |Android Chrome 58+|✔|?*|
 
-> - Firefox 的 H.264 依赖 `OpenH264 Video Codec provided by Cisco Systems, Inc.` 插件，这个插件会在 Firefox 安装成功后自动在后台下载并默认启用，但是如果此时插件没有下载完成，Firefox 的 H.264 将不可用。
-> - Chrome 会在 Android 设备上对 H.264 强制使用硬件编解码。此时就算 Chrome 声称支持 H.264，如果 Android 设备的芯片没有 H.264 的硬件编解码支持，H.264 实际上也是不可用的。
+> - Firefox 的 H.264 依赖 **OpenH264 Video Codec provided by Cisco Systems, Inc.** 插件。Firefox 安装成功后会自动在后台下载该插件并默认启用，但是如果通话时插件没有下载完成，Firefox 的 H.264 将不可用。
+> - Android 设备上 Chrome 对 H.264 的支持取决于设备。因为 Chrome 在 Android 设备上对 H.264 强制使用硬件编解码，即使 Chrome 支持 H.264，如果 Android 设备的芯片不支持 H.264 的硬件编解码，H.264 实际上也是不可用的。
+
+### 选择频道场景
+
+频道场景是 Agora 为了对不同的实时音视频场景进行针对性算法优化而提供的一种设置选项。Agora Web SDK NG 支持两种频道场景：`"rtc"`(通信场景) 和 `"live"`(直播场景)。
+
+**通信场景**
 
-### 选择合适的频道场景
-Agora RTC SDK NG 支持两种频道场景 `"rtc"`(通信场景) 和 `"live"`(直播场景)。
+通信场景适合多人会议、在线聊天等场景。这种场景的特征是，频道内的所有用户往往需要互相交流，但是用户的总数不会太多。
 
-通信场景适合多人会议，在线聊天等场景。这种场景的特征是频道内的所有用户往往需要互相交流但是频道内用户的总数不会太多。在这种场景下，发布端除了第一帧以外不会主动编码关键帧，只有当有人需要订阅时，会发起一个关键帧请求，此时发布端才会编码一个关键帧。这样的好处是可以加快首帧出图的时间，同时减少编码不必要的关键帧来降低对带宽的占用。但是如果订阅端的人数很多而且订阅操作很频繁，短时间内大量的关键帧请求会给发布端带来很大压力，此时我们推荐使用直播场景。
+在通信场景下，发布端除了第一帧以外不会主动编码关键帧，只有当有人需要订阅时，SDK 会发起一个关键帧请求，此时发布端会编码一个关键帧。这样做的好处是可以保证订阅端接收的首帧为关键帧，加快首帧出图，同时减少编码不必要的关键帧来降低对带宽的占用。但是如果订阅的人数很多而且订阅操作很频繁，短时间内大量的关键帧请求会给发布端带来很大压力，此时我们推荐使用直播场景。
 
-直播场景适合发布端很少但是订阅端很多的场景，这种场景下我们定义了两种用户角色：观众和主播。主播能够发送和接收音视频，观众不能发送，只能接收音视频。你可以通过修改 `createClient` 的 [role](/api/cn/interfaces/clientconfig.html#role) 参数来指定用户角色，也可以调用 [setClientRole](/api/cn/interfaces/iagorartcclient.html#setclientrole) 来动态修改。在直播场景下，主播会固定每隔 1 秒编码一个关键帧，不会依赖关键帧请求。
+**直播场景**
+
+直播场景适合发布端很少但是订阅端很多的场景，这种场景下我们定义了两种用户角色：观众和主播。主播能够发送和接收音视频，观众不能发送、只能接收音视频。你可以通过设置 `createClient` 的 [role](/api/cn/interfaces/clientconfig.html#role) 参数来指定用户角色，也可以调用 [setClientRole](/api/cn/interfaces/iagorartcclient.html#setclientrole) 来动态修改用户角色。在直播场景下，主播固定每隔一秒编码一个关键帧，不依赖关键帧请求。
 
 ## 加入频道
-创建好 `AgoraRTCClient` 对象后，接下来就可以加入频道了，直接调用 [AgoraRTCClient.join](/api/cn/interfaces/iagorartcclient.html#join) 即可加入频道。
 
-> `join` 方法详细参数说明请参阅 API 文档。注意该方法为异步方法，使用时需要配合 Promise 或者 async/await。
+创建 `AgoraRTCClient` 对象后，接下来就可以调用 [AgoraRTCClient.join](/api/cn/interfaces/iagorartcclient.html#join) 加入频道。
+
+> `join` 方法详细参数说明请参考 API 文档。注意该方法为异步方法，使用时需要配合 Promise 或者 async/await。
 
 ```js
 // 自动分配数字 UID
@@ -54,46 +65,50 @@ const uid = await client.join("APPID", "CHANNEL", "TOKEN");
 // 指定数字 UID
 await client.join("APPID", "CHANNEL", "TOKEN", 393939);
 
-// 指定 String UID
+// 指定字符串 UID
 await client.join("APPID", "CHANNEL", "TOKEN", "my_user_id");
 ```
 
-这里需要注意 `join` 方法的第四个参数，当不传入任何值时，Agora 将会为这个加入的本地用户自动分配一个数字 UID 作为其唯一的身份标识。你也可以自己传入相应的 UID 参数来实现指定 UID，UID 目前支持数字和 String 两种类型，在使用指定 UID 功能时请注意以下事项：
+这里需要注意 `join` 方法的第四个参数，当不传入任何值时，Agora 会为这个加入的本地用户自动分配一个数字类型的用户 ID 作为其唯一的身份标识。你也可以通过 `uid` 参数自行指定用户 ID。用户 ID 支持数字和字符串两种类型，在指定用户 ID 时请注意以下事项：
 
-- 指定 UID 时，一个频道内的 UID 类型必须是一致的，也就是不能出现数字 UID 和 String UID 混用的情况
-- 指定 UID 时，如果频道内有其他用户也在使用这个 UID，那么正在使用这个 UID 用户会被 Agora 网关立刻踢出，新用户将会使用 UID 成功加入。（用户因为 UID 重复被踢出时会触发 `connection-state-change` 回调，详细见下文的连接状态介绍）
-- 使用 String UID 时，实际上是在 Agora 内部服务里注册了一个 String UID 到数字 UID 的映射关系，所以使用 String UID 会增加加入房间的流程，会在一定程度上影响加入频道的时间
+- 一个频道内所有用户的用户 ID 类型必须是一致的，也就是不能出现数字用户 ID 和字符串用户 ID 混用的情况。
+- 如果频道内已经有其他用户在使用指定的用户 ID，那么正在使用这个 ID 的用户会被 Agora 服务器立刻踢出频道，新用户将会使用此用户 ID 成功加入。用户因为用户 ID 冲突被踢出频道时会触发 `connection-state-change` 回调，详见[频道内的连接状态](#connection)。
+- 使用字符串用户 ID 时，实际上是在 Agora 服务里注册了一个字符串用户 ID 到数字用户 ID 的映射关系，所以使用字符串用户 ID 会在一定程度上影响加入频道的时间。
 
 ## 离开频道
-通过调用 [AgoraRTCClient.leave](/api/cn/interfaces/iagorartcclient.html#leave) 可以离开当前频道。该方法在任何时候调用，即使当前正在加入频道或者正在重连。当调用离开频道后，SDK 会立刻销毁所有频道内的连接对象并重置整个频道。如果需要再次加入频道，先调用 `leave` 后再调用 `join` 即可。
 
-> 注意该方法为异步方法，使用时需要配合 Promise 或者 async/await。
+调用 [AgoraRTCClient.leave](/api/cn/interfaces/iagorartcclient.html#leave) 可以离开当前频道。该方法可以在任何时候调用，即使当前正在加入频道或者正在重连。调用 `leave` 后，SDK 会立刻销毁与当前频道相关的对象，包括订阅的远端用户对象、远端轨道对象、记录连接状态的对象等。如果需要再次加入频道，调用 `leave` 后再调用 `join` 即可。
+
+> 注意 `leave` 为异步方法，使用时需要配合 Promise 或者 async/await。
 
 ```js
 await client.leave();
 ```
 
-## 频道内的连接状态
-当一个用户加入目标频道后，因为网络波动可能会导致和 Agora 服务的连接断开，此时 SDK 会自动重新尝试加入频道。下面介绍所有的连接状态：
+## <a name="connection"></a>频道内的连接状态
 
-- "DISCONNECTED": 连接断开。当出于这个状态时，SDK 不会尝试重连。该状态表示用户处于以下任一阶段：
-  - 尚未通过 join 加入频道。
-  - 已经通过 leave 离开频道。
-  - 被 Agora 服务踢出频道或者连接失败等异常情况。
-- "CONNECTING": 正在连接中。当调用 join 时为此状态。
-- "CONNECTED": 已连接。该状态表示用户已经加入频道，可以在频道内发布或订阅媒体流。
-- "RECONNECTING": 连接断开，但是正在尝试重连中。因网络断开或切换而导致 SDK 与服务器的连接中断，SDK 会自动重连，此时连接状态变为 "RECONNECTING"。
-- "DISCONNECTING": 正在断开连接。在调用 leave 的时候为此状态。
+当一个用户加入目标频道后，网络波动可能会导致和 Agora 服务的连接断开，此时 SDK 会自动重新尝试加入频道。
 
-你可以通过 [AgoraRTCClient.connectionState](/api/cn/interfaces/iagorartcclient.html#connectionstate) 或者 [AgoraRTCClient.on("connection-state-change")](/api/cn/interfaces/iagorartcclient.html#event_connection_state_change) 获取当前最新的状态变化。
+你可以通过 [AgoraRTCClient.connectionState](/api/cn/interfaces/iagorartcclient.html#connectionstate) 或者 [AgoraRTCClient.on("connection-state-change")](/api/cn/interfaces/iagorartcclient.html#event_connection_state_change) 获取当前的连接状态。
+
+下面列出所有的连接状态：
+
+- `"DISCONNECTED"`: 连接断开。处于这个状态时，SDK 不会自动重连。该状态表示用户处于以下任一阶段：
+  - 尚未通过 `join` 加入频道。
+  - 已经通过 `leave` 离开频道。
+  - 被 Agora 服务器踢出频道或者连接失败等异常情况。
+- `"CONNECTING"`: 正在连接。调用 `join` 时为此状态。
+- `"CONNECTED"`: 已连接。该状态表示用户已经加入频道，可以在频道内发布或订阅媒体轨道。
+- `"RECONNECTING"`: 连接断开，正在尝试重连。因网络断开或切换导致 SDK 与服务器的连接中断，SDK 会自动重连，进入此状态。
+- `"DISCONNECTING"`: 正在断开连接。在调用 `leave` 的时候为此状态。
 
 ## 错误处理
+
 在加入频道的过程中，因为 SDK 使用不当或者网络异常等原因，可能会抛出以下错误：
 
-- INVALID_PARAMS: 提供的参数错误，比如提供了格式非法的 Token
-- INVALID_OPERATION: 非法操作，通常由于重复加入频道引起的，请确保重复加入时先调用 `leave`
-- OPERATION_ABORT: 加入中止，说明在 `join` 方法成功之前就调用了 `leave` 方法
-- UNEXPECTED_RESPONSE: Agora 后台返回了非预期的响应，通常是因为 APPID 或 Token 鉴权失败
-- INVALID_UINT_UID_FROM_STRING_UID：通过 String UID 映射数字 UID 失败
-- UID_CONFLICT：创建了多个 `AgoraRTCClient` 对象，其中重复使用了同一个 UID
-- WS_ABORT: 和 Agora 网关建立 WebSocket 连接失败
+- INVALID_PARAMS: 提供的参数错误，比如提供了格式非法的 Token。
+- INVALID_OPERATION: 非法操作。该错误通常是重复加入频道引起的，请确保重复加入时先调用 `leave`。
+- OPERATION_ABORT: 加入被中止，表示在 `join` 方法成功之前就调用了 `leave` 方法。
+- UNEXPECTED_RESPONSE: Agora 服务器返回了非预期的响应，通常是因为 App ID 或 Token 鉴权失败，例如开启了 App 证书却未传入 Token。
+- INVALID_UINT_UID_FROM_STRING_UID: 通过字符串用户 ID 映射数字用户 ID 失败，请联系 Agora [技术支持](https://agora-ticket.agora.io/)。
+- UID_CONFLICT: 创建了多个 `AgoraRTCClient` 对象，且重复使用了同一个用户 ID。