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

iOS

最近更新时间:2026-11-09 14:52:01
我的收藏

TAVRecorder

录制能力入口(TAVMagic 模块)。推荐通过 [TAVMagicBase createRecorder] 创建实例:
#import <TAVMagic/TAVMagicBase.h>
#import <TAVMagic/TAVRecorder.h>

// 需先调用 [TAVMagicBase initSDK:]
TAVRecorder *recorder = [TAVMagicBase createRecorder];
initWithAssetsPath: 也可直接初始化,但不推荐使用,详见下方说明。

接口方法汇总

API
描述
不推荐。使用指定资源路径初始化录制器,建议改用 [TAVMagicBase createRecorder]。
初始化录制器与预览容器。
开启相机预览。
停止相机预览。
开始录制,可指定录制速度。
停止当前段录制。
将所有录制片段合成为一个视频文件。
删除最后一段录制。
清空所有录制片段及对应文件。
获取当前所有录制片段列表。
snapShot:
截取当前预览帧为静态图片。
设置录制状态回调监听。
动态切换画面输出比例。
获取相机管理接口。
获取背景音乐管理接口。
获取美颜特效管理接口。

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
参数
无
返回值
类型:void

stopPreview

描述
停止相机预览。
接口
- (void)stopPreview
参数
无
返回值
类型:void

startRecordWithSpeed: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,失败时包含错误信息。
返回值
类型:void

deleteLastSegment

描述
删除最后一段录制片段,同时删除对应文件。用于“重录上一段”。
接口
- (void)deleteLastSegment
参数
无
返回值
类型:void

clearAllSegments

描述
清空所有录制片段及对应文件。
接口
- (void)clearAllSegments
参数
无
返回值
类型:void

getSegments

描述
获取当前所有录制片段列表。
接口
- (NSArray<TAVRecordSegment *> *)getSegments
参数
无
返回值
类型:NSArray<TAVRecordSegment *> *
说明:按录制顺序排列,字段见 TAVRecordSegment。

snapShot:

描述
截取当前预览帧为静态图片。
接口
- (void)snapShot:(void (^)(UIImage *image, NSError *error))completion
参数
参数名
类型
说明
completion
block
回调在主线程执行,成功时返回 UIImage,失败时返回 error。
返回值
类型:void

setRecordListener:

描述
设置录制状态回调监听。录制器对 listener 为弱引用持有,请自行保证监听对象生命周期。
接口
- (void)setRecordListener:(id<TAVRecordListener>)listener
参数
参数名
类型
说明
listener
id<TAVRecordListener>
遵守 TAVRecordListener 协议的对象。
返回值
类型:void

setAspectRatio:

描述
动态切换画面输出比例,须在非录制状态下调用。会立即更新相机裁剪区域,并在下次开始录制时使用新的视频尺寸。
接口
- (void)setAspectRatio:(TAVRecorderAspectRatio)aspectRatio
参数
参数名
类型
说明
aspectRatio
TAVRecorderAspectRatio
目标比例,见 TAVRecorderAspectRatio 枚举。
返回值
类型:void

getCameraManager

描述
获取相机控制接口,用于变焦、对焦、闪光灯等运行时调整。
接口
- (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
旋转角度(度),内部转四元数。