Agora Java API Reference for Android

Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
io.agora.rte.Player Class Reference

## Public Member Functions
| Player (Rte rte, PlayerInitialConfig initialConfig)
| Constructs a player object. More...
long | getNativeHandle ()
void | openWithUrl (String url, long startTime, AsyncCallback callback)
| Opens a URL resource. More...
void | openWithCustomSourceProvider (PlayerCustomSourceProvider provider, long startTime, AsyncCallback callback)
void | openWithStream (Stream stream, AsyncCallback callback)
void | switchWithUrl (String url, boolean syncPts, AsyncCallback callback)
| Switches to a new URL during playback. More...
void | getStats (PlayerGetStatsCallback callback)
| Retrieves statistics of the currently playing media resource in the player. More...
void | setCanvas (Canvas canvas) throws RteException
| Sets the view window to display video. More...
void | play () throws RteException
| Plays a URL resource. More...
void | stop () throws RteException
| Stops playing the media resource. More...
void | pause () throws RteException
| Pauses playback. More...
void | seek (long newTime) throws RteException
| Seeks to a specified playback position. More...
void | muteAudio (boolean mute) throws RteException
| Starts or stops receiving the audio stream. More...
void | muteVideo (boolean mute) throws RteException
| Starts or stops receiving remote video streams. More...
long | getPosition () throws RteException
| Gets the current playback position. More...
void | getInfo (PlayerInfo info) throws RteException
| Retrieves information related to the player and media stream. More...
void | getConfigs (PlayerConfig config) throws RteException
| Gets the current media player options. More...
void | setConfigs (PlayerConfig config) throws RteException
| Sets the player configurations. More...
void | registerObserver (PlayerObserver observer) throws RteException
| Registers an observer object for the player. More...
void | unregisterObserver (PlayerObserver observer) throws RteException
| Unregisters the media player event observer object. More...

## Static Public Member Functions
static void | preloadWithUrl (String url) throws RteException
| Preloads a URL resource. More...

## Protected Member Functions
void | finalize ()

## Detailed Description

The Player class can be used to play URL resources.

Since
  v4.4.0

## Constructor & Destructor Documentation

## ◆ Player()

io.agora.rte.Player.Player | ( | Rte | rte,
|  | PlayerInitialConfig | initialConfig
| ) |  |

Constructs a player object.

Since
  v4.4.0

Call timing: This method must be called after `initMediaEngine`.

Parameters

  rte | An `Rte` object.
  initialConfig | Initialization settings for the player object. You can pass a null pointer.

## Member Function Documentation

## ◆ preloadWithUrl()

static void io.agora.rte.Player.preloadWithUrl | ( | String | url | ) | throws RteException
| static

Preloads a URL resource.

Since
  v4.4.0

Successfully preloading a resource accelerates the speed of opening the URL resource with `openWithUrl`. When you need to use these resources, they can be accessed more quickly, reducing wait time. Applicable scenarios: Preloading media resources before opening them can reduce user wait time and provide a smoother audiovisual experience. Call timing: You must call this method before `openWithUrl`.

Note
  This method currently only works for URLs with the `rte://` prefix. You can preload up to 20 URLs. If the limit is exceeded, newly preloaded URLs will replace the earliest ones.

Parameters

  url | A URL with the `rte://` prefix. For details on each field, refer to `Media Pull` on the audience side.

Exceptions

  RteException | If the method call fails, the SDK throws an `RteException` with the corresponding error information. You need to catch and handle the exception.

## ◆ openWithUrl()

void io.agora.rte.Player.openWithUrl | ( | String | url,
|  | long | startTime,
|  | AsyncCallback | callback
| ) |  |

Opens a URL resource.

Since
  v4.4.0

This method supports opening real-time streaming media via a URL. If you want to speed up the process of opening a URL resource, you can call `preloadWithUrl` to preload the resource before invoking this method. If the resource fails to open, you will receive an `onStateChanged` callback reporting the player state as `FAILED`. In this case, you need to call `stop` first and then call `openWithUrl` again to reopen the URL resource. If you have disabled autoplay, you can call `play` to start playback after the resource is opened. Call timing: This method must be called after `Player`. Related callbacks: After calling this method, the `onStateChanged` callback is triggered, reporting the player state as `OPENING`, indicating that the URL is being opened. Once successfully opened, the player state is reported as `OPEN_COMPLETED`.

