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

iOS

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

功能概览

合拍是把一段已有素材与实时摄像头画面组合录制的模式:素材作为背景或画中画,人像作为另一路画面,二者按指定布局合成到同一个输出文件。合拍能力由 ITAVEffectManager 提供,通过 [recorder getEffectManager] 获取。

相关接口类

接口类名
描述
TAVRecorder
录制入口。
ITAVEffectManager
合拍素材设置、模式切换、播放控制与变换。
TAVRecorderDefinitions
TAVRecorderDuetMode、TAVRecorderGridQuad 枚举定义。
TAVDuetOperator
ScreenTransform 计算工具(构造 extraInfo、顶点换算)。
TAVDuetTransformInfo
合拍变换信息模型。

合拍模式

TAVRecorderDuetMode 定义四种状态:
枚举值
值
说明
TAVRecorderDuetModeNone
0
无合拍(取消合拍,恢复普通录制)。
TAVRecorderDuetModeSegmentOverlay
1
分割人像叠加:人像分割后叠加在素材上方,人像可自由拖动,素材作为背景铺满画布。
TAVRecorderDuetModeOverlay
2
素材画中画:不分割人像,人像作为背景铺满画布,素材以画中画显示,可自由拖动。
TAVRecorderDuetModeGrid
3
左右/上下合拍:由 TAVRecorderGridQuad 决定分屏方向与人像方位。
TAVRecorderGridQuad 用于 Grid 模式下指定人像所在位置:
枚举值
值
说明
TAVRecorderGridQuadUndefined
0
未指定(默认值)。
TAVRecorderGridQuadTop
1
人像在上,素材在下。
TAVRecorderGridQuadBottom
2
人像在下,素材在上。
TAVRecorderGridQuadLeft
3
人像在左,素材在右。
TAVRecorderGridQuadRight
4
人像在右,素材在左。

注意事项

合拍素材类型通过 TAVEditorMediaType 指定,视频与图片的时长语义不同;图片素材的展示时长由业务侧决定。
autoPlay 为 YES 时素材随预览开始播放;若业务需要“先定位再播放”,请传 NO 并自行调用 playDuetMedia。
Grid 模式下若 gridQuad 传 Undefined,分屏方向不确定,建议显式指定方位。
切换或取消合拍(None)后,已录制的片段不会回溯修改,切换应发生在两段录制之间。
删除某段录制后,SDK 会依据 TAVRecordSegment.duetMediaStartPosition 把合拍素材回退到该段起点。

使用流程

1. 设置合拍素材

/// 设置合拍素材
/// @param path 素材文件的绝对路径
/// @param type 素材类型(视频或图片),见 TAVEditorMediaType
/// @param autoPlay 是否在设置后立即自动播放(视频类型有效)
/// 传 NO 时视频保持暂停,需手动调用 playDuetMedia 触发播放
- (void)setDuetMedia:(NSString *)path type:(TAVEditorMediaType)type autoPlay:(BOOL)autoPlay;
id<ITAVEffectManager> effectManager = [recorder getEffectManager];

// 视频素材,设置后立即播放
[effectManager setDuetMedia:@"/path/to/duet.mp4"
type:TAVEditorMediaTypeVideo
autoPlay:YES];

// 图片素材(autoPlay 对图片无效)
[effectManager setDuetMedia:@"/path/to/duet.jpg"
type:TAVEditorMediaTypeImage
autoPlay:NO];
TAVEditorMediaType:
枚举值
值
说明
TAVEditorMediaTypeUnknown
0
未知。
TAVEditorMediaTypeVideo
1 << 0
视频。
TAVEditorMediaTypeAudio
1 << 1
音频。
TAVEditorMediaTypeImage
1 << 2
照片。

2. 切换合拍模式

/// 设置/切换合拍模式
/// 切换模式后系统自动计算并下发人像和素材的 ScreenTransform,同时重置已有的自定义变换设置
/// 设置为 TAVRecorderDuetModeNone 可取消合拍,恢复为普通录制模式
- (void)setDuetMode:(TAVRecorderDuetMode)mode gridQuad:(TAVRecorderGridQuad)gridQuad;
// 分割人像叠加
[effectManager setDuetMode:TAVRecorderDuetModeSegmentOverlay gridQuad:TAVRecorderGridQuadUndefined];

// 左右分屏,人像在左
[effectManager setDuetMode:TAVRecorderDuetModeGrid gridQuad:TAVRecorderGridQuadLeft];

// 取消合拍
[effectManager setDuetMode:TAVRecorderDuetModeNone gridQuad:TAVRecorderGridQuadUndefined];

3. 播放控制

