移动端视频编码参数速查：Claude Code Skill 一键查询最佳配置

编码参数选错，轻则画质下降，重则用户投诉「视频模糊」。但 iOS VideoToolbox 和 Android MediaCodec 的参数体系完全不同。本文写一个 Claude Code Skill，输入场景自动输出双端最优配置。

1、编码参数选择的困境

“每个新项目都要重新查一遍：实时通话用什么 Profile？短视频录制的码率设多少？H.265 的 Bitrate Mode 在 Android 上怎么对应 iOS 的 VBR？…”

编码参数的四维复杂度：

• 场景维度 — 实时通话 vs 录制 vs 直播，参数完全不同
• 平台维度 — iOS 的 kVTVBR 在 Android 上叫 BITRATE_MODE_VBR
• 分辨率维度 — 720p 和 1080p 的码率不是线性关系
• 编码器维度 — H.264 High Profile 在低端机可能不支持硬编

Claude Code Skill 方案： 写一个 encoder-config Skill，之后在任何项目中只需说「实时通话, 720p, iOS」，自动输出完整配置——包括每个参数的平台对应关系和选择理由。

2、Skill 设计思路

用户输入：「场景 + 平台 + 分辨率」
     │
     ▼
┌────────────────────────────────┐
│ encoder-config Skill           │
│                               │
│ 1. 解析场景 → 确定编码策略     │
│ 2. 查表 → 码率/帧率/关键帧间隔 │
│ 3. 平台映射 → iOS ↔ Android   │
│ 4. 输出 → 完整配置 + 选择理由   │
└────────────────────────────────┘

3、encoder-config Skill 完整实现

创建 .claude/skills/encoder-config.md：

---
name: encoder-config
description: 根据场景+平台+分辨率，输出视频编码器完整配置
allowed-tools: Read
---

# 编码器参数配置 Skill

用户描述需求后，按以下规则输出双端编码器配置。

## 场景分类

| 场景 | 核心目标 | 延迟要求 | 编码策略 |
|------|---------|---------|---------|
| 实时通话 | 低延迟 | <100ms | CBR + 无B帧 + 小Buffer |
| 视频录制 | 画质优先 | 无要求 | VBR + B帧 + 大Buffer |
| 直播推流 | 稳定码率 | <3s | CBR/VBR + 码率上限 |
| 短视频 | 画质+文件大小平衡 | 无要求 | VBR + 2秒I帧 |
| 屏幕录制 | 清晰文字 | 无要求 | CBR + HighProfile |

## 码率速查表 (H.264, 30fps)

| 分辨率 | 实时通话 | 录制/短视频 | 直播 |
|--------|---------|-----------|------|
| 360p (640×360) | 400Kbps | 800Kbps | 600Kbps |
| 480p (854×480) | 600Kbps | 1.5Mbps | 1Mbps |
| 720p (1280×720) | 1.5Mbps | 3Mbps | 2Mbps |
| 1080p (1920×1080) | 3Mbps | 6Mbps | 4Mbps |
| 4K (3840×2160) | 8Mbps | 20Mbps | 12Mbps |

## H.265 码率系数

H.265 ≈ H.264 码率 × 0.6 ~ 0.7（相同画质）

## 关键帧(I帧)间隔

| 场景 | I帧间隔 | 理由 |
|------|--------|------|
| 实时通话 | 10s | 减少I帧大小峰值，平滑码率 |
| 录制 | 2s | seek友好 |
| 直播 | 2-4s | 快速出画 + 平滑码率平衡 |
| 屏幕录制 | 5s | 内容变化慢 |

## iOSVideoToolbox 配置模板

