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

URL 拉流播放

  • macOS

更新时间不可用

addView:config:error:

添加一个渲染视图。

Objective-C
- (BOOL)addView:(AgoraRteView * _Nonnull)view config:(AgoraRteViewConfig* _Nullable)config error:(AgoraRteError* _Nullable)error;

自从

自 v4.4.0 版本新增。

你可以调用该方法将视图添加到视频渲染器中，以显示视频内容。

注： 当前仅支持一个视图。

适用场景

当你需要使用播放器播放视频时，可以调用此方法将视图添加到视频渲染器中，以显示视频内容。

调用时机

你必须在调用 setCanvas:error: 之前调用此方法。

参数

参数名描述
view

视图对象的指针。

  • iOS：一个 UIView 对象。
  • macOS：一个 NSView 对象。
config

视图对象的配置。当前请传入 nil。

error

状态或错误信息，详见 AgoraRteError。

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

返回值

  • YES：添加视图成功。
  • NO：添加视图失败。

所属接口类

initWithRte:initialConfig:

构造一个 AgoraRteCanvas 对象。

Objective-C
- (instancetype _Nonnull)initWithRte:(AgoraRte* _Nonnull)rte initialConfig:(AgoraRteCanvasInitialConfig * _Nullable)config;

自从

自 v4.4.0 版本新增。

参数

参数名描述
rte

用于构造 AgoraRteCanvas 的 AgoraRte 对象。详见 AgoraRte。

config

用于初始化的配置对象。你可以传入 nil。

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

所属接口类

code

获取 API 调用返回的错误码。

Objective-C
- (AgoraRteErrorCode)code;

自从

自 v4.4.0 版本新增。

当 API 调用失败时，你可以调用该方法获取错误码。

调用时机

当 API 调用失败时，你可以调用该方法获取错误码。

返回值

方法调用成功时，返回错误码，详见 AgoraRteErrorCode。

所属接口类

destroy:

销毁 RTE 对象。

Objective-C
- (BOOL)destroy:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

该方法会释放 RTE 对象使用的所有资源。

参数

参数名描述
error

状态或错误信息，详见 AgoraRteError。

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

返回值

  • YES：销毁成功。
  • NO：销毁失败。

所属接口类

abrFallbackLayer:

获取已配置的视频流分层回退选项。

Objective-C
- (AgoraRteAbrFallbackLayer)abrFallbackLayer:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

调用时机

你必须在调用 getConfigs:error: 之后调用此方法。

参数

参数名描述
error

状态或错误信息，详见 AgoraRteError。

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

返回值

已配置的视频流分层回退选项，详见 AgoraRteAbrFallbackLayer。

所属接口类

abrSubscriptionLayer:

获取订阅端视频流的质量层级。

Objective-C
- (AgoraRteAbrSubscriptionLayer)abrSubscriptionLayer:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

调用时机

你必须在调用 getConfigs:error: 之后调用此方法。

参数

参数名描述
error

状态或错误信息，详见 AgoraRteError。

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

返回值

当前设置的视频质量层级，详见 AgoraRteAbrSubscriptionLayer。

所属接口类

appId:

获取你已设置的声网 App ID。

Objective-C
- (NSString* _Nullable)appId:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

参数

参数名描述
error

错误信息对象，可能返回以下错误码，详见 AgoraRteErrorCode：

  • AgoraRteOk：调用成功。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 方法调用成功时，返回你已设置的声网 App ID。
  • 方法调用失败时，返回空字符串。

所属接口类

autoPlay:

获取媒体播放器的自动播放设置。

Objective-C
- (BOOL)autoPlay:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

你可以调用此方法获取媒体播放器当前的自动播放设置。

注： 必须在调用 getConfigs:error: 方法之后调用。

调用时机

必须在调用 getConfigs:error: 方法之后调用。

参数

参数名描述
error

状态或错误信息。详见 AgoraRteError。

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

返回值

是否成功获取自动播放设置：

  • YES：获取成功。
  • NO：获取失败。

所属接口类

getConfigs:error:

获取当前播放器的视频渲染配置。

Objective-C
- (BOOL)getConfigs:(AgoraRteCanvasConfig* _Nonnull)config error:(AgoraRteError* _Nullable)error;

自从

自 v4.4.0 版本新增。

调用时机

你需要在调用 initWithRte:initialConfig: 方法之后调用该方法。

参数

参数名描述
config

视频画布配置，详见 AgoraRteCanvasConfig。

error

状态或错误信息，详见 AgoraRteError。

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

返回值

  • YES：获取成功。
  • NO：获取失败。

所属接口类

getConfigs:error:

获取当前媒体播放器配置选项。

Objective-C
- (BOOL)getConfigs:(AgoraRtePlayerConfig * _Nonnull)config error:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

