Communitygithub.com

aalter(尼泊爾語影片配音工具)

透過兩個步驟產生尼泊爾語旁白影片:第一步撰寫包含旁白與鏡頭說明的 script.md,第二步將使用者提供的無聲影片配上逐行語音、背景音樂並確保同步。

aalter(尼泊爾語影片配音工具) 是什麼?

aalter 是一個專為 AI 代理(如 Claude Code、Cursor、Codex)設計的技能,用於自動化尼泊爾語旁白影片的製作流程。它將工作拆分為兩個階段:第一階段由 AI 撰寫完整的 `script.md` 檔案,包含旁白腳本、鏡頭方向以及機器可讀的行資料;第二階段當使用者提供已渲染好的無聲影片後,AI 會執行一個 Python 建置腳本,將每行旁白轉為語音(透過 ElevenLabs)、疊上背景音樂,並確保聲音與畫面精確同步。 此技能支援 Windows 平台,需要系統上安裝 `ffmpeg` 和 `ffprobe`,以及 ElevenLabs API 金鑰。它不產生影片畫面本身——使用者需根據腳本的鏡頭方向自行渲染——也不會燒錄字幕。建置流程會自動檢查腳本字數是否與影片長度匹配(尼泊爾語約 1.8–1.9 字/秒),若不符合則提供選項(如拉伸影片、刪減腳本、加速語速或接受更長的影片)。快取機制讓重新混音(如只換音樂)免費,且同一行文字未變時不耗費 TTS 額度。 對於 AI 開發者而言,此技能的核心價值在於自動化了一個否則需大量手動操作的流程:從腳本生成、語音合成、音訊剪輯到同步驗證,全部由指令驅動。它特別適合需要大量尼泊爾語旁白內容的創作者,如 YouTube 教育頻道或紀錄片製作。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Aalter — script.md,然後配上同步的尼泊爾語旁白

產生一部配有旁白的尼泊爾語影片,分兩個階段:第一階段寫出 script.md(旁白 + 鏡頭方向 + 機器可讀的行資料),第二階段接收使用者的無聲圖片並回傳完成後的影片,包含逐行語音、背景音樂以及驗證過的同步。它不會產生圖片——使用者需根據鏡頭方向自行渲染——也不會加字幕或燒錄字幕。需要在 PATH 中安裝 ffmpeg 以及 ElevenLabs 金鑰;除此之外僅需 Python 標準函式庫。

使用時機

  • 「給我腳本和影片提示」、「script.md」、「我會告訴你長度」
  • 「我已經生成了影片,這是檔案——請加入語音」、「同步音訊」
  • 「用不同的聲音重新錄製語音」、「發音錯了」
  • 「縮圖」、「標題與描述」、「在開頭加入免責聲明」(針對已建置好的集數)

先決條件

  • PATH 中需有 ffmpeg 和 ffprobe(此技能中的每個腳本都會檢查)。
  • ElevenLabs 金鑰放在 %LOCALAPPDATA%\hermes\.elevenlabs_key——純文字,一行。若缺少則詢問使用者一次,儲存於此,絕不在對話中回顯。
  • 免費方案每月 10,000 字元,5 分鐘腳本約 3,000 字元——呼叫 TTS 前先讀取額度(GET /v1/user/subscription)並告知使用者數字。
  • 從方案中讀取額度,而非從金鑰的歷史記錄:GET /v1/user/subscription → character_limit - character_count。該呼叫同時告知 tier(free = 無商業授權)且不會告知金鑰是否已加值——10,000 點的金鑰仍是 tier: free 且付費渲染約 $0.08/1k 字元。將數字和 tier 告知使用者。
  • 部分額度並非小額度。建置過程會朗讀每一行,因此若短少 40%,會在途中失敗且仍會消耗字元。量化整個腳本(對 script.json 執行 sum(len(text)))並在使用者決定前先讓使用者決定。
  • 資料庫語音(知名的尼泊爾語語音)需要付費方案——請參閱 references/elevenlabs-voices.md。

在付費前先確認腳本能配合影片

同步指南可能在內部一致但仍無法拍攝:1,837 個尼泊爾語單字配上 600 秒的影片相當於 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.06 的影片顯示 1039.10)——這是一個約 0.04 秒的標籤誤差,非漂移。

如何執行

第一階段是編寫:將完成的 script.md 以 write_file 寫入 <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 分鐘的字數~515(尼泊爾語速度約 1.9 字/秒)——字數超過此值的指南將無法配合
語音ElevenLabs Chris iP95p4xoKVk53GoZ742B,模型 eleven_v4
其他庫存語音Brian、Daniel、George、Bill、Eric、Adam(ID 在建置腳本中)
速度限制最大 1.45×;交付標準是零個被限制的行
背景音樂BED = 0.09 只適用於平均值為 −24 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撰寫第一階段的 script.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 分鐘),若未提供。切勿自行假設。預算: 行數 ≈ 長度秒 / 3,字數 ≈ 長度秒 × 1.9。
  2. 撰寫 script.md——一個檔案,四個部分,依此順序,範本在 references/script-md-template.md:
    1. 影片是什麼(標題、長度、鏡頭數、一個視覺概念);
    2. 如何導演——僅提供方向說明,不得有解析度、fps、編解碼器、模型名稱、檔案路徑或負面提示列表;
    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(stability、similarity_boost、style、use_speaker_boost);建置腳本會優先採用這些設定而非預設的 0.62/0.75/0.2,因此請將指南的數值複製過去而非捨棄。
  6. 透過重新拼寫而非更換語音來修正發音——शिव 讀作「Siv」;在天城文句子中以拉丁字母寫成 Shiva。先用 30 字元的樣本進行 A/B 測試。
  7. 建置,閱讀 build-report.txt,然後才回答。它會將行 i 對應到拍子 i,修剪每個片段的靜音,將行調整至其視窗內並混音。對於 10 分鐘的影片,僅混音就會超過前景 terminal 呼叫的時間——請以 background=true, notify=true 啟動,並在結束時接續工作,切勿重新輪詢。背景 session id 不會延續到後續呼叫;process_manage(action='list') 可找到它,且 poll 只接受仍在運行的 session。
  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(長度 / 3 秒) 個拍子,並在信任任何切割清單前先將行 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。任何其他情況都是草稿,而非交付成果。

相關技能