logo
ConsoleSign Up
Document
Client API
Server API
Video Call
Unity3D: C#
Introduction
Overview
Product Features
Differences Between Video Call SDK and Voice Call SDK
Known Issues and Solutions
Client SDK
Download SDK
Release Notes
Upgrade Guide
Common Error Codes
Quick Start
Example Code Running Guide
Integrate SDK
Implementing Video Call
Scenario-based Audio and Video Configuration
Connect to ZEGOCLOUD Document MCP Serverlink
Communication
Room Features
Audio
Video
Live Streaming
Other Features
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.

Download Example Source Code

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

For related source code, please view files in the "/ZegoExpressExample/Examples/Others/MediaPlayer" directory.

Prerequisites

Before implementing the media player function, please ensure:

Usage Steps

1 Create media player

Call the CreateMediaPlayer interface, a member method 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) {
// sucess
} else {
// fail
}

2 (Optional) Set event callbacks for player

You can set media player callback event delegates to receive notifications such as "player playback state change", "player network state update", "player playback progress change", etc.

  • Call example

    void OnMediaPlayerStateUpdate(ZegoMediaPlayer mediaPlayer, ZegoMediaPlayerState state, int errorCode)
{
    // This callback is called on the UI thread, developers can make UI changes here, such as play button changes
}

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
}

void OnMediaPlayerPlayingProgress(ZegoMediaPlayer mediaPlayer, ulong millisecond)
{
    // This callback is called on the UI thread, developers can make UI changes here, such as progress bar changes
}

mediaplayer.OnMediaPlayerPlayingProgress = OnMediaPlayerStateUpdate;
mediaplayer.OnMediaPlayerPlayingProgress = OnMediaPlayerNetworkEvent ;
mediaplayer.OnMediaPlayerPlayingProgress = OnMediaPlayerPlayingProgress;

3 Load media file

Warning

If the media resource has already been LoadResource loaded or is playing, please call the Stop interface to stop playback first, and then call the LoadResource interface to load the media resource, otherwise the loading will not succeed.

Call the media player's LoadResource to specify the media resource to play. The resource path can be the absolute path of a local resource or the URL of a network resource, such as http://your.domain.com/your-movie.mp4. Users can get the result of loading the file by passing in 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 in callback parameters.

  • Call example

    /**
* Load media resource
*
* Can pass the absolute path of local resources or the URL of network resources
* @param path Local resource path or network resource URL
* @param callback Notification of resource loading result
*/
mediaplayer.LoadResource("sourcePath", (int errorcode)=>{
    // This callback is called on the main thread, developers can make UI changes here
});

/**
* 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
*/
mediaplayer.LoadResourceFromMediaData(data, position, (int errorcode)=>{
    // This callback is called on the UI thread, developers can make UI changes here
});

4 Playback control

Playback state control

  • Play start/stop: After successfully calling loadResource to load the file, you can call Start, Pause, Resume, Stop to start/stop playback. Once the player's internal state changes, the onMediaplayerStateUpdate callback will be triggered.

  • Get current playback state: Users can call GetCurrentState at any time to get the current state of the player.

  • Whether to repeat playback: 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 playback, need to load resource first before playing
mediaplayer.Start();
// Pause playback
mediaplayer.Pause();
// Resume playback
mediaplayer.Resume();
// Stop playback
mediaplayer.Stop();

Playback progress control

  • Player playback progress callback: The progress of playing the file will be called back through the OnMediaPlayerPlayingProgress method. The default interval for triggering the callback is 1000 ms. You can change this interval through SetProgressInterval.

  • Get current playback progress: Users can get the current playback progress through GetCurrentProgress.

  • Adjust playback progress: Adjust the 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
ulong progress = mediaplayer.GetCurrentProgress();
mediaplayer.SeekTo(mediaplayer.GetTotalDuration() / 2, (int errorcode)=>{
    // This callback is called on the UI thread, developers can make UI changes here
});

Playback speed control

Set current playback speed: After loading the resource, users can set the current playback speed through SetPlaySpeed.

  • Call example

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

