粤语配音字幕成片

概述

输入：一个目录里的若干短视频（多为纯画面、无原声的手机竖屏素材）。
输出：每段一条成片 mp4（= 原画 + 粤语配音音轨 + 烧入画面的粤语字幕），另附该段的粤语配音 mp3 与粤语 srt。

适配场景：任意行业的推广素材要发粤语区（广东、中国香港）时，批量做"粤语版"——门店、餐饮、美容美发、教育、电商、知识付费、产品推广、个人 IP 等；素材类型不限，只要是无原声的短视频。技能本身不预设行业口径，旁白写什么完全由当次素材与用户要求决定。

一、环境准备（Windows）

1. ffmpeg：用 Python 包自带，省得找下载链接：
   powershell & <venv>\Scripts\pip.exe install imageio-ffmpeg
   二进制路径由 imageio_ffmpeg.get_ffmpeg_exe() 得到。该 build 已含 libass（ass/subtitles 过滤器）与 libx264，足够烧字幕；但不含 ffprobe——时长/分辨率要靠 ffmpeg -i 的 stderr 正则解析。
2. 粤语 TTS：pip install edge-tts（免密钥，联网即可）。粤语声线：
   - 女声 zh-HK-HiuGaaiNeural（默认推荐）
   - 女声 zh-HK-HiuMaanNeural
   - 男声 zh-HK-WanLungNeural
3. 中文字体：烧中文字幕必须给 CJK 字体，否则方块。Windows 自带 C:\Windows\Fonts\simhei.ttf（黑体）。

二、关键实测参数（务必先算稿长）

• 粤语 TTS 语速 ≈ 3.0 字/秒（rate=+0%，含标点停顿）；rate=+8% 时 ≈ 3.24 字/秒。
• 稿字预算 ≈ 视频秒数 × 3.2（配 rate=+8%）。旁白只能短不能长：短了补尾静音无所谓，长了要么加速（伤听感）要么被截断。
• 例：16s 视频 ≈ 50 字；82s ≈ 260 字；28s ≈ 90 字；24s ≈ 76 字；17s ≈ 55 字。
• "激情/情绪"三旋钮（edge-tts 免费通道没有情感参数，style 只有 Azure 付费语音才有）：
• rate 语速：默认 +8%；要更有劲用 +20%~+30%。
• pitch 音调：默认 +0Hz；提亮、更"冲"用 +2Hz~+5Hz（提太多会假）。
• voice_volume 配音音量：默认 +0%；+5%~+10% 更响更冲（其后还会经 ffmpeg volume=1.8 放大 + 限幅）。
• 三者叠加即"更有激情"；通常"语速提升 + 音调小提"最自然。
• 逐句合成后拼接，靠每句尾自然静音当停顿，不必另插空白；如需更清晰停顿再加 0.2–0.35s 静音。

三、字幕样式（"大 + 红字白边 + 黑体"花字感）

生成 ASS（比 SRT+force_style 稳，PlayRes 可控）：

[Script Info]
ScriptType: v4.00+
PlayResX: <视频宽>
PlayResY: <视频高>
WrapStyle: 0
ScaledBorderAndShadow: yes
[V4+ Styles]
Style: Default,SimHei,<fs>,&H000000FF,&H000000FF,&H00FFFFFF,&H80000000,-1,0,0,0,100,100,0.6,0,1,5,3,2,<ml>,<ml>,<mv>,1

• fs（字号）= 视频宽 × 0.080（够大；一屏约 10–12 字，长句自动折成 2 行）
• 位置：Alignment=2（底对齐）+ MarginV 抬升，mv（MarginV）= 视频高 × 0.35 → 中下偏底（1080×1920 约 672px、720×1280 约 448px）。⚠️ 善思兄要求中下偏底（2026-09-18 由 0.42 中下再往下调一点），不要贴底；如需贴底则 mv=高×0.097。
• ml（左右安全边距）= 宽 × 0.05，防出安全区
• 颜色：PrimaryColour=&H000000FF（红）、OutlineColour=&H00FFFFFF（白边）、BackColour=&H80000000（半透明黑阴影兜底）
• Bold=-1、Outline=5（白描边）、Shadow=3（黑阴影）→ 花字感、任何底色都清晰
• 文案规范：旁白稿用【繁体粤字】（唔／咗／嘅／啲／嚟／喺／係／冇／睇／哋／咁／靚…）；字幕显示时去标点（strip_punct，含全角括号「」『』（）()【】等），但 TTS 输入保留标点以保停顿语感。
• 音量：配音用 -af "volume=1.8,alimiter=limit=0.99" 放大（善思兄要求"再大一点"），alimiter 防削波。

