Agora Java API Reference for Android

Public Member Functions | List of all members
io.agora.mediaplayer.IMediaPlayer Interface Reference
Inheritance diagram for io.agora.mediaplayer.IMediaPlayer:

## Public Member Functions
int | getMediaPlayerId ()
int | open (Uri uri, long startPos)
int | open (String url, long startPos)
int | openWithCustomSource (long startPos, IMediaPlayerCustomDataProvider provider)
int | openWithMediaSource (MediaPlayerSource source)
int | play ()
int | pause ()
int | stop ()
int | resume ()
int | seek (long newPos)
int | setAudioPitch (int pitch)
int | mute (boolean muted)
| Turn mute on or off. More...
boolean | getMute ()
| Get mute state. More...
int | adjustPlayoutVolume (int volume)
| Adjust playback volume. More...
int | getPlayoutVolume ()
| Get the current playback volume. More...
long | getPlayPosition ()
long | getDuration ()
| Get media duration. More...
Constants.MediaPlayerState | getState ()
| Get player state. More...
int | getStreamCount ()
| Get the number of streams in the media. More...
int | setView (View videoView)
| Set video rendering view. More...
int | setRenderMode (int mode)
| Set video display mode. More...
MediaStreamInfo | getStreamInfo (int index)
int | setLoopCount (int loopCount)
int | setPlaybackSpeed (int speed)
int | selectAudioTrack (int index)
int | selectMultiAudioTrack (int playoutTrackIndex, int publishTrackIndex)
int | setPlayerOption (String key, int value)
int | setPlayerOptionString (String key, String value)
int | takeScreenshot (String filename)
int | selectInternalSubtitle (int index)
int | setExternalSubtitle (String url)
int | adjustPublishSignalVolume (int volume)
| adjust publish signal volume More...
int | getPublishSignalVolume ()
| get publish signal volume More...
String | getPlaySrc ()
int | switchSrc (String src, boolean syncPts)
| switch to another play source More...
int | preloadSrc (String src, long startPos)
| preload another play source More...
int | playPreloadedSrc (String src)
| play the preloaded source More...
int | unloadSrc (String src)
int | destroy ()
int | registerPlayerObserver (IMediaPlayerObserver playerObserver)
int | unRegisterPlayerObserver (IMediaPlayerObserver playerObserver)
int | registerAudioFrameObserver (IMediaPlayerAudioFrameObserver audioFrameObserver, int mode)
int | registerMediaPlayerAudioSpectrumObserver (IAudioSpectrumObserver observer, int intervalInMS)
int | unregisterMediaPlayerAudioSpectrumObserver (IAudioSpectrumObserver observer)
int | setAudioDualMonoMode (int mode)
int | registerVideoFrameObserver (IMediaPlayerVideoFrameObserver videoFrameObserver)
int | openWithAgoraCDNSrc (String src, long startPos)
int | getAgoraCDNLineCount ()
int | switchAgoraCDNLineByIndex (int index)
int | getCurrentAgoraCDNIndex ()
int | enableAutoSwitchAgoraCDN (boolean enable)
int | renewAgoraCDNSrcToken (String token, long ts)
int | switchAgoraCDNSrc (String src, boolean syncPts)
int | setSpatialAudioParams (SpatialAudioParams params)

## Member Function Documentation

## ◆ getMediaPlayerId()

int io.agora.mediaplayer.IMediaPlayer.getMediaPlayerId | ( |  | ) |

Get unique source id of the media player.

Returns
  - >= 0: The source id of this media player.
  - < 0: Failure.

## ◆ open() [1/2]

int io.agora.mediaplayer.IMediaPlayer.open | ( | Uri | uri,
|  | long | startPos
| ) |  |

Opens a media file with a specified URL.

Parameters

  uri | The uri of the media file that you want to play.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ open() [2/2]

int io.agora.mediaplayer.IMediaPlayer.open | ( | String | url,
|  | long | startPos
| ) |  |

Opens a media file with a andorid URI.

Parameters

  url | The URL of the media file that you want to play.

Returns
  - 0: Success.
  - < 0: Failure.

Implemented in io.agora.musiccontentcenter.IAgoraMusicPlayer.

## ◆ openWithCustomSource()

int io.agora.mediaplayer.IMediaPlayer.openWithCustomSource | ( | long | startPos,
|  | IMediaPlayerCustomDataProvider | provider
| ) |  |

Deprecated:
  Opens a media with custom data provider

Parameters

  startPos | the start position
  provider | custom data provider

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ openWithMediaSource()

