Looking for the previous docs site? Visit the legacy docs homepage. (opens in a new tab)
Agora Docs

Stream media to a channel

Updated

Play local or online media files locally or to remote users in an Agora 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 Video Calling 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:

  1. 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();

  2. Register the playback observer using registerPlayerSourceObserver.

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

  3. Register media player observer callbacks based on your needs:

    • 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);

  4. Open a media file:

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

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

  mediaPlayer.open(url, 0);
};

  5. 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
};

  6. 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

Contact Us

+1 (408) 879-5885

2804 Mission College Blvd.Santa Clara, CA, USA 95054

AgoraCopyright © 2026 AgoraAll rights reserved