# 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).

<a id="toc_rte_player"></a>

<a id="api_rteplayerinfo_abrsubscriptionlayer"></a>

<a id="ariaid-title2"></a>

## AbrSubscriptionLayer [#abrsubscriptionlayer]

获取当前订阅的视频层级。

<a id="api_rteplayerinfo_abrsubscriptionlayer__prototype"></a>

```cpp
AbrSubscriptionLayer AbrSubscriptionLayer() const
```

<a id="api_rteplayerinfo_abrsubscriptionlayer__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

:::note
注： 仅当你打开 RTE URL 时，该字段才有效。
:::

<a id="api_rteplayerinfo_abrsubscriptionlayer__return_values"></a>

### 返回值 [#返回值]

方法调用成功，返回当前订阅的视频层级，详见 [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)

<a id="api_canvas_addview"></a>

<a id="ariaid-title3"></a>

## AddView [#addview]

添加一个渲染视图。

<a id="api_canvas_addview__prototype"></a>

```cpp
bool AddView(View *view, ViewConfig *config, rte::Error *err = nullptr)
```

<a id="api_canvas_addview__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

当你需要使用播放器播放视频时，可以调用该方法向视频渲染器添加一个视图，以显示视频内容。

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

<a id="api_canvas_addview__scenario"></a>

### 适用场景 [#适用场景]

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

<a id="api_canvas_addview__timing"></a>

### 调用时机 [#调用时机]

该方法必须在调用 [SetCanvas](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_setcanvas) 之前调用。

<a id="api_canvas_addview__parameters"></a>

### 参数 [#参数]

<ParameterList>
<a id="view"></a>
<Parameter name="view">

`HWND` 窗口句柄。

</Parameter>
<a id="config"></a>
<Parameter name="config">

`View` 对象的设置，当前传入 NULL。

</Parameter>
<a id="err"></a>
<Parameter name="err">

状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_canvas_addview__return_values"></a>

### 返回值 [#返回值-1]

视图是否添加成功：

- true：视图添加成功。
- false：添加视图失败。

### 所属接口类 [#所属接口类-1]

- [Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvas)

<a id="api_rteplayerinfo_audiobitspersample"></a>

<a id="ariaid-title4"></a>

## AudioBitsPerSample [#audiobitspersample]

获取每个音频采样的位数。

<a id="api_rteplayerinfo_audiobitspersample__prototype"></a>

```cpp
int AudioBitsPerSample() const
```

<a id="api_rteplayerinfo_audiobitspersample__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

:::note
注： 仅在打开非 `RTE` URL 时该字段有效。
:::

<a id="api_rteplayerinfo_audiobitspersample__return_values"></a>

### 返回值 [#返回值-2]

方法调用成功，返回每个音频采样的位数，单位为 bit。

### 所属接口类 [#所属接口类-2]

- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)

<a id="api_rteplayerinfo_audiochannels"></a>

<a id="ariaid-title5"></a>

## AudioChannels [#audiochannels]

获取音频的声道数。

<a id="api_rteplayerinfo_audiochannels__prototype"></a>

```cpp
int AudioChannels() const
```

<a id="api_rteplayerinfo_audiochannels__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

<a id="api_rteplayerinfo_audiochannels__return_values"></a>

### 返回值 [#返回值-3]

方法调用成功，返回音频的声道数。

### 所属接口类 [#所属接口类-3]

- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)

<a id="api_rteplayerinfo_audiosamplerate"></a>

<a id="ariaid-title6"></a>

## AudioSampleRate [#audiosamplerate]

获取音频采样率。

<a id="api_rteplayerinfo_audiosamplerate__prototype"></a>

```cpp
int AudioSampleRate() const
```

<a id="api_rteplayerinfo_audiosamplerate__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

<a id="api_rteplayerinfo_audiosamplerate__return_values"></a>

### 返回值 [#返回值-4]

方法调用成功，返回音频采样率，单位为 Hz。

### 所属接口类 [#所属接口类-4]

- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)

<a id="api_canvas_canvas_canvas"></a>

<a id="ariaid-title7"></a>

## Canvas [#canvas]

构造一个 [Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_canvas_canvas_canvas) 对象。

<a id="api_canvas_canvas_canvas__prototype"></a>

```cpp
Canvas(Rte *rte, CanvasInitialConfig *initial_config = nullptr)
```

<a id="api_canvas_canvas_canvas__detailed_desc"></a>

<a id="api_canvas_canvas_canvas__timing"></a>

### 调用时机 [#调用时机-1]

在调用 [InitMediaEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_initmediaengine) 之后调用该方法。

<a id="api_canvas_canvas_canvas__parameters"></a>

### 参数 [#参数-1]

<ParameterList>
<a id="rte"></a>
<Parameter name="rte">

[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)。

</Parameter>
<a id="initial_config"></a>
<Parameter name="initial_config">

[Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_canvas_canvas_canvas) 的配置对象。该参数可传入 NULL。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-5]

- [Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvas)

<a id="api_error_code"></a>

<a id="ariaid-title8"></a>

## Code [#code]

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

<a id="api_error_code__prototype"></a>

```cpp
ErrorCode Code() const
```

<a id="api_error_code__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_error_code__timing"></a>

### 调用时机 [#调用时机-2]

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

<a id="api_error_code__return_values"></a>

### 返回值 [#返回值-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)

<a id="api_rteplayerinfo_currenturl"></a>

<a id="ariaid-title9"></a>

## CurrentUrl [#currenturl]

获取当前正在播放的 URL。

<a id="api_rteplayerinfo_currenturl__prototype"></a>

```cpp
std::string CurrentUrl() const
```

<a id="api_rteplayerinfo_currenturl__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

<a id="api_rteplayerinfo_currenturl__return_values"></a>

### 返回值 [#返回值-6]

- 方法调用成功时，返回当前正在播放的 URL。
- 方法调用失败，返回空字符串。

### 所属接口类 [#所属接口类-7]

- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)

<a id="api_rte_destroy_rte"></a>

<a id="ariaid-title10"></a>

## Destroy [#destroy]

销毁 `RTE` 对象。

<a id="api_rte_destroy_rte__prototype"></a>

```cpp
bool Destroy(Error *err = nullptr)
```

<a id="api_rte_destroy_rte__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_rte_destroy_rte__parameters"></a>

### 参数 [#参数-2]

<ParameterList>
<a id="err-1"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_rte_destroy_rte__return_values"></a>

### 返回值 [#返回值-7]

- true：销毁成功。
- false：销毁失败。

### 所属接口类 [#所属接口类-8]

- [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rte)

<a id="api_rteplayerinfo_duration"></a>

<a id="ariaid-title11"></a>

## Duration [#duration]

获取当前媒体资源的时长。

<a id="api_rteplayerinfo_duration__prototype"></a>

```cpp
size_t Duration() const
```

<a id="api_rteplayerinfo_duration__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

:::note
注： 仅在播放本地媒体文件或点播流时有效。
:::

<a id="api_rteplayerinfo_duration__return_values"></a>

### 返回值 [#返回值-8]

方法调用成功，返回当前媒体资源的时长，单位为毫秒。

### 所属接口类 [#所属接口类-9]

- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)

<a id="api_playerconfig_getabrfallbacklayer"></a>

<a id="ariaid-title12"></a>

## GetAbrFallbackLayer [#getabrfallbacklayer]

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

<a id="api_playerconfig_getabrfallbacklayer__prototype"></a>

```cpp
AbrFallbackLayer GetAbrFallbackLayer(Error *err = nullptr)
```

<a id="api_playerconfig_getabrfallbacklayer__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_playerconfig_getabrfallbacklayer__timing"></a>

### 调用时机 [#调用时机-3]

在调用 `GetConfigs` 之后调用该方法。

<a id="api_playerconfig_getabrfallbacklayer__parameters"></a>

### 参数 [#参数-3]

<ParameterList>
<a id="err-2"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_playerconfig_getabrfallbacklayer__return_values"></a>

### 返回值 [#返回值-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)

<a id="api_playerconfig_getabrsubscriptionlayer"></a>

<a id="ariaid-title13"></a>

## GetAbrSubscriptionLayer [#getabrsubscriptionlayer]

获取当前设置的已订阅视频流的质量层级。

<a id="api_playerconfig_getabrsubscriptionlayer__prototype"></a>

