Voice Call
  • iOS
  • Android : Java
  • Web
  • Flutter
  • React Native
  • Electron
  • Unity3D
  • Cocos Creator
  • Windows
  • macOS
  • Linux
  • Overview
  • Develop your app
    • Quick start
    • Enhance basic feature
      • Use Tokens for authentication
      • Set up common audio config
      • Check the room connection status
  • Best practices
    • Implement a live audio room
  • Upgrade using advanced features
    • Advanced features
      • Configure the audio
        • Beautify & Change the voice
      • Improve audio quality
        • Test network and devices in advance
        • Monitor streaming quality
        • Visualize the sound level
      • Message signaling
        • Broadcast real-time messages to a room
        • Convey extra information using SEI
        • Quotas and limits
      • Play media files
        • Play media files
        • Play sound effects
      • Mix the streams
      • Record media data
      • Encrypt the streams
    • Distincitve features
      • Join multiple rooms
      • Customize the audio
      • Play streams via URL
      • Low-latency live streaming
  • Resources & Reference
    • SDK
    • Sample code
    • API reference
    • Debugging
    • FAQs
    • Key concepts
  • Documentation
  • Voice Call
  • Upgrade using advanced features
  • Advanced features
  • Play media files
  • Play media files

Media player

Last updated:2023-04-09 15:53

Introduction

The media player component of the ZEGO Express SDK provides the following abilities:

  • Play audio and video files.
  • Simultaneously stream out the audio/video data of the media file being played.

This document describes how to use the media player in your apps.

Use cases

You can use the media player for various use cases. The following are some typical examples:

  • Verify audio output device: play test audio to verify that the audio playback device is working correctly.
  • Play background music: play and stream audio to remote users so that you can add background music to your live stream.

Supported media file formats

The media player supports MP3, MP4, FLV, WAV, AAC, M3U8 formats.

If you need support for other formats, contact ZEGOCLOUD Technical Support.

Supported protocols

The media player supports playing media resources from the internet over the HTTP or HTTPS protocol.

Prerequisites

Before you begin to use the media player in your project, make sure you complete the following steps:

  • ZEGO Express SDK has been integrated into the project to implement basic real-time audio and video functions. For details, please refer to Quick start .
  • A project has been created in ZEGOCLOUD Console and applied for a valid AppID and AppSign. For details, please refer to Console - Project Information .

Create media player instances

To create a media player instance, call the createMediaPlayer method of the engine (the ZegoExpressEngine instance you create when initializing the SDK).

A media player instance can only play one audio and video source at a time. You can create up to 4 media player instances to play multiple media resources at the same time. If there are already 4 media player instances running, calling this method will return null.

  • Function prototype:

    /**
     * Create a media player instance
     *
     * The ZegoExpressEngine class supports up to 4 media player instances. If there are already 4 media player instance running, calling this method returns `null`.
     * @return: The returned media player instance. 
     */
    public ZegoMediaPlayer createMediaPlayer();
  • Sample code:

    ZegoMediaplayer mediaplayer = mEngine.createMediaPlayer();
    if (mediaplayer != null) {
        Log.d(TAG, "createMediaPlayer sucess.");
    } else {
        Log.d(TAG, "createMediaPlayer failed.");
    }

Optional: Listen for and handle media player events

Set up an event handler for the media player Call the media player's [`setEventHandler`\|_blank](/article/api?doc=express_video_sdk_API~Java_android~class~im-zego-zegoexpress-zego-media-player#set-event-handler) method to set up an event handler to listen for and handle various media player events, such as changes in the media player's current state, playback progress, and network status.
  • Function prototype:

    public abstract class IZegoMediaPlayerEventHandler {
    
        public void onMediaPlayerStateUpdate(ZegoMediaPlayer mediaPlayer, ZegoMediaPlayerState state, int errorCode){
    
        }
    
        public void onMediaPlayerNetworkEvent(ZegoMediaPlayer mediaPlayer, ZegoMediaPlayerNetworkEvent networkEvent){
    
        }
    
        public void onMediaPlayerPlayingProgress(ZegoMediaPlayer mediaPlayer, long millisecond){
    
        }
    
    }
  • Sample code:

    public class MyIZegoMediaPlayerEventHandler extends IZegoMediaPlayerEventHandler {
    
        private static final String TAG = "MyIZegoExpressMediaplay";
    
        @Override
        public void onMediaPlayerStateUpdate(ZegoMediaPlayer mediaPlayer, ZegoMediaPlayerState state, int errorCode) {
            // This event callback is triggered on the UI thread. You can make corresponding UI changes here. For example, to refresh the Play button.
            Log.d(TAG, "onMediaPlayerStateUpdate: state = " + state.value() + ", errorCode = " + errorCode + ", zegoExpressMediaplayer = " + mediaPlayer);
        }
    
        @Override
        public void onMediaPlayerNetworkEvent(ZegoMediaPlayer mediaPlayer, ZegoMediaPlayerNetworkEvent networkEvent) {
            // This event callback is triggered on the UI thread. You can make corresponding UI changes here. For example, to prompt the user about the current network condition.
            Log.d(TAG, "onMediaPlayerNetworkEvent: networkEvent = " + networkEvent.value() + ", zegoExpressMediaplayer = " + mediaPlayer);
        }
    
        @Override
        public void onMediaPlayerPlayingProgress(ZegoMediaPlayer mediaPlayer, long millisecond) {
            // This event callback is triggered on the UI thread. Developers can make corresponding UI changes here. For example, to refresh the playback progress bar.
            Log.d(TAG, "onMediaPlayerPlayingProgress: millisecond = " + millisecond + ", zegoExpressMediaplayer = " + mediaPlayer);
        }
    }
    
    mediaplayer.setEventHandler(new MyIZegoMediaPlayerEventHandler());

