媒体播放器

功能简介

媒体播放器组件提供播放音视频媒体文件的能力，并且支持将播放的媒体文件的音画数据推流出去。

应用场景

• 播放测试音频：可以使用媒体播放器播放测试音频，验证音频播放设备是否工作正常。
• 播放背景音乐：使用媒体播放器播放音乐并混在流中推送出去，让远端听到背景音乐。
• 播放视频文件：结合自定义视频采集将媒体资源的视频数据推送出去，远端可拉流观看。

支持格式

媒体播放器默认支持格式为：MP3、MP4、FLV、WAV、AAC、M3U8、FLAC。如需支持其它格式，请联系 ZEGO 技术支持。

支持协议

支持 HTTP、HTTPS 协议。

示例源码下载

请参考 下载示例源码 获取源码。

相关源码请查看 “/ZegoExpressExample/Examples/Others/MediaPlayer” 目录下的文件。

前提条件

在实现媒体播放器功能之前，请确保：

• 已在 ZEGO 控制台 创建项目，并申请有效的 AppID 和 AppSign，详情请参考 控制台 - 项目信息。
• 已在项目中集成 ZEGO Express SDK，并实现了基本的音视频推拉流功能，详情请参考 快速开始 - 集成 和 快速开始 - 实现流程。

使用步骤

1 创建媒体播放器

调用 IZegoExpressEngine 的 createMediaPlayer 接口以创建媒体播放器实例。一个媒体播放器实例只能播放一个音视频，引擎同一时间最多支持创建 4 个播放器，以达到同时播放多个文件的效果。超出 4 个则创建失败，接口将返回 nullptr。

IZegoMediaPlayer* mediaPlayer = engine->createMediaPlayer();
if (mediaPlayer == nullptr) {
    printf("创建播放器失败");
}

2 （可选）为播放器设置事件回调

class MyMediaPlayerEventHandler: public IZegoMediaPlayerEventHandler{
public:
    // 播放器播放状态变更及事件回调
    void onMediaPlayerStateUpdate(IZegoMediaPlayer* mediaPlayer, ZegoMediaPlayerState state, int errorCode) override{
        printf("currentState: %d", state);
    }

    // 播放器网络状态事件回调
    void onMediaPlayerNetworkEvent(IZegoMediaPlayer* mediaPlayer, ZegoMediaPlayerNetworkEvent networkEvent) override {
        printf("networkEvent: %d", networkEvent);
    }

    // 播放器播放进度回调
    void onMediaPlayerPlayingProgress(IZegoMediaPlayer* mediaPlayer, unsigned long long millisecond) override {
        printf("currentProgress:%lld", millisecond);
    }
}

auto eventHandler = std::make_shared<MyMediaPlayerEventHandler>();
mediaPlayer->setEventHandler(eventHandler);

3 加载媒体资源

调用媒体播放器的 loadResource 来指定要播放的媒体资源。可以是本地资源的绝对路径，如 “D:/Zego/your-movie.mp4”；也可以是网络资源的 URL，如 “http://your.domain.com/your-movie.mp4”。用户可通过传入回调参数的方式获取加载文件的结果。

mediaPlayer->loadResource("sourcePath", [=](int errorCode){
    if(errorCode == 0){
        printf("the total duration of the file: %lld", mediaPlayer->getTotalDuration());
    } else {
        print("load resource failed");
    }
});

若用户需要加载二进制音频数据时，可调用媒体播放器的 loadResourceFromMediaData 指定要播放的二进制音频数据。用户可通过传入回调参数的方式获取加载数据的结果。

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");
    }
});

4 播放控制

播放状态控制

调用 start、pause、resume、stop 来启停播放。一旦播放器的内部状态改变，onMediaPlayerStateUpdate 回调将会被触发。

用户也可通过调用 getCurrentState 随时获取播放器的当前状态。

如果 enableRepeat 设置为 “true”，则播放器会在播放完文件后自动重播。

