视频渲染
enableInstantMediaRendering
开启音视频帧加速渲染。
- (int)enableInstantMediaRendering NS_SWIFT_NAME(enableInstantMediaRendering());
成功调用该方法后,SDK 会开启加速出图和出声模式,可加快用户加入频道后的首帧出图与出声速度。
适用场景
声网推荐在直播场景下,对观众开启该模式。
调用时机
该方法需要在加入频道前调用。
调用限制
一旦成功调用该方法,只能通过调用 destroy 方法销毁 AgoraRtcEngineKit 对象来取消加速渲染。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
- -7: AgoraRtcEngineKit 尚未初始化就调用方法。
setLocalRenderMode:mode:
设置本地视图显示模式。
- (int)setLocalRenderMode:(NSUInteger)uid
mode:(AgoraVideoRenderMode) mode;
详情
该方法设置本地视图显示模式。 App 可以多次调用此方法更改显示模式。
参数
- mode
本地视图显示模式。详见 AgoraVideoRenderMode。
- uid
- 用户 ID。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setLocalRenderMode:mirror:
更新本地视图显示模式。
- (int)setLocalRenderMode:(AgoraVideoRenderMode)mode
mirror:(AgoraVideoMirrorMode)mirror;
初始化本地用户视图后,你可以调用该方法更新本地用户视图的渲染和镜像模式。该方法只影响本地用户看到的视频画面,不影响本地视频的发布。
调用时机
- 请在调用 setupLocalVideo: 方法初始化本地视图后,调用该方法。
- 你可以在通话中多次调用该方法,多次更新本地用户视图的显示模式。
调用限制
该方法仅对第一个摄像头 (AgoraMediaSourceTypePrimaryCamera)
生效。在自定义视频采集或使用其他类型视频源的场景下,你需要使用 setupLocalVideo: 方法替代该方法。
参数
- mode
本地视图显示模式。详见 AgoraVideoRenderMode。
- mirror
本地视图的镜像模式,详见 AgoraVideoMirrorMode。
注意如果你使用前置摄像头,默认启动本地用户视图镜像模式;如果你使用后置摄像头,默认关闭本地视图镜像模式。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setLocalRenderTargetFps
设置本地视频渲染的最大帧率。
public abstract int setLocalRenderTargetFps(Constants.VideoSourceType sourceType, int targetFps);
适用场景
在对视频渲染帧率要求不高的场景(例如:屏幕共享、在线教育)下,你可以调用该方法设置本地视频渲染的最大帧率,SDK 进行本地渲染的实际帧率会尽量接近该值,从而减小 CPU 消耗、提升系统性能。
调用时机
该方法在加入频道前后均可调用。
调用限制
无。
参数
- sourceType
- 视频源的类型,详见 AgoraVideoSourceType。
- targetFps
- 最大渲染帧率 (fps)。支持的参数值为:1、7、10、15、24、30、60。警告请将此参数设置为低于视频实际帧率的渲染帧率,否则设置将不会生效。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setLocalVideoMirrorMode:
设置本地视频镜像。
- (int)setLocalVideoMirrorMode:(AgoraVideoMirrorMode)mode;
详情
参数
- mode
本地视频镜像模式。详见 AgoraVideoMirrorMode。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setRemoteRenderMode:mode:mirror:
更新远端视图显示模式。
- (int)setRemoteRenderMode:(NSUInteger)uid
mode:(AgoraVideoRenderMode)mode
mirror:(AgoraVideoMirrorMode)mirror;
详情
初始化远端用户视图后,你可以调用该方法更新远端用户视图在本地显示时的渲染和镜像模式。该方法只影响本地用户看到的视频画面。
- 请在调用 setupRemoteVideo: 方法初始化远端视图后,调用该方法。
- 你可以在通话中多次调用该方法,多次更新远端用户视图的显示模式。
参数
- uid
- 远端用户 ID。
- mode
远端用户视图的渲染模式,详见 AgoraVideoRenderMode。
- mirror
远端用户视图的镜像模式,详见 AgoraVideoMirrorMode。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
setRemoteRenderModeEx:mode:mirror:connection:
设置远端视图显示模式。
- (int)setRemoteRenderModeEx:(NSUInteger)uid
mode:(AgoraVideoRenderMode)mode
mirror:(AgoraVideoMirrorMode)mirror
connection:(AgoraRtcConnection * _Nonnull)connection;
详情
- 请在调用 setupRemoteVideo: 方法初始化远端视图后,调用该方法。
- 你可以在通话中多次调用该方法,多次更新远端用户视图的显示模式。
参数
- uid
- 远端用户 ID。
- renderMode
远端视图显示模式,详见 AgoraVideoRenderMode。
- mirrorMode
远端用户视图的镜像模式,详见 AgoraVideoMirrorMode。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
setRemoteRenderTargetFps
设置视频在远端渲染的最大帧率。
- (int)setRemoteRenderTargetFps:(int)targetFps;
适用场景
在对视频渲染帧率要求不高的场景(例如:屏幕共享、在线教育)或者远端使用中低端设备的场景下,你可以调用该方法设置视频在远端渲染的最大帧率,SDK 进行远端视频渲染的实际帧率会尽量接近该值,从而减小 CPU 消耗、提升系统性能。
调用时机
该方法在加入频道前后均可调用。
调用限制
无。
参数
- targetFps
- 最大渲染帧率 (fps)。支持的参数值为:1、7、10、15、24、30、60。警告请将此参数设置为低于视频实际帧率的渲染帧率,否则设置将不会生效。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setRenderMode:
设置播放器视图的渲染模式。
- (void)setRenderMode:(AgoraMediaPlayerRenderMode)mode;
参数
- mode
播放器视图的渲染模式。详见 AgoraVideoRenderMode。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setupLocalVideo:
初始化本地视图。
- (int)setupLocalVideo:(AgoraRtcVideoCanvas * _Nullable)local;
该方法初始化本地视图并设置本地用户视频显示属性,只影响本地用户看到的视频画面,不影响本地视频的发布。调用该方法绑定本地视频流的显示视窗 (view),并设置本地用户视图的渲染模式和镜像模式。
退出频道后绑定仍然有效。如果需要停止渲染或解除绑定,可以调用该方法将参数 view 设为 nil,以停止渲染并清理渲染缓存。
- 如果你希望在通话中仅更新本地用户视图的渲染或镜像模式,请使用 setLocalRenderMode:mirror: 方法。
适用场景
在 App 开发中,通常在初始化后调用该方法进行本地视频设置,然后再加入频道。
如果你需要在本地视频预览的画面中同时看到多个预览画面、且不同画面分别处于视频链路上不同观测点,可以重复调用该方法设置不同的 view,并针对每个 view 设置不同的观测位置。例如:将视频源设置为摄像头,然后对应两个 view 分别设置 position 为 AgoraVideoModulePositionPostCaptureOrigin 和 AgoraVideoModulePositionPostCapture,即可在本地视频预览中同时看到没有经过视频前处理的原始画面和已经过视频前处理(美颜、虚拟背景、水印本地预览)的画面。
调用时机
该方法在加入频道前后均可调用。
调用限制
无。
参数
- local
- 本地视频显示属性。详见 AgoraRtcVideoCanvas。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
setupRemoteVideo:
初始化远端用户视图。
- (int)setupRemoteVideo:(AgoraRtcVideoCanvas * _Nonnull)remote;
详情
该方法绑定远端用户和显示视图,并设置远端用户视图在本地显示时的渲染模式和镜像模式,只影响本地用户看到的视频画面。
调用该方法时需要指定远端视频的用户 ID,一般可以在进频道前提前设置好。如果无法在加入频道前得到远端用户的 ID,可以在收到 rtcEngine:didJoinedOfUid:elapsed: 回调时调用该方法。
如需解除某个远端用户的绑定视图,可以调用该方法并将 view 设置为空。
离开频道后,SDK 会清除远端用户视图的绑定关系。
- 如果你希望在通话中更新远端用户视图的渲染或镜像模式,请使用 setRemoteRenderMode:mode:mirror: 方法。
- 当使用录制服务时,由于它不会发送视频流,App 无需为它绑定视图。如果 App 无法识别录制服务,可以在收到 rtcEngine:firstRemoteVideoDecodedOfUid:size:elapsed: 回调时再绑定远端用户视图。
参数
- remote
远端视频显示属性。详见 AgoraRtcVideoCanvas。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
setupRemoteVideoEx:connection:
初始化远端用户视图。
- (int)setupRemoteVideoEx:(AgoraRtcVideoCanvas* _Nonnull)remote
connection:(AgoraRtcConnection * _Nonnull)connection;
详情
该方法绑定远端用户和显示视图,并设置远端用户视图在本地显示时的渲染模式和镜像模式,只影响本地用户看到的视频画面。
调用该方法时需要在 AgoraRtcVideoCanvas 中指定远端视频的用户 ID,一般可以在进频道前提前设置好。
如果无法在加入频道前得到远端用户的 uid,可以在收到 rtcEngine:didJoinedOfUid:elapsed: 回调时调用该方法。如果启用了视频录制功能,视频录制服务会做为一个哑客户端加入频道,因此其他客户端也会收到它的 onUserJoined
事件, App 不应给它绑定视图(因为它不会发送视频流)。
如需解除某个远端用户的绑定视图,可以调用该方法并将 view 设置为空。
离开频道后,SDK 会清除远端用户视图的绑定关系。
- 如果你希望在通话中更新远端用户视图的渲染或镜像模式,请使用 setRemoteRenderModeEx:mode:mirror:connection: 方法。
参数
- remote
视频画布信息。详见 AgoraRtcVideoCanvas。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
startMediaRenderingTracing
开启视频帧渲染数据打点。
- (int)startMediaRenderingTracing NS_SWIFT_NAME(startMediaRenderingTracing());
详情
成功调用该方法后,SDK 会以调用该方法的时刻作为起点,并通过 rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo: 回调报告视频帧渲染的相关信息。
- SDK 默认在成功加入频道的时刻起打点,自动开始跟踪视频频的渲染事件。你可以根据实际业务场景,在合适的时机调用该方法,进行自定义打点。
- 离开当前频道后,SDK 会自动重置该时间点为下一次成功加入频道的时刻。
适用场景
声网推荐你将该方法和 App 中的 UI 设置(按钮、滑动条等)结合使用,用于针对终端用户的体验改进。例如:在终端用户在点击 加入频道
按钮的时刻调用该方法进行打点,然后通过 rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo: 回调获取视频帧渲染过程中的指标,从而针对指标进行专项优化。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
- -7: AgoraRtcEngineKit 尚未初始化就调用方法。
startMediaRenderingTracingEx:
开启视频帧渲染数据打点。
- (int)startMediaRenderingTracingEx:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(startMediaRenderingTracingEx(_:));
详情
成功调用该方法后,SDK 会以调用该方法的时刻作为起点,并通过 rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo: 回调报告视频帧渲染的相关信息。
- SDK 默认在成功加入频道的时刻起打点,自动开始跟踪视频频的渲染事件。你可以根据实际业务场景,在合适的时机调用该方法,进行自定义打点。
- 离开当前频道后,SDK 会自动重置该时间点为下一次成功加入频道的时刻。
适用场景
声网推荐你将该方法和 App 中的 UI 设置(按钮、滑动条等)结合使用,用于针对终端用户的体验改进。例如:在终端用户在点击 加入频道
按钮的时刻调用该方法进行打点,然后通过 rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo: 回调获取视频帧渲染过程中的指标,从而针对指标进行专项优化。
参数
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo:
视频帧渲染事件回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine videoRenderingTracingResultOfUid:(NSUInteger)uid currentEvent:(AgoraMediaRenderTraceEvent)currentEvent tracingInfo:(AgoraVideoRenderingTracingInfo * _Nonnull)tracingInfo NS_SWIFT_NAME(rtcEngine(_:videoRenderingTracingResultOfUid:currentEvent:tracingInfo:));
详情
调用 startMediaRenderingTracing 方法或加入频道后,SDK 会触发该回调,报告视频帧渲染的事件和渲染过程中的指标。开发者可以针对指标进行专项优化,以提高出图效率。
参数
- uid
- 用户 ID。
- currentEvent
- 当前视频帧渲染事件。详见 AgoraMediaTraceEvent。
- tracingInfo
- 视频帧渲染过程中的指标。开发者需要尽可能降低指标值,以提高出图效率。详见 AgoraVideoRenderingTracingInfo。