```cpp
AbrSubscriptionLayer GetAbrSubscriptionLayer(Error *err = nullptr)
```

<a id="api_playerconfig_getabrsubscriptionlayer__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_playerconfig_getabrsubscriptionlayer__timing"></a>

### 调用时机 [#调用时机-4]

在调用 `GetConfigs` 之后调用该方法。

<a id="api_playerconfig_getabrsubscriptionlayer__parameters"></a>

### 参数 [#参数-4]

<ParameterList>
<a id="err-3"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_playerconfig_getabrsubscriptionlayer__return_values"></a>

### 返回值 [#返回值-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)

<a id="api_config_getappid"></a>

<a id="ariaid-title14"></a>

## GetAppId [#getappid]

获取已配置的声网 App ID。

<a id="api_config_getappid__prototype"></a>

```cpp
std::string GetAppId(Error *err = nullptr)
```

<a id="api_config_getappid__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_config_getappid__parameters"></a>

### 参数 [#参数-5]

<ParameterList>
<a id="err-4"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_config_getappid__return_values"></a>

### 返回值 [#返回值-11]

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

### 所属接口类 [#所属接口类-12]

- [Config](/zh-CN/api-reference/rtc/cpp-all-platforms/class-config)

<a id="api_playerconfig_getautoplay"></a>

<a id="ariaid-title15"></a>

## GetAutoPlay [#getautoplay]

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

<a id="api_playerconfig_getautoplay__prototype"></a>

```cpp
bool GetAutoPlay(Error *err = nullptr)
```

<a id="api_playerconfig_getautoplay__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_playerconfig_getautoplay__timing"></a>

### 调用时机 [#调用时机-5]

在调用 `GetConfigs` 之后调用此方法。

<a id="api_playerconfig_getautoplay__parameters"></a>

### 参数 [#参数-6]

<ParameterList>
<a id="err-5"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_playerconfig_getautoplay__return_values"></a>

### 返回值 [#返回值-12]

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

- true：获取成功。
- false：获取失败。

### 所属接口类 [#所属接口类-13]

- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)

<a id="api_canvas_getconfigs_canvas"></a>

<a id="ariaid-title16"></a>

## GetConfigs [3/3] [#getconfigs-33]

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

<a id="api_canvas_getconfigs_canvas__prototype"></a>

```cpp
bool GetConfigs(CanvasConfig *config, Error *err = nullptr)
```

<a id="api_canvas_getconfigs_canvas__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_canvas_getconfigs_canvas__timing"></a>

### 调用时机 [#调用时机-6]

在调用 [Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_canvas_canvas_canvas) 之后调用该方法。

<a id="api_canvas_getconfigs_canvas__parameters"></a>

### 参数 [#参数-7]

<ParameterList>
<a id="config-1"></a>
<Parameter name="config">

输出参数，表示 [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)。

</Parameter>
<a id="err-6"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_canvas_getconfigs_canvas__return_values"></a>

### 返回值 [#返回值-13]

- true：获取成功。
- false：获取失败。

### 所属接口类 [#所属接口类-14]

- [Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvas)

<a id="api_player_getconfigs_player"></a>

<a id="ariaid-title17"></a>

## GetConfigs [2/3] [#getconfigs-23]

获取当前播放器配置。

<a id="api_player_getconfigs_player__prototype"></a>

```cpp
bool GetConfigs(PlayerConfig* config, Error *err = nullptr)
```

<a id="api_player_getconfigs_player__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_player_getconfigs_player__timing"></a>

### 调用时机 [#调用时机-7]

在调用 [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_player_player) 后调用该方法。

<a id="api_player_getconfigs_player__parameters"></a>

### 参数 [#参数-8]

<ParameterList>
<a id="config-2"></a>
<Parameter name="config">

输出参数，播放器配置对象。详见 [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)。

</Parameter>
<a id="err-7"></a>
<Parameter name="err">

输出参数，状态或错误信息。详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_player_getconfigs_player__return_values"></a>

### 返回值 [#返回值-14]

- true：获取成功。
- false：获取失败。

### 所属接口类 [#所属接口类-15]

- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)

<a id="api_rte_getconfigs_rte"></a>

<a id="ariaid-title18"></a>

## GetConfigs [1/3] [#getconfigs-13]

获取 `RTE` 对象的配置信息。

<a id="api_rte_getconfigs_rte__prototype"></a>

```cpp
bool GetConfigs(Config *config, Error *err = nullptr)
```

<a id="api_rte_getconfigs_rte__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_rte_getconfigs_rte__timing"></a>

### 调用时机 [#调用时机-8]

在调用 [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_rte_rte) 之后调用该方法。

<a id="api_rte_getconfigs_rte__parameters"></a>

### 参数 [#参数-9]

<ParameterList>
<a id="config-3"></a>
<Parameter name="config">

输出参数，表示 `RTE` 对象的配置信息。详见 [Config](/zh-CN/api-reference/rtc/cpp-all-platforms/class-config)。

</Parameter>
<a id="err-8"></a>
<Parameter name="err">

输出参数，状态或错误信息。详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_rte_getconfigs_rte__return_values"></a>

### 返回值 [#返回值-15]

- true：获取成功。
- false：获取失败。

### 所属接口类 [#所属接口类-16]

- [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rte)

<a id="api_rte_getfrombridge"></a>

<a id="ariaid-title19"></a>

## GetFromBridge [#getfrombridge]

从 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 中桥接一个 `RTE` 对象。

<a id="api_rte_getfrombridge__prototype"></a>

```cpp
static Rte GetFromBridge(Error* err = nullptr)
```

<a id="api_rte_getfrombridge__detailed_desc"></a>

:::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) 进行初始化。

<a id="api_rte_getfrombridge__timing"></a>

### 调用时机 [#调用时机-9]

在调用此方法之前，请确保你已调用 [initialize](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#api_irtcengine_initialize) 初始化 RTC 引擎。

<a id="api_rte_getfrombridge__parameters"></a>

### 参数 [#参数-10]

<ParameterList>
<a id="err-9"></a>
<Parameter name="err">

输出参数，用于接收状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_rte_getfrombridge__return_values"></a>

### 返回值 [#返回值-16]

- 方法调用成功，返回一个 `RTE` 对象，详见 `RTE`。
- 方法调用失败，返回 NULL。

### 所属接口类 [#所属接口类-17]

- [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rte)

<a id="api_player_getinfo"></a>

<a id="ariaid-title20"></a>

## GetInfo [#getinfo]

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

<a id="api_player_getinfo__prototype"></a>

```cpp
bool GetInfo(PlayerInfo *info, Error *err = nullptr)
```

<a id="api_player_getinfo__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

你可以使用该方法获取播放器和媒体流的详细信息，例如音频采样率、视频帧大小等。

<a id="api_player_getinfo__timing"></a>

### 调用时机 [#调用时机-10]

在调用 [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_player_player) 之后调用此方法。

<a id="api_player_getinfo__parameters"></a>

### 参数 [#参数-11]

<ParameterList>
<a id="info"></a>
<Parameter name="info">

输出参数，表示播放器和媒体流的信息。详见 [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)。

</Parameter>
<a id="err-10"></a>
<Parameter name="err">

输出参数，状态或错误信息。详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_player_getinfo__return_values"></a>

### 返回值 [#返回值-17]

- true：获取成功。
- false：获取失败。

### 所属接口类 [#所属接口类-18]

- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)

<a id="api_config_getjsonparameter_config"></a>

<a id="ariaid-title21"></a>

## GetJsonParameter [#getjsonparameter]

获取已配置的 SDK JSON 配置信息。

<a id="api_config_getjsonparameter_config__prototype"></a>

```cpp
std::string GetJsonParameter(Error *err = nullptr)
```

<a id="api_config_getjsonparameter_config__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

调用 [SetJsonParameter](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_config_setjsonparameter_config) 设置 JSON 配置后，可调用本方法获取已配置的信息。

<a id="api_config_getjsonparameter_config__timing"></a>

### 调用时机 [#调用时机-11]

必须在调用 `GetConfigs` 之后调用此方法。

<a id="api_config_getjsonparameter_config__parameters"></a>

### 参数 [#参数-12]

<ParameterList>
<a id="err-11"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_config_getjsonparameter_config__return_values"></a>

### 返回值 [#返回值-18]

- 方法调用成功时，返回已配置的 JSON 信息。
- 方法调用失败，返回空字符串。

