TAVRecorder
录制能力入口(
TAVMagic 模块)。推荐通过 [TAVMagicBase createRecorder] 创建实例:#import <TAVMagic/TAVMagicBase.h>#import <TAVMagic/TAVRecorder.h>// 需先调用 [TAVMagicBase initSDK:]TAVRecorder *recorder = [TAVMagicBase createRecorder];
initWithAssetsPath: 也可直接初始化,但不推荐使用,详见下方说明。接口方法汇总
API | 描述 |
不推荐。使用指定资源路径初始化录制器,建议改用 [TAVMagicBase createRecorder]。 | |
初始化录制器与预览容器。 | |
开启相机预览。 | |
停止相机预览。 | |
开始录制,可指定录制速度。 | |
停止当前段录制。 | |
将所有录制片段合成为一个视频文件。 | |
删除最后一段录制。 | |
清空所有录制片段及对应文件。 | |
获取当前所有录制片段列表。 | |
截取当前预览帧为静态图片。 | |
设置录制状态回调监听。 | |
动态切换画面输出比例。 | |
获取相机管理接口。 | |
获取背景音乐管理接口。 | |
获取美颜特效管理接口。 |
initWithAssetsPath:
描述
使用指定 LightEngine 资源路径初始化录制器。需先调用
[TAVMagicBase initSDK:]。说明:
不推荐使用该接口。
建议统一使用
[TAVMagicBase createRecorder]:它会复用 initSDK: 已初始化的资源路径,未初始化时还会尝试默认路径兜底,可避免因传入错误路径导致初始化失败。仅在你明确需要指定独立资源路径时才使用本接口。接口
- (instancetype)initWithAssetsPath:(NSString *)assetsPath参数
参数名 | 类型 | 说明 |
assetsPath | NSString * | LightCore.bundle 资源路径。 |
返回值
类型:
instancetype说明:录制器实例。
prepareWithRecorderConfig:displayContainerView:
描述
准备录制器:创建采集与渲染链路并把预览画面绑定到指定容器。必须在其它录制接口之前调用。
接口
- (TAVRecorderPrepareResult)prepareWithRecorderConfig:(TAVRecorderConfig *)config displayContainerView:(UIView *)displayContainerView参数
参数名 | 类型 | 说明 |
config | TAVRecorderConfig * | 录制配置,传 nil 使用默认配置。见 TAVRecorderConfig。 |
displayContainerView | UIView * | 预览画面的容器视图,预览层会自动填充该视图。 |
返回值
类型:
TAVRecorderPrepareResult说明:
TAVRecorderPrepareResultSuccess(0) 成功;TAVRecorderPrepareResultNoAuthorized(-1) 缺少相机/麦克风等必要权限。startPreview
描述
开启相机预览。
prepareWithRecorderConfig:displayContainerView: 成功后可调用。接口
- (void)startPreview参数
无
返回值
类型:
voidstopPreview
描述
停止相机预览。
接口
- (void)stopPreview参数
无
返回值
类型:
voidstartRecordWithSpeed:enableMic:
描述
开始录制。支持分段录制:多次调用
startRecordWithSpeed:enableMic: / stopRecord 会生成多个 TAVRecordSegment。接口
- (void)startRecordWithSpeed:(CGFloat)speed enableMic:(BOOL)enableMic参数
参数名 | 类型 | 说明 |
speed | CGFloat | 录制速度,1.0 为正常速度,>1.0 为快速(如 2.0 为 2 倍速),<1.0 为慢动作。BGM 播放速率会自动同步为 1.0/speed,使 BGM 节奏与最终视频对齐。 |
enableMic | BOOL | 是否录制麦克风音频, YES 表示录制人声,NO 表示静音录制。 |
返回值
类型:
void说明:无返回值,过程与结果通过
TAVRecordListener 回调。stopRecord
描述
停止当前段录制。
接口
- (void)stopRecord参数
无
返回值
类型:
void说明:结果通过
TAVRecordListener 的 onStopRecord: 回调。composeVideo:completion:
描述
将所有录制片段合成为一个视频文件。
接口
- (void)composeVideo:(NSString *)outputPath completion:(void (^)(NSError *_Nullable error))completion参数
参数名 | 类型 | 说明 |
outputPath | NSString * | 输出文件路径(建议扩展名 .mp4)。 |
completion | block | 完成回调,在主线程执行;成功时 error 为 nil,失败时包含错误信息。 |
返回值
类型:
voiddeleteLastSegment
描述
删除最后一段录制片段,同时删除对应文件。用于“重录上一段”。
接口
- (void)deleteLastSegment参数
无
返回值
类型:
voidclearAllSegments
描述
清空所有录制片段及对应文件。
接口
- (void)clearAllSegments参数
无
返回值
类型:
voidgetSegments
描述
获取当前所有录制片段列表。
接口
- (NSArray<TAVRecordSegment *> *)getSegments
参数
无
返回值
类型:NSArray<TAVRecordSegment *> *
说明:按录制顺序排列,字段见
TAVRecordSegment。snapShot:
描述
截取当前预览帧为静态图片。
接口
- (void)snapShot:(void (^)(UIImage *image, NSError *error))completion参数
参数名 | 类型 | 说明 |
completion | block | 回调在主线程执行,成功时返回 UIImage,失败时返回 error。 |
返回值
类型:
voidsetRecordListener:
描述
设置录制状态回调监听。录制器对 listener 为弱引用持有,请自行保证监听对象生命周期。
接口
- (void)setRecordListener:(id<TAVRecordListener>)listener
参数
参数名 | 类型 | 说明 |
listener | id<TAVRecordListener> | 遵守 TAVRecordListener 协议的对象。 |
返回值
类型:
voidsetAspectRatio:
描述
动态切换画面输出比例,须在非录制状态下调用。会立即更新相机裁剪区域,并在下次开始录制时使用新的视频尺寸。
接口
- (void)setAspectRatio:(TAVRecorderAspectRatio)aspectRatio参数
参数名 | 类型 | 说明 |
aspectRatio | TAVRecorderAspectRatio | 目标比例,见 TAVRecorderAspectRatio 枚举。 |
返回值
类型:
voidgetCameraManager
描述
获取相机控制接口,用于变焦、对焦、闪光灯等运行时调整。
接口
- (id<ITAVCameraManager>)getCameraManager
返回值
类型:id<ITAVCameraManager>
getBGMManager
描述
获取 BGM 管理接口,用于设置、控制背景音乐。
接口
- (id<ITAVBGMManager>)getBGMManager
返回值
类型:id<ITAVBGMManager>
getEffectManager
描述
获取美颜特效管理接口,用于设置美颜、滤镜、合拍等特效。
接口
- (id<ITAVEffectManager>)getEffectManager
返回值
类型:id<ITAVEffectManager>
TAVRecorderConfig
录制配置(
TAVRecorderDefinitions.h),直接对属性赋值。字段
字段 | 类型 | 默认值 | 说明 |
devicePosition | AVCaptureDevicePosition | AVCaptureDevicePositionFront | 默认摄像头位置。 |
fps | int | 30 | 帧率。 |
resolution | TAVRecorderResolution | TAVRecorderResolution_1080 | 分辨率/帧率预设值。 |
aspectRatio | TAVRecorderAspectRatio | TAVRecorderAspectRatioFull | 画面比例。 |
bitrate | UInt64 | 0 | 视频码率(bps)。0 表示自动,按 width * height * fps * 0.22 动态计算;大于 0 则使用固定码率。 |
构造示例
TAVRecorderConfig *config = [[TAVRecorderConfig alloc] init];config.devicePosition = AVCaptureDevicePositionBack;config.resolution = TAVRecorderResolution_720;config.aspectRatio = TAVRecorderAspectRatioFull;config.fps = 30;config.bitrate = 0;
TAVRecorderDefinitions(枚举)
TAVRecorderAspectRatio
枚举值 | 值 | 说明 |
TAVRecorderAspectRatioFull | 0 | 9:16。 |
TAVRecorderAspectRatio_3_4 | 1 | 3:4。 |
TAVRecorderAspectRatio_1_1 | 2 | 1:1。 |
TAVRecorderResolution
枚举值 | 值 | 说明 |
TAVRecorderResolution_480 | 0 | 480 等级。 |
TAVRecorderResolution_540 | 1 | 540 等级。 |
TAVRecorderResolution_720 | 2 | 720 等级。 |
TAVRecorderResolution_1080 | 3 | 1080 等级。 |
TAVRecorderPrepareResult
枚举值 | 值 | 说明 |
TAVRecorderPrepareResultSuccess | 0 | 初始化成功。 |
TAVRecorderPrepareResultNoAuthorized | -1 | 缺少相机/麦克风权限。 |
TAVRecorderDuetMode
合拍模式枚举,配合
ITAVEffectManager 的 setDuetMode:gridQuad: 使用。枚举值 | 值 | 说明 |
TAVRecorderDuetModeNone | 0 | 无合拍,取消合拍。 |
TAVRecorderDuetModeSegmentOverlay | 1 | 分割人像叠加模式。 |
TAVRecorderDuetModeOverlay | 2 | 素材画中画模式。 |
TAVRecorderDuetModeGrid | 3 | 左右/上下合拍模式。 |
TAVRecorderGridQuad
枚举值 | 值 | 说明 |
TAVRecorderGridQuadUndefined | 0 | 未指定。 |
TAVRecorderGridQuadTop | 1 | 人像在上,素材在下。 |
TAVRecorderGridQuadBottom | 2 | 人像在下,素材在上。 |
TAVRecorderGridQuadLeft | 3 | 人像在左,素材在右。 |
TAVRecorderGridQuadRight | 4 | 人像在右,素材在左。 |
TAVRecordSegment
录制片段模型。
字段 | 类型 | 说明 |
path | NSString * | 录制视频路径。 |
duration | CMTime | 录制视频时长。 |
bgmPath | NSString * | 背景音乐路径。 |
bgmStartPosition | CMTime | 背景音乐起始时间。 |
duetMediaStartPosition | NSTimeInterval | 本段录制开始时合拍素材所在的 source 位置(秒)。删除本段后据此把合拍素材回退到本段起点。 |
TAVRecordListener
录制状态回调协议,所有方法均为
@optional。回调 | 说明 |
- (void)onRecordStart | 录制开始。 |
- (void)onRecording:(CMTime)recordingTime | 录制进行中,周期性回调当前已录制时长(已按 recordSpeed 缩放)。 |
- (void)onStopRecord:(NSError *)stopResult | 录制停止,成功时为 nil,失败时为具体错误信息。 |
- (void)onCameraError:(NSError *)error | 相机初始化/配置失败(会话配置、加输入/输出、设置 preset 等失败时触发)。 |
ITAVCameraManager
相机管理接口(
ITAVCameraManager.h),由 [recorder getCameraManager] 获取。方法 | 说明 |
- (void)switchCamera | 切换前后置摄像头。 |
- (int)getCameraCount | 获取可用摄像头数量。 |
- (void)setZoom:(CGFloat)zoomFactor | 设置变焦倍数,范围 [1.0, getMaxZoom]。 |
- (CGFloat)getMaxZoom | 当前设备支持的最大变焦倍数。 |
- (CGPoint)captureDevicePointOfInterestForViewPoint:(CGPoint)pointInPreview | 将预览视图坐标系中的点转换为相机对焦所需的归一化设备坐标 [0,1]×[0,1],内部已处理 videoGravity 造成的黑边/裁切。 |
- (void)setFocusPoint:(CGPoint)point | 设置点击对焦位置,归一化坐标 [0,1]×[0,1]。 |
- (void)setExposureCompensation:(CGFloat)bias | 设置曝光补偿,范围 [0, 1],默认 0.5。 |
- (void)resetExposureBrightnessToAuto | 把曝光复位到「连续自动 + 中性亮度」,清除残留手动 EV 偏移(切换摄像头/前后台切换时调用)。 |
- (void)setAspectRatio:(TAVRecorderAspectRatio)ratio | 设置画面输出比例。 |
- (BOOL)isSupportFlash | 当前设备是否支持闪光灯。 |
- (void)setFlashMode:(AVCaptureFlashMode)flashMode | 设置闪光灯模式( Off / On / Auto)。 |
- (AVCaptureFlashMode)flashMode | 获取当前闪光灯模式。 |
- (BOOL)isSupportTorch | 当前设备是否支持补光灯。 |
- (AVCaptureTorchMode)torchMode | 获取当前补光灯模式。 |
- (void)setTorchMode:(AVCaptureTorchMode)torchMode | 设置补光灯模式( Off / On / Auto)。 |
- (void)setMirror:(BOOL)isMirror | 设置前置摄像头是否开启镜像。 |
ITAVEffectManager
特效管理接口(
ITAVEffectManager.h),由 [recorder getEffectManager] 获取。底层基于腾讯 XMagic SDK。方法 | 说明 |
- (void)setEffect:effectValue:resourcePath:extraInfo: | 设置美颜/滤镜/特效参数。无返回值。 |
- (void)setDuetMedia:type:autoPlay: | 设置合拍素材。无返回值。 |
- (void)setDuetMode:gridQuad: | 设置/切换合拍模式,自动计算并下发 ScreenTransform,同时重置已有自定义变换。 |
- (void)playDuetMedia | 开始播放合拍素材(视频)。 |
- (void)pauseDuetMedia | 暂停合拍素材播放。 |
- (BOOL)isDuetMediaPlaying | 合拍素材当前是否正在播放。 |
- (void)seekDuetMedia:(NSTimeInterval)timeInSeconds | 将合拍素材 seek 到指定位置(秒),仅对视频素材有效。 |
- (void)setActiveDuetTransform:(CGAffineTransform)transform | 设置当前活跃(可拖动)实体的变换。 |
- (CGAffineTransform)getActiveDuetTransform | 获取当前活跃实体的变换矩阵,未设置时返回 CGAffineTransformIdentity。 |
- (NSArray *)computeActiveViewVertices:(CGRect)viewRect | 计算当前可拖动实体在 View 中的顶点位置,返回 [左上, 右上, 右下, 左下],失败返回空数组。 |
ITAVBGMManager
背景音乐管理接口(
ITAVBGMManager.h),由 [recorder getBGMManager] 获取。方法 | 说明 |
- (void)setBGM:startTime:duration: | 设置背景音乐。 startTime 传 kCMTimeZero 表示从头开始;duration 传 kCMTimeInvalid 表示播放到文件结尾。 |
- (void)setLoop:(BOOL)loop | 是否循环播放。 |
- (void)setVolume:(float)volume | 音量,范围 [0.0, 1.0]。 |
- (void)clearBGM | 清除当前 BGM,释放相关资源。 |
- (void)seekToTime:(CMTime)time | 跳转到指定播放位置。 |
- (void)setPlaybackRate:(float)rate | BGM 播放速率,1.0 为正常速度。录制速度为 N 倍时传入 1.0/N,使 BGM 节奏与录制内容对齐。 |
TAVDuetOperator
合拍 ScreenTransform 计算工具类(
TAVDuetOperator.h)。方法 | 说明 |
- (float)baseLength | ScreenTransform 基于高 1280 缩放的基准值。 |
- buildComponentExtraInfoWithPairs: | 构造 entity.component extraInfo。 |
- buildEnableExtraInfoWithPairs: | 构造 entity.component.enable extraInfo。 |
- buildVideoInputSource:path:durationUs: | 构造视频 AssetInput extraInfo,返回生成的 srcKey。 |
- buildVideoAndAudioInputSource:path:durationUs: | 构造同一视频的 Video + Audio InputSource,返回 @[videoKey, audioKey]。 |
- buildImageInputSource:path: | 构造图片 AssetInput extraInfo,返回生成的 srcKey。 |
- computeRectWithTranslationX:translationY:objWidth:objHeight:renderWidth:renderHeight: | 计算 ScreenTransform offset 矩形。 |
- computeAnchor | anchor 固定为 (0, 0, 0, 0)。 |
- computeFullScreenRectWithRenderWidth:renderHeight: | 铺满画布的 offset 矩形。 |
- computeGridEntitySizeWithGridQuad:areaW:areaH: | 计算 GRID 模式下分屏 Entity 尺寸。 |
- transformToViewVerticesWithTransform:renderWidth:renderHeight:viewWidth:viewHeight: | 计算 ScreenTransform 在 View 上的四个顶点坐标(ZOOM 模式)。 |
extraInfo Key 常量
常量 | 字符串值 |
kTAVDuetEntityComponent | entity.component |
kTAVDuetComponentJSON | entity.component.json |
kTAVDuetComponentPause | entity.component.pause |
kTAVDuetComponentEnable | entity.component.enable |
kTAVDuetAssetInput | asset.input |
kTAVDuetAssetInputJSON | asset.input.json |
kTAVDuetFlushTime | flush.time |
kTAVDuetTimelinePause | timeline.pause |
TAVScreenTransform
字段 | 类型 | 说明 |
anchor | TAVScreenRect | 锚点矩形。 |
offset | TAVScreenRect | 偏移矩形(bottom/left/right/top)。 |
scaleX / scaleY | float | 缩放(z 固定为 1)。 |
rotationDegrees | float | 旋转角度(度),内部转四元数。 |