Stream media to a channel

Playing media files during online business presentations, educational sessions, or casual meetups heightens user engagement. Video SDK enables you to add media playing functionality to your app.

This page shows you how to use media player-related APIs to play local or online media resources with remote users in Broadcast Streaming channels.

Understand the tech

To play a media file in a channel, you open the file using a media player instance. When the file is ready to be played, you set up the local video container to display the media player output. You update channel media options to start publishing the media player stream, and stop publishing the camera and microphone streams. The remote user sees the camera and microphone streams of the media publishing user replaced by media streams.

Media player flow

Prerequisites

Ensure that you have implemented the SDK quickstart in your project.

Implement the logic

To implement a media player in your app, follow these steps:

After initializing an RtcEngine instance, create an IMediaPlayer object and register a player observer by calling the registerPlayerObserver method.

mRtcEngine = RtcEngine.create(config);

 // Create a media player object
 mediaPlayer = mRtcEngine.createMediaPlayer();
 // Register a player observer
 mediaPlayer.registerPlayerObserver(this);

mRtcEngine = RtcEngine.create(config)

 // Create a media player object
 mediaPlayer = mRtcEngine.createMediaPlayer()
 // Register a player observer
 mediaPlayer.registerPlayerObserver(this)

Implement the callbacks for the media player observer. Observe the player's state through the onPlayerStateChanged callback, get the current media file's playback progress through onPositionChanged, and handle player events through the onPlayerEvent callback.

@Override
  // Observe the player's state
  public void onPlayerStateChanged(io.agora.mediaplayer.Constants.MediaPlayerState mediaPlayerState, io.agora.mediaplayer.Constants.MediaPlayerError mediaPlayerError) {
    Log.e(TAG, "onPlayerStateChanged mediaPlayerState " + mediaPlayerState);
    Log.e(TAG, "onPlayerStateChanged mediaPlayerError " + mediaPlayerError);
    if (mediaPlayerState.equals(PLAYER_STATE_OPEN_COMPLETED)) {
      setMediaPlayerViewEnable(true);
    } else if (mediaPlayerState.equals(PLAYER_STATE_IDLE) || mediaPlayerState.equals(PLAYER_STATE_PLAYBACK_COMPLETED)) {
      setMediaPlayerViewEnable(false);
    }
  }

  @Override
  // Observe the current playback progress
  public void onPositionChanged(long position) {
    Log.e(TAG, "onPositionChanged position " + position);
    if (playerDuration > 0) {
      final int result = (int) ((float) position / (float) playerDuration * 100);
      handler.post(new Runnable() {
        @Override
        public void run() {
          progressBar.setProgress(Long.valueOf(result).intValue());
        }
      });
    }
  }

  @Override
  // Observe player events
  public void onPlayerEvent(io.agora.mediaplayer.Constants.MediaPlayerEvent mediaPlayerEvent) {
    Log.e(TAG, " onPlayerEvent mediaPlayerEvent " + mediaPlayerEvent);
  }

// Observe the player's state
  override fun onPlayerStateChanged(
    mediaPlayerState: io.agora.mediaplayer.Constants.MediaPlayerState,
    mediaPlayerError: io.agora.mediaplayer.Constants.MediaPlayerError
  ) {
    Log.e(TAG, "onPlayerStateChanged mediaPlayerState $mediaPlayerState")
    Log.e(TAG, "onPlayerStateChanged mediaPlayerError $mediaPlayerError")

    when (mediaPlayerState) {
      PLAYER_STATE_OPEN_COMPLETED -> setMediaPlayerViewEnable(true)
      PLAYER_STATE_IDLE, PLAYER_STATE_PLAYBACK_COMPLETED -> setMediaPlayerViewEnable(false)
    }
  }

  // Observe the current playback progress
  override fun onPositionChanged(position: Long) {
    Log.e(TAG, "onPositionChanged position $position")

    if (playerDuration > 0) {
      val result = (position.toFloat() / playerDuration.toFloat() * 100).toInt()
      handler.post {
        progressBar.progress = result
      }
    }
  }

  // Observe player events
  override fun onPlayerEvent(mediaPlayerEvent: io.agora.mediaplayer.Constants.MediaPlayerEvent) {
    Log.e(TAG, "onPlayerEvent mediaPlayerEvent $mediaPlayerEvent")
  }

Call setupLocalVideo to render the local media player view.

VideoCanvas videoCanvas = new VideoCanvas(surfaceView, Constants.RENDER_MODE_HIDDEN, Constants.VIDEO_MIRROR_MODE_AUTO,
  Constants.VIDEO_SOURCE_MEDIA_PLAYER, mediaPlayer.getMediaPlayerId(), 0);
  mRtcEngine.setupLocalVideo(videoCanvas);

val videoCanvas = VideoCanvas(
   surfaceView,
   Constants.RENDER_MODE_HIDDEN,
   Constants.VIDEO_MIRROR_MODE_AUTO,
   Constants.VIDEO_SOURCE_MEDIA_PLAYER,
   mediaPlayer.mediaPlayerId,
   0
 )

 mRtcEngine.setupLocalVideo(videoCanvas)

When joining a channel, use ChannelMediaOptions to set the media player ID, publish media player audio and video, and share media resources with remote users in the channel.

