媒体播放器

1 功能简介

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

1.1 应用场景

• 播放测试音频

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

• 背景音乐

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

• 在线 KTV

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

1.2 支持格式

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

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 技术支持获取。

2.1 创建播放器并初始化

• 接口原型：

/**
 初始化媒体播放器

 @param playerType 播放器类型，ZegoMediaPlayer.PlayerTypePlayer = 0 - 本地播放模式，不会将音频混入推流中，只有调用端可以听到播放的声音；ZegoMediaPlayer.PlayerTypeAux = 1 - 推流播放模式，会将音频混入推流中，调用端和拉流端都可以听到播放的声音。
 @param playerIndex 播放器索引，采用 ZegoMediaPlayer.PlayerIndex 枚举，支持最多四个播放器实例
 */
public void init(int playerType, int playerIndex){}

• 调用示例：

zegoMediaPlayerFirst = new ZegoMediaPlayer();
zegoMediaPlayerSecond = new ZegoMediaPlayer();
...

zegoMediaPlayerFirst.init(ZegoMediaPlayer.PlayerTypePlayer, ZegoMediaPlayer.PlayerIndex.First);

zegoMediaPlayerSecond.init(ZegoMediaPlayer.PlayerTypePlayer, ZegoMediaPlayer.PlayerIndex.Second);
...

• 备注：

1. 在初始化播放器之后可以使用 setPlayerType(int type) 修改播放器类型。
2. 若不需要多实例媒体播放器可直接使用单实例媒体播放器，使用 init(int playerType) 初始化媒体播放器。
3. 如果在未初始化 SDK 之前初始化播放器会报错：

   No implementation found for void com.zego.zegoavkit2.ZegoMediaPlayer.enableEventCallbackNative(boolean, int) (tried Java_com_zego_zegoavkit2_ZegoMediaPlayer_enableEventCallbackNative and Java_com_zego_zegoavkit2_ZegoMediaPlayer_enableEventCallbackNative__ZI)

2.2 监听播放器事件回调

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

public void setEventWithIndexCallback(IZegoMediaPlayerWithIndexCallback callback) {}

回调代理协议请详细查看 IZegoMediaPlayerWithIndexCallback

• 备注：

若是单实例媒体播放器，使用 setCallback(IZegoMediaPlayerCallback) 设置播放器事件回调监听。

2.3 设置视频渲染 View

public void setView(View view); // 设置显示视频的视图 view

2.4 开始播放/停止播放

 public void start(String path, boolean repeat); // 开始播放
 public void stop();  // 停止播放

1. 指定的播放文件可以是本地文件的路径，也可以是在线文件 url，比如 http://your.domain.com/your-movie.mp4；repeat 参数设置为 true 时，表示开启循环播放。
2. 如果播放成功将回调 onPlayStart 事件，如果失败则回调 onPlayError 事件。

2.5 暂停播放/恢复播放

public void pause(); // 暂停播放
public void resume(); // 恢复播放

在开始播放后，可以调用 pause 暂停当前媒体播放，并在成功时回调 onPlayPause 事件；在预加载完成或暂停播放后，可以调用 resume 恢复播放，并在成功时回调 onPlayResume 事件。

2.6 反初始化播放器

和初始化接口对应，在不需要播放器时，应该调用反初始化播放器接口。

/**
 释放播放器
 */
public void uninit();

注意： 必须先调用 uninit 反初始化播放器，再将 player 实例置空。

2.7 更多方法

更多播放器相关的方法，比如获取当前的播放时间、媒体文件的总时长等请查看 ZegoMediaPlayer，根据需要选择使用。

3 进阶：将播放器播放的音视频推流出去

ZegoMediaPlayer 支持将音视频都推流出去，以下分别介绍播放器的音频、视频的推流方式。推流请参考文档：快速开始 - 实现流程 的 “2.3 推流”。

3.1 将音频推流出去

在创建播放器时或者调用 setPlayerType 直接修改播放器类型为 ZegoMediaPlayer.PlayerTypeAux，就可以实现将播放器的音频混音到推流。

3.2 将视频推流出去

