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 | 將旁白 + 背景音樂混入已建置好的影片(卡片 + 影片),並以每個視窗驗證 |
流程
- 詢問影片長度(5 或 10 分鐘),若未提供。切勿自行假設。預算:
行數 ≈ 長度秒 / 3,字數 ≈ 長度秒 × 1.9。 - 撰寫
script.md——一個檔案,四個部分,依此順序,範本在references/script-md-template.md:- 影片是什麼(標題、長度、鏡頭數、一個視覺概念);
- 如何導演——僅提供方向說明,不得有解析度、fps、編解碼器、模型名稱、檔案路徑或負面提示列表;
# | 旁白 (尼泊爾語) | 鏡頭方向表格,每個鏡頭一行,並加上明確說明:旁白欄就是語音腳本(這樣使用者就不需另外詢問);- 一個圍欄
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(stability、similarity_boost、style、use_speaker_boost);建置腳本會優先採用這些設定而非預設的 0.62/0.75/0.2,因此請將指南的數值複製過去而非捨棄。 - 透過重新拼寫而非更換語音來修正發音——
शिव讀作「Siv」;在天城文句子中以拉丁字母寫成Shiva。先用 30 字元的樣本進行 A/B 測試。 - 建置,閱讀
build-report.txt,然後才回答。它會將行 i 對應到拍子 i,修剪每個片段的靜音,將行調整至其視窗內並混音。對於 10 分鐘的影片,僅混音就會超過前景terminal呼叫的時間——請以background=true, notify=true啟動,並在結束時接續工作,切勿重新輪詢。背景 session id 不會延續到後續呼叫;process_manage(action='list')可找到它,且poll只接受仍在運行的 session。 - 發佈集數:縮圖、標題 + 描述、可選的 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(長度 / 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。任何其他情況都是草稿,而非交付成果。