多频道管理
介绍跟多频道相关的方法和回调。
RTC SDK 支持用户同时加入多个频道,可以同时在多个频道中接收和发布音视频流。
addVideoWatermarkEx
添加本地视频水印。
virtual int addVideoWatermarkEx(const char* watermarkUrl,
const WatermarkOptions& options,
const RtcConnection& connection) = 0;
详情
该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的用户、旁路直播观众和采集设备都能看到或采集到该水印图片。当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印。
- 如果视频编码方向(ORIENTATION_MODE)固定为横屏或自适应模式下的横屏,那么水印使用横屏坐标。
- 如果视频编码方向(ORIENTATION_MODE)固定为竖屏或自适应模式下的竖屏,那么水印使用竖屏坐标。
- 设置水印坐标时,水印的图像区域不能超出 setVideoEncoderConfigurationEx 方法中设置的视频尺寸,否则超出部分将被裁剪。
- 你需要在调用 enableVideo 方法之后再调用本方法。
- 待添加水印图片必须是 PNG 格式。本方法支持所有像素格式的 PNG 图片:RGBA、RGB、Palette、Gray 和 Alpha_gray。
- 如果待添加的 PNG 图片的尺寸与你在本方法中设置的尺寸不一致,SDK 会对 PNG 图片进行缩放或裁剪,以与设置相符。
- 如果你已经使用 startPreview [2/2] 方法开启本地视频预览,那么本方法的
visibleInPreview
可设置水印在预览时是否可见。 - 如果你已设置本地视频为镜像模式,那么此处的本地水印也为镜像。为避免本地用户看本地视频时的水印也被镜像,建议你不要对本地视频同时使用镜像和水印功能,请在应用层实现本地水印功能。
参数
- watermarkUrl
- 待添加的水印图片的本地路径。该方法支持从本地绝对/相对路径添加水印图片。
- options
- 待添加的水印图片的设置选项,详见 WatermarkOptions 。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustUserPlaybackSignalVolumeEx
调节本地播放的指定远端用户信号音量。
virtual int adjustUserPlaybackSignalVolumeEx(unsigned int uid, int volume, const RtcConnection& connection) = 0;
详情
- 自从
- v4.1.0
你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量,则需多次调用该方法。
- 该方法需要在加入频道后调用。
- 该方法调节的是本地播放的指定远端用户混音后的音量。
参数
- uid
- 远端用户 ID。
- volume
- 音乐文件音量范围为 0~100。100 (默认值)为原始文件音量。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
clearVideoWatermarkEx
删除已添加的视频水印。
virtual int clearVideoWatermarkEx(const RtcConnection& connection) = 0;
参数
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
createDataStreamEx [1/2]
创建数据流。
virtual int createDataStreamEx(int* streamId, bool reliable, bool ordered, const RtcConnection& connection) = 0;
详情
- 弃用:
- 该方法已废弃。请改用 createDataStreamEx [2/2]。
你可以调用该方法创建数据流并提高数据传输的可靠性和有序性。
- 请确保将 reliable 和 ordered 设为相同的值。
- 在 IRtcEngine 生命周期内,每个用户最多只能创建 5 个数据流。
- 频道内数据通道最多允许数据延迟 5 秒,若超过 5 秒接收方尚未收到数据流,则数据通道会向 app 报错。
参数
- streamId
- 输出参数,创建好的数据流 ID。
- reliable
-
是否保证数据可靠性,即接收方是否需要在数据发送后的 5 秒内接收:
true
: 保证接收方会在数据发送后的 5 秒内接收。如果接收方在数据发送后的 5 秒内没有接收数据,SDK 会报错。false
: 不保证收方会在数据发送后的 5 秒内接收。如果接收延迟或丢失数据,SDK 不会报错。
- ordered
-
是否保证数据有序性,即接收方是否需要收到有序的数据:
true
:保证接收方会按照发送方发送的顺序收到数据包。false
:不保证接收方按照发送方发送的顺序收到数据包。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 创建数据流成功。
- < 0: 创建数据流失败。
createDataStreamEx [2/2]
创建数据流。
virtual int createDataStreamEx(int* streamId, DataStreamConfig& config, const RtcConnection& connection) = 0;
详情
创建数据流。每个用户在每个频道中最多只能创建 5 个数据流。
相比 createDataStreamEx [1/2],本方法不支持数据可靠。接收方会丢弃超出发送时间 5 秒后的数据包。
参数
- streamId
- 输出参数,创建好的数据流 ID。
- config
- 数据流设置。详见 DataStreamConfig。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 创建数据流成功。
- < 0:方法调用失败。
enableAudioVolumeIndicationEx
启用用户音量提示。
virtual int enableAudioVolumeIndicationEx(int interval, int smooth, bool reportVad, const RtcConnection& connection) = 0;
详情
该方法允许 SDK 定期向 app 报告本地发流用户和瞬时音量最高的远端用户(最多 3 位)的音量相关信息。启用该方法后,只要频道内有发流用户,SDK 会在加入频道后按设置的时间间隔触发 onAudioVolumeIndication 回调。
参数
- interval
- 指定音量提示的时间间隔:
- ≤ 0: 禁用音量提示功能。
- > 0: 返回音量提示的间隔,单位为毫秒,最小取值为 50。
- smooth
- 平滑系数,指定音量提示的灵敏度。取值范围为 [0,10],建议值为 3。数字越大,波动越灵敏;数字越小,波动越平滑。
- reportVad
-
true
:开启本地人声检测功能。开启后,onAudioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声。false
:(默认)关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外,onAudioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
enableDualStreamModeEx
在发送端开启或关闭双流模式。
virtual int enableDualStreamModeEx(bool enabled, const SimulcastStreamConfig& streamConfig,
const RtcConnection& connection) = 0;
详情
- 自从
- v4.0.1
- 视频大流:高分辨率、高帧率的视频流。
- 视频小流:低分辨率、低帧率的视频流。
开启双流模式后,你可以在收流端调用 setRemoteVideoStreamType 选择接收视频大流或视频小流。
参数
- enabled
-
是否开启双流模式:
true
: 开启双流模式。false
: (默认) 关闭双流模式。
- streamConfig
-
视频小流的配置。详见 SimulcastStreamConfig。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableLoopbackRecordingEx
开启声卡采集。
virtual int enableLoopbackRecordingEx(const RtcConnection& connection, bool enabled, const char* deviceName = NULL) = 0;
详情
启用声卡采集功能后,声卡播放的声音会被合到本地音频流中,从而可以发送到远端。
- 该方法仅适用于 macOS 和 Windows 平台。
- macOS 系统默认声卡不支持采集功能,如果你需要使用该功能,请启用一个虚拟声卡,并将 deviceName 设为该虚拟声卡的设备名。声网推荐你使用声网自研的虚拟声卡 AgoraALD 进行采集。
- 该方法目前仅支持一路声卡采集。
参数
- connection
- Connection 信息。详见 RtcConnection。
- enabled
- 是否开启声卡采集:
true
: 开启声卡采集。false
:(默认)不开启声卡采集。
- deviceName
-
- macOS: 虚拟声卡的设备名。默认为空,代表使用 AgoraALD 虚拟声卡进行采集。
- Windows: 声卡的设备名。默认为空,代表使用设备自带的声卡进行采集。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getConnectionStateEx
获取当前网络连接状态。
virtual CONNECTION_STATE_TYPE getConnectionStateEx(const RtcConnection& connection) = 0;
详情
该方法在加入频道前后都能调用。
参数
- connection
- Connection 信息。详见 RtcConnection。
返回值
当前网络连接状态。详见 CONNECTION_STATE_TYPE。
joinChannelEx
使用连接 ID 加入频道。
virtual int joinChannelEx(const char* token, const RtcConnection& connection,
const ChannelMediaOptions& options,
IRtcEngineEventHandler* eventHandler) = 0;
详情
调用该方法,你可以同时加入多个频道。
- 如果你已经在一个频道内,你不能用相同的用户 UID 再次加入该频道。
- 如果你想在不同的设备上加入相同的频道,请确保你在不同设备上使用的用户 UID 都不同。
- 请确保生成 Token 时传入的 app ID 和创建 IRtcEngine 实例时传入的 app ID 一致。
- 在多摄像头采集场景下,你需要在调用该方法之后调用 startPreview [2/2] 方法设置 sourceType 为 VIDEO_SOURCE_CAMERA_SECONDARY,以确保第二个摄像头采集正常。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
注: 如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token,详见 使用通配 Token。
- connection
- Connection 信息。详见 RtcConnection。
- options
- 频道媒体设置选项。详见 ChannelMediaOptions。
- eventHandler
- IRtcEngineEx 的回调类,详见 IRtcEngineEventHandler。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,ChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:IRtcEngine 对象初始化失败。你需要重新初始化 IRtcEngine 对象。
- -7:IRtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 IRtcEngine 对象。
- -8:IRtcEngine 对象内部状态错误。可能的原因是:调用 startEchoTest [3/3] 开始通话回路测试后,未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 onConnectionStateChanged 回调判断用户是否在频道中。除收到 CONNECTION_STATE_DISCONNECTED(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
joinChannelWithUserAccountEx
使用 User Account 加入频道,并设置是否自动订阅音频或视频流。
virtual int joinChannelWithUserAccountEx(const char* token, const char* channelId,
const char* userAccount, const ChannelMediaOptions& options,
IRtcEngineEventHandler* eventHandler) = 0;
详情
- 本地:onLocalUserRegistered、onJoinChannelSuccess 和 onConnectionStateChanged 回调。
- 远端:通信场景下的用户和直播场景下的主播加入频道后,远端会分别触发 onUserJoined 和 onUserInfoUpdated 回调。
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
注: 如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token,详见 使用通配 Token。
- channelId
-
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- userAccount
-
用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account,并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填,最大不超过 255 字节,不可填 NULL。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- options
- 频道媒体设置选项。详见 ChannelMediaOptions。
- eventHandler
- IRtcEngineEx 的回调类,详见 IRtcEngineEventHandler。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
leaveChannelEx [1/2]
离开频道。
virtual int leaveChannelEx(const RtcConnection& connection) = 0;
详情
离开频道,即挂断或退出通话。
调用 joinChannelEx 加入频道后,必须调用本方法结束通话,才能开始下一次通话。
不管当前是否在通话中,都可以调用该方法。该方法会把会话相关的所有资源释放掉。
该方法是异步操作,调用返回时并没有真正退出频道。在真正退出频道后,SDK 会触发 onLeaveChannel 回调。
成功调用该方法离开频道后,本地会触发 onLeaveChannel 回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 onUserOffline 回调。
- 如果你调用了本方法后立即调用 release 方法,SDK 将无法触发 onLeaveChannel 回调。
- 调用 leaveChannel [1/2] 后会同时离开 joinChannel [2/2] 和 joinChannelEx 加入的频道。
参数
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
leaveChannelEx [2/2]
设置频道选项并离开频道。
virtual int leaveChannelEx(const RtcConnection& connection, const LeaveChannelOptions& options) = 0;
详情
离开频道,即挂断或退出通话。
调用 joinChannelEx 加入频道后,必须调用本方法结束通话,才能开始下一次通话。
不管当前是否在通话中,都可以调用该方法。该方法会把会话相关的所有资源释放掉。
该方法是异步操作,调用返回时并没有真正退出频道。在真正退出频道后,SDK 会触发 onLeaveChannel 回调。
成功调用该方法离开频道后,本地会触发 onLeaveChannel 回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 onUserOffline 回调。
- 如果你调用了本方法后立即调用 release 方法,SDK 将无法触发 onLeaveChannel 回调。
- 调用 leaveChannel [2/2] 后会同时离开 joinChannel [2/2] 和 joinChannelEx 加入的频道。
参数
- connection
- Connection 信息。详见 RtcConnection。
- options
-
- 自从
- v4.1.0
离开频道的选项,详见 LeaveChannelOptions。
注: 该参数仅支持设置 LeaveChannelOptions 中的 stopMicrophoneRecording 成员,设置其他成员均不生效。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
muteAllRemoteAudioStreamsEx
取消或恢复订阅所有远端用户的音频流。
virtual int muteAllRemoteAudioStreamsEx(bool mute, const RtcConnection& connection) = 0;
详情
成功调用该方法后,本地用户会取消或恢复订阅远端用户的音频流,包括在调用该方法后加入频道的用户的音频流。
- 该方法需要在加入频道后调用。
- 如果需要在加入频道前设置默认不订阅远端用户音频流,可以在调用 joinChannel [2/2] 加入频道时设置 autoSubscribeAudio 为
false
。 - 该方法的推荐设置详见设置订阅状态。
参数
- mute
-
是否取消订阅所有远端用户的音频流:
true
: 取消订阅所有远端用户的音频流。false
:(默认)订阅所有远端用户的音频流。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteAllRemoteVideoStreamsEx
取消或恢复订阅所有远端用户的视频流。
virtual int muteAllRemoteVideoStreamsEx(bool mute, const RtcConnection& connection) = 0;
详情
- 自从
- v4.1.0
成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的视频流,包括在调用该方法后加入频道的用户的视频流。
参数
- mute
-
是否取消订阅所有远端用户的视频流。
true
: 取消订阅所有用户的视频流。false
:(默认)订阅所有用户的视频流。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteLocalAudioStreamEx
取消或恢复发布本地音频流。
virtual int muteLocalAudioStreamEx(bool mute, const RtcConnection& connection) = 0;
详情
成功调用该方法后,远端会触发 onUserMuteAudio 回调和 onRemoteAudioStateChanged 回调。
参数
- mute
-
是否取消发布本地音频流。
true
: 取消发布。false
:(默认)发布。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteLocalVideoStreamEx
取消或恢复发布本地视频流。
virtual int muteLocalVideoStreamEx(bool mute, const RtcConnection& connection) = 0;
详情
- 自从
- v4.1.0
成功调用该方法后,远端会触发 onUserMuteVideo 回调。
- 该方法不影响视频采集状态,没有禁用摄像头。
参数
- mute
-
是否取消发送本地视频流。
true
: 取消发送本地视频流。false
: (默认)发送本地视频流。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteRemoteAudioStreamEx
停止/恢复接收指定的音频流。
virtual int muteRemoteAudioStreamEx(uid_t uid, bool mute, const RtcConnection& connection) = 0;
详情
该方法停止/恢复接收某一个指定远端用户的音频流。在加入频道前或后都可以调用。该方法的设置在离开频道后失效。参数
- uid
- 指定用户的 ID。
- mute
-
是否停止接收指定音频流:
true
: 停止接收指定音频流。false
:(默认)继续接收指定音频流。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteRemoteVideoStreamEx
停止/恢复接收指定的视频流。
virtual int muteRemoteVideoStreamEx(uid_t uid, bool mute, const RtcConnection& connection) = 0;
详情
该方法停止/恢复接收某一个指定远端用户的视频流。在加入频道前或后都可以调用。该方法的设置在离开频道后失效。
参数
- uid
-
远端用户的 ID。
- mute
-
是否停止接收某个远端用户的视频:
true
: 停止接收。false
: (默认)恢复接收。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
pauseAllChannelMediaRelayEx
暂停向所有目标频道转发媒体流。
virtual int pauseAllChannelMediaRelayEx(const RtcConnection& connection) = 0;
详情
开始跨频道转发媒体流后,如果你需要暂停向所有频道转发媒体流,可以调用该方法;暂停后,如果要恢复跨频道媒体流转发,可以调用 resumeAllChannelMediaRelay 方法。
参数
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
resumeAllChannelMediaRelayEx
恢复向所有目标频道转发媒体流。
virtual int resumeAllChannelMediaRelayEx(const RtcConnection& connection) = 0;
详情
调用 pauseAllChannelMediaRelayEx 方法后,如果你需要恢复向所有目标频道转发媒体流,可以调用该方法。
参数
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
sendCustomReportMessageEx
自定义数据上报和分析服务。
virtual int sendCustomReportMessageEx(const char* id, const char* category, const char* event, const char* label,
int value, const RtcConnection& connection) = 0;
详情
声网提供自定义数据上报和分析服务。该服务当前处于免费内测期。内测期提供的能力为 6 秒内最多上报 10 条数据,每条自定义数据不能超过 256 字节,每个字符串不能超过 100 字节。如需试用该服务,请联系 sales@agora.io 开通并商定自定义数据格式。
sendStreamMessageEx
发送数据流。
virtual int sendStreamMessageEx(int streamId, const char* data, size_t length, const RtcConnection& connection) = 0;
详情
调用 createDataStreamEx [2/2] 后,你可以调用本方法向频道内所有用户发送数据流消息。
- 频道内每秒最多能发送 60 个包,且每个包最大为 1 KB。
- 每个客户端每秒最多能发送 30 KB 数据。
- 频道内每人最多能同时有 5 个数据通道。
成功调用该方法后,远端会触发 onStreamMessage 回调,远端用户可以在该回调中获取接收到的流消息; 若调用失败,远端会触发 onStreamMessageError 回调。
- 请确保在调用该方法前,已调用 createDataStreamEx [2/2] 创建了数据通道。
- 该方法仅适用于通信场景以及直播场景下的主播用户,如果直播场景下的观众调用此方法可能会造成观众变主播。
参数
- streamId
- 数据流 ID。可以通过 createDataStreamEx [2/2] 获取。
- data
- 待发送的数据。
- length
- 数据长度。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setDualStreamModeEx
在发送端设置双流模式。
virtual int setDualStreamModeEx(SIMULCAST_STREAM_MODE mode,
const SimulcastStreamConfig& streamConfig,
const RtcConnection& connection) = 0;
详情
- 自从
- v4.0.1
SDK 默认在发送端开启小流 auto 模式,效果等同于调用该方法并将 mode 设置为 AUTO_SIMULCAST_STREAM。如果你想修改此行为,可以调用该方法并修改 mode 为 DISABLE_SIMULCAST_STREAM(始终不发送小流)或 ENABLE_SIMULCAST_STREAM(始终发送小流)。
- 调用该方法并设置 mode 为 DISABLE_SIMULCAST_STREAM 时,跟
enableDualStreamModeEx(false)
的效果相同。 - 调用该方法并设置 mode 为 ENABLE_SIMULCAST_STREAM 时,跟
enableDualStreamModeEx(true)
的效果相同。 - 两种方法均可在加入频道前后调用,若同时使用,则以后调用的方法中的设置为准。
参数
- mode
- 发送视频流的模式。详见 SIMULCAST_STREAM_MODE。
- streamConfig
-
视频小流的配置。详见 SimulcastStreamConfig。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteRenderModeEx
设置远端视图显示模式。
virtual int setRemoteRenderModeEx(uid_t uid, media::base::RENDER_MODE_TYPE renderMode,
VIDEO_MIRROR_MODE_TYPE mirrorMode, const RtcConnection& connection) = 0;
详情
- 请在调用 setupRemoteVideo 方法初始化远端视图后,调用该方法。
- 你可以在通话中多次调用该方法,多次更新远端用户视图的显示模式。
参数
- uid
- 远端用户 ID。
- renderMode
-
远端视图显示模式,详见 RENDER_MODE_TYPE。
- mirrorMode
-
远端用户视图的镜像模式,详见 VIDEO_MIRROR_MODE_TYPE。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功
- < 0:方法调用失败
setRemoteVideoStreamTypeEx
设置订阅的视频流类型。
virtual int setRemoteVideoStreamTypeEx(uid_t uid, VIDEO_STREAM_TYPE streamType, const RtcConnection& connection) = 0;
详情
在网络条件受限的情况下,如果发送端没有调用 enableDualStreamModeEx(false)
关闭双流模式,接收端可以调用该方法选择接收大流还是小流。其中,大流为高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。
正常情况下,用户默认接收大流。如需接收小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。
SDK 默认在发送端开启小流 auto 模式(不主动发送小流),接收端主播可以调用本方法在接收端发起小流申请,发送端收到申请后自动切换为小流模式。
参数
- uid
- 用户 ID。
- streamType
-
视频流类型: VIDEO_STREAM_TYPE。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteVideoSubscriptionOptionsEx
设置远端视频流的订阅选项。
virtual int setRemoteVideoSubscriptionOptionsEx(uid_t uid, const VideoSubscriptionOptions& options, const RtcConnection& connection) = 0;
详情
当远端发送双流时,可调用此方法来设置远端视频流的订阅选项。
参数
- uid
- 远端用户 ID。
- options
- 视频流的订阅设置,详见 VideoSubscriptionOptions。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setRemoteVoicePositionEx
设置远端用户声音的 2D 位置,即水平面位置。
virtual int setRemoteVoicePositionEx(uid_t uid, double pan, double gain, const RtcConnection& connection) = 0;
详情
设置远端用户声音的空间位置和音量,方便本地用户听声辨位。
通过调用该接口设置远端用户声音出现的位置,左右声道的声音差异会产生声音的方位感,从而判断出远端用户的实时位置。在多人在线游戏场景,如吃鸡游戏中,该方法能有效增加游戏角色的方位感,模拟真实场景。
- 为获得最佳听觉体验,建议用户佩戴有线耳机。
- 该方法需要在加入频道后调用。
参数
- uid
- 远端用户的 ID。
- pan
- 设置远端用户声音的空间位置,取值范围为 [-1.0,1.0]:
- -1.0: 声音出现在左边。
- (默认)0.0: 声音出现在正前方。
- 1.0: 声音出现在右边。
- gain
- 设置远端用户声音的音量,取值范围为 [0.0,100.0],默认值为 100.0,表示该用户的原始音量。取值越小,则音量越低。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setSubscribeAudioAllowlistEx
设置音频订阅白名单。
virtual int setSubscribeAudioAllowlistEx(uid_t* uidList, int uidNumber, const RtcConnection& connection) = 0;
详情
你可以调用该方法指定想要订阅的音频流。
- 该方法在加入频道前后均可调用。
- 音频订阅白名单不受 muteRemoteAudioStream、muteAllRemoteAudioStreams 以及 ChannelMediaOptions 中的 autoSubscribeAudio 的影响。
- 设置订阅白名单后,如果离开当前频道后再重新加入频道,白名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
音频订阅白名单的用户 ID 列表。
如果你想指定订阅某一发流用户的音频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅白名单中移除,需要重新调用 setSubscribeAudioAllowlist 方法更新音频订阅白名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- uidNumber
- 白名单用户 ID 列表中的用户数量。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeAudioBlocklistEx
设置音频订阅黑名单。
virtual int setSubscribeAudioBlocklistEx(uid_t* uidList, int uidNumber, const RtcConnection& connection) = 0;
详情
你可以调用该方法指定不订阅的音频流。
- 该方法在加入频道前后均可调用。
- 音频订阅黑名单不受 muteRemoteAudioStream、muteAllRemoteAudioStreams 以及 ChannelMediaOptions 中的 autoSubscribeAudio 影响。
- 设置订阅黑名单后,如果离开当前频道后再重新加入频道,黑名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
订阅黑名单的用户 ID 列表。
如果你想指定不订阅某一发流用户的音频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅黑名单中移除,需要重新调用 setSubscribeAudioBlocklist 方法更新订阅黑名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- uidNumber
- 黑名单用户 ID 列表中的用户数量。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeVideoAllowlistEx
设置视频订阅白名单。
virtual int setSubscribeVideoAllowlistEx(uid_t* uidList, int uidNumber, const RtcConnection& connection) = 0;
详情
你可以调用该方法指定想要订阅的视频流。
- 该方法在加入频道前后均可调用。
- 视频订阅白名单不受 muteRemoteVideoStream、muteAllRemoteVideoStreams 以及 ChannelMediaOptions 中的 autoSubscribeVideo 的影响。
- 设置订阅白名单后,如果离开当前频道后再重新加入频道,白名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
视频订阅白名单的用户 ID 列表。
如果你想指定仅订阅某一发流用户的视频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅白名单中移除,需要重新调用 setSubscribeVideoAllowlist 方法更新音频订阅白名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- uidNumber
- 白名单用户 ID 列表中的用户数量。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeVideoBlocklistEx
设置视频订阅黑名单。
virtual int setSubscribeVideoBlocklistEx(uid_t* uidList, int uidNumber, const RtcConnection& connection) = 0;
详情
你可以调用该方法指定不订阅的视频流。
- 该方法在加入频道前后均可调用。
- 视频订阅黑名单不受 muteRemoteVideoStream、muteAllRemoteVideoStreams 以及 ChannelMediaOptions 中的 autoSubscribeVideo 的影响。
- 设置订阅黑名单后,如果离开当前频道后再重新加入频道,黑名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
视频订阅黑名单的用户 ID 列表。
如果你想指定不订阅某一发流用户的视频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅黑名单中移除,需要重新调用 setSubscribeVideoBlocklist 方法更新订阅黑名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- uidNumber
- 黑名单用户 ID 列表中的用户数量。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setupRemoteVideoEx
初始化远端用户视图。
virtual int setupRemoteVideoEx(const VideoCanvas& canvas, const RtcConnection& connection) = 0;
详情
该方法绑定远端用户和显示视图,并设置远端用户视图在本地显示时的渲染模式和镜像模式,只影响本地用户看到的视频画面。
调用该方法时需要在 VideoCanvas 中指定远端视频的用户 ID,一般可以在进频道前提前设置好。
如果无法在加入频道前得到远端用户的 uid,可以在收到 onUserJoined 回调时调用该方法。如果启用了视频录制功能,视频录制服务会做为一个哑客户端加入频道,因此其他客户端也会收到它的 onUserJoined
事件, app 不应给它绑定视图(因为它不会发送视频流)。
如需解除某个远端用户的绑定视图,可以调用该方法并将 view 设置为空。
离开频道后,SDK 会清除远端用户视图的绑定关系。
如果你希望在通话中更新远端用户视图的渲染或镜像模式,请使用 setRemoteRenderModeEx 方法。
参数
- canvas
-
视频画布信息。详见 VideoCanvas。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setVideoEncoderConfigurationEx
设置本地视频编码属性。
virtual int setVideoEncoderConfigurationEx(const VideoEncoderConfiguration& config, const RtcConnection& connection) = 0;
详情
每一种视频编码属性对应一系列视频相关参数设置,包含分辨率、帧率和码率。
该方法的 config 参数设置是在理想网络状态下能达到的最大值。如果网络状态不好,视频引擎便不能使用该 config 渲染本地视频,它会自动降低到一个合适的视频参数设置。
参数
- config
- 视频编码参数配置。详见 VideoEncoderConfiguration。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
startChannelMediaRelayEx
开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。
virtual int startChannelMediaRelayEx(const ChannelMediaRelayConfiguration& configuration, const RtcConnection& connection) = 0;
详情
- 弃用:
- 该方法已废弃。请改用 startOrUpdateChannelMediaRelayEx 。
- 如果 onChannelMediaRelayStateChanged 回调报告 RELAY_STATE_RUNNING (2) 和 RELAY_OK (0),且 onChannelMediaRelayEvent 回调报告 RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL (4), 则表示 SDK 开始在源频道和目标频道之间转发媒体流。
- 如果 onChannelMediaRelayStateChanged 回调报告 RELAY_STATE_FAILURE (3), 则表示跨频道媒体流转发出现异常。
- 请在成功加入频道后调用该方法。
- 在直播场景中,只有角色为主播的用户才能调用该方法。
- 成功调用该方法后,若你想再次调用该方法,必须先调用 stopChannelMediaRelayEx 方法退出当前的转发状态。
- 跨频道媒体流转发功能需要联系技术支持开通。
- 该功能不支持 String 型 UID。
参数
- configuration
- 跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功
- < 0:方法调用失败。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -7: 方法调用被拒绝。可能因为 SDK 未初始化成功,或用户角色不是主播。
- -8:内部状态错误。可能因为用户角色不是主播。
startOrUpdateChannelMediaRelayEx
开始或更新跨频道媒体流转发。
virtual int startOrUpdateChannelMediaRelayEx(const ChannelMediaRelayConfiguration& configuration, const RtcConnection& connection) = 0;
详情
- 自从
- v4.2.0
首次成功调用该方法将开始跨频道转发媒体流。如需将流转发到多个目标频道,或退出当前的转发频道,可以再次调用该方法添加或移除转发的目标频道。该功能最多支持将媒体流转发至 6 个目标频道。
- 如果 onChannelMediaRelayStateChanged 回调报告 RELAY_STATE_RUNNING (2) 和 RELAY_OK (0), 则表示 SDK 开始在源频道和目标频道之间转发媒体流。
- 如果 onChannelMediaRelayStateChanged 回调报告 RELAY_STATE_FAILURE (3), 则表示跨频道媒体流转发出现异常。
- 请在成功加入频道后调用该方法。
- 在直播场景中,只有角色为主播的用户才能调用该方法。
- 跨频道媒体流转发功能需要联系技术支持开通。
- 该功能不支持 String 型 UID。
参数
- configuration
- 跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功
- < 0:方法调用失败。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -7: 方法调用被拒绝。可能因为 SDK 未初始化成功,或用户角色不是主播。
- -8:内部状态错误。可能因为用户角色不是主播。
startMediaRenderingTracingEx
开启视频帧渲染数据打点。
virtual int startMediaRenderingTracingEx(const RtcConnection& connection) = 0;
详情
- 自从
- v4.1.1
成功调用该方法后,SDK 会以调用该方法的时刻作为起点,并通过 onVideoRenderingTracingResult 回调报告视频帧渲染的相关信息。
- SDK 默认在成功加入频道的时刻起打点,自动开始跟踪视频频的渲染事件。你可以根据实际业务场景,在合适的时机调用该方法,进行自定义打点。
- 离开当前频道后,SDK 会自动重置该时间点为下一次成功加入频道的时刻。
适用场景
声网推荐你将该方法和 app 中的 UI 设置(按钮、滑动条等)结合使用,用于针对终端用户的体验改进。例如:在终端用户在点击 加入频道
按钮的时刻调用该方法进行打点,然后通过 onVideoRenderingTracingResult 回调获取视频帧渲染过程中的指标,从而针对指标进行专项优化。
参数
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
startRtmpStreamWithoutTranscodingEx
开始非转码推流。
virtual int startRtmpStreamWithoutTranscodingEx(const char* url, const RtcConnection& connection) = 0;
详情
- 自从
- v4.1.0
声网推荐你使用更加完善的服务端推流功能,详见实现服务端旁路推流。
调用该方法,你可以向指定的旁路推流地址推送直播音视频流。该方法每次只能向一个地址推送媒体流,如果你需要向多个地址转码推流,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 onRtmpStreamingStateChanged 回调,报告推流的状态。
- 请在加入频道后调用该方法。
- 只有直播场景下的主播才能调用该方法。
- 调用该方法推流失败后,如果你想要重新推流,那么请你务必先调用 stopRtmpStream,再调用该方法重推,否则 SDK 会返回与上次推流失败时一样的错误码。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:url 为空或为长度为 0 的字符串。
- -7:调用该方法前,未初始化 SDK。
- -19:该旁路推流 URL 已在使用中,请使用其他旁路推流 URL。
startRtmpStreamWithTranscodingEx
开始旁路推流并设置转码属性。
virtual int startRtmpStreamWithTranscodingEx(const char* url, const LiveTranscoding& transcoding, const RtcConnection& connection) = 0;
详情
- 自从
- v4.1.0
声网推荐你使用更加完善的服务端推流功能,详见实现服务端旁路推流。
调用该方法,你可以向指定的旁路推流地址推送直播音视频流并设置转码属性。该方法每次只能向一个地址推送媒体流,如果你需要向多个地址转码推流,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 onRtmpStreamingStateChanged 回调,报告推流的状态。
- 请确保已开通旁路推流服务。详见旁路推流中的前提条件。
- 请在加入频道后调用该方法。
- 只有直播场景下的主播才能调用该方法。
- 调用该方法推流失败后,如果你想要重新推流,那么请你务必先调用 stopRtmpStreamEx,再调用该方法重推,否则 SDK 会返回与上次推流失败时一样的错误码。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
- transcoding
-
旁路推流的转码属性,详见 LiveTranscoding 类。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:url 为空或为长度为 0 的字符串。
- -7:调用该方法前,未初始化 SDK。
- -19:该旁路推流 URL 已在使用中,请使用其他旁路推流 URL。
stopChannelMediaRelayEx
停止跨频道媒体流转发。一旦停止,主播会退出所有目标频道。
virtual int stopChannelMediaRelayEx(const RtcConnection& connection) = 0;
详情
成功调用该方法后,SDK 会触发 onChannelMediaRelayStateChanged 回调。如果报告 RELAY_STATE_IDLE (0) 和 RELAY_OK (0),则表示已停止转发媒体流。
参数
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
stopRtmpStreamEx
结束旁路推流。
virtual int stopRtmpStreamEx(const char* url, const RtcConnection& connection) = 0;
详情
声网推荐你使用更加完善的服务端推流功能,详见实现服务端旁路推流。
调用该方法,你可以结束指定的旁路推流地址上的直播。该方法每次只能结束一个推流地址上的直播,如果你需要结束多个推流地址的直播,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 onRtmpStreamingStateChanged 回调,报告推流的状态。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
takeSnapshotEx
获取视频截图。
virtual int takeSnapshotEx(const RtcConnection& connection, uid_t uid, const char* filePath) = 0;
详情
该方法用于对指定用户的视频流进行截图,生成一张 JPG 格式的图片,并保存至指定的路径。
该方法是异步操作,调用返回时 SDK 并没有真正获取截图。成功调用该方法后,SDK 会触发 onSnapshotTaken 回调报告截图是否成功和获取截图的详情。
- 该方法需要在调用 joinChannelEx 后调用。
- 该方法用于本地视频截图时,是对 ChannelMediaOptions 中指定发布的视频流进行截图。
- 如果用户的视频经过前处理,例如,添加了水印或美颜,生成的截图会包含前处理效果。
参数
- connection
- Connection 信息。详见 RtcConnection。
- uid
- 用户 ID。如果要对本地用户的视频截图,则设为 0。
- filePath
-
截图的本地保存路径,需精确到文件名及格式, 例如:
- Windows:
C:\Users\<user_name>\AppData\Local\Agora\<process_name>\example.jpg
- iOS:
/App Sandbox/Library/Caches/example.jpg
- macOS:
~/Library/Logs/example.jpg
- Android:
/storage/emulated/0/Android/data/<package name>/files/example.jpg
- Windows:
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
updateChannelMediaOptionsEx
加入频道后更新频道媒体选项 。
virtual int updateChannelMediaOptionsEx(const ChannelMediaOptions& options, const RtcConnection& connection) = 0;
参数
- options
- 频道媒体选项,详见 ChannelMediaOptions。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:ChannelMediaOptions 结构体成员值设置无效。例如,使用了不合法的 Token,设置了无效的用户角色。你需要填入有效的参数。
- -7:IRtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 IRtcEngine 对象。
- -8:IRtcEngine 对象内部状态错误。可能的原因是用户不在频道中。建议通过 onConnectionStateChanged 回调判断用户是否在频道中。如果收到 CONNECTION_STATE_DISCONNECTED(1) 或 CONNECTION_STATE_FAILED(5),则表示用户不在频道中。你需要在调用该方法前调用 joinChannel [2/2] 加入频道。
updateChannelMediaRelayEx
更新媒体流转发的频道。
virtual int updateChannelMediaRelayEx(const ChannelMediaRelayConfiguration& configuration, const RtcConnection& connection) = 0;
详情
- 弃用:
- 该方法已废弃。请改用 startOrUpdateChannelMediaRelayEx。
成功开始跨频道转发媒体流后,如果你希望将流转发到多个目标频道,或退出当前的转发频道,可以调用该方法。
成功调用该方法后,SDK 会触发 onChannelMediaRelayEvent 回调, 并在回调中报告状态码 RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7)。
onChannelMediaRelayStateChanged(RELAY_STATE_RUNNING, RELAY_OK)
后调用该方法;否则,方法调用会失败。参数
- configuration
- 跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration 。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功
- < 0:方法调用失败
updateRtmpTranscodingEx
更新旁路推流转码属性。
virtual int updateRtmpTranscodingEx(const LiveTranscoding& transcoding, const RtcConnection& connection) = 0;
详情
声网推荐你使用更加完善的服务端推流功能,详见实现服务端旁路推流。
开启转码推流后,你可以根据场景需求,动态更新转码属性。转码属性更新后,SDK 会触发 onTranscodingUpdated 回调。
参数
- transcoding
-
旁路推流的转码属性,详见 LiveTranscoding 类。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。