需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

URL 拉流播放

  • C++

更新时间不可用

AbrSubscriptionLayer

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

C++
AbrSubscriptionLayer AbrSubscriptionLayer() const

自从

自 v4.5.1 版本新增。

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

返回值

方法调用成功，返回当前订阅的视频层级，详见 RteAbrSubscriptionLayer。

所属接口类

AddView

添加一个渲染视图。

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

自从

自 v4.4.0 版本新增。

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

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

适用场景

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

调用时机

该方法必须在调用 SetCanvas 之前调用。

参数

参数名描述
view

HWND 窗口句柄。

config

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

err

状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

视图是否添加成功：

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

所属接口类

AudioBitsPerSample

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

C++
int AudioBitsPerSample() const

自从

自 v4.5.1 版本新增。

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

返回值

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

所属接口类

AudioChannels

获取音频的声道数。

C++
int AudioChannels() const

自从

自 v4.5.1 版本新增。

返回值

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

所属接口类

AudioSampleRate

获取音频采样率。

C++
int AudioSampleRate() const

自从

自 v4.5.1 版本新增。

返回值

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

所属接口类

Canvas

构造一个 Canvas 对象。

C++
Canvas(Rte *rte, CanvasInitialConfig *initial_config = nullptr)

调用时机

在调用 InitMediaEngine 之后调用该方法。

参数

参数名描述
rte

Rte 对象。详见 Rte。

initial_config

Canvas 的配置对象。该参数可传入 NULL。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

Code

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

C++
ErrorCode Code() const

自从

自 v4.4.0 版本新增。

调用时机

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

返回值

方法调用成功，返回错误码，详见 RteErrorCode。

所属接口类

CurrentUrl

获取当前正在播放的 URL。

C++
std::string CurrentUrl() const

自从

自 v4.5.1 版本新增。

返回值

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

所属接口类

Destroy

销毁 RTE 对象。

C++
bool Destroy(Error *err = nullptr)

自从

自 v4.4.0 版本新增。

参数

参数名描述
err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

Duration

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

C++
size_t Duration() const

自从

自 v4.5.1 版本新增。

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

返回值

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

所属接口类

GetAbrFallbackLayer

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

C++
AbrFallbackLayer GetAbrFallbackLayer(Error *err = nullptr)

自从

自 v4.4.0 版本新增。

调用时机

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

参数

参数名描述
err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法调用成功时，返回已配置的视频流回退选项，详见 RteAbrFallbackLayer。

所属接口类

GetAbrSubscriptionLayer

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

C++
AbrSubscriptionLayer GetAbrSubscriptionLayer(Error *err = nullptr)

自从

自 v4.4.0 版本新增。

调用时机

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

参数

参数名描述
err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法调用成功，返回当前设置的视频质量层级，详见 RteAbrSubscriptionLayer。

所属接口类

GetAppId

获取已配置的声网 App ID。

C++
std::string GetAppId(Error *err = nullptr)

自从

自 v4.4.0 版本新增。

参数

参数名描述
err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

GetAutoPlay

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

C++
bool GetAutoPlay(Error *err = nullptr)

自从

自 v4.4.0 版本新增。

调用时机

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

参数

参数名描述
err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

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

所属接口类

GetConfigs [3/3]

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

