Community코딩 & 개발github.com

dolby-vision-hevc-transcode

用 x265 重编码 iPhone 拍摄的杜比视界 Profile 8.4(HLG 基础层 + RPU)视频,仅降低码率而完整保留 DV 动态元数据、10bit/HLG/BT.2020 色彩、分辨率、旋转矩阵与音频。适用于"把 DV 8.4 视频压小但保住杜比视界""x265 CRF 转码保 RPU""iPhone HDR 视频降码率"等任务。内含检测 DV 8.4、安装新版工具、批量转码与逐文件校验的完整工作流。

dolby-vision-hevc-transcode란 무엇인가요?

dolby-vision-hevc-transcode is a Claude Code agent skill that 用 x265 重编码 iPhone 拍摄的杜比视界 Profile 8.4(HLG 基础层 + RPU)视频,仅降低码率而完整保留 DV 动态元数据、10bit/HLG/BT.2020 色彩、分辨率、旋转矩阵与音频。适用于"把 DV 8.4 视频压小但保住杜比视界""x265 CRF 转码保 RPU""iPhone HDR 视频降码率"等任务。内含检测 DV 8.4、安装新版工具、批量转码与逐文件校验的完整工作流。.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/pliu2021/dolby-vision-hevc-transcode.skill/tree/main

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

杜比视界 8.4 视频保 RPU 重编码

用途

对 iPhone(12 系列及以上)拍摄的杜比视界 Profile 8.4 视频,用 x265 以 CRF 方式重编码只降码率,同时完整保留:

  • DV 动态元数据(RPU,逐帧)
  • DV Profile 8.4 配置(dv_profile=8、dv_bl_signal_compatibility_id=4)
  • 10bit yuv420p10le、HLG(arib-std-b67)、BT.2020 原色
  • 分辨率、时长、竖屏旋转矩阵(Display Matrix)、音频流

实测效果:4K60 片段 83108 Mbps 压到 315 Mbps,1080p 1026 Mbps 压到 0.62.6 Mbps,整体省约 90% 体积。

何时使用

在以下情形触发本 skill:

  • 用户要求压缩/转码杜比视界视频且明确要「保住杜比视界」「保留 RPU」「保留 HDR 动态元数据」
  • 用户要求给 iPhone HDR 视频降码率、减小体积但画质可接受
  • 遇到 x265 报 Unsupported Dolby Vision profile, only profile 5, 8.1 and 8.2 enabled
  • 转码后的视频 ffprobe 读不到 DOVI configuration record,但源文件有

核心原理(先看懂再动手)

DV Profile 8.4 = HLG 基础层(可独立解码)+ 逐帧 RPU 动态元数据,单层 BL+RPU、无增强层。三个关键事实决定了整套流程:

  1. x265 ≥ 3.6 才支持 profile 8.4(官方 3.6 release notes 明确 "Added Dolby Vision 8.4 Profile Support")。Debian bookworm 的 libx265 3.5 不支持,会直接报错。
  2. ffmpeg 的 -dolbyvision 1(libx265 编码器选项)会把输入帧的 RPU 自动传给 x265 注入,无需 dovi_tool 提取 RPU。但必须由支持 8.4 的 x265 来做。
  3. ffmpeg 重编码后不会写 dvvC/dvcC 配置盒。RPU 虽然在码流里(45 帧对应 45 个 RPU NAL),但播放器/ffprobe 认不出 DV。必须事后从源 MOV 复制 dvvC box 到输出的 hvc1 sample entry。

详细的技术细节、失败路径与实测数据见 references/technical_notes.md。

工作流

第 1 步:确认源视频确实是 DV 8.4

ffprobe -v quiet -print_format json -show_streams INPUT.MOV

检查视频流 side_data_list 里的 DOVI configuration record:dv_profile=8 且 dv_bl_signal_compatibility_id=4 才是 8.4。compat_id=1 是 8.1(PQ/HDR10 兼容),走的是另一条路,本 skill 不适用。

快速批量检查:

ffprobe -v quiet -select_streams v:0 \
  -show_entries stream_side_data=dv_profile,dv_bl_signal_compatibility_id \
  -of csv=p=0 INPUT.MOV    # 期望输出 8,4

第 2 步:确认 x265 版本 ≥ 3.6

ffmpeg -hide_banner -loglevel info -f lavfi -i color=c=black:s=64x64:d=0.1:r=1 \
  -frames:v 1 -c:v libx265 -f null - 2>&1 | grep 'HEVC encoder version'