private ChannelMediaOptions options = new ChannelMediaOptions();

  // Set up options
  options.publishMediaPlayerId = mediaPlayer.getMediaPlayerId();
  options.publishMediaPlayerAudioTrack = true;
  options.publishMediaPlayerVideoTrack = true;

  // Join the channel
  int res = mRtcEngine.joinChannel(accessToken, channelId, 0, options);

val options = ChannelMediaOptions()

 // Set up options
 options.publishMediaPlayerId = mediaPlayer.mediaPlayerId
 options.publishMediaPlayerAudioTrack = true
 options.publishMediaPlayerVideoTrack = true

 // Join the channel
 val res = mRtcEngine.joinChannel(accessToken, channelId, 0, options)

Use the open method to open a local or online media file.

mediaPlayer.open(url, 0);

mediaPlayer.open(url, 0)

Call the play method to play the media file.

mediaPlayer.play();

mediaPlayer?.play()

Call the play method to play the media file only after receiving the onPlayerStateChanged callback reporting the player state as PLAYER_STATE_OPEN_COMPLETED.

When a user leaves the channel, call stop to stop playback, destroy to destroy the media player, unRegisterPlayerObserver to unregister the player observer, and release allocated resources.

mediaPlayer.stop();
 mediaPlayer.destroy();
 mediaPlayer.unRegisterPlayerObserver(this);

mediaPlayer.stop()
 mediaPlayer.destroy()
 mediaPlayer.unRegisterPlayerObserver(this)

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

Supported formats and protocols

The media player supports the following media formats and protocols:

Video encoding formats

H.263, H.264, H.265, MPEG-4, MPEG-2, RMVB, Theora, VP3, VP8, AVS, WMV

Audio coding formats

WAV, MP2, MP3, AAC, OPUS, FLAC, Vorbis, AMR-NB, AMR-WB, WMA v1, WMA v2

Container formats

WAV, FLAC, OGG, MOV, ASF, FLV, MP3, MP4, MPEG-TS, Matroska (MKV), AVI, ASS, CONCAT, DTS, AVS

Supported protocols

HTTP, HTTPS, RTMP, HLS, RTP, RTSP

Sample project

Agora provides an open source sample project MediaPlayer on GitHub. Download it or view the source code for a more detailed example.

API reference

Playing media files during online business presentations, educational sessions, or casual meetups heightens user engagement. Video SDK enables you to add media playing functionality to your app.

This page shows you how to use media player-related APIs to play local or online media resources with remote users in Broadcast Streaming channels.

Understand the tech

Media player flow

Prerequisites

Ensure that you have implemented the SDK quickstart in your project.

Implement the logic

To implement a media player in your app, follow these steps:

After initializing an instance of AgoraRtcEngineKit, create a mediaPlayerKit object.

// Initialize AgoraRtcEngineKit and create a mediaPlayerKit object.
agoraKit = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self)
// Create mediaPlayerKit object
mediaPlayerKit = agoraKit.createMediaPlayer(with: self)

Implement media player callbacks. Observe the status of the player through callbacks and obtain the playback progress of the current media file.

extension MediaPlayerMain: AgoraRtcMediaPlayerDelegate {
  // Observe the state of the player
  func agoraRtcMediaPlayer(_ playerKit: AgoraRtcMediaPlayerProtocol, didChangedTo state: AgoraMediaPlayerState, error: AgoraMediaPlayerError) {
    LogUtils.log(message: "Player RTC channel publish helper state changed to: \(state.rawValue), error: \(error.rawValue)", level: .info)
    DispatchQueue.main.async { [weak self] in
      guard let weakself = self else { return }
      switch state {
      case .failed:
        weakself.showAlert(message: "Media player error: \(error.rawValue)")
        break
      case .openCompleted:
        let duration = weakself.mediaPlayerKit.getDuration()
        weakself.playerControlStack.isHidden = false
        weakself.playerDurationLabel.text = "\(String(format: "%02d", duration / 60)) : \(String(format: "%02d", duration % 60))"
        weakself.playerProgressSlider.setValue(0, animated: true)
        break
      case .stopped:
        weakself.playerControlStack.isHidden = true
        weakself.playerProgressSlider.setValue(0, animated: true)
        weakself.playerDurationLabel.text = "00 : 00"
        break
      default: break
      }
    }
  }
  // Observe the current playback progress
  func agoraRtcMediaPlayer(_ playerKit: AgoraRtcMediaPlayerProtocol, didChangedToPosition position: Int) {
    let duration = Float(mediaPlayerKit.getDuration() * 1000)
    var progress: Float = 0
    var left: Int = 0
    if duration > 0 {
      progress = Float(mediaPlayerKit.getPosition()) / duration
      left = Int((mediaPlayerKit.getDuration() * 1000 - mediaPlayerKit.getPosition()) / 1000)
    }
    DispatchQueue.main.async { [weak self] in
      guard let weakself = self else { return }
      weakself.playerDurationLabel.text = "\(String(format: "%02d", left / 60)) : \(String(format: "%02d", left % 60))"
      if !weakself.playerProgressSlider.isTouchInside {
        weakself.playerProgressSlider.setValue(progress, animated: true)
      }
    }
  }
}

Call the setupLocalVideo method to render the local media player view.

