Agora C++ API Reference for All Platforms

Public Member Functions | Protected Member Functions | List of all members
agora::rtc::IMediaPlayerSource Class Referenceabstract

Inherits agora::RefCountInterface.

Inherited by agora::rtc::IMediaPlayerSourceEx.

## Public Member Functions
virtual int | getSourceId () const =0
virtual int | open (const char *url, int64_t startPos)=0
virtual int | openWithMediaSource (const media::base::MediaSource &source)=0
virtual int | play ()=0
virtual int | pause ()=0
virtual int | stop ()=0
virtual int | resume ()=0
virtual int | seek (int64_t newPos)=0
virtual int | getDuration (int64_t &duration)=0
virtual int | getPlayPosition (int64_t &pos)=0
virtual int | getStreamCount (int64_t &count)=0
virtual int | getStreamInfo (int64_t index, media::base::PlayerStreamInfo *info)=0
virtual int | setLoopCount (int64_t loopCount)=0
virtual int | setPlaybackSpeed (int speed)=0
virtual int | selectAudioTrack (int64_t index)=0
virtual int | selectMultiAudioTrack (int playoutTrackIndex, int publishTrackIndex)=0
virtual int | setPlayerOption (const char *key, int64_t value)=0
virtual int | setPlayerOption (const char *key, const char *value)=0
virtual int | takeScreenshot (const char *filename)=0
virtual int | selectInternalSubtitle (int64_t index)=0
virtual int | setExternalSubtitle (const char *url)=0
virtual media::base::MEDIA_PLAYER_STATE | getState ()=0
virtual int | registerPlayerSourceObserver (IMediaPlayerSourceObserver *observer)=0
virtual int | unregisterPlayerSourceObserver (IMediaPlayerSourceObserver *observer)=0
virtual int | registerAudioFrameObserver (media::IAudioPcmFrameSink *observer)=0
virtual int | unregisterAudioFrameObserver (media::IAudioPcmFrameSink *observer)=0
virtual int | openWithAgoraCDNSrc (const char *src, int64_t startPos)=0
virtual int | getAgoraCDNLineCount ()=0
virtual int | switchAgoraCDNLineByIndex (int index)=0
virtual int | getCurrentAgoraCDNIndex ()=0
virtual int | enableAutoSwitchAgoraCDN (bool enable)=0
virtual int | renewAgoraCDNSrcToken (const char *token, int64_t ts)=0
virtual int | switchAgoraCDNSrc (const char *src, bool syncPts=false)=0
virtual int | switchSrc (const char *src, bool syncPts)=0
virtual int | preloadSrc (const char *src, int64_t startPos)=0
virtual int | unloadSrc (const char *src)=0
virtual int | playPreloadedSrc (const char *src)=0
Public Member Functions inherited from agora::RefCountInterface
virtual void | AddRef () const =0
virtual RefCountReleaseStatus | Release () const =0
virtual bool | HasOneRef () const =0

## Protected Member Functions
virtual | ~IMediaPlayerSource ()
Protected Member Functions inherited from agora::RefCountInterface
virtual | ~RefCountInterface ()

## Detailed Description

The IMediaPlayerSource class provides access to a media player source. To playout multiple media sources simultaneously, create multiple media player source objects.

## Constructor & Destructor Documentation

## ◆ ~IMediaPlayerSource()

virtual agora::rtc::IMediaPlayerSource::~IMediaPlayerSource | ( |  | ) |
| inline protected virtual

## Member Function Documentation

## ◆ getSourceId()

virtual int agora::rtc::IMediaPlayerSource::getSourceId | ( |  | ) | const
| pure virtual

Gets the unique source ID of the media player source.

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

## ◆ open()

virtual int agora::rtc::IMediaPlayerSource::open | ( | const char * | url,
|  | int64_t | startPos
| ) |  |
| pure virtual

Opens a media file with a specified URL.

Parameters

  url | The path of the media file. Both the local path and online path are supported.
  startPos | The starting position (ms) for playback. Default value is 0.

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

## ◆ openWithMediaSource()

virtual int agora::rtc::IMediaPlayerSource::openWithMediaSource | ( | const media::base::MediaSource & | source | ) |
| pure virtual

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()

virtual int agora::rtc::IMediaPlayerSource::play | ( |  | ) |
| pure virtual

Plays the media file.

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

## ◆ pause()

virtual int agora::rtc::IMediaPlayerSource::pause | ( |  | ) |
| pure virtual