int io.agora.mediaplayer.IMediaPlayer.openWithMediaSource | ( | MediaPlayerSource | source | ) |

Opens a media file with a media file source.

Parameters

  source | Media file source that you want to play, see `MediaSource`

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ play()

int io.agora.mediaplayer.IMediaPlayer.play | ( |  | ) |

Plays the media file.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ pause()

int io.agora.mediaplayer.IMediaPlayer.pause | ( |  | ) |

Pauses playing the media file.

## ◆ stop()

int io.agora.mediaplayer.IMediaPlayer.stop | ( |  | ) |

Stops playing the current media file.

Implemented in io.agora.musiccontentcenter.IAgoraMusicPlayer.

## ◆ resume()

int io.agora.mediaplayer.IMediaPlayer.resume | ( |  | ) |

Resumes playing the media file.

## ◆ seek()

int io.agora.mediaplayer.IMediaPlayer.seek | ( | long | newPos | ) |

Sets the current playback position of the media file.

Parameters

  newPos | The new playback position (ms).

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setAudioPitch()

int io.agora.mediaplayer.IMediaPlayer.setAudioPitch | ( | int | pitch | ) |

Sets the pitch of the current media file.

Parameters

  pitch | Sets the pitch of the local music file by chromatic scale. The default value is 0, which means keeping the original pitch. The value ranges from -12 to 12, and the pitch value between consecutive values is a chromatic value. The greater the absolute value of this parameter, the higher or lower the pitch of the local music file.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ mute()

int io.agora.mediaplayer.IMediaPlayer.mute | ( | boolean | muted | ) |

Turn mute on or off.

Parameters

  muted | Whether to mute on

Returns
  int <= 0 On behalf of an error, the value corresponds to one of MediaPlayerReason

## ◆ getMute()

boolean io.agora.mediaplayer.IMediaPlayer.getMute | ( |  | ) |

Get mute state.

Returns
  Whether media player is mute on

## ◆ adjustPlayoutVolume()

int io.agora.mediaplayer.IMediaPlayer.adjustPlayoutVolume | ( | int | volume | ) |

Adjust playback volume.

Parameters

  volume | The volume value to be adjusted The volume can be adjusted from 0 to 400: 0: mute; 100: original volume; 400: Up to 4 times the original volume (with built-in overflow protection).

Returns
  int <= 0 On behalf of an error, the value corresponds to one of MediaPlayerReason

## ◆ getPlayoutVolume()

int io.agora.mediaplayer.IMediaPlayer.getPlayoutVolume | ( |  | ) |

Get the current playback volume.

Returns
  int <= 0 On behalf of an error, the value corresponds to one of MediaPlayerReason

Parameters

  [out] | volume |

## ◆ getPlayPosition()

long io.agora.mediaplayer.IMediaPlayer.getPlayPosition | ( |  | ) |

Gets the current playback position of the media file.

Returns
  int <= 0 On behalf of an error, the value corresponds to one of MediaPlayerReason

## ◆ getDuration()

long io.agora.mediaplayer.IMediaPlayer.getDuration | ( |  | ) |

Get media duration.

Returns
  int <= 0 On behalf of an error, the value corresponds to one of MediaPlayerReason

Parameters

  [out] | duration | Duration in seconds

## ◆ getState()

Constants.MediaPlayerState io.agora.mediaplayer.IMediaPlayer.getState | ( |  | ) |

Get player state.

Returns
  MediaPlayerState

## ◆ getStreamCount()

int io.agora.mediaplayer.IMediaPlayer.getStreamCount | ( |  | ) |

Get the number of streams in the media.

Returns
  int <= 0 On behalf of an error, the value corresponds to one of MediaPlayerReason

Parameters

  [out] | count |

## ◆ setView()

int io.agora.mediaplayer.IMediaPlayer.setView | ( | View | videoView | ) |

Set video rendering view.

Parameters

  videoView | view object, windows platform is HWND

Returns
  int <= 0 On behalf of an error, the value corresponds to one of MediaPlayerReason

## ◆ setRenderMode()

int io.agora.mediaplayer.IMediaPlayer.setRenderMode | ( | int | mode | ) |

Set video display mode.

Parameters

  mode | Video display mode

Returns
  int < 0 on behalf of an error, the value corresponds to one of MediaPlayerReason

## ◆ setLoopCount()

int io.agora.mediaplayer.IMediaPlayer.setLoopCount | ( | int | loopCount | ) |

Sets whether to loop the media file for playback.