> ★ 以上样式全部可配置（v2.3 起）：通过 config 的 subtitle 块自定义，给用户自行设计空间——
> json > "subtitle": { > "color": "red", // 预设 red(红字白边,默认) / white(白字黑边) / yellow(黄字黑边) / custom > "custom_color": "&H000000FF,&H000000FF,&H00FFFFFF,&H80000000", // color=custom 时填(主,次,描边,阴影) > "font_scale": 0.08, // 字号=屏宽×此值（越大字越大） > "font": "C:/Windows/Fonts/simhei.ttf", > "font_name": "SimHei", > "position": 0.35 // 距底比例（越小越贴底） > } >
> 也可在单个 clips[] 里覆盖（只对那一条生效）。不设则全部走上面默认值。

四、压片命令（烧字幕 + 加音轨）

关键坑：Windows 路径的冒号在 ffmpeg filter 里要转义很麻烦 → 直接把工作目录设为 cwd，用相对文件名：

# cwd = 工作目录（内含 subs.ass 与 fonts/simhei.ttf）
ffmpeg -y -i <原视频绝对路径> -i narration_fit.wav `
  -vf "ass=subs.ass:fontsdir=fonts" `
  -map 0:v -map 1:a `
  -af "volume=1.8,alimiter=limit=0.99" `
  -c:v libx264 -preset medium -crf 20 -pix_fmt yuv420p `
  -c:a aac -b:a 192k -movflags +faststart <输出.mp4>

• -af "volume=1.8,alimiter=limit=0.99"：配音音量放大 + 防削波（成片与 mp3 都加）。

• fontsdir=fonts 指向放着 simhei.ttf 的目录，确保 libass 找得到中文字体。

• 画面分辨率不变（竖屏保持竖屏）。

五、时长对齐（防"音比画长"）

1. 逐句合成 → 转 wav → 量每句时长 → 求和 total。
2. total > 视频时长：atempo = min(total/vdur, 1.30)，并加 -t <vdur> 兜底。
3. total ≤ 视频时长：apad -t <vdur> 补尾静音到视频长度。
4. 字幕时间轴按每句时长累加；句中按标点切分并按字数比例分配时间；末条 end ≤ vdur-0.05。

六、输入契约与提问规范（★必须遵守）

输入至少要有一样（两样都有最准）：

看不懂、拿不准时——必须问，不许瞎猜

• 画面模糊、看不清是什么行业/产品/场景 → 先问，别硬编。
• 旁白口径不确定（是否点品牌名、是否引导到店/私信、面向哪种客户）→ 先问。
• 时长与稿量不确定 → 按"秒数×3.2"先算，落差大再确认。
• 原声怎么处理不确定 → 按"§六之三"给选项问（抹掉／保留／压低做背景）。

提问方式：给选项让用户选，最后一项固定"其他"

用选择式提问（如 AskUserQuestion），每题给 2–4 个具体选项，让用户点选即可：

• ✅ 好：「这条片主要想讲：A 门店环境 / B 产品细节 / C 顾客案例 / 其他」
• ❌ 差：空泛地问「你想讲什么？」——用户还得自己想，等于没帮上忙。

「其他」留自由输入，兜住选项没覆盖的情况。能一次问清就一次问完（单次最多 4 题），别来回挤牙膏。

六之二、写稿方法论（★技能自带能力）

有视频就看懂画面再写；没视频就按用户给的行业/场景写。按下面五步出稿：

1. 先定三件事（拿不准就问，见上）

• 说什么：主题（门店/产品/案例/知识/日常…）
• 对谁说：客户画像（街坊、年轻人、求职者、宝爸宝妈…）
• 要他做什么：行动引导（私信／到店／留言／关注／无引导）

2. 结构：钩子 → 内容 → 引导

• 首句当钩子：3–6 秒内抓住注意力。用提问、反差、痛点开头。
• 提问式：「你知唔知点解……」　反差式：「呢件嘢睇落平平無奇……」　痛点式：「越嚟越疏，越嚟越闊……」
• 中段给实料：按画面/卖点分点讲，一句一个信息，别堆砌。
• 尾句给引导：一句行动号召（有品牌名就点品牌名）。

3. 语言：说人话、说粤语

• 口语化，写出来要顺口、听着不别扭；不写书面腔（"本产品采用……" ✗）。
• 用繁体粤字：唔／咗／嘅／啲／嚟／喺／係／冇／睇／哋／咁／靚／傾／擺／咁樣。
• 一句一事，句子要短（长句听着累）；TTS 稿可带标点帮断句，字幕显示时自动去标点。
• 少量英文术语可以（食材名、品牌英文名），但别整句英文。

4. 控字数（关键，写前先算）

• 预算 = 视频秒数 × 3.2 字（配 rate=+8%）。
• 只短不长：短了自动补尾静音；长了要被加速（伤听感）或截断。
• 拿 16s 视频举例：预算约 50 字 → 拆 4–5 句，每句 10–12 字最舒服。

5. 按画面切句（有视频时）

• 一个画面/一个动作配 1–2 句，别让一句话跨太多镜头。
• 关键画面（前后对比、产品特写）要给足句子，别一带而过。

6. 合规自检（写完后过一遍）

• 涉及医疗/药品/保健品/金融/教育/美容功效等行业时，按使用者行业与平台规则把关——不写疗效、收益、升学率、绝对化用语（"最""第一""包治"）。
• 技能不预设禁用词表，只提醒：发布前由使用者核对自己行业的红线。

六之三、原声处理（★技能自带能力）

素材本来有原声（说话声、环境音、BGM）也能用——配音时按需要处理原声：

• 可写在全局（对所有片段生效）或单个片段里（覆盖全局）。
• 素材本身无音轨时自动按 off 处理，不会报错。
• 脚本用 -map 0:v -map 1:a 只取画面+新配音实现"抹掉"；keep/duck 走 amix 混音。
• 拿不准用户要哪种 → 给上面三个选项问。
• ⚠️ 实测要点：部分素材的音轨是空轨／近乎静音（实测见过 -91dB 的纯静音轨，也有 -26dB 的正常原声）。空轨素材下三种模式听感相同，不是功能失效——用 volumedetect 看原素材 mean_volume 即可判断；或看输出码率（off≈14kb/s，duck/keep 明显更高）。

6.4 字幕样式 / 声线 / BGM 选项菜单（可选提问，★必含「原生默认」项）

生成视频前，若用户没明确指定样式／声线／BGM，可主动用 AskUserQuestion 给一个选项菜单，让用户自行设计；每个选项菜单都必须含「原生默认」项——不选就走下表默认配置，外观和旧版完全一致。

• 各项映射到 config 的 subtitle / gender / bgm.by_gender（见 §三、§8.2、§8.3）。
• 原生默认 = 不填这些字段时脚本的自动行为：红字白边、中下偏底 0.35、女声、无 BGM——即 v2.2 及之前版本的默认外观，保证「用户不挑就还是老样子」。
• 用户挑了就写进 config 覆盖默认；没挑就不写，脚本走原生默认。
• ⚠️ 菜单提问一律用【普通话】：用这个技能的人（运营/店主）通常不会粤语，菜单是给他看的——绝不能用粤语词（如「几大」）或粤语短句来问；选项标签、说明全部用简体普通话、通俗直白（写「字号要多大」，不要写「要几大」）。粤语只用在成片内容里（旁白稿 + 字幕），不要用在跟用户的交互上。

• 提问时把「原生默认/（默认）」放在第一项并标注，用户可直接选默认跳过；用户一次没答完的项，不要反复追问第二遍，缺的项直接走原生默认，最后一句说明「其余按默认，要改随时讲」。

• 菜单做成可视化预览：给用户看选项时，优先用内联可视化图（手机预览 + 颜色/字号/字体/位置四项的字形样例 + 声线/BGM 一行）直接画出每项字幕长什么样，比纯文字卡片更直观；用户不读说明也能挑。可视化图里把「原生默认」项用醒目标记（如紫色框）标出。

七、工作流

1. （有视频）列素材目录 → ffmpeg 抽关键帧 → 多模态看懂画面；
   （无视频）读用户给的行业/场景/时长。
2. 拿不准先按"提问规范"发选项问（含原声如何处理）；确认后按"写稿方法论"写粤语旁白稿。
3. 跑 scripts/dub_cantonese.py（读 JSON 配置）生成 mp3/srt/mp4。
4. 抽帧复核字幕渲染（红字白边/大小/位置/无方框）；确认音轨（原声是否按要求处理）。

八、扩展能力（v2.0 新增）

8.1 自动拼合集（compile 配置块）

把各段成片用 xfade 转场串成一条合集，可选加片头/片尾纯色文字卡：

"compile": {
  "enabled": true,
  "title": "品牌名_粤语合集",
  "order": null,
  "transition": "fade",
  "transition_dur": 0.6,
  "intro": {"enabled": true, "duration": 2.5, "text": "品牌名", "sub": "副标题", "color": "0x111111"},
  "outro": {"enabled": true, "duration": 3.0, "text": "引导语", "sub": "补充行", "color": "0x111111"}
}

• 转场 transition 可选：fade／dissolve／wipeleft／wiperight／slideleft／slideright／fadeblack／circleopen 等（对应 ffmpeg xfade 的 transition 名）。
• 实现要点：①各段先 scale+pad+setsar=1+fps=30 统一规格，否则 xfade 报尺寸不符；②用 xfade 叠画面、acrossfade 叠声音；③offset 按累计时长 − 转场时长递推。
• 片头/片尾卡用 lavfi color 源 + drawtext 生成。⚠️ drawtext 不吃 fontsdir，字体必须给绝对路径（Windows 盘符冒号要转义成 C\:/...），否则中文渲染成白色方框（已实测踩到）。脚本已按此处理。
• ⚠️⚠️ 更隐蔽的一坑：drawtext 的字体路径不能含非 ASCII 字符。若 out_dir 是中文名（如「粤语成片/微信视频_案例A」），沿用 work/fonts/simhei.ttf 这种带中文的路径会照样渲染成方框，而 libass 烧字幕却不受影响（所以字幕正常、只有卡片方框，极易误判为"卡片功能坏了"）。判据：同样内容输出 PNG，方框版体积明显偏小（实测 6950B vs 18680B）。脚本已加 _ascii_font_path()：路径含非 ASCII 时自动把字体复制到纯 ASCII 临时目录再用。

8.2 背景音乐（bgm 配置块）

"bgm": {"file": "C:/music/bgm.mp3", "gain_db": -18}

• BGM 自动 -stream_loop -1 循环铺满全长，按 gain_db 压低（默认 −18dB）后用 amix 与人声混合，不抢人声。
• 只作用于配音音轨（成片与导出的配音 mp3 都带 BGM）。

8.3 换声线（voice 字段）

改 voice 字段即可整批切换。

声线之外的"表现力"三旋钮（顶层 config）：rate（语速）/ pitch（音调）/ voice_volume（配音音量）。粤语免费通道（edge-tts）无情感参数，靠这三项叠出「激情」；要真情感见 §8.5 第三方引擎。voice 可 clip 级覆盖；rate/pitch/voice_volume 为整批统一。

8.4 自动读视频分析画面（脚本内置，可选）

适用于「有视频、懒得自己写稿」：clip 只要给 file + title（不写 sentences），脚本会：
1. ffmpeg 均匀抽 vision.frames 帧；
2. 调视觉大模型（OpenAI 兼容接口，可接 OpenAI / DeepSeek / 通义千问VL / 智谱GLM-4V 等）看懂画面；
3. 自动写出繁体粤字旁白稿（按 §三 / §六之二 规范），继续走配音→烧字幕→拼片。

"vision": {
  "key": "视觉模型API密钥",
  "base_url": "https://api.openai.com/v1",   // 各家填对应地址
  "model": "gpt-4o",                          // 支持视觉的模型名
  "frames": 6                                 // 抽帧数
}

• 也可在单个 clip 写 "script_hint" 给视觉模型额外提示（如行业、要突出的点）。
• 缺 vision 配置且 clip 没写 sentences → 脚本给清晰中文报错，不会瞎编。
• ⚠️ 无视频时不能自动：没视频就必须手动写 sentences 或给文字说明（见 §六）。自动分析依赖画面帧，纯文字需求走手动写稿。
• ⚠️ 视觉接口非免费：需自备 key，且画面理解质量取决于所用模型——复杂画面（如多产品对比）建议仍人工看帧写稿，或先用 script_hint 兜底。

8.5 第三方语音引擎（v2.5 新增：免费 + 情感控制）

默认 provider="edge-tts"（微软免费通道，无情感参数）。要真正有情绪起伏的粤语配音，可切到以下【真正免费】的第三方——都有免费额度/免费试用，官方面板领 key 即可，免信用卡：

切换方式（顶层 config 加一行，clip 可覆盖）：

"provider": "fish-audio",
"emotion": "excited"

key 从哪领（设为环境变量）：
- fish-audio → FISH_AUDIO_API_KEY：fish.audio → Settings → API Keys（免费额度、免信用卡）。
- minimax → MINIMAX_API_KEY：minimax.io 开放平台 / 或 TokenFaucet 每日免费额度。
- cosyvoice → DASHSCOPE_API_KEY：阿里云百炼控制台（需 pip install dashscope）。

⚠️ voice 字段各家语义不同：edge-tts 用 zh-HK-*；切第三方必须换成对应平台音色 id，否则报错。
⚠️ 情感标签只在第三方 provider 生效：edge-tts 仍只认 rate/pitch/voice_volume 三旋钮（无 emotion）。
⚠️ 免费≠无限：都有额度/并发限制，大批量请错峰或自备 key。

8.6 美颜 + 美体后期（v2.x 新增，与国语版共用 scripts/video_beauty.py）

config 顶层可开 beauty / body 两个工序，都关（默认）时零开销，在烧字幕之前作用于画面。

• 美颜（ffmpeg，无依赖，稳）：磨皮（hqdn3d 皮肤降噪）＋提亮/增白/微增饱和＋锐化保细节。字段：beauty.enabled / smooth(磨皮强度,默认9.0) / brightness(0.10) / contrast(1.06) / saturation(0.90) / sharpen(0.45) / strength(cas 对比度自适应锐化,0=关,0.4~0.9 常用,恢复纹理且不炸噪点)。⚠️ 清晰度增强用 cas（本机参数名 strength，非 amount）：素材偏肉/磨皮发糊时设 strength:0.7 找回毛发针脚细纹理，噪点控制远优于 unsharp；cas 放提亮之后。
  json "beauty": {"enabled": true, "smooth": 6.0, "brightness": 0.10, "contrast": 1.06, "saturation": 0.90, "sharpen": 0.45, "strength": 0.7}
  ⚠️ 旧版 gblur+blend 方案在 1080p 上肉眼几乎看不出，已换 hqdn3d；强度要给到用户看得出来。
• 美体（OpenCV 几何瘦体，非 AI）：针对竖屏半身/口播画面——腰部收窄（body.slim，中部一条带向中轴收拢）＋腿部拉长（body.leg，下半部纵向拉伸）。
  json "body": {"enabled": true, "slim": 0.15, "leg": 0.08}
  ⚠️ 这是与内容无关的几何变形，不识别人体；真正的"认人瘦体"需 MediaPipe 人体关键点，后续可升级。
• ⚠️ 本机 ffmpeg 不吃 -map "[标签]" 和单引号表达式，滤镜链不挂输出标签、不写 -map（已写进 video_beauty.py）。
  ⚠️ 粤语覆盖：鱼声、MiniMax（挑 Chinese (Cantonese) 音色）、CosyVoice（支持粤语方言）均可出粤语；到各平台声音库挑「粤语/广东话」项即可。

8.6 整文件夹自动扫描（auto_scan，v2.7 新增）

最省事的用法：不用一条条列 clips。把一批竖屏视频丢进一个文件夹，脚本自动扫出里面所有视频，逐条出粤语成片。

{
  "src_dir": "C:/Users/你/Desktop/素材文件夹",
  "out_dir": "C:/Users/你/Desktop/粤语成片",
  "auto_scan": true,
  "vision": { "key": "...", "base_url": "...", "model": "gpt-4o", "frames": 6 },
  "voice": "zh-HK-HiuGaaiNeural"
}

• auto_scan: true 时脚本忽略 clips 数组，改为扫描 src_dir 下所有视频（默认支持 mp4/mov/avi/mkv/webm/m4v/flv，大小写不敏感；想加别的扩展名用 scan_ext 字段，如 ["\.mp4", "\.mov"]）。
• 每条视频的 title 默认取文件名（去扩展名）——所以扫之前把素材命名好（如「门店环境.mp4」「术后对比.mp4」），成片文件名才好看；否则会用源文件名（可能是哈希串）。
• 全自动写稿：配了 vision 块（OpenAI 兼容接口，见 §8.4）时，每条视频自动抽帧、看画面、写繁体粤字旁白，全程无需手动写 sentences。
• 想手动微调某条：仍可在 clips 里写覆盖项，用 "file": "源文件名.mp4" 对应回去，覆盖 title / sentences / gender / voice / original_audio 等，其余视频照常自动扫出。
• 批量容错（不怕半路挂）：逐条独立处理，某条视频出错（如没写稿也没配视觉、或某句 TTS 限流）只跳过那一条并中文报告，同目录其他视频照常出片；结尾日志会写「成功 N 条，跳过 M 条」。整批全失败时才会友好退出并提示查日志。
• ⚠️ 扫到的视频若既没写 sentences、又没配 vision，该条会被跳过（不会瞎编稿）——配 vision 或补 sentences 即可。

8.7 视频号封面自动生成（cover，v2.8 新增；v2.8.3 改主流版式）

出片时自动生成封面（封面失败不影响成片）。做法：从原视频抽一帧作底图，文字直接排在画面上，输出两种主流规格：

• {title}_封面_9x16.jpg（1080×1920）：竖屏封面，与竖屏视频同比例；
• {title}_封面_1x1.jpg（1080×1080）：正方形，用于信息流的卡片缩略。

版式（v2.8.3 起，对齐当下主流封面）：

• 不加任何黑白底条、不加投影阴影（v2.8.0–2.8.2 那种上下半透明黑条的做法已废弃）；
• 白字居中排布，主标题在上、副标题紧跟其下（不是一上一下顶着画面两头）；
• 只保留一圈极细深色描边（1080 宽下 3px）——这不是阴影，是主流字幕标配，否则白字压白墙看不清；cover_stroke: 0 可完全关掉；
• 文字块默认落在画面偏上（主标题约 13% 高度处），既醒目又不压主体；露脸素材仍按 cover_time 挑五官在中间的画面，保证不挡脸。

每条 clip 可加（示例）：

{"file": "01.mp4", "title": "01_案例",
 "cover_title": "一句话点出卖点",
 "cover_subtitle": "专业服务 · 自然效果",
 "cover_time": 0.4}

• cover_title：主标题（大号白字，排在上方）；缺省用 title；支持 \n 手动换行（长标题建议拆两行）。
• cover_subtitle：副标题（小一号白字，紧跟主标题下方）；缺省用顶层 cover_subtitle。⚠️ 副标题必须写跟视频内容/品牌相关的卖点（如「美丽共感 · 纹发加密」「门店实拍 · 当日现做」）——绝不能用「粤语配音 · 视频成片」这类工具功能名（2026-09-25 用户明确批驳：没有任何行业会把剪辑工具的功能写到自己成片封面上；缺省兜底文案只作占位，交付前必须替换成内容相关文案或干脆留空不写副标题）。
• cover_time：抽帧时刻，按视频时长比例 0~1，默认 0.4（约 40% 处，一般能取到主体最清楚的画面）；想换画面就调它（0.1 取开头 / 0.8 取结尾）。
• cover_pos：文字块位置，top（默认，偏上）/ center / bottom（贴下）。
• 尺寸字号微调（都有默认值，一般不用写）：cover_title_scale（主标题字号占画面宽比例，默认 0.078）、cover_sub_scale（副标题，默认 0.046）、cover_top（文字块距顶比例，默认 0.105；cover_pos:bottom 时用 cover_bottom，默认 0.90）、cover_stroke（描边像素，默认 3，0=不描边）。
• 字体：优先 C:/Windows/Fonts/msyhbd.ttc（微软雅黑粗体，实际存在的就是这个 ttc），缺失依次回退 msyhbd.ttf / simhei.ttf / msyh.ttc。
• 关闭：顶层写 "cover": false 即不出封面。

⚠️ 封面文字用简体中文：封面面向朋友圈/关注页的泛读者，简体更通用；视频内的粤语旁白与字幕照旧用繁体粤字。

auto_scan 也支持封面——扫到的每条视频若无 cover_title，主标题就用文件名（去扩展名），副标题用默认。

九、容易踩的坑

• 抽关键帧拼图：单张 PNG 输出必须加 -frames:v 1 -update 1，否则报 "does not contain an image sequence pattern"。
• drawtext（片头尾卡/水印）字体路径不能含中文：输出目录是中文名时，字体路径也会带中文 → 中文渲染成方框（libass 字幕不受影响）。脚本已自动转 ASCII 临时路径；手工写 ffmpeg 命令时也要注意，或直接把字体放 ASCII 目录。
• 输出目录要先建：ffmpeg 不会自动建目录，写进不存在的目录报 "Could not open file"。
• 合规（交给使用者拿捏，技能不预设行业限制）：本技能泛行业通用，不写死任何行业的禁用词表。旁白用词由当次素材所属行业与投放平台法规决定——例如医疗、药品、保健品、金融、教育培训、美容功效等在多数平台有专门限制（如不得宣称疗效、收益、升学率等），产出前须由使用者按自身行业与平台规则把关。技能只负责"配音准确、字幕规范、成片合规交付"，不对内容做行业化删改。
• 本机有"批量删除确认"拦截（safe-delete hook）：脚本里 shutil.rmtree(工作目录) 会触发 SAFE_DELETE_BULK_CONFIRM_REQUIRED 并中断整个脚本（EXIT=1）。→ 不要 rmtree，改覆盖式写入（同名文件被 -y 覆盖即可）。
• config.json 路径千万别用反斜杠 \：从资源管理器复制的 C:\Users\xxx\Desktop 直接粘进 JSON 会炸 JSONDecodeError: Invalid \escape（看不懂）。一律改正斜杠 /，如 C:/Users/xxx/Desktop。v2.6 起脚本会抓这个错并提示"Windows 路径用了反斜杠，请改正斜杠"。
• 脚本报错都是中文、不甩堆栈（v2.6 起）：缺必填字段 / 视频文件找不到 / 第三方缺 key / 无文案又没配视觉，都会打印 【错误】… 一行中文要点后干净退出，完整堆栈只在 out_dir/_cwork/progress.log 留底，不会吓人。
• edge-tts 偶发失败：批量跑时某句 TTS 可能超时／限流抛异常，令整批中断。→ 单条重跑（传 clipIndex / 单个 clip）即可，已成功的文件不受影响。
• 本机 PowerShell 工具 stdout 不回显 → 所有命令把结果写日志文件再 Read。
• Git Bash 在本机不可用（dirname/which 缺失）→ 一律走 PowerShell。
• 打包上传技能平台必须是"两级目录"（v2.8.2 实测坑）：多数技能市场校验 zip 结构，只接受「根目录/二级目录/文件」，出现第三层（如 技能名/SKILL.md、assets/bgm/x.mp3）会报「目录层级超限 — 请移除子目录嵌套」而解析失败。两条铁律：① zip 根目录直接放 SKILL.md，不要在外面再裹一层技能名文件夹；② 技能内最多只能有一层子目录（scripts/、examples/、assets/），不要再往下建子目录。v2.8.2 已把 assets/avatar/*、assets/bgm/* 全部拍平到 assets/ 下。
• 跑 dub_cantonese.py 要用装了依赖的那个 python（v2.8.1 实测坑）：脚本需要 PIL + edge_tts + imageio_ffmpeg 三个库。managed python（C:\Users\Administrator\.workbuddy\binaries\python\versions\3.13.12\python.exe）装了 imageio_ffmpeg 但缺 PIL，直接跑报 ModuleNotFoundError: No module named 'PIL'；应改用 venv 的 C:\Users\Administrator\.workbuddy\binaries\python\envs\default\Scripts\python.exe（三库齐全）。换机若缺库先 pip install pillow edge-tts imageio-ffmpeg。
• 本机字体只有 msyhbd.ttc，没有 msyhbd.ttf（v2.8.3 实测）：旧代码写死 msyhbd.ttf（不存在）→ 静默回退成 simhei.ttf 黑体。v2.8.3 起按 msyhbd.ttc → msyhbd.ttf → simhei.ttf → msyh.ttc 顺序找，优先拿到微软雅黑粗体。
• 封面版式别退回"上下黑条"（v2.8.3 用户明确否掉）：用户要的是当下主流封面观感——白字直接排在画面上，无黑白底条、无投影阴影，主标题在上、副标题紧跟其下。改封面样式时不要重新引入 rectangle 半透明遮罩。
• 只想重排封面时不要重跑整条流水线：写个几行的小脚本 import 技能里的 dub_cantonese 模块直接调 make_cover(clip, cfg, video, log, out) 即可（cfg 里要有 work_dir），8 张封面 ~20 秒，避免重复 TTS。

十、脚本用法

# 1) 准备配置 config.json（src_dir / out_dir / voice / rate / clips[]；可选 bgm / compile）
# 2) 运行
& <venv>\Scripts\python.exe scripts\dub_cantonese.py config.json

clips[].sentences 是逐句粤语旁白；脚本自动完成 配音→拼接→对齐→(BGM混音)→ass/srt→压片→封面→(拼合集)。

视频号封面（cover 用法）

每条 clip 加 cover_title（主标题）与 cover_subtitle（副标题），出片时自动生成 _封面_9x16.jpg（1080×1920 竖屏）与 _封面_1x1.jpg（1080×1080 信息流）两个文件（详见 §8.7）；想改封面取帧时刻用 cover_time（0~1，默认 0.4）。

整文件夹自动扫描（auto_scan 用法）

若只要"对一个文件夹里的所有视频批量出粤语版"，把 clips 数组换成 "auto_scan": true 即可（详见 §8.6）。脚本自动扫 src_dir、逐条出片；配了 vision 还能全自动写稿，连 sentences 都不用写。

> 便利提示：把素材文件命名好（如「门店环境.mp4」），成片文件名就跟着好看；否则会用源文件名（可能是哈希串）。扫之前建议先按"提问规范"确认旁白口径／原声处理／声线，或直接走 §6.4 选项菜单。

十一、技能头像（品牌标识）

• 头像名：粤语剪辑
• 规格：512×512 px，≤500KB，JPG/PNG（符合常见平台头像上传要求）。
• 获取：本技能包不含图片文件，头像在展示侧通过 iconUrl 配置；需要时按下面的设计稿重新生成。
• 设计：米白底 ＋ 深红主标题「粤语剪辑」＋ 金色香港天际线（中环 IFC／中银大厦／摩天轮／跨海桥）＋ 胶片播放键 ＋ 声波，金色圆角边框；与兄弟技能「沪语剪辑」同一套视觉系统。
• 用途：本技能在技能列表／介绍页的头像；也可作为粤语成片的片头署名或品牌角标直接引用该 PNG。