调用时机

你必须在调用 initWithRte:initialConfig: 之后调用此方法。

参数

参数名描述
config

媒体播放器配置选项，详见 AgoraRtePlayerConfig。

error

状态或错误信息，详见 AgoraRteError。

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

返回值

  • YES：获取成功。
  • NO：获取失败。

所属接口类

getConfigs:error:

获取 RTE 对象的配置信息。

Objective-C
- (BOOL)getConfigs:(AgoraRteConfig *_Nonnull)config error:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

调用时机

你必须在调用 initWithInitialConfig: 之后调用该方法。

参数

参数名描述
config

RTE 对象的配置信息。详见 AgoraRteConfig。

error

状态或错误信息。详见 AgoraRteError。

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

返回值

  • YES：获取成功。
  • NO：获取失败。

所属接口类

getFromBridge:

桥接一个来自 AgoraRtcEngineKit 的 RTE 对象。

Objective-C
+ (instancetype _Nonnull)getFromBridge:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

通过调用此方法创建的 RTE 对象无需通过 initMediaEngine:error: 进行初始化。如果你尚未创建并初始化 RTC 引擎，可以先调用 AgoraRte 创建一个 RTE 对象，然后使用 initMediaEngine:error: 进行初始化。

调用时机

在调用此方法之前，请确保你已通过调用 sharedEngineWithConfig:delegate: 初始化 RTC 引擎。

参数

参数名描述
error

用于接收状态和错误码的指针，详见 AgoraRteError。

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

返回值

方法调用成功，返回一个 RTE 对象，详见 AgoraRte。

所属接口类

getInfo:error:

获取播放器播放和媒体流相关的信息。

Objective-C
- (BOOL)getInfo:(AgoraRtePlayerInfo * _Nonnull)info error:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

你可以使用该方法获取播放器和媒体流相关的信息，例如音频采样率和视频帧尺寸。

注： 你必须在调用 initWithRte:initialConfig: 之后调用此方法。

参数

参数名描述
info

播放器和媒体流相关的信息。详见 AgoraRtePlayerInfo。

error

状态或错误信息。详见 AgoraRteError。

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

返回值

  • YES：成功获取信息。
  • NO：获取信息失败。

所属接口类

jsonParameter:

获取当前配置的 RTE 私有参数。

Objective-C
- (NSString * _Nullable)jsonParameter:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

参数

参数名描述
error

状态或错误信息。详见 AgoraRteError。

  • AgoraRteOk：调用成功。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 方法调用成功时，返回已设置的 JSON 格式参数集。
  • 方法调用失败时，返回空字符串。

所属接口类

loopCount:

获取媒体文件的循环次数参数。

Objective-C
- (int32_t)loopCount:(AgoraRteError * _Nullable)error;

自从

自 v4.5.1 版本新增。

参数

参数名描述
error

输出参数，用于指示错误信息，详见 AgoraRteError。

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

返回值

方法调用成功时，返回媒体文件的循环次数。

所属接口类

videoMirrorMode:

获取当前设置的镜像模式。

Objective-C
- (AgoraRteVideoMirrorMode)videoMirrorMode:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

调用时机

你必须在调用 getConfigs:error: 之后调用此方法。

参数

参数名描述
error

状态或错误信息，详见 AgoraRteError。

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

返回值

当前设置的镜像模式，详见 AgoraRteVideoMirrorMode。

所属接口类

playbackSpeed:

获取播放速度参数。

Objective-C
- (int32_t)playbackSpeed:(AgoraRteError * _Nullable)error;

自从

自 v4.5.1 版本新增。

参数

参数名描述
error

输出参数，用于指示错误信息，详见 AgoraRteError。

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

返回值

方法调用成功时，返回播放速度的值。

所属接口类

playoutVolume:

获取媒体播放器的播放音量。

Objective-C
- (int32_t)playoutVolume:(AgoraRteError * _Nullable)error;

自从

自 v4.5.1 版本新增。

参数

参数名描述
error

输出参数，用于返回错误信息，详见 AgoraRteError。

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

返回值

方法调用成功，返回媒体播放器的播放音量。

所属接口类

getPosition:

获取当前播放位置。

Objective-C
- (uint64_t)getPosition:(AgoraRteError * _Nullable)error;

自从

自 v4.5.1 版本新增。

该方法用于获取当前播放的时间位置，单位为毫秒。

参数

参数名描述
error

输出参数，用于指示错误信息。可能的返回值包括：

  • AgoraRteOk：调用成功。

  • AgoraRteErrorInvalidOperation：

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

返回值

方法调用成功时，返回当前播放位置，单位为毫秒。

所属接口类

videoRenderMode:

获取当前设置的视频渲染模式。

Objective-C
- (AgoraRteVideoRenderMode)videoRenderMode:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

调用时机

你需要在调用 getConfigs:error: 之后调用此方法。

参数

参数名描述
error

状态或错误信息。详见 AgoraRteError。

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

返回值

当前设置的视频渲染模式。详见 AgoraRteVideoRenderMode。

所属接口类

getStats:

获取播放器当前播放媒体资源的统计信息。

Objective-C
- (void)getStats:(void (^_Nonnull)(AgoraRtePlayerStats* _Nonnull stats, AgoraRteError* _Nullable err))cb;

自从

自 v4.4.0 版本新增。

该方法用于获取播放器的统计信息，并通过回调函数异步返回结果。统计信息包括解码和渲染帧率、音视频码率等。

注： 你必须在调用 openWithUrl:startTime:cb: 方法之后再调用此方法。

参数

参数名描述
cb

一个异步回调函数，用于通知你播放器媒体资源统计信息的获取结果以及任何错误信息。该函数包含以下参数：

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

所属接口类

initMediaEngine:error:

初始化 RTE 引擎。

Objective-C
- (BOOL)initMediaEngine:(void (^ _Nullable)(AgoraRteError* _Nullable err) )cb error:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

该方法为异步方法，通过回调函数返回初始化结果。你需要在创建 RTE 对象并设置 App ID 后调用该方法。

注： 该返回值仅表示初始化操作是否已成功加入异步任务队列，并不表示初始化是否成功。

调用时机

你需要在创建 RTE 对象并设置 App ID 后调用该方法。

参数

参数名描述
cb

用于返回引擎初始化结果的异步回调函数。你可以通过该回调的 err 参数判断引擎初始化的结果或错误码。详见 AgoraRteError。

error

初始化过程中发生的错误信息。当调用 initMediaEngine:error: 方法进行初始化时，如果发生可立即检测的错误（如参数无效或资源不足），SDK 会通过该参数同步返回错误信息。详见 AgoraRteError。

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

返回值

  • YES：异步操作成功加入队列。
  • NO：异步操作未能加入队列。

该返回值仅表示初始化操作是否已成功加入异步任务队列，并不表示初始化是否成功。

所属接口类

message

获取详细错误信息。

Objective-C
- (NSString * _Nullable)message;

自从

自 v4.4.0 版本新增。

调用时机

当 API 调用失败时，你可以调用此方法获取错误信息，以帮助排查问题。

返回值

  • 方法调用成功时，返回错误信息字符串。
  • 方法调用失败时，返回空字符串。

所属接口类

muteAudio:error:

开始或停止接收音频流。

Objective-C
- (BOOL)muteAudio:(BOOL)mute error:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

调用时机

你必须在调用 openWithUrl:startTime:cb: 之后调用此方法。

相关回调

调用该方法成功后，会触发 onPlayerInfoUpdated: 回调以上报最新的播放器和媒体流信息。

参数

参数名描述
mute

是否接收音频流：

  • YES：不接收音频流。
  • NO：接收音频流。
error

输出参数，状态或错误信息，详见 AgoraRteError。

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

返回值

  • YES：操作成功。
  • NO：操作失败。

所属接口类

muteVideo:error:

开始或停止接收远端视频流。

Objective-C
- (BOOL)muteVideo:(BOOL)mute error:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

调用时机

你必须在调用 openWithUrl:startTime:cb: 之后调用此方法。

相关回调

调用该方法成功后，会触发 onPlayerInfoUpdated: 回调以上报最新的播放器和媒体流信息。

参数

参数名描述
mute

是否接收远端视频流：

  • YES：不接收远端视频流。
  • NO：接收远端视频流。
error

状态或错误信息，详见 AgoraRteError。

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

返回值

  • YES：操作成功。
  • NO：操作失败。

所属接口类

openWithUrl:startTime:cb:

打开一个 URL 资源。

Objective-C
- (void)openWithUrl:(NSString * _Nonnull)url startTime:(uint64_t)startTime cb:(void (^_Nullable)(AgoraRteError* _Nullable err))cb;

自从

自 v4.4.0 版本新增。

该方法支持通过 URL 打开实时流媒体资源。若希望加快打开 URL 资源的速度，可以在调用该方法前先调用 preloadWithUrl:error: 预加载资源。

注： 该方法目前仅支持打开以 rte:// 开头的 URL、CDN 推流 URL 和本地媒体文件。

调用时机

该方法必须在调用 initWithRte:initialConfig: 之后调用。

相关回调

