AgoraRtcChannel
提供在 AgoraRtcChannel 频道中实现实时音视频功能的方法。
addInjectStreamUrl
输入在线媒体流。
addInjectStreamUrl(url: string, config: InjectStreamConfig): number
- 请确保已开通旁路推流的功能,详见推流到 CDN 中的前提条件。
- 在直播场景中,只有角色为主播的用户才能调用该方法。
- 频道内同一时间只允许输入一个在线媒体流。
- 该方法需要在加入频道后调用。
该方法将正在播放的音视频作为音视频源导入到正在进行的直播中。可主要应用于赛事直播、多人看视频互动等直播场景。调用该方法后,SDK 会在本地触发 STREAM_INJECT_STATUS 回调,报告输入在线媒体流的状态;成功输入媒体流后,该音视频流会出现在频道中,频道内所有用户都会收到 USER_JOINED 回调,其中 uid 为 666。
参数
- url
-
添加到直播中的视频流 URL 地址。支持 RTMP、HLS、HTTP-FLV 协议传输。
- 支持的音频编码格式:AAC;
- 支持的视频编码格式:H.264(AVC)。
- config
- 所添加的视频流属性定义,详见: InjectStreamConfig 。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
ERR_INVALID_ARGUMENT
(2): 输入的 URL 为空。请重新调用该方法,并确认输入的媒体流的 URL 有效。ERR_NOT_READY
(3): 用户没有加入频道。ERR_NOT_SUPPORTED
(4): 频道非直播场景。请调用 setChannelProfile 并将频道设置为直播场景再调用该方法。ERR_NOT_INITIALIZED
(7): 引擎没有初始化。请确认调用该方法前已创建 AgoraRtcEngine 对象并完成初始化。
addPublishStreamUrl
增加旁路推流地址。
addPublishStreamUrl(url: string, transcodingEnabled: boolean): number
调用该方法后,你可以向 CDN 推送 RTMP 或 RTMPS 协议的媒体流。SDK 会在本地触发 RTMP_STREAMING_STATE_CHANGED 回调,报告增加旁路推流地址的状态。
- 该方法需要在加入频道后调用。
- 请确保已开通旁路推流的功能,详见进阶功能推流到 CDN 中的前提条件。
- 只有直播场景中角色为主播的用户才能调用该方法。
- 该方法每次只能增加一路旁路推流地址。若需推送多路流,则需多次调用该方法。
- Agora 目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。
参数
- url
- CDN 推流地址,格式为 RTMP 或 RTMPS。该字符长度不能超过 1024 字节。url 不支持中文字符等特殊字符。
- transcodingEnabled
- 是否转码。转码是指在旁路推流时对音视频流进行转码处理后再推送到其他 CDN 服务器。多适用于频道内有多个主播,需要进行混流、合图的场景。
true
: 转码。false
: 不转码。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
ERR_INVALID_ARGUMENT
(2): 参数无效,一般是 URL 为空或是长度为 0 的字符串。ERR_NOT_INITIALIZED
(7): 推流时未初始化引擎。
adjustUserPlaybackSignalVolume
调节本地播放的指定远端用户信号音量。
adjustUserPlaybackSignalVolume(userId: number, volume: number): number
- 自从
- v3.0.0
你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量,则需多次调用该方法。
- 该方法需要在加入频道后调用。
- 该方法调节的是本地播放的指定远端用户混音后的音量。
参数
- userId
- 远端用户 ID。
- volume
-
播放音量。取值范围为 [0,100]。默认值为 100,表示原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
channelId
获取当前频道的频道名。
channelId(): string
返回值
- 方法调用成功,返回当前频道的频道名。
- 方法调用失败,返回空字符串
""
。
createDataStream
创建数据流。
createDataStream(reliable: boolean, ordered: boolean): number
- 弃用:
- 该方法从 v3.3.0 起废弃。请改用 createDataStreamWithConfig。
在 AgoraRtcEngine 生命周期内,每个用户最多只能创建 5 个数据流。
- 该方法需要在加入频道后调用。
- 不可将 reliable 设为
true
且将 ordered 设为true
。
参数
- reliable
-
该数据流是否可靠:
true
: 接收方 5 秒内会收到发送方所发送的数据,否则会收到 STREAM_MESSAGE_ERROR 回调并获得相应报错信息。false
: 接收方不保证收到,就算数据丢失也不会报错。
- ordered
- 该数据流是否有序:
true
: 接收方会按照发送方发送的顺序收到数据包。true
: 接收方不保证按照发送方发送的顺序收到数据包。
返回值
- 成功创建的数据流 ID:方法调用成功。
- < 0: 创建数据流失败。你可以参考错误码和警告码进行问题排查。
createDataStreamWithConfig
创建数据流。
createDataStreamWithConfig(config: DataStreamConfig): number
- 自从
- v3.3.0。用于取代 createDataStream。
该方法用于创建数据流。每个用户在每个频道中最多只能创建 5 个数据流。
相比 createDataStream,该方法不支持数据可靠。接收方会丢弃超出发送时间 5 秒后的数据包。
参数
- config
- 数据流设置。详见 DataStreamConfig。
返回值
- 创建的数据流的 ID:方法调用成功。
- < 0:方法调用失败。你可以参考错误码和警告码进行问题排查。
enableEncryption
开启或关闭内置加密。
enableEncryption(enabled: boolean, config: EncryptionConfig): number
- 自从
- v3.1.0
在安全要求较高的场景下,Agora 建议你在加入频道前,调用本方法开启内置加密。
同一频道内所有用户必须使用相同的加密模式和密钥。用户离开频道后,SDK 会自动关闭加密。如需重新开启加密,你需要在用户再次加入频道前调用该方法。
参数
- enabled
-
是否开启内置加密:
- true: 开启内置加密。
- false: 关闭内置加密。
- config
- 配置内置加密模式和密钥。详见 EncryptionConfig。
返回值
- 0: 方法调用成功
-
< 0: 方法调用失败
- -2(ERR_INVALID_ARGUMENT): 调用了无效的参数。需重新指定参数。
- -4(ERR_NOT_SUPPORTED): 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。需在调用 API 之前已创建 AgoraRtcEngine 对象并完成初始化。
getCallId
getConnectionState
获取当前网络连接状态。
getConnectionState(): CONNECTION_STATE_TYPE
- 自从
- v2.3.2
该方法在加入频道前后都能调用。
返回值
当前网络连接的状态。详见 CONNECTION_STATE_TYPE。
joinChannel
通过 UID 加入频道。
joinChannel(token: string, info: string, uid: number, options?: ChannelMediaOptions ): number
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute
方法实现。
- 该方法不支持相同的用户重复加入同一个频道。
- 我们建议不同频道中使用不同的 UID。
- 如果想要从不同的设备同时接入同一个频道,请确保每个设备上使用的 UID 是不同的。
参数
- token
-
在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
警告: 请确保用于生成 token 的 App ID、频道名和用户名和 initializeWithContext 方法初始化引擎时用的 App ID,以及该方法中设置的频道名和用户名是一致的。 - info
-
预留参数。
- uid
- 用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID,并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数,建议设置范围:1 到 21 到 232-1如果不指定(即设为 0),SDK 会自动分配一个,并在 JOIN_CHANNEL_SUCCESS 回调中返回,App 层必须记住该返回值并维护,SDK 不对该返回值进行维护。
- options
- 频道媒体设置选项。详见 ChannelMediaOptions。
返回值
- 0(ERR_OK) 方法调用成功。
- < 0 方法调用失败。
- -2(ERR_INVALID_ARGUMENT): 参数无效。
- -3(ERR_NOT_READY): SDK 初始化失败,请尝试重新初始化 SDK。
- -5(ERR_REFUSED): 调用被拒绝。可能有如下两个原因:
- 已经创建了一个同名的 AgoraRtcChannel 频道。
- 已经通过 AgoraRtcChannel 加入了一个频道,并在该 AgoraRtcChannel 频道中发布了音视频流。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化,就调用该方法。请确认在调用 API 之前已经创建 AgoraRtcEngine 对象并完成初始化。
joinChannelWithUserAccount
通过 User Account 加入频道。
joinChannelWithUserAccount(token: string, userAccount: string, options: ChannelMediaOptions ): number
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute
方法实现。
- 该方法不支持相同的用户重复加入同一个频道。
- 我们建议不同频道中使用不同的 user account。
- 如果想要从不同的设备同时接入同一个频道,请确保每个设备上使用的 user account 是不同的。
参数
- token
-
在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
警告: 请确保用于生成 token 的 App ID、频道名和用户名和 initializeWithContext 方法初始化引擎时用的 App ID,以及该方法中设置的频道名和用户名是一致的。 - userAccount
- 用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account,并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填,最大不超过 255 字节,不可填 null。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- options
- 频道媒体设置选项。详见 ChannelMediaOptions。
返回值
- 0(ERR_OK) 方法调用成功。
- < 0 方法调用失败。
- -2(ERR_INVALID_ARGUMENT): 参数无效。
- -3(ERR_NOT_READY): SDK 初始化失败,请尝试重新初始化 SDK。
- -5(ERR_REFUSED): 调用被拒绝。可能有如下两个原因:
- 已经创建了一个同名的 AgoraRtcChannel 频道。
- 已经通过 AgoraRtcChannel 加入了一个频道,并在该 AgoraRtcChannel 频道中发布了音视频流。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化,就调用该方法。请确认在调用 API 之前已经创建 AgoraRtcEngine 对象并完成初始化。
leaveChannel
离开频道。
leaveChannel(): number
离开频道,即挂断或退出通话。该方法会把会话相关的所有资源释放掉。该方法是异步操作,调用返回时并没有真正退出频道。
调用 joinChannel 后,必须调用 leaveChannel 结束通话,否则无法开始下一次通话。
不管当前是否在通话中,都可以调用 leaveChannel,没有副作用。
- 本地会触发 LEAVE_CHANNEL 回调。
- 通信场景下的用户和直播场景下的主播离开频道后,远端会触发 USER_OFFLINE 回调。
- 如果你调用了 leaveChannel 后立即调用 release 方法,SDK 将无法触发 LEAVE_CHANNEL 回调。
- 如果你在旁路推流过程中调用了 leaveChannel 方法,SDK 将自动调用 removePublishStreamUrl 方法。
返回值
- 0(ERR_OK): 方法调用成功。
- < 0: 方法调用失败。
- -1(ERR_FAILED): 一般性的错误(未明确归类)。
- -2(ERR_INVALID_ARGUMENT): 参数无效。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。
muteAllRemoteAudioStreams
取消或恢复订阅所有远端用户的音频流。
muteAllRemoteAudioStreams(mute: boolean): number
自 v3.3.0 起,成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的音频流,包括在调用该方法后加入频道的用户的音频流。
- 该方法需要在加入频道后调用。
- 该方法的推荐设置详见设置订阅状态。
参数
- mute
- 是否取消订阅所有远端用户的音频流:
true
: 取消订阅所有远端用户的音频流。false
:(默认)订阅所有远端用户的音频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteAllRemoteVideoStreams
取消或恢复订阅所有远端用户的视频流。
muteAllRemoteVideoStreams(mute: boolean): number
自 v3.3.0 起,成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的视频流,包括在调用该方法后加入频道的用户的视频流。
- 该方法需要在加入频道后调用。
- 该方法的推荐设置详见《设置订阅状态》。
参数
- mute
-
是否取消订阅所有远端用户的视频流。
true
: 取消订阅所有用户的视频流。false
:(默认)订阅所有用户的视频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
muteRemoteAudioStream
取消或恢复订阅指定远端用户的音频流。
muteRemoteAudioStream(userId: number, mute: boolean): number
- 该方法需要在加入频道后调用。
- 该方法的推荐设置详见《设置订阅状态》。
参数
- userId
- 指定用户的用户 ID。
- mute
是否取消订阅指定远端用户的音频流。
true
: 取消订阅指定用户的音频流。false
:(默认)订阅指定用户的音频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteRemoteVideoStream
取消或恢复订阅指定远端用户的视频流。
muteRemoteVideoStream(userId: number, mute: boolean): number
参数
- userId
-
指定用户的用户 ID。
- mute
是否取消订阅指定远端用户的视频流。
true
: 取消订阅指定用户的视频流。false
: (默认)订阅指定用户的视频流。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
publish
将本地音视频流发布到本频道。
publish(): number
- 该方法仅支持将音视频流发布到当前 AgoraRtcChannel 类所对应的频道。
- 直播场景下,该方法仅适用于角色为主播的用户。你可以调用该 AgoraRtcChannel 类下的 setClientRole 方法设置用户角色。
- SDK 只支持用户同一时间在一个频道发布一路音视频流。详情请参考进阶功能《多频道管理》。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -5(ERR_REFUSED): 调用被拒绝。
registerMediaMetadataObserver
注册媒体 metadata 观测器用于接收或发送 metadata。
registerMediaMetadataObserver(type: METADATA_TYPE = 0): number
- 请在 joinChannel 前调用该方法。
- 该方法仅适用于直播场景。
参数
- type
- 用户希望在观测器中使用的 METADATA 类型 。目前仅支持 VIDEO_METADATA 。详见 METADATA_TYPE。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
release
销毁 AgoraRtcChannel 对象。
release(): number
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
ERR_NOT_INITIALIZED
(7): SDK 尚未初始化,就调用其 API。请确认在调用 API 之前已创建 AgoraRtcChannel 对象并完成初始化。
removeInjectStreamUrl
删除导入的外部媒体流。
removeInjectStreamUrl(url: string): number
成功删除外部视频源 URL 地址后会触发 USER_OFFLINE 回调,uid 为
666
。
参数
- url
- 已导入、待删除的外部视频源 URL 地址。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
removePublishStreamUrl
删除旁路推流地址。
removePublishStreamUrl(url: string): number
调用该方法后,SDK 会在本地触发 RTMP_STREAMING_STATE_CHANGED 回调,报告删除旁路推流地址的状态。
- 调用该方法前,请确保已开通旁路推流的功能,详见进阶功能《推流到 CDN》中的前提条件。
- 只有直播场景中角色为主播的用户才能调用该方法。
- 该方法需要在加入频道后调用。
- 该方法每次只能删除一路旁路推流地址。若需删除多路流,则需多次调用该方法。
参数
- url
- 待删除的旁路推流地址,格式为 RTMP。该字符长度不能超过 1024 字节。推流地址不支持中文等特殊字符。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
renewToken
更新 Token。
renewToken(token: string): number
- 发生 TOKEN_PRIVILEGE_WILL_EXPIRE 回调时。
- CONNECTION_STATE_CHANGED 回调报告 CONNECTION_CHANGED_TOKEN_EXPIRED(9) 时。
参数
- token
- 新的 Token。
sendMetadata
发送媒体附属信息。
sendMetadata(metadata: Metadata): number
成功调用 registerMediaMetadataObserver 方法后,SDK 会触发 READY_TO_SEND_METADATA 回调,你可以调用该方法发送媒体附属信息。
如果成功发送了媒体附属信息,接收端会收到 METADATA_RECEIVED 回调。
参数
- metadata
- 媒体附属信息。详见 Metadata。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
sendStreamMessage
发送数据流。
sendStreamMessage(streamId: number, data: string): number
- 频道内每秒最多能发送 30 个包,且每个包最大为 1 KB。
- 每个客户端每秒最多能发送 6 KB 数据。
- 频道内每人最多能同时有 5 个数据通道。
成功调用该方法后,远端会触发 STREAM_MESSAGE 回调,远端用户可以在该回调中获取接收到的流消息; 若调用失败,远端会触发 STREAM_MESSAGE_ERROR 回调。
- 请确保在调用该方法前,已调用 createDataStreamWithConfig 创建了数据通道。
- 直播场景下,该方法仅适用于主播用户。
参数
- streamId
- 数据流 ID。可以通过 createDataStreamWithConfig 获取。
- data
- 待发送的数据。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setClientRole
设置直播场景下的用户角色。
setClientRole(role: CLIENT_ROLE_TYPE): number
在加入频道前和加入频道后均可调用该方法设置用户角色。
- 本地会触发 CLIENT_ROLE_CHANGED 回调。
- 远端会触发 USER_JOINED 或 USER_OFFLINE(USER_OFFLINE_BECOME_AUDIENCE) 回调。
参数
- role
-
直播场景里的用户角色。详见 CLIENT_ROLE_TYPE。
返回值
- 0(ERR_OK): 方法调用成功。
- < 0: 方法调用失败。
- -1(ERR_FAILED): 一般性的错误(未明确归类)。
- -2(ERR_INALID_ARGUMENT): 参数无效。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。
setClientRoleWithOptions
设置直播场景下的用户角色和级别。
setClientRoleWithOptions(role: CLIENT_ROLE_TYPE, options: ClientRoleOptions): number
- 自从
- v3.2.0
在加入频道前和加入频道后均可调用该方法设置用户角色。
- 本地触发 CLIENT_ROLE_CHANGED 回调。
- 远端触发 USER_JOINED 或 USER_OFFLINE 回调。
- 该方法仅在频道场景为直播(setChannelProfile 中 profile 设为 CHANNEL_PROFILE_LIVE_BROADCASTING)时生效。
- 该方法与 setClientRole 的区别在于,该方法还支持设置用户级别。
- 用户角色(role)确定用户在 SDK 层的权限,包含是否可以发送流、是否可以接收流、是否可以推流到 CDN 等。
- 用户级别(level)需要与角色结合使用,确定用户在其权限范围内,可以操作和享受到的服务级别。例如对于观众,选择接收低延时还是超低延时的视频流。不同的级别会影响计费。
参数
- role
- 直播场景中的用户角色。详见 CLIENT_ROLE_TYPE。
- options
- 用户具体设置,包含用户级别。详见 ClientRoleOptions。
返回值
- 0(ERR_OK): 方法调用成功。
- < 0: 方法调用失败。
- -1(ERR_FAILED): 一般性的错误(未明确归类)。
- -2(ERR_INVALID_ARGUMENT): 参数无效。
- -7(ERR_NOT_INITALIZED): SDK 尚未初始化。
setDefaultMuteAllRemoteAudioStreams
默认取消或恢复订阅远端用户的音频流。
setDefaultMuteAllRemoteAudioStreams(mute: boolean): number
- 弃用:
- 该方法自 v3.3.0 起废弃。
该方法需要在加入频道后调用。调用成功后,本地用户取消或恢复订阅调用时刻之后加入频道的远端用户。
取消订阅音频流后,如果需要恢复订阅频道内的远端,可以进行如下操作:
- 如果需要恢复订阅单个用户的音频流,调用 muteRemoteAudioStream (
false
),并指定你想要订阅的远端用户 ID。 - 如果想恢复订阅多个用户的音频流,则需要多次调用 muteRemoteAudioStream (
false
)。
参数
- mute
- 是否默认取消订阅远端用户的音频流:
true
:默认取消订阅远端用户的音频流。false
:(默认)默认订阅远端用户的音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setDefaultMuteAllRemoteVideoStreams
默认取消或恢复订阅远端用户的视频流。
setDefaultMuteAllRemoteVideoStreams(mute: boolean): number
- 弃用:
- 该方法自 v3.3.0 起废弃。
该方法需要在加入频道后调用。调用成功后,本地用户取消或恢复订阅调用时刻之后加入频道的远端用户。
取消订阅视频流后,如果需要恢复订阅频道内的远端,可以进行如下操作:
- 如果需要恢复订阅单个用户的视频流,调用 muteRemoteVideoStream (false),并指定你想要订阅的远端用户 ID。
- 如果想恢复订阅多个用户的视频流,则需要多次调用 muteRemoteVideoStream
(
false
)。
参数
- mute
-
是否默认取消订阅远端用户的视频流:
true
: 默认取消订阅。false
:(默认)默认订阅。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setEncryptionMode
启用内置的加密方案。
setEncryptionMode(encryptionMode: string): number
- 弃用:
- 该方法自 v3.1.0 起废弃。请改用 enableEncryption 方法。
Agora Video SDK 支持内置加密方案,默认支持 AES-128-XTS。如需采用其他加密方案,可以调用本方法。同一频道内的所有用户必须设置相同的加密方式和 secret 才能进行通话。关于这几种加密方式的区别,请参考 AES 加密算法的相关资料。
参数
- encryptionMode
-
加密模式:
- "
aes-128-xts
": 128 位 AES 加密,XTS 模式; - "
aes-128-ecb
": 128 位 AES 加密,ECB 模式; - "
aes-256-xts
": 256 位 AES 加密,XTS 模式; - "": 设置为空字符串时,默认使用加密方式 "
aes-128-xts
"。
- "
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setEncryptionSecret
启用内置加密,并设置数据加密密码。
setEncryptionSecret(secret: string): number
- 弃用:
- 该方法自 v3.1.0 起废弃。请改用 enableEncryption 方法。
在加入频道之前, app 需调用该方法指定 secret 来启用内置的加密功能,同一频道内的所有用户应设置相同的 secret。当用户离开频道时,该频道的 secret 会自动清除。如果未指定 secret 或将 secret 设置为空,则无法激活加密功能。
- 请不要在旁路推流时调用此方法。
- 为保证最佳传输效果,请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。
参数
- secret
- 加密密码。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLiveTranscoding
设置直播推流转码。
setLiveTranscoding(transcoding: LiveTranscoding): number
该方法用于旁路推流的视图布局及音频设置等。调用该方法更新转码设置后本地会触发 TRANSCODING_UPDATED 回调。
- 只有直播场景中角色为主播的用户才能调用该方法。
- 请确保已开通旁路推流的功能,详见进阶功能《推流到 CDN》中的前提条件。
- 首次调用该方法更新转码设置时,不会触发 TRANSCODING_UPDATED 回调。
- 该方法需要在加入频道后调用。
- Agora 目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。
参数
- transcoding
-
推流转码设置。详见 LiveTranscoding。
返回
- 0:方法调用成功。
- < 0:方法调用失败。
setMaxMetadataSize
设置媒体附属信息的最大大小。
setMaxMetadataSize(size: number): number
调用 registerMediaMetadataObserver 后,你可以调用本方法来设置媒体附属信息的最大大小。
参数
- size
- 媒体附属信息的最大大小。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setRemoteDefaultVideoStreamType
设置默认订阅的视频流类型。
setRemoteDefaultVideoStreamType(streamType: REMOTE_VIDEO_STREAM_TYPE): number
在网络条件受限的情况下,如果发送端没有调用 enableDualStreamMode (false
)
关闭双流模式,接收端可以选择接收大流还是小流。其中,大流可以接为高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。
正常情况下,用户默认接收大流。如需默认接收所有用户的视频小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。
调用本方法的执行结果将在 API_CALL_EXECUTED 中返回。
参数
- streamType
- 视频流类型: REMOTE_VIDEO_STREAM_TYPE 。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteUserPriority
设置远端用户媒体流的优先级。
setRemoteUserPriority(uid: number, userPriority: PRIORITY_TYPE): number
- 自从
- v2.4.0
设置远端用户的优先级。如果将某个用户的优先级设为高,那么发给这个用户的音视频流的优先级就会高于其他用户。弱网下 SDK 会优先保证高优先级用户收到的流的质量。
- 目前 Agora SDK 仅允许将一名远端用户设为高优先级。
- 该方法需要在加入频道前调用。
参数
- uid
- 远端用户的 ID。
- userPriority
- 远端用户的需求优先级。详见: PRIORITY_TYPE。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteVideoStreamType
设置订阅的视频流类型。
setRemoteVideoStreamType(userId: number, streamType: REMOTE_VIDEO_STREAM_TYPE): number
在网络条件受限的情况下,如果发送端没有调用 enableDualStreamMode(false) 关闭双流模式,接收端可以选择接收大流还是小流。其中,大流为高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。
正常情况下,用户默认接收大流。如需接收小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。
调用本方法的执行结果将在 API_CALL_EXECUTED 中返回。
参数
- userId
- 用户 ID。
- streamType
- 视频流类型: REMOTE_VIDEO_STREAM_TYPE 。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteVoicePosition
设置远端用户的语音位置。
setRemoteVoicePosition(uid: number, pan: number, gain: number): number
设置远端用户声音的空间位置和音量,方便本地用户听声辨位。
通过调用该接口设置远端用户声音出现的位置,左右声道的声音差异会产生声音的方位感,从而判断出远端用户的实时位置。在多人在线游戏场景,如吃鸡游戏中,该方法能有效增加游戏角色的方位感,模拟真实场景。
- 使用该方法需要在加入频道前调用 enableSoundPositionIndication 开启远端用户的语音立体声。
- 为获得最佳听觉体验,我们建议使用该方法时使用立体声外放。
- 该方法需要在加入频道后调用。
参数
- uid
- 远端用户的 ID
- pan
- 设置远端用户声音的空间位置,取值范围为 [-1.0,1.0]:
- (默认)0.0: 声音出现在正前方。
- -1.0: 声音出现在左边。
- 1.0: 声音出现在右边。
- gain
- 设置远端用户声音的音量,取值范围为 [0.0,100.0],默认值为 100.0,表示该用户的原始音量。取值越小,则音量越低。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startChannelMediaRelay
开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。
startChannelMediaRelay(configuration: ChannelMediaRelayConfiguration): number
- 如果 CHANNEL_MEDIA_RELAY_STATE_CHANGED 回调报告 RELAY_STATE_RUNNING (2) 和 RELAY_OK (0),且 CHANNEL_MEDIA_RELAY_EVENT 回调报告 RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL (4), 则表示 SDK 开始在源频道和目标频道之间转发媒体流。
- 如果 CHANNEL_MEDIA_RELAY_STATE_CHANGED 回调报告 RELAY_STATE_FAILURE (3), 则表示跨频道媒体流转发出现异常。
- 请在成功加入频道后调用该方法。
- 在直播场景中,只有角色为主播的用户才能调用该方法。
- 功调用该方法后,若你想再次调用该方法,必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。
- 跨频道媒体流转发功能需要提交工单联系技术支持开通。
- 该功能不支持 String 型 UID。
参数
- configuration
- 跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration。
返回值
- 0:方法调用成功
- < 0:方法调用失败
stopChannelMediaRelay
停止跨频道媒体流转发。一旦停止,主播会退出所有目标频道。
stopChannelMediaRelay(): number
成功调用该方法后,SDK 会触发 CHANNEL_MEDIA_RELAY_STATE_CHANGED 回调。如果报告 RELAY_STATE_IDLE (0) 和 RELAY_OK (0),则表示已停止转发媒体流。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
unpublish
停止将本地音视频流发布到本频道。
unpublish(): number
如果当前 IChannel 频道没有发布音视频流,调用该方法后 SDK 会返回 -5(ERR_REFUSED)。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -5(ERR_REFUSED): 调用被拒绝。
unregisterMediaMetadataObserver
取消注册媒体附属信息观测器。
unregisterMediaMetadataObserver(type: METADATA_TYPE = 0): number
参数
- type
- 观测器使用的 metadata 类型。目前仅支持 VIDEO_METADATA 。详见 METADATA_TYPE。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
updateChannelMediaRelay
更新媒体流转发的频道。
updateChannelMediaRelay(configuration: ChannelMediaRelayConfiguration): number
成功开始跨频道转发媒体流后,如果你希望将流转发到多个目标频道,或退出当前的转发频道,可以调用该方法。
成功调用该方法后,SDK 会触发 CHANNEL_MEDIA_RELAY_EVENT 回调, 并在回调中报告状态码 RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7)。
参数
- configuration
- 跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration 。
返回值
- 0:方法调用成功
- < 0:方法调用失败