### 所属接口类 [#所属接口类-19]

- [Config](/zh-CN/api-reference/rtc/cpp-all-platforms/class-config)

<a id="api_playerconfig_getloopcount"></a>

<a id="ariaid-title22"></a>

## GetLoopCount [#getloopcount]

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

<a id="api_playerconfig_getloopcount__prototype"></a>

```cpp
int32_t GetLoopCount(Error *err = nullptr)
```

<a id="api_playerconfig_getloopcount__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

<a id="api_playerconfig_getloopcount__parameters"></a>

### 参数 [#参数-13]

<ParameterList>
<a id="err-12"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_playerconfig_getloopcount__return_values"></a>

### 返回值 [#返回值-19]

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

### 所属接口类 [#所属接口类-20]

- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)

<a id="api_canvasconfig_getmirrormode"></a>

<a id="ariaid-title23"></a>

## GetMirrorMode [#getmirrormode]

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

<a id="api_canvasconfig_getmirrormode__prototype"></a>

```cpp
VideoMirrorMode GetMirrorMode(Error *err = nullptr)
```

<a id="api_canvasconfig_getmirrormode__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_canvasconfig_getmirrormode__timing"></a>

### 调用时机 [#调用时机-12]

该方法必须在调用 `GetConfigs` 之后调用。

<a id="api_canvasconfig_getmirrormode__parameters"></a>

### 参数 [#参数-14]

<ParameterList>
<a id="err-13"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_canvasconfig_getmirrormode__return_values"></a>

### 返回值 [#返回值-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)

<a id="api_playerconfig_getplaybackspeed"></a>

<a id="ariaid-title24"></a>

## GetPlaybackSpeed [#getplaybackspeed]

获取播放速度参数。

<a id="api_playerconfig_getplaybackspeed__prototype"></a>

```cpp
int32_t GetPlaybackSpeed(Error *err = nullptr)
```

<a id="api_playerconfig_getplaybackspeed__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

<a id="api_playerconfig_getplaybackspeed__parameters"></a>

### 参数 [#参数-15]

<ParameterList>
<a id="err-14"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_playerconfig_getplaybackspeed__return_values"></a>

### 返回值 [#返回值-21]

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

### 所属接口类 [#所属接口类-22]

- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)

<a id="api_playerconfig_getplayoutvolume"></a>

<a id="ariaid-title25"></a>

## GetPlayoutVolume [#getplayoutvolume]

获取播放器的播放音量。

<a id="api_playerconfig_getplayoutvolume__prototype"></a>

```cpp
int32_t GetPlayoutVolume(Error *err = nullptr)
```

<a id="api_playerconfig_getplayoutvolume__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

<a id="api_playerconfig_getplayoutvolume__parameters"></a>

### 参数 [#参数-16]

<ParameterList>
<a id="err-15"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_playerconfig_getplayoutvolume__return_values"></a>

### 返回值 [#返回值-22]

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

### 所属接口类 [#所属接口类-23]

- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)

<a id="api_player_getposition"></a>

<a id="ariaid-title26"></a>

## GetPosition [#getposition]

获取当前播放位置。

<a id="api_player_getposition__prototype"></a>

```cpp
uint64_t GetPosition(Error *err = nullptr)
```

<a id="api_player_getposition__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

<a id="api_player_getposition__parameters"></a>

### 参数 [#参数-17]

<ParameterList>
<a id="err-16"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [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)。

</Parameter>
</ParameterList>

<a id="api_player_getposition__return_values"></a>

### 返回值 [#返回值-23]

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

### 所属接口类 [#所属接口类-24]

- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)

<a id="api_canvasconfig_getrendermode"></a>

<a id="ariaid-title27"></a>

## GetRenderMode [#getrendermode]

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

<a id="api_canvasconfig_getrendermode__prototype"></a>

```cpp
VideoRenderMode GetRenderMode(Error *err = nullptr)
```

<a id="api_canvasconfig_getrendermode__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_canvasconfig_getrendermode__timing"></a>

### 调用时机 [#调用时机-13]

该方法必须在调用 `GetConfigs` 之后调用。

<a id="api_canvasconfig_getrendermode__parameters"></a>

### 参数 [#参数-18]

<ParameterList>
<a id="err-17"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_canvasconfig_getrendermode__return_values"></a>

### 返回值 [#返回值-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)

<a id="api_player_getstats"></a>

<a id="ariaid-title28"></a>

## GetStats [#getstats]

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

<a id="api_player_getstats__prototype"></a>

```cpp
void GetStats(std::function<void(rte::PlayerStats *stats, rte::Error *err)> cb)
```

<a id="api_player_getstats__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

该方法通过回调异步返回播放器的统计信息，包括解码情况、渲染帧率、音视频码率等。

<a id="api_player_getstats__timing"></a>

### 调用时机 [#调用时机-14]

该方法必须在调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 之后调用。

<a id="api_player_getstats__parameters"></a>

### 参数 [#参数-19]

<ParameterList>
<a id="cb"></a>
<Parameter name="cb">

异步通知获取播放器媒体资源统计信息结果的回调。你可以通过该回调的参数获取以下信息：