```swift
// 实时通话场景, H.265, 720p
letcompressionSession:VTCompressionSession

// 基本参数
VTSessionSetProperty(session, kVTCompressionPropertyKey_RealTime, kCFBooleanTrue)
VTSessionSetProperty(session, kVTCompressionPropertyKey_ProfileLevel,
    kVTProfileLevel_HEVC_Main_AutoLevel)

// 码率:1.5Mbps (H.265 = 2.5MbpsH.264 × 0.6)
VTSessionSetProperty(session, kVTCompressionPropertyKey_AverageBitRate,
    1_500_000asCFNumber)
VTSessionSetProperty(session, kVTCompressionPropertyKey_DataRateLimits,
    [1_500_000 * 1.5, 1] asCFArray)  // 上限1.5倍码率

// 帧率
VTSessionSetProperty(session, kVTCompressionPropertyKey_ExpectedFrameRate, 30asCFNumber)

// I帧间隔:10s = 300帧
VTSessionSetProperty(session, kVTCompressionPropertyKey_MaxKeyFrameInterval, 300asCFNumber)
VTSessionSetProperty(session, kVTCompressionPropertyKey_MaxKeyFrameIntervalDuration, 10asCFNumber)

// 允许帧重排 (B帧) — 实时通信场景设为false
VTSessionSetProperty(session, kVTCompressionPropertyKey_AllowFrameReordering, kCFBooleanFalse)

// 低延迟模式
if #available(iOS11.0, *) {
    VTSessionSetProperty(session, kVTCompressionPropertyKey_ExpectedDuration,
        1.0/30.0asCFNumber)  // 每帧 33ms
}

4、Android MediaCodec 配置模板

// 实时通话场景, H.265 (HEVC), 720p
val format = MediaFormat.createVideoFormat(
    MediaFormat.MIME_TYPE_VIDEO_HEVC,  // H.265
    1280, 720// 宽, 高
)

// 基本参数
format.setInteger(MediaFormat.KEY_BIT_RATE, 1_500_000)  // 1.5 Mbps
format.setInteger(MediaFormat.KEY_FRAME_RATE, 30)
format.setInteger(MediaFormat.KEY_I_FRAME_INTERVAL, 10) // 10 秒

// 码率控制: CBR (实时场景)
format.setInteger(MediaFormat.KEY_BITRATE_MODE,
    MediaCodecInfo.EncoderCapabilities.BITRATE_MODE_CBR)

// 颜色格式: Surface 输入 (零拷贝)
format.setInteger(MediaFormat.KEY_COLOR_FORMAT,
    MediaCodecInfo.CodecCapabilities.COLOR_FormatSurface)

// Profile: HEVC Main
format.setInteger(MediaFormat.KEY_PROFILE,
    MediaCodecInfo.CodecProfileLevel.HEVCProfileMain)

// 优先级: 实时
format.setInteger(MediaFormat.KEY_PRIORITY, 0) // 0=实时

// 复杂度: 平衡速度与画质 (0=最快, 2=最佳画质)
format.setInteger(MediaFormat.KEY_COMPLEXITY, 0) // 实时场景用最快的

// H.264 版本 (如果设备不支持 H.265)
// val format = MediaFormat.createVideoFormat(
//     MediaFormat.MIME_TYPE_VIDEO_AVC, 1280, 720)
// format.setInteger(MediaFormat.KEY_BIT_RATE, 2_500_000)  // H.264 需更高码率
// format.setInteger(MediaFormat.KEY_PROFILE,
//     MediaCodecInfo.CodecProfileLevel.AVCProfileHigh)

5、平台参数对照表

⚠️ Android KEY_I_FRAME_INTERVAL 单位是秒，iOS kVT_MaxKeyFrameInterval 单位是帧数！非常容易搞混。

6、输出格式

每次输出必须包含以下四部分：

1. 场景分析: 一句话总结需求
2. iOS 完整配置: Swift 代码块，每个参数注释选择理由
3. Android 完整配置: Kotlin 代码块，每个参数注释选择理由
4. 平台差异提醒: 重点标出容易搞混的参数

7、编码器兼容性速查

8、错误处理

• 如果设备不支持目标编码器：自动降级 H.265 → H.264 High
• 低端机：强制 Baseline Profile + CBR
• 编码器创建失败：输出降级方案的代码

### 3.3 使用方式

在 Claude Code 会话中：

@encoder-config

我需要一个「短视频录制、1080p 30fps、iOS」的 H.265 编码器配置

Claude Code 会按 Skill 中的规则表直接输出：

```swift
// 短视频录制, H.265, 1080p 30fps, iOS
// 场景：画质优先，不需要极低延迟
// 码率：4.2 Mbps (H.264 6Mbps × 0.7)

let bitrate = 4_200_000
VTSessionSetProperty(session, kVTCompressionPropertyKey_RealTime, kCFBooleanFalse)  // 录制非实时
VTSessionSetProperty(session, kVTCompressionPropertyKey_AverageBitRate, bitrate as CFNumber)
VTSessionSetProperty(session, kVTCompressionPropertyKey_ExpectedFrameRate, 30 as CFNumber)
VTSessionSetProperty(session, kVTCompressionPropertyKey_MaxKeyFrameInterval, 60 as CFNumber)  // 2s I帧
VTSessionSetProperty(session, kVTCompressionPropertyKey_AllowFrameReordering, kCFBooleanTrue)  // 允许B帧，提升画质
VTSessionSetProperty(session, kVTCompressionPropertyKey_ProfileLevel, kVTProfileLevel_HEVC_Main_AutoLevel)
// ... 更多参数

9. Skill 进阶用法

9.1、一键生成双端对比代码

@encoder-config

帮我生成「直播推流、720p 30fps」的 iOS + Android 配置，要求左右对比

Skill 输出双端对照表 + 差异化提醒：

9.2、参数合理性检查

@encoder-config

检查这个 Android MediaCodec 配置有什么问题：
- 实时通话, H.264, 1080p
- BITRATE_MODE_VBR
- KEY_I_FRAME_INTERVAL = 1
- KEY_BIT_RATE = 5000000

输出诊断结果

Skill 会指出：

1. ❌ 实时通话应用 CBR 而非 VBR
2. ❌ I帧间隔 1 秒太短，实时场景建议 10 秒
3. ⚠️ 1080p 5Mbps 偏低，H.264 建议 3-4Mbps（实时场景实际 3Mbps 够用）

10、Claude Code 审查记录

11、Skill 使用效果

学习和提升音视频开发技术，欢迎你加入我们的知识星球