Note
  This method currently supports only URLs that start with `rte://`, direct CDN streaming URLs, and local media files.

Parameters

  url | The URL to open. It can be a direct CDN streaming URL, a local media file, or a URL prefixed with `rte://`. For detailed explanations of each field in the RTE URL, see "Audience-side URL playback".
  startTime | The start playback position in milliseconds.
  callback | An asynchronous callback function used to notify the result of opening the URL resource. If an error occurs during the process, you can get the specific error information through the `onResult` callback under `AsyncCallback`.

## ◆ switchWithUrl()

void io.agora.rte.Player.switchWithUrl | ( | String | url,
|  | boolean | syncPts,
|  | AsyncCallback | callback
| ) |  |

Switches to a new URL during playback.

Since
  v4.5.1

You must call this method when the SDK returns the player state as `OPEN_COMPLETED`.

Note
  This method is only effective when the player opens a non-RTE URL.

Parameters

  url | The URL resource to switch to.
  syncPts | - `true`: Synchronizes the playback position. `false`: (Default) Does not synchronize the playback position.
  callback | Asynchronous callback used to notify the result of the switch operation. See `AsyncCallback` for details.

## ◆ getStats()

void io.agora.rte.Player.getStats | ( | PlayerGetStatsCallback | callback | ) |

Retrieves statistics of the currently playing media resource in the player.

Since
  v4.4.0

This method retrieves player statistics, including decoding and rendering frame rates, audio and video bitrate, etc., and returns the result asynchronously through a callback function. Call timing: This method must be called after `openWithUrl`.

Parameters

  callback | Callback interface used to asynchronously receive statistics and possible error information. See the `onResult` callback under the `PlayerGetStatsCallback` interface class.

## ◆ setCanvas()

void io.agora.rte.Player.setCanvas | ( | Canvas | canvas | ) | throws RteException

Sets the view window to display video.

Since
  v4.4.0

This method specifies a `Canvas` object to display video. Once the video stream plays successfully, the video image appears on the specified `Canvas`. Call timing: This method must be called after `Player`.

Parameters

  canvas | The `Canvas` object used to render video frames. See `Canvas` for details.

Exceptions

  RteException | If the method call fails, the SDK throws an `RteException` with the corresponding error information. You need to catch and handle the exception.

## ◆ play()

void io.agora.rte.Player.play | ( |  | ) | throws RteException

Plays a URL resource.

Since
  v4.4.0

If you have disabled autoplay, after successfully opening a Media Pull stream using `openWithUrl`, you can call this method to start playback. Call timing: Call this method only after receiving the `onStateChanged` callback with the state `OPEN_COMPLETED`. Related callbacks: After this method is successfully called, the `onStateChanged` callback will be triggered to report the player state.

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

Exceptions

  RteException | If the method call fails, the SDK throws an `RteException` with the corresponding error information. You need to catch and handle the exception.

## ◆ stop()

void io.agora.rte.Player.stop | ( |  | ) | throws RteException

Stops playing the media resource.

Since
  v4.4.0

After you successfully open a URL stream using `openWithUrl` and start playback with `play`, you can call this method to stop playback. If you want to pause playback instead, call `pause`. If opening the URL stream with `openWithUrl` fails, you need to call this method first before calling `openWithUrl` again to reopen the URL. Call timing: This method must be called after `openWithUrl`. Related callbacks: Upon successful execution, this method triggers the `onStateChanged` callback and reports the player state as `STOPPED`.

Exceptions

  RteException | If the method call fails, the SDK throws an `RteException` with the corresponding error information. You need to catch and handle the exception.

## ◆ pause()

void io.agora.rte.Player.pause | ( |  | ) | throws RteException

Pauses playback.

Since
  v4.4.0

After you call `play` to play a URL resource, you can call this method if you want to pause the playback. If you want to stop the playback, call `stop` instead.
Call timing: This method must be called after `play`. Related callbacks: After this method is successfully called, the `onStateChanged` callback is triggered to report the player state as `PAUSED`.

Exceptions

  RteException | If this method call fails, the SDK throws an `RteException` with the corresponding error message. You need to catch and handle the exception.

## ◆ seek()

void io.agora.rte.Player.seek | ( | long | newTime | ) | throws RteException

Seeks to a specified playback position.

Since
  v4.5.1

Parameters

  newTime | The playback position to seek to, in milliseconds.