Load a media resource

  • Before you play a media resource, call the media player's loadResource method to load the resource first. According to the actual situation, you can pass the absolute path of a local resource or the URL (for example, http://your.domain.com/your-movie.mp4) of a network resource to the path parameter. To obtain the result of the resource loading, pass in a callback parameter.

  • If you want to play a binary audio, call the loadResourceFromMediaData method the load the audio resource. To obtain the result of the resource loading, pass in a callback parameter.

If you are playing the media files loaded before, call the stop method to stop playing first, and then call the loadResource method to load the media resource; Otherwise, the loading operation will fail.

  • Function prototype:

    /**
     * Load a media resource
     *
     * @param path: The absolute path to a local resource or the URL of a network resource.
     * @param callback: The callback to report the result of loading the media resource.
     */
    public void loadResource(String path, IZegoMediaPlayerLoadResourceCallback callback);
    /**
     * Load a binary audio resource. 
     *
     * @param [mediaData] is the binary audio resource.
     * @param [startPosition] is the starting position, which can be used to specify the playback progress. Unit: ms 
     * @param [callback] refers to the result of the resource loading.
     */
    public abstract void loadResourceFromMediaData(byte[] mediaData, long startPosition, IZegoMediaPlayerLoadResourceCallback callback);
  • Sample code:

    zegoMediaplayer.loadResource("sourcePath", new IZegoMediaPlayerLoadResourceCallback() {
        @Override
        public void onLoadResourceCallback(int errorcode) {
            // This event callback is called on the UI thread. Developers can make corresponding UI changes here.
            if(errorcode == 0){
                Log.d(TAG, "onLoadResourceCallback: success");
            } else {
                Log.d(TAG, "onLoadResourceCallback: errorcode = " + errorcode);
            }
        }
    });
    zegoMediaplayer.loadResourceFromMediaData(data, position, new IZegoMediaPlayerLoadResourceCallback() {
        @Override
        public void onLoadResourceCallback(int errorcode) {
            // Update the application UI accordingly.
            if(errorcode == 0){
                Log.d(TAG, "onLoadResourceCallback: success");
            } else {
                Log.d(TAG, "onLoadResourceCallback: errorcode = " + errorcode);
            }
        }
    });

Control the playback

Control the playback status

mediaplayer_state

Call the media player's methods start, pause, resume, and stop to control the playback.

When you execute these operations, the internal state of the media player changes accordingly, and the onMediaPlayerStateUpdate callback will be triggered.

You can also call the media player's getCurrentState method to get the current state of the media player at any time.

If you set enableRepeat to true, the media player will automatically repeat playing the loaded media resource.

  • Function prototype:

    /**
     * Whether to repeat playing the media resource
     *
     * @param enable: The repeat flag, defaults to false.
     */
    public void enableRepeat(boolean enable);
    
    /**
     * Start the playback (the media resource needs to be loaded first)
     *
     */
    public void start();
    
    /**
     * Pause the playback
     *
     */
    public void pause();
    
    /**
     * Resume the playback
     *
     */
    public void resume();
    
    /**
     * Stop the playback
     *
     */
    public void stop();
  • Sample code:

    mediaplayer.enableRepeat(true);
    mediaplayer.start();
    mediaplayer.pause();
    mediaplayer.resume();
    mediaplayer.stop();

Control the playback progress

The playback progress can be obtained through the callback onMediaPlayerPlayingProgress, which is triggered at an interval of 1,000 ms by default. You can change the callback interval by calling the media player's setProgressInterval.

You can also call the media player's getCurrentProgress method to get the current playback progress.

