Player

The fundamental interface class for the RTE player, which implements the major functions of media playback.

Code

Gets the error code.

ErrorCode Code();
Since
v4.5.0

Call timing

When an API call fails, you can call this method to get the error code.

Restrictions

None.

Returns

Error code. See RteErrorCode.

GetConfigs [2/3]

Gets the current player settings.

bool GetConfigs(PlayerConfig* config, Error* err);
Since
v4.5.0

Call timing

Call this method after Player.

Restrictions

None.

Parameters

config
The player configuration object: PlayerConfig.
err
The state or error information: Error.

Returns

Whether the RTE object is configured successfully:
  • true: Yes.
  • false: No.

GetInfo

Gets the player state and the information about the media stream being played.

bool GetInfo(PlayerInfo *info, Error *err);
Since
v4.5.0

You can obtain information about the player state and media stream through this method, such as audio sampling rate, video frame size.

Call timing

Call this method after Player.

Restrictions

None.

Parameters

info
The information of the player and the media stream. See RtePlayerInfo.
err
The state or error information: Error.

Returns

Whether obtaining the information is successful:
  • true: Obtaining information succeeds.
  • false: Obtaining information fails.

GetStats

Gets statistical information about the current media resource being played.

void GetStats(std::function<void(rte::PlayerStats *stats, rte::Error *err)> cb)
Since
v4.5.0

This method is used to obtain statistical information about the player, including decoding, rendering frame rate, audio and video bitrate, etc., and asynchronously returns the results through a callback function.

Call timing

Call this method after OpenWithUrl.

Restrictions

None.

Parameters

cb
An asynchronous callback used to notify the result and possible error information of obtaining the statistics. The callback includes the following parameters:
  • stats: The information of the media resource currently being played. See RtePlayerStats.
  • err: The detailed infromation about errors. See Error.

Message

Gets the error message.

const char *Message();
Since
v4.5.0

Call timing

When an API call fails, you can use this method to retrieve error information to help troubleshoot the issue.

Restrictions

None.

Returns

The error message.

MuteAudio

Subscribes or unsubscribes to an audio stream.

bool MuteAudio(bool mute, Error* err);
Since
v4.5.0

Audience member can call this method to decide whether to subscribe to the host's audio stream.

Call timing

Call this method after OpenWithUrl.

Restrictions

None.

Related callbacks

After successfully calling this method, the SDK triggers the onPlayerInfoUpdated [2/2] callback to report the latest nformation of the player's state and media stream.

Parameters

mute
Whether to subscribe to the audio stream of the host:
  • true: Subscribe to the audio stream.
  • false: Do not subscribe to the audio stream.
err
The state or error information: Error.

Returns

Whether the subscription or unsubscription is successful:
  • true: Succeeds.
  • false: Fails.

MuteVideo

Subscribes or unsubscribes to a video stream.

bool MuteVideo(bool mute, Error* err);
Since
v4.5.0

Audience member can call this method to decide whether to subscribe to the host's video stream.

Call timing

Call this method after OpenWithUrl.

Restrictions

None.

Related callbacks

After successfully calling this method, the SDK triggers the onPlayerInfoUpdated [2/2] callback to report the latest nformation of the player's state and media stream.

Parameters

mute
Whether to subscribe to the video stream of the host:
  • true: Subscribe to the video stream.
  • false: Do not subscribe to the video stream.
err
The state or error information: Error.

Returns

Whether the subscription or unsubscription is successful:
  • true: Succeeds.
  • false: Fails.

OpenWithUrl

Opens a URL.

void OpenWithUrl(const char* url, uint64_t start_time, std::function<void(rte::Error* err)> cb);
Since
v4.5.0

This method can open a live stream via URL. If you want to speed up the process of opening a URL, you can call the PreloadWithUrl method to preload the URL before calling the method.

If you fail to open the URL, you will receive the onStateChanged callback reporting the state as kRtePlayerStateFailed. At this time, you need to call Stop first, then call OpenWithUrl to reopen the URL. If you have disabled autoplay, you can call Play to play after opening the URL.

Call timing

Call this method after Player.

Restrictions

This method currently only supports playing URLs with the rte:// prefix.

Related callbacks

After calling this method, the SDK triggers the onStateChanged callback and reports the state as kRtePlayerStateOpening, which means the player is opening the URL. After successfully opening the URL, the SDK reports the player's state as kRtePlayerStateOpenCompleted.

Parameters

url
URLs with the rte:// prefix.
start_time
Reserved for future use.
cb
An asynchronous callback, used to notify the result of opening a URL. If an error occurs during the opening, you can get specific error information through the err parameter in this callback. See Error.

Pause

Pauses the playback.

bool Pause(Error* err);
Since
v4.5.0

When you call Play to play a URL, if you want to pause the playback, you can call this method. If you need to stop the playback, call Stop.