Exceptions

  RteException | If the method call fails, the SDK throws an `RteException` with the corresponding error information. You need to catch and handle the exception.

## ◆ muteAudio()

void io.agora.rte.Player.muteAudio | ( | boolean | mute | ) | throws RteException

Starts or stops receiving the audio stream.

Since
  v4.4.0

Call timing: You must call this method after `openWithUrl`. Related callbacks: After this method is successfully called, the `onPlayerInfoUpdated(PlayerInfo info)` callback is triggered to report the latest player and Media Pull information.

Parameters

  mute | Whether to receive the audio stream: `true`: Do not receive the audio stream. `false`: Receive the audio stream.

Exceptions

  RteException | If the method call fails, the SDK throws an `RteException` with the corresponding error information. You need to catch and handle the exception.

## ◆ muteVideo()

void io.agora.rte.Player.muteVideo | ( | boolean | mute | ) | throws RteException

Starts or stops receiving remote video streams.

Since
  v4.4.0

Call timing: You must call this method after `openWithUrl`. Related callbacks: After this method is successfully called, the `onPlayerInfoUpdated(PlayerInfo info)` callback is triggered to report the latest player and media stream information.

Parameters

  mute | Whether to receive remote video streams: `true`: Do not receive remote video streams. `false`: Receive remote video streams.

Exceptions

  RteException | If the method call fails, the SDK throws an `RteException` with the corresponding error information. You need to catch and handle the exception.

## ◆ getPosition()

long io.agora.rte.Player.getPosition | ( |  | ) | throws RteException

Gets the current playback position.

Since
  v4.5.1

This method retrieves the current playback time position in milliseconds.

Returns
  If the method call succeeds, returns the current playback position in milliseconds.

Exceptions

  RteException | If the method call fails, the SDK throws an `RteException` with the corresponding error information. You need to catch and handle the exception.

## ◆ getInfo()

void io.agora.rte.Player.getInfo | ( | PlayerInfo | info | ) | throws RteException

Retrieves information related to the player and media stream.

Since
  v4.4.0

You can use this method to obtain information about the player and the media stream, such as audio sample rate and video frame dimensions. Call timing: This method must be called after `Player`.

Parameters

  info | Information related to the player and media stream. See `PlayerInfo` for details.

Exceptions

  RteException | If this method call fails, the SDK throws an `RteException` with the corresponding error message. You need to catch and handle the exception.

## ◆ getConfigs()

void io.agora.rte.Player.getConfigs | ( | PlayerConfig | config | ) | throws RteException

Gets the current media player options.

Since
  v4.4.0

Call timing: This method must be called after `Player`.

Parameters

  config | The media player options object. See `PlayerConfig` for details.

Exceptions

  RteException | If the method call fails, the SDK throws an `RteException` with the corresponding error information. You need to catch and handle the exception.

## ◆ setConfigs()

void io.agora.rte.Player.setConfigs | ( | PlayerConfig | config | ) | throws RteException

Sets the player configurations.

Since
  v4.4.0

You can call this method to configure the player, such as enabling autoplay and subscribing to video streams of different resolutions and bitrate. Call timing: This method must be called after `Player`.

Parameters

  config | The player configuration object. See `PlayerConfig` for details.

Exceptions

  RteException | If the method call fails, the SDK throws an `RteException` with the corresponding error information. You need to catch and handle the exception.

## ◆ registerObserver()

void io.agora.rte.Player.registerObserver | ( | PlayerObserver | observer | ) | throws RteException

Registers an observer object for the player.

Since
  v4.4.0

Before calling this method, you need to implement an interface class that inherits from `PlayerObserver`. Call timing: This method must be called after `Player`.

Parameters

  observer | An instance of the interface object. See `PlayerObserver` for details.

Exceptions

  RteException | If the method call fails, the SDK throws a `RteException` with the corresponding error message. You need to catch and handle the exception.

## ◆ unregisterObserver()

void io.agora.rte.Player.unregisterObserver | ( | PlayerObserver | observer | ) | throws RteException

Unregisters the media player event observer object.

Since
  v4.4.0

After calling `registerObserver` to register a media player event observer, if you need to unregister it, call this method. Call timing: This method must be called after `registerObserver`.

Parameters

  observer | The interface object instance. See `PlayerObserver` for details.

Exceptions

  RteException | If the method call fails, the SDK throws an `RteException` with the corresponding error message. You need to catch and handle the exception.