中英双语朗读视频生成器
把一段英文原文（配中文译文）做成带朗读配音的电影感短视频：英文由微软免费 TTS 朗读，画面是逐句浮现的中英双语文案，明暗色调随文意切换，句间交叉淡入。
核心卖点：全程不需要任何 API Key，零成本、纯本地生成。 相比走付费 AI 视频 Skill（如 AI Hive，按 5 秒约 50–100 积分计费），本方案对"朗读 + 字幕卡片"类需求是更省、更稳的选择。
一、适用场景
- 英文名言 / 诗歌 / 课文的朗读 + 双语字幕视频（英语教学、课件、早读素材）
- 文学作品开篇、演讲金句的氛围化呈现
- 社媒短视频（可再裁成竖屏）
- 任何"想让英文被读出来 + 配中文"的需求
> 注意：本方案是文字卡片 + 配音，不是 AI 生成实景画面。若要电影级运镜蒙太奇，需要付费 AI 视频 Key（如 AI Hive 的 sk-api-*），那是另一个 Skill 的事。
二、核心流程（SOP）
0. 准备 Python 环境（一次性）
需要一个含以下依赖的 Python（建议用隔离 venv，避免污染用户环境）：
pip install edge-tts moviepy Pillow
edge_tts：微软 Edge 免费 TTS，联网即可，无需密钥。moviepy（v2）：视频合成，自带 ffmpeg（通过 imageio-ffmpeg）。Pillow：绘制文案卡片。numpy：moviepy 依赖，会被一并装上。
> 若用 WorkBuddy 托管 Python，可建 venv：
> python -m venv <venv> && <venv>/scripts/python.exe -m pip install edge-tts moviepy Pillow
1. 准备文案
两种用法：
- 直接用内置演示（狄更斯《双城记》开篇），不传 --input 即可。
- 自定义文案：写一个 txt，每行 英文 | 中文 | 可选色调(light/dark)。第三列省略时按奇偶行自动交替明暗。格式见 references/example_input.txt。
2. 运行脚本
# 横屏（默认 1920x1080）
python scripts/make_readalong.py \
--input references/example_input.txt \
--voice en-GB-RyanNeural \
--en-size 96 --zh-size 60 \
--output bilingual_readalong.mp4
# 竖屏（1080x1920，适合抖音/视频号）
python scripts/make_readalong.py \
--input references/example_input.txt \
--portrait --en-size 96 --zh-size 60 \
--output bilingual_portrait.mp4
# 加背景音乐（mp3/wav，自动循环/裁剪到成片时长并压低音量混在朗读下方）
python scripts/make_readalong.py \
--input references/example_input.txt \
--bgm ./bgm.mp3 --bgm-volume 0.3 \
--output bilingual_with_music.mp4
# 竖屏 + 背景音乐 组合
python scripts/make_readalong.py --portrait --bgm ./bgm.mp3 \
--output bilingual_portrait_music.mp4
不传 --input 时自动用内置《双城记》文案。
3. 取结果
输出 MP4（默认 1920×1080 横屏；加 --portrait 时为 1080×1920 竖屏。24fps，时长 = 各句朗读时长之和 + 片头 3s + 片尾 1.5s）。加 --bgm 后音频为"朗读配音 + 背景音乐"混音轨。
> 收尾时 moviepy 会尝试删除临时音频文件；在部分沙箱里这一步会因"回收站不可用"报错并抛 OSError，但视频已经写完了，可忽略。临时文件在 <输出目录>/_tts_tmp/，手动删掉即可。
三、经验与教训（踩过的坑）
- moviepy v2 的
ImageClip不吃 PIL.Image：必须传np.array(img)（或直接传图片文件路径），传原始 PIL 对象会报Cannot understand given URI。 - 交叉淡入不是方法，是效果类：v2 里
clip.crossfadein(x)不存在，要用clip.with_effects([vfx.CrossFadeIn(x)])，且合成时用concatenate_videoclips(clips, method="compose")。 - 依赖冲突警告可忽略：若同环境有 pdfplumber 等要求
Pillow>=12，而装的是 11.x，pip 会报 conflict，但 PIL 基础功能不受影响，不用强行升级。 - TTS 句级拆分最稳：逐句调用 edge-tts 各生成一段 mp3，用该段时长驱动画面对齐，天然音画同步，比"整段朗读再切时间戳"简单可靠。
- 中文必须按字符折行，不能按空格分词：中文没有空格，若复用英文的"按空格分词"折行逻辑，整段中文会被当成一个超长"单词"，一旦超过画宽就会溢出、显示不全。正确做法是先按空格分词，再对超宽的词（或无空格整段）逐字符断行（脚本里的
wrap_text()）。同时布局上让"英文块 + 中文块"上下堆叠后整体垂直居中（而不是给中英各固定一个 y 偏移），文案长短变化时既不重叠也不出画，每行再水平居中即可。 - 字体路径硬编码 Windows 位置：
C:/Windows/Fonts/times.ttf（英文衬线）、simsun.ttc/msyh.ttc（中文）。换平台（mac/Linux）需改load_fonts()里的路径，否则中文可能显示成方块。 - 沙箱删除临时文件会失败：见流程第 3 步，属无害报错。
四、可复制模板
输入文件模板（references/example_input.txt）
# 每行 "英文 | 中文 | 可选色调(light/dark)"，# 开头忽略
It was the best of times, | 这是最好的时代， | light
it was the worst of times, | 这是最坏的时代的。 | dark
The only thing we have to fear is fear itself. | |
命令模板
python scripts/make_readalong.py --input <你的文案.txt> \
--voice en-GB-RyanNeural --en-size 96 --zh-size 60 \
--output <输出名>.mp4
完整代码
见 scripts/make_readalong.py（已参数化：--input / --voice / --en-size / --zh-size / --output / --fps / --cross）。改文案、换音色、调字号、改输出名，全靠这几个参数，无需改代码。
五、常用参数
| 参数 | 默认 | 说明 |
|---|---|---|
--input |
无（用内置） | 文案 txt，每行 英文\|中文\|色调 |
--voice |
en-GB-RyanNeural |
英文音色，可换 en-US-GuyNeural、en-US-AriaNeural 等 |
--en-size |
96 | 英文字号 |
--zh-size |
60 | 中文字号 |
--output |
bilingual_readalong.mp4 |
输出路径 |
--fps |
24 | 帧率 |
--cross |
0.4 | 句间交叉淡入秒数 |
--portrait |
关 | 开启后输出 1080×1920 竖屏（抖音/视频号） |
--bgm |
无 | 背景音乐文件（mp3/wav），自动循环/裁剪到成片时长 |
--bgm-volume |
0.3 | 背景音乐音量（0~1），叠在朗读配音下方 |
六、个性化改造建议
> 竖屏（--portrait）和背景音乐（--bgm）已经是内置开关，无需改代码，直接加参数即可（见第二节命令模板）。
- 换画面风格：改
make_gradient的颜色区间，或把纯色渐变换成你自己的背景图（ImageClip叠底）。 - 中文也朗读：若要中文配音，对中文行再调一次 edge-tts（需中文 voice 如
zh-CN-YunyangNeural），与英文音频拼接。 - BGM 音量/淡入：用
--bgm-volume调整体量；若想片头片尾淡入淡出，可在make_readalong.py的混音段给bgm再加afx.AudioFadeIn/AudioFadeOut效果。 - 画幅随心：除
--portrait外，也可在main()里直接改W,H全局变量做任意分辨率（绘图函数已按 W/H 自适应折行与构图）。
