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.
Usage Steps
1 Create Media Player
Call the createMediaPlayer interface of ZegoExpressEngine to create a media player instance. One media player instance can only play one audio/video file. The engine supports creating up to 10 players at the same time to achieve the effect of playing multiple files simultaneously. If more than 10 are created, the creation will fail and the interface will return nullptr.
IZegoMediaPlayer* mediaPlayer = engine->createMediaPlayer();
if (mediaPlayer == nullptr) {
printf("Failed to create player");
}2 (Optional) Set Event Callback for Player
Call the media player's setEventHandler interface to set the event callback IZegoMediaPlayerEventHandler for the player to receive notifications such as player playing state change, player network state update, player playing progress change, etc.
// Please note, do not call any SDK interfaces in the SDK callback thread, you need to manually switch to another thread, otherwise a deadlock will occur
class MyMediaPlayerEventHandler: public IZegoMediaPlayerEventHandler{
public:
// Player playing state change and event callback
void onMediaPlayerStateUpdate(IZegoMediaPlayer* mediaPlayer, ZegoMediaPlayerState state, int errorCode) override{
printf("currentState: %d", state);
}
// Player network state event callback
void onMediaPlayerNetworkEvent(IZegoMediaPlayer* mediaPlayer, ZegoMediaPlayerNetworkEvent networkEvent) override {
printf("networkEvent: %d", networkEvent);
}
// Player playing progress callback
void onMediaPlayerPlayingProgress(IZegoMediaPlayer* mediaPlayer, unsigned long long millisecond) override {
printf("currentProgress:%lld", millisecond);
}
}
auto eventHandler = std::make_shared<MyMediaPlayerEventHandler>();
mediaPlayer->setEventHandler(eventHandler);3 Load Media Resource
Call the media player's loadResource to specify the media resource to play. It can be the absolute path of a local resource, such as D:/Zego/your-movie.mp4, 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 the media resource has already been loadResource or is playing, please call the stop interface to stop playing first, and then call the loadResource interface to load the media resource, otherwise the loading will fail.
// Load resource, can pass absolute path of local resource or URL of network resource
mediaPlayer->loadResource("sourcePath", [=](int errorCode){
if(errorCode == 0){
printf("the total duration of the file: %lld", mediaPlayer->getTotalDuration());
} else {
printf("load resource failed");
}
});4 Playback Control
Playing State Control
After calling loadResource to successfully load the file, 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 at any time to get the player's current state.
If enableRepeat is set to true, the player will automatically replay the file after playing it.
// Set whether to repeat playback
mediaPlayer->enableRepeat(true);
// Start playing, need to call the interface to load media file before playing
mediaPlayer->start();
// Pause
mediaPlayer->pause();
// Resume
mediaPlayer->resume();
// Stop
mediaPlayer->stop();Playing 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 playing progress through getCurrentProgress
Adjust the progress through the seekTo interface.
// Set playing progress callback interval to 2000 ms
mediaPlayer->setProgressInterval(2000);
// Get the player's playing progress, in milliseconds
auto progress = mediaPlayer->getCurrentProgress();
// Jump the playing progress to half of the total duration, the unit of progress is milliseconds
mediaPlayer->seekTo(mediaPlayer->getTotalDuration() / 2, nullptr);Player Audio Control
Get and control playing volume through getPlayVolume and setPlayVolume.
Get and control publishing volume through getPublishVolume and setPublishVolume.
Call enableAux to mix the file's sound into the stream being published.
Call muteLocal to control local mute playback.
// Get the player's current playing volume
auto playVolume = mediaPlayer->getPlayVolume();
// Set player volume to half of the original
mediaPlayer->setPlayVolume(playVolume / 2);
// Get the player's current publishing volume
int publishVolume = mediaPlayer->getPublishVolume();
// Set player publishing volume
mediaPlayer->setPublishVolume(publishVolume);
// Enable mixing the resource's sound into the stream being published
mediaPlayer->enableAux(true);
// Enable local silent playback
mediaPlayer->muteLocal(true);If you want to get the audio data of the file, you can specify the audio frame callback IZegoMediaPlayerAudioHandler for the player through the setAudioHandler interface.
// Callback for player throwing audio data
// Please note, do not call any SDK interfaces in the SDK callback thread, you need to manually switch to another thread, otherwise a deadlock will occur
class MyAudioHandler: public IZegoMediaPlayerAudioHandler {
public:
virtual void onAudioFrame(IZegoMediaPlayer* /*mediaPlayer*/, const unsigned char* /*data*/, unsigned int /*dataLength*/, ZegoAudioFrameParam /*param*/) {
}
};
auto audioHandler = std::make_shared<MyAudioHandler>();
mediaPlayer->setAudioHandler(audioHandler);Player Video Control
If you want to get the video data of the file, you can specify the video frame callback IZegoMediaPlayerVideoHandler for the player through the setVideoHandler interface.
// Set callback for player video data
// Please note, do not call any SDK interfaces in the SDK callback thread, you need to manually switch to another thread, otherwise a deadlock will occur
class MyVideoHandler: public IZegoMediaPlayerVideoHandler {
public:
void onVideoFrame(IZegoMediaPlayer* /*mediaPlayer*/, const unsigned char** /*data*/, unsigned int* /*dataLength*/, ZegoVideoFrameParam /*param*/) {
}
};
auto videoHandler = std::make_shared<MyVideoHandler>();
mediaPlayer->setVideoHandler(videoHandler);The SDK currently does not support video rendering on the Linux platform. Users can implement custom rendering after obtaining the video data.
Publish the Video Played by the Player
-
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.
-
Use custom method to capture video and mix the obtained video data into the published data. For detailed operations, please refer to Custom Video Capture .
When custom capturing data, it is recommended that developers define a flag marker themselves:
-
Developers need to add judgment logic for
flagin onVideoFrame. Whenflagis set toTrue(i.e., the onStart callback is triggered), call the sendCustomVideoCaptureRawData method to send the obtained video data to the SDK. -
Call startPublishingStream to start publishing stream. Please refer to "Publishing Stream" in Quick Start - Implementation Flow.
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 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. Voice changer is disabled by default.
ZegoVoiceChangerParam param = 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->enableVoiceChanger(ZEGO_MEDIA_PLAYER_AUDIO_CHANNEL_ALL, true, param);5 Destroy Media Player
After using the player, you need to call the destroyMediaPlayer interface in time to release the resources occupied by the player.
engine->destroyMediaPlayer(mediaPlayer);FAQ
How to switch playing resources during playback?
First call the player's stop interface, and then call the loadResource interface again to load the new resource.