logo
ConsoleSign Up
Document
Client API
Server API
Video Call
Android: Java
Introduction
Overview
Product Features
Performance Data
Differences between Video Call SDK and Voice Call SDK
Client SDK
Download SDK
Experience App
Release Notes
Upgrade Guide
Common Error Codes
Quick Start
Example Source Code Running Guide
Integrating the SDK
Implement Video Call
Scenario-based Audio and Video Configuration
Connect to ZEGOCLOUD Document MCP Serverlink
Communication
Room Features
Audio
Video
Live Streaming
Other Features
Best Practices
FAQ
On this page

Media Player

2024-07-27

Feature Overview

The media player component provides the ability to play audio and video media files, and also supports pushing the audio and video data of the played media files to the stream.

Application Scenarios

  • Playing test audio: You can use the media player to play test audio and verify whether the audio playback device is working properly.
  • Playing background music: Use the media player to play music and mix it into the stream so that remote users can hear the background music.
  • Playing video files: Combine with custom video capture functionality to push the video data of media resources to the stream, so remote users can play and watch it.

Supported Formats

The media player supports the following formats and protocols by default:

Video Codec Formats:

  • H263, H264, H265, MPEG4, MJPEG

Audio Codec Formats:

  • AAC, MP2, MP3, FLAC, WMA V1, WMA V2, PCM, AC3, EAC3

Container Formats:

  • WAV, FLAC, MP3, MP4, MOV, MPEG-TS, FLV, Matroska (MKV), AVI, ASF, JPEG

Supported Protocols:

  • HTTP, HTTPS, HLS
Note

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

Example Source Code Download

Please refer to Download Example Source Code to get the source code.

For related source code, please check the files in the "/ZegoExpressExample/Others/src/main/java/im/zego/others/mediaplayer" directory.

Prerequisites

Before implementing media player functionality, please ensure:

Usage Steps

1 Create Media Player

Call the member method createMediaPlayer interface of "ZegoExpressEngine" to create a media player instance. One media player instance can only play one audio or video file. The engine supports creating up to 10 player instances at the same time to achieve the effect of playing multiple media resources simultaneously. If there are already 10 player instances, calling the create player interface again will return null.

  • Call example

    // Create media player instance object, currently supports creating up to 4 instances, will return null if exceeded
ZegoMediaPlayer mediaplayer = mEngine.createMediaPlayer();
if (mediaplayer != null) {
    Log.d(TAG, "createMediaPlayer create sucess");
} else {
    Log.d(TAG, "createMediaPlayer create fail");
}

2 (Optional) Set Event Callbacks for Player

Call the media player's setEventHandler interface to set event callbacks for the player to receive notifications such as "player playback state changed", "player network state updated", "player playback progress changed", etc.

  • Call example

    public class MyIZegoMediaPlayerEventHandler extends IZegoMediaPlayerEventHandler {

    private static final String TAG = "MyIZegoExpressMediaplay";

    @Override
    public void onMediaPlayerStateUpdate(ZegoMediaPlayer mediaPlayer, ZegoMediaPlayerState state, int errorCode) {
        // This callback is called on the UI thread, developers can make UI changes here, such as changes to play buttons
        Log.d(TAG, "onMediaPlayerStateUpdate: state = " + state.value() + ", errorCode = " + errorCode + ", zegoExpressMediaplayer = " + mediaPlayer);
    }

    @Override
    public void onMediaPlayerNetworkEvent(ZegoMediaPlayer mediaPlayer, ZegoMediaPlayerNetworkEvent networkEvent) {
        // This callback is called on the UI thread, developers can make UI changes here, such as friendly prompts for poor network conditions
        Log.d(TAG, "onMediaPlayerNetworkEvent: networkEvent = " + networkEvent.value() + ", zegoExpressMediaplayer = " + mediaPlayer);
    }

    @Override
    public void onMediaPlayerPlayingProgress(ZegoMediaPlayer mediaPlayer, long millisecond) {
        // This callback is called on the UI thread, developers can make UI changes here, such as progress bar changes
        Log.d(TAG, "onMediaPlayerPlayingProgress: millisecond = " + millisecond + ", zegoExpressMediaplayer = " + mediaPlayer);
    }
}

