URL 拉流播放
AddView
Code
获取接口调用返回的错误码。
ErrorCode Code();
调用时机
当调用 API 失败时，可调用此方法以获取错误码。
调用限制
无。
返回值
错误码。详见 RteErrorCode。
Destroy
GetInfo
Message
获取详细的错误信息。
const char *Message();
调用时机
当 API 调用失败后，你可以调用该方法获取错误信息来帮助排查问题。
调用限制
无。
返回值
MuteAudio
订阅或取消订阅主播的音频流。
bool MuteAudio(bool mute, Error* err);
观众端可以调用该方法来设置是否订阅主播的音频流。
调用时机
该方法需要在 OpenWithUrl 之后调用。
调用限制
无。
相关回调
成功调用该方法后，会触发 onPlayerInfoUpdated [2/2] 回调报告最新的播放器和媒体流信息。
参数
- mute
- 是否订阅主播的音频流：
true：不订阅主播的音频流。false：订阅主播的音频流。
- err
- 状态或错误信息，详见 Error。
返回值
true：操作成功。false：操作失败。
MuteVideo
订阅或取消订阅主播的视频流。
bool MuteVideo(bool mute, Error* err);
观众端可以调用该方法来设置是否订阅主播的视频流。
调用时机
该方法需要在 OpenWithUrl 之后调用。
调用限制
无。
相关回调
成功调用该方法后，会触发 onPlayerInfoUpdated [2/2] 回调报告最新的播放器和媒体流信息。
参数
- mute
- 是否订阅主播的视频流：
true：不订阅主播的视频流。false：订阅主播的视频流。
- err
- 状态或错误信息，详见 Error。
返回值
true：操作成功。false：操作失败。
OpenWithUrl
打开 URL 资源。
void OpenWithUrl(const char* url, uint64_t start_time, std::function<void(rte::Error* err)> cb);
该方法支持通过 URL 打开实时流媒体。如果你想要加快打开 URL 资源的速度，可以在调用该方法前，调用 PreloadWithUrl 预加载资源。
如果资源打开失败，你会收到 onStateChanged 的回调报告状态为 kRtePlayerStateFailed。此时你需要先调用 Stop 然后再调用 OpenWithUrl 重新打开 URL 资源。如果你设置关闭了自动播放，打开资源后可以调用 Play 进行播放。
调用时机
该方法需要在 Player 之后调用。
调用限制
该方法目前仅支持打开以 rte:// 开头的 URL。
相关回调
调用该方法后会触发 onStateChanged 回调，报告播放器状态为 kRtePlayerStateOpening，表示正在打开 URL。成功打开后，报告播放器状态为 kRtePlayerStateOpenCompleted。
参数
- url
- 带
rte://前缀的 URL。 - start_time
- 预留参数。
- cb
- 一个异步回调函数，用于通知打开 URL 资源的结果。如果打开过程中出错，你可以通过该回调中的 err 参数得知具体错误信息。详见 Error。
Pause
Player
构造一个播放器对象。
explicit Player(Rte *self, PlayerInitialConfig *config = nullptr) ;
调用时机
该方法需要在 InitMediaEngine 之后调用。
调用限制
无。
参数
- Rte
- 一个 Rte 对象。
- config
- 播放器对象初始化设置，可传空指针。
Play
播放 URL 资源。
bool Play(Error* err);
如果你关闭了自动播放，当你调用 OpenWithUrl 成功打开实时流媒体，你可以调用此方法进行播放。
调用时机
请在收到 onStateChanged 回调报告状态为 kRtePlayerStateOpenCompleted 后再调用该方法。
调用限制
该方法目前仅支持播放带 rte:// 前缀的 URL。
相关回调
成功调用该方法后，会触发 onStateChanged 回调来报告播放器状态。
参数
- err
- 状态或错误信息，详见 Error。
返回值
true：播放成功。false：播放失败。
PreloadWithUrl
预加载 URL 资源。
static bool PreloadWithUrl(const char* url, Error *err = nullptr) {
return RtePlayerPreloadWithUrl(nullptr, url, err != nullptr ? err->get_underlying_impl() : nullptr);
成功预加载后，可以加快通过 OpenWithUrl 打开 URL 资源的速度。当需要使用这些资源时，可以更加快速地访问，缩短等待的过程。
适用场景
在打开媒体资源之前，提前加载可以减少用户等待时间，提供更流畅的视听体验。
调用时机
该方法需要在 OpenWithUrl 之前调用。
调用限制
该方法目前仅对带 rte:// 前缀的 URL 生效，最多可以预加载 20 个 URL。如果超出限制，新预加载的 URL 将会替换最早的 URL。
参数
- url
- 带
rte://前缀的 URL。 - err
- 状态或错误信息，详见 Error。
返回值
true：预加载成功。false：预加载失败。
RemoveView
RegisterObserver
注册播放器观测器的对象。
bool RegisterObserver(PlayerObserver *observer, Error *err);
调用该方法前，你需要实现一个继承自 PlayerObserver 的接口类。
调用时机
该方法需要在 Player 之后调用。
调用限制
无。
参数
- observer
- 接口对象实例，详见 PlayerObserver。
- err
- 状态或错误信息，详见 Error。
返回值
true：注册成功。false：注册失败。
Rte
构造一个 RTE 对象。
explicit Rte(InitialConfig *config = nullptr);
RTE 对象用于组织和管理 Rte 内部相关资源。
调用时机
该方法需要在 InitMediaEngine 前调用。
调用限制
无。
参数
- config
- 初始化设置，当前可传空。
SetAbrFallbackLayer
设置已订阅的视频流的回退选项。
void SetAbrFallbackLayer(AbrFallbackLayer abr_fallback_layer, Error *err = nullptr);
网络不理想的环境下，实时通信音视频的质量会下降。调用该方法后，SDK 会在网络情况差的时候将视频流的分辨率回退到你指定的视频质量层级。不同的视频质量层级对应不同的分辨率和码率。同时，SDK 会持续监控网络质量，并在网络质量改善时恢复至你所订阅的视频流质量层级。
默认情况下，调用该方法后只能在源频道选择回退至 kRteAbrFallbackLow 或 kRteAbrFallbackAudioOnly。如果你对视频体验有更高要求，你可以联系技术支持开通 ABR 功能。启用该功能后，可以在转码频道选择回退到所有质量层级的视频流，并支持自定义不同质量层级的视频流所对应的分辨率。
适用场景
- 在一般场景下，你可以调用该方法并将回退的质量层级设为 kRteAbrFallbackLow 或 kRteAbrFallbackAudioOnly，SDK 会在网络情况差的时候将视频流回退为低质量的视频流、或是仅接收音频流。
- 如果对视频流回退的分辨率要求较高，可以联系联系技术支持开通 ABR 功能。开通后，你可以自定义每个层级的分辨率。SDK 会以你指定的最低质量层级分辨率为下限，在此范围内根据网络状况动态调整分辨率。
调用时机
该方法需要在 SetConfigs [2/3] 之前调用。
调用限制
调用该方法时如果你未开通 ABR 功能，视频流回退的质量层级只能选择 kRteAbrFallbackLow 或 kRteAbrFallbackAudioOnly。
参数
- abr_fallback_layer
- 视频流回退的质量层级，详见 RteAbrFallbackLayer。在自定义 kRteAbrFallbackLayer1 至 kRteAbrFallbackLayer6 的分辨率时，可以参考下表进行设置，你也可以根据实际需求自行设置：
视频质量层级 分辨率 kRteAbrSubscriptionLayer1 2160p（4K）
kRteAbrSubscriptionLayer2 1440p（2K） kRteAbrSubscriptionLayer3 1080p（HD） kRteAbrSubscriptionLayer4 720p（HD） kRteAbrSubscriptionLayer5 540p（SD） kRteAbrSubscriptionLayer6 480p（SD） 注意自定义分辨率时请务必将视频质量层级（Layer）按分辨率从大到小进行排序，分辨率相同时需按帧率从大到小进行排序。 - err
- 状态或错误信息，详见 Error。
SetAbrSubscriptionLayer
设置订阅的媒体流的质量层级。
void SetAbrSubscriptionLayer(AbrSubscriptionLayer abr_subscription_layer, Error *err = nullptr);
你可以根据实际的网络情况切换订阅不同的视频流质量层级，对应不同的分辨率。 默认情况下，调用该方法后观众只能在源频道切换订阅视频的大小流，即在 kRteAbrSubscriptionHigh 和 kRteAbrSubscriptionLow 之间切换。如对视频分辨率切换有更高要求，你可以联系技术支持开通 ABR（自适应码率）功能。启用该功能后，你可以自定义不同质量层级的视频流所对应的分辨率，观众可以在专门的转码频道根据需求切换所有质量层级的视频流。
适用场景
在网络环境不稳定的情况下，观众端可以根据实际的网络状况来选择订阅合适的视频质量级别，以保证流畅的观感体验。
调用时机
该方法需要在 SetConfigs [2/3] 之前调用。
调用限制
调用该方法时如果你未开通 ABR 功能，订阅的视频质量层级只能选择 kRteAbrSubscriptionHigh 或 kRteAbrSubscriptionLow。
参数
- abr_subscription_layer
- 订阅的视频质量层级，详见 RteAbrSubscriptionLayer。在自定义 kRteAbrSubscriptionLayer1 至 kRteAbrSubscriptionLayer6 的分辨率时，可以参考下表进行设置，你也可以根据实际需求自行设置：注意自定义分辨率时请务必将视频质量层级（Layer）按分辨率从大到小进行排序，分辨率相同时需按帧率从大到小进行排序。
视频质量层级 分辨率 kRteAbrSubscriptionLayer1 2160p（4K）
kRteAbrSubscriptionLayer2 1440p（2K） kRteAbrSubscriptionLayer3 1080p（HD） kRteAbrSubscriptionLayer4 720p（HD） kRteAbrSubscriptionLayer5 540p（SD） kRteAbrSubscriptionLayer6 480p（SD） - err
- 状态或错误信息，详见 Error。
SetAppId
设置 App ID。
void SetAppId(const char *app_id, Error *err);
调用时机
该方法需要在 InitMediaEngine 之前调用。
调用限制
无。
参数
- appId
- 你的项目的 App ID，在声网控制台获取。
- err
- 状态或错误信息，详见 Error。
SetAutoPlay
设置是否自动播放。
void SetAutoPlay(bool auto_play, Error *err = nullptr);
当你调用 OpenWithUrl 打开媒体流之前，你可以调用该方法设置是否自动播放。如不设置，默认会启用自动播放。
调用时机
该方法需要在 OpenWithUrl 之前调用。
调用限制
无。
参数
- auto_play
- 是否自动播放：
true：（默认）开启自动播放。false：关闭自动播放。
- err
- 状态或错误信息，详见 Error。
SetCanvas
SetConfigs [1/3]
SetConfigs [2/3]
SetConfigs [3/3]
设置播放器视频渲染配置。
bool SetConfigs(CanvasConfig *config, Error *err);
调用时机
该方法需要在 OpenWithUrl 之前调用。
调用限制
无。
参数
- config
- Canvas 对象的设置，详见 CanvasConfig。
- err
- 状态或错误信息，详见 Error。
返回值
true：配置成功。false：配置失败。
SetJsonParameter
通过 JSON 配置 SDK 提供技术预览或特别定制功能。
void SetJsonParameter(const char *json_parameter, Error *err = nullptr);
适用场景
当你需要设置私有参数或使用定制功能时，可以调用该方法。
调用时机
该方法需要在 SetConfigs [1/3] 之前调用。
调用限制
无。
参数
- json_parameter
- JSON 字符串形式的参数。
- err
- 状态或错误信息，详见 Error。
SetMirrorMode
设置视频的镜像模式。
void SetMirrorMode(VideoMirrorMode mode, Error *err = nullptr);
调用时机
该方法需要在 SetConfigs [3/3] 之前调用。
调用限制
无。
参数
- mode
- 镜像模式，详见 RteVideoMirrorMode。默认为 kRteVideoMirrorModeAuto，即由 SDK 决定镜像模式。默认关闭远端用户的镜像模式。
- err
- 状态或错误信息，详见 Error。
SetRenderMode
设置视频的渲染模式。
void SetRenderMode(VideoRenderMode mode, Error *err = nullptr);
调用时机
该方法需要在 SetConfigs [3/3] 之前调用。
调用限制
无。
参数
- mode
- 渲染模式，详见 RteVideoRenderMode。默认的渲染模式为 kRteVideoRenderModeHidden，即视频尺寸等比缩放，优先保证视窗被填满。
- err
- 状态或错误信息，详见 Error。
Stop
停止播放媒体资源。
bool Stop(Error* err);
当你成功打开 URL 流并调用 Play 播放后，如果你想停止播放，可以调用此方法。如果你需要暂停播放，请调用 Pause。
如果你调用 OpenWithUrl 打开 URL 流失败，需要先调用此方法，然后再调用 OpenWithUrl 重新打开 URL。
调用时机
该方法需要在 OpenWithUrl 之后调用。
调用限制
无。
相关回调
成功调用该方法后会触发 onStateChanged 回调，并报告播放器状态为 kRtePlayerStateStopped。
参数
- err
- 状态或错误信息，详见 Error。
返回值
true：停止播放成功。false：停止播放失败。
GetAbrFallbackLayer
获取已设置的视频流回退选项。
AbrFallbackLayer GetAbrFallbackLayer(Error *err = nullptr);
调用时机
该方法需要在 GetConfigs [2/3] 之后调用。
调用限制
无。
参数
- err
- 状态或错误信息，详见 Error。
返回值
设置的视频流回退选项，详见 RteAbrFallbackLayer。
所属接口类GetAbrSubscriptionLayer
获取所订阅的视频流的质量层级。
AbrSubscriptionLayer GetAbrSubscriptionLayer(Error *err = nullptr);
调用时机
该方法需要在 GetConfigs [2/3] 之后调用。
调用限制
无。
参数
- err
- 状态或错误信息，详见 Error。
返回值
当前设置的视频质量层级，详见 RteAbrSubscriptionLayer。
所属接口类GetAppId
GetAutoPlay
获取自动播放设置。
bool GetAutoPlay(Error *err = nullptr);
你可以调用该方法来得知当前播放器的自动播放设置。
调用时机
该方法需要在 GetConfigs [2/3] 之后调用。
调用限制
无。
参数
- err
- 状态或错误信息，详见 Error。
返回值
true：获取成功。false：获取失败。
GetConfigs [1/3]
GetConfigs [2/3]
GetConfigs [3/3]
GetFromBridge
从 IRtcEngine 中桥接出一个 RTE 对象。
static Rte GetFromBridge(Error* err = nullptr);
调用该方法创建的 RTE 对象，无需再通过 InitMediaEngine 进行初始化。如果你之前未创建并初始化 RTC 引擎，可以先调用 Rte 创建一个 RTE 对象，然后再调用 InitMediaEngine 进行初始化。
调用时机
调用该方法前，请确保已调用 initialize 初始化 RTC 引擎。
调用限制
无。
参数
- err
- 指向 Error 对象的指针，用于接收状态及错误码。
返回值
一个 RTE 对象。
所属接口类GetJsonParameter
获取已设置的 SDK JSON 配置信息。
std::string GetJsonParameter(Error *err = nullptr)
当你调用 SetJsonParameter 设置 JSON 配置信息后，你可以调用该方法获取已设置的配置信息。
调用时机
该方法需要在 GetConfigs [1/3] 之后调用。
调用限制
无。
参数
- err
- 状态或错误信息，详见 Error。
返回值
- 方法调用成功，返回设置的 JSON 配置信息。
- 方法调用失败，返回空字符串。
GetMirrorMode
获取当前设置的镜像模式。
VideoMirrorMode GetMirrorMode(Error *err = nullptr);
调用时机
该方法需要在 GetConfigs [3/3] 之后调用。
调用限制
无。
参数
- err
- 状态或错误信息，详见 Error。
返回值
当前设置的镜像模式，详见 RteVideoMirrorMode。
GetRenderMode
获取当前设置的视频渲染模式。
VideoRenderMode GetRenderMode(Error *err = nullptr)
调用时机
该方法需要在 GetConfigs [3/3] 之后调用。
调用限制
无。
参数
- err
- 状态或错误信息，详见 Error。
返回值
当前设置的视频渲染模式，详见 RteVideoRenderMode。
GetStats
获取播放器当前播放的媒体资源的统计信息。
void GetStats(std::function<void(rte::PlayerStats *stats, rte::Error *err)> cb)
该方法用于获取播放器的统计信息，包括解码、渲染帧率、音视频码率等，并通过回调函数异步返回结果。
调用时机
该方法需要在 OpenWithUrl 之后调用。
调用限制
无。
参数
- cb
- 一个异步回调函数，用于通知获取播放器媒体资源统计信息的结果和错误信息。该函数包含以下参数：
stats： 播放器当前播放的媒体资源的统计数据，详见 RtePlayerStats。err： 获取错误信息，详见 Error。
InitMediaEngine
初始化 RTE 引擎。
bool InitMediaEngine(std::function<void(rte::Error *err)> cb, Error *err = nullptr);
此方法为异步方法，通过回调函数返回初始化结果。
调用时机
该方法需要在创建 RTE 对象并设置 App ID 后调用。
调用限制
无。
参数
- cb
- 一个异步回调函数，用于返回引擎初始化结果。你可以通过该回调的 err 参数得知引擎初始化的结果或错误码信息，详见 Error。
- err
- 初始化过程中的错误信息，详见 Error。在调用 InitMediaEngine 方法初始化时，如果过程遇到立即可检测的错误（如参数无效、资源不足等），SDK 会通过此参数同步返回错误信息。
返回值
true：成功加入队列。false：未成功加入队列。
UnregisterObserver
取消注册播放器事件观测器的对象。
bool UnregisterObserver(PlayerObserver *observer, Error *err);
调用 RegisterObserver 注册播放器事件观测器后，如果你需要取消注册，请调用该方法。
调用时机
该方法需在 RegisterObserver 之后调用。
调用限制
无。
参数
- observer
- 接口对象实例，详见 PlayerObserver。
- err
- 状态或错误信息，详见 Error。
返回值
true：取消注册成功。false：取消注册失败。
onAudioVolumeIndication
主播音量提示回调。
virtual void onAudioVolumeIndication(int32_t volume) = 0;
触发时机
当主播的音量发生变化时，SDK 会触发该回调。
使用限制
无。
参数
- volume
- 主播当前的音量，取值范围为 [0,225]。
onEvent
播放器事件回调。
virtual void onEvent(PlayerEvent event) = 0;
如果你需要监控播放器事件，需要先调用 RegisterObserver 注册播放器观测器的对象。
触发时机
当播放器事件发生变化时，SDK 会触发该回调。
使用限制
无。
参数
- event
- 播放器事件，详见 RtePlayerEvent。
onMetadata [2/2]
已获取媒体附属信息回调。
virtual void onMetadata(PlayerMetadataType type,
const uint8_t *data, size_t length) = 0;
如果你需要获取媒体流的附属信息，需要先调用 RegisterObserver 注册播放器观测器的对象。
触发时机
在 SDK 解析播放器所播放的媒体流的附属信息后，会触发该回调报告数据的类型及其具体内容。
使用限制
无。
参数
- type
- 附属信息类型，详见 RtePlayerMetadataType。
- data
- 解析的附属信息。
- length
- 数据的大小（字节）。
onPlayerInfoUpdated [2/2]
播放器及媒体流的相关信息发生变化回调。
virtual void onPlayerInfoUpdated(const PlayerInfo *info) = 0;
如果你需要获取播放器、媒体流的相关信息，需要先调用 RegisterObserver 注册播放器观测器的对象。你也可以直接通过 GetInfo 方法来获取。
触发时机
当播放器及媒体流的相关信息发生变化时，SDK 会触发该回调。
使用限制
无。
参数
- info
- 播放器及媒体流的相关信息，详见 RtePlayerInfo。
onResolutionChanged
视频分辨率发生改变回调。
virtual void onResolutionChanged(int width, int height) = 0;
如果你需要监控播放器所播放视频流分辨率的变化，需要先调用 RegisterObserver 注册播放器观测器的对象。
触发时机
当视频流的分辨率发生变化时，SDK 会触发该回调报告当前视频的宽高。
使用限制
无。
参数
- width
- 视频帧的宽度（px）。
- height
- 视频帧的高度（px）。
onStateChanged
播放器状态发生改变回调。
virtual void onStateChanged(PlayerState old_state, PlayerState new_state,
rte::Error *err) = 0;
如果你需要监控播放器状态的变化，需要先调用 RegisterObserver 注册播放器观测器的对象。
触发时机
当播放器状态发生变化时，SDK 会触发此回调报告当前和变化之前的状态。
使用限制
无。
参数
- old_state
- 播放器变化前的状态，详见 RtePlayerState。
- new_state
- err
- 状态或错误信息，详见 Error。