Real-time Audio
  • Platform
  • Framework / Engine
  • iOS
  • Android
  • macOS
  • Windows
  • Linux
  • Web
  • WeChat Mini Program

Media Player

Update Time:2021-04-15 14:49

1 Introduction

The media player component provides the ability to play audio and video files, and simultaneously stream out the audio/video data of the media file being played.

1.1 Application Scenarios

  • Play test audio: Use the media player to play test audio to verify that the audio playback device is working properly.
  • Play background music: Use the media player to play background music and also stream it out to remote users.
  • Play video files: Use the media player, in combination with the custom video capture module, to play a video file and stream it out to remote users at the same time.

1.2 Support Formats

  • Audio:MP3, WAV, AAC, M4A
  • Video:AVI, MOV, MP4, M4V, FLV, 3GP

1.3 Support Agreements

Supports HTTP and HTTPS protocols.

2 Download the Sample Codes

Please refer to Sample Codes for how to download and run the sample code.

The sample code package contains many code examples of different features of the SDK. Please refer to the source files in the directory "/ZegoExpressExample/Mediaplayer" for the code examples of how to use the APIs of the media player module.

3 Prerequisites

Before implementing the media player functions, please make sure:

  • ZEGO Express SDK has been integrated in the project to realize basic real-time audio and video functions. For details, please refer to Quick Starts.
  • A project has been created in ZEGO Admin Console and a valid AppID and AppSign have been applied. For details, please refer to Console - Project Management.

4 Implementation Steps

4.1 Create a Media Player

Call the member method createMediaPlayer of "ZegoExpressEngine" to create a media player instance. A media player instance can only play one audio and video resource and the engine can support up to 4 media player instances at the same time, which allows you to play multiple media resources simultaneously. If there are already 4 media player instances running, calling this method again will return null.

  • API Function Prototype:

    /**
     * Create a media player instance
     *
     * Currently, a maximum of 4 instances can be created. After that, `null` will be returned.
     * @return: The returned media player instance. `null` will be returned when the maximum number is exceeded.
     */
    public ZegoMediaPlayer createMediaPlayer();
  • API Call Example:

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

4.2 Set up an Event Handler for the Media Player

Call the media player method setEventHandler 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.

  • API 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){
    
        }
    
    }
  • API Call Example:

    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 called on the UI thread. Developers can make corresponding UI changes here. For example, to make a change to 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 called on the UI thread. Developers 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 called on the UI thread. Developers can make corresponding UI changes here. For example, to make a change to the playback progress bar.
            Log.d(TAG, "onMediaPlayerPlayingProgress: millisecond = " + millisecond + ", zegoExpressMediaplayer = " + mediaPlayer);
        }
    }
    
    mediaplayer.setEventHandler(new MyIZegoMediaPlayerEventHandler());

4.3 Load a Media Resource

Call the media player method loadResource to specify the media resource to be played, which can be the absolute path to a local resource or the URL of a network resource (e.g., "http://your.domain.com/your-movie.mp4"). A callback parameter can be passed in to obtain the result of loading the resource.

  • API 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);
  • API Call Example:

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

4.4 Playback Control

4.4.1 Playback Status Control

mediaplayer_state

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

Whenever the internal state of the player changes, the callback onMediaPlayerStateUpdate will be triggered. You can also call the media player method getCurrentState to get the current status of the media player at any time.

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

  • API Function Prototype:

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

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

4.4.2 Playback Progress Control

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

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

By calling the media player method seekTo, you can adjust the playback progress as needed.

  • API 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();
  • API Call Example:

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

4.4.3 Audio Control

Through getPlayVolume and setPlayVolume Get and control the playback volume.

Through getPublishVolume and setPublishVolume Get and control the volume of the push stream.

Call the media player method muteLocal to mute or unmute the local playback.

Call the media player method enableAux to mix the audio data of the media resource being played into the stream being published.

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

If you want to get the audio data of the media file being played, you can call the media player method setAudioHandler to set up an audio event callback handler for the media player, so that the audio frame data can be obtained through the callback onAudioFrame.

  • API 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)
  • API Call Example:

    // 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 data thrown out through the callback here, such as to save the audio data to a local file, perform sound effect processing, etc.
            Log.d(TAG, "onAudioFrame: buffer = " + data + ", zegoAudioFrame = " + dataLength);
        }
    });