成功调用该方法后，SDK 会触发 onStateChanged:newState:error: 回调报告播放器连接状态为 AgoraRtePlayerStateOpening，表示正在打开 URL。打开成功后，播放器连接状态会报告为 AgoraRtePlayerStateOpenCompleted。如果资源打开失败，会收到 onStateChanged:newState:error: 回调，报告连接状态为 AgoraRtePlayerStateFailed。此时需先调用 pause:，再调用 openWithUrl:startTime:cb: 重新打开 URL 资源。如果已关闭自动播放，可在资源打开后调用 play: 开始播放。

参数

参数名描述
url

要打开的 URL，可以是 CDN 推流 URL、本地媒体文件，或以 rte:// 为前缀的 URL。关于 RTE URL 各字段的详细信息，详见 观众端 URL 拉流。

startTime

起始播放位置，单位为毫秒。

cb

异步通知打开 URL 资源结果的回调。你可以通过该回调的 err 参数得知操作的结果或错误码信息，详见 AgoraRteError。

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

所属接口类

pause:

暂停播放。

Objective-C
- (BOOL)pause:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

调用 play: 播放 URL 资源后，如果你希望暂停播放，可以调用该方法。如果你希望停止播放，请调用 pause:。你必须在调用 play: 之后调用该方法。

调用时机

你必须在调用 play: 之后调用该方法。

参数

参数名描述
error

状态或错误信息，详见 AgoraRteError。

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

返回值

  • YES：暂停播放成功。
  • NO：暂停播放失败。

所属接口类

play:

播放一个以 rte:// 开头的 URL 资源。

Objective-C
- (BOOL)play:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

如果你已关闭自动播放，在使用 openWithUrl:startTime:cb: 成功打开直播流后，可以调用此方法开始播放。

调用时机

仅在收到 onStateChanged:newState:error: 回调并报告状态为 AgoraRtePlayerStateOpenCompleted 后调用此方法。

参数

参数名描述
error

连接状态或错误信息，详见 AgoraRteError。

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

返回值

  • YES：播放成功。
  • NO：播放失败。

所属接口类

initWithRte:initialConfig:

构造一个播放器对象。

Objective-C
- (instancetype _Nonnull)initWithRte:(AgoraRte * _Nonnull)rte initialConfig:(AgoraRtePlayerInitialConfig * _Nullable)config;

自从

自 v4.4.0 版本新增。

调用时机

你必须在调用 initMediaEngine:error: 之后调用此方法。

参数

参数名描述
rte

一个 AgoraRte 对象，详见 AgoraRte。

config

播放器对象的初始化设置。你可以传入 nil。

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

所属接口类

preloadWithUrl:error:

预加载 URL 资源。

Objective-C
+ (BOOL)preloadWithUrl:(NSString * _Nonnull)url error:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

你可以在调用 openWithUrl:startTime:cb: 之前调用该方法，成功预加载 URL 资源后，可以更快地通过 openWithUrl:startTime:cb: 打开该资源，从而减少等待时间，提升视听体验的流畅度。

注： 该方法当前仅对以 rte:// 为前缀的 URL 生效。最多可预加载 20 个 URL，若超过限制，最新预加载的 URL 会替换最早的 URL。

适用场景

在打开媒体资源前预加载，可以减少用户等待时间，提供更流畅的视听体验。

参数

参数名描述
url

以 rte:// 为前缀的 URL。

error

状态或错误信息，详见 AgoraRteError。

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

返回值

  • YES：预加载成功。
  • NO：预加载失败。

所属接口类

registerObserver:error:

注册一个播放器观察者对象。

Objective-C
- (BOOL)registerObserver:(AgoraRtePlayerObserver *_Nonnull)observer error:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

在调用此方法之前，你需要实现一个继承自 AgoraRtePlayerObserver 的接口类。你必须在调用 initWithRte:initialConfig: 之后再调用此方法。

参数

参数名描述
observer

接口对象实例，详见 AgoraRtePlayerObserver。

error

状态或错误信息，详见 AgoraRteError。

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

返回值

  • YES：注册成功。
  • NO：注册失败。

所属接口类

removeView:config:error:

移除一个渲染视图。

Objective-C
- (BOOL)removeView:(AgoraRteView * _Nonnull)view config:(AgoraRteViewConfig* _Nullable)config error:(AgoraRteError* _Nullable)error;

自从

自 v4.4.0 版本新增。

调用 addView:config:error: 方法添加视图后，可以调用该方法移除渲染视图。

注： 每次只能移除一个视图。

调用时机

必须在调用 addView:config:error: 方法之后调用。

参数

参数名描述
view

要移除的视图对象，详见 AgoraRteView。

config

视图对象的配置。目前传入 nil。

error

状态或错误信息，详见 AgoraRteError。

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

返回值

  • YES：视图移除成功。
  • NO：视图移除失败。

所属接口类

initWithInitialConfig:

构造一个 RTE 对象。

Objective-C
- (instancetype _Nonnull)initWithInitialConfig:(AgoraRteInitialConfig * _Nullable)config;

自从

自 v4.4.0 版本新增。

RTE 对象用于组织和管理 RTE 的内部资源。你必须在调用 initMediaEngine:error: 方法之前调用此方法。

调用时机

你必须在调用 initMediaEngine:error: 方法之前调用此方法。

参数

参数名描述
config

初始化设置。你可以传入 nil。

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

返回值

  • 方法调用成功，返回 RTE 对象。
  • 方法调用失败，返回 nil。

所属接口类

seek:error:

跳转到指定的播放位置。

Objective-C
- (BOOL)seek:(uint64_t)newTime error:(AgoraRteError * _Nullable)error;

自从

自 v4.5.1 版本新增。

参数

参数名描述
newTime

要跳转到的播放位置。

error

输出参数，用于在跳转操作失败时返回错误信息。详见 AgoraRteError。

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

返回值

  • YES：跳转成功。
  • NO：跳转失败。

所属接口类

setAbrFallbackLayer:error:

设置已订阅远端视频流的分层推流回退选项。

Objective-C
- (void)setAbrFallbackLayer:(AgoraRteAbrFallbackLayer)layer error:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

在网络条件较差时，实时音视频通信的质量可能会下降。调用该方法后，SDK 会在网络变差时将远端视频流的分辨率回退到指定的视频质量层级。每个视频质量层级对应特定的分辨率和码率。SDK 会持续监测网络质量，在网络改善时恢复到原始订阅的视频质量层级。

默认情况下，调用该方法后只能选择回退到 AgoraRteAbrFallbackLow 或 AgoraRteAbrFallbackAudioOnly。如果你对视频体验有更高要求，可以联系技术支持开启 ABR 功能。开启后，可以回退到所有视频质量层级，并自定义每个层级的分辨率。

注： 如果未开启 ABR 功能，远端视频流的回退质量层级只能设置为 AgoraRteAbrFallbackLow 或 AgoraRteAbrFallbackAudioOnly。

适用场景

一般场景下，可调用该方法并将回退质量层设置为 kRteAbrFallbackLow 或 kRteAbrFallbackAudioOnly。当网络较差时，SDK 会回退为视频小流或仅接收音频流。 如果对回退视频流的分辨率有更高要求，可联系技术支持开启 ABR 功能。开启后，可自定义每一层的分辨率。SDK 会以你指定的最低质量层的分辨率为下限，并根据网络状况在该范围内动态调整分辨率。

调用时机

必须在调用 setConfigs:error: 之前调用该方法。

参数

参数名描述
layer

回退的视频质量层级。可选值详见 AgoraRteAbrFallbackLayer。当自定义 AgoraRteAbrFallbackLayer1 到 AgoraRteAbrFallbackLayer6 的分辨率时，可参考下表或根据实际需求定义：

注： 自定义分辨率时，必须按从高到低的分辨率顺序排列视频质量层级。如果两个层级的分辨率相同，则按帧率从高到低排序。

视频质量层级分辨率
AgoraRteAbrSubscriptionLayer12160p (4K)
AgoraRteAbrSubscriptionLayer21440p (2K)
AgoraRteAbrSubscriptionLayer31080p (HD)
AgoraRteAbrSubscriptionLayer4720p (HD)
AgoraRteAbrSubscriptionLayer5540p (SD)
AgoraRteAbrSubscriptionLayer6480p (SD)
表格内容超出当前宽度，可横向滚动查看更多列。

自定义分辨率时，必须按从高到低的分辨率顺序排列视频质量层级。如果两个层级的分辨率相同，则按帧率从高到低排序。详见 AgoraRteAbrFallbackLayer。

error

状态或错误信息。详见 AgoraRteError。

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

所属接口类

setAbrSubscriptionLayer:error:

设置订阅端媒体流的视频质量层级。

Objective-C
- (void)setAbrSubscriptionLayer:(AgoraRteAbrSubscriptionLayer)layer error:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

你可以根据实际的网络状况，在多质量层级视频流中切换不同的视频质量层级，每个层级对应不同的分辨率。默认情况下，调用该方法后，观众只能在高、低两个视频流之间切换，即 AgoraRteAbrSubscriptionHigh 和 AgoraRteAbrSubscriptionLow。如果你需要更高级的分辨率切换功能，可以联系技术支持开启 ABR（自适应码率）功能。开启后，你可以自定义每个视频质量层级的分辨率，观众可以根据需要在所有可用的视频质量层级之间切换。

注： 如果在调用该方法时未开启 ABR 功能，订阅的视频质量层级只能设置为 AgoraRteAbrSubscriptionHigh 或 AgoraRteAbrSubscriptionLow。