Parameters

  loopCount | the number of times looping the media file. 0: Play the audio effect once. 1: Play the audio effect twice. -1: Play the audio effect in a loop indefinitely, until stopEffect() or stop() is called.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setPlaybackSpeed()

int io.agora.mediaplayer.IMediaPlayer.setPlaybackSpeed | ( | int | speed | ) |

Change playback speed

Parameters

  speed | the enum of playback speed

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ selectAudioTrack()

int io.agora.mediaplayer.IMediaPlayer.selectAudioTrack | ( | int | index | ) |

Select playback audio track of the media file

Parameters

  index | the index of the audio track in media file

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ selectMultiAudioTrack()

int io.agora.mediaplayer.IMediaPlayer.selectMultiAudioTrack | ( | int | playoutTrackIndex,
|  | int | publishTrackIndex
| ) |  |

Selects multi audio track of the media file for playback or publish to channel.

Parameters

  playoutTrackIndex | The index of the audio track in media file for local playback.
  publishTrackIndex | The index of the audio track in the media file published to the remote.

Note
  You can obtain the streamIndex of the audio track by calling getStreamInfo.. If you want to use selectMultiAudioTrack, you need to open the media file with openWithMediaSource and set enableMultiAudioTrack to true.

Returns
  - 0: Success.
  - < 0: Failure. See MEDIA_PLAYER_REASON.
  - -2: Invalid argument. Argument must be greater than or equal to zero.
  - -8: Invalid State.You must open the media file with openWithMediaSource and set enableMultiAudioTrack to true

## ◆ setPlayerOption()

int io.agora.mediaplayer.IMediaPlayer.setPlayerOption | ( | String | key,
|  | int | value
| ) |  |

change player option before play a file

Parameters

  key | the key of the option param
  value | the value of option param

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setPlayerOptionString()

int io.agora.mediaplayer.IMediaPlayer.setPlayerOptionString | ( | String | key,
|  | String | value
| ) |  |

change player option before play a file

Parameters

  key | the key of the option param
  value | the value of option param

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ takeScreenshot()

int io.agora.mediaplayer.IMediaPlayer.takeScreenshot | ( | String | filename | ) |

take screenshot while playing video

Parameters

  filename | the filename of screenshot file

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ selectInternalSubtitle()

int io.agora.mediaplayer.IMediaPlayer.selectInternalSubtitle | ( | int | index | ) |

select internal subtitles in video

Parameters

  index | the index of the internal subtitles

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setExternalSubtitle()

int io.agora.mediaplayer.IMediaPlayer.setExternalSubtitle | ( | String | url | ) |

set an external subtitle for video

Parameters

  url | The URL of the subtitle file that you want to load.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ adjustPublishSignalVolume()

int io.agora.mediaplayer.IMediaPlayer.adjustPublishSignalVolume | ( | int | volume | ) |

adjust publish signal volume

Returns
  int < 0 on behalf of an error, the value corresponds to one of MEDIA_PLAYER_REASON

## ◆ getPublishSignalVolume()

int io.agora.mediaplayer.IMediaPlayer.getPublishSignalVolume | ( |  | ) |

get publish signal volume

Returns
  int < 0 on behalf of an error, the value corresponds to one of MEDIA_PLAYER_REASON

## ◆ getPlaySrc()

String io.agora.mediaplayer.IMediaPlayer.getPlaySrc | ( |  | ) |

Gets the url of the current play media file for publishing.

Returns
  the current play media file for publishing.

Implemented in io.agora.musiccontentcenter.IAgoraMusicPlayer.

## ◆ switchSrc()

int io.agora.mediaplayer.IMediaPlayer.switchSrc | ( | String | src,
|  | boolean | syncPts
| ) |  |

switch to another play source

Parameters

  src | The URL of the source
  syncPts | whether to sync pts for the other source

Returns
  int < 0 on behalf of an error, the value corresponds to one of MEDIA_PLAYER_REASON

## ◆ preloadSrc()

int io.agora.mediaplayer.IMediaPlayer.preloadSrc | ( | String | src,
|  | long | startPos
| ) |  |

preload another play source

Parameters

  src | The URL of the source
  startPos | play pos of the preload source

Returns
  int < 0 on behalf of an error, the value corresponds to one of MEDIA_PLAYER_REASON

## ◆ playPreloadedSrc()

int io.agora.mediaplayer.IMediaPlayer.playPreloadedSrc | ( | String | src | ) |

play the preloaded source

Parameters

  src | The URL of the source

Returns
  int < 0 on behalf of an error, the value corresponds to one of MEDIA_PLAYER_REASON