低于 3.6 需要装新版静态 ffmpeg。不要替换系统自带的 ffmpeg(如飞牛 NAS 的 /usr/bin/ffmpeg 是指向 /usr/trim/lib/mediasrv/ffmpeg 的软链,属系统包,动它可能影响相册等服务)。正确做法:下载 BtbN 静态构建,放到 /usr/local/bin/ffmpeg(PATH 优先),系统原版保留。下载与安装步骤见 references/technical_notes.md。

第 3 步:单文件验证(必做,不要跳过)

先用最短的一个文件跑通全链路,确认 RPU 与配置盒都保住,再批量。

ffmpeg -noautorotate -i SRC.MOV \
  -map 0:v:0 -map '0:a?' \
  -c:v libx265 -preset slow -crf 29 \
  -pix_fmt yuv420p10le -fps_mode passthrough -dolbyvision 1 \
  -tag:v hvc1 \
  -color_primaries bt2020 -color_trc arib-std-b67 -colorspace bt2020nc \
  -x265-params 'colorprim=bt2020:transfer=arib-std-b67:colormatrix=bt2020nc:range=limited:vbv-maxrate=120000:vbv-bufsize=120000' \
  -c:a copy OUT.mov

关键参数说明:

  • -dolbyvision 1:让 ffmpeg 把输入帧的 RPU 传给 x265(核心)
  • -tag:v hvc1:Apple 生态兼容的硬性要求(否则 iPhone 相册/QuickTime 拒绝入库)。ffmpeg 默认输出 hev1,而 Apple 全系只认 hvc1(参数集必须带外存在 hvcC)。不加这个参数,视频在 ffprobe/VLC 正常,但 iPhone 相册无法导入。实测 iPhone 原片就是 hvc1。
  • -x265-params ...:dolby-vision-profile...:不要手动加 profile 参数,让 ffmpeg 自动从 RPU 推断;手动指定 8.4 在旧 x265 上会被拒绝
  • vbv-maxrate/vbv-bufsize:x265 启用 DV 的硬性要求(否则报 "Dolby Vision requires VBV settings to enable HRD");120000 kbps 足够宽松,不影响 CRF
  • -noautorotate:保留 coded 分辨率与 Display Matrix 旋转矩阵;默认的自动旋转会把 1920x1080 变成 1080x1920 并丢掉旋转标记
  • -fps_mode passthrough:保持帧数不变,VFR 视频尤其重要(帧数一变 RPU 就错位)
  • -c:a copy:音频不重编码,保持不变

编码后用 scripts/patch_dvvc.py 从源复制 dvvC box:

python3 scripts/patch_dvvc.py SRC.MOV OUT.mov

然后校验(见第 5 步),全部通过再批量。

第 4 步:批量转码

使用 scripts/transcode_dv84.py,支持断点续跑、逐文件校验、失败重转:

# 生成 manifest
python3 scripts/transcode_dv84.py --manifest SRC_DIR > manifest.json

# 后台批量执行(长任务用 nohup setsid,SSH 断开不影响)
nohup setsid python3 scripts/transcode_dv84.py \
  --run --manifest manifest.json --src SRC_DIR --out OUT_DIR \
  > run.log 2>&1 < /dev/null &

脚本会为每个文件:转码 → 补 dvvC → 13 项校验 → 写 state;已通过校验的文件重跑时自动跳过。

重要:日志、state、manifest 不要放在 /tmp(NAS/系统重启会被清空,导致无法断点续跑)。统一放到输出目录或持久工作目录。

第 5 步:校验(13 项)

每个文件必须全部通过:

  1. dv_8_4:输出仍有 DOVI configuration record,profile 8 / compat 4
  2. hvc1_tag:codec_tag_string == hvc1(Apple 兼容必需;hev1 会导致 iPhone 相册不入库)
  3. rpu_flag:rpu_present_flag=1
  4. rpu_per_frame:RPU NAL 数 = 帧数(用 ffmpeg -c copy -bsf:v hevc_mp4toannexb -f hevc - 数 type 62 NAL)
  5. frames:输出帧数 = 源帧数
  6. pix_fmt_10bit:yuv420p10le
  7. hlg_bt2020:transfer=arib-std-b67、primaries=bt2020
  8. resolution:分辨率不变
  9. rotation:Display Matrix rotation 与源一致
  10. duration:时长差 < 0.15s
  11. audio:有音频流
  12. smaller:输出体积 < 源文件
  13. decode_ok:完整解码 ffmpeg -v error -i F -f null - 返回 0——必须项,能抓出「元数据全对但实际损坏」的文件(faststart + dvvC 补丁的惨案)