Call timing

Call this method after Play.

Restrictions

None.

Related callbacks

A successful call of this method triggers the onStateChanged callback and reports the player state as kRtePlayerStatePaused.

Parameters

err
The state or error information: Error.

Returns

Whether the playback has been successfully paused:
  • true: The playback is paused.
  • false: Pausing the playback fails.

Player

Create a player object.

 explicit Player(Rte *self, PlayerInitialConfig *config = nullptr) ;
Since
v4.5.0

Call timing

Call this method after InitMediaEngine.

Restrictions

None.

Parameters

Rte
One Rte object.
config
Player object initialization settings. Currently you can set it as null.

Play

Plays a URL.

bool Play(Error* err);
Since
v4.5.0

If you have disabled autoplay, when you successfully open a live stream through a URL by calling OpenWithUrl, you can call this method to play the stream.

Call timing

Call this method after you receive the onStateChanged callback reporting the kRtePlayerStateOpenCompleted state.

Restrictions

This method currently only supports playing URLs with the rte:// prefix.

Related callbacks

A successful call of this method triggers the onStateChanged callback to report the player state.

Parameters

err
The state or error information: Error.

Returns

Whether the playing is successful:
  • true: The playing succeeds.
  • false: The playing fails.

PreloadWithUrl

Preloads a URL resource.

static bool PreloadWithUrl(const char* url, Error *err = nullptr)  {
    return RtePlayerPreloadWithUrl(nullptr, url, err != nullptr ? err->get_underlying_impl() : nullptr);
Since
v4.5.0

After successful preloading, the speed of accessing URL resources can be accelerated when calling OpenWithUrl. When you need to use these resources, you can access them more quickly and shorten the waiting process.

Applicable scenarios

Before opening media resources, preloading can reduce the time for waiting and provide a smoother user experience.

Call timing

Call this method after OpenWithUrl.

Restrictions

This method currently only takes effect on URLs with the prefix rte://. A maximum of 20 URLs can be preloaded. If exceeded, the newly preloaded URL will replace the oldest one.

Parameters

url
URLs with the rte:// prefix.
err
The state or error information: Error.

Returns

Whether preloading is successful:
  • true: Preloading succeeds.
  • false: Preloading fails.

RegisterObserver

Registers the observer of the player.

bool RegisterObserver(PlayerObserver *observer, Error *err);
Since
v4.5.0

Before calling this method, you need to implement a class that inherits from PlayerObserver.

Call timing

Call this method after Player.

Restrictions

None.

Parameters

observer
The delegate instance. See PlayerObserver.
err
The state or error information: Error.

Returns

Whether the registration is successful:
  • true: Registration succeeds.
  • false: Registration fails.

SetCanvas

Sets the view window for displaying the video.

bool SetCanvas(Canvas *canvas, Error *err);
Since
v4.5.0

This method specifies a Canvas object to display the video. Once the the video stream sucessfully plays, the video image will be displayed on the specified canvas.

Call timing

Call this method after Player.

Restrictions

None.

Parameters

canvas
The Canvas object on which the video is rendered: Canvas
err
The state or error information: Error.

Returns

Whether the settings are successful:
  • true: Yes.
  • false: No. Refer to the error code in err to get the detaled information.

Stop

Stops playing media resource.

bool Stop(Error* err);
Since
v4.5.0

After you successfully play the URL stream using Play, call this method if you want to stop playing it. If you need to pause the playback, call Pause.

If you fail to open the URL stream using OpenWithUrl, call this method first, and then call OpenWithUrl to reopen the URL.

Call timing

Call this method after OpenWithUrl.

Restrictions

None.

Related callbacks

A successful call of this method triggers the onStateChanged callback, which reports the player state as kRtePlayerStateStopped.

Parameters

err
The state or error information: Error.

Returns

Whether the media resource stops playing:
  • true: Yes.
  • false: No.

SetConfigs [2/3]

Sets the player configurations.

bool SetConfigs(PlayerConfig* config, Error* err);
Since
v4.5.0

You can call this method to configuer the player, such as enabling autoplay and subscribing to video streams of a different resolution and bitrate.

Call timing

Call this method after Player.

Restrictions

None.

Parameters

config
The player configuration object: PlayerConfig.
err
The state or error information: Error.

Returns

Whether the player is configured successfully:
  • true: Yes.
  • false: No.

UnregisterObserver

Unregisters the player event observer.

bool UnregisterObserver(PlayerObserver *observer, Error *err);
Since
v4.5.0

After you register the player event observer by calling RegisterObserver, if you want to unregister the observer, call this method.

Call timing

Call this method after RegisterObserver.

Restrictions

None.

Parameters

observer
The delegate instance. See PlayerObserver.
err
The state or error information: Error.

Returns

Whether you successfully unregister the observer:
  • true: Yes.
  • false: No.