mediaPlayer->enableRepeat(true);
mediaPlayer->start();
mediaPlayer->pause();
mediaPlayer->resume();
mediaPlayer->stop();

播放进度控制

播放文件的进度会通过 onMediaPlayerPlayingProgress 方法回调，默认触发回调的间隔是 1000 ms，可通过 setProgressInterval 来更改此间隔。

用户也可通过 getCurrentProgress 来获取当前播放进度。

通过 seekTo 接口来调整进度。

mediaPlayer->setProgressInterval(2000);
auto progress = mediaPlayer->getCurrentProgress();
mediaPlayer->seekTo(mediaPlayer->getTotalDuration() / 2, nullptr);

播放速度控制

加载资源完成后，用户可通过 setPlaySpeed 来设置当前播放速度。

// 设置 2 倍速播放，播放速度范围为 0.3 ~ 4.0，默认为 1.0
mediaPlayer->setPlaySpeed(2.0);

播放器音频控制

通过 getPlayVolume 和 setPlayVolume 获取和控制播放音量。

通过 getPublishVolume 和 setPublishVolume 获取和控制推流音量。

调用 enableAux 可以将文件的声音混入正在推的流中。

调用 muteLocal 可以控制本地静音播放。

auto playVolume = mediaPlayer->getPlayVolume();
mediaPlayer->setPlayVolume(playVolume / 2);
int publishVolume = mediaPlayer->getPublishVolume();
mediaPlayer->setPublishVolume(publishVolume);
mediaPlayer->muteLocal(true);
mediaPlayer->enableAux(true);

如果想获取文件的音频数据，可通过 setAudioHandler 接口来为播放器指定音频帧回调 IZegoMediaPlayerAudioHandler。

// 播放器抛音频数据的回调
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);

播放器视频控制

当播放视频资源时，用 setPlayerCanvas 来设置视频的显示视图。

// 填写 windows 窗口句柄
HWND playWND = ...; 
ZegoCanvas canvas(playWND);
mediaPlayer->setPlayerCanvas(&canvas);

如果想获取文件的视频数据，可通过 setVideoHandler 接口来为播放器指定视频帧回调 IZegoMediaPlayerVideoHandler。

// 播放器抛视频数据的回调
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);

将播放器播放的视频推流出去

1. 将播放器的视频推流出去前，需要先通过 setVideoHandler 设置视频帧回调监听，用于获取 onVideoFrame 抛出的视频帧数据。

2. 使用自定义方式采集视频，并将获取到的视频数据混入推流数据中，详细操作请参考 自定义视频采集 。

3. 开发者需要在 onVideoFrame 中添加对 “flag” 的判断逻辑，当 “flag” 设置为 “True” 时（即触发了 onStart 回调），调用 sendCustomVideoCaptureRawData 方法发送已获取的视频数据。

4. 调用 startPublishingStream 开始推流，请参考 快速开始 - 实现流程 的 “推流”。

变声

处理类似于 KTV 中对伴奏升降调等场景时，可以调用媒体播放器的 enableVoiceChanger 接口来实现变声功能。开发者可通过 ZegoVoiceChangerParam 对象中的音高参数 “pitch” 设置变声效果，该参数取值范围为 [-12.0, 12.0]，值越大声音越尖锐，默认关闭变声。

ZegoVoiceChangerParam param = ZegoVoiceChangerParam();
// 男声变童声
param.pitch = 8.0f; 
// 男声变女声    
param.pitch = 4.0f;  
// 女声变童声   
param.pitch = 6.0f;  
// 女声变男声   
param.pitch = -3.0f;    
mediaPlayer->enableVoiceChanger(ZEGO_MEDIA_PLAYER_AUDIO_CHANNEL_ALL, true, param);

5 销毁媒体播放器

使用完播放器之后，需要及时的调用 destroyMediaPlayer 接口以释放该播放器占用的资源。

engine->destroyMediaPlayer(mediaPlayer);