mediaPlayerKit.setView(localVideo.videoView)
let videoCanvas = AgoraRtcVideoCanvas()
videoCanvas.view = localVideo.videoView
videoCanvas.renderMode = .hidden
videoCanvas.sourceType = .mediaPlayer
videoCanvas.sourceId = mediaPlayerKit.getMediaPlayerId()
agoraKit.setupLocalVideo(videoCanvas)

When joining a channel using joinChannelByToken, set the media player ID, publish media player's audio and video, and share media resources with remote users in the channel through the mediaOptions parameter.
```
let option1 = AgoraRtcChannelMediaOptions()

// ...

option1.publishMediaPlayerId = .of((Int32)(mediaPlayerKit.getMediaPlayerId()))
```
Use the open method to open a local or online media file.
```
mediaPlayerKit.open(url, startPos: 0)
```
Call the play method to play the media file.
```
mediaPlayerKit.play()
```

Call the play method to play the media file only after receiving the didChangedToState callback reporting the player state as AgoraMediaPlayerStateOpenCompleted.

When a user leaves the channel, call stop to stop playback, and destroyMediaPlayer to release resources.
```
mediaPlayerKit.stop()
agoraKit.destroyMediaPlayer(mediaPlayerKit)
```

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

Supported formats and protocols

The media player supports the following media formats and protocols:

Video encoding formats

H.263, H.264, H.265, MPEG-4, MPEG-2, RMVB, Theora, VP3, VP8, AVS, WMV

Audio coding formats

WAV, MP2, MP3, AAC, OPUS, FLAC, Vorbis, AMR-NB, AMR-WB, WMA v1, WMA v2

Container formats

WAV, FLAC, OGG, MOV, ASF, FLV, MP3, MP4, MPEG-TS, Matroska (MKV), AVI, ASS, CONCAT, DTS, AVS

Supported protocols

HTTP, HTTPS, RTMP, HLS, RTP, RTSP

Sample project

Agora provides an open source sample project MediaPlayer on GitHub. Download it or view the source code for a more detailed example.

API reference

Playing media files during online business presentations, educational sessions, or casual meetups heightens user engagement. Video SDK enables you to add media playing functionality to your app.

This page shows you how to use media player-related APIs to play local or online media resources with remote users in Broadcast Streaming channels.

Understand the tech

Media player flow

Prerequisites

Ensure that you have implemented the SDK quickstart in your project.

Implement the logic

To implement a media player in your app, follow these steps:

After initializing an instance of AgoraRtcEngineKit, create a mediaPlayerKit object.

// Initialize AgoraRtcEngineKit and create a mediaPlayerKit object.
agoraKit = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self)
// Create mediaPlayerKit object
mediaPlayerKit = agoraKit.createMediaPlayer(with: self)

Implement media player callbacks. Observe the status of the player through callbacks and obtain the playback progress of the current media file.

extension MediaPlayerMain: AgoraRtcMediaPlayerDelegate {
  // Observe the state of the player
  func agoraRtcMediaPlayer(_ playerKit: AgoraRtcMediaPlayerProtocol, didChangedTo state: AgoraMediaPlayerState, error: AgoraMediaPlayerError) {
    LogUtils.log(message: "Player RTC channel publish helper state changed to: \(state.rawValue), error: \(error.rawValue)", level: .info)
    DispatchQueue.main.async { [weak self] in
      guard let weakself = self else { return }
      switch state {
      case .failed:
        weakself.showAlert(message: "Media player error: \(error.rawValue)")
        break
      case .openCompleted:
        let duration = weakself.mediaPlayerKit.getDuration()
        weakself.playerControlStack.isHidden = false
        weakself.playerDurationLabel.text = "\(String(format: "%02d", duration / 60)) : \(String(format: "%02d", duration % 60))"
        weakself.playerProgressSlider.setValue(0, animated: true)
        break
      case .stopped:
        weakself.playerControlStack.isHidden = true
        weakself.playerProgressSlider.setValue(0, animated: true)
        weakself.playerDurationLabel.text = "00 : 00"
        break
      default: break
      }
    }
  }
  // Observe the current playback progress
  func agoraRtcMediaPlayer(_ playerKit: AgoraRtcMediaPlayerProtocol, didChangedToPosition position: Int) {
    let duration = Float(mediaPlayerKit.getDuration() * 1000)
    var progress: Float = 0
    var left: Int = 0
    if duration > 0 {
      progress = Float(mediaPlayerKit.getPosition()) / duration
      left = Int((mediaPlayerKit.getDuration() * 1000 - mediaPlayerKit.getPosition()) / 1000)
    }
    DispatchQueue.main.async { [weak self] in
      guard let weakself = self else { return }
      weakself.playerDurationLabel.text = "\(String(format: "%02d", left / 60)) : \(String(format: "%02d", left % 60))"
      if !weakself.playerProgressSlider.isTouchInside {
        weakself.playerProgressSlider.setValue(progress, animated: true)
      }
    }
  }
}

Call the setupLocalVideo method to render the local media player view.

mediaPlayerKit.setView(localVideo.videoView)
let videoCanvas = AgoraRtcVideoCanvas()
videoCanvas.view = localVideo.videoView
videoCanvas.renderMode = .hidden
videoCanvas.sourceType = .mediaPlayer
videoCanvas.sourceId = mediaPlayerKit.getMediaPlayerId()
agoraKit.setupLocalVideo(videoCanvas)