[effectManager playDuetMedia]; // 开始播放(仅视频素材)
[effectManager pauseDuetMedia]; // 暂停播放
[effectManager seekDuetMedia:0]; // seek 到指定播放位置(秒),0 表示回到素材开头
BOOL playing = [effectManager isDuetMediaPlaying]; // 素材当前是否正在播放
isDuetMediaPlaying 仅当“已设置视频素材(时长有效)且未处于暂停态”时返回 YES。以下情况均返回 NO:未设置素材、素材为图片、调用过 pauseDuetMedia(含录制停止 / 退后台 / stopPreview 触发的暂停)、以及 setDuetMedia 传 autoPlay=NO 尚未调用 playDuetMedia。
注意:
该值与合拍模式无关,TAVRecorderDuetModeNone 下若素材仍在播放也会返回 YES。

4. 位置与尺寸调整

/// 设置当前活跃(可拖动)实体的变换(scale、rotation、translation)
/// 仅在合拍模式下有效(非 TAVRecorderDuetModeNone)
- (void)setActiveDuetTransform:(CGAffineTransform)transform;

/// 获取当前活跃(可拖动)实体的变换矩阵,未设置时返回 CGAffineTransformIdentity
- (CGAffineTransform)getActiveDuetTransform;
变换目标由当前合拍模式自动决定:
合拍模式
变换目标
TAVRecorderDuetModeSegmentOverlay
Camera(人像抠图层在上层可拖动)。
TAVRecorderDuetModeOverlay
Media(素材在上层可拖动)。
TAVRecorderDuetModeGrid
Media(素材在其格子内自由拖动,可越界盖住 Camera 格)。
背景实体始终铺满画面,调用 setActiveDuetTransform: 不会影响背景实体。transform 中 tx/ty 为归一化坐标 0~1,scale 为相对缩放因子。
如需自行绘制合拍素材的边框或命中区域,可用:
/// 计算当前可拖动实体在 View 中的顶点位置
/// 画布通过 LetterBox(FitCenter)方式等比缩放渲染到相机预览 View 上
/// 此方法已处理 LetterBox 黑边偏移
/// @param viewRect 推荐与相机视图一样大
/// @return [左上, 右上, 右下, 左下],NSValue 包装的 CGPoint;失败返回空数组
- (NSArray *)computeActiveViewVertices:(CGRect)viewRect;

5. ScreenTransform 计算工具(TAVDuetOperator)

TAVDuetOperator 提供归一化坐标到 Light SDK ScreenTransform 的换算能力:
/// ScreenTransform 基于高 1280 缩放的基准值
+ (float)baseLength;

/// 构造 entity.component extraInfo
+ (NSDictionary *)buildComponentExtraInfoWithPairs:(NSArray<NSArray *> *)pairs;

/// 构造 entity.component.enable extraInfo
+ (NSDictionary *)buildEnableExtraInfoWithPairs:(NSArray<NSArray *> *)pairs;

/// 构造视频 AssetInput extraInfo,返回生成的 srcKey
+ (NSString *)buildVideoInputSource:(NSMutableDictionary *)extraInfo
path:(NSString *)path
durationUs:(long long)durationUs;

/// 构造同一视频的 Video + Audio InputSource,返回 @[videoKey, audioKey]
+ (NSArray<NSString *> *)buildVideoAndAudioInputSource:(NSMutableDictionary *)extraInfo
path:(NSString *)path
durationUs:(long long)durationUs;

/// 构造图片 AssetInput extraInfo,返回生成的 srcKey
+ (NSString *)buildImageInputSource:(NSMutableDictionary *)extraInfo path:(NSString *)path;

/// 计算 ScreenTransform offset 矩形
+ (TAVScreenRect)computeRectWithTranslationX:(float)translationX
translationY:(float)translationY
objWidth:(float)objWidth
objHeight:(float)objHeight
renderWidth:(float)renderWidth
renderHeight:(float)renderHeight;

/// anchor 固定为 (0, 0, 0, 0)
+ (TAVScreenRect)computeAnchor;

/// 铺满画布的 offset 矩形
+ (TAVScreenRect)computeFullScreenRectWithRenderWidth:(float)renderWidth
renderHeight:(float)renderHeight;

/// 计算 GRID 模式下分屏 Entity 尺寸
+ (CGSize)computeGridEntitySizeWithGridQuad:(TAVRecorderGridQuad)gridQuad
areaW:(float)areaW
areaH:(float)areaH;

/// 计算 ScreenTransform 在 View 上的四个顶点坐标(ZOOM 模式)
+ (NSArray<NSValue *> *)transformToViewVerticesWithTransform:(TAVScreenTransform *)transform
renderWidth:(float)renderWidth
renderHeight:(float)renderHeight
viewWidth:(int)viewWidth
viewHeight:(int)viewHeight;
TAVScreenTransform 字段:anchor、offset(TAVScreenRect)、scaleX、scaleY、rotationDegrees。