Pauses the playback.

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

## ◆ stop()

virtual int agora::rtc::IMediaPlayerSource::stop | ( |  | ) |
| pure virtual

Stops the playback.

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

## ◆ resume()

virtual int agora::rtc::IMediaPlayerSource::resume | ( |  | ) |
| pure virtual

Resumes the playback.

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

## ◆ seek()

virtual int agora::rtc::IMediaPlayerSource::seek | ( | int64_t | newPos | ) |
| pure virtual

Sets the playback position of the media file.

Parameters

  newPos | The new playback position (ms).

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

## ◆ getDuration()

virtual int agora::rtc::IMediaPlayerSource::getDuration | ( | int64_t & | duration | ) |
| pure virtual

Gets the duration of the media file.

Parameters

  [out] | duration | A reference to the duration of the media file.

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

## ◆ getPlayPosition()

virtual int agora::rtc::IMediaPlayerSource::getPlayPosition | ( | int64_t & | pos | ) |
| pure virtual

Gets the current playback position of the media file.

Parameters

  [out] | pos | A reference to the current playback position (ms).

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

## ◆ getStreamCount()

virtual int agora::rtc::IMediaPlayerSource::getStreamCount | ( | int64_t & | count | ) |
| pure virtual

Gets the number of the media streams in the media source.

Parameters

  [out] | count | The number of the media streams in the media source.

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

## ◆ getStreamInfo()

virtual int agora::rtc::IMediaPlayerSource::getStreamInfo | ( | int64_t | index,
|  | media::base::PlayerStreamInfo * | info
| ) |  |
| pure virtual

Gets the detailed information of a media stream.

Parameters

  | index | The index of the media stream.
  [out] | info | The detailed information of the media stream. See PlayerStreamInfo for details.

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

## ◆ setLoopCount()

virtual int agora::rtc::IMediaPlayerSource::setLoopCount | ( | int64_t | loopCount | ) |
| pure virtual

Sets whether to loop the media file for playback.

Parameters

  loopCount | The number of times of looping the media file. 0: Play the media file once. 1: Play the media file twice. -1: Play the media file in a loop indefinitely, until stop is called.

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

## ◆ setPlaybackSpeed()

virtual int agora::rtc::IMediaPlayerSource::setPlaybackSpeed | ( | int | speed | ) |
| pure virtual

Changes the playback speed.

Parameters

  speed | The playback speed ref [50-400].

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

## ◆ selectAudioTrack()

virtual int agora::rtc::IMediaPlayerSource::selectAudioTrack | ( | int64_t | index | ) |
| pure virtual

Selects an audio track of the media file for playback.

Parameters

  index | The index of the audio track in media file.

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

## ◆ selectMultiAudioTrack()

virtual int agora::rtc::IMediaPlayerSource::selectMultiAudioTrack | ( | int | playoutTrackIndex,
|  | int | publishTrackIndex
| ) |  |
| pure virtual

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() [1/2]

virtual int agora::rtc::IMediaPlayerSource::setPlayerOption | ( | const char * | key,
|  | int64_t | value
| ) |  |
| pure virtual

Changes the player option before playing a file.

Parameters

  key | The key of the option paramemter.
  value | The value of option parameter.

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

## ◆ setPlayerOption() [2/2]

virtual int agora::rtc::IMediaPlayerSource::setPlayerOption | ( | const char * | key,
|  | const char * | value
| ) |  |
| pure virtual

Changes the player option before playing a file.

Parameters

  key | The key of the option paramemter.
  value | The value of option parameter.

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

## ◆ takeScreenshot()

virtual int agora::rtc::IMediaPlayerSource::takeScreenshot | ( | const char * | filename | ) |
| pure virtual

Takes a screenshot when playing a video file.

Parameters

  filename | The filename of the screenshot file.

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

## ◆ selectInternalSubtitle()

virtual int agora::rtc::IMediaPlayerSource::selectInternalSubtitle | ( | int64_t | index | ) |
| pure virtual

Selects internal subtitles for a video file.

Parameters

  index | The index of the internal subtitles.

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

## ◆ setExternalSubtitle()

virtual int agora::rtc::IMediaPlayerSource::setExternalSubtitle | ( | const char * | url | ) |
| pure virtual

Sets an external subtitle file for a video file.

Parameters

  url | The URL of the subtitle file.

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

## ◆ getState()

