Media Player
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
If you need support for other formats, please contact ZEGOCLOUD Technical Support.
Download Sample Source Code
Please refer to Download Sample Source Code to get the source code.
For related source code, please check files in the "/lib/topics/OtherFunctions/media_player" directory.
Prerequisites
Before implementing the media player feature, ensure:
- You have created a project in the ZEGOCLOUD Console and applied for a valid AppID and AppSign. For details, please refer to Console - Project Information.
- You have integrated ZEGO Express SDK in your project and implemented basic audio and video publishing and playing features. For details, please refer to Quick Start - Integrating SDK and Quick Start - Implementing Video Call.
Usage Steps
1 Create Media Player
Call the createMediaPlayer method of ZegoExpressEngine to create a media player instance. A 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.
ZegoMediaPlayer? mediaPlayer = await ZegoExpressEngine.instance.createMediaPlayer();
if (mediaplayer != null) {
// createMediaPlayer create sucess
} else {
// createMediaPlayer create fail
}2 (Optional) Set Event Callbacks for Player
Through the media player's onMediaPlayerStateUpdate, onMediaPlayerNetworkEvent, and onMediaPlayerPlayingProgress callbacks to receive notifications of "player playback state changes", "player network state updates", and "player playback progress changes".
// Player playback state callback
ZegoExpressEngine.onMediaPlayerStateUpdate = (ZegoMediaPlayer mediaPlayer, ZegoMediaPlayerState state, int errorCode) {
print("onMediaPlayerStateUpdate: state = $state, errorCode = $errorCode, mediaPlayer index = ${mediaPlayer.getIndex()}");
}
// Player network state callback
ZegoExpressEngine.onMediaPlayerNetworkEvent = (ZegoMediaPlayer mediaPlayer, ZegoMediaPlayerNetworkEvent networkEvent) {
print("onMediaPlayerNetworkEvent: networkEvent = $networkEvent, mediaPlayer index = ${mediaPlayer.getIndex()}");
}
// Player playback progress callback
ZegoExpressEngine.onMediaPlayerPlayingProgress = (ZegoMediaPlayer mediaPlayer, int millisecond) {
print("onMediaPlayerPlayingProgress: millisecond = $millisecond, mediaPlayer index = ${mediaPlayer.getIndex()}");
}3 Load Media File
If the media resource has already been loaded or is currently playing, please call the stop method first to stop playback, then call the loadResource method to load the media resource, otherwise loading will fail.
Call the media player's loadResource to specify the media resource to play. It 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 through the return value of the function.
// Load resource, can pass absolute path of local resource or URL of network resource
zegoMediaplayer.loadResource("sourcePath").then( (ZegoMediaPlayerLoadResourceResult result) {
if(errorcode == 0){
// loadResource success
} else {
// loadResource errorcode: errorcode
}
});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 through the return value of the function.
// Load resource, pass in the binary audio data to be loaded and the starting position
zegoMediaplayer.loadResourceFromMediaData(data, position).then(ZegoMediaPlayerLoadResourceResult result) {
if(errorcode == 0){
// loadResourceFromMediaData success
} else {
// loadResourceFromMediaData errorcode: errorcode
}
});4 Playback Control
Playback State Control
After successfully loading the file by calling loadResource, you can 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 to get the current state of the player at any time.
If enableRepeat is set to "true", the player will automatically replay after finishing playing the file.
// Set whether to repeat playback
mediaplayer.enableRepeat(true);
// Start playback, need to call interface to load media file before playing
mediaplayer.start();
// Pause
mediaplayer.pause();
// Resume
mediaplayer.resume();
// Stop
mediaplayer.stop();Playback Progress Control
The progress of playing the file will be called back through the onMediaPlayerPlayingProgress method. The default callback interval is 1000 ms, which can be changed through setProgressInterval.
In Web, the onMediaPlayerPlayingProgress interface is not currently supported.
Users can also get the current playback progress through getCurrentProgress.
Adjust the progress through the seekTo interface.
// Set playback progress callback interval to 2000 ms
mediaplayer.setProgressInterval(2000);
// Get the player's playback progress, in milliseconds
int progress = await mediaplayer.getCurrentProgress();
// Get the total duration of the currently playing media file, in milliseconds
int totalDuration = await mediaplayer.getTotalDuration();
// Jump to half of the total duration, progress unit is milliseconds
mediaplayer.seekTo(totalDuration / 2).then(ZegoMediaPlayerSeekToResult result){
if(errorcode == 0){
// seekTo success
} else {
// seekTo errorcode: errorcode
}
});Playback Speed Control
After loading the resource, users can set the current playback speed through setPlaySpeed.
// Set the player's playback speed, must be called after loading the resource
// Set 2x speed playback, 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 stream being published.
If you want to use the audio mixing feature, you must set microphone permissions. If you don't want to record microphone sound, you can mute the microphone through muteMicrophone.
// Get the player's current playback volume
int playVolume = await mediaplayer.getPlayVolume();
// Set player volume to half of original
mediaplayer.setPlayVolume(playVolume / 2);
// Get the player's current publishing volume
var publishVolume = await this.mediaPlayer.getPublishVolume();
// Set player publishing volume
mediaPlayer.setPublishVolume(80.0);
// Enable local mute playback
mediaplayer.muteLocal(true);
// Enable mixing the resource's sound into the stream being published
mediaplayer.enableAux(true);Player Video Control
When playing video resources, use setPlayerCanvas to set the video display view.
// textureView is the id obtained through createTextureRenderer or createPlatformView method
mediaplayer.setPlayerCanvas(ZegoCanvas(textureView));Voice Changer
When handling scenarios such as adjusting the pitch of accompaniment in KTV, you can call the media player's enableVoiceChanger interface to implement voice changing functionality. Developers can set the voice changing 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 changing is disabled by default.
In Web, the enableVoiceChanger interface is not currently supported.
/**
* 8.0 // Male voice to child voice
* 4.0 // Male voice to female voice
* 6.0 // Female voice to child voice
* -3.0 // Female voice to male voice
*/
ZegoVoiceChangerParam param = ZegoVoiceChangerParam(6.0)
mediaplayer.enableVoiceChanger(ZegoMediaPlayerAudioChannel.All, true, param);5 Destroy Media Player
After using the player, you need to call the destroyMediaplayer interface in time to release occupied resources.
ZegoExpressEngine.instance.destroyMediaPlayer(mediaplayer);
mEngine.destroyMediaPlayer(mediaplayer);FAQ
How to switch playback resources during playback?
First call the player's stop interface, then call the loadResource interface again to load the new resource.