mediaplayer.setEventHandler(new MyIZegoMediaPlayerEventHandler());

3 Load Media File

Call the media player's loadResource to specify the media resource to play, which can be an absolute path to a local resource or a URL to a network resource, such as http://your.domain.com/your-movie.mp4. Users can get the result of loading the file by passing callback parameters.

If users need to load binary audio data, they can call the media player's loadResourceFromMediaData to specify the binary audio data to play. Users can get the result of loading the data by passing callback parameters.

Warning

If the media resource has already been loaded by loadResource or is playing, please call the stop interface to stop playing first, then call the loadResource interface to load the media resource, otherwise it cannot be loaded successfully.

  • Call example

    /**
 * Load media resource
 *
 * Can pass absolute path to local resource or URL to network resource
 * @param path Local resource path or URL to network resource
 * @param callback Notification of resource loading result
 */
zegoMediaplayer.loadResource("sourcePath", new IZegoMediaPlayerLoadResourceCallback() {
    @Override
    public void onLoadResourceCallback(int errorcode) {
        // This callback is called on the UI thread, developers can make UI changes here
        if(errorcode == 0){
            Log.d(TAG, "onLoadResourceCallback: success");
        } else {
            Log.d(TAG, "onLoadResourceCallback: errorcode = " + errorcode);
        }
    }
});
    /**
 * Load binary audio data
 *
 * @param mediaData Binary audio data
 * @param startPosition Specify the progress to start playing, in milliseconds
 * @param callback Notification of resource loading result
 */
zegoMediaplayer.loadResourceFromMediaData(data, position, new IZegoMediaPlayerLoadResourceCallback() {
    @Override
    public void onLoadResourceCallback(int errorcode) {
        // This callback is called on the UI thread, developers can make UI changes here
        if(errorcode == 0){
            Log.d(TAG, "onLoadResourceCallback: success");
        } else {
            Log.d(TAG, "onLoadResourceCallback: errorcode = " + errorcode);
        }
    }
});

4 Playback Control

Playback State Control

Call start, pause, resume, stop to start and stop playback. Once the player's internal state changes, the onMediaplayerStateUpdate callback will be triggered.

Users can also call getCurrentState at any time to get the player's current state.

If enableRepeat is set to "true", the player will automatically replay after finishing playing the file.

  • Call example

    // Set whether to repeat playback
mediaplayer.enableRepeat(true);
// Start playing, need to load resource before playing
mediaplayer.start();
// Pause playback
mediaplayer.pause();
// Resume playback
mediaplayer.resume();
// Stop playback
mediaplayer.stop();

Playback Progress Control

The progress of playing the file will be called back through the onMediaPlayerPlayingProgress method. The default interval for triggering the callback is 1000 ms, which can be changed by setProgressInterval.

Users can also get the current playback progress through getCurrentProgress.

Adjust progress through the seekTo interface.

  • Call example

    // Set playback progress callback interval, in milliseconds, can control the callback frequency of [onMediaPlayerPlayingProgress] through this interface
mediaplayer.setProgressInterval(2000);
// Get current playback progress
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 UI changes here
        if(errorcode == 0){
            Log.d(TAG, "onSeekToTimeCallback: success");
        } else {
            Log.d(TAG, "onSeekToTimeCallback: errorcode = " + errorcode);
        }
    }
});

Playback Speed Control

After loading the resource, users can set the current playback speed through setPlaySpeed.

  • Call example

    // Set 2x speed playback, must be called after loading the resource. Playback speed range is 0.3 ~ 4.0, default is 1.0
mediaplayer.setPlaySpeed(2.0);

Player Audio Control

Get and control playback volume through getPlayVolume and setPlayVolume.

Get and control publishing volume through getPublishVolume and setPublishVolume.

Call muteLocal to control local mute playback.

Call enableAux to mix the file's sound into the currently publishing stream.

Note

If you want to use the audio mixing capability, you must set microphone permissions. If you don't want to record microphone sound, you can mute the microphone through muteMicrophone.

int playVolume = mediaplayer.getPlayVolume();
mediaplayer.setPlayVolume(playVolume / 2);
int publishVolume = mediaPlayer.getPublishVolume();
mediaPlayer.setPublishVolume(publishVolume);
mediaplayer.muteLocal(true);
mediaplayer.enableAux(true);

