数据流录制 Beta
  • 平台类型
  • 框架 / 引擎
  • iOS
  • Android
  • macOS
  • Windows
  • Linux
  • Web
  • 小程序

回放实现流程

更新时间:2021-08-31 18:02

1 概念解释

  • ZegoRecorderPlayback SDK:ZEGO 数据流录制回放的客户端 SDK。
  • ZegoWhiteboardView SDK:ZEGO 互动白板共享对应的客户端 SDK。
  • ZegoDocsView SDK:ZEGO 文件共享服务对应的客户端 SDK。
  • Express-Video SDK:ZEGO 实时音视频服务对应的客户端 SDK。

2 回放实现流程图

/Pics/ZegoRecorderPlayback/playbackImplementation.png

以上流程图展示了回放功能的实现流程,其中内部实现逻辑如下:

  1. 客户端向 ZEGO 数据流录制服务发送请求回放信息。
  2. 客户端根据得到的回放信息,向 ZegoRecorderPlayback SDK 发送请求信息。
  3. SDK 访问数据流录制后台服务,下载到媒体文件(包含音视频流、白板流、文件流、自定义信令流等)。
  4. 客户端开始播放。
  5. 客户端收到由 ZegoRecorderPlayback SDK 抛出的、音视频流开始播放的回调。
  6. 客户端创建视频播放的 View、并设置给 ZegoRecorderPlayback SDK,SDK 会将音视频画面渲染到指定的 View 上。
  7. 客户端收到由 ZegoWhiteboardView SDK 抛出 onWhiteboardAdded 白板新增的回调。
  8. 客户端收到 ZegoRecorderPlayback SDK 抛出布局更新的回调,并更新各个窗口的大小以及位置。
  9. 在 UI 界面播放出媒体资源。

3 前提条件

4 使用步骤

本节介绍如何使用 ZegoRecorderPlayback SDK 实现基本的录制回放功能。

4.1 初始化 SDK

  • 在初始化本功能组件前,请先确保 Express-Video SDK 已初始化成功,并且和当前录制任务是在同一开发环境下。
  • 如果有录制白板文件,也需要先将 ZegoWhiteboardView SDK、ZegoDocsView SDK 初始化成功。

创建 ZegoRecorderPlayback 对象,并调用 init 接口初始化该对象。

/** 定义 SDK ZegoRecordPlayback 对象 */
ZegoRecorderPlayback recorderPlayback = new ZegoRecorderPlayback();

/** 初始化SDK */
recorderPlayback.init();

/** 设置SDK日志输出路径,以下代码示例为输出到 sdcard/Android/data/您的应用package名称/files/zegologs 路径下 */
recorderPlayback.setLogFolderPath(context.getExternalFilesDir(null).getAbsolutePath() + File.separator + "zegologs");

4.2 监听事件回调信息

开发者可以通过设置以下回放事件的回调监听,接收加载资源完成、开始回放,结束回放,回放错误、布局变更、自定义信令回调、音视频流、白板流等事件的回调通知。

/** 监听播放器事件,包含文件白板流信息,音视频流信息 */
recorderPlayback.setPlaybackPlayerEventCallback(new IZegoPlaybackPlayerEventCallback() {
    /**
     * 加载录制信息完成的回调,用户只有在加载成功后,才能调用开始播放 (start) 接口
     * @param error 0 -> 代表成功
     */
    @Override
    public void onLoadComplete(int error, long duration) {
        //加载成功  
        if (error == 0) {       
            //开始播放
            recorderPlayback.start();
        } else { 
            //加载失败
        }    
    }

    /**
     * 收到白板流的切换通知
     * 如果在录制过程中,切换了白板,那么在回放时,将会收到 `onWhiteboardSwitch` 接口的回调通知。开发者需要根据回调信息中的白板 ID,在收到此通知时将 ZegoWhiteboardView SDK 中对应的白板视图置于界面上展示。
     * @param whiteboardId 白板ID
     */
    @Override
    public void onWhiteboardSwitch(long whiteboardId) {
    }

    /**
     * 音视频流开始通知
     * 当文件资源中的音视频流进入时,在 `onMediaStreamStart` 的回调里,开发者可以根据宽高比、位置、层级等信息,创建一个用于音视频播放的 TextureView。
     * 
     * 创建完成后,调用 `info.mediaInfo.play` 对象的方法 `setMediaView` 把创建好的 TextureView 设置到 SDK 中。
     * @param info 流信息相关的对象model
     */
    @Override
    public void onMediaStreamStart(ZegoPlaybackStreamInfo info) {
        TextureView textureView = new TextureView(this);
        addView(textureView, FrameLayout.LayoutParams.MATCH_PARENT, FrameLayout.LayoutParams.MATCH_PARENT);
        info.mediaInfo.play.setMediaView(textureView);    
    }

    /**
     * 音视频流结束通知,用户可以在回调中移除相应的 View
     * @param info 流信息相关的对象model
     */
    @Override
    public void onMediaStreamStop(ZegoPlaybackStreamInfo info) {
    }

    /** 省略部分接口回调 */
});