When joining a channel using joinChannelByToken, set the media player ID, publish media player's audio and video, and share media resources with remote users in the channel through the mediaOptions parameter.
```
let option1 = AgoraRtcChannelMediaOptions()

// ...

option1.publishMediaPlayerId = .of((Int32)(mediaPlayerKit.getMediaPlayerId()))
```
Use the open method to open a local or online media file.
```
mediaPlayerKit.open(url, startPos: 0)
```
Call the play method to play the media file.
```
mediaPlayerKit.play()
```

Call the play method to play the media file only after receiving the didChangedToState callback reporting the player state as AgoraMediaPlayerStateOpenCompleted.

When a user leaves the channel, call stop to stop playback, and destroyMediaPlayer to release resources.
```
mediaPlayerKit.stop()
agoraKit.destroyMediaPlayer(mediaPlayerKit)
```

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

Supported formats and protocols

The media player supports the following media formats and protocols:

Video encoding formats

H.263, H.264, H.265, MPEG-4, MPEG-2, RMVB, Theora, VP3, VP8, AVS, WMV

Audio coding formats

WAV, MP2, MP3, AAC, OPUS, FLAC, Vorbis, AMR-NB, AMR-WB, WMA v1, WMA v2

Container formats

WAV, FLAC, OGG, MOV, ASF, FLV, MP3, MP4, MPEG-TS, Matroska (MKV), AVI, ASS, CONCAT, DTS, AVS

Supported protocols

HTTP, HTTPS, RTMP, HLS, RTP, RTSP

Sample project

Agora provides an open source sample project MediaPlayer on GitHub. Download it or view the source code for a more detailed example.

API reference

Playing media files during online business presentations, educational sessions, or casual meetups heightens user engagement. Video SDK enables you to add media playing functionality to your app.

This page shows you how to use media player-related APIs to play local or online media resources with remote users in Broadcast Streaming channels.

Understand the tech

Media player flow

Prerequisites

Ensure that you have implemented the SDK quickstart in your project.

Implement the logic

To implement a media player in your app, follow these steps:

After initializing an instance of IRtcEngine, create an IMediaPlayer object.

void CAgoraMediaPlayer::InitMediaPlayerKit() {
  // Create Agora media player
  m_mediaPlayer = m_rtcEngine->createMediaPlayer().get();
  m_lstInfo.InsertString(m_lstInfo.GetCount(), _T("createAgoraMediaPlayer"));
  m_lstInfo.InsertString(m_lstInfo.GetCount(), _T("Media player initialization"));

  // Set the player rendering view
  RECT rc = {0};
  m_localVideoWnd.GetWindowRect(&rc);
  int ret = m_mediaPlayer->setView(
    (agora::media::base::view_t)m_localVideoWnd.GetSafeHwnd());

  // Set the window to receive player events
  m_mediaPlayerEvent.SetMsgReceiver(m_hWnd);
}

To register the playback observer, call registerPlayerSourceObserverthe before you join the channel. To unregister the playback observer, call unregisterPlayerSourceObserver before you leave the channel.

void CAgoraMediaPlayer::OnBnClickedButtonJoinchannel() {
  // ...
  // Register the player observer
  ret = m_mediaPlayer->registerPlayerSourceObserver(&m_mediaPlayerEvent);
  m_lstInfo.InsertString(m_lstInfo.GetCount(),
            _T("registerPlayerSourceObserver"));

  if (0 ==
    m_rtcEngine->joinChannel(APP_TOKEN, szChannelId.c_str(), 0, options)) {
    strInfo.Format(_T("Join channel %s, use ChannelMediaOptions"),
          getCurrentTime());
  }
  else {
    // Unregister the player observer
    ret = m_mediaPlayer->unregisterPlayerSourceObserver(&m_mediaPlayerEvent);
    m_lstInfo.InsertString(m_lstInfo.GetCount(),
              _T("unregisterPlayerSourceObserver"));

    // Leave the channel in the engine.
    if (0 == m_rtcEngine->leaveChannel()) {
      strInfo.Format(_T("Leave channel %s"), getCurrentTime());
    }
  }

  m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
}

Implement callbacks for the observer.

// Observe player state changes
LRESULT CAgoraMediaPlayer::OnmediaPlayerStateChanged(WPARAM wParam,
                           LPARAM lParam) {
  CString strState;
  CString strError;
  switch ((agora::media::base::MEDIA_PLAYER_STATE)wParam) {
    case agora::media::base::PLAYER_STATE_OPEN_COMPLETED:
      strState = _T("PLAYER_STATE_OPEN_COMPLETED");
      m_mediaPlayerState = mediaPLAYER_OPEN;
      int64_t duration;
      m_mediaPlayer->getDuration(duration);
      m_sldVideo.SetRangeMax((int)duration);

      break;
    // Additional cases for other player states...
  }

  switch ((agora::media::base::MEDIA_PLAYER_ERROR)lParam) {
    case agora::media::base::PLAYER_ERROR_URL_NOT_FOUND:
      strError = _T("PLAYER_ERROR_URL_NOT_FOUND");
      // Additional cases for other player errors...
      break;
  }
  CString strInfo;
  strInfo.Format(_T("State:%s,\nError:%s"), strState, strError);
  m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
  return TRUE;
}

// Observe current playback progress
LRESULT CAgoraMediaPlayer::OnmediaPlayerPositionChanged(WPARAM wParam,
                            LPARAM lParam) {
  int64_t *p = (int64_t *)wParam;
  m_sldVideo.SetPos((int)*p);
  delete p;
  return TRUE;
}

