RtcEngineEx
提供多频道方法的接口类。
继承自 RtcEngine。
addVideoWatermarkEx
添加本地视频水印。
public abstract int addVideoWatermarkEx( String watermarkUrl, WatermarkOptions options, RtcConnection connection);
该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的用户、旁路直播观众和采集设备都能看到或采集到该水印图片。 Agora 当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印。
- 如果视频编码方向(ORIENTATION_MODE)固定为横屏或自适应模式下的横屏,那么水印使用横屏坐标。
- 如果视频编码方向(ORIENTATION_MODE)固定为竖屏或自适应模式下的竖屏,那么水印使用竖屏坐标。
- 设置水印坐标时,水印的图像区域不能超出 setVideoEncoderConfigurationEx 方法中设置的视频尺寸,否则超出部分将被裁剪。
- 你需要在调用 enableVideo 方法之后再调用本方法。
- 待添加水印图片必须是 PNG 格式。本方法支持所有像素格式的 PNG 图片:RGBA、RGB、Palette、Gray 和 Alpha_gray。
- 如果待添加的 PNG 图片的尺寸与你在本方法中设置的尺寸不一致,SDK 会对 PNG 图片进行缩放或裁剪,以与设置相符。
- 如果你已经使用 startPreview [1/2] 方法开启本地视频预览,那么本方法的
visibleInPreview
可设置水印在预览时是否可见。 - 如果你已设置本地视频为镜像模式,那么此处的本地水印也为镜像。为避免本地用户看本地视频时的水印也被镜像,Agora 建议你不要对本地视频同时使用镜像和水印功能,请在应用层实现本地水印功能。
参数
- watermarkUrl
- 待添加的水印图片的本地路径。该方法支持从本地绝对/相对路径添加水印图片。
- options
- 待添加的水印图片的设置选项,详见 WatermarkOptions 。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
clearVideoWatermarkEx
删除已添加的视频水印。
public abstract int clearVideoWatermarkEx(RtcConnection connection);
参数
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
createDataStreamEx [1/2]
创建数据流。
public abstract int createDataStreamEx( boolean reliable, boolean ordered, RtcConnection connection);
- 弃用:
- 该方法已废弃。请改用 createDataStreamEx [2/2]。
你可以调用该方法创建数据流并提高数据传输的可靠性和有序性。
- 请确保将 reliable 和 ordered 设为相同的值。
- 在 RtcEngine 生命周期内,每个用户最多只能创建 5 个数据流。
- 频道内数据通道最多允许数据延迟 5 秒,若超过 5 秒接收方尚未收到数据流,则数据通道会向 app 报错。
参数
- reliable
-
是否保证数据可靠性,即接收方是否需要在数据发送后的 5 秒内接收:
true
: 保证接收方会在数据发送后的 5 秒内接收。如果接收方在数据发送后的 5 秒内没有接收数据,SDK 会报错。false
: 不保证收方会在数据发送后的 5 秒内接收。如果接收延迟或丢失数据,SDK 不会报错。
- ordered
-
是否保证数据有序性,即接收方是否需要收到有序的数据:
true
:保证接收方会按照发送方发送的顺序收到数据包。false
:不保证接收方按照发送方发送的顺序收到数据包。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 成功创建的数据流 ID:方法调用成功。
- < 0: 创建数据流失败。
createDataStreamEx [2/2]
创建数据流。
public abstract int createDataStreamEx(DataStreamConfig config, RtcConnection connection);
创建数据流。每个用户在每个频道中最多只能创建 5 个数据流。
相比 createDataStreamEx [1/2] ,本方法不支持数据可靠。接收方会丢弃超出发送时间 5 秒后的数据包。
参数
- config
- 数据流设置。详见 DataStreamConfig。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 创建的数据流的 ID:方法调用成功。
- < 0:方法调用失败。
enableDualStreamModeEx
在发送端开启或关闭双流模式。
public abstract int enableDualStreamModeEx( boolean enabled, SimulcastStreamConfig streamConfig, RtcConnection connection);
- 自从
- v4.0.1
- 视频大流:高分辨率、高帧率的视频流。
- 视频小流:低分辨率、低帧率的视频流。
开启双流模式后,你可以在收流端调用 setRemoteVideoStreamType 选择接收视频大流或视频小流。
- 该方法适用于发送端发送的所有类型的流,包括且不限于来自摄像头采集的视频流、屏幕共享流、自定义采集的视频流。
- 如果需要在多频道场景下开启视频双流,可以调用 enableDualStreamModeEx 方法。
- 该方法可以在加入频道前后调用。
参数
- enabled
-
是否开启双流模式:
true
: 开启双流模式。false
: (默认) 关闭双流模式。
- streamConfig
-
视频小流的配置。详见 SimulcastStreamConfig。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
getConnectionStateEx
获取当前网络连接状态。
public abstract RtcConnection.CONNECTION_STATE_TYPE getConnectionStateEx( RtcConnection connection);
该方法在加入频道前后都能调用。
参数
- connection
- Connection 信息。详见 RtcConnection。
返回值
当前网络连接状态。
getUserInfoByUid
通过 UID 获取用户信息。
public abstract UserInfo getUserInfoByUid(int uid, String channelId, String localUserAccount);
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发 onUserInfoUpdated 回调。收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 UserInfo 对象。
参数
- uid
- 用户 ID。
- channelId
-
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- localUserAccount
- 本地用户的 User Account。
返回值
- 方法调用成功,返回 UserInfo 对象。
- 方法调用失败,则返回 NULL。
getUserInfoByUserAccount
通过 User Account 获取用户信息。
public abstract UserInfo getUserInfoByUserAccount(String userAccount, String channelId, String localUserAccount);
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发 onUserInfoUpdated 回调。收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 UserInfo 对象。
参数
- userAccount
- 用户 User Account。
- channelId
-
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- localUserAccount
- 本地用户的 User Account。
返回值
- 方法调用成功,返回 UserInfo 对象。
- 方法调用失败,则返回 NULL。
joinChannelEx
使用连接 ID 加入频道。
public abstract int joinChannelEx(String token, RtcConnection connection, ChannelMediaOptions options, IRtcEngineEventHandler eventHandler);
调用该方法,你可以同时加入多个频道。
- 如果你已经在一个频道内,你不能用相同的用户 UID 再次加入该频道。
- 如果你想在不同的设备上加入相同的频道,请确保你在不同设备上使用的用户 UID 都不同。
- 请确保生成 Token 时传入的 app ID 和创建 RtcEngine 实例时传入的 app ID 一致。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
- connection
- Connection 信息。详见 RtcConnection。
- options
- 频道媒体设置选项。详见 ChannelMediaOptions。
- eventHandler
- RtcEngineEx 的回调类,详见 IRtcEngineEventHandler。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,ChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:RtcEngine 对象初始化失败。你需要重新初始化 RtcEngine 对象。
- -7:RtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 RtcEngine 对象。
- -8:RtcEngine 对象内部状态错误。可能的原因是:调用 startEchoTest [2/2] 开始通话回路测试后,未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。Agora 推荐通过 onConnectionStateChanged 回调判断用户是否在频道中。除收到 CONNECTION_STATE_DISCONNECTED(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
joinChannelWithUserAccountEx
使用 User Account 加入频道,并设置是否自动订阅音频或视频流。
public abstract int joinChannelWithUserAccountEx(String token, String channelId, String userAccount, ChannelMediaOptions options, IRtcEngineEventHandler eventHandler);
- 本地:onLocalUserRegistered、onJoinChannelSuccess 和 onConnectionStateChanged 回调。
- 远端:通信场景下的用户和直播场景下的主播加入频道后,远端会分别触发 onUserJoined 和 onUserInfoUpdated 回调。
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。
参数
- 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
- RtcEngineEx 的回调类,详见 IRtcEngineEventHandler。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
leaveChannelEx
离开频道。
public abstract int leaveChannelEx(RtcConnection connection);
参数
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
muteRemoteAudioStreamEx
停止/恢复接收指定的音频流。
public abstract int muteRemoteAudioStreamEx(int uid, boolean muted, RtcConnection connection);
参数
- uid
- 指定用户的 ID。
- muted
-
是否停止接收指定音频流:
true
: 停止接收指定音频流。false
:(默认)继续接收指定音频流。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteRemoteVideoStreamEx
停止/恢复接收指定的视频流。
public abstract int muteRemoteVideoStreamEx(int uid, boolean muted, RtcConnection connection);
该方法停止/恢复接收某一个指定远端用户的视频流。在加入频道前或后都可以调用。该方法的设置在离开频道后失效。
参数
- uid
-
远端用户的 ID。
- muted
-
是否停止接收某个远端用户的视频:
true
: 停止接收。false
: (默认)恢复接收。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
pushExternalVideoFrameEx [1/2]
推送外部原始视频帧到 SDK。
public abstract int pushExternalVideoFrameEx(AgoraVideoFrame frame, int videoTrackId);
- 弃用:
- 该方法已废弃,请改用 pushExternalVideoFrameEx [2/2]。
调用 setExternalVideoSource 方法,设置 enabled 参数为 true
、encodedFrame 参数为 false
后,你可以调用本方法将未编码的外部视频帧推送到 SDK。
调用该方法或 pushExternalVideoFrameEx [2/2] 均能将视频帧数据传递给SDK。区别为 pushExternalVideoFrameEx [1/2] 方法不支持 texture 格式的视频数据。
参数
- frame
-
待推送的视频帧。详见 AgoraVideoFrame。
- videoTrackId
- 调用 createCustomVideoTrack 方法返回的视频轨道 ID。默认值为 0。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
pushExternalVideoFrameEx [2/2]
推送外部原始视频帧到 SDK。
public abstract int pushExternalVideoFrameEx(VideoFrame frame, int videoTrackId);
该方法主动将视频帧数据用 VideoFrame 类封装后传递给 SDK。请确保在你调用本方法前已调用 setExternalVideoSource, 并将参数 enable 设置为 true
,不然调用本方法后会一直报错。
调用该方法或 pushExternalVideoFrameEx [1/2] 均能将视频帧数据传递给SDK。区别为 pushExternalVideoFrameEx [2/2] 方法支持 texture 格式的视频数据。
参数
- frame
-
待推送的视频帧。详见 AgoraVideoFrame。
- videoTrackId
- 调用 createCustomVideoTrack 方法返回的视频轨道 ID。默认值为 0。
返回值
- 0: 推送成功。
- < 0: 推送失败。
sendCustomReportMessageEx
自定义数据上报和分析服务。
public abstract int sendCustomReportMessageEx( String id, String category, String event, String label, int value, RtcConnection connection);
声网提供自定义数据上报和分析服务。该服务当前处于免费内测期。内测期提供的能力为 6 秒内最多上报 10 条数据,每条自定义数据不能超过 256 字节,每个字符串不能超过 100 字节。如需试用该服务,请联系 sales@agora.io 开通并商定自定义数据格式。
sendStreamMessageEx
发送数据流。
public abstract int sendStreamMessageEx(int streamId, byte[] message, RtcConnection connection);
调用 createDataStreamEx [2/2] 后,你可以调用本方法向频道内所有用户发送数据流消息。
- 频道内每秒最多能发送 60 个包,且每个包最大为 1 KB。
- 每个客户端每秒最多能发送 30 KB 数据。
- 频道内每人最多能同时有 5 个数据通道。
成功调用该方法后,远端会触发 onStreamMessage 回调,远端用户可以在该回调中获取接收到的流消息; 若调用失败,远端会触发 onStreamMessageError 回调。
- 请确保在调用该方法前,已调用 createDataStreamEx [2/2] 创建了数据通道。
- 该方法仅适用于通信场景以及直播场景下的主播用户,如果直播场景下的观众调用此方法可能会造成观众变主播。
参数
- streamId
- 数据流 ID。可以通过 createDataStreamEx [2/2] 获取。
- message
- 待发送的数据。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setDualStreamModeEx
在发送端设置双流模式。
public abstract int setDualStreamModeEx(Constants.SimulcastStreamMode mode, SimulcastStreamConfig streamConfig, RtcConnection connection);
- 自从
- 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
设置远端视图显示模式。
public abstract int setRemoteRenderModeEx( int uid, int renderMode, int mirrorMode, RtcConnection connection);
- 请在调用 setupRemoteVideo 方法初始化远端视图后,调用该方法。
- 你可以在通话中多次调用该方法,多次更新远端用户视图的显示模式。
参数
- uid
- 远端用户 ID。
- renderMode
-
远端视图显示模式:
- RENDER_MODE_HIDDEN (1):优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,多出的视频将被截掉。
- RENDER_MODE_FIT (2):优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同,视窗上未被填满的区域将被涂黑。
- RENDER_MODE_ADAPTIVE (3): 该模式已废弃,不推荐使用。
- mirrorMode
-
远端用户视图的镜像模式:
- MIRROR_MODE_AUTO (0):默认的镜像模式(SDK 决定镜像模式)。如果你使用前置摄像头,默认启动本地视图镜像模式;如果你启用后置摄像头,默认关闭本地视图镜像模式。
- MIRROR_MODE_ENABLED (1):开启镜像模式。
- MIRROR_MODE_DISABLED (2):关闭镜像模式。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setRemoteVoicePositionEx
设置远端用户声音的 2D 位置,即水平面位置。
public abstract int setRemoteVoicePositionEx( int uid, double pan, double gain, RtcConnection connection);
设置远端用户声音的空间位置和音量,方便本地用户听声辨位。
通过调用该接口设置远端用户声音出现的位置,左右声道的声音差异会产生声音的方位感,从而判断出远端用户的实时位置。在多人在线游戏场景,如吃鸡游戏中,该方法能有效增加游戏角色的方位感,模拟真实场景。
- 为获得最佳听觉体验,我们建议用户佩戴有线耳机。
- 该方法需要在加入频道后调用。
参数
- 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: 方法调用失败
setSubscribeAudioBlacklistEx
设置音频订阅黑名单。
public abstract int setSubscribeAudioBlacklistEx(int[] uidList, RtcConnection connection);
你可以调用该方法指定不订阅的音频流。
- 该方法在加入频道前后均可调用。
- 音频订阅黑名单不受 muteRemoteAudioStream、muteAllRemoteAudioStreams 以及 ChannelMediaOptions 中的 autoSubscribeAudio 影响。
- 设置订阅黑名单后,如果离开当前频道后再重新加入频道,黑名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
订阅黑名单的用户 ID 列表。
如果你想指定不订阅某一发流用户的音频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅黑名单中移除,需要重新调用 setSubscribeAudioBlacklist 方法更新订阅黑名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeAudioWhitelistEx
设置音频订阅白名单。
public abstract int setSubscribeAudioWhitelistEx(int[] uidList, RtcConnection connection);
你可以调用该方法指定想要订阅的音频流。
- 该方法在加入频道前后均可调用。
- 音频订阅白名单不受 muteRemoteAudioStream、muteAllRemoteAudioStreams 以及 ChannelMediaOptions 中的 autoSubscribeAudio 的影响。
- 设置订阅白名单后,如果离开当前频道后再重新加入频道,白名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
音频订阅白名单的用户 ID 列表。
如果你想指定订阅某一发流用户的音频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅白名单中移除,需要重新调用 setSubscribeAudioWhitelist 方法更新音频订阅白名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeVideoBlacklistEx
设置视频订阅黑名单。
public abstract int setSubscribeVideoBlacklistEx(int[] uidList, RtcConnection connection);
你可以调用该方法指定不订阅的视频流。
- 该方法在加入频道前后均可调用。
- 视频订阅黑名单不受 muteRemoteVideoStream、muteAllRemoteVideoStreams 以及 ChannelMediaOptions 中的 autoSubscribeVideo 的影响。
- 设置订阅黑名单后,如果离开当前频道后再重新加入频道,黑名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
视频订阅黑名单的用户 ID 列表。
如果你想指定不订阅某一发流用户的视频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅黑名单中移除,需要重新调用 setSubscribeVideoBlacklist 方法更新订阅黑名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeVideoWhitelistEx
设置视频订阅白名单。
public abstract int setSubscribeVideoWhitelistEx(int[] uidList, RtcConnection connection);
你可以调用该方法指定想要订阅的视频流。
- 该方法在加入频道前后均可调用。
- 视频订阅白名单不受 muteRemoteVideoStream、muteAllRemoteVideoStreams 以及 ChannelMediaOptions 中的 autoSubscribeVideo 的影响。
- 设置订阅白名单后,如果离开当前频道后再重新加入频道,白名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
视频订阅白名单的用户 ID 列表。
如果你想指定仅订阅某一发流用户的视频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅白名单中移除,需要重新调用 setSubscribeVideoWhitelist 方法更新音频订阅白名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setupRemoteVideoEx
初始化远端用户视图。
public abstract int setupRemoteVideoEx(VideoCanvas remote, RtcConnection connection);
该方法绑定远端用户和显示视图,并设置远端用户视图在本地显示时的渲染模式和镜像模式,只影响本地用户看到的视频画面。
调用该方法时需要在 VideoCanvas 中指定远端视频的用户 ID,一般可以在进频道前提前设置好。
如果无法在加入频道前得到远端用户的 uid,可以在收到 onUserJoined 回调时调用该方法。如果启用了视频录制功能,视频录制服务会做为一个哑客户端加入频道,因此其他客户端也会收到它的 onUserJoined
事件, App 不应给它绑定视图(因为它不会发送视频流)。
如需解除某个远端用户的绑定视图,可以调用该方法并将 view 设置为空。
离开频道后,SDK 会清除远端用户视图的绑定关系。
如果你希望在通话中更新远端用户视图的渲染或镜像模式,请使用 setRemoteRenderModeEx 方法。
参数
- remote
-
视频画布信息。详见 VideoCanvas。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setVideoEncoderConfigurationEx
设置本地视频编码属性。
public abstract int setVideoEncoderConfigurationEx( VideoEncoderConfiguration config, RtcConnection connection);
每一种视频编码属性对应一系列视频相关参数设置,包含分辨率、帧率和码率。
该方法的 config 参数设置是在理想网络状态下能达到的最大值。如果网络状态不好,视频引擎便不能使用该 config 渲染本地视频, 它会自动降低到一个合适的视频参数设置。
参数
- config
- 视频编码参数配置。详见 VideoEncoderConfiguration。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
takeSnapshotEx
获取视频截图。
public abstract int takeSnapshotEx(RtcConnection connection, int uid, String filePath);
该方法用于对指定用户的视频流进行截图,生成一张 JPG 格式的图片,并保存至指定的路径。
该方法是异步操作,调用返回时 SDK 并没有真正获取截图。成功调用该方法后,SDK 会触发 onSnapshotTaken 回调报告截图是否成功和获取截图的详情。
- 该方法需要在调用 joinChannelEx 后调用。
- 该方法对 ChannelMediaOptions 中指定发布的视频流进行截图。
- 如果用户的视频经过前处理,例如,添加了水印或美颜,生成的截图会包含前处理效果。
参数
- connection
- Connection 信息。详见 RtcConnection。
- uid
- 用户 ID。如果要对本地用户的视频截图,则设为 0。
- filePath
-
截图的本地保存路径,需精确到文件名及格式, 例如:
- Android:
/storage/emulated/0/Android/data/<package name>/files/example.jpg
- Android:
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
updateChannelMediaOptionsEx
加入频道后更新频道媒体选项 。
public abstract int updateChannelMediaOptionsEx( ChannelMediaOptions options, RtcConnection connection);
参数
- options
- 频道媒体选项,详见 ChannelMediaOptions。
- connection
- Connection 信息。详见 RtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:ChannelMediaOptions 结构体成员值设置无效。例如,使用了不合法的 Token,设置了无效的用户角色。你需要填入有效的参数。
- -7:RtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 RtcEngine 对象。
- -8:RtcEngine 对象内部状态错误。可能的原因是用户不在频道中。Agora 推荐通过 onConnectionStateChanged 回调判断用户是否在频道中。如果收到 CONNECTION_STATE_DISCONNECTED(1) 或 CONNECTION_STATE_FAILED(5),则表示用户不在频道中。你需要在调用该方法前调用 joinChannel [2/2] 加入频道。