适用场景

在网络环境不稳定的场景中，订阅端可根据实际网络状况选择合适的视频质量层级，以保障流畅的观看体验。

调用时机

你必须在调用 setConfigs:error: 之前调用该方法。

参数

参数名描述
layer

要订阅的视频质量层级。你可以自定义 AgoraRteAbrSubscriptionLayer1 到 AgoraRteAbrSubscriptionLayer6 的分辨率，参考如下建议，或根据实际需求定义：

注意：自定义分辨率时，请确保视频质量层级按分辨率从高到低排序；如果分辨率相同，则按帧率从高到低排序。

视频质量层级分辨率
AgoraRteAbrSubscriptionLayer12160p (4K)
AgoraRteAbrSubscriptionLayer21440p (2K)
AgoraRteAbrSubscriptionLayer31080p (HD)
AgoraRteAbrSubscriptionLayer4720p (HD)
AgoraRteAbrSubscriptionLayer5540p (SD)
AgoraRteAbrSubscriptionLayer6480p (SD)
表格内容超出当前宽度，可横向滚动查看更多列。

详见 AgoraRteAbrSubscriptionLayer。

error

状态或错误信息。详见 AgoraRteError。

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

所属接口类

setAppId:error:

设置声网 App ID。

Objective-C
- (void)setAppId:(NSString * _Nullable)appId error:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

调用时机

你必须在调用 initMediaEngine:error: 之前调用此方法。

参数

参数名描述
appId

项目的声网 App ID，可从控制台获取。

error

状态或错误信息，详见 AgoraRteError。

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

所属接口类

setAutoPlay:error:

设置是否启用自动播放。

Objective-C
- (void)setAutoPlay:(BOOL)autoPlay error:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

你可以在调用 openWithUrl:startTime:cb: 之前调用此方法设置是否启用自动播放。如果未设置，默认启用自动播放。

注： 该方法必须在调用 openWithUrl:startTime:cb: 之前调用。

调用时机

该方法必须在调用 openWithUrl:startTime:cb: 之前调用。

参数

参数名描述
autoPlay

是否启用自动播放：

  • YES：（默认）启用自动播放。
  • NO：不启用自动播放。
error

状态或错误信息，详见 AgoraRteError。

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

所属接口类

setCanvas:error:

设置用于显示视频的视图窗口。

Objective-C
- (BOOL)setCanvas:(AgoraRteCanvas *_Nonnull)canvas error:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

该方法用于设置用于显示视频的视图窗口。在视频流成功开始播放后，视频将渲染在指定的 canvas 上。

注： 你必须在调用 initWithRte:initialConfig: 之后调用此方法。

参数

参数名描述
canvas

用于渲染视频帧的视图窗口。详见 AgoraRteCanvas。

error

状态或错误信息。详见 AgoraRteError。

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

返回值

  • YES：设置成功。
  • NO：设置失败。你可以通过 error 参数返回的错误码获取详细信息。

所属接口类

setConfigs:error:

设置播放器的视频渲染配置。

Objective-C
- (BOOL)setConfigs:(AgoraRteCanvasConfig* _Nonnull)config error:(AgoraRteError* _Nullable)error;

自从

自 v4.4.0 版本新增。

调用时机

你必须在调用 openWithUrl:startTime:cb: 之前调用此方法。

参数

参数名描述
config

Canvas 对象的设置，详见 AgoraRteCanvasConfig。

error

状态或错误信息，详见 AgoraRteError。

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

返回值

  • YES：配置成功。
  • NO：配置失败。

所属接口类

setConfigs:error:

配置播放器参数。

Objective-C
- (BOOL)setConfigs:(AgoraRtePlayerConfig * _Nonnull)config error:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

你可以调用此方法配置播放器，例如启用自动播放、订阅不同分辨率和码率的视频流。

注： 必须在调用 initWithRte:initialConfig: 之后调用此方法。

参数

参数名描述
config

播放器配置对象。详见 AgoraRtePlayerConfig。

error

状态或错误信息。详见 AgoraRteError。

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

返回值

  • YES：配置成功。
  • NO：配置失败。

所属接口类

setConfigs:error:

配置 RTE 对象的信息。

Objective-C
- (BOOL)setConfigs:(AgoraRteConfig * _Nonnull)config error:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

你可以调用此方法设置如 App ID 等信息。

注： 必须在调用 initWithInitialConfig: 之后调用此方法。

参数

参数名描述
config

RTE 对象的设置信息，详见 AgoraRteConfig。

error

状态或错误信息，详见 AgoraRteError。

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

返回值

  • YES：配置成功。
  • NO：配置失败。

所属接口类

setJsonParameter:error:

通过 JSON 配置 SDK 提供的技术预览或定制功能。

Objective-C
- (void)setJsonParameter:(NSString * _Nullable)jsonParameter error:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

当你需要设置私有参数或使用定制功能时，可以调用此方法。

注： 你必须在调用 setConfigs:error: 之前调用此方法。

适用场景

当你需要设置私有参数或使用定制化功能时，可以调用此方法。

参数

参数名描述
jsonParameter

以 JSON 字符串形式传入的参数。

error

状态或错误信息，详见 AgoraRteError。

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

所属接口类

setLoopCount:error:

设置播放媒体文件的循环次数。

Objective-C
- (void)setLoopCount:(int32_t)count error:(AgoraRteError * _Nullable)error;

自从

自 v4.5.1 版本新增。

参数

参数名描述
count

媒体文件的播放次数：

  • 1：播放一次。
  • 2：播放两次。
  • -1：无限循环播放，直到调用 pause:。
error

输出参数，表示状态或错误信息，详见 AgoraRteError。

  • AgoraRteOk：调用成功。
  • AgoraRteErrorInvalidArgument：count 参数设置为无效值。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

setVideoMirrorMode:error:

设置视频镜像模式。

Objective-C
- (void)setVideoMirrorMode:(AgoraRteVideoMirrorMode)mode error:(AgoraRteError* _Nullable)error;

自从

自 v4.4.0 版本新增。

调用时机

你必须在调用 setConfigs:error: 之前调用此方法。

参数

参数名描述
mode

镜像模式，详见 AgoraRteVideoMirrorMode。默认值为 AgoraRteVideoMirrorModeAuto，表示由 SDK 自动决定镜像模式。默认情况下，远端用户的视频镜像模式为关闭状态。

error

状态或错误信息，详见 AgoraRteError。

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

所属接口类

setPlaybackSpeed:error:

设置播放速度参数。

Objective-C
- (void)setPlaybackSpeed:(int32_t)speed error:(AgoraRteError * _Nullable)error;

自从

自 v4.5.1 版本新增。

注： 你可以在调用 openWithUrl:startTime:cb: 方法之后调用此方法。

参数

参数名描述
speed

播放速度，取值范围为 [50, 400]。

error

用于返回错误信息的输出参数。详见 AgoraRteError。

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

所属接口类

setPlayoutVolume:error:

设置播放音量参数。

Objective-C
- (void)setPlayoutVolume:(int32_t)volume error:(AgoraRteError * _Nullable)error;

自从

自 v4.5.1 版本新增。

你可以使用该方法设置播放音量。有效范围为 [0, 400]。

参数

参数名描述
volume

要设置的播放音量。有效范围为 [0, 400]。

error

输出参数，返回错误信息。详见 AgoraRteError。

  • AgoraRteOk：设置成功。
  • AgoraRteErrorInvalidArgument：音量参数无效。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

setVideoRenderMode:error:

设置视频渲染模式。

Objective-C
- (void)setVideoRenderMode:(AgoraRteVideoRenderMode)mode error:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

参数

参数名描述
mode

要设置的视频渲染模式，详见 AgoraRteVideoRenderMode。默认值为 AgoraRteVideoRenderModeHidden。

error

状态或错误信息。

  • AgoraRteOk：成功。
  • AgoraRteErrorInvalidArgument：mode 参数设置为非法值。详见 AgoraRteError。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

stop:

停止播放。

Objective-C
- (BOOL)stop:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

参数

参数名描述
error

状态或错误信息，详见 AgoraRteError。可能返回以下 AgoraRteErrorCode：

  • AgoraRteOk：成功。
  • AgoraRteErrorInvalidOperation：对应的内部 AgoraRtePlayer 对象已被销毁或无效。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • YES：停止成功。
  • NO：停止失败。你可以通过 error 参数查看具体错误信息。

所属接口类

switchWithUrl:syncPts:cb:

在播放过程中切换到新的 URL。

Objective-C
- (void)switchWithUrl:(NSString * _Nonnull)url syncPts:(BOOL)syncPts cb:(void (^_Nullable)(AgoraRteError* _Nullable err))cb;

自从

自 v4.5.1 版本新增。

注： 该方法仅在使用非 RTE URL 打开播放器时有效。你必须在 SDK 返回播放器状态为 AgoraRtePlayerStateOpenCompleted 后调用此方法。

参数

参数名描述
url

要切换到的目标 URL。

syncPts

是否在切换后同步播放位置（单位为毫秒）：

  • YES：同步播放位置。
  • NO：（默认）不同步播放位置。
cb

异步通知切换操作结果的回调。你可以通过该回调的 err 参数得知操作的结果或错误码信息，详见 AgoraRteError。

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

所属接口类

