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 the files in the "/ZegoExpressExample/Examples/Others/MediaPlayer" directory.
Prerequisites
Before implementing the media player feature, ensure that:
- A project has been created in the ZEGOCLOUD Console, and a valid AppID and AppSign have been obtained. For details, please refer to Console - Project Information.
- ZEGO Express SDK has been integrated into the project, and basic audio/video stream publishing and playing functionality has been implemented. For details, please refer to Quick Start - Integration and Quick Start - Implementation.
Implementation Steps
1 Create media player
Call the createMediaPlayer interface of IZegoExpressEngine to create a media player instance. One media player instance can only play one audio/video, and the engine supports creating up to 10 players at the same time to achieve the effect of playing multiple files simultaneously. Creating more than 10 will fail, and the interface will return nullptr.
IZegoMediaPlayer* mediaPlayer = engine->createMediaPlayer();
if (mediaPlayer == nullptr) {
printf("Failed to create player");
}2 (Optional) Set event callbacks for the player
Call the media player's setEventHandler interface to set event callbacks IZegoMediaPlayerEventHandler for the player to receive notifications such as "player state changes", "player network state updates", "player playing progress changes", etc.
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 resources
Call the media player's loadResource to specify the media resource to play. It can be an absolute path to a local resource, such as "D:/Zego/your-movie.mp4"; 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.
mediaPlayer->loadResource("sourcePath", [=](int errorCode){
if(errorCode == 0){
printf("the total duration of the file: %lld", mediaPlayer->getTotalDuration());
} else {
print("load resource failed");
}
});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 data by passing callback parameters.
mediaPlayer->loadResourceFromMediaData((unsigned char*)data, dataLength, 0L, [=](int errorCode){
if(errorCode == 0){
printf("the total duration of the file: %lld", mediaPlayer->getTotalDuration());
} else {
print("load resource failed");
}
});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 it cannot be loaded successfully.
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 to get the player's current state at any time.
If enableRepeat is set to "true", the player will automatically replay after finishing playing the file.
mediaPlayer->enableRepeat(true);
mediaPlayer->start();
mediaPlayer->pause();
mediaPlayer->resume();
mediaPlayer->stop();Playback progress control
The progress of playing the file will be callbacked through the onMediaPlayerPlayingProgress method. The default interval for triggering the callback is 1000 ms, which can be changed through setProgressInterval.
Users can also get the current playback progress through getCurrentProgress.
Adjust the progress through the seekTo interface.
mediaPlayer->setProgressInterval(2000);
auto progress = mediaPlayer->getCurrentProgress();
mediaPlayer->seekTo(mediaPlayer->getTotalDuration() / 2, nullptr);Playback speed control
After loading resources, users can set the current playback speed through setPlaySpeed.
// 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 enableAux to mix the file's sound into the stream being published.
Call muteLocal to control local mute playback.
auto 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 specify the audio frame callback IZegoMediaPlayerAudioHandler for the player through the setAudioHandler interface.
// Callback for player throwing audio data
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
When playing video resources, use setPlayerCanvas to set the video display view.
// Fill in Windows window handle
HWND playWND = ...;
ZegoCanvas canvas(playWND);
mediaPlayer->setPlayerCanvas(&canvas);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.
// Callback for player throwing video data
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);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 publishing stream 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 "flag" in onVideoFrame. When "flag" is set to "True" (i.e., when the onStart callback is triggered), call the sendCustomVideoCaptureRawData method to send the obtained video data.
-
Call startPublishingStream to start publishing stream. Please refer to "Publishing Stream" in Quick Start - Implementation.
Voice Changer
When handling scenarios similar to adjusting accompaniment pitch 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 = 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(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);