C++
bool GetConfigs(CanvasConfig *config, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

调用时机

在调用 Canvas 之后调用该方法。

参数

参数名描述
config

输出参数，表示 Canvas 对象的设置，详见 CanvasConfig。

err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

GetConfigs [2/3]

获取当前播放器配置。

C++
bool GetConfigs(PlayerConfig* config, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

调用时机

在调用 Player 后调用该方法。

参数

参数名描述
config

输出参数，播放器配置对象。详见 PlayerConfig。

err

输出参数，状态或错误信息。详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

GetConfigs [1/3]

获取 RTE 对象的配置信息。

C++
bool GetConfigs(Config *config, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

调用时机

在调用 Rte 之后调用该方法。

参数

参数名描述
config

输出参数，表示 RTE 对象的配置信息。详见 Config。

err

输出参数，状态或错误信息。详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

GetFromBridge

从 IRtcEngine 中桥接一个 RTE 对象。

C++
static Rte GetFromBridge(Error* err = nullptr)

自从

自 v4.4.0 版本新增。

通过该方法创建的 RTE 对象无需再调用 InitMediaEngine 进行初始化。如果尚未创建并初始化 RTC 引擎，可以先调用 Rte 创建一个 RTE 对象，再调用 InitMediaEngine 进行初始化。

调用时机

在调用此方法之前，请确保你已调用 initialize 初始化 RTC 引擎。

参数

参数名描述
err

输出参数，用于接收状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

GetInfo

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

C++
bool GetInfo(PlayerInfo *info, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

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

调用时机

在调用 Player 之后调用此方法。

参数

参数名描述
info

输出参数，表示播放器和媒体流的信息。详见 PlayerInfo。

err

输出参数，状态或错误信息。详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

GetJsonParameter

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

C++
std::string GetJsonParameter(Error *err = nullptr)

自从

自 v4.4.0 版本新增。

调用 SetJsonParameter 设置 JSON 配置后，可调用本方法获取已配置的信息。

调用时机

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

参数

参数名描述
err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

GetLoopCount

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

C++
int32_t GetLoopCount(Error *err = nullptr)

自从

自 v4.5.1 版本新增。

参数

参数名描述
err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

GetMirrorMode

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

C++
VideoMirrorMode GetMirrorMode(Error *err = nullptr)

自从

自 v4.4.0 版本新增。

调用时机

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

参数

参数名描述
err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法调用成功，返回当前设置的镜像模式，详见 RteVideoMirrorMode。

所属接口类

GetPlaybackSpeed

获取播放速度参数。

C++
int32_t GetPlaybackSpeed(Error *err = nullptr)

自从

自 v4.5.1 版本新增。

参数

参数名描述
err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

GetPlayoutVolume

获取播放器的播放音量。

C++
int32_t GetPlayoutVolume(Error *err = nullptr)

自从

自 v4.5.1 版本新增。

参数

参数名描述
err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

GetPosition

获取当前播放位置。

C++
uint64_t GetPosition(Error *err = nullptr)

自从

自 v4.5.1 版本新增。

参数

参数名描述
err

输出参数，状态或错误信息，详见 Error。

  • kRteOk：调用成功。

  • kRteErrorInvalidOperation：

    • 对应的内部 Player 对象已被销毁或无效。
    • 打开的 URL 是 RTE URL，不支持调用 GetPosition。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

GetRenderMode

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

C++
VideoRenderMode GetRenderMode(Error *err = nullptr)

自从

自 v4.4.0 版本新增。

调用时机

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

参数

参数名描述
err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

当前设置的视频渲染模式，详见 RteVideoRenderMode。

所属接口类

GetStats

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

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

自从

自 v4.4.0 版本新增。

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

调用时机

该方法必须在调用 OpenWithUrl 之后调用。

参数

参数名描述
cb

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

  • stats：播放器当前播放媒体资源的统计数据，详见 RtePlayerStats。
  • err：状态或错误信息，详见 Error。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

HasAudio

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

C++
bool HasAudio() const

自从

自 v4.5.1 版本新增。

返回值

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

所属接口类

HasVideo

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

C++
bool HasVideo() const

自从

自 v4.5.1 版本新增。

返回值

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

所属接口类

InitMediaEngine

初始化 RTE 引擎。

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

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

调用时机

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

参数

参数名描述
cb

异步通知初始化结果的回调。你可以通过该回调的 err 参数获取初始化结果或错误码信息，详见 Error。

err

输出参数，表示初始化过程中产生的状态或错误信息，详见 Error。调用 InitMediaEngine 时，如果发生可立即检测的错误（如参数无效或资源不足），SDK 会通过该参数同步返回错误信息。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

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

所属接口类

IsAudioMuted

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

C++
bool IsAudioMuted() const

自从

自 v4.5.1 版本新增。

返回值

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

所属接口类

IsVideoMuted

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

C++
bool IsVideoMuted() const

自从

自 v4.5.1 版本新增。

注： IsVideoMuted 仅在打开 RTE URL 时有效。

返回值

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

所属接口类

Message

获取详细错误信息。

C++
const char *Message() const

自从

自 v4.4.0 版本新增。

调用时机

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

返回值

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

所属接口类

MuteAudio

接收或停止接收音频流。

C++
bool MuteAudio(bool mute, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

调用时机

该方法必须在调用 OpenWithUrl 之后调用。

相关回调

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

参数

参数名描述
mute

是否接收音频流：

  • true：不接收音频流。
  • false：接收音频流。
err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

MuteVideo

接收或停止接收视频流。

C++
bool MuteVideo(bool mute, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

调用时机

该方法必须在调用 OpenWithUrl 之后调用。

相关回调

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

参数

参数名描述
mute

是否接收视频流：

  • true：不接收视频流。
  • false：接收视频流。
err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

OpenWithUrl

打开一个 URL 资源。

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

自从

自 v4.4.0 版本新增。

该方法支持通过 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

暂停播放。

C++
bool Pause(Error *err = nullptr)

自从

自 v4.4.0 版本新增。

调用 Play 播放 URL 资源后，可以调用此方法暂停播放。如果需要停止播放，请调用 Stop 方法。

调用时机

该方法必须在调用 Play 之后调用。

相关回调

成功调用该方法后，SDK 会触发 onStateChanged 回调报告播放器状态为 kRtePlayerStatePaused。

参数

参数名描述
err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

Play

播放一个 URL 资源。

C++
bool Play(Error *err = nullptr)

自从

自 v4.4.0 版本新增。

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

调用时机

在收到 onStateChanged 回调报告状态为 kRtePlayerStateOpenCompleted 后调用此方法。

参数

参数名描述
err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

播放是否成功：

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

所属接口类

Player

构造一个 Player 播放器对象。

C++
explicit Player(Rte *self, PlayerInitialConfig *config = nullptr)

自从

自 v4.4.0 版本新增。

调用时机

该方法必须在调用 InitMediaEngine 之后调用。

参数

参数名描述
self

Rte 对象。详见 Rte。

config

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

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

PreloadWithUrl

预加载 URL 资源。

C++
static bool PreloadWithUrl(const char* url, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

预加载成功后，通过 OpenWithUrl 打开该 URL 资源的速度可以提升，从而减少等待时间，提升视听体验。

注： 该方法目前仅支持以 rte:// 开头的 URL。最多可预加载 20 个 URL，若超过限制，最早预加载的 URL 会被新预加载的 URL 替换。

适用场景

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

调用时机

该方法必须在调用 OpenWithUrl 之前调用。

参数

参数名描述
url

以 rte:// 开头的 URL。

err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

是否预加载成功：

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

所属接口类

RegisterObserver

注册一个 PlayerObserver 播放器观察者对象。

C++
bool RegisterObserver(PlayerObserver *observer, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

在调用该方法前，你需要实现一个继承自 PlayerObserver 的接口类。

调用时机

该方法必须在调用 Player 之后执行。

参数

参数名描述
observer

PlayerObserver 接口对象的实例。详见 PlayerObserver。

err

输出参数，状态或错误信息。详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

是否注册成功：

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

所属接口类

RemoveView

移除一个渲染视图。

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

自从

自 v4.4.0 版本新增。

调用 AddView 添加视图后，如有需要，可以调用该方法移除该视图。

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

调用时机

该方法必须在调用 AddView 之后调用。

参数

参数名描述
view

要移除的视图对象。

config

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

err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

Rte

构造一个 Rte 对象。

C++
explicit Rte(InitialConfig *config = nullptr)

自从

自 v4.4.0 版本新增。

调用时机

该方法必须在调用 InitMediaEngine 之前调用。

参数

参数名描述
config

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

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

Seek

跳转到新的播放位置。

C++
bool Seek(uint64_t new_time, Error *err = nullptr)

自从

自 v4.5.1 版本新增。

参数

参数名描述
new_time

要跳转到的新播放位置。

err

输出参数，状态或错误信息，详见 Error。

  • kRteOk：成功。

  • kRteErrorInvalidOperation：

    • 对应的内部 Player 对象已被销毁或无效。
    • 打开的 URL 是 RTE URL，不支持跳转。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

SetAbrFallbackLayer

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

C++
void SetAbrFallbackLayer(AbrFallbackLayer abr_fallback_layer, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

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

注： 如果在调用该方法时未开启 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

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

C++
void SetAbrSubscriptionLayer(AbrSubscriptionLayer abr_subscription_layer, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

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

注： 如果在调用该方法时未开启 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。

C++
void SetAppId(const char *app_id, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

调用时机

该方法必须在调用 InitMediaEngine 之前调用。

参数

参数名描述
app_id

你的项目的声网 App ID，可从声网控制台获取。

err

输出参数，状态或错误信息。详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

SetAutoPlay

设置是否自动播放。

C++
void SetAutoPlay(bool auto_play, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

在调用 OpenWithUrl 打开媒体流之前，可以调用该方法设置是否自动播放。如果未设置，默认启用自动播放。

调用时机

该方法必须在调用 OpenWithUrl 之前调用。

参数

参数名描述
auto_play

是否启用自动播放：

  • true：（默认）启用自动播放。
  • false：不启用自动播放。
err

输出参数，表示状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

SetCanvas

设置用于显示视频的视图窗口。

C++
bool SetCanvas(Canvas *canvas, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

该方法用于指定一个 Canvas 对象用于显示视频。一旦视频流成功播放，视频将显示在该 Canvas 上。

调用时机

该方法必须在调用 Player 之后执行。

参数

参数名描述
canvas

Canvas 对象，用于渲染视频帧，详见 Canvas。

err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • true：设置成功。
  • false：设置失败。你可以通过 err 参数返回的错误码查看详细信息。

所属接口类

SetConfigs [3/3]

设置播放器的视频渲染配置。

C++
bool SetConfigs(CanvasConfig *config, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

调用时机

该方法必须在调用 OpenWithUrl 之前调用。

参数

参数名描述
config

用于设置 Canvas 对象的配置，详见 CanvasConfig。

err

状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

配置是否成功：

  • true：配置成功。
  • false：配置失败。

所属接口类

SetConfigs [2/3]

配置播放器。

C++
bool SetConfigs(PlayerConfig* config, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

你可以调用该方法配置播放器，例如启用自动播放、订阅不同分辨率和码率的视频流等。

调用时机

该方法必须在调用 Player 之后执行。

参数

参数名描述
config

播放器配置对象，详见 PlayerConfig。

err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

配置是否成功：

  • true：配置成功。
  • false：配置失败。

所属接口类

SetConfigs [1/3]

配置 RTE 对象的信息。

C++
bool SetConfigs(Config *config, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

你可以调用该方法设置如 App ID 等信息。

调用时机

该方法必须在调用 Rte 之后执行。

参数

参数名描述
config

RTE 对象的设置信息，详见 Config。

err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • true：配置成功。
  • false：配置失败。

所属接口类

SetJsonParameter

使用 JSON 配置 SDK 的技术预览或自定义功能。

C++
void SetJsonParameter(const char *json_parameter, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

你可以在需要设置私有参数或使用自定义功能时调用此方法。

适用场景

当你需要设置私有参数或使用定制化功能时，可以调用此方法。

调用时机

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

参数

参数名描述
json_parameter

JSON 字符串格式的参数。

err

输出参数，表示状态或错误信息。详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

SetLoopCount

设置媒体文件播放的循环次数。

C++
void SetLoopCount(int32_t count, Error *err = nullptr)

自从

自 v4.5.1 版本新增。

参数

参数名描述
count

媒体文件的循环播放次数。

  • 1：播放一次。
  • 2：播放两次。
  • -1：无限循环播放，直到调用 Stop。
err

输出参数，状态或错误信息，详见 Error。

  • kRteOk：调用成功。
  • kRteErrorInvalidArgument：count 参数设置为无效值。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

SetMirrorMode

设置视频的镜像模式。

C++
void SetMirrorMode(VideoMirrorMode mode, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

调用时机

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

参数

参数名描述
mode

镜像模式，详见 RteVideoMirrorMode。

  • 默认值为 kRteVideoMirrorModeAuto，由 SDK 自动决定镜像模式。
  • 默认情况下，远端用户的镜像模式为关闭状态。
err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

SetPlaybackSpeed

设置播放速度参数。

C++
void SetPlaybackSpeed(int32_t speed, Error *err = nullptr)

自从

自 v4.5.1 版本新增。

注： 你可以在调用 OpenWithUrl 方法之后调用此方法。

参数

参数名描述
speed

播放速度。有效范围为 [50, 400]。

err

状态或错误信息，详见 Error。

  • kRteOk：调用成功。
  • kRteErrorInvalidArgument：speed 参数设置为无效值。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

SetPlayoutVolume

设置播放音量。

C++
void SetPlayoutVolume(int32_t volume, Error *err = nullptr)

自从

自 v4.5.1 版本新增。

参数

参数名描述
volume

要设置的播放音量，取值范围为 [0, 400]。

err

状态或错误信息，详见 Error。

  • kRteOk：设置成功。
  • kRteErrorInvalidArgument：音量参数设置为无效值。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

SetRenderMode

设置视频渲染模式。

C++
void SetRenderMode(VideoRenderMode mode, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

调用时机

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

参数

参数名描述
mode

渲染模式，详见 RteVideoRenderMode。默认值为 kRteVideoRenderModeHidden，该模式按比例缩放视频并优先填满视图窗口。

err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

State

获取当前播放器状态。

C++
RtePlayerState State() const

自从

自 v4.5.1 版本新增。

返回值

方法调用成功时，返回当前播放器状态，详见 RtePlayerState。

所属接口类

Stop

停止媒体播放。

C++
bool Stop(Error *err = nullptr)

自从

自 v4.4.0 版本新增。

成功调用 OpenWithUrl 和 Play 后，可以调用该方法停止播放。如果希望暂停播放，请调用 Pause 方法。如果使用 OpenWithUrl 打开 URL 流失败，则需要先调用该方法，再重新调用 OpenWithUrl 以重新打开 URL。

调用时机

此方法必须在调用 OpenWithUrl 之后调用。

相关回调

成功调用该方法后，SDK 会触发 onStateChanged 回调并报告播放器状态为 kRtePlayerStateStopped。

参数

参数名描述
err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • true：成功停止播放。
  • false：停止播放失败。

所属接口类

StreamCount

获取当前播放源中的流数量。

C++
size_t StreamCount() const

自从

自 v4.5.1 版本新增。

注： StreamCount 方法在打开非 RTE URL 时有效。

返回值

方法调用成功，返回当前播放源中的流数量。

所属接口类

SwitchWithUrl

在播放过程中切换到新的 URL。

C++
void SwitchWithUrl(const char* url, bool sync_pts, std::function<void(rte::Error* err)> cb)

自从

自 v4.5.1 版本新增。

注： 该方法仅在播放器已打开非 RTE URL 时有效。请在 SDK 报告播放器状态为 kRtePlayerStateOpenCompleted 时调用该方法。

参数

参数名描述
url

要切换到的新 URL。

sync_pts

是否同步播放位置：

  • true：同步播放位置。
  • false：（默认）不同步播放位置。
cb

异步通知切换操作结果的回调。你可以通过该回调的 err 参数得知操作的结果或错误码信息，详见 Error。 err 的可能取值包括：

  • kRteOk：切换成功。

  • kRteErrorDefault：切换失败。

  • kRteErrorInvalidArgument：提供的 URL 为空或格式无效。

  • kRteErrorInvalidOperation：

    • 对应的内部 Player 对象已被销毁或无效。
    • 当前打开的 URL 是 RTE URL，不支持切换。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

UnregisterObserver

取消注册播放器事件观察者对象。

C++
bool UnregisterObserver(PlayerObserver *observer, Error *err = nullptr)

自从

自 v4.4.0 版本新增。

调用 RegisterObserver 注册播放器事件观察者后，如需取消注册，可调用该方法。

调用时机

该方法必须在调用 RegisterObserver 之后调用。

参数

参数名描述
observer

播放器事件观察者对象实例，详见 PlayerObserver。

err

输出参数，状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • true：取消注册成功。
  • false：取消注册失败。

所属接口类

VideoHeight

获取视频分辨率的高度。

C++
int VideoHeight() const

自从

自 v4.5.1 版本新增。

返回值

方法调用成功，返回视频分辨率的高度，单位为像素。

所属接口类

VideoWidth

获取视频分辨率的宽度。

C++
int VideoWidth() const

自从

自 v4.5.1 版本新增。

返回值

方法调用成功，返回视频分辨率的宽度，单位为像素。

所属接口类

onAudioVolumeIndication

onAudioVolumeIndication 回调。播放器音量变化时触发。

C++
virtual void onAudioVolumeIndication(int32_t volume) {}

自从

自 v4.4.0 版本新增。

触发时机

当播放器的音量发生变化时，SDK 会触发该回调。

参数

参数名描述
volume

播放器当前的音量，取值范围为 [0, 225]。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onEvent

播放器事件回调。

C++
virtual void onEvent(PlayerEvent event) {}

自从

自 v4.4.0 版本新增。

调用 RegisterObserver 注册播放器观察者对象后，才能监听播放器事件。

触发时机

当播放器事件发生时，SDK 会触发该回调。

参数

参数名描述
event

播放器事件，详见 RtePlayerEvent。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onMetadata [2/2]

接收媒体流中元数据的回调。

C++
virtual void onMetadata(PlayerMetadataType type, const uint8_t *data, size_t length) {}

自从

自 v4.4.0 版本新增。

如果你需要从媒体流中获取元数据，必须先调用 RegisterObserver 注册播放器观察者对象。

触发时机

当 SDK 从正在播放的媒体流中解析出元数据后，会触发该回调报告元数据类型及其内容。

参数

参数名描述
type

元数据类型，详见 RtePlayerMetadataType。

data

解析后的元数据内容。

length

数据的字节大小。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onPlayerInfoUpdated [2/2]

播放器或媒体流信息发生变化时触发的回调。

C++
virtual void onPlayerInfoUpdated(const PlayerInfo *info) {}

自从

自 v4.4.0 版本新增。

如果你需要获取播放器和媒体流的信息，必须先调用 RegisterObserver 注册播放器观察者对象。你也可以直接调用 GetInfo 获取信息。

触发时机

当播放器或媒体流的信息发生变化时，SDK 会触发此回调。

参数

参数名描述
info

播放器和媒体流的信息。详见 PlayerInfo。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onPositionChanged

播放进度变化回调。

C++
virtual void onPositionChanged(uint64_t curr_time, uint64_t utc_time) {}

自从

自 v4.4.0 版本新增。

触发时机

该回调在媒体播放过程中每秒触发一次。

参数

参数名描述
curr_time

当前播放进度，单位为毫秒。

utc_time

当前 NTP（网络时间协议）时间，单位为毫秒。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onResolutionChanged

视频分辨率发生变化时触发的回调。

C++
virtual void onResolutionChanged(int width, int height) {}

自从

自 v4.4.0 版本新增。

如果你需要监控播放器播放的视频流的分辨率变化，必须先调用 RegisterObserver 注册播放器观察者对象。

触发时机

当视频流的分辨率发生变化时，SDK 会触发该回调以报告当前视频的宽度和高度。

参数

参数名描述
width

视频帧的宽度（像素）。

height

视频帧的高度（像素）。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onStateChanged

播放器状态发生变化时触发的回调。

C++
virtual void onStateChanged(PlayerState old_state, PlayerState new_state, rte::Error *err) {}

自从

自 v4.4.0 版本新增。

如果你需要监听播放器状态的变化，必须先调用 RegisterObserver 注册播放器观察者对象。

触发时机

当播放器状态发生变化时，SDK 会触发该回调以报告当前状态和之前的状态。

参数

参数名描述
old_state

播放器之前的状态，详见 RtePlayerState。

new_state

播放器当前的状态，详见 RtePlayerState。如果当前状态为 kRtePlayerStateFailed，你可以通过 err 参数获取详细的错误信息。

err

状态或错误信息，详见 Error。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利