媒体播放器

1 功能简介

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

1.1 应用场景

• 播放测试音频

可以使用媒体播放器播放测试音频，验证音频播放设备是否工作正常。

• 背景音乐

使用媒体播放器播放音乐，媒体播放器支持将播放出来的音频推流出去，让远端听到背景音乐。

• 在线 KTV

主唱使用媒体播放器播放 MV 或其它类型歌曲，主唱随音乐唱歌，通过简单的配置就能让观众欣赏主唱 K 歌。结合媒体次要信息，还可以实现歌词同步显示。

1.2 支持格式

媒体播放器支持 MP3、MP4、FLV、WAV、AAC、M3U8 等格式文件。除了支持播放本地媒体文件，媒体播放器还支持 HTTP/HTTPS 和 RTMP 流媒体协议，在线播放这些格式的文件。

1.3 注意

在 6.5.0 版本 （2021 年 10 月发布）之前的 SDK 默认不包含媒体播放器功能，可联系 ZEGO 技术支持提供。

1.4 媒体播放器业务流程

媒体播放器业务状态流转如下图所示：

1. 启始状态为 Stopped，调用了媒体开始播放接口后，进入 Playing 状态
2. 在 Playing 状态内部存在多个子状态
3. Requesting 表示提交播放请求，但还没有播放成功
4. PlayBegin 表示开始播放了
5. Paused 表示调用了暂停接口，播放暂停了
6. Buffering 表示正在缓冲
7. 当调用了 stop，或是收到 OnPlayEnd、OnPlayError 时，播放结束，进入 Stopped 状态。

2 使用步骤

相关功能的 Demo 源码，请联系 ZEGO 技术支持获取。

为了使用媒体播放器组件，必须引入头文件 zego-api-mediaplayer.h。

2.1 创建播放器

播放器支持两种模式，纯本地播放及推流播放：

enum ZegoMediaPlayerType
{
    ZegoMediaPlayerTypePlayer   = 0,  // 本地播放模式，不会将音频混入推流中，只有调用端可以听到播放的声音。
    ZegoMediaPlayerTypeAux      = 1   // 推流播放模式，会将音频混流推流中，调用端和拉流端都可以听到播放的声音。    
};

调用示例：

MEDIAPLAYER::InitWithType(MEDIAPLAYER::ZegoMediaPlayerType::ZegoMediaPlayerTypePlayer);

可以使用下面接口修改播放器类型：

void SetPlayerType(const ZegoMediaPlayerType type);

2.2 获取播放器状态

获取播放器状态有两种途径，设置事件回调代理，及主动获取接口。

2.2.1 接收播放器事件回调

设置播放器事件回调，就可以接收到开始播放，结束播放，播放错误等事件回调。

void SetEventCallback(IZegoMediaPlayerEventCallback *callback);

回调代理协议为 IZegoMediaPlayerEventCallback：

class IZegoMediaPlayerEventCallback
{
public:
    virtual void OnPlayStart();             // 播放开始
    virtual void OnPlayError(const int errCode) = 0;        // 播放错误
    virtual void OnVideoBegin();            // 开始播放视频
    virtual void OnAudioBegin();            // 开始播放音频
    virtual void OnPlayEnd();               // 播放结束
    virtual void OnSeekComplete(const int state, const long duration);   // 完成快进到指定时刻
    virtual void OnPlayPause();             // 播放暂停
    virtual void OnPlayResume();            // 播放恢复 
    virtual void OnPlayStop();              // 播放结束
    virtual void OnBufferBegin();           // 开始缓冲数据，播放暂停
    virtual void OnBufferEnd();             // 缓冲结束，恢复播放
};

详见 api 文档说明。

2.2.2 获取播放进度

long GetDuration();           // 获取整个文件的播放时长，单位为毫秒
long GetCurrentDuration();    // 获取当前播放的进度，单位为毫秒

2.3 设置视频渲染 View

void SetView(void *view);    // 设置显示视频的 view