- `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)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-26]

- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)

<a id="api_rteplayerinfo_hasaudio"></a>

<a id="ariaid-title29"></a>

## HasAudio [#hasaudio]

判断媒体资源中是否包含音频流。

<a id="api_rteplayerinfo_hasaudio__prototype"></a>

```cpp
bool HasAudio() const
```

<a id="api_rteplayerinfo_hasaudio__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

<a id="api_rteplayerinfo_hasaudio__return_values"></a>

### 返回值 [#返回值-25]

- true：媒体资源中包含音频流。
- false：媒体资源中不包含音频流。

### 所属接口类 [#所属接口类-27]

- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)

<a id="api_rteplayerinfo_hasvideo"></a>

<a id="ariaid-title30"></a>

## HasVideo [#hasvideo]

判断 URL 源中是否包含视频流。

<a id="api_rteplayerinfo_hasvideo__prototype"></a>

```cpp
bool HasVideo() const
```

<a id="api_rteplayerinfo_hasvideo__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

<a id="api_rteplayerinfo_hasvideo__return_values"></a>

### 返回值 [#返回值-26]

- true：URL 源包含视频流。
- false：URL 源不包含视频流。

### 所属接口类 [#所属接口类-28]

- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)

<a id="api_rte_initmediaengine"></a>

<a id="ariaid-title31"></a>

## InitMediaEngine [#initmediaengine]

初始化 `RTE` 引擎。

<a id="api_rte_initmediaengine__prototype"></a>

```cpp
bool InitMediaEngine(std::function<void(rte::Error *err)> cb, Error *err = nullptr)
```

<a id="api_rte_initmediaengine__detailed_desc"></a>

:::note
注： [InitMediaEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_initmediaengine) 的返回值仅表示初始化操作是否已成功加入异步任务队列，并不表示初始化本身是否成功。
:::

<a id="api_rte_initmediaengine__timing"></a>

### 调用时机 [#调用时机-15]

该方法必须在创建 `RTE` 对象并设置 App ID 后调用。

<a id="api_rte_initmediaengine__parameters"></a>

### 参数 [#参数-20]

<ParameterList>
<a id="cb-1"></a>
<Parameter name="cb">

异步通知初始化结果的回调。你可以通过该回调的 `err` 参数获取初始化结果或错误码信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
<a id="err-18"></a>
<Parameter name="err">

输出参数，表示初始化过程中产生的状态或错误信息，详见 [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 会通过该参数同步返回错误信息。

</Parameter>
</ParameterList>

<a id="api_rte_initmediaengine__return_values"></a>

### 返回值 [#返回值-27]

- true：成功将初始化操作加入异步任务队列。
- false：未能将初始化操作加入异步任务队列。

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

### 所属接口类 [#所属接口类-29]

- [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rte)

<a id="api_rteplayerinfo_isaudiomuted"></a>

<a id="ariaid-title32"></a>

## IsAudioMuted [#isaudiomuted]

判断播放器是否停止接收音频流。

<a id="api_rteplayerinfo_isaudiomuted__prototype"></a>

```cpp
bool IsAudioMuted() const
```

<a id="api_rteplayerinfo_isaudiomuted__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

<a id="api_rteplayerinfo_isaudiomuted__return_values"></a>

### 返回值 [#返回值-28]

- true：播放器已停止接收音频流。
- false：播放器仍在接收音频流。

### 所属接口类 [#所属接口类-30]

- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)

<a id="api_rteplayerinfo_isvideomuted"></a>

<a id="ariaid-title33"></a>

## IsVideoMuted [#isvideomuted]

判断播放器是否停止接收视频流。

<a id="api_rteplayerinfo_isvideomuted__prototype"></a>

```cpp
bool IsVideoMuted() const
```

<a id="api_rteplayerinfo_isvideomuted__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

:::note
注： [IsVideoMuted](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rteplayerinfo_isvideomuted) 仅在打开 RTE URL 时有效。
:::

<a id="api_rteplayerinfo_isvideomuted__return_values"></a>

### 返回值 [#返回值-29]

- true：播放器已停止接收视频流。
- false：播放器仍在接收视频流。

### 所属接口类 [#所属接口类-31]

- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)

<a id="api_error_message"></a>

<a id="ariaid-title34"></a>

## Message [#message]

获取详细错误信息。

<a id="api_error_message__prototype"></a>

```cpp
const char *Message() const
```

<a id="api_error_message__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_error_message__timing"></a>

### 调用时机 [#调用时机-16]

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

<a id="api_error_message__return_values"></a>

### 返回值 [#返回值-30]

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

### 所属接口类 [#所属接口类-32]

- [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)

<a id="api_player_muteaudio"></a>

<a id="ariaid-title35"></a>

## MuteAudio [#muteaudio]

接收或停止接收音频流。

<a id="api_player_muteaudio__prototype"></a>

```cpp
bool MuteAudio(bool mute, Error *err = nullptr)
```

<a id="api_player_muteaudio__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_player_muteaudio__timing"></a>

### 调用时机 [#调用时机-17]

该方法必须在调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 之后调用。

<a id="api_player_muteaudio__related"></a>

### 相关回调 [#相关回调]

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

<a id="api_player_muteaudio__parameters"></a>

### 参数 [#参数-21]

<ParameterList>
<a id="mute"></a>
<Parameter name="mute">

是否接收音频流：

- true：不接收音频流。
- false：接收音频流。

</Parameter>
<a id="err-19"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_player_muteaudio__return_values"></a>

### 返回值 [#返回值-31]

true 表示操作成功，false 表示操作失败。

### 所属接口类 [#所属接口类-33]

- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)

<a id="api_player_mutevideo"></a>

<a id="ariaid-title36"></a>

## MuteVideo [#mutevideo]

接收或停止接收视频流。

<a id="api_player_mutevideo__prototype"></a>

```cpp
bool MuteVideo(bool mute, Error *err = nullptr)
```

<a id="api_player_mutevideo__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_player_mutevideo__timing"></a>

### 调用时机 [#调用时机-18]

该方法必须在调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 之后调用。

<a id="api_player_mutevideo__related"></a>

### 相关回调 [#相关回调-1]

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

<a id="api_player_mutevideo__parameters"></a>

### 参数 [#参数-22]

<ParameterList>
<a id="mute-1"></a>
<Parameter name="mute">

是否接收视频流：

- true：不接收视频流。
- false：接收视频流。

</Parameter>
<a id="err-20"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_player_mutevideo__return_values"></a>

### 返回值 [#返回值-32]

true 表示操作成功，false 表示操作失败。

### 所属接口类 [#所属接口类-34]

- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)

<a id="api_player_openwithurl"></a>

<a id="ariaid-title37"></a>

## OpenWithUrl [#openwithurl]

打开一个 URL 资源。

<a id="api_player_openwithurl__prototype"></a>

```cpp
void OpenWithUrl(const char* url, uint64_t start_time, std::function<void(rte::Error* err)> cb)
```

<a id="api_player_openwithurl__detailed_desc"></a>

:::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 和本地媒体文件。
:::

<a id="api_player_openwithurl__timing"></a>

### 调用时机 [#调用时机-19]

该方法必须在 [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_player_player) 初始化后调用。

<a id="api_player_openwithurl__related"></a>

### 相关回调 [#相关回调-2]

成功调用该方法后，SDK 会触发 [onStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#callback_playerobserver_onstatechanged) 回调报告播放器状态为 `kRtePlayerStateOpening`，表示正在打开 URL。打开成功后，播放器状态将报告为 `kRtePlayerStateOpenCompleted`。

<a id="api_player_openwithurl__parameters"></a>

### 参数 [#参数-23]

<ParameterList>
<a id="url"></a>
<Parameter name="url">

要打开的 URL，可以是 CDN 推流 URL、本地媒体文件，或以 `rte://` 开头的 URL。

</Parameter>
<a id="start_time"></a>
<Parameter name="start_time">

开始播放的位置，单位为毫秒。

</Parameter>
<a id="cb-2"></a>
<Parameter name="cb">

异步通知 URL 资源打开结果的回调。你可以通过该回调的 `err` 参数获取操作结果或错误码信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-35]

- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)

<a id="api_player_pause_player"></a>

<a id="ariaid-title38"></a>

## Pause [#pause]

暂停播放。

<a id="api_player_pause_player__prototype"></a>

```cpp
bool Pause(Error *err = nullptr)
```

<a id="api_player_pause_player__detailed_desc"></a>

:::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) 方法。

<a id="api_player_pause_player__timing"></a>

### 调用时机 [#调用时机-20]

该方法必须在调用 [Play](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_play_player) 之后调用。

<a id="api_player_pause_player__related"></a>

### 相关回调 [#相关回调-3]

成功调用该方法后，SDK 会触发 [onStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#callback_playerobserver_onstatechanged) 回调报告播放器状态为 `kRtePlayerStatePaused`。

<a id="api_player_pause_player__parameters"></a>

### 参数 [#参数-24]

<ParameterList>
<a id="err-21"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_player_pause_player__return_values"></a>

### 返回值 [#返回值-33]

- true：暂停播放成功。
- false：暂停播放失败。

### 所属接口类 [#所属接口类-36]

- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)

<a id="api_player_play_player"></a>

<a id="ariaid-title39"></a>

## Play [#play]

播放一个 URL 资源。

<a id="api_player_play_player__prototype"></a>

```cpp
bool Play(Error *err = nullptr)
```

<a id="api_player_play_player__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

:::note
注： 该方法当前仅支持以 `rte://` 开头的 URL。
:::

<a id="api_player_play_player__timing"></a>

### 调用时机 [#调用时机-21]

在收到 [onStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#callback_playerobserver_onstatechanged) 回调报告状态为 `kRtePlayerStateOpenCompleted` 后调用此方法。

<a id="api_player_play_player__parameters"></a>

### 参数 [#参数-25]

<ParameterList>
<a id="err-22"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_player_play_player__return_values"></a>

### 返回值 [#返回值-34]

播放是否成功：

- true：播放成功。
- false：播放失败。

### 所属接口类 [#所属接口类-37]

- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)

<a id="api_player_player_player"></a>

<a id="ariaid-title40"></a>

## Player [#player]

构造一个 [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_player_player) 播放器对象。

<a id="api_player_player_player__prototype"></a>

```cpp
explicit Player(Rte *self, PlayerInitialConfig *config = nullptr)
```

<a id="api_player_player_player__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_player_player_player__timing"></a>

### 调用时机 [#调用时机-22]

该方法必须在调用 [InitMediaEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_initmediaengine) 之后调用。

<a id="api_player_player_player__parameters"></a>

### 参数 [#参数-26]

<ParameterList>
<a id="self"></a>
<Parameter name="self">

[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)。

</Parameter>
<a id="config-4"></a>
<Parameter name="config">

播放器的初始配置。你可以传入 NULL。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-38]

- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)

<a id="api_player_preloadwithurl"></a>

<a id="ariaid-title41"></a>

## PreloadWithUrl [#preloadwithurl]

预加载 URL 资源。

<a id="api_player_preloadwithurl__prototype"></a>

```cpp
static bool PreloadWithUrl(const char* url, Error *err = nullptr)
```

<a id="api_player_preloadwithurl__detailed_desc"></a>

:::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 替换。
:::

<a id="api_player_preloadwithurl__scenario"></a>

### 适用场景 [#适用场景-1]

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

<a id="api_player_preloadwithurl__timing"></a>

### 调用时机 [#调用时机-23]

