Aalter — script.md, then a synced Nepali voiceover
分两步生成一部带旁白的尼泊尔语影片:第一步创建 script.md(旁白 + 导演说明 + 机器可读行),第二步接收用户的无声画面并返回带有逐行配音、背景音乐和已验证同步的最终影片。它不生成画面——用户根据镜头说明自行渲染——也不添加字幕或烧录字幕。需要 ffmpeg 在 PATH 中,以及一个 ElevenLabs 密钥;除此之外无其他依赖,仅用 Python 标准库即可。
何时使用
- “给我脚本和视频提示”、“script.md”、“我会告诉你长度”
- “我已生成视频,给你——添加配音”、“同步音频”
- “用不同的声音重新配音”、“发音错误”
- “缩略图”、“标题和描述”、“在开头添加免责声明”用于已构建的视频集
前提条件
ffmpeg+ffprobe在 PATH 中(本技能中的每个脚本都会检查)。- ElevenLabs 密钥位于
%LOCALAPPDATA%\hermes\.elevenlabs_key——纯文本,一行。如果缺失则索要一次,保存到该文件,切勿将其回显到聊天中。 - 免费套餐每月 10 000 个字符,5 分钟脚本大约需 3000 个字符——在采样前先读取预算(
GET /v1/user/subscription)并将数字告知用户。 - 从套餐计划中读取预算,而不是从密钥的历史记录中读取:
GET /v1/user/subscription→character_limit - character_count。这一个调用还能告诉你套餐级别(free表示无商业许可),但不会告诉你密钥是否已充值——一个 10 000 信用点的密钥仍然是tier: free,付费渲染大约 $0.08/千字符。将数字和级别告知用户。 - 部分预算不等于小预算。构建过程会逐行生成语音,因此如果短缺 40%,会在中途失败并仍然消耗字符。量化整个脚本(
sum(len(text))overscript.json),并在首次 TTS 调用前让用户决定。 - 库声音(知名的尼泊尔语声音)需要付费套餐——参见
references/elevenlabs-voices.md。
在付费前确保脚本适配画面
同步指南可能在内部一致但仍然无法拍摄:600 秒画面配上 1837 个尼泊尔语单词相当于 3.06 词/秒,而所有尼泊尔语语音的测量速度均为 1.8–1.9 词/秒。在花费字符前检查字数与画面的匹配——重写脚本比拉伸影片更划算。
如果脚本不匹配,以下是唯一诚实的选项,由用户选择:
| 选项 | 画面 | 声音 | 成本 |
|---|---|---|---|
| 拉伸画面 | setpts * need/600, 重新编码 | 自然 | 添加配音后免费 |
| 裁剪脚本文字 | 不变 | 自然 | 重新录制修改的行 |
| 加快语速 | 不变 | 1.3 倍及以上听起来急促 | 从 .aalter_cache/ 免费 |
| 接受更长的影片 | 拉长 | 自然,每句间 0.35 秒呼吸 | 免费 |
- 缓存决定哪个选项便宜。 不同的行窗口可以复用所有剪辑(免费);不同的行文本需要重新消费。当画面长度不同时,根据实际剪辑长度构建窗口:
start_i = prev_end,end_i = start_i + clip_i + 0.35。 - 拉伸整体素材,而不是连接多个剪辑:在整个画面上使用
-vf "setpts=(PTS-STARTPTS)*need/600" -r 24可以保持每个剪切点相对于镜头的原始位置,仅减慢运动(肉眼观察在 ×1.43 下仍然平滑)。而且编码成本较高——10 分钟 24 fps 影片拉伸至 17 分钟大约需要 10 分钟 CPU 时间;使用background=true, notify=true运行。 - 帧对齐是同步的一部分。 以秒为单位的指南只有在拼接保持完整帧时才能对齐语音:使用
ffprobe -count_frames检查卡片+画面,若帧计数不等于round(frames/24)*24 + card_frames则拒绝构建。然后混流后的文件时长显示最后一个音频包的尾部(例如,1039.10 对应 1039.06 的影片)——大约 0.04 秒的标签差异,并非漂移。
如何运行
第一阶段是编写:将完成后的 script.md 写入 <project>/script.md,然后停止。
第二阶段是一条命令,通过 terminal 工具执行:
python "C:/Users/<user>/AppData/Local/hermes/skills/creative/aalter/scripts/aalter_build.py" \
<project_dir> --video video.mp4 --music music.m4a
它会输出 out/<slug>.mp4 和 build-report.txt。先阅读报告再回答。
快速参考
| 项目 | 值 |
|---|---|
| 构建 | scripts/aalter_build.py <project> --video f --music f --engine eleven --voice Chris |
| 长时间构建 | 使用 terminal(background=true, notify=true) 运行——一个 10 分钟混音会超过 180 秒的前台调用 |
| 免费重新混音 | .aalter_cache/<engine>/ 包含每个剪辑一个片段,因此旁白可以免费重建(-c:v copy) |
| 短音乐 | 在构建前使用 scripts/music_bed.py <track> <seconds> music.wav |
| 5 分钟行数 | ~100 行(一镜一行 ≈ ~3 秒) |
| 5 分钟字数 | 按尼泊尔语语速 ~1.9 词/秒 计算约为 515 词——字数超过此值的指南将无法适配 |
| 声音 | ElevenLabs Chris iP95p4xoKVk53GoZ742B,模型 eleven_v4 |
| 其他库存声音 | Brian, Daniel, George, Bill, Eric, Adam(ID 在构建脚本中) |
| 速度上限 | 最大 1.45 倍;交付标准是零个速度过快的行 |
| 背景音乐 | BED = 0.09 仅在轨道均值对应 −24 dB 时为 −33 dB;测量它(volumedetect)并设置 BED = 10 ** (target_db/20 - track_mean_db/20) |
| 语音音量 | loudnorm I=-16 TP=-1.5 LRA=11 |
| 缩略图 | 1280×720 JPEG,文本在浏览器中排版 |
| 免责声明卡片 | 1 秒保持画面,静音,使用 -c copy 拼接;拼接后的帧计数必须是完整的画面数 |
| 混音电平 | volume=0.1 为 −20 dB,0.4 约为 −8 dB——指南中的“−20 dB”并非 volume 值 |
按需使用 skill_view(name="aalter", file_path=…) 加载:
| 文件 | 何时加载 |
|---|---|
references/script-md-template.md | 编写第一阶段剧本时 |
references/elevenlabs-voices.md | 选择/试听语音时,或出现 402 错误时 |
references/thumbnail-and-shipping.md | 处理缩略图、标题/描述、免责声明卡片、音乐时 |
scripts/aalter_build.py | 整个第二阶段构建时——直接调用,不要重新输入 |
scripts/music_bed.py | 提供的音乐轨道比画面短时 |
scripts/assemble.py | 将旁白+背景音乐混音到已构建的画面上(卡片+影片),并逐窗口验证时 |
操作流程
- 询问长度(5 或 10 分钟),如果未给出。切勿自行编造。预算:
lines ≈ length_s / 3,words ≈ length_s × 1.9。 - 编写
script.md——一个文件,四个部分,按此顺序,模板在references/script-md-template.md:- 影片内容(标题、长度、镜头数、一个视觉创意);
- 导演说明——仅提供纯说明,不要包含分辨率、帧率、编码器、模型名称、文件路径或负面提示列表;
- 表格
# | 旁白 (尼泊尔语) | 镜头说明,每个镜头一行,并明确说明旁白列就是配音脚本(这样用户无需另外询问); - 一个围栏
json代码块,包含title、slug、length_s、voice、music、lines[]——这是第二阶段唯一读取的内容。 保持吸引力的结构:0–12 秒冷开场带后果 → 提示回报 + “几乎人人都会犯的错误” → 神与配偶的对话框架 → 编号要点 → 隐藏错误 → 评论提示 + 订阅。 行的规则:5–8 个尼泊尔语单词,以।或?结尾,使用天城文数字(७ 而不是 7),每行对应一个镜头。
- 交接。 除非被要求,否则不要在同一个回合中生成音频。
- 当无声视频到达后,将所有内容放入一个文件夹,并从
script.md中提取 JSON 块到script.json——该文件是构建的唯一输入。如果指南携带时间戳,请将start/end放入每一行。 - 在渲染前确定声音。 从
samples/发送 3–5 个 同一句短难行(专有名词 +—停顿)的 mp3 样本,每个语音一个注释,等待用户返回一个名称。缓存使重新运行免费,但更换声音会重新消耗全部字符。script.json可以携带指南自身的voice_settings(稳定性、相似度提升、风格、使用说话人增强);构建将优先使用这些设置而非其默认的 0.62/0.75/0.2,因此请保留指南的数字而不丢弃它们。 - 通过重新拼写而不是更换声音来修正发音 ——
शिव读作 “Siv”;在尼泊尔语语句中使用拉丁字母写成Shiva。先用一个 30 字符的样本进行 A/B 比较。 - 构建,阅读
build-report.txt,然后再回答。它将第 i 行映射到第 i 个节拍,修剪每个剪辑中的静音,将行适配到其窗口并混音。对于 10 分钟的影片,仅混音就可能超过前台terminal调用的范围——使用background=true, notify=true启动,在退出时接手工作,不要重新轮询。后台会话 ID 不会延续到后续调用;使用process_manage(action='list')查找它,而poll只接受仍在运行的会话。 - 发布视频集:缩略图、标题 + 描述、可选的 1 秒免责声明卡片——参见
references/thumbnail-and-shipping.md。 - 已发布影片的修正是手术式的。 错误的音乐轨道、免责声明或画面可以单独修复:替换文件,仅重建衍生资产(
scripts/music_bed.py、card.mp4),重新运行构建,重新拼接。TTS 可从.aalter_cache/<engine>/免费使用——在承诺之前先对比缓存中的剪辑数与行数,然后在拼接后输出的 t=0.5 秒处验证修正。
陷阱
- 切勿替换用户选择的声音 ——无论是出于配额限制、
402错误还是速度考虑。停止操作并说明阻碍,然后将备用方案作为问题提出。 - 带有逐行
start/end的同步指南优于所有猜测。 当镜头列表附带时间戳时,请为script.json中的每一行设置start/end;构建将直接使用这些窗口而不是partition()。首先验证:select='gt(scene,0.10)'的剪切时间必须等于指南的边界。 - 镜头检测不等于节奏。 ffmpeg 在深色 AI 素材上对于 100 个镜头大约检测到 88 个剪切点;将每个镜头分割为
round(duration / 3 s)个节拍,在信任任何剪切列表之前将第 i 行映射到第 i 个节拍。 - 短的背景音乐需要交叉淡入淡出,而不是
-stream_loop。 构建会循环短轨道,在每个连接点进行硬剪切;库存剪辑结尾通常很大声,因此 10 分钟的影片会产生约 21 个可闻的咔嗒声。请先运行scripts/music_bed.py(参见references/thumbnail-and-shipping.md)。 - 带有指南时间戳的脚本会铺满整个影片 ——连续行之间没有间隙,因此无法测量背景音乐的静音部分。通过更换轨道重新运行构建,或相信
music.wav自身的 RMS 来证明背景音乐存在;不要寻找不存在的间隙。 - 在最终拼接输出的 t=0.5 秒处使用
vision_analyze验证免责声明 ——不要在中途的card.mp4上验证,也不要相信 PNG 的转录。 - ffmpeg
drawtext会损坏天城文(ख्न→ख्छ)。仅通过 1280×720 截图 HTML 页面烧录尼泊尔语文本,切勿使用 drawtext。 - 在裁切区域上验证烧录的文字:全帧读取会误读合字和数字(将 ४ 读作 ८)。
- 在每个窗口中最响亮的 0.25 秒处探测,而不是一个中点:自然停顿可能看起来像静音并引发误报。
- 必须是零个速度过快的行才算完成 ——修正脚本行或在 1.45 倍速下重新渲染,切勿交付速度受限的片段。一长串速度过快行列表意味着脚本不匹配画面,而不是声音太慢:报告计数并停止等待决策(参见“在付费前确保脚本适配画面”)。
- 切勿信任指南中对某种语言的模型名称。
eleven_multilingual_v2根本不支持尼泊尔语;eleven_v4和eleven_v3支持。在渲染前检查GET /v1/models→ 每个模型的languages中language_id == 'ne',无论脚本中写的是什么。 - 切勿根据一个样本判断音频。
-ss/volumedetect对同一半秒的测量与完全解码的测量不同,在一个安静片段中的一个压缩峰值可能读为 −14 dB。在 Python 中一次性扫描整个文件(每 0.5 秒 RMS,然后每个行窗口取最大值)并判断一致性——没有窗口低于 −40 dB,电平彼此相差在几 dB 以内——而不是一个单一数字。 - 被终止的
assemble.py/mux 会持有输出句柄。 在重命名或删除输出前,先杀死后台验证器(process_manage kill),否则mv会因为“Device or resource busy”失败,而文件看起来已经完成。 - 来自生成器的字幕副文件(如果存在)优于镜头检测 ——使用其提示窗口。
- 此主机上的本地工具需要
C:/…路径,而不是/c/…。
验证
python -c "import json;t=json.load(open('<project>/script.json'));print(len(t['lines']),'lines')"
ffprobe -v error -show_entries format=duration -show_entries stream=codec_type,channels,sample_rate \
-of default=nw=1 <project>/out/<slug>.mp4
验证通过条件,全部来自 build-report.txt 和上述探测结果:时长等于画面时长,存在 aac 48 kHz 立体声轨道,weak/silent windows: none,tempo-clamped: none。任何其他情况都是草稿,而非交付品。