## ◆ unloadSrc()

int io.agora.mediaplayer.IMediaPlayer.unloadSrc | ( | String | src | ) |

Unload a preloaded media source

Parameters

  src | Specific src.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ destroy()

int io.agora.mediaplayer.IMediaPlayer.destroy | ( |  | ) |

Returns
  - 0: Success.
  - < 0: Failure.

Implemented in io.agora.musiccontentcenter.IAgoraMusicPlayer.

## ◆ registerPlayerObserver()

int io.agora.mediaplayer.IMediaPlayer.registerPlayerObserver | ( | IMediaPlayerObserver | playerObserver | ) |

Registers a media player observer.

Once the media player observer is registered, you can use the observer to monitor the state change of the media player.

Parameters

  playerObserver | The pointer to the IMediaPlayerObserver object.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unRegisterPlayerObserver()

int io.agora.mediaplayer.IMediaPlayer.unRegisterPlayerObserver | ( | IMediaPlayerObserver | playerObserver | ) |

Releases the media player observer.

Parameters

  playerObserver | The pointer to the IMediaPlayerObserver object.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ registerMediaPlayerAudioSpectrumObserver()

int io.agora.mediaplayer.IMediaPlayer.registerMediaPlayerAudioSpectrumObserver | ( | IAudioSpectrumObserver | observer,
|  | int | intervalInMS
| ) |  |

Registers the audio frame spectrum observer.

Parameters

  observer | The pointer to the IAudioSpectrumObserver object.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unregisterMediaPlayerAudioSpectrumObserver()

int io.agora.mediaplayer.IMediaPlayer.unregisterMediaPlayerAudioSpectrumObserver | ( | IAudioSpectrumObserver | observer | ) |

Releases the audio frame spectrum observer.

Parameters

  observer | The pointer to the IAudioSpectrumObserver object.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setAudioDualMonoMode()

int io.agora.mediaplayer.IMediaPlayer.setAudioDualMonoMode | ( | int | mode | ) |

Set dual-mono output mode of the music file.

Parameters

  mode | See AudioDualMonoMode. Default in AUDIO_DUAL_MONO_STEREO

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ openWithAgoraCDNSrc()

int io.agora.mediaplayer.IMediaPlayer.openWithAgoraCDNSrc | ( | String | src,
|  | long | startPos
| ) |  |

Open the Agora CDN media source.

Parameters

  src | The src of the media file that you want to play.
  startPos | The playback position (ms).

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getAgoraCDNLineCount()

int io.agora.mediaplayer.IMediaPlayer.getAgoraCDNLineCount | ( |  | ) |

Gets the number of Agora CDN lines.

Returns
  - > 0: number of CDN.
  - <= 0: Failure.

## ◆ switchAgoraCDNLineByIndex()

int io.agora.mediaplayer.IMediaPlayer.switchAgoraCDNLineByIndex | ( | int | index | ) |

Switch Agora CDN lines.

Parameters

  index | Specific CDN line index.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getCurrentAgoraCDNIndex()

int io.agora.mediaplayer.IMediaPlayer.getCurrentAgoraCDNIndex | ( |  | ) |

Gets the line of the current CDN.

Returns
  - >= 0: Specific line.
  - < 0: Failure.

## ◆ enableAutoSwitchAgoraCDN()

int io.agora.mediaplayer.IMediaPlayer.enableAutoSwitchAgoraCDN | ( | boolean | enable | ) |

Enable automatic CDN line switching.

Parameters

  enable | Whether enable.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ renewAgoraCDNSrcToken()

int io.agora.mediaplayer.IMediaPlayer.renewAgoraCDNSrcToken | ( | String | token,
|  | long | ts
| ) |  |

Update the CDN source token and timestamp.

Parameters

  token | token.
  ts | ts.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ switchAgoraCDNSrc()

int io.agora.mediaplayer.IMediaPlayer.switchAgoraCDNSrc | ( | String | src,
|  | boolean | syncPts
| ) |  |

Switch the CDN source.

Parameters

  src | Specific src.
  syncPts | Live streaming must be set to false.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setSpatialAudioParams()

int io.agora.mediaplayer.IMediaPlayer.setSpatialAudioParams | ( | SpatialAudioParams | params | ) |

Set spatial audio params for the music file. It can be called after the media player was created.

Parameters

  params | See SpatialAudioParams. If it's not set, then the spatial audio will be disabled; or it will be enabled.

Returns
  - 0: Success.
  - < 0: Failure.