# URL 拉流播放 (/zh-CN/api-reference/rtc/ios/play/rte-player)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## addView\:config\:error: [#addviewconfigerror]
添加一个渲染视图。
```objc
- (BOOL)addView:(AgoraRteView * _Nonnull)view config:(AgoraRteViewConfig* _Nullable)config error:(AgoraRteError* _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
你可以调用该方法将视图添加到视频渲染器中,以显示视频内容。
:::note
注: 当前仅支持一个视图。
:::
### 适用场景 [#适用场景]
当你需要使用播放器播放视频时,可以调用此方法将视图添加到视频渲染器中,以显示视频内容。
### 调用时机 [#调用时机]
你必须在调用 [setCanvas\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_setcanvas) 之前调用此方法。
### 参数 [#参数]
视图对象的指针。
- iOS:一个 `UIView` 对象。
- macOS:一个 `NSView` 对象。
视图对象的配置。当前请传入 nil。
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值]
- YES:添加视图成功。
- NO:添加视图失败。
### 所属接口类 [#所属接口类]
- [AgoraRteCanvas](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_canvas)
## initWithRte\:initialConfig: [#initwithrteinitialconfig]
构造一个 [AgoraRteCanvas](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_canvas) 对象。
```objc
- (instancetype _Nonnull)initWithRte:(AgoraRte* _Nonnull)rte initialConfig:(AgoraRteCanvasInitialConfig * _Nullable)config;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 参数 [#参数-1]
用于构造 [AgoraRteCanvas](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_canvas) 的 [AgoraRte](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_rte) 对象。详见 [AgoraRte](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_rte)。
用于初始化的配置对象。你可以传入 nil。
### 所属接口类 [#所属接口类-1]
- [AgoraRteCanvas](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_canvas)
## code [#code]
获取 API 调用返回的错误码。
```objc
- (AgoraRteErrorCode)code;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
当 API 调用失败时,你可以调用该方法获取错误码。
### 调用时机 [#调用时机-1]
当 API 调用失败时,你可以调用该方法获取错误码。
### 返回值 [#返回值-1]
方法调用成功时,返回错误码,详见 [AgoraRteErrorCode](/zh-CN/api-reference/rtc/ios/enum-rteerrorcode)。
### 所属接口类 [#所属接口类-2]
- [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)
## destroy: [#destroy]
销毁 `RTE` 对象。
```objc
- (BOOL)destroy:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
该方法会释放 `RTE` 对象使用的所有资源。
### 参数 [#参数-2]
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-2]
- YES:销毁成功。
- NO:销毁失败。
### 所属接口类 [#所属接口类-3]
- [AgoraRte](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_rte)
## abrFallbackLayer: [#abrfallbacklayer]
获取已配置的视频流分层回退选项。
```objc
- (AgoraRteAbrFallbackLayer)abrFallbackLayer:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-2]
你必须在调用 [getConfigs\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_canvas_getconfigs_canvas) 之后调用此方法。
### 参数 [#参数-3]
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-3]
已配置的视频流分层回退选项,详见 [AgoraRteAbrFallbackLayer](/zh-CN/api-reference/rtc/ios/enum-rteabrfallbacklayer)。
### 所属接口类 [#所属接口类-4]
- [AgoraRtePlayerConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerconfig)
## abrSubscriptionLayer: [#abrsubscriptionlayer]
获取订阅端视频流的质量层级。
```objc
- (AgoraRteAbrSubscriptionLayer)abrSubscriptionLayer:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-3]
你必须在调用 [getConfigs\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_canvas_getconfigs_canvas) 之后调用此方法。
### 参数 [#参数-4]
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-4]
当前设置的视频质量层级,详见 [AgoraRteAbrSubscriptionLayer](/zh-CN/api-reference/rtc/ios/enum-rteabrsubscriptionlayer)。
### 所属接口类 [#所属接口类-5]
- [AgoraRtePlayerConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerconfig)
## appId: [#appid]
获取你已设置的声网 App ID。
```objc
- (NSString* _Nullable)appId:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 参数 [#参数-5]
错误信息对象,可能返回以下错误码,详见 [AgoraRteErrorCode](/zh-CN/api-reference/rtc/ios/enum-rteerrorcode):
- `AgoraRteOk`:调用成功。
### 返回值 [#返回值-5]
- 方法调用成功时,返回你已设置的声网 App ID。
- 方法调用失败时,返回空字符串。
### 所属接口类 [#所属接口类-6]
- [AgoraRteConfig](/zh-CN/api-reference/rtc/ios/class-config)
## autoPlay: [#autoplay]
获取媒体播放器的自动播放设置。
```objc
- (BOOL)autoPlay:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
你可以调用此方法获取媒体播放器当前的自动播放设置。
:::note
注: 必须在调用 [getConfigs\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_canvas_getconfigs_canvas) 方法之后调用。
:::
### 调用时机 [#调用时机-4]
必须在调用 [getConfigs\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_canvas_getconfigs_canvas) 方法之后调用。
### 参数 [#参数-6]
状态或错误信息。详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-6]
是否成功获取自动播放设置:
- YES:获取成功。
- NO:获取失败。
### 所属接口类 [#所属接口类-7]
- [AgoraRtePlayerConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerconfig)
## getConfigs\:error: [#getconfigserror]
获取当前播放器的视频渲染配置。
```objc
- (BOOL)getConfigs:(AgoraRteCanvasConfig* _Nonnull)config error:(AgoraRteError* _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-5]
你需要在调用 [initWithRte\:initialConfig:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_canvas_canvas_canvas) 方法之后调用该方法。
### 参数 [#参数-7]
视频画布配置,详见 [AgoraRteCanvasConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_canvasconfig)。
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-7]
- YES:获取成功。
- NO:获取失败。
### 所属接口类 [#所属接口类-8]
- [AgoraRteCanvas](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_canvas)
## getConfigs\:error: [#getconfigserror-1]
获取当前媒体播放器配置选项。
```objc
- (BOOL)getConfigs:(AgoraRtePlayerConfig * _Nonnull)config error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-6]
你必须在调用 [initWithRte\:initialConfig:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_player_player) 之后调用此方法。
### 参数 [#参数-8]
媒体播放器配置选项,详见 [AgoraRtePlayerConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerconfig)。
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-8]
- YES:获取成功。
- NO:获取失败。
### 所属接口类 [#所属接口类-9]
- [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player)
## getConfigs\:error: [#getconfigserror-2]
获取 RTE 对象的配置信息。
```objc
- (BOOL)getConfigs:(AgoraRteConfig *_Nonnull)config error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-7]
你必须在调用 [initWithInitialConfig:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_rte_rte_rte) 之后调用该方法。
### 参数 [#参数-9]
RTE 对象的配置信息。详见 [AgoraRteConfig](/zh-CN/api-reference/rtc/ios/class-config)。
状态或错误信息。详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-9]
- YES:获取成功。
- NO:获取失败。
### 所属接口类 [#所属接口类-10]
- [AgoraRte](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_rte)
## getFromBridge: [#getfrombridge]
桥接一个来自 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine) 的 `RTE` 对象。
```objc
+ (instancetype _Nonnull)getFromBridge:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
通过调用此方法创建的 `RTE` 对象无需通过 [initMediaEngine\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_rte_initmediaengine) 进行初始化。如果你尚未创建并初始化 RTC 引擎,可以先调用 [AgoraRte](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_rte) 创建一个 `RTE` 对象,然后使用 [initMediaEngine\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_rte_initmediaengine) 进行初始化。
### 调用时机 [#调用时机-8]
在调用此方法之前,请确保你已通过调用 [sharedEngineWithConfig\:delegate:](/zh-CN/api-reference/rtc/ios/initialize#api_irtcengine_initialize) 初始化 RTC 引擎。
### 参数 [#参数-10]
用于接收状态和错误码的指针,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-10]
方法调用成功,返回一个 `RTE` 对象,详见 [AgoraRte](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_rte)。
### 所属接口类 [#所属接口类-11]
- [AgoraRte](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_rte)
## getInfo\:error: [#getinfoerror]
获取播放器播放和媒体流相关的信息。
```objc
- (BOOL)getInfo:(AgoraRtePlayerInfo * _Nonnull)info error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
你可以使用该方法获取播放器和媒体流相关的信息,例如音频采样率和视频帧尺寸。
:::note
注: 你必须在调用 [initWithRte\:initialConfig:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_player_player) 之后调用此方法。
:::
### 参数 [#参数-11]
播放器和媒体流相关的信息。详见 [AgoraRtePlayerInfo](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_rteplayerinfo)。
状态或错误信息。详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-11]
- YES:成功获取信息。
- NO:获取信息失败。
### 所属接口类 [#所属接口类-12]
- [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player)
## jsonParameter: [#jsonparameter]
获取当前配置的 RTE 私有参数。
```objc
- (NSString * _Nullable)jsonParameter:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 参数 [#参数-12]
状态或错误信息。详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
- `AgoraRteOk`:调用成功。
### 返回值 [#返回值-12]
- 方法调用成功时,返回已设置的 JSON 格式参数集。
- 方法调用失败时,返回空字符串。
### 所属接口类 [#所属接口类-13]
- [AgoraRteConfig](/zh-CN/api-reference/rtc/ios/class-config)
## loopCount: [#loopcount]
获取媒体文件的循环次数参数。
```objc
- (int32_t)loopCount:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 参数 [#参数-13]
输出参数,用于指示错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-13]
方法调用成功时,返回媒体文件的循环次数。
### 所属接口类 [#所属接口类-14]
- [AgoraRtePlayerConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerconfig)
## videoMirrorMode: [#videomirrormode]
获取当前设置的镜像模式。
```objc
- (AgoraRteVideoMirrorMode)videoMirrorMode:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-9]
你必须在调用 [getConfigs\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_canvas_getconfigs_canvas) 之后调用此方法。
### 参数 [#参数-14]
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-14]
当前设置的镜像模式,详见 [AgoraRteVideoMirrorMode](/zh-CN/api-reference/rtc/ios/enum-rtevideomirrormode)。
### 所属接口类 [#所属接口类-15]
- [AgoraRteCanvasConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_canvasconfig)
## playbackSpeed: [#playbackspeed]
获取播放速度参数。
```objc
- (int32_t)playbackSpeed:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 参数 [#参数-15]
输出参数,用于指示错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-15]
方法调用成功时,返回播放速度的值。
### 所属接口类 [#所属接口类-16]
- [AgoraRtePlayerConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerconfig)
## playoutVolume: [#playoutvolume]
获取媒体播放器的播放音量。
```objc
- (int32_t)playoutVolume:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 参数 [#参数-16]
输出参数,用于返回错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-16]
方法调用成功,返回媒体播放器的播放音量。
### 所属接口类 [#所属接口类-17]
- [AgoraRtePlayerConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerconfig)
## getPosition: [#getposition]
获取当前播放位置。
```objc
- (uint64_t)getPosition:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.5.1 版本新增。
:::
该方法用于获取当前播放的时间位置,单位为毫秒。
### 参数 [#参数-17]
输出参数,用于指示错误信息。可能的返回值包括:
- `AgoraRteOk`:调用成功。
- `AgoraRteErrorInvalidOperation`:
- 对应的内部 [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player) 对象已被销毁或无效。
- 打开的 URL 是 RTE URL,不支持调用 [getPosition:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_getposition)。详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-17]
方法调用成功时,返回当前播放位置,单位为毫秒。
### 所属接口类 [#所属接口类-18]
- [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player)
## videoRenderMode: [#videorendermode]
获取当前设置的视频渲染模式。
```objc
- (AgoraRteVideoRenderMode)videoRenderMode:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-10]
你需要在调用 [getConfigs\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_canvas_getconfigs_canvas) 之后调用此方法。
### 参数 [#参数-18]
状态或错误信息。详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-18]
当前设置的视频渲染模式。详见 [AgoraRteVideoRenderMode](/zh-CN/api-reference/rtc/ios/enum-rtevideorendermode)。
### 所属接口类 [#所属接口类-19]
- [AgoraRteCanvasConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_canvasconfig)
## getStats: [#getstats]
获取播放器当前播放媒体资源的统计信息。
```objc
- (void)getStats:(void (^_Nonnull)(AgoraRtePlayerStats* _Nonnull stats, AgoraRteError* _Nullable err))cb;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
该方法用于获取播放器的统计信息,并通过回调函数异步返回结果。统计信息包括解码和渲染帧率、音视频码率等。
:::note
注: 你必须在调用 [openWithUrl\:startTime\:cb:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_openwithurl) 方法之后再调用此方法。
:::
### 参数 [#参数-19]
一个异步回调函数,用于通知你播放器媒体资源统计信息的获取结果以及任何错误信息。该函数包含以下参数:
- `stats`:播放器当前播放媒体资源的统计信息,详见 [AgoraRtePlayerStats](/zh-CN/api-reference/rtc/ios/class-rteplayerstats)。
- `err`:错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-20]
- [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player)
## initMediaEngine\:error: [#initmediaengineerror]
初始化 `RTE` 引擎。
```objc
- (BOOL)initMediaEngine:(void (^ _Nullable)(AgoraRteError* _Nullable err) )cb error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
该方法为异步方法,通过回调函数返回初始化结果。你需要在创建 `RTE` 对象并设置 App ID 后调用该方法。
:::note
注: 该返回值仅表示初始化操作是否已成功加入异步任务队列,并不表示初始化是否成功。
:::
### 调用时机 [#调用时机-11]
你需要在创建 `RTE` 对象并设置 App ID 后调用该方法。
### 参数 [#参数-20]
用于返回引擎初始化结果的异步回调函数。你可以通过该回调的 `err` 参数判断引擎初始化的结果或错误码。详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
初始化过程中发生的错误信息。当调用 [initMediaEngine\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_rte_initmediaengine) 方法进行初始化时,如果发生可立即检测的错误(如参数无效或资源不足),SDK 会通过该参数同步返回错误信息。详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-19]
- YES:异步操作成功加入队列。
- NO:异步操作未能加入队列。
该返回值仅表示初始化操作是否已成功加入异步任务队列,并不表示初始化是否成功。
### 所属接口类 [#所属接口类-21]
- [AgoraRte](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_rte)
## message [#message]
获取详细错误信息。
```objc
- (NSString * _Nullable)message;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-12]
当 API 调用失败时,你可以调用此方法获取错误信息,以帮助排查问题。
### 返回值 [#返回值-20]
- 方法调用成功时,返回错误信息字符串。
- 方法调用失败时,返回空字符串。
### 所属接口类 [#所属接口类-22]
- [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)
## muteAudio\:error: [#muteaudioerror]
开始或停止接收音频流。
```objc
- (BOOL)muteAudio:(BOOL)mute error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-13]
你必须在调用 [openWithUrl\:startTime\:cb:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_openwithurl) 之后调用此方法。
### 相关回调 [#相关回调]
调用该方法成功后,会触发 [onPlayerInfoUpdated:](/zh-CN/api-reference/rtc/ios/play/rte-player#callback_playerobserver_onplayerinfoupdated_playerobserver) 回调以上报最新的播放器和媒体流信息。
### 参数 [#参数-21]
是否接收音频流:
- YES:不接收音频流。
- NO:接收音频流。
输出参数,状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-21]
- YES:操作成功。
- NO:操作失败。
### 所属接口类 [#所属接口类-23]
- [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player)
## muteVideo\:error: [#mutevideoerror]
开始或停止接收远端视频流。
```objc
- (BOOL)muteVideo:(BOOL)mute error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-14]
你必须在调用 [openWithUrl\:startTime\:cb:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_openwithurl) 之后调用此方法。
### 相关回调 [#相关回调-1]
调用该方法成功后,会触发 [onPlayerInfoUpdated:](/zh-CN/api-reference/rtc/ios/play/rte-player#callback_playerobserver_onplayerinfoupdated_playerobserver) 回调以上报最新的播放器和媒体流信息。
### 参数 [#参数-22]
是否接收远端视频流:
- YES:不接收远端视频流。
- NO:接收远端视频流。
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-22]
- YES:操作成功。
- NO:操作失败。
### 所属接口类 [#所属接口类-24]
- [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player)
## openWithUrl\:startTime\:cb: [#openwithurlstarttimecb]
打开一个 URL 资源。
```objc
- (void)openWithUrl:(NSString * _Nonnull)url startTime:(uint64_t)startTime cb:(void (^_Nullable)(AgoraRteError* _Nullable err))cb;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
该方法支持通过 URL 打开实时流媒体资源。若希望加快打开 URL 资源的速度,可以在调用该方法前先调用 [preloadWithUrl\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_preloadwithurl) 预加载资源。
:::note
注: 该方法目前仅支持打开以 `rte://` 开头的 URL、CDN 推流 URL 和本地媒体文件。
:::
### 调用时机 [#调用时机-15]
该方法必须在调用 [initWithRte\:initialConfig:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_player_player) 之后调用。
### 相关回调 [#相关回调-2]
成功调用该方法后,SDK 会触发 [onStateChanged\:newState\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#callback_playerobserver_onstatechanged) 回调报告播放器连接状态为 `AgoraRtePlayerStateOpening`,表示正在打开 URL。打开成功后,播放器连接状态会报告为 `AgoraRtePlayerStateOpenCompleted`。如果资源打开失败,会收到 [onStateChanged\:newState\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#callback_playerobserver_onstatechanged) 回调,报告连接状态为 `AgoraRtePlayerStateFailed`。此时需先调用 [pause:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_pause_player),再调用 [openWithUrl\:startTime\:cb:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_openwithurl) 重新打开 URL 资源。如果已关闭自动播放,可在资源打开后调用 [play:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_play_player) 开始播放。
### 参数 [#参数-23]
要打开的 URL,可以是 CDN 推流 URL、本地媒体文件,或以 `rte://` 为前缀的 URL。关于 RTE URL 各字段的详细信息,详见 `观众端 URL 拉流`。
起始播放位置,单位为毫秒。
异步通知打开 URL 资源结果的回调。你可以通过该回调的 `err` 参数得知操作的结果或错误码信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-25]
- [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player)
## pause: [#pause]
暂停播放。
```objc
- (BOOL)pause:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
调用 [play:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_play_player) 播放 URL 资源后,如果你希望暂停播放,可以调用该方法。如果你希望停止播放,请调用 [pause:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_pause_player)。你必须在调用 [play:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_play_player) 之后调用该方法。
### 调用时机 [#调用时机-16]
你必须在调用 [play:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_play_player) 之后调用该方法。
### 参数 [#参数-24]
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-23]
- YES:暂停播放成功。
- NO:暂停播放失败。
### 所属接口类 [#所属接口类-26]
- [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player)
## play: [#play]
播放一个以 `rte://` 开头的 URL 资源。
```objc
- (BOOL)play:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
如果你已关闭自动播放,在使用 [openWithUrl\:startTime\:cb:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_openwithurl) 成功打开直播流后,可以调用此方法开始播放。
### 调用时机 [#调用时机-17]
仅在收到 [onStateChanged\:newState\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#callback_playerobserver_onstatechanged) 回调并报告状态为 `AgoraRtePlayerStateOpenCompleted` 后调用此方法。
### 参数 [#参数-25]
连接状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-24]
- YES:播放成功。
- NO:播放失败。
### 所属接口类 [#所属接口类-27]
- [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player)
## initWithRte\:initialConfig: [#initwithrteinitialconfig-1]
构造一个播放器对象。
```objc
- (instancetype _Nonnull)initWithRte:(AgoraRte * _Nonnull)rte initialConfig:(AgoraRtePlayerInitialConfig * _Nullable)config;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-18]
你必须在调用 [initMediaEngine\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_rte_initmediaengine) 之后调用此方法。
### 参数 [#参数-26]
一个 [AgoraRte](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_rte) 对象,详见 [AgoraRte](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_rte)。
播放器对象的初始化设置。你可以传入 nil。
### 所属接口类 [#所属接口类-28]
- [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player)
## preloadWithUrl\:error: [#preloadwithurlerror]
预加载 URL 资源。
```objc
+ (BOOL)preloadWithUrl:(NSString * _Nonnull)url error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
你可以在调用 [openWithUrl\:startTime\:cb:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_openwithurl) 之前调用该方法,成功预加载 URL 资源后,可以更快地通过 [openWithUrl\:startTime\:cb:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_openwithurl) 打开该资源,从而减少等待时间,提升视听体验的流畅度。
:::note
注: 该方法当前仅对以 `rte://` 为前缀的 URL 生效。最多可预加载 20 个 URL,若超过限制,最新预加载的 URL 会替换最早的 URL。
:::
### 适用场景 [#适用场景-1]
在打开媒体资源前预加载,可以减少用户等待时间,提供更流畅的视听体验。
### 参数 [#参数-27]
以 `rte://` 为前缀的 URL。
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-25]
- YES:预加载成功。
- NO:预加载失败。
### 所属接口类 [#所属接口类-29]
- [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player)
## registerObserver\:error: [#registerobservererror]
注册一个播放器观察者对象。
```objc
- (BOOL)registerObserver:(AgoraRtePlayerObserver *_Nonnull)observer error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
在调用此方法之前,你需要实现一个继承自 [AgoraRtePlayerObserver](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerobserver) 的接口类。你必须在调用 [initWithRte\:initialConfig:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_player_player) 之后再调用此方法。
### 参数 [#参数-28]
接口对象实例,详见 [AgoraRtePlayerObserver](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerobserver)。
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-26]
- YES:注册成功。
- NO:注册失败。
### 所属接口类 [#所属接口类-30]
- [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player)
## removeView\:config\:error: [#removeviewconfigerror]
移除一个渲染视图。
```objc
- (BOOL)removeView:(AgoraRteView * _Nonnull)view config:(AgoraRteViewConfig* _Nullable)config error:(AgoraRteError* _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
调用 [addView\:config\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_canvas_addview) 方法添加视图后,可以调用该方法移除渲染视图。
:::note
注: 每次只能移除一个视图。
:::
### 调用时机 [#调用时机-19]
必须在调用 [addView\:config\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_canvas_addview) 方法之后调用。
### 参数 [#参数-29]
要移除的视图对象,详见 `AgoraRteView`。
视图对象的配置。目前传入 nil。
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-27]
- YES:视图移除成功。
- NO:视图移除失败。
### 所属接口类 [#所属接口类-31]
- [AgoraRteCanvas](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_canvas)
## initWithInitialConfig: [#initwithinitialconfig]
构造一个 `RTE` 对象。
```objc
- (instancetype _Nonnull)initWithInitialConfig:(AgoraRteInitialConfig * _Nullable)config;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
`RTE` 对象用于组织和管理 `RTE` 的内部资源。你必须在调用 [initMediaEngine\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_rte_initmediaengine) 方法之前调用此方法。
### 调用时机 [#调用时机-20]
你必须在调用 [initMediaEngine\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_rte_initmediaengine) 方法之前调用此方法。
### 参数 [#参数-30]
初始化设置。你可以传入 nil。
### 返回值 [#返回值-28]
- 方法调用成功,返回 `RTE` 对象。
- 方法调用失败,返回 nil。
### 所属接口类 [#所属接口类-32]
- [AgoraRte](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_rte)
## seek\:error: [#seekerror]
跳转到指定的播放位置。
```objc
- (BOOL)seek:(uint64_t)newTime error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 参数 [#参数-31]
要跳转到的播放位置。
输出参数,用于在跳转操作失败时返回错误信息。详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-29]
- YES:跳转成功。
- NO:跳转失败。
### 所属接口类 [#所属接口类-33]
- [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player)
## setAbrFallbackLayer\:error: [#setabrfallbacklayererror]
设置已订阅远端视频流的分层推流回退选项。
```objc
- (void)setAbrFallbackLayer:(AgoraRteAbrFallbackLayer)layer error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
在网络条件较差时,实时音视频通信的质量可能会下降。调用该方法后,SDK 会在网络变差时将远端视频流的分辨率回退到指定的视频质量层级。每个视频质量层级对应特定的分辨率和码率。SDK 会持续监测网络质量,在网络改善时恢复到原始订阅的视频质量层级。
默认情况下,调用该方法后只能选择回退到 `AgoraRteAbrFallbackLow` 或 `AgoraRteAbrFallbackAudioOnly`。如果你对视频体验有更高要求,可以[联系技术支持](https://ticket.shengwang.cn/)开启 ABR 功能。开启后,可以回退到所有视频质量层级,并自定义每个层级的分辨率。
:::note
注: 如果未开启 ABR 功能,远端视频流的回退质量层级只能设置为 `AgoraRteAbrFallbackLow` 或 `AgoraRteAbrFallbackAudioOnly`。
:::
### 适用场景 [#适用场景-2]
一般场景下,可调用该方法并将回退质量层设置为 `kRteAbrFallbackLow` 或 `kRteAbrFallbackAudioOnly`。当网络较差时,SDK 会回退为视频小流或仅接收音频流。
如果对回退视频流的分辨率有更高要求,可[联系技术支持](https://ticket.shengwang.cn/)开启 ABR 功能。开启后,可自定义每一层的分辨率。SDK 会以你指定的最低质量层的分辨率为下限,并根据网络状况在该范围内动态调整分辨率。
### 调用时机 [#调用时机-21]
必须在调用 [setConfigs\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_canvas_setconfigs_canvas) 之前调用该方法。
### 参数 [#参数-32]
回退的视频质量层级。可选值详见 [AgoraRteAbrFallbackLayer](/zh-CN/api-reference/rtc/ios/enum-rteabrfallbacklayer)。当自定义 `AgoraRteAbrFallbackLayer1` 到 `AgoraRteAbrFallbackLayer6` 的分辨率时,可参考下表或根据实际需求定义:
:::note
注: 自定义分辨率时,必须按从高到低的分辨率顺序排列视频质量层级。如果两个层级的分辨率相同,则按帧率从高到低排序。
:::
| 视频质量层级 | 分辨率 |
| --- | --- |
| `AgoraRteAbrSubscriptionLayer1` | 2160p (4K) |
| `AgoraRteAbrSubscriptionLayer2` | 1440p (2K) |
| `AgoraRteAbrSubscriptionLayer3` | 1080p (HD) |
| `AgoraRteAbrSubscriptionLayer4` | 720p (HD) |
| `AgoraRteAbrSubscriptionLayer5` | 540p (SD) |
| `AgoraRteAbrSubscriptionLayer6` | 480p (SD) |
自定义分辨率时,必须按从高到低的分辨率顺序排列视频质量层级。如果两个层级的分辨率相同,则按帧率从高到低排序。详见 `AgoraRteAbrFallbackLayer`。
状态或错误信息。详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-34]
- [AgoraRtePlayerConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerconfig)
## setAbrSubscriptionLayer\:error: [#setabrsubscriptionlayererror]
设置订阅端媒体流的视频质量层级。
```objc
- (void)setAbrSubscriptionLayer:(AgoraRteAbrSubscriptionLayer)layer error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
你可以根据实际的网络状况,在多质量层级视频流中切换不同的视频质量层级,每个层级对应不同的分辨率。默认情况下,调用该方法后,观众只能在高、低两个视频流之间切换,即 `AgoraRteAbrSubscriptionHigh` 和 `AgoraRteAbrSubscriptionLow`。如果你需要更高级的分辨率切换功能,可以[联系技术支持](https://ticket.shengwang.cn/)开启 ABR(自适应码率)功能。开启后,你可以自定义每个视频质量层级的分辨率,观众可以根据需要在所有可用的视频质量层级之间切换。
:::note
注: 如果在调用该方法时未开启 ABR 功能,订阅的视频质量层级只能设置为 `AgoraRteAbrSubscriptionHigh` 或 `AgoraRteAbrSubscriptionLow`。
:::
### 适用场景 [#适用场景-3]
在网络环境不稳定的场景中,订阅端可根据实际网络状况选择合适的视频质量层级,以保障流畅的观看体验。
### 调用时机 [#调用时机-22]
你必须在调用 [setConfigs\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_canvas_setconfigs_canvas) 之前调用该方法。
### 参数 [#参数-33]
要订阅的视频质量层级。你可以自定义 `AgoraRteAbrSubscriptionLayer1` 到 `AgoraRteAbrSubscriptionLayer6` 的分辨率,参考如下建议,或根据实际需求定义:
注意:自定义分辨率时,请确保视频质量层级按分辨率从高到低排序;如果分辨率相同,则按帧率从高到低排序。
| 视频质量层级 | 分辨率 |
| --- | --- |
| `AgoraRteAbrSubscriptionLayer1` | 2160p (4K) |
| `AgoraRteAbrSubscriptionLayer2` | 1440p (2K) |
| `AgoraRteAbrSubscriptionLayer3` | 1080p (HD) |
| `AgoraRteAbrSubscriptionLayer4` | 720p (HD) |
| `AgoraRteAbrSubscriptionLayer5` | 540p (SD) |
| `AgoraRteAbrSubscriptionLayer6` | 480p (SD) |
详见 `AgoraRteAbrSubscriptionLayer`。
状态或错误信息。详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-35]
- [AgoraRtePlayerConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerconfig)
## setAppId\:error: [#setappiderror]
设置声网 App ID。
```objc
- (void)setAppId:(NSString * _Nullable)appId error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-23]
你必须在调用 [initMediaEngine\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_rte_initmediaengine) 之前调用此方法。
### 参数 [#参数-34]
项目的声网 App ID,可从控制台获取。
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-36]
- [AgoraRteConfig](/zh-CN/api-reference/rtc/ios/class-config)
## setAutoPlay\:error: [#setautoplayerror]
设置是否启用自动播放。
```objc
- (void)setAutoPlay:(BOOL)autoPlay error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
你可以在调用 [openWithUrl\:startTime\:cb:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_openwithurl) 之前调用此方法设置是否启用自动播放。如果未设置,默认启用自动播放。
:::note
注: 该方法必须在调用 [openWithUrl\:startTime\:cb:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_openwithurl) 之前调用。
:::
### 调用时机 [#调用时机-24]
该方法必须在调用 [openWithUrl\:startTime\:cb:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_openwithurl) 之前调用。
### 参数 [#参数-35]
是否启用自动播放:
- YES:(默认)启用自动播放。
- NO:不启用自动播放。
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-37]
- [AgoraRtePlayerConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerconfig)
## setCanvas\:error: [#setcanvaserror]
设置用于显示视频的视图窗口。
```objc
- (BOOL)setCanvas:(AgoraRteCanvas *_Nonnull)canvas error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
该方法用于设置用于显示视频的视图窗口。在视频流成功开始播放后,视频将渲染在指定的 `canvas` 上。
:::note
注: 你必须在调用 [initWithRte\:initialConfig:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_player_player) 之后调用此方法。
:::
### 参数 [#参数-36]
用于渲染视频帧的视图窗口。详见 [AgoraRteCanvas](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_canvas)。
状态或错误信息。详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-30]
- YES:设置成功。
- NO:设置失败。你可以通过 `error` 参数返回的错误码获取详细信息。
### 所属接口类 [#所属接口类-38]
- [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player)
## setConfigs\:error: [#setconfigserror]
设置播放器的视频渲染配置。
```objc
- (BOOL)setConfigs:(AgoraRteCanvasConfig* _Nonnull)config error:(AgoraRteError* _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-25]
你必须在调用 [openWithUrl\:startTime\:cb:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_openwithurl) 之前调用此方法。
### 参数 [#参数-37]
Canvas 对象的设置,详见 [AgoraRteCanvasConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_canvasconfig)。
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-31]
- YES:配置成功。
- NO:配置失败。
### 所属接口类 [#所属接口类-39]
- [AgoraRteCanvas](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_canvas)
## setConfigs\:error: [#setconfigserror-1]
配置播放器参数。
```objc
- (BOOL)setConfigs:(AgoraRtePlayerConfig * _Nonnull)config error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
你可以调用此方法配置播放器,例如启用自动播放、订阅不同分辨率和码率的视频流。
:::note
注: 必须在调用 [initWithRte\:initialConfig:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_player_player) 之后调用此方法。
:::
### 参数 [#参数-38]
播放器配置对象。详见 [AgoraRtePlayerConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerconfig)。
状态或错误信息。详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-32]
- YES:配置成功。
- NO:配置失败。
### 所属接口类 [#所属接口类-40]
- [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player)
## setConfigs\:error: [#setconfigserror-2]
配置 RTE 对象的信息。
```objc
- (BOOL)setConfigs:(AgoraRteConfig * _Nonnull)config error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
你可以调用此方法设置如 App ID 等信息。
:::note
注: 必须在调用 [initWithInitialConfig:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_rte_rte_rte) 之后调用此方法。
:::
### 参数 [#参数-39]
RTE 对象的设置信息,详见 [AgoraRteConfig](/zh-CN/api-reference/rtc/ios/class-config)。
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-33]
- YES:配置成功。
- NO:配置失败。
### 所属接口类 [#所属接口类-41]
- [AgoraRte](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_rte)
## setJsonParameter\:error: [#setjsonparametererror]
通过 JSON 配置 SDK 提供的技术预览或定制功能。
```objc
- (void)setJsonParameter:(NSString * _Nullable)jsonParameter error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
当你需要设置私有参数或使用定制功能时,可以调用此方法。
:::note
注: 你必须在调用 [setConfigs\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_canvas_setconfigs_canvas) 之前调用此方法。
:::
### 适用场景 [#适用场景-4]
当你需要设置私有参数或使用定制化功能时,可以调用此方法。
### 参数 [#参数-40]
以 JSON 字符串形式传入的参数。
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-42]
- [AgoraRteConfig](/zh-CN/api-reference/rtc/ios/class-config)
## setLoopCount\:error: [#setloopcounterror]
设置播放媒体文件的循环次数。
```objc
- (void)setLoopCount:(int32_t)count error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 参数 [#参数-41]
媒体文件的播放次数:
- `1`:播放一次。
- `2`:播放两次。
- `-1`:无限循环播放,直到调用 [pause:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_pause_player)。
输出参数,表示状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
- `AgoraRteOk`:调用成功。
- `AgoraRteErrorInvalidArgument`:`count` 参数设置为无效值。
### 所属接口类 [#所属接口类-43]
- [AgoraRtePlayerConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerconfig)
## setVideoMirrorMode\:error: [#setvideomirrormodeerror]
设置视频镜像模式。
```objc
- (void)setVideoMirrorMode:(AgoraRteVideoMirrorMode)mode error:(AgoraRteError* _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-26]
你必须在调用 [setConfigs\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_canvas_setconfigs_canvas) 之前调用此方法。
### 参数 [#参数-42]
镜像模式,详见 [AgoraRteVideoMirrorMode](/zh-CN/api-reference/rtc/ios/enum-rtevideomirrormode)。默认值为 `AgoraRteVideoMirrorModeAuto`,表示由 SDK 自动决定镜像模式。默认情况下,远端用户的视频镜像模式为关闭状态。
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-44]
- [AgoraRteCanvasConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_canvasconfig)
## setPlaybackSpeed\:error: [#setplaybackspeederror]
设置播放速度参数。
```objc
- (void)setPlaybackSpeed:(int32_t)speed error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.5.1 版本新增。
:::
:::note
注: 你可以在调用 [openWithUrl\:startTime\:cb:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_openwithurl) 方法之后调用此方法。
:::
### 参数 [#参数-43]
播放速度,取值范围为 [50, 400]。
用于返回错误信息的输出参数。详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-45]
- [AgoraRtePlayerConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerconfig)
## setPlayoutVolume\:error: [#setplayoutvolumeerror]
设置播放音量参数。
```objc
- (void)setPlayoutVolume:(int32_t)volume error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.5.1 版本新增。
:::
你可以使用该方法设置播放音量。有效范围为 [0, 400]。
### 参数 [#参数-44]
要设置的播放音量。有效范围为 [0, 400]。
输出参数,返回错误信息。详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
- `AgoraRteOk`:设置成功。
- `AgoraRteErrorInvalidArgument`:音量参数无效。
### 所属接口类 [#所属接口类-46]
- [AgoraRtePlayerConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerconfig)
## setVideoRenderMode\:error: [#setvideorendermodeerror]
设置视频渲染模式。
```objc
- (void)setVideoRenderMode:(AgoraRteVideoRenderMode)mode error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 参数 [#参数-45]
要设置的视频渲染模式,详见 [AgoraRteVideoRenderMode](/zh-CN/api-reference/rtc/ios/enum-rtevideorendermode)。默认值为 `AgoraRteVideoRenderModeHidden`。
状态或错误信息。
- `AgoraRteOk`:成功。
- `AgoraRteErrorInvalidArgument`:`mode` 参数设置为非法值。详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-47]
- [AgoraRteCanvasConfig](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_canvasconfig)
## stop: [#stop]
停止播放。
```objc
- (BOOL)stop:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 参数 [#参数-46]
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。可能返回以下 [AgoraRteErrorCode](/zh-CN/api-reference/rtc/ios/enum-rteerrorcode):
- `AgoraRteOk`:成功。
- `AgoraRteErrorInvalidOperation`:对应的内部 [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player) 对象已被销毁或无效。
### 返回值 [#返回值-34]
- YES:停止成功。
- NO:停止失败。你可以通过 `error` 参数查看具体错误信息。
### 所属接口类 [#所属接口类-48]
- [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player)
## switchWithUrl\:syncPts\:cb: [#switchwithurlsyncptscb]
在播放过程中切换到新的 URL。
```objc
- (void)switchWithUrl:(NSString * _Nonnull)url syncPts:(BOOL)syncPts cb:(void (^_Nullable)(AgoraRteError* _Nullable err))cb;
```
:::info[自从]
自 v4.5.1 版本新增。
:::
:::note
注: 该方法仅在使用非 RTE URL 打开播放器时有效。你必须在 SDK 返回播放器状态为 `AgoraRtePlayerStateOpenCompleted` 后调用此方法。
:::
### 参数 [#参数-47]
要切换到的目标 URL。
是否在切换后同步播放位置(单位为毫秒):
- YES:同步播放位置。
- NO:(默认)不同步播放位置。
异步通知切换操作结果的回调。你可以通过该回调的 `err` 参数得知操作的结果或错误码信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-49]
- [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player)
## unregisterObserver\:error: [#unregisterobservererror]
取消注册媒体播放器事件观察者对象。
```objc
- (BOOL)unregisterObserver:(AgoraRtePlayerObserver * _Nullable)observer error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
调用 [registerObserver\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_registerobserver_player) 注册媒体播放器事件观察者对象后,如需取消注册该观察者对象,可以调用此方法。
:::note
注: 该方法必须在调用 [registerObserver\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_registerobserver_player) 之后调用。
:::
### 调用时机 [#调用时机-27]
该方法必须在调用 [registerObserver\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_registerobserver_player) 之后调用。
### 参数 [#参数-48]
媒体播放器事件观察者对象。详见 [AgoraRtePlayerObserver](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerobserver)。
状态或错误信息。详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 返回值 [#返回值-35]
- YES:取消注册成功。
- NO:取消注册失败。
### 所属接口类 [#所属接口类-50]
- [AgoraRtePlayer](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_player)
## onAudioVolumeIndication: [#onaudiovolumeindication]
播放器音量提示回调。
```objc
- (void)onAudioVolumeIndication:(int32_t)volume;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 触发时机 [#触发时机]
当播放器音量发生变化时,SDK 会触发该回调。
### 参数 [#参数-49]
播放器当前的音量,取值范围为 [0,225]。
### 所属接口类 [#所属接口类-51]
- [AgoraRtePlayerObserver](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerobserver)
## onEvent: [#onevent]
播放器事件回调。
```objc
- (void)onEvent:(AgoraRtePlayerEvent)event;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
如果你需要监听播放器事件,必须先调用 [registerObserver\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_registerobserver_player) 方法注册播放器观察者对象。
### 触发时机 [#触发时机-1]
该回调在播放器事件发生变化时被触发。
### 参数 [#参数-50]
播放器事件,详见 [AgoraRtePlayerEvent](/zh-CN/api-reference/rtc/ios/enum-rteplayerevent)。
### 所属接口类 [#所属接口类-52]
- [AgoraRtePlayerObserver](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerobserver)
## onMetadata\:data: [#onmetadatadata]
接收媒体元数据的回调。
```objc
- (void)onMetadata:(AgoraRtePlayerMetadataType)type data:(NSData * _Nonnull)data;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
如果你需要从输入在线媒体流中获取元数据,必须先调用 [registerObserver\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_registerobserver_player) 注册一个播放器观察者对象。
### 触发时机 [#触发时机-2]
该回调在 SDK 从输入在线媒体流中解析出元数据后触发,用于上报数据的类型和内容。
### 参数 [#参数-51]
元数据的类型,详见 [AgoraRtePlayerMetadataType](/zh-CN/api-reference/rtc/ios/enum-rteplayermetadatatype)。
解析后的元数据内容。
### 所属接口类 [#所属接口类-53]
- [AgoraRtePlayerObserver](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerobserver)
## onPlayerInfoUpdated: [#onplayerinfoupdated]
播放器或媒体流信息发生变化时触发的回调。
```objc
- (void)onPlayerInfoUpdated:(AgoraRtePlayerInfo * _Nonnull)info;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
如果你希望获取播放器或媒体流的信息,需要先调用 [registerObserver\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_registerobserver_player) 方法注册播放器观察者对象。你也可以直接使用 [getInfo\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_getinfo) 方法获取信息。
### 触发时机 [#触发时机-3]
当播放器或媒体流信息发生变化时,SDK 会触发该回调。
### 参数 [#参数-52]
关于播放器和媒体流的信息,详见 [AgoraRtePlayerInfo](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_rteplayerinfo)。
### 所属接口类 [#所属接口类-54]
- [AgoraRtePlayerObserver](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerobserver)
## onPositionChanged\:utcTime: [#onpositionchangedutctime]
[onPositionChanged\:utcTime:](/zh-CN/api-reference/rtc/ios/play/rte-player#callback_playerobserver_onpositionchanged_playerobserver) 回调。报告媒体资源的当前播放进度。
```objc
- (void)onPositionChanged:(uint64_t)currentTime utcTime:(uint64_t)utcTime;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 触发时机 [#触发时机-4]
该回调在媒体资源播放过程中每秒触发一次。
### 参数 [#参数-53]
当前播放进度,单位为毫秒。
当前的 NTP(网络时间协议)时间,单位为毫秒。
### 所属接口类 [#所属接口类-55]
- [AgoraRtePlayerObserver](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerobserver)
## onResolutionChanged\:height: [#onresolutionchangedheight]
视频分辨率变化的回调。
```objc
- (void)onResolutionChanged:(int)width height:(int)height;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
如果你需要监控播放器正在播放的视频流的分辨率变化,必须先调用 [registerObserver\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_registerobserver_player) 方法注册播放器观察者对象。
### 触发时机 [#触发时机-5]
该回调在视频流的分辨率发生变化时被触发,报告当前视频的宽度和高度。
### 参数 [#参数-54]
视频帧的宽度(像素)。
视频帧的高度(像素)。
### 所属接口类 [#所属接口类-56]
- [AgoraRtePlayerObserver](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerobserver)
## onStateChanged\:newState\:error: [#onstatechangednewstateerror]
播放器状态发生变化回调。
```objc
- (void)onStateChanged:(AgoraRtePlayerState)oldState newState:(AgoraRtePlayerState)newState error:(AgoraRteError * _Nullable)error;
```
:::info[自从]
自 v4.4.0 版本新增。
:::
如果你需要监听播放器状态的变化,必须先调用 [registerObserver\:error:](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_registerobserver_player) 方法注册播放器观察者对象。
### 触发时机 [#触发时机-6]
该回调在播放器状态发生变化时被触发,用于报告当前状态和之前的状态。
### 参数 [#参数-55]
变更前的播放器状态,详见 [AgoraRtePlayerState](/zh-CN/api-reference/rtc/ios/enum-rteplayerstate)。
当前的播放器状态,详见 [AgoraRtePlayerState](/zh-CN/api-reference/rtc/ios/enum-rteplayerstate)。如果当前状态为 `AgoraRtePlayerStateFailed`,你可以通过 `error` 参数获取详细的错误信息。
状态或错误信息,详见 [AgoraRteError](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-57]
- [AgoraRtePlayerObserver](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_playerobserver)