Player audio control

  • Get and control playback volume: Get and control playback volume through GetPlayVolume and SetPlayVolume.
  • Get and control publishing volume: Get and control publishing volume through GetPublishVolume and SetPublishVolume.
  • Mute local playback: Control local mute playback by calling MuteLocal.
  • Mix the player's sound into the main channel being published: Mix the file's sound into the stream being published by calling EnableAux.
Note

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

  • Call example

    int playVolume = mediaplayer.GetPlayVolume();
// Set player volume to half of the original
mediaplayer.SetPlayVolume(playVolume / 2);
// Enable mixing the resource's sound into the stream being published
mediaplayer.EnableAux(true);
// Enable local mute playback
mediaplayer.MuteLocal(true);

  • Get audio data of file: 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 out audio data, you can set this callback to throw out the audio data of the media resource file played by the media player
mediaplayer.SetAudioHandler((ZegoMediaPlayer mediaPlayer, System.IntPtr data, uint dataLength, ZegoAudioFrameParam param) =>{
    // Developers can process the thrown audio frame data in this callback, such as local storage, sound effect processing, etc.
});

Player video control

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

  • Call example

    // Callback for player to throw out video data, you can set this callback to throw out the video data of the media resource file played by the media player
mediaPlayer.SetVideoHandler((ZegoMediaPlayer mediaPlayer, System.IntPtr[] data, uint[] dataLength, ZegoVideoFrameParam param, string extraInfo)=>{
    // Developers can process the thrown video frame data in this callback, such as local storage, video layer mixing
}, ZegoVideoFrameFormat.ARGB32);// 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 data. For detailed operations, please refer to Custom Video Capture.

Note

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

  • When the OnCustomVideoCaptureStart callback is triggered, set the "flag" marker to "True", indicating that custom captured video data can start being sent to the SDK.
  • When the OnCustomVideoCaptureStop 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 judgment logic for "flag" in OnVideoFrame. When "flag" is set to "True" (i.e., the OnCustomVideoCaptureStart callback is triggered), call the SendCustomVideoCaptureRawData method to send the obtained video data to the SDK.

  2. Call StartPublishingStream to start publishing stream. Please refer to "Publish stream" in Quick Start - Implementation.

Voice changer

When handling scenarios similar to accompaniment pitch shifting in KTV, you can call the media player's SetVoiceChangerParam interface to implement the voice changer function. 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 sound. The default value is "0.0" (i.e., voice changer is disabled).

  • Call example

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

Render video picture

When the player plays video, you need to play the video picture through custom rendering. Refer to the following example code:

  • Call example

    //Use RawImage to render
RawImageCustomVideoSurface rawImageVideoSurface;
//Use Renderer to render
RendererCustomVideoSurface rendererVideoSurface;

rawImageVideoSurface = GameObject.Find("RawImage_MediaPlayer").AddComponent<RawImageCustomVideoSurface>();
rendererVideoSurface = GameObject.Find("Plane_MediaPlayer").AddComponent<RendererCustomVideoSurface>();
// Rotate to the appropriate angle
rendererVideoSurface.transform.Rotate(90.0f, -180.0f, 0.0f);
rendererVideoSurface.transform.localScale = new Vector3(10f, 10f, 10f);

// Listen to video frame data
mediaPlayer.SetVideoHandler((ZegoMediaPlayer mediaPlayer, System.IntPtr[] data, uint[] dataLength, ZegoVideoFrameParam param, string extraInfo) =>
{
    // Use custom rendering to load original video data
    if(rawImageVideoSurface)
    {
        rawImageVideoSurface.LoadNativeVideoRawData(data[0], param.width, param.height, param.strides, param.format);
    }

    //if(rendererVideoSurface)
    //{
    //    rendererVideoSurface.LoadNativeVideoRawData(data[0], param.width, param.height, param.strides, param.format);
    //}
}, ZegoVideoFrameFormat.RGBA32);

5 Destroy media player

After using the player, you need to call the DestroyMediaPlayer 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 the references held by the business layer
mediaplayer = null;

FAQ

How to switch playback resources during playback?

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

Previous

Playing Stream by URL

Next

Audio Effect Player

On this page

Back to top