要将播放器的视频推流出去，需要使用视频外部采集方式将视频数据混入推流中。

3.2.1 监听播放器视频帧回调

设置播放器播放视频帧回调监听后能获取到视频帧数据和视频帧的格式。

// 播放器视频帧数据回调返回的帧格式为 ARGB32/ABGR32/RGBA32/BGRA32
public void setVideoPlayWithIndexCallback(IZegoMediaPlayerVideoPlayWithIndexCallback callback, int format);   

// 播放器视频帧数据回调返回的帧格式为 I420/NV12/NV21
public void setVideoPlayWithIndexCallback2(IZegoMediaPlayerVideoPlayWithIndexCallback2 callback, int format);

回调代理协议请详细查看 IZegoMediaPlayerVideoPlayWithIndexCallback、IZegoMediaPlayerVideoPlayWithIndexCallback2

视频帧格式请详细查看 ZegoVideoDataFormat

• 备注：

若是单实例播放器请使用 setVideoPlayCallback、setVideoPlayCallback2 设置播放器视频帧的回调监听。

3.2.2 设置视频外部采集工厂

在 init SDK 前，启用 SDK 的视频外部采集功能。示例代码如下：

ZegoExternalVideoCapture.setVideoCaptureFactory(captureFactory, ZegoConstants.PublishChannelIndex.MAIN);

视频外部采集功能的使用方法请参看 进阶功能-视频外部采集，示例代码可参考 互动视频示例 Demo 的 /src/LiveRoomPlayground/videocapture 专题。

3.2.3 开始推流

必须先开始推流，才能将播放器的音视频数据推流出去。如何推流请参考文档：快速开始-推流

3.2.4 向 SDK 传递播放器的视频帧数据

根据设置的视频帧回调，在相应的回调方法中处理视频帧，然后将视频数据通过 ZegoVideoCaptureDevice 中的 onByteBufferFrameCaptured 方法塞给 SDK，实现将播放器的视频推流出去。其中 IZegoMediaPlayerVideoPlayWithIndexCallback 回调的是 RGB 类型视频数据，IZegoMediaPlayerVideoPlayWithIndexCallback2 回调的是 YUV 类型视频数据。

互动视频示例 Demo 的媒体播放器模块示范了单实例播放器向 SDK 传递 RGB 类型的视频帧数据。

4 错误码

播放器 onPlayError 返回的错误码如下：

5 FAQ

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

  答：包含。

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

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

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

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

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

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

Q5: 播放器调用 start() 未开始播放。

  答：如果有调用 load() 则只能通过 resume() 恢复播放，load 之后 调用 start 会被 skip。如果想通过调用 start() 播放，就不能调用 load()。

Q6: 收不到 onPlayError回调

  答：MediaPlayer callback 需要在 init 播放器后设置。

Q7: 播放结束怎么再次播放，而不是让他自动循环播放？

  答：调用 start()，设置非循环播放，每次播放都调用 start()。

Q8: 播放进度 onProcessInterval 没有被回调。

  答：需要设置一下时间间隔 setProcessInterval。

Q9: 我调了 seekTo() 是不是必须用 resume()？

  答：会自动播放，不需要 resume。

Q10: 同一个实例不能 load 两次 url，还是说 load 第二个 url 前必须先调 stop()？

  答：同一个实例 load 一个 url 并播放之后想要再播放另一个 url 需要先 stop 后才能再 load 第二个 url，不能连续 load 两次。

Q11: setEventWithIndexCallback 这个方法设置的回调是所有实例共享的吗？那我调用两次 set，之前的那个还能收到回调吗？

  答：实例无法共享，回调只能设置到对应的实例，可以有两种实现方式：

public class Foo implements IZegoMediaPlayerWithIndexCallback {
    void init() {
        player1.setEventWithIndexCallback(this);
        player2.setEventWithIndexCallback(this);
    }
}
public class Foo2 {
    void init() {
        player1.setEventWithIndexCallback(new IZegoMediaPlayerWithIndexCallback(){});
        player2.setEventWithIndexCallback(new IZegoMediaPlayerWithIndexCallback(){});
    }
}

如果要回调到同一个 callBack，建议采用第一种方式。