Communitygithub.com

aalter

为无声视频添加尼泊尔语配音——分两步走:先生成剧本,再同步配音。

aalter 是什么?

这个技能专门用于制作用于尼泊尔语观众的产品视频或解说片。它采用清晰的两阶段工作流:第一阶段,根据用户指定的时长(例如 5 或 10 分钟)生成一个结构化的 `script.md` 文件,其中包含剧本、导演说明、逐镜头的尼泊尔语旁白和机器可读的 JSON 数据块。第二阶段,用户提供渲染好的无声视频和背景音乐文件,该技能会自动将每句旁白精确对齐到对应的镜头窗口,并混入音乐和音效。它依赖本地 `ffmpeg` 和 ElevenLabs API(用于文字转语音)。该技能包含智能预算检查(查看 ElevenLabs 剩余字符数)、速度/时长冲突解决(通过加速旁白或拉伸画面)、缓存复用(避免重复消耗字符)以及详细的构建报告和验证。支持自定义缩略图、标题和免责声明卡片。主要平台是 Windows 环境下的命令行工具。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/amgainprabesh/aalter-nepali-narrated-video/tree/HEAD

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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)) over script.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将旁白+背景音乐混音到已构建的画面上(卡片+影片),并逐窗口验证时

操作流程

  1. 询问长度(5 或 10 分钟),如果未给出。切勿自行编造。预算:lines ≈ length_s / 3,words ≈ length_s × 1.9。
  2. 编写 script.md ——一个文件,四个部分,按此顺序,模板在 references/script-md-template.md:
    1. 影片内容(标题、长度、镜头数、一个视觉创意);
    2. 导演说明——仅提供纯说明,不要包含分辨率、帧率、编码器、模型名称、文件路径或负面提示列表;
    3. 表格 # | 旁白 (尼泊尔语) | 镜头说明,每个镜头一行,并明确说明旁白列就是配音脚本(这样用户无需另外询问);
    4. 一个围栏 json 代码块,包含 title、slug、length_s、voice、music、lines[] ——这是第二阶段唯一读取的内容。 保持吸引力的结构:0–12 秒冷开场带后果 → 提示回报 + “几乎人人都会犯的错误” → 神与配偶的对话框架 → 编号要点 → 隐藏错误 → 评论提示 + 订阅。 行的规则:5–8 个尼泊尔语单词,以 । 或 ? 结尾,使用天城文数字(७ 而不是 7),每行对应一个镜头。
  3. 交接。 除非被要求,否则不要在同一个回合中生成音频。
  4. 当无声视频到达后,将所有内容放入一个文件夹,并从 script.md 中提取 JSON 块到 script.json ——该文件是构建的唯一输入。如果指南携带时间戳,请将 start/end 放入每一行。
  5. 在渲染前确定声音。 从 samples/ 发送 3–5 个 同一句短难行(专有名词 + — 停顿)的 mp3 样本,每个语音一个注释,等待用户返回一个名称。缓存使重新运行免费,但更换声音会重新消耗全部字符。script.json 可以携带指南自身的 voice_settings(稳定性、相似度提升、风格、使用说话人增强);构建将优先使用这些设置而非其默认的 0.62/0.75/0.2,因此请保留指南的数字而不丢弃它们。
  6. 通过重新拼写而不是更换声音来修正发音 —— शिव 读作 “Siv”;在尼泊尔语语句中使用拉丁字母写成 Shiva。先用一个 30 字符的样本进行 A/B 比较。
  7. 构建,阅读 build-report.txt,然后再回答。它将第 i 行映射到第 i 个节拍,修剪每个剪辑中的静音,将行适配到其窗口并混音。对于 10 分钟的影片,仅混音就可能超过前台 terminal 调用的范围——使用 background=true, notify=true 启动,在退出时接手工作,不要重新轮询。后台会话 ID 不会延续到后续调用;使用 process_manage(action='list') 查找它,而 poll 只接受仍在运行的会话。
  8. 发布视频集:缩略图、标题 + 描述、可选的 1 秒免责声明卡片——参见 references/thumbnail-and-shipping.md。
  9. 已发布影片的修正是手术式的。 错误的音乐轨道、免责声明或画面可以单独修复:替换文件,仅重建衍生资产(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。任何其他情况都是草稿,而非交付品。

相关技能