验证 RPU 逐帧数的快捷方法(比全片解码快):

ffprobe -v quiet -select_streams v:0 -show_frames -read_intervals '%+#5' \
  -print_format json OUT.mov | grep -c 'Dolby Vision RPU Data'

性能提示:不要对几十个视频逐个做 ffmpeg -c copy ... hevc_mp4toannexb 全片解码(4K 大文件单个数分钟,23 个要 30+ 分钟,且易被超时打断)。批量复检时用 ffprobe 只读流元数据 + 抽样几帧即可,逐帧校验在转码当时做。

已转文件的修补流程(hev1 → hvc1)

对已经转码完成、但 tag 是 hev1 的文件,无需重编码,两步修补:

# 步骤 1:改 tag —— 绝对不要加 -movflags +faststart!
ffmpeg -i IN.mov -map 0:v:0 -map '0:a?' -c copy -tag:v hvc1 OUT.mov

# 步骤 2:从 iPhone 原片重新补 dvvC(改 tag 会丢掉它)
python3 scripts/patch_dvvc.py SOURCE_IPHONE.MOV OUT.mov

# 步骤 3:完整校验(不能只查元数据!见下)
ffprobe -v quiet -print_format json -show_streams OUT.mov   # tag=hvc1, dv compat=4
ffmpeg -v error -i OUT.mov -f null -                        # 必须 rc=0,无报错

🚨 两个致命陷阱(都实测踩过):

  1. -movflags +faststart 会毁掉文件。它会把 moov 移到 mdat 之前;此时再往 moov 里插入 dvvC box(32 字节)会把后面的 mdat 整体推移,而 stco/co64 的 chunk offsets 没同步更新 → 文件元数据看着全对(tag=hvc1、dvvC=1、DV 8.4 都在),实际解码损坏(ffmpeg -v error -i F -f null - 报 rc=69、RPU 归零)。修补时严禁 faststart;让 moov 保持在 mdat 之后(ffmpeg 默认布局),插入才安全。
  2. 改 tag 会丢 dvvC。-c copy -tag:v hvc1 会重建 sample entry,丢弃手工补入的未知 box(dvvC 计数 1→0)。所以改 tag 之后必须重新跑 patch_dvvc.py,顺序不能反。

校验必须包含完整解码:ffprobe 只看元数据发现不了上述损坏。务必跑 ffmpeg -v error -i OUT.mov -f null -,并确认退出码为 0。批量修补时对每个文件都做这一步。

根治方案是转码时就加 -tag:v hvc1,避免事后修补。

常见失败与处理

现象原因处理
iPhone 相册无法导入/不识别codec tag 是 hev1,Apple 只认 hvc1转码时加 -tag:v hvc1(根治)。已转好的用下方「已转文件的修补流程」——严禁加 -movflags +faststart
Unsupported Dolby Vision profile, only profile 5, 8.1 and 8.2 enabledx265 < 3.6换新版静态 ffmpeg(放 /usr/local/bin)
Dolby Vision requires VBV settings to enable HRD未设 VBV加 vbv-maxrate/vbv-bufsize
Unknown option: dolby-vision-rpu老 x265 不支持该参数用 -dolbyvision 1 自动传 RPU,不手动指定
输出有 RPU 但 ffprobe 读不到 DOVI conf缺 dvvC 配置盒跑 scripts/patch_dvvc.py
输出变成 1080x1920 且丢失旋转ffmpeg 自动旋转加 -noautorotate
帧数变化导致 RPU 错位时间戳重排用 -fps_mode passthrough
手改 dvvC 的 compat 4→1 骗 x265profile 标识来自 RPU NAL 内部,不是容器盒无效,必须用支持 8.4 的 x265

资源文件

  • scripts/patch_dvvc.py:从源 MOV 复制 dvvC box 到输出(整个流程最关键的补丁)
  • scripts/transcode_dv84.py:批量转码 + 校验 + 断点续跑
  • references/technical_notes.md:新版 ffmpeg 下载安装、DOVI box 结构、实测数据与失败路径

관련 스킬