功能概览
合拍是把一段已有素材与实时摄像头画面组合录制的模式:素材作为背景或画中画,人像作为另一路画面,二者按指定布局合成到同一个输出文件。合拍能力由
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:TAVEditorMediaTypeVideoautoPlay:YES];// 图片素材(autoPlay 对图片无效)[effectManager setDuetMedia:@"/path/to/duet.jpg"type:TAVEditorMediaTypeImageautoPlay: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 *)extraInfopath:(NSString *)pathdurationUs:(long long)durationUs;/// 构造同一视频的 Video + Audio InputSource,返回 @[videoKey, audioKey]+ (NSArray<NSString *> *)buildVideoAndAudioInputSource:(NSMutableDictionary *)extraInfopath:(NSString *)pathdurationUs:(long long)durationUs;/// 构造图片 AssetInput extraInfo,返回生成的 srcKey+ (NSString *)buildImageInputSource:(NSMutableDictionary *)extraInfo path:(NSString *)path;/// 计算 ScreenTransform offset 矩形+ (TAVScreenRect)computeRectWithTranslationX:(float)translationXtranslationY:(float)translationYobjWidth:(float)objWidthobjHeight:(float)objHeightrenderWidth:(float)renderWidthrenderHeight:(float)renderHeight;/// anchor 固定为 (0, 0, 0, 0)+ (TAVScreenRect)computeAnchor;/// 铺满画布的 offset 矩形+ (TAVScreenRect)computeFullScreenRectWithRenderWidth:(float)renderWidthrenderHeight:(float)renderHeight;/// 计算 GRID 模式下分屏 Entity 尺寸+ (CGSize)computeGridEntitySizeWithGridQuad:(TAVRecorderGridQuad)gridQuadareaW:(float)areaWareaH:(float)areaH;/// 计算 ScreenTransform 在 View 上的四个顶点坐标(ZOOM 模式)+ (NSArray<NSValue *> *)transformToViewVerticesWithTransform:(TAVScreenTransform *)transformrenderWidth:(float)renderWidthrenderHeight:(float)renderHeightviewWidth:(int)viewWidthviewHeight:(int)viewHeight;
TAVScreenTransform 字段:anchor、offset(TAVScreenRect)、scaleX、scaleY、rotationDegrees。