When joining a channel use ChannelMediaOptions to set the media player ID, publish media player's audio and video, and share media resources with remote users in the channel.

void CAgoraMediaPlayer::OnBnClickedButtonPublishVideo() {
  if (m_publishMeidaplayer) {
    ChannelMediaOptions op;
    op.clientRoleType = CLIENT_ROLE_BROADCASTER;
    op.publishMediaPlayerVideoTrack = false;
    op.publishMediaPlayerAudioTrack = false;
    op.publishMediaPlayerId = m_mediaPlayer->getMediaPlayerId();
    int ret = m_rtcEngine->updateChannelMediaOptions(op);
    ChannelMediaOptions op2;
    op2.clientRoleType = CLIENT_ROLE_BROADCASTER;
    op2.publishCameraTrack = true;
    ret = m_rtcEngine->updateChannelMediaOptions(op2);
    m_publishMeidaplayer = false;
  } else {
    ChannelMediaOptions options;
    options.clientRoleType = CLIENT_ROLE_BROADCASTER;
    options.publishMediaPlayerVideoTrack = true;
    options.publishMediaPlayerAudioTrack = true;
    options.publishMediaPlayerId = m_mediaPlayer->getMediaPlayerId();
    options.publishCameraTrack = false;
    options.publishAudioTrack = false;
    options.autoSubscribeAudio = false;
    options.autoSubscribeVideo = false;
    m_rtcEngine->updateChannelMediaOptions(options);
    m_publishMeidaplayer = true;
  }
}

Use the open method to open a local or online media file.

void CAgoraMediaPlayer::OnBnClickedButtonOpen() {
  CString strUrl;
  CString strInfo;
  m_edtVideoSource.GetWindowText(strUrl);
  std::string tmp = cs2utf8(strUrl);
  switch (m_mediaPlayerState) {
    case mediaPLAYER_READY:
    case mediaPLAYER_STOP:
      if (tmp.empty()) {
        AfxMessageBox(_T("you can fill video source."));
        return;
      }
      m_mediaPlayer->open(tmp.c_str(), 0);
      break;
    default:
      m_lstInfo.InsertString(m_lstInfo.GetCount(),
                _T("can not open player."));
      break;
  }
}

Call the play method to play the media file.

void CAgoraMediaPlayer::OnBnClickedButtonPlay() {
  int ret;
  switch (m_mediaPlayerState) {
    case mediaPLAYER_PAUSE:
    case mediaPLAYER_OPEN:
      // Play media file
      ret = m_mediaPlayer->play();
      if (ret == 0) {
        m_mediaPlayerState = mediaPLAYER_PLAYING;
      }
      break;
    case mediaPLAYER_PLAYING:
      // Pause playback
      ret = m_mediaPlayer->pause();
      if (ret == 0) {
        m_mediaPlayerState = mediaPLAYER_PAUSE;
      }
      break;
    default:
      break;
  }
}

Call the play method to play the media file only after receiving the onPlayerSourceStateChanged callback reporting the player state as PLAYER_STATE_OPEN_COMPLETED.

When a user stops playback or leaves the channel, call stop to stop playback, and destroyMediaPlayer to release resources.

void CAgoraMediaPlayer::OnBnClickedButtonStop() {
  if (m_mediaPlayerState == mediaPLAYER_OPEN ||
    m_mediaPlayerState == mediaPLAYER_PLAYING ||
    m_mediaPlayerState == mediaPLAYER_PAUSE) {
    // Stop playback
    m_mediaPlayer->stop();
    m_mediaPlayerState = mediaPLAYER_STOP;
  }
}

void CAgoraMediaPlayer::OnDestroy() {
  // Destroy the media player
  CDialogEx::OnDestroy();
  m_mediaPlayer->destroy();
}

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

Supported formats and protocols

The media player supports the following media formats and protocols:

Video encoding formats

H.263, H.264, H.265, MPEG-4, MPEG-2, RMVB, Theora, VP3, VP8, AVS, WMV

Audio coding formats

WAV, MP2, MP3, AAC, OPUS, FLAC, Vorbis, AMR-NB, AMR-WB, WMA v1, WMA v2

Container formats

WAV, FLAC, OGG, MOV, ASF, FLV, MP3, MP4, MPEG-TS, Matroska (MKV), AVI, ASS, CONCAT, DTS, AVS

Supported protocols

HTTP, HTTPS, RTMP, HLS, RTP, RTSP

Sample project

Agora provides an open source MediaPlayer sample project on GitHub. Download it or view the source code for a more detailed example.

API reference

Playing media files during online business presentations, educational sessions, or casual meetups heightens user engagement. Video SDK enables you to add media playing functionality to your app.

This page shows you how to use media player-related APIs to play local or online media resources with remote users in Broadcast Streaming channels.

Understand the tech

Media player flow

Prerequisites

Ensure that you have implemented the SDK quickstart in your project.

Implement the logic

To implement a media player in your app, follow these steps:

Initialize IRtcEngine and create an IMediaPlayer object:

// Create and initialize the engine
let rtcEngine = createAgoraRtcEngine();
rtcEngine.initialize({
 appId,
});
// Create a media player object
let mediaPlayer = rtcEngine.createMediaPlayer();