4.4.4 Video Control

When you need to play a video resource, you can call the media player method setPlayerCanvas to set the view for displaying the video.

  • API Function Prototype:

    /**
     * Set up the view for displaying the video
     *
     * @param canvas: The canvas object for rendering the video
     */
    public void setPlayerCanvas(ZegoCanvas canvas);
  • API Call Example:

    // textureView is an instance of android.view.TextureView that is attached to the UI layout
    mediaplayer.setPlayerCanvas(new ZegoCanvas(textureView));

If you want to get the video data of the media file being played, you can call the media player method setVideoHandler to set up a video event callback handler for the media player, so that the video data can be obtained through the callback onVideoFrame.

  • API Function Prototype:

    /**
     * Set up a video event callback handler for the media player.
     *
     * By setting up this handler, you can obtain the video data of the media file being played through the callback onVideoFrame.
     * @param handler: The video event handler of the media player.
     * @param format: The video frame format of the video data.
     */
    public void setVideoHandler(IZegoMediaPlayerVideoHandler handler, ZegoVideoFrameFormat format);
  • API Call Example:

    // Set up a video event callback handler for the media player
    mediaplayer.setVideoHandler(new IZegoMediaPlayerVideoHandler(){
        @Override
        public void onVideoFrame(ZegoMediaPlayer mediaPlayer, ByteBuffer[] data, int[] dataLength, ZegoVideoFrameParam param) {
            // Process the audio data thrown out through the callback here, such as to save the audio data to a local file, perform video layer blending, etc.
            Log.d(TAG, "onVideoFrame");
        }
    }, ZegoVideoFrameFormat.Unknown); // Generally, the second parameter should be specified as the default video frame format of the current platform.

4.4.5 Push and stream the video played by the player

  1. Before pushing the video of the player, you need to pass setVideoHandler Set the video frame callback monitor to obtain onVideoFrame The video frame data thrown out.

  2. Use a custom method to capture video and mix the obtained video data into the push stream data. For detailed operations, please refer to Advanced Video Processing - Custom Video Capture.

When customizing data collection, it is recommended that developers define a flag bit:

  • When the onStart callback is triggered, set the "flag" flag to "True", it means that you can start sending the customized video data to the SDK.
  • When the onStop callback is triggered, set the "flag" flag to "False" means that you need to stop sending the collected video data to the SDK.
  1. Developers need to log in onVideoFrame Add the judgment logic of "flag". When "flag" is set to "True" (that is, onStart callback), call sendCustomVideoCaptureRawData method sends the acquired video data to the SDK.

  2. Call startPublishingStream to start streaming, please refer to Publishing Streams.

4.4.6 Voice Changer

When dealing with scenes similar to the rising and falling of accompaniment in KTV, you can call the media player's setVoiceChangerParam interface to realize the voice change function. Developers can use ZegoVoiceChangerParam to set the pitch parameter "pitch" in the object Voice changer effect. The value range of this parameter is [-8.0, 8.0]. The larger the value, the sharper the sound. The default value is 0.0 (i.e., turn off the voice changer).

ZegoVoiceChangerParam param = new ZegoVoiceChangerParam()
param.pitch = 8.0f; /** Male voice becomes child voice */
param.pitch = 4.0f; /** Male voice to female voice */
param.pitch = 6.0f; /** Female voice becomes child voice */
param.pitch = -3.0f; /** Female voice becomes male voice */
mMediaplayer.setVoiceChangerParam(ZegoMediaPlayerAudioChannel.ALL, voiceChangerParam);

4.5 Destroy the Media Player

After using the media player, you need to destroy the media player instance in time to release the occupied resources.

  • API Function Prototype:

    /**
     * Destroy a media player instance
     *
     */
    public void destroyMediaPlayer();
  • API Call Example:

    mediaplayer.destroyMediaPlayer();
    // When calling this method, developers must manually release the object references used in the application's business layer to avoid memory leak.
    mediaplayer = null;

5 API Reference

Method Description
createMediaPlayer Creates a media player instance.
destroyMediaPlayer Destroys a media player instance.

6 FAQ

  1. How to switch media resources during playback?

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