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