需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

视频渲染

  • macOS

更新时间不可用

enableInstantMediaRendering

启用音视频帧的极速渲染。

Objective-C
- (int)enableInstantMediaRendering NS_SWIFT_NAME(enableInstantMediaRendering());

自从

自 v4.1.1 版本新增。

调用该方法后，SDK 会启用极速帧渲染模式，从而加快你加入频道后首帧的渲染速度。

注： 主播和观众都需调用该方法，才能体验音视频帧的极速渲染。若需取消极速渲染，需调用 destroy 方法销毁 AgoraRtcEngineKit 对象。

适用场景

声网建议在直播场景中为观众开启该模式。

调用时机

请在加入频道前调用该方法。

返回值

  • 0：方法调用成功。

  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

setLocalRenderMode:mode:

设置本地视频显示模式。

Objective-C
- (int)setLocalRenderMode:(NSUInteger)uid
                     mode:(AgoraVideoRenderMode)mode NS_SWIFT_NAME(setLocalRenderMode(_:mode:)) __deprecated;

废弃

该方法已废弃。

你可以在通话过程中多次调用该方法以更改本地视频的显示模式。

参数

参数名描述
uid

用户 ID。

mode

本地视频显示模式，详见 AgoraVideoRenderMode。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

setLocalRenderMode:mirror:

更新本地视频视图的显示模式。

Objective-C
- (int)setLocalRenderMode:(AgoraVideoRenderMode)mode
                   mirror:(AgoraVideoMirrorMode)mirror NS_SWIFT_NAME(setLocalRenderMode(_:mirror:));

你可以在初始化本地视频视图后调用该方法，更新其渲染模式和镜像模式。该方法仅影响你本地看到的视频视图，不影响本地视频的发布。

注： 该方法仅对主摄像头（AgoraMediaSourceTypePrimaryCamera）生效。在使用自定义视频采集或其他视频源的场景中，应使用 setupLocalVideo: 方法替代。

调用时机

调用时序：

  • 请确保在调用该方法前已调用 setupLocalVideo: 方法初始化本地视频视图。
  • 通话过程中，你可以多次调用该方法更新本地视频视图的显示模式。

参数

参数名描述
mode

本地视频的显示模式，详见 AgoraVideoRenderMode。

mirror

本地视频视图的镜像模式，详见 AgoraVideoMirrorMode。如果使用前置摄像头，SDK 默认启用镜像模式；如果使用后置摄像头，SDK 默认关闭镜像模式。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

setLocalRenderTargetFps:targetFps:

设置本地视频渲染的最大帧率。

Objective-C
- (int)setLocalRenderTargetFps:(AgoraVideoSourceType)sourceType
                               targetFps:(int)targetFps;

在对视频渲染帧率要求不高的场景（如屏幕共享或在线教育）中，可以调用该方法设置本地视频渲染的最大帧率。SDK 会尝试将本地渲染的实际帧率保持在该值附近，从而降低 CPU 消耗并提升系统性能。

适用场景

在对视频渲染帧率要求不高的场景（如屏幕共享或在线教育）中，你可以调用该方法设置本地视频渲染的最大帧率。SDK 会尝试将本地渲染的实际帧率保持在该值附近，以降低 CPU 消耗并提升系统性能。

调用时机

你可以在加入频道前或后调用该方法。

参数

参数名描述
sourceType

视频源的类型，详见 AgoraVideoSourceType。

targetFps

本地视频的采集帧率（fps）。支持的取值包括：1、7、10、15、24、30、60。将该参数设置为低于实际视频帧率的值，否则设置不生效。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

setLocalVideoMirrorMode:

设置本地视频镜像模式。

Objective-C
- (int)setLocalVideoMirrorMode:(AgoraVideoMirrorMode)mode NS_SWIFT_NAME(setLocalVideoMirrorMode(_:)) __deprecated;

废弃

该方法已废弃。

参数

参数名描述
mode

本地视频镜像模式。详见 AgoraVideoMirrorMode。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

setRemoteRenderMode:mode:mirror:

更新远端用户视频视图的显示模式。

Objective-C
- (int)setRemoteRenderMode:(NSUInteger)uid
                      mode:(AgoraVideoRenderMode)mode
                    mirror:(AgoraVideoMirrorMode)mirror NS_SWIFT_NAME(setRemoteRenderMode(_:mode:mirror:));

初始化远端用户的视频视图后，你可以调用该方法更新其渲染模式和镜像模式。该方法仅影响本地用户看到的视频视图。

注：

  • 调用该方法前需先通过 setupRemoteVideo: 方法初始化远端视图。
  • 通话过程中，你可以多次调用该方法以更新远端用户视频视图的显示模式。

参数

参数名描述
uid

远端用户的用户 ID。

mode

远端用户视图的渲染模式，详见 AgoraVideoRenderMode。

mirror

远端用户视图的镜像模式，详见 AgoraVideoMirrorMode。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

setRemoteRenderModeEx:mode:mirror:connection:

设置指定远端用户的视频显示模式。

Objective-C
- (int)setRemoteRenderModeEx:(NSUInteger)uid
                        mode:(AgoraVideoRenderMode)mode
                      mirror:(AgoraVideoMirrorMode)mirror
                  connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(setRemoteRenderModeEx(_:mode:mirror:connection:));

你可以调用该方法更新远端用户的视频渲染模式和镜像模式。该方法仅影响你本地看到的远端用户视频视图。

注：

  • 请在调用 setupRemoteVideo: 方法初始化远端视图后调用该方法。
  • 通话过程中，你可以根据需要多次调用该方法更新远端用户视频视图的显示模式。

适用场景

该方法适用于多频道场景。

参数

参数名描述
uid

远端用户的用户 ID。

mode

远端用户的视频显示模式，详见 AgoraVideoRenderMode。

mirror

远端用户视图的镜像模式，详见 AgoraVideoMirrorMode。

connection

连接信息。详见 AgoraRtcConnection。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

setRemoteRenderTargetFps:

设置远端视频渲染的最大帧率。

Objective-C
- (int)setRemoteRenderTargetFps:(int)targetFps;

在视频渲染帧率要求不高的场景（例如屏幕共享、在线教育）或远端用户使用中低端设备的情况下，你可以调用该方法设置远端客户端的视频渲染最大帧率。SDK 会尽可能将实际渲染帧率控制在该值附近，从而降低 CPU 消耗并提升系统性能。

适用场景

在视频渲染帧率要求不高的场景（例如屏幕共享、在线教育）或远端用户使用中低端设备的情况下，你可以调用该方法设置远端客户端的视频渲染最大帧率。SDK 会尽可能将实际渲染帧率控制在该值附近，从而降低 CPU 消耗并提升系统性能。

调用时机

你可以在加入频道前或加入频道后调用该方法。

参数

参数名描述
targetFps

本地视频的采集帧率（fps）。支持的取值包括：1、7、10、15、24、30、60。将该参数设置为低于实际视频帧率的值，否则设置不生效。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

setRenderMode:

设置媒体播放器的渲染模式。

Objective-C
- (int)setRenderMode:(AgoraMediaPlayerRenderMode)mode NS_SWIFT_NAME(setRenderMode(_:));

参数

参数名描述
mode

视图的渲染模式，详见 AgoraMediaPlayerRenderMode。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

setupLocalVideo:

初始化本地视频画面。

Objective-C
- (int)setupLocalVideo:(AgoraRtcVideoCanvas * _Nullable)local NS_SWIFT_NAME(setupLocalVideo(_:));

该方法在本地设备上初始化本地视频流的画面，仅影响你本地看到的视频内容，不影响本地视频的发布。你可以调用该方法将本地视频流绑定到指定的视频画面（view），并设置画面的渲染模式和镜像模式。绑定关系在离开频道后仍然有效。如需停止渲染或解绑本地视频与画面，将 view 设为 nil 即可。

在实时互动场景中，如果你需要在本地视频预览中同时查看多个处于视频链路不同观察位置的预览画面，可以多次调用该方法，设置不同的 view，并为每个 view 设置不同的观察位置。例如，将视频源设置为摄像头后，配置两个 view，分别设置 position 为 AgoraVideoModulePositionPostCaptureOrigin 和 AgoraVideoModulePositionPostCapture，即可在本地视频预览中同时查看原始未处理的视频帧和经过美颜特效、虚拟背景、水印等预处理后的视频帧。

注： 若仅需在通话中更新本地视频画面的渲染模式或镜像模式，请调用 setLocalRenderMode:mirror: 方法。

适用场景

初始化后调用该方法设置本地视频，然后加入频道。在实时互动场景中，如需在本地预览中同时查看多个不同观察位置的画面，可多次调用该方法设置不同的 view 和观察位置。

调用时机

你可以在加入频道前或后调用该方法。

参数

参数名描述
local

本地视频画面及相关设置，详见 AgoraRtcVideoCanvas。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

setupRemoteVideo:

初始化远端用户的视频视图。

Objective-C
- (int)setupRemoteVideo:(AgoraRtcVideoCanvas * _Nonnull)remote NS_SWIFT_NAME(setupRemoteVideo(_:));

该方法在本地设备上初始化远端视频流的视频视图，仅影响你本地看到的视频画面。调用该方法可以将远端视频流绑定到指定视图，并设置该视图的渲染模式和镜像模式。你需要在该方法中指定远端用户 ID。如果你尚未获取远端用户 ID，请在收到 rtcEngine:didJoinedOfUid:elapsed: 回调后再设置。

若要解绑远端用户与视图的绑定关系，请将 view 参数设置为 nil。一旦远端用户离开频道，SDK 会自动解绑该用户。

在移动端进行合流视频自定义布局的场景中，你可以调用该方法，并为合流视频流中的每个子视频流设置独立的 view 进行渲染。

