adr

ADR — Automated Documentary Rendering

ADR 是一套自动纪录片生成管线。输入一个主题或带时间戳的台词，输出带画面、配音、字幕、BGM 的横屏或竖屏视频，并把过程状态和成片推送到 Telegram。

本 README 是 ADR 的产品契约：模式名、默认行为、质量兜底和禁止误触发规则必须和代码保持一致。每次改动 run_adr_v8.py 或 Telegram 启动器时，都要同步更新这里。

当前模式

重要边界：

• HADS/VADS 只表示"动态纪录片"，不等于现场记者。
• 只有显式传 --ads-reporter，或用户明确说"拟现场记者 / 战地记者 / dispatch / 第一人称记者 / POV 记者"，才进入记者 POV。
• --ads-dialogue 和 --ads-reporter 互斥；多角色对话优先。
• ADSD 走 step66 lip_sync，不参与 step65 motion；--no-motion 对 ADSD 无效。
• MTV 是独立音乐视频管线，不走普通旁白 TTS / Whisper 字幕时间轴；主音轨来自 WeryAI VOCAL_SONG。
• MTV 主唱通过 --singer <名字> 指定；如果主唱已存在于 voice_assets/speaker_ips/，直接复用人物卡和绑定音色；如果不存在，自动孵化人物卡并写入人物库。
• MTV 默认烧录歌词字幕；先用歌曲 ASR 建立“声音/字幕/视频”共享时间轴，再按该时间轴生成前奏、歌词和尾奏镜头；人声段默认尝试歌曲音频驱动 lip-sync（ADR_MTV_LIP_SYNC=0 可关闭），失败时降级普通动效；可用 ADR_MTV_SUBTITLES=0 关闭字幕。

默认策略

架构