该方法必须在调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 之前调用。

<a id="api_player_preloadwithurl__parameters"></a>

### 参数 [#参数-27]

<ParameterList>
<a id="url-1"></a>
<Parameter name="url">

以 `rte://` 开头的 URL。

</Parameter>
<a id="err-23"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_player_preloadwithurl__return_values"></a>

### 返回值 [#返回值-35]

是否预加载成功：

- true：预加载成功。
- false：预加载失败。

### 所属接口类 [#所属接口类-39]

- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)

<a id="api_player_registerobserver_player"></a>

<a id="ariaid-title42"></a>

## RegisterObserver [#registerobserver]

注册一个 [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver) 播放器观察者对象。

<a id="api_player_registerobserver_player__prototype"></a>

```cpp
bool RegisterObserver(PlayerObserver *observer, Error *err = nullptr)
```

<a id="api_player_registerobserver_player__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

在调用该方法前，你需要实现一个继承自 [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver) 的接口类。

<a id="api_player_registerobserver_player__timing"></a>

### 调用时机 [#调用时机-24]

该方法必须在调用 [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_player_player) 之后执行。

<a id="api_player_registerobserver_player__parameters"></a>

### 参数 [#参数-28]

<ParameterList>
<a id="observer"></a>
<Parameter name="observer">

[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)。

</Parameter>
<a id="err-24"></a>
<Parameter name="err">

输出参数，状态或错误信息。详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_player_registerobserver_player__return_values"></a>

### 返回值 [#返回值-36]

是否注册成功：

- true：注册成功。
- false：注册失败。

### 所属接口类 [#所属接口类-40]

- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)

<a id="api_canvas_removeview"></a>

<a id="ariaid-title43"></a>

## RemoveView [#removeview]

移除一个渲染视图。

<a id="api_canvas_removeview__prototype"></a>

```cpp
bool RemoveView(View *view, ViewConfig *config, rte::Error *err = nullptr)
```

<a id="api_canvas_removeview__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

调用 [AddView](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_canvas_addview) 添加视图后，如有需要，可以调用该方法移除该视图。

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

<a id="api_canvas_removeview__timing"></a>

### 调用时机 [#调用时机-25]

该方法必须在调用 [AddView](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_canvas_addview) 之后调用。

<a id="api_canvas_removeview__parameters"></a>

### 参数 [#参数-29]

<ParameterList>
<a id="view-1"></a>
<Parameter name="view">

要移除的视图对象。

</Parameter>
<a id="config-5"></a>
<Parameter name="config">

视图对象的设置，目前传入 NULL。

</Parameter>
<a id="err-25"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_canvas_removeview__return_values"></a>

### 返回值 [#返回值-37]

- true：视图移除成功。
- false：视图移除失败。

### 所属接口类 [#所属接口类-41]

- [Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvas)

<a id="api_rte_rte_rte"></a>

<a id="ariaid-title44"></a>

## Rte [#rte]

构造一个 [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_rte_rte) 对象。

<a id="api_rte_rte_rte__prototype"></a>

```cpp
explicit Rte(InitialConfig *config = nullptr)
```

<a id="api_rte_rte_rte__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_rte_rte_rte__timing"></a>

### 调用时机 [#调用时机-26]

该方法必须在调用 [InitMediaEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_initmediaengine) 之前调用。

<a id="api_rte_rte_rte__parameters"></a>

### 参数 [#参数-30]

<ParameterList>
<a id="config-6"></a>
<Parameter name="config">

初始化设置。你可以传入 NULL。详见 `InitialConfig`。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-42]

- [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rte)

<a id="api_player_seek"></a>

<a id="ariaid-title45"></a>

## Seek [#seek]

跳转到新的播放位置。

<a id="api_player_seek__prototype"></a>

```cpp
bool Seek(uint64_t new_time, Error *err = nullptr)
```

<a id="api_player_seek__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

<a id="api_player_seek__parameters"></a>

### 参数 [#参数-31]

<ParameterList>
<a id="new_time"></a>
<Parameter name="new_time">

要跳转到的新播放位置。

</Parameter>
<a id="err-26"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [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，不支持跳转。

</Parameter>
</ParameterList>

<a id="api_player_seek__return_values"></a>

### 返回值 [#返回值-38]

- true：成功跳转到播放位置。
- false：跳转失败。

### 所属接口类 [#所属接口类-43]

- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)

<a id="api_playerconfig_setabrfallbacklayer"></a>

<a id="ariaid-title46"></a>

## SetAbrFallbackLayer [#setabrfallbacklayer]

设置已订阅视频流的回退选项。

<a id="api_playerconfig_setabrfallbacklayer__prototype"></a>

```cpp
void SetAbrFallbackLayer(AbrFallbackLayer abr_fallback_layer, Error *err = nullptr)
```

<a id="api_playerconfig_setabrfallbacklayer__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

在网络状况较差时，SDK 会将视频流的分辨率降级为指定的回退质量层，以保证播放的连续性。不同的质量层对应不同的分辨率和码率。SDK 会持续监测网络状况，在网络恢复后自动将视频流恢复为订阅的质量层。
默认情况下，仅支持回退到 `kRteAbrFallbackLow` 或 `kRteAbrFallbackAudioOnly`。如需更灵活的视频体验，可[联系技术支持](https://ticket.shengwang.cn/)开启 ABR 功能，开启后可回退到所有质量层，并自定义每一层的分辨率。

:::note
注： 如果在调用该方法时未开启 ABR 功能，视频流的回退质量层只能为 `kRteAbrFallbackLow` 或 `kRteAbrFallbackAudioOnly`。
:::

<a id="api_playerconfig_setabrfallbacklayer__scenario"></a>

### 适用场景 [#适用场景-2]

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

<a id="api_playerconfig_setabrfallbacklayer__timing"></a>

### 调用时机 [#调用时机-27]

该方法必须在调用 `SetConfigs` 之前调用。

<a id="api_playerconfig_setabrfallbacklayer__parameters"></a>

### 参数 [#参数-32]

<ParameterList>
<a id="abr_fallback_layer"></a>
<Parameter name="abr_fallback_layer">

视频流的回退质量层，详见 [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) |

</Parameter>
<a id="err-27"></a>
<Parameter name="err">

状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-44]

- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)

<a id="api_playerconfig_setabrsubscriptionlayer"></a>

<a id="ariaid-title47"></a>

## SetAbrSubscriptionLayer [#setabrsubscriptionlayer]

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

<a id="api_playerconfig_setabrsubscriptionlayer__prototype"></a>

```cpp
void SetAbrSubscriptionLayer(AbrSubscriptionLayer abr_subscription_layer, Error *err = nullptr)
```

<a id="api_playerconfig_setabrsubscriptionlayer__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

你可以根据实际网络状况在不同的视频流质量层级之间切换，每个层级对应不同的分辨率。默认情况下，调用该方法后，订阅端只能在高低画质之间切换，即 `kRteAbrSubscriptionHigh` 和 `kRteAbrSubscriptionLow`。如果你对视频分辨率切换有更高要求，可以[联系技术支持](https://ticket.shengwang.cn/)开启 ABR（自适应码率）功能。开启后，你可以自定义每个视频质量层级的分辨率，订阅端可根据需要在所有视频质量层级之间切换。

:::note
注： 如果在调用该方法时未开启 ABR 功能，订阅的视频质量层级只能为 `kRteAbrSubscriptionHigh` 或 `kRteAbrSubscriptionLow`。
:::

<a id="api_playerconfig_setabrsubscriptionlayer__scenario"></a>

### 适用场景 [#适用场景-3]

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

<a id="api_playerconfig_setabrsubscriptionlayer__timing"></a>

### 调用时机 [#调用时机-28]

该方法必须在调用 `SetConfigs` 之前调用。

<a id="api_playerconfig_setabrsubscriptionlayer__parameters"></a>

### 参数 [#参数-33]

<ParameterList>
<a id="abr_subscription_layer"></a>
<Parameter name="abr_subscription_layer">

要订阅的视频质量层级，详见 [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) |

</Parameter>
<a id="err-28"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-45]

- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)

<a id="api_config_setappid"></a>

<a id="ariaid-title48"></a>

## SetAppId [#setappid]

设置声网 App ID。

<a id="api_config_setappid__prototype"></a>

```cpp
void SetAppId(const char *app_id, Error *err = nullptr)
```

<a id="api_config_setappid__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_config_setappid__timing"></a>

### 调用时机 [#调用时机-29]

该方法必须在调用 [InitMediaEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_initmediaengine) 之前调用。

<a id="api_config_setappid__parameters"></a>

### 参数 [#参数-34]

<ParameterList>
<a id="app_id"></a>
<Parameter name="app_id">

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

</Parameter>
<a id="err-29"></a>
<Parameter name="err">

输出参数，状态或错误信息。详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-46]

- [Config](/zh-CN/api-reference/rtc/cpp-all-platforms/class-config)

<a id="api_playerconfig_setautoplay"></a>

<a id="ariaid-title49"></a>

## SetAutoPlay [#setautoplay]

设置是否自动播放。

<a id="api_playerconfig_setautoplay__prototype"></a>

```cpp
void SetAutoPlay(bool auto_play, Error *err = nullptr)
```

<a id="api_playerconfig_setautoplay__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

在调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 打开媒体流之前，可以调用该方法设置是否自动播放。如果未设置，默认启用自动播放。

<a id="api_playerconfig_setautoplay__timing"></a>

### 调用时机 [#调用时机-30]

该方法必须在调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 之前调用。

<a id="api_playerconfig_setautoplay__parameters"></a>

### 参数 [#参数-35]

<ParameterList>
<a id="auto_play"></a>
<Parameter name="auto_play">

是否启用自动播放：

- true：（默认）启用自动播放。
- false：不启用自动播放。

</Parameter>
<a id="err-30"></a>
<Parameter name="err">

输出参数，表示状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-47]

- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)

<a id="api_player_setcanvas"></a>

<a id="ariaid-title50"></a>

## SetCanvas [#setcanvas]

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

<a id="api_player_setcanvas__prototype"></a>

```cpp
bool SetCanvas(Canvas *canvas, Error *err = nullptr)
```

<a id="api_player_setcanvas__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

该方法用于指定一个 `Canvas` 对象用于显示视频。一旦视频流成功播放，视频将显示在该 [Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvas) 上。

<a id="api_player_setcanvas__timing"></a>

### 调用时机 [#调用时机-31]

该方法必须在调用 [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_player_player) 之后执行。

<a id="api_player_setcanvas__parameters"></a>

### 参数 [#参数-36]

<ParameterList>
<a id="canvas"></a>
<Parameter name="canvas">

[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)。

</Parameter>
<a id="err-31"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_player_setcanvas__return_values"></a>

### 返回值 [#返回值-39]

- true：设置成功。
- false：设置失败。你可以通过 `err` 参数返回的错误码查看详细信息。

### 所属接口类 [#所属接口类-48]

- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)

<a id="api_canvas_setconfigs_canvas"></a>

<a id="ariaid-title51"></a>

## SetConfigs [3/3] [#setconfigs-33]

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

<a id="api_canvas_setconfigs_canvas__prototype"></a>

```cpp
bool SetConfigs(CanvasConfig *config, Error *err = nullptr)
```

<a id="api_canvas_setconfigs_canvas__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_canvas_setconfigs_canvas__timing"></a>

### 调用时机 [#调用时机-32]

该方法必须在调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 之前调用。

<a id="api_canvas_setconfigs_canvas__parameters"></a>

### 参数 [#参数-37]

<ParameterList>
<a id="config-7"></a>
<Parameter name="config">

用于设置 [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)。

</Parameter>
<a id="err-32"></a>
<Parameter name="err">

状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_canvas_setconfigs_canvas__return_values"></a>

### 返回值 [#返回值-40]

配置是否成功：

- true：配置成功。
- false：配置失败。

### 所属接口类 [#所属接口类-49]

- [Canvas](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvas)

<a id="api_player_setconfigs_player"></a>

<a id="ariaid-title52"></a>

## SetConfigs [2/3] [#setconfigs-23]

配置播放器。

<a id="api_player_setconfigs_player__prototype"></a>

```cpp
bool SetConfigs(PlayerConfig* config, Error *err = nullptr)
```

<a id="api_player_setconfigs_player__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

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

<a id="api_player_setconfigs_player__timing"></a>

### 调用时机 [#调用时机-33]

该方法必须在调用 [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_player_player) 之后执行。

<a id="api_player_setconfigs_player__parameters"></a>

### 参数 [#参数-38]

<ParameterList>
<a id="config-8"></a>
<Parameter name="config">

播放器配置对象，详见 [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)。

</Parameter>
<a id="err-33"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_player_setconfigs_player__return_values"></a>

### 返回值 [#返回值-41]

配置是否成功：

- true：配置成功。
- false：配置失败。

### 所属接口类 [#所属接口类-50]

- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)

<a id="api_rte_setconfigs"></a>

<a id="api_rte_setconfigs_rte"></a>

<a id="ariaid-title53"></a>

## SetConfigs [1/3] [#setconfigs-13]

配置 `RTE` 对象的信息。

<a id="api_rte_setconfigs_rte__prototype"></a>

```cpp
bool SetConfigs(Config *config, Error *err = nullptr)
```

<a id="api_rte_setconfigs_rte__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

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

<a id="api_rte_setconfigs_rte__timing"></a>

### 调用时机 [#调用时机-34]

该方法必须在调用 [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rte_rte_rte) 之后执行。

<a id="api_rte_setconfigs_rte__parameters"></a>

### 参数 [#参数-39]

<ParameterList>
<a id="config-9"></a>
<Parameter name="config">

`RTE` 对象的设置信息，详见 [Config](/zh-CN/api-reference/rtc/cpp-all-platforms/class-config)。

</Parameter>
<a id="err-34"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_rte_setconfigs_rte__return_values"></a>

### 返回值 [#返回值-42]

- true：配置成功。
- false：配置失败。

### 所属接口类 [#所属接口类-51]

- [Rte](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rte)

<a id="api_config_setjsonparameter_config"></a>

<a id="ariaid-title54"></a>

## SetJsonParameter [#setjsonparameter]

使用 JSON 配置 SDK 的技术预览或自定义功能。

<a id="api_config_setjsonparameter_config__prototype"></a>

```cpp
void SetJsonParameter(const char *json_parameter, Error *err = nullptr)
```

<a id="api_config_setjsonparameter_config__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

你可以在需要设置私有参数或使用自定义功能时调用此方法。

<a id="api_config_setjsonparameter_config__scenario"></a>

### 适用场景 [#适用场景-4]

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

<a id="api_config_setjsonparameter_config__timing"></a>

### 调用时机 [#调用时机-35]

该方法必须在调用 `SetConfigs` 之前调用。

<a id="api_config_setjsonparameter_config__parameters"></a>

### 参数 [#参数-40]

<ParameterList>
<a id="json_parameter"></a>
<Parameter name="json_parameter">

JSON 字符串格式的参数。

</Parameter>
<a id="err-35"></a>
<Parameter name="err">

输出参数，表示状态或错误信息。详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-52]

- [Config](/zh-CN/api-reference/rtc/cpp-all-platforms/class-config)

<a id="api_playerconfig_setloopcount"></a>

<a id="ariaid-title55"></a>

## SetLoopCount [#setloopcount]

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

<a id="api_playerconfig_setloopcount__prototype"></a>

```cpp
void SetLoopCount(int32_t count, Error *err = nullptr)
```

<a id="api_playerconfig_setloopcount__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

<a id="api_playerconfig_setloopcount__parameters"></a>

### 参数 [#参数-41]

<ParameterList>
<a id="count"></a>
<Parameter name="count">

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

- `1`：播放一次。
- `2`：播放两次。
- `-1`：无限循环播放，直到调用 [Stop](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_stop_player)。

</Parameter>
<a id="err-36"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

- `kRteOk`：调用成功。
- `kRteErrorInvalidArgument`：`count` 参数设置为无效值。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-53]

- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)

<a id="api_canvasconfig_setmirrormode"></a>

<a id="ariaid-title56"></a>

## SetMirrorMode [#setmirrormode]

设置视频的镜像模式。

<a id="api_canvasconfig_setmirrormode__prototype"></a>

```cpp
void SetMirrorMode(VideoMirrorMode mode, Error *err = nullptr)
```

<a id="api_canvasconfig_setmirrormode__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_canvasconfig_setmirrormode__timing"></a>

### 调用时机 [#调用时机-36]

该方法必须在调用 `SetConfigs` 之前调用。

<a id="api_canvasconfig_setmirrormode__parameters"></a>

### 参数 [#参数-42]

<ParameterList>
<a id="mode"></a>
<Parameter name="mode">

镜像模式，详见 [RteVideoMirrorMode](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rtevideomirrormode)。

- 默认值为 `kRteVideoMirrorModeAuto`，由 SDK 自动决定镜像模式。
- 默认情况下，远端用户的镜像模式为关闭状态。

</Parameter>
<a id="err-37"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-54]

- [CanvasConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvasconfig)

<a id="api_playerconfig_setplaybackspeed"></a>

<a id="ariaid-title57"></a>

## SetPlaybackSpeed [#setplaybackspeed]

设置播放速度参数。

<a id="api_playerconfig_setplaybackspeed__prototype"></a>

```cpp
void SetPlaybackSpeed(int32_t speed, Error *err = nullptr)
```

<a id="api_playerconfig_setplaybackspeed__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

:::note
注： 你可以在调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 方法之后调用此方法。
:::

<a id="api_playerconfig_setplaybackspeed__parameters"></a>

### 参数 [#参数-43]

<ParameterList>
<a id="speed"></a>
<Parameter name="speed">

播放速度。有效范围为 [50, 400]。

</Parameter>
<a id="err-38"></a>
<Parameter name="err">

状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

- `kRteOk`：调用成功。
- `kRteErrorInvalidArgument`：`speed` 参数设置为无效值。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-55]

- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)

<a id="api_playerconfig_setplayoutvolume"></a>

<a id="ariaid-title58"></a>

## SetPlayoutVolume [#setplayoutvolume]

设置播放音量。

<a id="api_playerconfig_setplayoutvolume__prototype"></a>

```cpp
void SetPlayoutVolume(int32_t volume, Error *err = nullptr)
```

<a id="api_playerconfig_setplayoutvolume__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

<a id="api_playerconfig_setplayoutvolume__parameters"></a>

### 参数 [#参数-44]

<ParameterList>
<a id="volume"></a>
<Parameter name="volume">

要设置的播放音量，取值范围为 [0, 400]。

</Parameter>
<a id="err-39"></a>
<Parameter name="err">

状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

- `kRteOk`：设置成功。
- `kRteErrorInvalidArgument`：音量参数设置为无效值。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-56]

- [PlayerConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerconfig)

<a id="api_canvasconfig_setrendermode_canvasconfig"></a>

<a id="ariaid-title59"></a>

## SetRenderMode [#setrendermode]

设置视频渲染模式。

<a id="api_canvasconfig_setrendermode_canvasconfig__prototype"></a>

```cpp
void SetRenderMode(VideoRenderMode mode, Error *err = nullptr)
```

<a id="api_canvasconfig_setrendermode_canvasconfig__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="api_canvasconfig_setrendermode_canvasconfig__timing"></a>

### 调用时机 [#调用时机-37]

该方法必须在调用 `SetConfigs` 之前调用。

<a id="api_canvasconfig_setrendermode_canvasconfig__parameters"></a>

### 参数 [#参数-45]

<ParameterList>
<a id="mode-1"></a>
<Parameter name="mode">

渲染模式，详见 [RteVideoRenderMode](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rtevideorendermode)。默认值为 `kRteVideoRenderModeHidden`，该模式按比例缩放视频并优先填满视图窗口。

</Parameter>
<a id="err-40"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-57]

- [CanvasConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_canvasconfig)

<a id="api_rteplayerinfo_state"></a>

<a id="ariaid-title60"></a>

## State [#state]

获取当前播放器状态。

<a id="api_rteplayerinfo_state__prototype"></a>

```cpp
RtePlayerState State() const
```

<a id="api_rteplayerinfo_state__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

<a id="api_rteplayerinfo_state__return_values"></a>

### 返回值 [#返回值-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)

<a id="api_player_stop_player"></a>

<a id="ariaid-title61"></a>

## Stop [#stop]

停止媒体播放。

<a id="api_player_stop_player__prototype"></a>

```cpp
bool Stop(Error *err = nullptr)
```

<a id="api_player_stop_player__detailed_desc"></a>

:::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。

<a id="api_player_stop_player__timing"></a>

### 调用时机 [#调用时机-38]

此方法必须在调用 [OpenWithUrl](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 之后调用。

<a id="api_player_stop_player__related"></a>

### 相关回调 [#相关回调-4]

成功调用该方法后，SDK 会触发 [onStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#callback_playerobserver_onstatechanged) 回调并报告播放器状态为 `kRtePlayerStateStopped`。

<a id="api_player_stop_player__parameters"></a>

### 参数 [#参数-46]

<ParameterList>
<a id="err-41"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_player_stop_player__return_values"></a>

### 返回值 [#返回值-44]

- true：成功停止播放。
- false：停止播放失败。

### 所属接口类 [#所属接口类-59]

- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)

<a id="api_rteplayerinfo_streamcount"></a>

<a id="ariaid-title62"></a>

## StreamCount [#streamcount]

获取当前播放源中的流数量。

<a id="api_rteplayerinfo_streamcount__prototype"></a>

```cpp
size_t StreamCount() const
```

<a id="api_rteplayerinfo_streamcount__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

:::note
注： [StreamCount](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_rteplayerinfo_streamcount) 方法在打开非 `RTE` URL 时有效。
:::

<a id="api_rteplayerinfo_streamcount__return_values"></a>

### 返回值 [#返回值-45]

方法调用成功，返回当前播放源中的流数量。

### 所属接口类 [#所属接口类-60]

- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)

<a id="api_player_switchwithurl"></a>

<a id="ariaid-title63"></a>

## SwitchWithUrl [#switchwithurl]

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

<a id="api_player_switchwithurl__prototype"></a>

```cpp
void SwitchWithUrl(const char* url, bool sync_pts, std::function<void(rte::Error* err)> cb)
```

<a id="api_player_switchwithurl__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

:::note
注： 该方法仅在播放器已打开非 `RTE` URL 时有效。请在 SDK 报告播放器状态为 `kRtePlayerStateOpenCompleted` 时调用该方法。
:::

<a id="api_player_switchwithurl__parameters"></a>

### 参数 [#参数-47]

<ParameterList>
<a id="url-2"></a>
<Parameter name="url">

要切换到的新 URL。

</Parameter>
<a id="sync_pts"></a>
<Parameter name="sync_pts">

是否同步播放位置：

- true：同步播放位置。
- false：（默认）不同步播放位置。

</Parameter>
<a id="cb-3"></a>
<Parameter name="cb">

异步通知切换操作结果的回调。你可以通过该回调的 `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，不支持切换。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-61]

- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)

<a id="api_player_unregisterobserver_player"></a>

<a id="ariaid-title64"></a>

## UnregisterObserver [#unregisterobserver]

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

<a id="api_player_unregisterobserver_player__prototype"></a>

```cpp
bool UnregisterObserver(PlayerObserver *observer, Error *err = nullptr)
```

<a id="api_player_unregisterobserver_player__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

调用 [RegisterObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_registerobserver_player) 注册播放器事件观察者后，如需取消注册，可调用该方法。

<a id="api_player_unregisterobserver_player__timing"></a>

### 调用时机 [#调用时机-39]

该方法必须在调用 [RegisterObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_registerobserver_player) 之后调用。

<a id="api_player_unregisterobserver_player__parameters"></a>

### 参数 [#参数-48]

<ParameterList>
<a id="observer-1"></a>
<Parameter name="observer">

播放器事件观察者对象实例，详见 [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver)。

</Parameter>
<a id="err-42"></a>
<Parameter name="err">

输出参数，状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

<a id="api_player_unregisterobserver_player__return_values"></a>

### 返回值 [#返回值-46]

- true：取消注册成功。
- false：取消注册失败。

### 所属接口类 [#所属接口类-62]

- [Player](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_player)

<a id="api_rteplayerinfo_videoheight"></a>

<a id="ariaid-title65"></a>

## VideoHeight [#videoheight]

获取视频分辨率的高度。

<a id="api_rteplayerinfo_videoheight__prototype"></a>

```cpp
int VideoHeight() const
```

<a id="api_rteplayerinfo_videoheight__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

<a id="api_rteplayerinfo_videoheight__return_values"></a>

### 返回值 [#返回值-47]

方法调用成功，返回视频分辨率的高度，单位为像素。

### 所属接口类 [#所属接口类-63]

- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)

<a id="api_rteplayerinfo_videowidth"></a>

<a id="ariaid-title66"></a>

## VideoWidth [#videowidth]

获取视频分辨率的宽度。

<a id="api_rteplayerinfo_videowidth__prototype"></a>

```cpp
int VideoWidth() const
```

<a id="api_rteplayerinfo_videowidth__detailed_desc"></a>

:::info[自从]
自 v4.5.1 版本新增。
:::

<a id="api_rteplayerinfo_videowidth__return_values"></a>

### 返回值 [#返回值-48]

方法调用成功，返回视频分辨率的宽度，单位为像素。

### 所属接口类 [#所属接口类-64]

- [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)

<a id="callback_playerobserver_onaudiovolumeindication_playerobserver"></a>

<a id="ariaid-title67"></a>

## onAudioVolumeIndication [#onaudiovolumeindication]

[onAudioVolumeIndication](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#callback_playerobserver_onaudiovolumeindication_playerobserver) 回调。播放器音量变化时触发。

<a id="callback_playerobserver_onaudiovolumeindication_playerobserver__prototype"></a>

```cpp
virtual void onAudioVolumeIndication(int32_t volume) {}
```

<a id="callback_playerobserver_onaudiovolumeindication_playerobserver__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="callback_playerobserver_onaudiovolumeindication_playerobserver__timing"></a>

### 触发时机 [#触发时机]

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

<a id="callback_playerobserver_onaudiovolumeindication_playerobserver__parameters"></a>

### 参数 [#参数-49]

<ParameterList>
<a id="volume-1"></a>
<Parameter name="volume">

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

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-65]

- [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver)

<a id="callback_playerobserver_onevent"></a>

<a id="ariaid-title68"></a>

## onEvent [#onevent]

播放器事件回调。

<a id="callback_playerobserver_onevent__prototype"></a>

```cpp
virtual void onEvent(PlayerEvent event) {}
```

<a id="callback_playerobserver_onevent__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

调用 [RegisterObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_registerobserver_player) 注册播放器观察者对象后，才能监听播放器事件。

<a id="callback_playerobserver_onevent__timing"></a>

### 触发时机 [#触发时机-1]

当播放器事件发生时，SDK 会触发该回调。

<a id="callback_playerobserver_onevent__parameters"></a>

### 参数 [#参数-50]

<ParameterList>
<a id="event"></a>
<Parameter name="event">

播放器事件，详见 [RtePlayerEvent](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rteplayerevent)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-66]

- [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver)

<a id="callback_playerobserver_onmetadata_playerobserver"></a>

<a id="ariaid-title69"></a>

## onMetadata [2/2] [#onmetadata-22]

接收媒体流中元数据的回调。

<a id="callback_playerobserver_onmetadata_playerobserver__prototype"></a>

```cpp
virtual void onMetadata(PlayerMetadataType type, const uint8_t *data, size_t length) {}
```

<a id="callback_playerobserver_onmetadata_playerobserver__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

如果你需要从媒体流中获取元数据，必须先调用 [RegisterObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_registerobserver_player) 注册播放器观察者对象。

<a id="callback_playerobserver_onmetadata_playerobserver__timing"></a>

### 触发时机 [#触发时机-2]

当 SDK 从正在播放的媒体流中解析出元数据后，会触发该回调报告元数据类型及其内容。

<a id="callback_playerobserver_onmetadata_playerobserver__parameters"></a>

### 参数 [#参数-51]

<ParameterList>
<a id="type"></a>
<Parameter name="type">

元数据类型，详见 [RtePlayerMetadataType](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rteplayermetadatatype)。

</Parameter>
<a id="data"></a>
<Parameter name="data">

解析后的元数据内容。

</Parameter>
<a id="length"></a>
<Parameter name="length">

数据的字节大小。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-67]

- [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver)

<a id="callback_playerobserver_onplayerinfoupdated_playerobserver"></a>

<a id="ariaid-title70"></a>

## onPlayerInfoUpdated [2/2] [#onplayerinfoupdated-22]

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

<a id="callback_playerobserver_onplayerinfoupdated_playerobserver__prototype"></a>

```cpp
virtual void onPlayerInfoUpdated(const PlayerInfo *info) {}
```

<a id="callback_playerobserver_onplayerinfoupdated_playerobserver__detailed_desc"></a>

:::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) 获取信息。

<a id="callback_playerobserver_onplayerinfoupdated_playerobserver__timing"></a>

### 触发时机 [#触发时机-3]

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

<a id="callback_playerobserver_onplayerinfoupdated_playerobserver__parameters"></a>

### 参数 [#参数-52]

<ParameterList>
<a id="info-1"></a>
<Parameter name="info">

播放器和媒体流的信息。详见 [PlayerInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-68]

- [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver)

<a id="callback_playerobserver_onpositionchanged_playerobserver"></a>

<a id="ariaid-title71"></a>

## onPositionChanged [#onpositionchanged]

播放进度变化回调。

<a id="callback_playerobserver_onpositionchanged_playerobserver__prototype"></a>

```cpp
virtual void onPositionChanged(uint64_t curr_time, uint64_t utc_time) {}
```

<a id="callback_playerobserver_onpositionchanged_playerobserver__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

<a id="callback_playerobserver_onpositionchanged_playerobserver__timing"></a>

### 触发时机 [#触发时机-4]

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

<a id="callback_playerobserver_onpositionchanged_playerobserver__parameters"></a>

### 参数 [#参数-53]

<ParameterList>
<a id="curr_time"></a>
<Parameter name="curr_time">

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

</Parameter>
<a id="utc_time"></a>
<Parameter name="utc_time">

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

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-69]

- [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver)

<a id="callback_playerobserver_onresolutionchanged"></a>

<a id="ariaid-title72"></a>

## onResolutionChanged [#onresolutionchanged]

视频分辨率发生变化时触发的回调。

<a id="callback_playerobserver_onresolutionchanged__prototype"></a>

```cpp
virtual void onResolutionChanged(int width, int height) {}
```

<a id="callback_playerobserver_onresolutionchanged__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

如果你需要监控播放器播放的视频流的分辨率变化，必须先调用 [RegisterObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_registerobserver_player) 注册播放器观察者对象。

<a id="callback_playerobserver_onresolutionchanged__timing"></a>

### 触发时机 [#触发时机-5]

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

<a id="callback_playerobserver_onresolutionchanged__parameters"></a>

### 参数 [#参数-54]

<ParameterList>
<a id="width"></a>
<Parameter name="width">

视频帧的宽度（像素）。

</Parameter>
<a id="height"></a>
<Parameter name="height">

视频帧的高度（像素）。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-70]

- [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver)

<a id="callback_playerobserver_onstatechanged"></a>

<a id="ariaid-title73"></a>

## onStateChanged [#onstatechanged]

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

<a id="callback_playerobserver_onstatechanged__prototype"></a>

```cpp
virtual void onStateChanged(PlayerState old_state, PlayerState new_state, rte::Error *err) {}
```

<a id="callback_playerobserver_onstatechanged__detailed_desc"></a>

:::info[自从]
自 v4.4.0 版本新增。
:::

如果你需要监听播放器状态的变化，必须先调用 [RegisterObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_registerobserver_player) 注册播放器观察者对象。

<a id="callback_playerobserver_onstatechanged__timing"></a>

### 触发时机 [#触发时机-6]

当播放器状态发生变化时，SDK 会触发该回调以报告当前状态和之前的状态。

<a id="callback_playerobserver_onstatechanged__parameters"></a>

### 参数 [#参数-55]

<ParameterList>
<a id="old_state"></a>
<Parameter name="old_state">

播放器之前的状态，详见 [RtePlayerState](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rteplayerstate)。

</Parameter>
<a id="new_state"></a>
<Parameter name="new_state">

播放器当前的状态，详见 [RtePlayerState](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rteplayerstate)。如果当前状态为 `kRtePlayerStateFailed`，你可以通过 `err` 参数获取详细的错误信息。

</Parameter>
<a id="err-43"></a>
<Parameter name="err">

状态或错误信息，详见 [Error](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_error)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-71]

- [PlayerObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_playerobserver)