URL 拉流播放
AbrSubscriptionLayer
获取当前订阅的视频层级。
AbrSubscriptionLayer AbrSubscriptionLayer() const
返回值
方法调用成功，返回当前订阅的视频层级，详见 RteAbrSubscriptionLayer。
所属接口类AddView
添加一个渲染视图。
bool AddView(View *view, ViewConfig *config, rte::Error *err = nullptr)
当你需要使用播放器播放视频时，可以调用该方法向视频渲染器添加一个视图，以显示视频内容。
适用场景
当你需要使用播放器播放视频时，可以调用此方法将视图添加到视频渲染器中，以显示视频内容。
调用时机
该方法必须在调用 SetCanvas 之前调用。
参数
- view
HWND窗口句柄。- config
View对象的设置，当前传入 NULL。- err
- 状态或错误信息，详见 Error。
返回值
- true：视图添加成功。
- false：添加视图失败。
AudioBitsPerSample
获取每个音频采样的位数。
int AudioBitsPerSample() const
RTE URL 时该字段有效。返回值
方法调用成功，返回每个音频采样的位数，单位为 bit。
所属接口类AudioChannels
AudioSampleRate
Canvas
Code
获取 API 调用失败时返回的错误码。
ErrorCode Code() const
调用时机
当 API 调用失败时，可以调用此方法获取错误码。
返回值
方法调用成功，返回错误码，详见 RteErrorCode。
所属接口类CurrentUrl
获取当前正在播放的 URL。
std::string CurrentUrl() const
返回值
- 方法调用成功时，返回当前正在播放的 URL。
- 方法调用失败，返回空字符串。
Destroy
Duration
获取当前媒体资源的时长。
size_t Duration() const
返回值
方法调用成功，返回当前媒体资源的时长，单位为毫秒。
所属接口类GetAbrFallbackLayer
获取已配置的视频流回退选项。
AbrFallbackLayer GetAbrFallbackLayer(Error *err = nullptr)
调用时机
在调用 GetConfigs 之后调用该方法。
参数
- err
- 输出参数，状态或错误信息，详见 Error。
返回值
方法调用成功时，返回已配置的视频流回退选项，详见 RteAbrFallbackLayer。
所属接口类GetAbrSubscriptionLayer
获取当前设置的已订阅视频流的质量层级。
AbrSubscriptionLayer GetAbrSubscriptionLayer(Error *err = nullptr)
调用时机
在调用 GetConfigs 之后调用该方法。
参数
- err
- 输出参数，状态或错误信息，详见 Error。
返回值
方法调用成功，返回当前设置的视频质量层级，详见 RteAbrSubscriptionLayer。
所属接口类GetAppId
GetAutoPlay
GetConfigs [3/3]
GetConfigs [2/3]
GetConfigs [1/3]
GetFromBridge
从 IRtcEngine 中桥接一个 RTE 对象。
static Rte GetFromBridge(Error* err = nullptr)
通过该方法创建的 RTE 对象无需再调用 InitMediaEngine 进行初始化。如果尚未创建并初始化 RTC 引擎，可以先调用 Rte 创建一个 RTE 对象，再调用 InitMediaEngine 进行初始化。
调用时机
在调用此方法之前，请确保你已调用 initialize 初始化 RTC 引擎。
参数
- err
- 输出参数，用于接收状态或错误信息，详见 Error。
返回值
- 方法调用成功，返回一个
RTE对象，详见RTE。 - 方法调用失败，返回 NULL。
GetInfo
GetJsonParameter
获取已配置的 SDK JSON 配置信息。
std::string GetJsonParameter(Error *err = nullptr)
调用 SetJsonParameter 设置 JSON 配置后，可调用本方法获取已配置的信息。
调用时机
必须在调用 GetConfigs 之后调用此方法。
参数
- err
- 输出参数，状态或错误信息，详见 Error。
返回值
- 方法调用成功时，返回已配置的 JSON 信息。
- 方法调用失败，返回空字符串。
GetLoopCount
GetMirrorMode
获取当前设置的视频镜像模式。
VideoMirrorMode GetMirrorMode(Error *err = nullptr)
调用时机
该方法必须在调用 GetConfigs 之后调用。
参数
- err
- 输出参数，状态或错误信息，详见 Error。
返回值
方法调用成功，返回当前设置的镜像模式，详见 RteVideoMirrorMode。
所属接口类GetPlaybackSpeed
GetPlayoutVolume
GetPosition
GetRenderMode
获取当前设置的视频渲染模式。
VideoRenderMode GetRenderMode(Error *err = nullptr)
调用时机
该方法必须在调用 GetConfigs 之后调用。
参数
- err
- 输出参数，状态或错误信息，详见 Error。
返回值
当前设置的视频渲染模式，详见 RteVideoRenderMode。
所属接口类GetStats
获取播放器当前播放的媒体资源的统计信息。
void GetStats(std::function<void(rte::PlayerStats *stats, rte::Error *err)> cb)
该方法通过回调异步返回播放器的统计信息，包括解码情况、渲染帧率、音视频码率等。
调用时机
该方法必须在调用 OpenWithUrl 之后调用。
参数
- cb
- 异步通知获取播放器媒体资源统计信息结果的回调。你可以通过该回调的参数获取以下信息：
stats：播放器当前播放媒体资源的统计数据，详见 RtePlayerStats。err：状态或错误信息，详见 Error。
HasAudio
判断媒体资源中是否包含音频流。
bool HasAudio() const
返回值
- true：媒体资源中包含音频流。
- false：媒体资源中不包含音频流。
HasVideo
判断 URL 源中是否包含视频流。
bool HasVideo() const
返回值
- true：URL 源包含视频流。
- false：URL 源不包含视频流。
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：未能将初始化操作加入异步任务队列。
IsAudioMuted
判断播放器是否停止接收音频流。
bool IsAudioMuted() const
返回值
- true：播放器已停止接收音频流。
- false：播放器仍在接收音频流。
IsVideoMuted
判断播放器是否停止接收视频流。
bool IsVideoMuted() const
返回值
- true：播放器已停止接收视频流。
- false：播放器仍在接收视频流。
Message
MuteAudio
接收或停止接收音频流。
bool MuteAudio(bool mute, Error *err = nullptr)
调用时机
该方法必须在调用 OpenWithUrl 之后调用。
相关回调
成功调用该方法后，SDK 会触发 onPlayerInfoUpdated 回调报告最新的播放器和媒体流信息。
参数
- mute
- 是否接收音频流：
- true：不接收音频流。
- false：接收音频流。
- err
- 输出参数，状态或错误信息，详见 Error。
返回值
true 表示操作成功，false 表示操作失败。
所属接口类MuteVideo
接收或停止接收视频流。
bool MuteVideo(bool mute, Error *err = nullptr)
调用时机
该方法必须在调用 OpenWithUrl 之后调用。
相关回调
成功调用该方法后，SDK 会触发 onPlayerInfoUpdated 回调报告最新的播放器和媒体流信息。
参数
- 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 开始播放。
rte:// 开头的 URL、CDN 推流 URL 和本地媒体文件。调用时机
该方法必须在 Player 初始化后调用。
相关回调
成功调用该方法后，SDK 会触发 onStateChanged 回调报告播放器状态为 kRtePlayerStateOpening，表示正在打开 URL。打开成功后，播放器状态将报告为 kRtePlayerStateOpenCompleted。
参数
- url
- 要打开的 URL，可以是 CDN 推流 URL、本地媒体文件，或以
rte://开头的 URL。 - start_time
- 开始播放的位置，单位为毫秒。
- cb
- 异步通知 URL 资源打开结果的回调。你可以通过该回调的
err参数获取操作结果或错误码信息，详见 Error。
Pause
Play
播放一个 URL 资源。
bool Play(Error *err = nullptr)
rte:// 开头的 URL。调用时机
在收到 onStateChanged 回调报告状态为 kRtePlayerStateOpenCompleted 后调用此方法。
参数
- err
- 输出参数，状态或错误信息，详见 Error。
返回值
- true：播放成功。
- false：播放失败。
Player
PreloadWithUrl
预加载 URL 资源。
static bool PreloadWithUrl(const char* url, Error *err = nullptr)
预加载成功后，通过 OpenWithUrl 打开该 URL 资源的速度可以提升，从而减少等待时间，提升视听体验。
rte:// 开头的 URL。最多可预加载 20 个 URL，若超过限制，最早预加载的 URL 会被新预加载的 URL 替换。适用场景
在打开媒体资源前预加载，可以减少用户等待时间，提供更流畅的视听体验。
调用时机
该方法必须在调用 OpenWithUrl 之前调用。
参数
- url
- 以
rte://开头的 URL。 - err
- 输出参数，状态或错误信息，详见 Error。
返回值
- true：预加载成功。
- false：预加载失败。
RegisterObserver
注册一个 PlayerObserver 播放器观察者对象。
bool RegisterObserver(PlayerObserver *observer, Error *err = nullptr)
在调用该方法前，你需要实现一个继承自 PlayerObserver 的接口类。
调用时机
该方法必须在调用 Player 之后执行。
参数
- observer
- PlayerObserver 接口对象的实例。详见 PlayerObserver。
- err
- 输出参数，状态或错误信息。详见 Error。
返回值
- true：注册成功。
- false：注册失败。
RemoveView
Rte
构造一个 Rte 对象。
explicit Rte(InitialConfig *config = nullptr)
调用时机
该方法必须在调用 InitMediaEngine 之前调用。
参数
- config
- 初始化设置。你可以传入 NULL。详见
InitialConfig。
Seek
SetAbrFallbackLayer
设置已订阅视频流的回退选项。
void SetAbrFallbackLayer(AbrFallbackLayer abr_fallback_layer, Error *err = nullptr)
在网络状况较差时，SDK 会将视频流的分辨率降级为指定的回退质量层，以保证播放的连续性。不同的质量层对应不同的分辨率和码率。SDK 会持续监测网络状况，在网络恢复后自动将视频流恢复为订阅的质量层。 默认情况下，仅支持回退到 kRteAbrFallbackLow 或 kRteAbrFallbackAudioOnly。如需更灵活的视频体验，可联系技术支持开启 ABR 功能，开启后可回退到所有质量层，并自定义每一层的分辨率。
kRteAbrFallbackLow 或 kRteAbrFallbackAudioOnly。适用场景
一般场景下，可调用该方法并将回退质量层设置为 kRteAbrFallbackLow 或 kRteAbrFallbackAudioOnly。当网络较差时，SDK 会回退为视频小流或仅接收音频流。 如果对回退视频流的分辨率有更高要求，可联系技术支持开启 ABR 功能。开启后，可自定义每一层的分辨率。SDK 会以你指定的最低质量层的分辨率为下限，并根据网络状况在该范围内动态调整分辨率。
调用时机
该方法必须在调用 SetConfigs 之前调用。
参数
- abr_fallback_layer
- 视频流的回退质量层，详见 RteAbrFallbackLayer。当自定义
kRteAbrFallbackLayer1到kRteAbrFallbackLayer6的分辨率时，可参考下表：信息自定义分辨率时，务必将视频质量层按分辨率从高到低排序；当分辨率相同时，按帧率从高到低排序。视频质量层 分辨率 kRteAbrSubscriptionLayer12160p (4K) kRteAbrSubscriptionLayer21440p (2K) kRteAbrSubscriptionLayer31080p (HD) kRteAbrSubscriptionLayer4720p (HD) kRteAbrSubscriptionLayer5540p (SD) kRteAbrSubscriptionLayer6480p (SD) - err
- 状态或错误信息，详见 Error。
SetAbrSubscriptionLayer
设置订阅媒体流的视频质量层级。
void SetAbrSubscriptionLayer(AbrSubscriptionLayer abr_subscription_layer, Error *err = nullptr)
你可以根据实际网络状况在不同的视频流质量层级之间切换，每个层级对应不同的分辨率。默认情况下，调用该方法后，订阅端只能在高低画质之间切换，即 kRteAbrSubscriptionHigh 和 kRteAbrSubscriptionLow。如果你对视频分辨率切换有更高要求，可以联系技术支持开启 ABR（自适应码率）功能。开启后，你可以自定义每个视频质量层级的分辨率，订阅端可根据需要在所有视频质量层级之间切换。
kRteAbrSubscriptionHigh 或 kRteAbrSubscriptionLow。适用场景
在网络环境不稳定的场景中，订阅端可根据实际网络状况选择合适的视频质量层级，以保障流畅的观看体验。
调用时机
该方法必须在调用 SetConfigs 之前调用。
参数
- abr_subscription_layer
- 要订阅的视频质量层级，详见 RteAbrSubscriptionLayer。当自定义
kRteAbrSubscriptionLayer1到kRteAbrSubscriptionLayer6的分辨率时，可参考下表或根据实际需求设置： 注意：自定义分辨率时，需确保视频质量层级按分辨率从高到低排序；当分辨率相同时，按帧率从高到低排序。视频质量层级 分辨率 kRteAbrSubscriptionLayer12160p (4K) kRteAbrSubscriptionLayer21440p (2K) kRteAbrSubscriptionLayer31080p (HD) kRteAbrSubscriptionLayer4720p (HD) kRteAbrSubscriptionLayer5540p (SD) kRteAbrSubscriptionLayer6480p (SD) - err
- 输出参数，状态或错误信息，详见 Error。
SetAppId
设置声网 App ID。
void SetAppId(const char *app_id, Error *err = nullptr)
调用时机
该方法必须在调用 InitMediaEngine 之前调用。
参数
- app_id
- 你的项目的声网 App ID，可从声网控制台获取。
- err
- 输出参数，状态或错误信息。详见 Error。
SetAutoPlay
设置是否自动播放。
void SetAutoPlay(bool auto_play, Error *err = nullptr)
在调用 OpenWithUrl 打开媒体流之前，可以调用该方法设置是否自动播放。如果未设置，默认启用自动播放。
调用时机
该方法必须在调用 OpenWithUrl 之前调用。
参数
- auto_play
- 是否启用自动播放：
- true：（默认）启用自动播放。
- false：不启用自动播放。
- err
- 输出参数，表示状态或错误信息，详见 Error。
SetCanvas
SetConfigs [3/3]
设置播放器的视频渲染配置。
bool SetConfigs(CanvasConfig *config, Error *err = nullptr)
调用时机
该方法必须在调用 OpenWithUrl 之前调用。
参数
- config
- 用于设置 Canvas 对象的配置，详见 CanvasConfig。
- err
- 状态或错误信息，详见 Error。
返回值
- true：配置成功。
- false：配置失败。
SetConfigs [2/3]
SetConfigs [1/3]
SetJsonParameter
SetLoopCount
SetMirrorMode
设置视频的镜像模式。
void SetMirrorMode(VideoMirrorMode mode, Error *err = nullptr)
调用时机
该方法必须在调用 SetConfigs 之前调用。
参数
- mode
- 镜像模式，详见 RteVideoMirrorMode。
- 默认值为
kRteVideoMirrorModeAuto，由 SDK 自动决定镜像模式。 - 默认情况下，远端用户的镜像模式为关闭状态。
- 默认值为
- err
- 输出参数，状态或错误信息，详见 Error。
SetPlaybackSpeed
设置播放速度参数。
void SetPlaybackSpeed(int32_t speed, Error *err = nullptr)
参数
- speed
- 播放速度。有效范围为 [50, 400]。
- err
- 状态或错误信息，详见 Error。
kRteOk：调用成功。kRteErrorInvalidArgument：speed参数设置为无效值。
SetPlayoutVolume
SetRenderMode
设置视频渲染模式。
void SetRenderMode(VideoRenderMode mode, Error *err = nullptr)
调用时机
该方法必须在调用 SetConfigs 之前调用。
参数
- mode
- 渲染模式，详见 RteVideoRenderMode。默认值为
kRteVideoRenderModeHidden，该模式按比例缩放视频并优先填满视图窗口。 - err
- 输出参数，状态或错误信息，详见 Error。
State
获取当前播放器状态。
RtePlayerState State() const
返回值
方法调用成功时，返回当前播放器状态，详见 RtePlayerState。
所属接口类Stop
停止媒体播放。
bool Stop(Error *err = nullptr)
成功调用 OpenWithUrl 和 Play 后，可以调用该方法停止播放。如果希望暂停播放，请调用 Pause 方法。如果使用 OpenWithUrl 打开 URL 流失败，则需要先调用该方法，再重新调用 OpenWithUrl 以重新打开 URL。
调用时机
此方法必须在调用 OpenWithUrl 之后调用。
相关回调
成功调用该方法后，SDK 会触发 onStateChanged 回调并报告播放器状态为 kRtePlayerStateStopped。
参数
- err
- 输出参数，状态或错误信息，详见 Error。
返回值
- true：成功停止播放。
- false：停止播放失败。
StreamCount
获取当前播放源中的流数量。
size_t StreamCount() const
RTE URL 时有效。返回值
方法调用成功，返回当前播放源中的流数量。
所属接口类SwitchWithUrl
在播放过程中切换到新的 URL。
void SwitchWithUrl(const char* url, bool sync_pts, std::function<void(rte::Error* err)> cb)
RTE URL 时有效。请在 SDK 报告播放器状态为 kRtePlayerStateOpenCompleted 时调用该方法。参数
- url
- 要切换到的新 URL。
- sync_pts
- 是否同步播放位置：
- true：同步播放位置。
- false：（默认）不同步播放位置。
- cb
UnregisterObserver
取消注册播放器事件观察者对象。
bool UnregisterObserver(PlayerObserver *observer, Error *err = nullptr)
调用 RegisterObserver 注册播放器事件观察者后，如需取消注册，可调用该方法。
调用时机
该方法必须在调用 RegisterObserver 之后调用。
参数
- observer
- 播放器事件观察者对象实例，详见 PlayerObserver。
- err
- 输出参数，状态或错误信息，详见 Error。
返回值
- true：取消注册成功。
- false：取消注册失败。
VideoHeight
VideoWidth
onAudioVolumeIndication
onAudioVolumeIndication 回调。播放器音量变化时触发。
virtual void onAudioVolumeIndication(int32_t volume) {}
触发时机
当播放器的音量发生变化时，SDK 会触发该回调。
参数
- volume
- 播放器当前的音量，取值范围为 [0, 225]。
onEvent
播放器事件回调。
virtual void onEvent(PlayerEvent event) {}
调用 RegisterObserver 注册播放器观察者对象后，才能监听播放器事件。
触发时机
当播放器事件发生时，SDK 会触发该回调。
参数
- event
- 播放器事件，详见 RtePlayerEvent。
onMetadata [2/2]
接收媒体流中元数据的回调。
virtual void onMetadata(PlayerMetadataType type, const uint8_t *data, size_t length) {}
如果你需要从媒体流中获取元数据，必须先调用 RegisterObserver 注册播放器观察者对象。
触发时机
当 SDK 从正在播放的媒体流中解析出元数据后，会触发该回调报告元数据类型及其内容。
参数
- type
- 元数据类型，详见 RtePlayerMetadataType。
- data
- 解析后的元数据内容。
- length
- 数据的字节大小。
onPlayerInfoUpdated [2/2]
播放器或媒体流信息发生变化时触发的回调。
virtual void onPlayerInfoUpdated(const PlayerInfo *info) {}
如果你需要获取播放器和媒体流的信息，必须先调用 RegisterObserver 注册播放器观察者对象。你也可以直接调用 GetInfo 获取信息。
触发时机
当播放器或媒体流的信息发生变化时，SDK 会触发此回调。
参数
- info
- 播放器和媒体流的信息。详见 PlayerInfo。
onPositionChanged
播放进度变化回调。
virtual void onPositionChanged(uint64_t curr_time, uint64_t utc_time) {}
触发时机
该回调在媒体播放过程中每秒触发一次。
参数
- curr_time
- 当前播放进度，单位为毫秒。
- utc_time
- 当前 NTP（网络时间协议）时间，单位为毫秒。
onResolutionChanged
视频分辨率发生变化时触发的回调。
virtual void onResolutionChanged(int width, int height) {}
如果你需要监控播放器播放的视频流的分辨率变化，必须先调用 RegisterObserver 注册播放器观察者对象。
触发时机
当视频流的分辨率发生变化时，SDK 会触发该回调以报告当前视频的宽度和高度。
参数
- width
- 视频帧的宽度（像素）。
- height
- 视频帧的高度（像素）。
onStateChanged
播放器状态发生变化时触发的回调。
virtual void onStateChanged(PlayerState old_state, PlayerState new_state, rte::Error *err) {}
如果你需要监听播放器状态的变化，必须先调用 RegisterObserver 注册播放器观察者对象。
触发时机
当播放器状态发生变化时，SDK 会触发该回调以报告当前状态和之前的状态。
参数
- old_state
- 播放器之前的状态，详见 RtePlayerState。
- new_state
- err
- 状态或错误信息，详见 Error。