主题 / 台词输入
  |
  |-- Step 1: 剧本、考证、分镜
  |   |-- 题材分析：文化、地域、年代、服饰、负面禁令
  |   |-- 台词生成或外部台词解析：支持带时间戳文本
  |   |-- 历史顾问：校准时代视觉，避免文化和年代穿帮
  |   |-- 分镜提示词：画面、角色、镜头、情绪、动作
  |
  |-- Step 2: 配音 / 音色
  |   |-- 普通 ADR：Podcast/TTS 生成整段音轨
  |   |-- ADSD：逐 turn 配音，支持口型同步
  |   |-- WeryDance audio-dub：可用音色资产参考音频完成视频内配音
  |
  |-- Step 3: 时间轴
  |   |-- Whisper 字级时间戳
  |   |-- 外部带时间戳台词优先
  |   |-- 字幕、画面、音频按分镜对齐
  |
  |-- Step 4: 故事板
  |   |-- GPT Image 2 单镜故事板
  |   |-- 4K storyboard grid / 多 storyboard fallback
  |   |-- crop QA，避免切到相邻格
  |
  |-- Step 5: 静态画面和封面
  |   |-- 分镜图并发生成
  |   |-- 失败重试，必要时重写 prompt
  |   |-- Telegram 图片审批可选
  |
  |-- Step 6.5: WeryDance 动态化
  |   |-- clean keyframe 优先，其次 annotated storyboard 实验模式
  |   |-- 每镜头 motion prompt + 动作计划 + 可选终点参考
  |   |-- 失败镜头保留静态兜底，不中断整片
  |
  |-- Step 7: 合成
  |   |-- ffmpeg 拼接视频
  |   |-- WeryDance 字幕优先，ASS 字幕兜底
  |   |-- 配音、BGM 混音
  |
  `-- Step 8: QA 和交付
      |-- motion_qa.json
      |-- storyboard / crop / caption / voice QA
      |-- Telegram 推送成片和文案

快速开始

export WERYAI_API_KEY="your-key"
export TG_BOT_TOKEN="your-bot-token"
export TG_CHAT_ID="your-chat-id"

python3 run_adr_v8.py "1924年泰戈尔访华" h
python3 run_adr_v8.py "黄仁勋CMU毕业演讲核心内容" h
python3 run_adr_v8.py "1915年二十一条最后通牒" v --ads-reporter
python3 run_adr_v8.py "AI时代就业市场访谈" h --ads-dialogue
python3 run_adr_v8.py "江南春日风物" v --bgm-only
python3 run_adr_v8.py "曹操的短歌行" hmtv --singer 曹操
python3 tools/mtv_sync_audit.py /tmp/adr_v8_xxx
python3 run_adr_v8.py "唐宋八大家" h --no-motion          # 罕用：HADR 静态分镜

常用参数

关键环境变量

2026-09-06 同 prompt 主创 A/B：GPT_5_6_SOL 在 22 镜视觉 JSON 中实现 22/22 对象、8/8 字段及所有 enum/字数/首尾约束通过；CLAUDE_FABLE_5 有超长与截断，CLAUDE_4_8_OPUS 出现间歇 5xx，因此未设为首选。判断档另以 180/200/300/600/800 token 的五类生产近似任务对照：GEMINI_3_7_FLASH 5/5 正常停止且格式通过，GEMINI_25_FLASH 4/5（严格 JSON 出现 Markdown fence）。

文本降级配置优先级为：调用点显式 fallback_models > 全局多值 ADR_CHAT_FALLBACK_MODELS > 旧单值 ADR_CHAT_FALLBACK_MODEL > 主创/判断分档默认链。5xx 与模型下线错误会推进到下一模型；429 只在当前模型退避，不跨模型。Vision 同样遵循 429 原模型退避策略。

Telegram 进度策略

默认 dashboard 模式下，ADR 只发一条可编辑进度面板，后续用 Telegram editMessageText 原地更新，类似软件安装进度：

• 面板内容：主题、阶段、百分比、进度条、当前状态、最近日志、更新时间。
• 强制刷新：启动、剧本、主音轨、故事板、动态化、合成、发布门禁、成片、耗时统计、告警和错误。
• 限频刷新：普通过程日志最多每 8 秒编辑一次，避免 Telegram API 限流。
• 最终视频、封面、社媒文案、复制按钮仍单独发送，因为这些是交付物，不应该被进度面板覆盖。

compact 模式保留为备用，会把过程信息分为三层：

• 立即发送：启动、剧本完成、主音轨完成、故事板完成、动态化启动/完成、视频拼接、发布门禁、最终成片、耗时统计、所有告警和错误。
• 合并摘要：单张图完成、单个分镜动态化成功、Podcast task_id、轮询类信息、重复审批进度。
• 本地日志：所有细节仍写入 stdout/log，调试时可设 ADR_TG_PROGRESS_MODE=verbose 恢复全量推送。

目标是让 TG 对话框里能直接看到“现在跑到哪、有没有风险、最终文件在哪里”，不需要在几十条过程消息里捞结果。

音色资产库

音色资产配置位于 voice_assets/voice_assets.json。当前库中包含候选资产：

• external_luo_xiang_xyma_001：罗翔，默认男声。
• external_by2_e7gn_001：BY2，默认女声。
• external_xu_zhiyuan_xyma_001：许知远，访谈/文化类备选。
• external_huang_renxun_fzh_001：黄仁勋，英文科技领袖演讲备选。

外部人物声音默认只允许内部测试和分析；公开发布、商业用途、拟真冒充必须另行做权利审查。

QA 检查点

每次改管线后至少验证：

• python3 -m py_compile run_adr_v8.py
• HADS/VADS 不带 --ads-reporter 时，日志必须显示 HADS/VADS（或 --no-motion 下 HADR/VADR），不能出现"拟现场记者"。
• motion_qa.json 里应记录参考图数量、字幕策略、音色策略。
• storyboard crop QA 不能把两个分镜切在同一张输出里。
• WeryDance 字幕失败时，ASS 兜底必须仍能合成。
• 自定义音色任务要检查声音性别、画面人物性别、台词内容三者一致。

README 更新规则

README 只写已经落地并通过基础 QA 的能力，不写愿景。每次新增默认开关或改变模式含义时，要同步