// Register playback observer
mediaPlayer.registerPlayerSourceObserver(this);

onPlayerSourceStateChanged: Reports player state changes.
onPositionChanged: Reports playback progress.
onPlayerEvent: Reports player events.

const EventHandles = {
  // Report player state change
  onPlayerSourceStateChanged: (state, ec) => {
    console.log(`state: ${state}, ec: ${ec}`);
  },

  // Report current media file playback progress
  onPositionChanged: (position) => {
    console.log(`position: ${position}`);
  },

  // Report player event
  onPlayerEvent: (eventCode, elapsedTime, message) => {
    console.log(
      `eventCode: ${eventCode}, elapsedTime: ${elapsedTime}, message: ${message}`
    );
  }
};

// Register main callback events
rtcEngine.registerEventHandler(EventHandles);

Open a media file:

open = () => {
  const url = 'https://example/video.mov';

  if (!url) {
    this.error("url is invalid");
    return;
  }

  mediaPlayer.open(url, 0);
};

Play and control media playback:

// Play the media file
play = () => {
  const { position, duration } = this.state;
  if (position === duration && duration !== 0) {
    mediaPlayer.seek(0); // If playback is at the end, seek to the start
  } else {
    mediaPlayer.play(); // Otherwise, play the media
  }
};

// Pause the media file
pause = () => {
  mediaPlayer.pause(); // Pause playback
};

// Resume the media file
resume = () => {
  mediaPlayer.resume(); // Resume playback
};

Stop playback and release resources:

// Stop playing
mediaPlayer.stop();
// Destroy the media player
rtcEngine.destroyMediaPlayer(this.player);
// Unregister the playback observer
rtcEngine.unregisterEventHandler(this);

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

Sample project

Agora provides an open source MediaPlayer sample project on GitHub. Download it or view the source code for a more detailed example.

API reference

Playing media files during online business presentations, educational sessions, or casual meetups heightens user engagement. Video SDK enables you to add media playing functionality to your app.

This page shows you how to use media player-related APIs to play local or online media resources with remote users in Broadcast Streaming channels.

Understand the tech

Media player flow

Prerequisites

Ensure that you have implemented the SDK quickstart in your project.

Implement the logic

To implement a media player in your app, follow these steps:

Initialize IRtcEngine and create an IMediaPlayer object:

// Create and initialize the engine
let rtcEngine = createAgoraRtcEngine();
rtcEngine.initialize({
 appId,
});
// Create a media player object
let mediaPlayer = rtcEngine.createMediaPlayer();

// Register playback observer
mediaPlayer.registerPlayerSourceObserver(this);

onPlayerSourceStateChanged: Reports player state changes.
onPositionChanged: Reports playback progress.
onPlayerEvent: Reports player events.

const EventHandles = {
  // Report player state change
  onPlayerSourceStateChanged: (state, ec) => {
    console.log(`state: ${state}, ec: ${ec}`);
  },

  // Report current media file playback progress
  onPositionChanged: (position) => {
    console.log(`position: ${position}`);
  },

  // Report player event
  onPlayerEvent: (eventCode, elapsedTime, message) => {
    console.log(
      `eventCode: ${eventCode}, elapsedTime: ${elapsedTime}, message: ${message}`
    );
  }
};

// Register main callback events
rtcEngine.registerEventHandler(EventHandles);

Open a media file:

open = () => {
  const url = 'https://example/video.mov';

  if (!url) {
    this.error("url is invalid");
    return;
  }

  mediaPlayer.open(url, 0);
};

Play and control media playback:

// Play the media file
play = () => {
  const { position, duration } = this.state;
  if (position === duration && duration !== 0) {
    mediaPlayer.seek(0); // If playback is at the end, seek to the start
  } else {
    mediaPlayer.play(); // Otherwise, play the media
  }
};

// Pause the media file
pause = () => {
  mediaPlayer.pause(); // Pause playback
};

// Resume the media file
resume = () => {
  mediaPlayer.resume(); // Resume playback
};

Stop playback and release resources:

// Stop playing
mediaPlayer.stop();
// Destroy the media player
rtcEngine.destroyMediaPlayer(this.player);
// Unregister the playback observer
rtcEngine.unregisterEventHandler(this);

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

Sample project

Agora provides an open source MediaPlayer sample project on GitHub. Download it or view the source code for a more detailed example.

API reference

Playing media files during online business presentations, educational sessions, or casual meetups heightens user engagement. Video SDK enables you to add media playing functionality to your game.

This page shows you how to use media player-related APIs to play local or online media resources with remote users in Broadcast Streaming channels.

Understand the tech

Media player flow

Prerequisites

Ensure that you have implemented the SDK quickstart in your project.

Implement the logic

To implement a media player in your game, follow these steps:

Create a media player object

After initializing an IRtcEngine instance, call createMediaPlayer to create an IMediaPlayer object.

MediaPlayer = RtcEngine.CreateMediaPlayer();
if (MediaPlayer == null)
{
  this.Log.UpdateLog("Failed to create media player.");
  return;
}

If you need multiple media player objects, call createMediaPlayer multiple times.

Register callback events and implement callbacks

Call InitEventHandler from the IMediaPlayer class to register media player callback events.

MpkEventHandler handler = new MpkEventHandler(this);
MediaPlayer.InitEventHandler(handler);
this.Log.UpdateLog("Player ID: " + MediaPlayer.GetId());

