# URL 拉流播放 (/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## AbrSubscriptionLayer [#abrsubscriptionlayer]
获取当前订阅的视频层级。
```cpp
AbrSubscriptionLayer AbrSubscriptionLayer() const
```
:::info[自从]
自 v4.5.1 版本新增。
:::
:::note
注: 仅当你打开 RTE URL 时,该字段才有效。
:::
### 返回值 [#返回值]
方法调用成功,返回当前订阅的视频层级,详见 [RteAbrSubscriptionLayer](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rteabrsubscriptionlayer)。
### 所属接口类 [#所属接口类]
- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)
## AddView [#addview]
添加一个渲染视图。
```cpp
bool AddView(View *view, ViewConfig *config, rte::Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
当你需要使用播放器播放视频时,可以调用该方法向视频渲染器添加一个视图,以显示视频内容。
:::note
注: 当前仅支持一个视图。
:::
### 适用场景 [#适用场景]
当你需要使用播放器播放视频时,可以调用此方法将视图添加到视频渲染器中,以显示视频内容。
### 调用时机 [#调用时机]
该方法必须在调用 [SetCanvas](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_setcanvas) 之前调用。
### 参数 [#参数]
`HWND` 窗口句柄。
`View` 对象的设置,当前传入 NULL。
状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-1]
视图是否添加成功:
- true:视图添加成功。
- false:添加视图失败。
### 所属接口类 [#所属接口类-1]
- [Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvas)
## AudioBitsPerSample [#audiobitspersample]
获取每个音频采样的位数。
```cpp
int AudioBitsPerSample() const
```
:::info[自从]
自 v4.5.1 版本新增。
:::
:::note
注: 仅在打开非 `RTE` URL 时该字段有效。
:::
### 返回值 [#返回值-2]
方法调用成功,返回每个音频采样的位数,单位为 bit。
### 所属接口类 [#所属接口类-2]
- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)
## AudioChannels [#audiochannels]
获取音频的声道数。
```cpp
int AudioChannels() const
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 返回值 [#返回值-3]
方法调用成功,返回音频的声道数。
### 所属接口类 [#所属接口类-3]
- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)
## AudioSampleRate [#audiosamplerate]
获取音频采样率。
```cpp
int AudioSampleRate() const
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 返回值 [#返回值-4]
方法调用成功,返回音频采样率,单位为 Hz。
### 所属接口类 [#所属接口类-4]
- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)
## Canvas [#canvas]
构造一个 [Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_canvas_canvas_canvas) 对象。
```cpp
Canvas(Rte *rte, CanvasInitialConfig *initial_config = nullptr)
```
### 调用时机 [#调用时机-1]
在调用 [InitMediaEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_initmediaengine) 之后调用该方法。
### 参数 [#参数-1]
[Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rte) 对象。详见 [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rte)。
[Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_canvas_canvas_canvas) 的配置对象。该参数可传入 NULL。
### 所属接口类 [#所属接口类-5]
- [Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvas)
## Code [#code]
获取 API 调用失败时返回的错误码。
```cpp
ErrorCode Code() const
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-2]
当 API 调用失败时,可以调用此方法获取错误码。
### 返回值 [#返回值-5]
方法调用成功,返回错误码,详见 [RteErrorCode](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rteerrorcode)。
### 所属接口类 [#所属接口类-6]
- [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)
## CurrentUrl [#currenturl]
获取当前正在播放的 URL。
```cpp
std::string CurrentUrl() const
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 返回值 [#返回值-6]
- 方法调用成功时,返回当前正在播放的 URL。
- 方法调用失败,返回空字符串。
### 所属接口类 [#所属接口类-7]
- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)
## Destroy [#destroy]
销毁 `RTE` 对象。
```cpp
bool Destroy(Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 参数 [#参数-2]
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-7]
- true:销毁成功。
- false:销毁失败。
### 所属接口类 [#所属接口类-8]
- [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rte)
## Duration [#duration]
获取当前媒体资源的时长。
```cpp
size_t Duration() const
```
:::info[自从]
自 v4.5.1 版本新增。
:::
:::note
注: 仅在播放本地媒体文件或点播流时有效。
:::
### 返回值 [#返回值-8]
方法调用成功,返回当前媒体资源的时长,单位为毫秒。
### 所属接口类 [#所属接口类-9]
- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)
## GetAbrFallbackLayer [#getabrfallbacklayer]
获取已配置的视频流回退选项。
```cpp
AbrFallbackLayer GetAbrFallbackLayer(Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-3]
在调用 `GetConfigs` 之后调用该方法。
### 参数 [#参数-3]
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-9]
方法调用成功时,返回已配置的视频流回退选项,详见 [RteAbrFallbackLayer](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rteabrfallbacklayer)。
### 所属接口类 [#所属接口类-10]
- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)
## GetAbrSubscriptionLayer [#getabrsubscriptionlayer]
获取当前设置的已订阅视频流的质量层级。
```cpp
AbrSubscriptionLayer GetAbrSubscriptionLayer(Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-4]
在调用 `GetConfigs` 之后调用该方法。
### 参数 [#参数-4]
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-10]
方法调用成功,返回当前设置的视频质量层级,详见 [RteAbrSubscriptionLayer](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rteabrsubscriptionlayer)。
### 所属接口类 [#所属接口类-11]
- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)
## GetAppId [#getappid]
获取已配置的声网 App ID。
```cpp
std::string GetAppId(Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 参数 [#参数-5]
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-11]
- 方法调用成功时,返回已配置的声网 App ID。
- 方法调用失败,返回空字符串。
### 所属接口类 [#所属接口类-12]
- [Config](/zh-CN/api-reference/rtc/cpp-all-platforms/class-config)
## GetAutoPlay [#getautoplay]
获取播放器的自动播放设置。
```cpp
bool GetAutoPlay(Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-5]
在调用 `GetConfigs` 之后调用此方法。
### 参数 [#参数-6]
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-12]
是否成功获取自动播放设置:
- true:获取成功。
- false:获取失败。
### 所属接口类 [#所属接口类-13]
- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)
## GetConfigs [3/3] [#getconfigs-33]
获取当前播放器的视频渲染配置。
```cpp
bool GetConfigs(CanvasConfig *config, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-6]
在调用 [Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_canvas_canvas_canvas) 之后调用该方法。
### 参数 [#参数-7]
输出参数,表示 [Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_canvas_canvas_canvas) 对象的设置,详见 [CanvasConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvasconfig)。
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-13]
- true:获取成功。
- false:获取失败。
### 所属接口类 [#所属接口类-14]
- [Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvas)
## GetConfigs [2/3] [#getconfigs-23]
获取当前播放器配置。
```cpp
bool GetConfigs(PlayerConfig* config, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-7]
在调用 [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_player_player) 后调用该方法。
### 参数 [#参数-8]
输出参数,播放器配置对象。详见 [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)。
输出参数,状态或错误信息。详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-14]
- true:获取成功。
- false:获取失败。
### 所属接口类 [#所属接口类-15]
- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)
## GetConfigs [1/3] [#getconfigs-13]
获取 `RTE` 对象的配置信息。
```cpp
bool GetConfigs(Config *config, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-8]
在调用 [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_rte_rte) 之后调用该方法。
### 参数 [#参数-9]
输出参数,表示 `RTE` 对象的配置信息。详见 [Config](/zh-CN/api-reference/rtc/cpp-all-platforms/class-config)。
输出参数,状态或错误信息。详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-15]
- true:获取成功。
- false:获取失败。
### 所属接口类 [#所属接口类-16]
- [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rte)
## GetFromBridge [#getfrombridge]
从 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 中桥接一个 `RTE` 对象。
```cpp
static Rte GetFromBridge(Error* err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
通过该方法创建的 `RTE` 对象无需再调用 [InitMediaEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_initmediaengine) 进行初始化。如果尚未创建并初始化 RTC 引擎,可以先调用 [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_rte_rte) 创建一个 `RTE` 对象,再调用 [InitMediaEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_initmediaengine) 进行初始化。
### 调用时机 [#调用时机-9]
在调用此方法之前,请确保你已调用 [initialize](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#api_irtcengine_initialize) 初始化 RTC 引擎。
### 参数 [#参数-10]
输出参数,用于接收状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-16]
- 方法调用成功,返回一个 `RTE` 对象,详见 `RTE`。
- 方法调用失败,返回 NULL。
### 所属接口类 [#所属接口类-17]
- [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rte)
## GetInfo [#getinfo]
获取播放器和媒体流的信息。
```cpp
bool GetInfo(PlayerInfo *info, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
你可以使用该方法获取播放器和媒体流的详细信息,例如音频采样率、视频帧大小等。
### 调用时机 [#调用时机-10]
在调用 [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_player_player) 之后调用此方法。
### 参数 [#参数-11]
输出参数,表示播放器和媒体流的信息。详见 [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)。
输出参数,状态或错误信息。详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-17]
- true:获取成功。
- false:获取失败。
### 所属接口类 [#所属接口类-18]
- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)
## GetJsonParameter [#getjsonparameter]
获取已配置的 SDK JSON 配置信息。
```cpp
std::string GetJsonParameter(Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
调用 [SetJsonParameter](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_config_setjsonparameter_config) 设置 JSON 配置后,可调用本方法获取已配置的信息。
### 调用时机 [#调用时机-11]
必须在调用 `GetConfigs` 之后调用此方法。
### 参数 [#参数-12]
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-18]
- 方法调用成功时,返回已配置的 JSON 信息。
- 方法调用失败,返回空字符串。
### 所属接口类 [#所属接口类-19]
- [Config](/zh-CN/api-reference/rtc/cpp-all-platforms/class-config)
## GetLoopCount [#getloopcount]
获取媒体文件的循环次数。
```cpp
int32_t GetLoopCount(Error *err = nullptr)
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 参数 [#参数-13]
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-19]
方法调用成功,返回媒体文件的循环次数。
### 所属接口类 [#所属接口类-20]
- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)
## GetMirrorMode [#getmirrormode]
获取当前设置的视频镜像模式。
```cpp
VideoMirrorMode GetMirrorMode(Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-12]
该方法必须在调用 `GetConfigs` 之后调用。
### 参数 [#参数-14]
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-20]
方法调用成功,返回当前设置的镜像模式,详见 [RteVideoMirrorMode](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rtevideomirrormode)。
### 所属接口类 [#所属接口类-21]
- [CanvasConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvasconfig)
## GetPlaybackSpeed [#getplaybackspeed]
获取播放速度参数。
```cpp
int32_t GetPlaybackSpeed(Error *err = nullptr)
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 参数 [#参数-15]
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-21]
方法调用成功,返回播放速度值。
### 所属接口类 [#所属接口类-22]
- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)
## GetPlayoutVolume [#getplayoutvolume]
获取播放器的播放音量。
```cpp
int32_t GetPlayoutVolume(Error *err = nullptr)
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 参数 [#参数-16]
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-22]
方法调用成功,返回播放器的音量值。
### 所属接口类 [#所属接口类-23]
- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)
## GetPosition [#getposition]
获取当前播放位置。
```cpp
uint64_t GetPosition(Error *err = nullptr)
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 参数 [#参数-17]
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
- `kRteOk`:调用成功。
- `kRteErrorInvalidOperation`:
- 对应的内部 [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_player_player) 对象已被销毁或无效。
- 打开的 URL 是 RTE URL,不支持调用 [GetPosition](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_getposition)。
### 返回值 [#返回值-23]
方法调用成功,返回当前播放位置,单位为毫秒。
### 所属接口类 [#所属接口类-24]
- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)
## GetRenderMode [#getrendermode]
获取当前设置的视频渲染模式。
```cpp
VideoRenderMode GetRenderMode(Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-13]
该方法必须在调用 `GetConfigs` 之后调用。
### 参数 [#参数-18]
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-24]
当前设置的视频渲染模式,详见 [RteVideoRenderMode](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rtevideorendermode)。
### 所属接口类 [#所属接口类-25]
- [CanvasConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvasconfig)
## GetStats [#getstats]
获取播放器当前播放的媒体资源的统计信息。
```cpp
void GetStats(std::function cb)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
该方法通过回调异步返回播放器的统计信息,包括解码情况、渲染帧率、音视频码率等。
### 调用时机 [#调用时机-14]
该方法必须在调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 之后调用。
### 参数 [#参数-19]
异步通知获取播放器媒体资源统计信息结果的回调。你可以通过该回调的参数获取以下信息:
- `stats`:播放器当前播放媒体资源的统计数据,详见 [RtePlayerStats](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rteplayerstats)。
- `err`:状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-26]
- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)
## HasAudio [#hasaudio]
判断媒体资源中是否包含音频流。
```cpp
bool HasAudio() const
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 返回值 [#返回值-25]
- true:媒体资源中包含音频流。
- false:媒体资源中不包含音频流。
### 所属接口类 [#所属接口类-27]
- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)
## HasVideo [#hasvideo]
判断 URL 源中是否包含视频流。
```cpp
bool HasVideo() const
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 返回值 [#返回值-26]
- true:URL 源包含视频流。
- false:URL 源不包含视频流。
### 所属接口类 [#所属接口类-28]
- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)
## InitMediaEngine [#initmediaengine]
初始化 `RTE` 引擎。
```cpp
bool InitMediaEngine(std::function cb, Error *err = nullptr)
```
:::note
注: [InitMediaEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_initmediaengine) 的返回值仅表示初始化操作是否已成功加入异步任务队列,并不表示初始化本身是否成功。
:::
### 调用时机 [#调用时机-15]
该方法必须在创建 `RTE` 对象并设置 App ID 后调用。
### 参数 [#参数-20]
异步通知初始化结果的回调。你可以通过该回调的 `err` 参数获取初始化结果或错误码信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
输出参数,表示初始化过程中产生的状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。调用 [InitMediaEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_initmediaengine) 时,如果发生可立即检测的错误(如参数无效或资源不足),SDK 会通过该参数同步返回错误信息。
### 返回值 [#返回值-27]
- true:成功将初始化操作加入异步任务队列。
- false:未能将初始化操作加入异步任务队列。
该返回值仅表示初始化操作是否已成功加入异步任务队列,并不表示初始化本身是否成功。
### 所属接口类 [#所属接口类-29]
- [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rte)
## IsAudioMuted [#isaudiomuted]
判断播放器是否停止接收音频流。
```cpp
bool IsAudioMuted() const
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 返回值 [#返回值-28]
- true:播放器已停止接收音频流。
- false:播放器仍在接收音频流。
### 所属接口类 [#所属接口类-30]
- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)
## IsVideoMuted [#isvideomuted]
判断播放器是否停止接收视频流。
```cpp
bool IsVideoMuted() const
```
:::info[自从]
自 v4.5.1 版本新增。
:::
:::note
注: [IsVideoMuted](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rteplayerinfo_isvideomuted) 仅在打开 RTE URL 时有效。
:::
### 返回值 [#返回值-29]
- true:播放器已停止接收视频流。
- false:播放器仍在接收视频流。
### 所属接口类 [#所属接口类-31]
- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)
## Message [#message]
获取详细错误信息。
```cpp
const char *Message() const
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-16]
当 API 调用失败时,你可以调用该方法获取错误信息,以帮助排查问题。
### 返回值 [#返回值-30]
- 方法调用成功时,返回错误信息字符串。
- 方法调用失败,返回空字符串。
### 所属接口类 [#所属接口类-32]
- [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)
## MuteAudio [#muteaudio]
接收或停止接收音频流。
```cpp
bool MuteAudio(bool mute, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-17]
该方法必须在调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 之后调用。
### 相关回调 [#相关回调]
成功调用该方法后,SDK 会触发 `onPlayerInfoUpdated` 回调报告最新的播放器和媒体流信息。
### 参数 [#参数-21]
是否接收音频流:
- true:不接收音频流。
- false:接收音频流。
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-31]
true 表示操作成功,false 表示操作失败。
### 所属接口类 [#所属接口类-33]
- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)
## MuteVideo [#mutevideo]
接收或停止接收视频流。
```cpp
bool MuteVideo(bool mute, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-18]
该方法必须在调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 之后调用。
### 相关回调 [#相关回调-1]
成功调用该方法后,SDK 会触发 `onPlayerInfoUpdated` 回调报告最新的播放器和媒体流信息。
### 参数 [#参数-22]
是否接收视频流:
- true:不接收视频流。
- false:接收视频流。
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-32]
true 表示操作成功,false 表示操作失败。
### 所属接口类 [#所属接口类-34]
- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)
## OpenWithUrl [#openwithurl]
打开一个 URL 资源。
```cpp
void OpenWithUrl(const char* url, uint64_t start_time, std::function cb)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
该方法支持通过 URL 打开实时流媒体资源。如果你希望加快 URL 的打开速度,可以在调用该方法前调用 [PreloadWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_preloadwithurl) 预加载资源。如果资源打开失败,你将收到 [onStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#callback_playerobserver_onstatechanged) 回调,状态为 `kRtePlayerStateFailed`。此时,你需要先调用 [Stop](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_stop_player),然后再次调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 重新打开 URL 资源。如果你已关闭自动播放功能,可以在资源打开后调用 [Play](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_play_player) 开始播放。
:::note
注: 该方法目前仅支持以 `rte://` 开头的 URL、CDN 推流 URL 和本地媒体文件。
:::
### 调用时机 [#调用时机-19]
该方法必须在 [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_player_player) 初始化后调用。
### 相关回调 [#相关回调-2]
成功调用该方法后,SDK 会触发 [onStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#callback_playerobserver_onstatechanged) 回调报告播放器状态为 `kRtePlayerStateOpening`,表示正在打开 URL。打开成功后,播放器状态将报告为 `kRtePlayerStateOpenCompleted`。
### 参数 [#参数-23]
要打开的 URL,可以是 CDN 推流 URL、本地媒体文件,或以 `rte://` 开头的 URL。
开始播放的位置,单位为毫秒。
异步通知 URL 资源打开结果的回调。你可以通过该回调的 `err` 参数获取操作结果或错误码信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-35]
- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)
## Pause [#pause]
暂停播放。
```cpp
bool Pause(Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
调用 [Play](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_play_player) 播放 URL 资源后,可以调用此方法暂停播放。如果需要停止播放,请调用 [Stop](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_stop_player) 方法。
### 调用时机 [#调用时机-20]
该方法必须在调用 [Play](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_play_player) 之后调用。
### 相关回调 [#相关回调-3]
成功调用该方法后,SDK 会触发 [onStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#callback_playerobserver_onstatechanged) 回调报告播放器状态为 `kRtePlayerStatePaused`。
### 参数 [#参数-24]
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-33]
- true:暂停播放成功。
- false:暂停播放失败。
### 所属接口类 [#所属接口类-36]
- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)
## Play [#play]
播放一个 URL 资源。
```cpp
bool Play(Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
:::note
注: 该方法当前仅支持以 `rte://` 开头的 URL。
:::
### 调用时机 [#调用时机-21]
在收到 [onStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#callback_playerobserver_onstatechanged) 回调报告状态为 `kRtePlayerStateOpenCompleted` 后调用此方法。
### 参数 [#参数-25]
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-34]
播放是否成功:
- true:播放成功。
- false:播放失败。
### 所属接口类 [#所属接口类-37]
- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)
## Player [#player]
构造一个 [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_player_player) 播放器对象。
```cpp
explicit Player(Rte *self, PlayerInitialConfig *config = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-22]
该方法必须在调用 [InitMediaEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_initmediaengine) 之后调用。
### 参数 [#参数-26]
[Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rte) 对象。详见 [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rte)。
播放器的初始配置。你可以传入 NULL。
### 所属接口类 [#所属接口类-38]
- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)
## PreloadWithUrl [#preloadwithurl]
预加载 URL 资源。
```cpp
static bool PreloadWithUrl(const char* url, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
预加载成功后,通过 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 打开该 URL 资源的速度可以提升,从而减少等待时间,提升视听体验。
:::note
注: 该方法目前仅支持以 `rte://` 开头的 URL。最多可预加载 20 个 URL,若超过限制,最早预加载的 URL 会被新预加载的 URL 替换。
:::
### 适用场景 [#适用场景-1]
在打开媒体资源前预加载,可以减少用户等待时间,提供更流畅的视听体验。
### 调用时机 [#调用时机-23]
该方法必须在调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 之前调用。
### 参数 [#参数-27]
以 `rte://` 开头的 URL。
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-35]
是否预加载成功:
- true:预加载成功。
- false:预加载失败。
### 所属接口类 [#所属接口类-39]
- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)
## RegisterObserver [#registerobserver]
注册一个 [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver) 播放器观察者对象。
```cpp
bool RegisterObserver(PlayerObserver *observer, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
在调用该方法前,你需要实现一个继承自 [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver) 的接口类。
### 调用时机 [#调用时机-24]
该方法必须在调用 [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_player_player) 之后执行。
### 参数 [#参数-28]
[PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver) 接口对象的实例。详见 [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver)。
输出参数,状态或错误信息。详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-36]
是否注册成功:
- true:注册成功。
- false:注册失败。
### 所属接口类 [#所属接口类-40]
- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)
## RemoveView [#removeview]
移除一个渲染视图。
```cpp
bool RemoveView(View *view, ViewConfig *config, rte::Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
调用 [AddView](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_canvas_addview) 添加视图后,如有需要,可以调用该方法移除该视图。
:::note
注: 每次只能移除一个视图。
:::
### 调用时机 [#调用时机-25]
该方法必须在调用 [AddView](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_canvas_addview) 之后调用。
### 参数 [#参数-29]
要移除的视图对象。
视图对象的设置,目前传入 NULL。
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-37]
- true:视图移除成功。
- false:视图移除失败。
### 所属接口类 [#所属接口类-41]
- [Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvas)
## Rte [#rte]
构造一个 [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_rte_rte) 对象。
```cpp
explicit Rte(InitialConfig *config = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-26]
该方法必须在调用 [InitMediaEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_initmediaengine) 之前调用。
### 参数 [#参数-30]
初始化设置。你可以传入 NULL。详见 `InitialConfig`。
### 所属接口类 [#所属接口类-42]
- [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rte)
## Seek [#seek]
跳转到新的播放位置。
```cpp
bool Seek(uint64_t new_time, Error *err = nullptr)
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 参数 [#参数-31]
要跳转到的新播放位置。
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
- `kRteOk`:成功。
- `kRteErrorInvalidOperation`:
- 对应的内部 [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_player_player) 对象已被销毁或无效。
- 打开的 URL 是 RTE URL,不支持跳转。
### 返回值 [#返回值-38]
- true:成功跳转到播放位置。
- false:跳转失败。
### 所属接口类 [#所属接口类-43]
- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)
## SetAbrFallbackLayer [#setabrfallbacklayer]
设置已订阅视频流的回退选项。
```cpp
void SetAbrFallbackLayer(AbrFallbackLayer abr_fallback_layer, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
在网络状况较差时,SDK 会将视频流的分辨率降级为指定的回退质量层,以保证播放的连续性。不同的质量层对应不同的分辨率和码率。SDK 会持续监测网络状况,在网络恢复后自动将视频流恢复为订阅的质量层。
默认情况下,仅支持回退到 `kRteAbrFallbackLow` 或 `kRteAbrFallbackAudioOnly`。如需更灵活的视频体验,可[联系技术支持](https://ticket.shengwang.cn/)开启 ABR 功能,开启后可回退到所有质量层,并自定义每一层的分辨率。
:::note
注: 如果在调用该方法时未开启 ABR 功能,视频流的回退质量层只能为 `kRteAbrFallbackLow` 或 `kRteAbrFallbackAudioOnly`。
:::
### 适用场景 [#适用场景-2]
一般场景下,可调用该方法并将回退质量层设置为 `kRteAbrFallbackLow` 或 `kRteAbrFallbackAudioOnly`。当网络较差时,SDK 会回退为视频小流或仅接收音频流。
如果对回退视频流的分辨率有更高要求,可[联系技术支持](https://ticket.shengwang.cn/)开启 ABR 功能。开启后,可自定义每一层的分辨率。SDK 会以你指定的最低质量层的分辨率为下限,并根据网络状况在该范围内动态调整分辨率。
### 调用时机 [#调用时机-27]
该方法必须在调用 `SetConfigs` 之前调用。
### 参数 [#参数-32]
视频流的回退质量层,详见 [RteAbrFallbackLayer](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rteabrfallbacklayer)。当自定义 `kRteAbrFallbackLayer1` 到 `kRteAbrFallbackLayer6` 的分辨率时,可参考下表:
:::note
注: 自定义分辨率时,务必将视频质量层按分辨率从高到低排序;当分辨率相同时,按帧率从高到低排序。
:::
| 视频质量层 | 分辨率 |
| --- | --- |
| `kRteAbrSubscriptionLayer1` | 2160p (4K) |
| `kRteAbrSubscriptionLayer2` | 1440p (2K) |
| `kRteAbrSubscriptionLayer3` | 1080p (HD) |
| `kRteAbrSubscriptionLayer4` | 720p (HD) |
| `kRteAbrSubscriptionLayer5` | 540p (SD) |
| `kRteAbrSubscriptionLayer6` | 480p (SD) |
状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-44]
- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)
## SetAbrSubscriptionLayer [#setabrsubscriptionlayer]
设置订阅媒体流的视频质量层级。
```cpp
void SetAbrSubscriptionLayer(AbrSubscriptionLayer abr_subscription_layer, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
你可以根据实际网络状况在不同的视频流质量层级之间切换,每个层级对应不同的分辨率。默认情况下,调用该方法后,订阅端只能在高低画质之间切换,即 `kRteAbrSubscriptionHigh` 和 `kRteAbrSubscriptionLow`。如果你对视频分辨率切换有更高要求,可以[联系技术支持](https://ticket.shengwang.cn/)开启 ABR(自适应码率)功能。开启后,你可以自定义每个视频质量层级的分辨率,订阅端可根据需要在所有视频质量层级之间切换。
:::note
注: 如果在调用该方法时未开启 ABR 功能,订阅的视频质量层级只能为 `kRteAbrSubscriptionHigh` 或 `kRteAbrSubscriptionLow`。
:::
### 适用场景 [#适用场景-3]
在网络环境不稳定的场景中,订阅端可根据实际网络状况选择合适的视频质量层级,以保障流畅的观看体验。
### 调用时机 [#调用时机-28]
该方法必须在调用 `SetConfigs` 之前调用。
### 参数 [#参数-33]
要订阅的视频质量层级,详见 [RteAbrSubscriptionLayer](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rteabrsubscriptionlayer)。当自定义 `kRteAbrSubscriptionLayer1` 到 `kRteAbrSubscriptionLayer6` 的分辨率时,可参考下表或根据实际需求设置:
注意:自定义分辨率时,需确保视频质量层级按分辨率从高到低排序;当分辨率相同时,按帧率从高到低排序。
| 视频质量层级 | 分辨率 |
| --- | --- |
| `kRteAbrSubscriptionLayer1` | 2160p (4K) |
| `kRteAbrSubscriptionLayer2` | 1440p (2K) |
| `kRteAbrSubscriptionLayer3` | 1080p (HD) |
| `kRteAbrSubscriptionLayer4` | 720p (HD) |
| `kRteAbrSubscriptionLayer5` | 540p (SD) |
| `kRteAbrSubscriptionLayer6` | 480p (SD) |
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-45]
- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)
## SetAppId [#setappid]
设置声网 App ID。
```cpp
void SetAppId(const char *app_id, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-29]
该方法必须在调用 [InitMediaEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_initmediaengine) 之前调用。
### 参数 [#参数-34]
你的项目的声网 App ID,可从声网控制台获取。
输出参数,状态或错误信息。详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-46]
- [Config](/zh-CN/api-reference/rtc/cpp-all-platforms/class-config)
## SetAutoPlay [#setautoplay]
设置是否自动播放。
```cpp
void SetAutoPlay(bool auto_play, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
在调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 打开媒体流之前,可以调用该方法设置是否自动播放。如果未设置,默认启用自动播放。
### 调用时机 [#调用时机-30]
该方法必须在调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 之前调用。
### 参数 [#参数-35]
是否启用自动播放:
- true:(默认)启用自动播放。
- false:不启用自动播放。
输出参数,表示状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-47]
- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)
## SetCanvas [#setcanvas]
设置用于显示视频的视图窗口。
```cpp
bool SetCanvas(Canvas *canvas, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
该方法用于指定一个 `Canvas` 对象用于显示视频。一旦视频流成功播放,视频将显示在该 [Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvas) 上。
### 调用时机 [#调用时机-31]
该方法必须在调用 [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_player_player) 之后执行。
### 参数 [#参数-36]
[Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvas) 对象,用于渲染视频帧,详见 [Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvas)。
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-39]
- true:设置成功。
- false:设置失败。你可以通过 `err` 参数返回的错误码查看详细信息。
### 所属接口类 [#所属接口类-48]
- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)
## SetConfigs [3/3] [#setconfigs-33]
设置播放器的视频渲染配置。
```cpp
bool SetConfigs(CanvasConfig *config, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-32]
该方法必须在调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 之前调用。
### 参数 [#参数-37]
用于设置 [Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_canvas_canvas_canvas) 对象的配置,详见 [CanvasConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvasconfig)。
状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-40]
配置是否成功:
- true:配置成功。
- false:配置失败。
### 所属接口类 [#所属接口类-49]
- [Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvas)
## SetConfigs [2/3] [#setconfigs-23]
配置播放器。
```cpp
bool SetConfigs(PlayerConfig* config, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
你可以调用该方法配置播放器,例如启用自动播放、订阅不同分辨率和码率的视频流等。
### 调用时机 [#调用时机-33]
该方法必须在调用 [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_player_player) 之后执行。
### 参数 [#参数-38]
播放器配置对象,详见 [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)。
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-41]
配置是否成功:
- true:配置成功。
- false:配置失败。
### 所属接口类 [#所属接口类-50]
- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)
## SetConfigs [1/3] [#setconfigs-13]
配置 `RTE` 对象的信息。
```cpp
bool SetConfigs(Config *config, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
你可以调用该方法设置如 App ID 等信息。
### 调用时机 [#调用时机-34]
该方法必须在调用 [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_rte_rte) 之后执行。
### 参数 [#参数-39]
`RTE` 对象的设置信息,详见 [Config](/zh-CN/api-reference/rtc/cpp-all-platforms/class-config)。
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-42]
- true:配置成功。
- false:配置失败。
### 所属接口类 [#所属接口类-51]
- [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rte)
## SetJsonParameter [#setjsonparameter]
使用 JSON 配置 SDK 的技术预览或自定义功能。
```cpp
void SetJsonParameter(const char *json_parameter, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
你可以在需要设置私有参数或使用自定义功能时调用此方法。
### 适用场景 [#适用场景-4]
当你需要设置私有参数或使用定制化功能时,可以调用此方法。
### 调用时机 [#调用时机-35]
该方法必须在调用 `SetConfigs` 之前调用。
### 参数 [#参数-40]
JSON 字符串格式的参数。
输出参数,表示状态或错误信息。详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-52]
- [Config](/zh-CN/api-reference/rtc/cpp-all-platforms/class-config)
## SetLoopCount [#setloopcount]
设置媒体文件播放的循环次数。
```cpp
void SetLoopCount(int32_t count, Error *err = nullptr)
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 参数 [#参数-41]
媒体文件的循环播放次数。
- `1`:播放一次。
- `2`:播放两次。
- `-1`:无限循环播放,直到调用 [Stop](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_stop_player)。
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
- `kRteOk`:调用成功。
- `kRteErrorInvalidArgument`:`count` 参数设置为无效值。
### 所属接口类 [#所属接口类-53]
- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)
## SetMirrorMode [#setmirrormode]
设置视频的镜像模式。
```cpp
void SetMirrorMode(VideoMirrorMode mode, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-36]
该方法必须在调用 `SetConfigs` 之前调用。
### 参数 [#参数-42]
镜像模式,详见 [RteVideoMirrorMode](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rtevideomirrormode)。
- 默认值为 `kRteVideoMirrorModeAuto`,由 SDK 自动决定镜像模式。
- 默认情况下,远端用户的镜像模式为关闭状态。
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-54]
- [CanvasConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvasconfig)
## SetPlaybackSpeed [#setplaybackspeed]
设置播放速度参数。
```cpp
void SetPlaybackSpeed(int32_t speed, Error *err = nullptr)
```
:::info[自从]
自 v4.5.1 版本新增。
:::
:::note
注: 你可以在调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 方法之后调用此方法。
:::
### 参数 [#参数-43]
播放速度。有效范围为 [50, 400]。
状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
- `kRteOk`:调用成功。
- `kRteErrorInvalidArgument`:`speed` 参数设置为无效值。
### 所属接口类 [#所属接口类-55]
- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)
## SetPlayoutVolume [#setplayoutvolume]
设置播放音量。
```cpp
void SetPlayoutVolume(int32_t volume, Error *err = nullptr)
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 参数 [#参数-44]
要设置的播放音量,取值范围为 [0, 400]。
状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
- `kRteOk`:设置成功。
- `kRteErrorInvalidArgument`:音量参数设置为无效值。
### 所属接口类 [#所属接口类-56]
- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)
## SetRenderMode [#setrendermode]
设置视频渲染模式。
```cpp
void SetRenderMode(VideoRenderMode mode, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 调用时机 [#调用时机-37]
该方法必须在调用 `SetConfigs` 之前调用。
### 参数 [#参数-45]
渲染模式,详见 [RteVideoRenderMode](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rtevideorendermode)。默认值为 `kRteVideoRenderModeHidden`,该模式按比例缩放视频并优先填满视图窗口。
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-57]
- [CanvasConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvasconfig)
## State [#state]
获取当前播放器状态。
```cpp
RtePlayerState State() const
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 返回值 [#返回值-43]
方法调用成功时,返回当前播放器状态,详见 [RtePlayerState](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rteplayerstate)。
### 所属接口类 [#所属接口类-58]
- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)
## Stop [#stop]
停止媒体播放。
```cpp
bool Stop(Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
成功调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 和 [Play](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_play_player) 后,可以调用该方法停止播放。如果希望暂停播放,请调用 [Pause](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_pause_player) 方法。如果使用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 打开 URL 流失败,则需要先调用该方法,再重新调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 以重新打开 URL。
### 调用时机 [#调用时机-38]
此方法必须在调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 之后调用。
### 相关回调 [#相关回调-4]
成功调用该方法后,SDK 会触发 [onStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#callback_playerobserver_onstatechanged) 回调并报告播放器状态为 `kRtePlayerStateStopped`。
### 参数 [#参数-46]
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-44]
- true:成功停止播放。
- false:停止播放失败。
### 所属接口类 [#所属接口类-59]
- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)
## StreamCount [#streamcount]
获取当前播放源中的流数量。
```cpp
size_t StreamCount() const
```
:::info[自从]
自 v4.5.1 版本新增。
:::
:::note
注: [StreamCount](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rteplayerinfo_streamcount) 方法在打开非 `RTE` URL 时有效。
:::
### 返回值 [#返回值-45]
方法调用成功,返回当前播放源中的流数量。
### 所属接口类 [#所属接口类-60]
- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)
## SwitchWithUrl [#switchwithurl]
在播放过程中切换到新的 URL。
```cpp
void SwitchWithUrl(const char* url, bool sync_pts, std::function cb)
```
:::info[自从]
自 v4.5.1 版本新增。
:::
:::note
注: 该方法仅在播放器已打开非 `RTE` URL 时有效。请在 SDK 报告播放器状态为 `kRtePlayerStateOpenCompleted` 时调用该方法。
:::
### 参数 [#参数-47]
要切换到的新 URL。
是否同步播放位置:
- true:同步播放位置。
- false:(默认)不同步播放位置。
异步通知切换操作结果的回调。你可以通过该回调的 `err` 参数得知操作的结果或错误码信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
`err` 的可能取值包括:
- `kRteOk`:切换成功。
- `kRteErrorDefault`:切换失败。
- `kRteErrorInvalidArgument`:提供的 URL 为空或格式无效。
- `kRteErrorInvalidOperation`:
- 对应的内部 [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_player_player) 对象已被销毁或无效。
- 当前打开的 URL 是 `RTE` URL,不支持切换。
### 所属接口类 [#所属接口类-61]
- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)
## UnregisterObserver [#unregisterobserver]
取消注册播放器事件观察者对象。
```cpp
bool UnregisterObserver(PlayerObserver *observer, Error *err = nullptr)
```
:::info[自从]
自 v4.4.0 版本新增。
:::
调用 [RegisterObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_registerobserver_player) 注册播放器事件观察者后,如需取消注册,可调用该方法。
### 调用时机 [#调用时机-39]
该方法必须在调用 [RegisterObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_registerobserver_player) 之后调用。
### 参数 [#参数-48]
播放器事件观察者对象实例,详见 [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver)。
输出参数,状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 返回值 [#返回值-46]
- true:取消注册成功。
- false:取消注册失败。
### 所属接口类 [#所属接口类-62]
- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)
## VideoHeight [#videoheight]
获取视频分辨率的高度。
```cpp
int VideoHeight() const
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 返回值 [#返回值-47]
方法调用成功,返回视频分辨率的高度,单位为像素。
### 所属接口类 [#所属接口类-63]
- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)
## VideoWidth [#videowidth]
获取视频分辨率的宽度。
```cpp
int VideoWidth() const
```
:::info[自从]
自 v4.5.1 版本新增。
:::
### 返回值 [#返回值-48]
方法调用成功,返回视频分辨率的宽度,单位为像素。
### 所属接口类 [#所属接口类-64]
- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)
## onAudioVolumeIndication [#onaudiovolumeindication]
[onAudioVolumeIndication](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#callback_playerobserver_onaudiovolumeindication_playerobserver) 回调。播放器音量变化时触发。
```cpp
virtual void onAudioVolumeIndication(int32_t volume) {}
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 触发时机 [#触发时机]
当播放器的音量发生变化时,SDK 会触发该回调。
### 参数 [#参数-49]
播放器当前的音量,取值范围为 [0, 225]。
### 所属接口类 [#所属接口类-65]
- [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver)
## onEvent [#onevent]
播放器事件回调。
```cpp
virtual void onEvent(PlayerEvent event) {}
```
:::info[自从]
自 v4.4.0 版本新增。
:::
调用 [RegisterObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_registerobserver_player) 注册播放器观察者对象后,才能监听播放器事件。
### 触发时机 [#触发时机-1]
当播放器事件发生时,SDK 会触发该回调。
### 参数 [#参数-50]
播放器事件,详见 [RtePlayerEvent](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rteplayerevent)。
### 所属接口类 [#所属接口类-66]
- [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver)
## onMetadata [2/2] [#onmetadata-22]
接收媒体流中元数据的回调。
```cpp
virtual void onMetadata(PlayerMetadataType type, const uint8_t *data, size_t length) {}
```
:::info[自从]
自 v4.4.0 版本新增。
:::
如果你需要从媒体流中获取元数据,必须先调用 [RegisterObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_registerobserver_player) 注册播放器观察者对象。
### 触发时机 [#触发时机-2]
当 SDK 从正在播放的媒体流中解析出元数据后,会触发该回调报告元数据类型及其内容。
### 参数 [#参数-51]
元数据类型,详见 [RtePlayerMetadataType](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rteplayermetadatatype)。
解析后的元数据内容。
数据的字节大小。
### 所属接口类 [#所属接口类-67]
- [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver)
## onPlayerInfoUpdated [2/2] [#onplayerinfoupdated-22]
播放器或媒体流信息发生变化时触发的回调。
```cpp
virtual void onPlayerInfoUpdated(const PlayerInfo *info) {}
```
:::info[自从]
自 v4.4.0 版本新增。
:::
如果你需要获取播放器和媒体流的信息,必须先调用 [RegisterObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_registerobserver_player) 注册播放器观察者对象。你也可以直接调用 [GetInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_getinfo) 获取信息。
### 触发时机 [#触发时机-3]
当播放器或媒体流的信息发生变化时,SDK 会触发此回调。
### 参数 [#参数-52]
播放器和媒体流的信息。详见 [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)。
### 所属接口类 [#所属接口类-68]
- [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver)
## onPositionChanged [#onpositionchanged]
播放进度变化回调。
```cpp
virtual void onPositionChanged(uint64_t curr_time, uint64_t utc_time) {}
```
:::info[自从]
自 v4.4.0 版本新增。
:::
### 触发时机 [#触发时机-4]
该回调在媒体播放过程中每秒触发一次。
### 参数 [#参数-53]
当前播放进度,单位为毫秒。
当前 NTP(网络时间协议)时间,单位为毫秒。
### 所属接口类 [#所属接口类-69]
- [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver)
## onResolutionChanged [#onresolutionchanged]
视频分辨率发生变化时触发的回调。
```cpp
virtual void onResolutionChanged(int width, int height) {}
```
:::info[自从]
自 v4.4.0 版本新增。
:::
如果你需要监控播放器播放的视频流的分辨率变化,必须先调用 [RegisterObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_registerobserver_player) 注册播放器观察者对象。
### 触发时机 [#触发时机-5]
当视频流的分辨率发生变化时,SDK 会触发该回调以报告当前视频的宽度和高度。
### 参数 [#参数-54]
视频帧的宽度(像素)。
视频帧的高度(像素)。
### 所属接口类 [#所属接口类-70]
- [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver)
## onStateChanged [#onstatechanged]
播放器状态发生变化时触发的回调。
```cpp
virtual void onStateChanged(PlayerState old_state, PlayerState new_state, rte::Error *err) {}
```
:::info[自从]
自 v4.4.0 版本新增。
:::
如果你需要监听播放器状态的变化,必须先调用 [RegisterObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_registerobserver_player) 注册播放器观察者对象。
### 触发时机 [#触发时机-6]
当播放器状态发生变化时,SDK 会触发该回调以报告当前状态和之前的状态。
### 参数 [#参数-55]
播放器之前的状态,详见 [RtePlayerState](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rteplayerstate)。
播放器当前的状态,详见 [RtePlayerState](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rteplayerstate)。如果当前状态为 `kRtePlayerStateFailed`,你可以通过 `err` 参数获取详细的错误信息。
状态或错误信息,详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。
### 所属接口类 [#所属接口类-71]
- [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver)