功能概览
录制侧的“画幅”与“分辨率”是两套耦合参数:
TAVAspectRatio 决定画面的宽高比,TAVResolution 只声明短边像素等级,长边由画幅推导。预览画面与最终成片共用同一份 TAVRecorderConfig,因此配置只在一处生效,不存在“预览 16:9、导出 4:3”的隐式转换。相关接口类
接口类名 | 描述 |
TAVRecorder | 录制入口, prepare 时读取配置。 |
TAVRecorderConfig | 画幅、分辨率、帧率、码率与降级策略。 |
TAVRecorderConstants | TAVAspectRatio / TAVResolution / 降级与动作枚举。 |
TAVRecorderResolutionListener | 采集侧与编码侧分辨率回调。 |
画幅与分辨率
画幅
枚举值 | 比例 |
TAVAspectRatio.RATIO_16_9 | 16:9(默认) |
TAVAspectRatio.RATIO_4_3 | 4:3 |
TAVAspectRatio.RATIO_1_1 | 1:1 |
分辨率
TAVResolution 以短边像素标识,长边由画幅决定:枚举值 | 短边 |
RESOLUTION_480 | 480 |
RESOLUTION_540 | 540 |
RESOLUTION_720 | 720(默认) |
RESOLUTION_1080 | 1080 |
说明:
TAVResolution.longSide 是按 4:3 计算的兼容字段,实际输出以 aspectRatio 与解析结果为准,不要用它做布局计算。配置示例
TAVRecorderConfig config = new TAVRecorderConfig.Builder().setResolution(TAVRecorderConstants.TAVResolution.RESOLUTION_720).setAspectRatio(TAVRecorderConstants.TAVAspectRatio.RATIO_16_9).setFps(30).build();recorder.prepare(context, previewContainer, config);
配置默认值
配置项 | 默认值 |
resolution | RESOLUTION_720 |
aspectRatio | RATIO_16_9 |
fps | 30 |
cameraId | FRONT |
videoBitRate | 0(自动计算) |
resolutionFallbackStrategy | ALLOW_LOWER_OUTPUT_RESOLUTION |
videoBitRate 传0时由 SDK 自动计算:码率 = 宽 × 高 × 帧率 × 0.22,并保证结果落在 2 × 1024² bps ~ 50 × 1024² bps(约 2.1 ~ 52.4 Mbps)之间(低于下限取下限,高于上限取上限)。其中宽为分辨率短边(向下取偶),高按 aspectRatio 推导。例如 720×1280、30fps 约为 6.1 Mbps。分辨率降级
不同机型对采集尺寸与编码尺寸的支持差异很大,SDK 通过两条链路分别解析:
1. 采集链路:相机实际支持的采集尺寸 →
TAVCaptureResolutionResult。2. 编码链路:编码器最终接受的输出尺寸 →
TAVEncoderResolutionResult。降级策略
枚举值 | 行为 |
FAIL_IF_UNSUPPORTED | 编码器不支持当前有效输出分辨率时,拒绝开始录制。 |
ALLOW_LOWER_OUTPUT_RESOLUTION | 依次尝试更低标准分辨率,并回调最终输出尺寸。 |
TAVRecorderConfig config = new TAVRecorderConfig.Builder().setResolution(TAVRecorderConstants.TAVResolution.RESOLUTION_1080).setResolutionFallbackStrategy(TAVRecorderConstants.TAVResolutionFallbackStrategy.ALLOW_LOWER_OUTPUT_RESOLUTION).build();
监听解析结果
recorder.setResolutionListener(new TAVRecorderResolutionListener() {@Overridepublic void onCaptureResolutionResolved(TAVCaptureResolutionResult result) {// 采集侧结果:实际采集宽高、相机原始宽高、采取的动作}@Overridepublic void onEncoderResolutionResolved(TAVEncoderResolutionResult result) {// 编码侧结果:请求宽高 / 实际输出宽高 / 实际码率 / 编码器名 / 动作与原因}});
TAVCaptureResolutionResult(只读):字段 | 说明 |
cameraId | 摄像头。 |
requestedOutputWidth / requestedOutputHeight | 请求的输出宽高。 |
effectiveCaptureWidth / effectiveCaptureHeight | 实际采集宽高。 |
cameraSourceWidth / cameraSourceHeight | 相机原始宽高。 |
effectiveCaptureShortSide | 实际采集短边。 |
action | DIRECT(直接匹配)或 RESOLUTION_FALLBACK(发生降级)。 |
TAVEncoderResolutionResult(只读):字段 | 说明 |
requestedOutputWidth / requestedOutputHeight | 请求输出宽高。 |
effectiveOutputWidth / effectiveOutputHeight | 实际输出宽高。 |
requestedVideoBitRate / effectiveVideoBitRate | 请求码率 / 实际码率。 |
fps | 帧率。 |
encoderName | 编码器名称。 |
action | SUPPORTED / AUTO_BITRATE_ADJUSTED / OUTPUT_MATCHED_TO_CAPTURE / OUTPUT_RESOLUTION_FALLBACK / REJECTED。 |
reason | 触发动作的原因,如 CAPTURE_RESOLUTION_LIMITED、ENCODER_UNAVAILABLE、SIZE_AND_FPS_UNSUPPORTED、BITRATE_UNSUPPORTED 等。 |
常见问题
现象 | 原因与处理 |
预览比例与成片不一致 | 预览容器与录制输出必须共用同一份 TAVRecorderConfig.aspectRatio;不要在 prepare 之后再改配置对象。 |
1080P 机型上无法开始录制 | 编码器不支持时,若策略为 FAIL_IF_UNSUPPORTED 会直接拒绝;改用 ALLOW_LOWER_OUTPUT_RESOLUTION 或降到 720P。 |
实际输出比请求的小 | 属正常降级,通过 TAVEncoderResolutionResult.effectiveOutputWidth/Height 读取真实尺寸。 |