功能概览
合拍是把一段已有素材与实时摄像头画面组合录制的模式:素材作为背景或画中画,人像作为另一路画面,二者按指定布局合成到同一个输出文件。合拍能力由
ITAVEffectManager 提供,通过 TAVRecorder.getEffectManager() 获取。相关接口类
接口类名 | 描述 |
TAVRecorder | 录制入口。 |
ITAVEffectManager | 合拍素材设置、模式切换、播放控制与变换。 |
TAVRecorderConstants | TAVDuetMode、TAVGridQuad 枚举。 |
TAVVideoInfo | 合拍素材信息。 |
TAVDuetMediaReadyListener | 合拍素材准备完成回调。 |
合拍模式
TAVDuetMode 定义四种状态:枚举值 | 说明 |
NONE | 无合拍(取消合拍,恢复普通录制)。 |
SEGMENT_OVERLAY | 分割人像叠加:人像分割后叠加在素材上方,人像可自由拖动,素材作为背景铺满画布。 |
OVERLAY | 素材画中画:不分割人像,人像作为背景铺满画布,素材以画中画显示在左上角,可自由拖动。 |
GRID | 左右/上下合拍:由 TAVGridQuad 决定分屏方向与人像方位。 |
TAVGridQuad 用于 GRID 模式下指定人像所在位置:枚举值 | 说明 |
UNDEFINED | 未指定(默认值)。 |
TOP | 人像在上,素材在下。 |
BOTTOM | 人像在下,素材在上。 |
LEFT | 人像在左,素材在右。 |
RIGHT | 人像在右,素材在左。 |
注意事项
合拍素材类型通过
TAVMediaType 指定,视频与图片的时长语义不同:视频素材返回的 duration 为素材实际时长(微秒);图片素材没有固有时长,返回的 duration 为 Long.MAX_VALUE,录制时长请由业务侧自行控制;path 传空表示清除当前素材但保留合拍模式,此时返回的 duration 为 0。isAutoPlay 为 true 时素材随预览开始播放;若业务需要“先定位再播放”,请传 false 并自行调用 playDuetMedia()。GRID 模式下若 TAVGridQuad 传 UNDEFINED,按上下分屏处理(合拍素材在上、摄像头画面在下),效果与 BOTTOM 相同;如需其他方位请显式指定。合拍布局支持在录制中切换(SDK 未做拦截),但实际业务交互中不建议这么做:切换会触发画面重排,可能出现卡顿与掉帧,建议在两段录制之间切换;另外切换或取消合拍(
NONE)不会回溯修改已录制的片段。使用流程
1. 设置合拍素材
ITAVEffectManager effectManager = recorder.getEffectManager();// 简单用法:素材路径、媒体类型、是否自动播放TAVVideoInfo info = effectManager.setDuetMedia(path, TAVMediaType.VIDEO, true);// 需要感知素材就绪时,使用带回调的重载effectManager.setDuetMedia(path, TAVMediaType.VIDEO, true, new TAVDuetMediaReadyListener() {@Overridepublic void onReady(TAVVideoInfo mediaInfo) {// 素材解析完成,可读取时长、尺寸}});
TAVVideoInfo 字段:字段 | 类型 | 说明 |
path | String | 素材路径。 |
duration | long | 素材时长。 |
natureW / natureH | float | 素材原始宽高。 |
frameRate | int | 帧率,默认 30。 |
2. 切换合拍模式
// 分割人像叠加effectManager.setDuetMode(TAVRecorderConstants.TAVDuetMode.SEGMENT_OVERLAY,TAVRecorderConstants.TAVGridQuad.UNDEFINED);// 左右分屏,人像在左effectManager.setDuetMode(TAVRecorderConstants.TAVDuetMode.GRID,TAVRecorderConstants.TAVGridQuad.LEFT);// 取消合拍effectManager.setDuetMode(TAVRecorderConstants.TAVDuetMode.NONE,TAVRecorderConstants.TAVGridQuad.UNDEFINED);
3. 播放控制
effectManager.playDuetMedia();effectManager.pauseDuetMedia();effectManager.seekDuetMedia(positionUs); // 单位:微秒
4. 位置与尺寸调整
// 读取当前变换矩阵Matrix matrix = effectManager.getActiveDuetTransformMatrix();// 设置新的变换矩阵(拖动/缩放/旋转后回写)effectManager.setActiveDuetTransform(matrix);
如需自行绘制合拍素材的边框或命中区域,可用:
方法 | 说明 |
PointF[] computeActiveViewVertices(Rect viewRect) | 计算当前合拍素材在给定视图区域内的顶点。 |
RectF getCanvasRenderRect(int viewWidth, int viewHeight) | 计算画布渲染区域。 |