4.3 加载录制文件资源

4.3.1 访问后台服务查询录制的文件资源

通过调用服务端 API 接口 get_play_info 获取回放信息(JSON 格式的字符串),并根据 “task_id”(即开始录制时的 task_id)查询回放信息,详细内容请参考 服务端 API - 获取回放信息

4.3.2 获取文件资源

通过从数据流录制服务 API 获取到的回放信息,调用 load 接口,并通过 onLoadComplete 接口的回调通知,获取到文件资源、回放的总时长等信息。

/** 设置SDK缓存路径,以下代码示例为输出到 sdcard/Android/data/您的应用package名称/files/cache 路径下 */
recorderPlayback.setCacheFolderPath(context.getExternalFilesDir(null).getAbsolutePath() + File.separator + "cache");
/** 设置回放的相对宽高 */
recorderPlayback.setDeviceSize(1280, 720);
/** 用拿到的json加载资源,比如视频流、白板流等 */
recorderPlayback.load(metaJsonInfo);

4.4 播放录制的文件

移动端在进行回放时,Express-Video SDK 的媒体播放器功能将暂时无法使用。开发者可在回放结束后,调用 ZegoRecorderPlayback SDK 的 unInit 接口,即可恢复使用。

4.4.1 开始/暂停/继续/结束回放

调用 startpauseresumestop 接口,来启停回放文件资源。

如果 SDK 播放器状态发生改变,将会触发 onPlayStateUpdate 回调,通知相关的状态消息。开发者也可通过调用 getCurrentState 接口随时获取播放器的当前状态。调用各接口时播放器状态转换请参考下图:

/Pics/ZegoRecorderPlayback/playStateChange.png

回放开始后,回放的进度将通过 onPlayingProgress 回调抛出,开发者可以以此数据更新 UI 进度条。

请确保在 onLoadComplete 回调接口中,判断加载资源成功后,才可以开始播放。

/**
 * 加载录制信息完成的回调,用户只有在加载成功后,才能调用开始播放 (start) 接口
 * @param error 0 -> 代表成功
 */
@Override
public void onLoadComplete(int error, long duration) {
    //加载成功  
    if (error == 0) {       
        //开始播放
        recorderPlayback.start();
    } else { 
        //加载失败
    }    
}

4.4.2 跳转

调用 seekTo 接口,可以实现跳转播放文件资源,其中参数 “timestamp” 表示需要跳转到播放的时间点位置,单位:毫秒(ms)。跳转成功后,将会收到 onSeekComplete 接口的回调通知,开发者可以在此回调更新 UI 进度条。

例如:如果需要跳转到第 50 秒,调用方式为 “seekTo(50000)”。

recorderPlayback.seekTo(timestamp);

4.4.3 音视频流的进入/退出

当文件资源中的音视频流进入时,在 onMediaStreamStart 的回调里,开发者可以根据宽高比、位置、层级等信息,创建一个音视频播放的窗口 View。

创建完成后,调用 info.mediaInfo.play 对象的成员函数 setMediaView 把创建好的 TextureView 设置到 SDK 中。