Implement IMediaPlayerSourceObserver callbacks as needed.

class MpkEventHandler : IMediaPlayerSourceObserver
{
  // Report player status changes
  public override void OnPlayerSourceStateChanged(MEDIA_PLAYER_STATE state, MEDIA_PLAYER_REASON reason)
  {

  }

  // Report player events
  public override void OnPlayerEvent(MEDIA_PLAYER_EVENT @event, Int64 elapsedTime, string message)
  {
    Debug.Log($"OnPlayerEvent state: {@event}");
  }

  // Report preload events
  public override void OnPreloadEvent(string src, PLAYER_PRELOAD_EVENT @event)
  {
    Debug.Log($"OnPreloadEvent src: {src}, event: {@event}");
  }

  // Report media resource playback progress
  public override void OnPositionChanged(long positionMs, long timestampMs)
  {

  }
}

Set the video rendering window

To play a video, set the video renderer after opening the media resource. Destroy the video view when playback stops. Use GetId to retrieve the player ID and set VIDEO_SOURCE_TYPE to VIDEO_SOURCE_MEDIA_PLAYER.

// Handle player status changes
public override void OnPlayerSourceStateChanged(MEDIA_PLAYER_STATE state, MEDIA_PLAYER_REASON reason)
{
  Debug.Log($"State: {state}, Reason: {reason}, Player ID: {_sample.MediaPlayer.GetId()}");
  if (state == MEDIA_PLAYER_STATE.PLAYER_STATE_OPEN_COMPLETED)
  {
    // Create a view to display the video stream when the media resource opens
    MakeVideoView((uint)_sample.MediaPlayer.GetId(), "", VIDEO_SOURCE_TYPE.VIDEO_SOURCE_MEDIA_PLAYER);
  }
  else if (state == MEDIA_PLAYER_STATE.PLAYER_STATE_STOPPED)
  {
    // Destroy the video view after playback stops
    DestroyVideoView((uint)_sample.MediaPlayer.GetId());
  }
}

To set the video display, call SetForUser, and start rendering with SetEnable.

// Create a video view
static void MakeVideoView(uint uid, string channelId = "", VIDEO_SOURCE_TYPE videoSourceType = VIDEO_SOURCE_TYPE.VIDEO_SOURCE_CAMERA)
{
  var go = GameObject.Find(uid.ToString());
  if (go != null) return;

  // Create a GameObject for rendering video
  var videoSurface = MakeImageSurface(uid.ToString());
  if (videoSurface == null) return;

  // Set up video display
  videoSurface.SetForUser(uid, channelId, videoSourceType);
  videoSurface.SetEnable(true);

  // Adjust video surface size
  videoSurface.OnTextureSizeModify += (int width, int height) =>
  {
    var transform = videoSurface.GetComponent<RectTransform>();
    if (transform != null)
    {
      transform.sizeDelta = new Vector2(width / 2, height / 2);
      transform.localScale = Vector3.one;
    }
    else
    {
      float scale = (float)height / (float)width;
      videoSurface.transform.localScale = new Vector3(-1, 1, scale);
    }
    Debug.Log($"Texture size modified: {width} x {height}");
  };
}

// Destroy the video view
static void DestroyVideoView(uint uid)
{
  var go = GameObject.Find(uid.ToString());
  if (go != null)
  {
    Destroy(go);
  }
}

// Create a video view with a RawImage component
private static VideoSurface MakeImageSurface(string goName)
{
  GameObject go = new GameObject(goName);
  go.AddComponent<RawImage>();
  go.AddComponent<UIElementDrag>();

  var canvas = GameObject.Find("VideoCanvas");
  if (canvas != null)
  {
    go.transform.SetParent(canvas.transform);
    Debug.Log("Added video view");
  }
  else
  {
    Debug.Log("Canvas not found for video view");
  }

  go.transform.Rotate(0f, 0f, 180f);
  go.transform.localPosition = Vector3.zero;
  go.transform.localScale = new Vector3(4.5f, 3f, 1f);

  return go.AddComponent<VideoSurface>();
}

Open media resources

Call Open to load a local or online media file. You can also set the playback start position. For supported formats, see Supported Formats.

public void OnOpenButtonPress()
{
  var ret = MediaPlayer.Open("Your File Path", 0);
  Debug.Log("Open returns: " + ret);
}

Alternatively, use OpenWithMediaSource to open media resources and configure playback settings, like automatic playback and real-time caching.

Publish the audio and video streams

When joining a channel, set the ChannelMediaOptions as follows:

ChannelMediaOptions options = new ChannelMediaOptions();
// Enable automatic subscription to audio and video streams
options.autoSubscribeAudio.SetValue(true);
options.autoSubscribeVideo.SetValue(true);
options.publishCustomAudioTrack.SetValue(false);
options.publishCameraTrack.SetValue(false);
// Enable publishing audio and video streams from the media player
options.publishMediaPlayerAudioTrack.SetValue(true);
options.publishMediaPlayerVideoTrack.SetValue(true);
// Provide the media player ID
options.publishMediaPlayerId.SetValue(MediaPlayer.GetId());
// Enable audio playback
options.enableAudioRecordingOrPlayout.SetValue(true);
// Set the user role to broadcaster
options.clientRoleType.SetValue(CLIENT_ROLE_TYPE.CLIENT_ROLE_BROADCASTER);