注：

  • 若需在通话过程中更新远端视频视图的渲染模式或镜像模式，请使用 setRemoteRenderMode 方法。
  • 使用录制服务时，应用无需绑定视图，因为录制服务不会发送视频流。如果你的应用无法识别录制服务，请在 SDK 触发 rtcEngine:firstRemoteVideoDecodedOfUid:size:elapsed: 回调时将远端用户绑定到视图。

参数

参数名描述
remote

远端视频视图及其相关设置，详见 AgoraRtcVideoCanvas。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

setupRemoteVideoEx:connection:

初始化远端用户的视频视图。

Objective-C
- (int)setupRemoteVideoEx:(AgoraRtcVideoCanvas* _Nonnull)remote
               connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(setupRemoteVideoEx(_:connection:));

该方法在本地设备上初始化远端视频流的视频视图，仅影响你所看到的远端视频画面。你可以调用该方法将远端视频流绑定到指定的视频视图，并设置渲染模式和镜像模式。

你需要在远端用户加入频道前，通过 AgoraRtcVideoCanvas 设置远端用户的 UID。如果你尚未获取远端用户的 UID，可在收到 didJoinedOfUid 回调后再设置。

如果启用了视频录制功能，录制服务会以虚拟客户端身份加入频道，其他客户端也会因此收到 onUserJoined 回调。请勿将该虚拟客户端绑定到应用视图，因为它不会发送任何视频流。

如需解绑远端用户与视图的绑定关系，请将 view 参数设为 nil。一旦远端用户离开频道，SDK 会自动解绑该用户。

注： 若需在通话过程中更新远端视频视图的渲染模式或镜像模式，请使用 setRemoteRenderModeEx 方法。

适用场景

该方法适用于多频道场景。

参数

参数名描述
remote

远端视频视图的设置。详见 AgoraRtcVideoCanvas。

connection

连接信息。详见 AgoraRtcConnection。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

0：方法调用成功。 < 0：方法调用失败。

所属接口类

startMediaRenderingTracing

启用视频帧渲染过程的追踪功能。

Objective-C
- (int)startMediaRenderingTracing NS_SWIFT_NAME(startMediaRenderingTracing());

自从

自 v4.1.1 版本新增。

从成功调用该方法开始，SDK 会追踪频道中视频帧的渲染状态，并通过 rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo: 回调报告相关事件信息。

注：

  • 如果你未调用该方法，SDK 会从调用 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 加入频道开始追踪视频帧的渲染事件。你可以根据实际应用场景在合适的时机调用该方法，以设置追踪视频渲染事件的起始位置。
  • 本地用户离开当前频道后，SDK 会自动从你加入频道的时刻开始追踪视频渲染事件。

适用场景

你可以结合应用中的 UI 设置（如按钮、滑块）调用该方法，以提升用户体验。例如，在用户点击“加入频道”按钮时调用该方法，然后通过 rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo: 回调获取视频帧渲染过程所耗费的时间，从而优化相关指标。

返回值

  • 0：方法调用成功。

  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

startMediaRenderingTracingEx:

启用视频帧渲染过程的追踪。

Objective-C
- (int)startMediaRenderingTracingEx:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(startMediaRenderingTracingEx(_:));

自从

自 v4.1.1 版本新增。

从成功调用该方法开始，SDK 会追踪频道中视频帧的渲染状态，并通过 rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo: 回调报告相关信息。

注：

  • 如果你未调用该方法，SDK 会从调用 joinChannelByToken 加入频道时开始追踪视频帧的渲染事件。你可以根据实际应用场景在合适的时机调用该方法，以设置追踪视频渲染事件的起始位置。
  • 本地用户离开当前频道后，SDK 会自动从你加入频道的时刻开始追踪视频渲染事件。

适用场景

该方法适用于多频道场景。

参数

参数名描述
connection

连接信息。详见 AgoraRtcConnection。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo:

视频帧渲染事件的回调。

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine videoRenderingTracingResultOfUid:(NSUInteger)uid currentEvent:(AgoraMediaTraceEvent)currentEvent tracingInfo:(AgoraVideoRenderingTracingInfo * _Nonnull)tracingInfo NS_SWIFT_NAME(rtcEngine(_:videoRenderingTracingResultOfUid:currentEvent:tracingInfo:));

调用 startMediaRenderingTracing 方法或加入频道后，SDK 会触发该回调，用于上报视频帧渲染的事件及渲染过程中的指标。你可以通过优化这些指标，提高首帧视频渲染的效率。

触发时机

该回调在调用 startMediaRenderingTracing 方法或加入频道后被触发。

参数

参数名描述
engine

AgoraRtcEngineKit 实例。详见 AgoraRtcEngineKit。

uid

用户 ID。

currentEvent

当前的视频帧渲染事件。详见 AgoraMediaTraceEvent。

tracingInfo

视频帧渲染过程中的指标信息。你需要尽可能降低这些指标的数值，以提高首帧视频渲染的效率。详见 AgoraVideoRenderingTracingInfo。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利