当音视频流退出时,会收到 onMediaStreamStop 接口的回调通知,此时开发者可以销毁之前创建的窗口 TextureView 实例。

/**
 * 音视频流开始通知
 * 当文件资源中的音视频流进入时,在 `onMediaStreamStart` 的回调里,开发者可以根据宽高比、位置、层级等信息,创建一个用于音视频播放的 TextureView。
 * 
 * 创建完成后,调用 `info.mediaInfo.play` 对象的方法 `setMediaView` 把创建好的 TextureView 设置到 SDK 中。
 * @param info 流信息相关的对象model
 */
@Override
public void onMediaStreamStart(ZegoPlaybackStreamInfo info) {
    TextureView textureView = new TextureView(this);
    addView(textureView, FrameLayout.LayoutParams.MATCH_PARENT, FrameLayout.LayoutParams.MATCH_PARENT);
    info.mediaInfo.play.setMediaView(textureView);    
}

/**
 * 音视频流结束通知,用户可以在回调中移除相应的 View
 * @param info 流信息相关的对象model
 */
@Override
public void onMediaStreamStop(ZegoPlaybackStreamInfo info) {
}

4.4.4 白板文件流的进入/退出

白板文件流信息的回放是通过 ZegoWhiteboardView SDK 和 ZegoDocsView SDK,详细的实现流程请参考 互动白板 - 快速开始 - 实现流程

在开始或结束播放白板文件流信息时,ZegoWhiteboardView SDK 将会收到 onWhiteboardAddedonWhiteboardRemoved 接口的回调通知,开发者需要根据 public void onLayoutChange(ZegoPlaybackStreamInfo[] infoList) 回调通知中返回的布局信息,来调整当前 “whiteboardView” 的布局。

/**
* 收到新增 ZegoWhiteboardView 的回调
* 用户可以将新增的 whiteboardView 添加到视图中
*/
@Override
public void onWhiteboardAdded(ZegoWhiteboardView zegoWhiteboardView) {
    //收到新增白板
    mWhiteboardContainer.onReceiveWhiteboardView(zegoWhiteboardView, (errorCode, newHolder, holder) -> null);
}

/**
* 收到 ZegoWhiteboardView 移除的回调
* 用户可以根据 whiteboardID 移除相应的 ZegoWhiteboardView
*/
@Override
public void onWhiteboardRemoved(long whiteboardID) {
    //收到白板移除消息
    mWhiteboardContainer.removeWhiteboardViewHolder(whiteboardID);
}

4.4.5 白板文件的切换

如果在录制过程中,切换了白板,那么在回放时,将会收到 onWhiteboardSwitch 接口的回调通知。开发者需要根据回调信息中的白板 ID,在收到此通知时将 ZegoWhiteboardView SDK 中对应的白板视图置于界面上展示。

/**
 * 收到白板流的切换通知
 * @param whiteboardId 白板ID
 */
@Override
public void onWhiteboardSwitch ( long whiteboardId){
}

4.4.6 布局的变化

录制时有 5 种布局模式:自定义布局、平分布局、水平布局、垂直布局、悬浮布局。

  • 如果选择后 4 种布局模式,开发者可以在 onLayoutChange 接口回调中,通过参数 “infoList” 获取到布局的变更,更新所有的流窗口的位置。
  • 如果选择自定义布局,那么开发者可以忽略此回调接口,根据自己的业务场景需要,将各路流窗口放置到相应的位置。

当收到此回调通知时,需要遍历 “infoList” 数组,找到每个 ZegoPlaybackStreamInfo 信息中对应的白板 View 或者音视频 View,并调整其布局。

/**
 * 回放布局变化通知,返回每个流的布局
 * @param infoList 每个流的布局model
 */
@Override
public void onLayoutChange (ZegoPlaybackStreamInfo[]infoList){
}

关于布局模式的设置,详细内容请参考 常用功能 - 设置回放布局

5 API 调用时序图

整个回放过程的 API 调用时序如下图:

/Pics/ZegoRecorderPlayback/Android/QuickStarts/playback_Android.png

相关文档

如何回放超过 4 条流?录制超过 4 条流会如何表现?