var ret = RtcEngine.JoinChannel(_token, _channelName, 0, options);
this.Log.UpdateLog($"JoinChannel returns: {ret}");

Playback control

Call Play to start playing a local or online media resource.

public void OnPlayButtonPress()
{
  var ret = MediaPlayer.Play();
  Debug.Log($"Play return: {ret}");
}

If you use Open to load a media resource, wait for the OnPlayerSourceStateChanged callback to report the state as PLAYER_STATE_OPEN_COMPLETED before calling Play. If you use OpenWithMediaSource with autoPlay enabled, playback starts automatically.

To loop playback, call SetLoopCount. Set the value to -1 for infinite looping. The default value of 0 means no loop playback.

public void OnPlayButtonPress()
{
  MediaPlayer.SetLoopCount(this.IsLoop() ? -1 : 0);
  var ret = MediaPlayer.Play();
  this.Log.UpdateLog($"Play return: {ret}");
}

To play from a specific position, use Seek. Ensure Seek is called after receiving the PLAYER_STATE_OPEN_COMPLETED state in the OnPlayerSourceStateChanged callback.

If you call Seek while playback is paused, the media remains paused after the call. Call Resume or Play to continue playback.

Call SetPlaybackSpeed to control the playback speed.

public void OnSetPlaybackSpeedButtonPress()
{
  var ret = MediaPlayer.SetPlaybackSpeed(2);
  this.Log.UpdateLog($"SetPlaybackSpeed return: {ret}");
}

Pause, resume, and stop

To control playback, use the following methods:

Pause: Pauses playback.

public void OnPauseButtonPress()
{
  var ret = MediaPlayer.Pause();
  this.Log.UpdateLog($"Pause return: {ret}");
}

Resume: Resumes playback after pausing.

public void OnResumeButtonPress()
{
  var ret = MediaPlayer.Resume();
  this.Log.UpdateLog($"Resume returns: {ret}");
}

Stop: Stops playback. Reopen the media resource to play again.

public void OnStopButtonPress()
{
  var ret = MediaPlayer.Stop();
  this.Log.UpdateLog($"Stop return: {ret}");
}

Adjust the volume

To adjust the local playback volume, call AdjustPlayoutVolume. To adjust the volume of the audio stream sent to the remote end, call AdjustPublishSignalVolume.

var ret = MediaPlayer.AdjustPlayoutVolume(30);
this.Log.UpdateLog($"AdjustPlayoutVolume return: {ret}");

ret = MediaPlayer.AdjustPublishSignalVolume(50);
this.Log.UpdateLog($"AdjustPublishSignalVolume return: {ret}");

Preload media resources

To play multiple media resources continuously, preload the media resources to ensure optimal audience experience when switching resources.

Call PreloadSrc to preload media resources. To load multiple resources, call this method multiple times. Listen to the OnPreloadEvent callbacks to receive preload related events.
```
public void OnPreloadSrcButtonClick()
{

  var nRet = MediaPlayer.PreloadSrc(PRELOAD_URL, 0);
  this.Log.UpdateLog("PreloadSrc: " + nRet);
}
```
Call PlayPreloadedSrc to play the preloaded media resource. After you call this method successfully, you receive a OnPlayerStateChanged callback reporting status PLAYER_STATE_PLAYING.
```
public void OnPlayPreloadButtonClick()
{
  var nRet = MediaPlayer.PlayPreloadedSrc(PRELOAD_URL);
  this.Log.UpdateLog("PlayPreloadedSrc: " + nRet);
}
```
When you no longer need the loaded media resources, call UnloadSrc to release the preloaded resources.
```
var nRet = MediaPlayer.UnloadSrc(PRELOAD_URL);
this.Log.UpdateLog("UnloadSrc: " + nRet);
```

Leave channel

Follow these steps to leave a channel:

Call DestroyMediaPlayer to destroy the media player object.
Call InitEventHandler to unregister the player event observer.
Call LeaveChannel to leave the channel.

Call Dispose to destroy IRtcEngine object and releases resources used by the SDK.

public void OnLeaveChannelButtonPress()
{
  if (RtcEngine == null) return;
  // Destroy the media player object
  if (MediaPlayer != null) RtcEngine.DestroyMediaPlayer(MediaPlayer);
  // Unregister the media player event handler
  RtcEngine.InitEventHandler(null);
  // Leave the channel
  RtcEngine.LeaveChannel();
  // Destroy the engine and release resources
  RtcEngine.Dispose();
  RtcEngine = null;
  MediaPlayer = null;
}

H.263, H.264, H.265, MPEG-4, MPEG-2, RMVB, Theora, VP3, VP8, AVS, WMV

Audio coding formats

WAV, MP2, MP3, AAC, OPUS, FLAC, Vorbis, AMR-NB, AMR-WB, WMA v1, WMA v2

Container formats

WAV, FLAC, OGG, MOV, ASF, FLV, MP3, MP4, MPEG-TS, Matroska (MKV), AVI, ASS, CONCAT, DTS, AVS

Supported protocols

HTTP, HTTPS, RTMP, HLS, RTP, RTSP

Sample project

Agora provides an open source sample project MediaPlayer on GitHub. Download it or view the source code for a more detailed example.

Contact Us

Contact Us