Get Started with MediaPlayer Kit

Agora provides Media Player Kit to meet your needs for a media player. The Agora Media Player Kit can achieve a series of functions, for example, they allow you to play media files, to have a full control over the audio and video playback, to synchronously share the media files being played to remote users in the Agora channel, and so on.

This page shows the minimum code you need to play a media file and publish media streams that you play in an Agora channel.

Prerequisites

• Java Development Kit
• Android Studio 3.0 or later
• Android SDK API Level 16 or higher
• A mobile device running Android 4.1 or later

Project Setup

Create an Android project and integrate the Native SDK

For more details on how to create an Android project and integrate the Native SDK, see Get Started with Interactive Live Streaming.

Integrate the Media Player Kit

Choose either of the following methods to integrate the MediaPlayer Kit into your project.

Method 1: Automatically integrate the Media Player Kit with Maven Central

1. To add the Maven Central dependency, add the following lines in /Gradle Scripts/build.gradle(Project: <projectname>):

   buildscript {
     repositories {
         ...
         mavenCentral()
     }
     ...
   }
   
   allprojects {
     repositories {
         ...
         mavenCentral()
     }
   }

   The way to add the Maven Central dependency can be different if you set dependencyResolutionManagement in your Android project.

2. To integrate the Media Player Kit into your Android project, add the following lines in /Gradle Scripts/build.gradle(Module: <projectname>.app). In the following example, 3.6.1.202 refers to a version of the Media Player Kit.

   ...
   dependencies {
   ...
   implementation 'io.agora.rtc:agora-special-full:3.6.1.202.mpk.3'
   }

Method 2: Manually copy the Media Player Kit files

1. Download the Media Player Kit and unzip the download package.

2. Add the following files or subfolders from the libs folder of the download package to the paths of your project.

   File or subfolder	Path of your project
   agora-rtc-sdk.jar file	/app/libs/
   arm64-v8a folder	/app/src/main/jniLibs/
   armeabi-v7a folder	/app/src/main/jniLibs/
   x86 folder	/app/src/main/jniLibs/
   x86_64 folder	/app/src/main/jniLibs/

3. In the /app/src/main/AndroidManifest.xml file, add the following permissions for device access according to your needs:

   <uses-permission android:name="android.permission.INTERNET" />

Implementation

This sections show the code logic of how to play a media file and and publish streams in an Agora channel.

Play media files

Refer to the following steps to play a media file:

Create a player instance
After initialization, create a MediaPlayer object.

MediaPlayer mediaPlayerRtc = new MediaPlayer(mRtcEngine);

If you need to play different media resources at the same time, you need to create multiple instances.

Register a player observer object

1. Implement the IMediaPlayerObserver interface and instantiate a IMediaPlayerObserver object.

2. Call the registerPlayerObserver method in the to register a player observer object, and listen for playback events. You can add the following playback events according to your scenarios:

   mediaPlayer.registerPlayerObserver(new IMediaPlayerObserver() {
   @Override
     // Reports the changes in playback state. 
   public void onPlayerStateChanged(io.agora.mediaplayer.Constants.MediaPlayerState state, io.agora.mediaplayer.Constants.MediaPlayerError error) {
   if (state.equals(PLAYER_STATE_OPEN_COMPLETED)) {
          // The media file is opened and ready to be played.
          mediaPlayer.play();
      }
   }
   
   @Override
    // Reports the current playback progress.
   public void onPositionChanged(long position) {
   }
   @Override
      // Reports the player events.
   public void onPlayerEvent(io.agora.mediaplayer.Constants.MediaPlayerEvent eventCode, long elapsedTime, String message) {
   }
   @Override
    // Occurs each time the player receives the media metadata.
   public void onMetaData(io.agora.mediaplayer.Constants.MediaPlayerMetadataType type, byte[] data) {
   }
   @Override
    // Reports the playback duration that the buffered data can support.
   public void onPlayBufferUpdated(long playCachedBuffer) {
   }
   @Override
    // Reports the events of preloading media resources.
   public void onPreloadEvent(String src, io.agora.mediaplayer.Constants.MediaPlayerPreloadEvent event) {
   }
   @Override
    // The player finishes playing.
   public void onCompleted() {
   }
   @Override
    // Occurs when the token is to expire.
   public void onAgoraCDNTokenWillExpire() {
   
   }
   });

   By listening for these events, you can have greater control over the playback process and enable your app to support data in custom formats (media metadata). If an exception occurs, you can use these event callbacks for troubleshooting.

Preparations for playback

1. Call the setView method to set the render view of the player.

2. Call the setRenderMode method to set the render mode of the player's view.

3. Call the open method to open the media resource. The media resource path can be a network path or a local path. Both absolute and relative paths are supported.

// Creates a SurfaceView object.
SurfaceView surfaceView = new SurfaceView(getApplicationContext());
fl_frame.addView(surfaceView);
mSurfaceHolder = surfaceView.getHolder();
// Registers callback events.
mSurfaceHolder.addCallback(this);
//surfaceCreated(@NonNull SurfaceHolder holder)
// Sets the render view of the player.
mediaPlayer.setView(holder.getSurface());
// Sets the render mode.
mediaPlayer.setRenderMode(PLAYER_RENDER_MODE_FIT);
// Opens a media file.
mediaPlayer.open(url,0);

Play a media file

Call the play method to play a media file.

mediaPlayer.play();

Publish media streams in an Agora channel

Refer to the following steps to join an Agora channel as the host and publish media streams in the channel:

1. Call the create method to create an RtcEngine.
2. Call the setChannelProfile method to set the channel profile to LIVE_BROADCASTING.
3. Call the setClientRole method to set the local user role as the host.
4. Call the joinChannel method to enable the local user to join the channel.
5. Call the publishPlayerVideo to publish video streams in the channel.
6. Call the publishPlayerAudio to publish audio streams in the channel.

engine = RtcEngine.create(context.getApplicationContext(), getString(R.string.agora_app_id), iRtcEngineEventHandler);
engine.setChannelProfile(Constants.CHANNEL_PROFILE_LIVE_BROADCASTING);
engine.setClientRole(IRtcEngineEventHandler.ClientRole.CLIENT_ROLE_BROADCASTER);
int res = engine.joinChannel(accessToken, channelId, "Extra Optional Data", 0, option);
mediaPlayer.publishPlayerPlayerVideo();
mediaPlayer.publishPlayerPlayerAudio();

API documentation

Java API Reference