2.4 控制播放

2.4.1 开始、停止播放

void Start(const char *path, const bool repeat);  // 开始播放
void Stop();  // 停止播放

播放文件指定，可以是本地文件的路径，也可以是在线文件 url，比如 http://your.domain.com/your-movie.mp4；repeat 参数设置为 true 时，表示开启循环播放。

2.4.2 暂停、恢复播放

void Pause();// 暂停播放
void Resume(); // 恢复播放

2.4.3 设置播放进度

void SeekTo(const long duration); // 设置指定的进度进行播放，单位为毫秒

2.4.4 设置音量

void SetVolume(const int volume);   // 设置音量，范围在0到200，默认值是60

2.4.5 选择音轨

如果资源类型支持多个音轨，可以使用以下接口获取音轨数量信息：

long GetAudioStreamCount();

选择音轨（音轨下标从 0 开始）：

long SetAudioStream(const long streamIndex);

2.5 释放播放器

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

void DestroyPlayer(ZegoMediaPlayerIndex index);

注意： 必须先调用 DestroyPlayer 释放播放器，再将 player 实例置空。

3 进阶：把媒体播放器播放的音视频推流出去

媒体播放器支持直接将播放得到的音频与麦克风音频混音，因此，应用层只需处理视频部分，就可以实现将媒体播放器的音视频推流出去。

3.1 获取播放得到的视频帧

如果播放的是视频文件，而且设置了播放器视频数据回调，就会以一定频率收到相应的数据回调。

// 设置视频数据回调
void SetVideoDataCallback(IZegoMediaPlayerVideoDataCallback *callback, ZegoMediaPlayerVideoPixelFormat format); 

其中 ZegoVideoDataFormat 指定了视频数据的格式：

enum ZegoMediaPlayerVideoPixelFormat
{
    ZegoMediaPlayerVideoPixelFormatUnknown  = 0,
    ZegoMediaPlayerVideoPixelFormatBGRA32   = 4,
    ZegoMediaPlayerVideoPixelFormatRGBA32   = 5,
    ZegoMediaPlayerVideoPixelFormatARGB32   = 6,
    ZegoMediaPlayerVideoPixelFormatABGR32   = 7,
};

回调协议 IZegoMediaPlayerVideoDataCallback 定义为：

class IZegoMediaPlayerVideoDataCallback
{
public:
    /**
    视频帧数据回调，同步回调，不要在回调中处理数据或进行耗时操作
    @param data 视频帧数据
    @param len 视频帧数据长度
    @param format 视频帧格式信息
    */
    virtual void OnPlayVideoData(const char* data, int len, ZegoMediaPlayerVideoDataFormat& format) = 0;
};

3.2 使用外部视频采集接口

外部视频采集接口主要包括 ZegoVideoCaptureFactory、ZegoVideoCaptureDevice ，及对应的组件设置接口 + SetVideoCaptureFactory(ZegoVideoCaptureFactory factory, int channelIndex);。应用层通过这些接口，就可以实现将媒体播放器得到视频帧送进 SDK 编码推流。

4 错误码

5 FAQ

Q1：播放器得到的音频混入推流后，采集音频数据回调 （IZegoAudioRecordCallback void onAudioRecordCallback(byte[] data, int sampleRate, int channelCount, int bitDepth);） 包含播放器的音频吗？

  答：包含。

Q2: 媒体播放器可以播放网络视频吗？

  答：可以，支持播放 HTTP/HTTPS 和 RTMP 流媒体协议的 MP3、MP4、FLV、WAV、AAC、M3U8 等格式的网络资源。

Q3: 媒体播放器支持哪些格式的本地媒体文件？

  答：支持播放 MP3、MP4、FLV、WAV、AAC、M3U8 等格式的本地媒体文件。

Q4：使用播放器混音后，还能使用原有的混音接口吗？

  答：播放器混音推流并不影响原有混音接口功能，二者可以同时并存