virtual media::base::MEDIA_PLAYER_STATE agora::rtc::IMediaPlayerSource::getState | ( |  | ) |
| pure virtual

Gets the playback state.

Returns
  The current playback state. See MEDIA_PLAYER_STATE for details.

## ◆ registerPlayerSourceObserver()

virtual int agora::rtc::IMediaPlayerSource::registerPlayerSourceObserver | ( | IMediaPlayerSourceObserver * | observer | ) |
| pure virtual

Registers a media player source observer.

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

Parameters

  observer | The pointer to the IMediaPlayerSourceObserver object.

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

Implemented in agora::rtc::IMediaPlayerSourceEx.

## ◆ unregisterPlayerSourceObserver()

virtual int agora::rtc::IMediaPlayerSource::unregisterPlayerSourceObserver | ( | IMediaPlayerSourceObserver * | observer | ) |
| pure virtual

Releases the media player source observer.

Parameters

  observer | The pointer to the IMediaPlayerSourceObserver object.

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

## ◆ registerAudioFrameObserver()

virtual int agora::rtc::IMediaPlayerSource::registerAudioFrameObserver | ( | media::IAudioPcmFrameSink * | observer | ) |
| pure virtual

Registers the audio frame observer.

Parameters

  observer | The pointer to the observer object.

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

## ◆ unregisterAudioFrameObserver()

virtual int agora::rtc::IMediaPlayerSource::unregisterAudioFrameObserver | ( | media::IAudioPcmFrameSink * | observer | ) |
| pure virtual

Releases the audio frame observer.

Parameters

  observer | The pointer to the observer object.

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

## ◆ openWithAgoraCDNSrc()

virtual int agora::rtc::IMediaPlayerSource::openWithAgoraCDNSrc | ( | const char * | src,
|  | int64_t | startPos
| ) |  |
| pure virtual

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()

virtual int agora::rtc::IMediaPlayerSource::getAgoraCDNLineCount | ( |  | ) |
| pure virtual

Gets the number of Agora CDN lines.

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

## ◆ switchAgoraCDNLineByIndex()

virtual int agora::rtc::IMediaPlayerSource::switchAgoraCDNLineByIndex | ( | int | index | ) |
| pure virtual

Switch Agora CDN lines.

Parameters

  index | Specific CDN line index.

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

## ◆ getCurrentAgoraCDNIndex()

virtual int agora::rtc::IMediaPlayerSource::getCurrentAgoraCDNIndex | ( |  | ) |
| pure virtual

Gets the line of the current CDN.

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

## ◆ enableAutoSwitchAgoraCDN()

virtual int agora::rtc::IMediaPlayerSource::enableAutoSwitchAgoraCDN | ( | bool | enable | ) |
| pure virtual

Enable automatic CDN line switching.

Parameters

  enable | Whether enable.

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

## ◆ renewAgoraCDNSrcToken()

virtual int agora::rtc::IMediaPlayerSource::renewAgoraCDNSrcToken | ( | const char * | token,
|  | int64_t | ts
| ) |  |
| pure virtual

Update the CDN source token and timestamp.

Parameters

  token | token.
  ts | ts.

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

## ◆ switchAgoraCDNSrc()

virtual int agora::rtc::IMediaPlayerSource::switchAgoraCDNSrc | ( | const char * | src,
|  | bool | syncPts = `false`
| ) |  |
| pure virtual

Switch the CDN source when open a media through "openWithAgoraCDNSrc" API

Parameters

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

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

## ◆ switchSrc()

virtual int agora::rtc::IMediaPlayerSource::switchSrc | ( | const char * | src,
|  | bool | syncPts
| ) |  |
| pure virtual

Switch the media source when open a media through "open" API

Parameters

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

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

## ◆ preloadSrc()

virtual int agora::rtc::IMediaPlayerSource::preloadSrc | ( | const char * | src,
|  | int64_t | startPos
| ) |  |
| pure virtual

Preload a media source

Parameters

  src | Specific src.
  startPos | The starting position (ms) for playback. Default value is 0.

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

## ◆ unloadSrc()

virtual int agora::rtc::IMediaPlayerSource::unloadSrc | ( | const char * | src | ) |
| pure virtual

Unload a preloaded media source

Parameters

  src | Specific src.

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

## ◆ playPreloadedSrc()

virtual int agora::rtc::IMediaPlayerSource::playPreloadedSrc | ( | const char * | src | ) |
| pure virtual

Play a pre-loaded media source

Parameters

  src | Specific src.

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