unregisterObserver:error:

取消注册媒体播放器事件观察者对象。

Objective-C
- (BOOL)unregisterObserver:(AgoraRtePlayerObserver * _Nullable)observer error:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

调用 registerObserver:error: 注册媒体播放器事件观察者对象后，如需取消注册该观察者对象，可以调用此方法。

注： 该方法必须在调用 registerObserver:error: 之后调用。

调用时机

该方法必须在调用 registerObserver:error: 之后调用。

参数

参数名描述
observer

媒体播放器事件观察者对象。详见 AgoraRtePlayerObserver。

error

状态或错误信息。详见 AgoraRteError。

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

返回值

  • YES：取消注册成功。
  • NO：取消注册失败。

所属接口类

onAudioVolumeIndication:

播放器音量提示回调。

Objective-C
- (void)onAudioVolumeIndication:(int32_t)volume;

自从

自 v4.4.0 版本新增。

触发时机

当播放器音量发生变化时，SDK 会触发该回调。

参数

参数名描述
volume

播放器当前的音量，取值范围为 [0,225]。

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

所属接口类

onEvent:

播放器事件回调。

Objective-C
- (void)onEvent:(AgoraRtePlayerEvent)event;

自从

自 v4.4.0 版本新增。

如果你需要监听播放器事件，必须先调用 registerObserver:error: 方法注册播放器观察者对象。

触发时机

该回调在播放器事件发生变化时被触发。

参数

参数名描述
event

播放器事件，详见 AgoraRtePlayerEvent。

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

所属接口类

onMetadata:data:

接收媒体元数据的回调。

Objective-C
- (void)onMetadata:(AgoraRtePlayerMetadataType)type data:(NSData * _Nonnull)data;

自从

自 v4.4.0 版本新增。

如果你需要从输入在线媒体流中获取元数据，必须先调用 registerObserver:error: 注册一个播放器观察者对象。

触发时机

该回调在 SDK 从输入在线媒体流中解析出元数据后触发，用于上报数据的类型和内容。

参数

参数名描述
type

元数据的类型，详见 AgoraRtePlayerMetadataType。

data

解析后的元数据内容。

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

所属接口类

onPlayerInfoUpdated:

播放器或媒体流信息发生变化时触发的回调。

Objective-C
- (void)onPlayerInfoUpdated:(AgoraRtePlayerInfo * _Nonnull)info;

自从

自 v4.4.0 版本新增。

如果你希望获取播放器或媒体流的信息，需要先调用 registerObserver:error: 方法注册播放器观察者对象。你也可以直接使用 getInfo:error: 方法获取信息。

触发时机

当播放器或媒体流信息发生变化时，SDK 会触发该回调。

参数

参数名描述
info

关于播放器和媒体流的信息，详见 AgoraRtePlayerInfo。

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

所属接口类

onPositionChanged:utcTime:

onPositionChanged:utcTime: 回调。报告媒体资源的当前播放进度。

Objective-C
- (void)onPositionChanged:(uint64_t)currentTime utcTime:(uint64_t)utcTime;

自从

自 v4.4.0 版本新增。

触发时机

该回调在媒体资源播放过程中每秒触发一次。

参数

参数名描述
currentTime

当前播放进度，单位为毫秒。

utcTime

当前的 NTP（网络时间协议）时间，单位为毫秒。

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

所属接口类

onResolutionChanged:height:

视频分辨率变化的回调。

Objective-C
- (void)onResolutionChanged:(int)width height:(int)height;

自从

自 v4.4.0 版本新增。

如果你需要监控播放器正在播放的视频流的分辨率变化，必须先调用 registerObserver:error: 方法注册播放器观察者对象。

触发时机

该回调在视频流的分辨率发生变化时被触发，报告当前视频的宽度和高度。

参数

参数名描述
width

视频帧的宽度（像素）。

height

视频帧的高度（像素）。

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

所属接口类

onStateChanged:newState:error:

播放器状态发生变化回调。

Objective-C
- (void)onStateChanged:(AgoraRtePlayerState)oldState newState:(AgoraRtePlayerState)newState error:(AgoraRteError * _Nullable)error;

自从

自 v4.4.0 版本新增。

如果你需要监听播放器状态的变化，必须先调用 registerObserver:error: 方法注册播放器观察者对象。

触发时机

该回调在播放器状态发生变化时被触发，用于报告当前状态和之前的状态。

参数

参数名描述
oldState

变更前的播放器状态，详见 AgoraRtePlayerState。

newState

当前的播放器状态，详见 AgoraRtePlayerState。如果当前状态为 AgoraRtePlayerStateFailed，你可以通过 error 参数获取详细的错误信息。

error

状态或错误信息，详见 AgoraRteError。

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

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利