Skip to content

HOWTO.md

Latest commit

 

History

History
130 lines (92 loc) · 5.61 KB

HOWTO.md

File metadata and controls

130 lines (92 loc) · 5.61 KB
Raw

Atlas Explainer 使用手册

一句选题 → 一条带旁白、字幕、配乐的纸艺讲解视频(Vox / Kurzgesagt 风格)。全程走 Atlas Cloud API + 本地 ffmpeg,不需要剪辑软件、不需要 GPU。

0. 一次性准备

# 1) 装依赖(ffmpeg 是 imageio-ffmpeg 自带的二进制,不用另装系统 ffmpeg)
pip install imageio-ffmpeg pillow

# 2) 配 key(去 https://www.atlascloud.ai/console/api-keys 领)
export ATLASCLOUD_API_KEY=apikey-你的key

就这两步。字体:macOS/含常见 Linux 字体的机器开箱即用;实在没有字体也会用 PIL 默认字体兜底(不会报错)。

1. 最快用法:一句话出片

cd skill/atlas-explainer
python3 scripts/run.py /tmp/myvideo --topic "how the shipping container reshaped global trade"

参数:

  • --scenes 6 分几幕(默认 6;每幕 ~8s,6 幕成片约 55s)
  • --vertical 竖屏 9:16(默认横屏 16:9)
  • --lang en 旁白语言(en 英文;中文见 §4)
  • --force 全部重来(否则已生成的素材会复用,省钱省时间)

跑完成片在 /tmp/myvideo/out/final.mp4。

它内部做了什么:plan(LLM 写分镜)→ 并行(4-6 个镜头文生视频 ∥ 旁白 TTS ∥ 配乐)→ 撕纸标题/字幕 → ffmpeg 合成。

2. 进阶用法:自己写分镜(质量更高)

LLM 自动分镜够用,但你(或 Claude)自己写文案通常更好。做法:自己在项目目录放一个 scenes.json,然后:

python3 scripts/run.py /tmp/myvideo        # 不带 --topic,直接读现成的 scenes.json

scenes.json 字段(照着 examples/scenes.example.json 改最省事):

字段 说明
width/height/aspect_ratio 1280x720+16:9 或 720x1280+9:16,三者要一致
video_model 一般填 google/gemini-omni-flash/text-to-video
voice_id xai-tts 音色:leo/eve/rex/sal/ara 等
tts {"language":"en"};中文见 §4
bgm_prompt 配乐英文描述,务必带 instrumental, no vocals
title_lines 片头 1-2 行大写标题
end_rows 片尾署名行
style_block 全片统一的画面风格(最关键,见 §3)
scenes[] 每幕:id(从0)、headline(2-4词大写)、narration(一句话≤20词)、visual(画面描述)

3. 出片好看的铁律(别跳过)

  1. 所有镜头共用一个 style_block。6 个镜头是分别生成的,靠这段共同风格描述才能整片统一(纸艺质感 + 固定配色)。
  2. 视频画面里不要出现文字。在 style_block 里写死 no on-screen text, letters, numbers, captions, logos。所有文字(标题、字幕)都是后期用 PIL/ffmpeg 烧上去的——AI 直接生成的文字会是乱码。
  3. 不要出现真实、可识别的人物。gemini-omni-flash 审核会拦真人肖像(prohibited contents)。只用纸艺/物体/抽象。(真人拼贴是本仓另一条 cr7v2 管线,不是这个 skill。)
  4. 每幕旁白 ≤ 20 词、一句话,念出来要能塞进 ~6-8 秒。
  5. 原生音频只当环境音。style_block 里写 audio: subtle ambient foley only — no speech, no voice, no music。旁白和配乐是后期叠的。

4. 中文旁白

把 scenes.json 的 tts 换成 seed-audio(中文最自然):

"tts": {
  "engine": "seed-audio",
  "speaker": "zh_male_taocheng_uranus_bigtts",
  "template": "干净的录音棚人声独白，没有任何背景音乐，没有任何音效。**Speaker A** @audio1 以纪录片旁白语气缓缓说道：\"{line}\""
}

narration/headline/title_lines 直接写中文,字幕会自动用中文字体、按标点断行。可用男声 zh_male_taocheng_uranus_bigtts,女声 zh_female_cancan_uranus_bigtts 等(有效音色后缀是 _uranus_bigtts)。

5. 验收(别只看"成功"字样)

mp4 内容读不了,抽帧成图再看:

FF=$(python3 -c "import imageio_ffmpeg;print(imageio_ffmpeg.get_ffmpeg_exe())")
$FF -y -i /tmp/myvideo/out/final.mp4 -vf "fps=1,scale=480:-1,tile=4x4" -frames:v 1 /tmp/grid.jpg
open /tmp/grid.jpg      # macOS;Linux 用 xdg-open /tmp/grid.jpg。看:风格统一？标题字幕清晰？有没有乱码字/黑帧

6. 单步调试

整条流水线可以拆开单跑,方便定位问题(都接收「项目目录」做第一个参数):

python3 scripts/plan.py         /tmp/myvideo "你的选题" --scenes 6   # 只生成 scenes.json
python3 scripts/gen_scene.py    /tmp/myvideo 0                       # 只出第 0 个镜头
python3 scripts/gen_audio.py    /tmp/myvideo --tts                   # 只出所有旁白
python3 scripts/gen_audio.py    /tmp/myvideo --bgm                   # 只出配乐
python3 scripts/make_overlays.py /tmp/myvideo                        # 只出标题/字幕
python3 scripts/assemble.py     /tmp/myvideo                         # 只做合成

7. 常见问题

现象 原因 / 解法
Set your AtlasCloud key first 没配 ATLASCLOUD_API_KEY
某个镜头 generation failed ... prohibited contents 该幕 visual 触发审核(常是像真人)。改文案去掉真人特征,重跑(已完成的镜头会复用,只重跑失败的那个)
想更省钱 --scenes 4、或用默认 720p;成片按 $0.125×镜头数 + $0.015×镜头数 + $0.112 估
并发撞限额 export ATLAS_MAX_WORKERS=4 调低并发再跑
换风格/配色 只改 style_block,别动每幕结构
Linux 上字幕字体不理想 装 fonts-noto-cjk / fonts-liberation,或把字体丢进 /usr/share/fonts

8. 成本与耗时

6 幕 720p 成片 ≈ $0.95(6×$0.125 视频 + 6×$0.015 旁白 + $0.112 配乐),墙钟 ~3-6 分钟(镜头并行生成)。幕数越少越便宜。