To adjust the playback progress, call the media player's seekTo method with the target time point.

  • Function prototype:

    /**
     * Set the playback progress callback interval
     *
     * The playback progress callback interval controls the frequency at which the callback [onMediaPlayerPlayingProgress] is called. The default callback interval is 1,000 ms. If it is set to 0, the callback is stopped. 
     * @param millisecond: The playback progress callback interval in milliseconds.
     */
    public void setProgressInterval(long millisecond);
    
    /**
     * Get the current playback progress
     *
     */
    public long getCurrentProgress();
  • Sample code:

    mediaplayer.setProgressInterval(2000);
    long progress = mediaplayer.getCurrentProgress();
    mediaplayer.seekTo(mediaplayer.getTotalDuration() / 2, new IZegoMediaPlayerSeekToCallback(){
        @Override
        public void onSeekToTimeCallback(int errorcode) {
            // This callback is triggered on the UI thread. You can make corresponding UI changes here.
            if(errorcode == 0){
                Log.d(TAG, "onSeekToTimeCallback: success");
            } else {
                Log.d(TAG, "onSeekToTimeCallback: errorcode = " + errorcode);
            }
        }
    });

Control the playback speed

After you loaded the resource, you can call the setPlaySpeed method to set the playback speed.

  • Function prototype:

    /**
     * Set the playback speed.
     *
     * Version supported: 2.12.0 or later
     * Description: Used for setting the playback speed.
     * Execution time: After you loaded the resource.
     * Restrictions: None
     * API related: You can load the resource by calling the [loadResource] method.
     *
     * @param [speed] is the playback speed. Range from 0.5 -2.0. The default value is 1.0
     */
    public abstract void setPlaySpeed(float speed);
  • Sample code:

    // Set the playback speed to double-speed (2.0).
    mediaplayer.setPlaySpeed(2.0);

Control the audio

To get the local playback volume, call the media player's getPlayVolume method.

To set the local playback volume, call the media player's setPlayVolume method.

To get the volume of the audio being streamed out, call the media player's getPublishVolume method.

To set the volume of the audio being streamed out, call the media player's setPublishVolume method.

To mix the audio of the media resource being played into the stream being published, call the media player's enableAux method.

If you want to use the Audio Mixing capability, you must Add Microphone permissions. If you don’t want to Record the Microphone sound, you can mute the Microphone via muteMicrophone.

To mute or unmute the local playback, call the media player's muteLocal method. This doesn't affect the audio being published out simultaneously.

int playVolume = mediaplayer.getPlayVolume();
mediaplayer.setPlayVolume(playVolume / 2);
mediaplayer.muteLocal(true);
mediaplayer.enableAux(true);

If you want to obtain the audio data of the media file being played, do the following:

  1. Call the media player's setAudioHandler method to set up an audio event callback handler for the media player.
  2. Listen for the onAudioFrame callback to obtain the audio frame data the media player sends out.
  • Function prototype:

    /**
     * Set up an audio event callback handler for the media player.
     *
     * By setting up this handler, you can obtain the audio frame data of the media file being played through the callback onAudioFrame.
     * @param handler: The audio event handler of the media player.
     */
    public void setAudioHandler(IZegoMediaPlayerAudioHandler handler)
  • Sample code:

    // Set up an audio event callback handler for the media player.
    mediaplayer.setAudioHandler(new IZegoMediaPlayerAudioHandler() {
        @Override
        public void onAudioFrame(ZegoMediaPlayer mediaPlayer, ByteBuffer data, int dataLength, ZegoAudioFrameParam param) {
            // Process the audio frame data the media player sends out. For example, you can save the audio data to a local file, perform sound effect processing, etc.
            Log.d(TAG, "onAudioFrame: buffer = " + data + ", zegoAudioFrame = " + dataLength);
        }
    });

Use the voice changer

In online karaoke use cases, if you need to change the pitch of the accompaniment, you can call the media player’s setVoiceChangerParam method to do so. By changing the value of the ZegoVoiceChangerParam parameter, you can raise or lower the pitch as needed. The value range of this parameter is [-12.0, 12.0]. As you increase the value, the pitch gets higher. The default value is 0.0, which means the voice changer is turned off.

ZegoVoiceChangerParam param = new ZegoVoiceChangerParam()
param.pitch = 8.0f; /** Change an adult male voice into a child's voice. */
param.pitch = 4.0f; /** Change an adult male voice into an adult female voice. */
param.pitch = 6.0f; /** Change an adult female voice into a child's voice. */
param.pitch = -3.0f; /** Change an adult female voice into an adult male voice. */
mMediaplayer.setVoiceChangerParam(ZegoMediaPlayerAudioChannel.ALL, voiceChangerParam);

Destroy the media player instance

When a media player instance is no longer required, destroy it in time to release the occupied resources.

  • Function prototype:

    /**
     * Destroy a media player instance
     *
     */
    public void destroyMediaPlayer();
  • Sample code:

    mediaplayer.destroyMediaPlayer();
    // When calling this method, you must manually release the object references used at the business layer to avoid memory leak.
    mediaplayer = null;

FAQ

  1. How to switch media resources during playback?

    First, call the media player's stop method, and then call the media player's loadResource method to load the new resource.

Page Directory