帮你快速理解、总结文档立即下载

Android

最近更新时间:2026-11-09 14:52:03
本文档已由 AI 辅助审校
我的收藏

功能概览

合拍是把一段已有素材与实时摄像头画面组合录制的模式:素材作为背景或画中画,人像作为另一路画面,二者按指定布局合成到同一个输出文件。合拍能力由 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() {
@Override
public 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)
计算画布渲染区域。