If you want to get the audio data of the file, you can set the audio frame callback through setAudioHandler.

  • Call example

    // Callback for player to throw audio data, can set this callback to throw the audio data of the media resource file played by the media player
mediaplayer.setAudioHandler(new IZegoMediaPlayerAudioHandler() {
    @Override
    public void onAudioFrame(ZegoMediaPlayer mediaPlayer, ByteBuffer data, int dataLength, ZegoAudioFrameParam param) {
        // Developers can process the thrown audio frame data in this callback, such as local storage, sound effect processing, etc.
        Log.d(TAG, "onAudioFrame: buffer = " + data + ", zegoAudioFrame = " + dataLength);
    }
});

Player Video Control

When playing video resources, use setPlayerCanvas to set the video display view.

  • Call example

    // Set the view for the player to play video
// textureView is an android.view.TextureView instance attached to the UI layout
mediaplayer.setPlayerCanvas(new ZegoCanvas(textureView));

If you want to get the video data of the file, you can set the video frame callback through setVideoHandler.

  • Interface prototype

    /**
 * Set video callback handler
 *
 * Can set this callback to throw the video data of the media resource file played by the media player
 * @param handler Video event callback object for the media player
 * @param format Video frame format of the video data
 */
public void setVideoHandler(IZegoMediaPlayerVideoHandler handler, ZegoVideoFrameFormat format);

  • Call example

    // Callback for player to throw video data, can set this callback to throw the video data of the media resource file played by the media player
mediaplayer.setVideoHandler(new IZegoMediaPlayerVideoHandler(){
    @Override
    public void onVideoFrame(ZegoMediaPlayer mediaPlayer, ByteBuffer[] data, int[] dataLength, ZegoVideoFrameParam param) {
        // Developers can process the thrown video frame data in this callback, such as local storage, video layer mixing, etc.
        Log.d(TAG, "onVideoFrame");
    }
}, ZegoVideoFrameFormat.Unknown);// The second parameter should generally be specified as the platform's default video frame format

Publish the video played by the player

  1. Before publishing the player's video, you need to first set the video frame callback listener through setVideoHandler to get the video frame data thrown by onVideoFrame.

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

Note

When custom capturing data, it is recommended that developers define a "flag" marker:

  • When the onStart callback is triggered, set the "flag" marker to "True", indicating that custom captured video data can start being sent to the SDK.
  • When the onStop callback is triggered, set the "flag" marker to "False", indicating that sending captured video data to the SDK needs to stop.

  1. Developers need to add logic to judge the "flag" in onVideoFrame. When the "flag" is set to "True" (i.e., the onStart callback is triggered), call the sendCustomVideoCaptureRawData method to send the obtained video data to the SDK.

  2. Call startPublishingStream to start publishing. Please refer to "Publish Stream" in Quick Start - Implementation.

Voice Changer

To handle scenarios such as pitch shifting accompaniment in KTV, you can call the media player's enableVoiceChanger interface to implement voice changer functionality. Developers can set the voice changer effect through the pitch parameter "pitch" in the ZegoVoiceChangerParam object. The value range of this parameter is [-12.0, 12.0]. The larger the value, the sharper the voice. Voice changer is disabled by default.

ZegoVoiceChangerParam param = new ZegoVoiceChangerParam()
// Male voice to child voice
param.pitch = 8.0f;
// Male voice to female voice
param.pitch = 4.0f;
// Female voice to child voice
param.pitch = 6.0f;
// Female voice to male voice
param.pitch = -3.0f;
mediaplayer.enableVoiceChanger(ZegoMediaPlayerAudioChannel.ALL, true, param);

5 Destroy Media Player

After using the player, you need to call the destroy interface in time to release the occupied resources.

  • Call example

    // Destroy media player instance object
mEngine.destroyMediaPlayer(mediaplayer);
// When calling the interface to destroy, to avoid memory leaks, developers must manually release references held by the business layer
mediaplayer = null;

FAQ

  1. How to switch playing resources during playback?

First call the player's stop interface, then call the loadResource interface again to load the new resource.

Previous

OBS Streaming with WHIP Protocol

Next

Audio Effect Player

On this page

Back to top