Papercut 語音
每個後期階段都需要在旁白資料夾中有兩樣東西:voice/final_narrator/<id>.wav(每個腳本行一個 WAV 檔案)和 timing_narrator.js(每個單字的開始與結束時間)。此技能透過三種路徑之一產生這些檔案,然後建立字幕和場景計畫。腳本的完整參考資料位於 $MOTION_LIB/core/voice/README.md。
前置檢查
- 函式庫:
$MOTION_LIB,否則讀取~/.config/motion-explainer/config.env中的MOTION_LIB=行,否則詢問一次。匯出它,然後執行. "$MOTION_LIB/env.sh"會將ASR_PY、QWEN_TTS_PY和其他設定值載入 shell。 - 一個已建構好的專案(
motion-build,步驟 1),包含narration/script.json和帶有scenes的video/episode.json。new_episode.sh會將build_timing.py複製到narration/。 - 如果使用者已安裝 TTS,則直接使用,不要重新建置(路徑 B,如果是 Qwen3-TTS 則為路徑 A)。詢問一次是哪個以及它在哪裡執行。否則詢問要走哪個路徑,並告知其需求:
| 路徑 | 需求 | 安裝模式 |
|---|---|---|
| A. 本地 Qwen3-TTS | 來自 $MOTION_LIB/core/voice/setup_tts.sh 的語音虛擬環境(模型下載 2.3-4.2 GB) | 完整 |
| B. 您自己的錄音或其他 TTS | 一個 ASR 後端(mlx-whisper 或 faster-whisper)以及用於音高傳遞的 librosa 和 numpy,位於 ASR_PY 和 QWEN_TTS_PY 所指名的 Python 環境中 | 完整,或手動安裝這些套件 |
| C. 佔位用 | ffmpeg;macOS 用於 --say | 標準 |
如果路徑需要的東西比安裝的還多,請執行 ./install.sh --doctor 並移交給 motion-setup。沒有 ASR 時,build_timing.py 只會估計每秒 2.75 個單字,因此字幕會與真實音訊產生偏移。
路徑 A:本地 Qwen3-TTS
從系列資料夾執行:
cp $MOTION_LIB/core/voice/voice.example.json voice/voice.json # 每個系列執行一次;編輯它
$MOTION_LIB/core/voice/narrate.sh voice/voice.json episodes/NN-slug/narration
$MOTION_LIB/core/voice/finalize.sh voice/voice.json episodes/NN-slug/narration episodes/NN-slug/narration/voice/takes/narrator [num.json]
voice.json:speaker(CustomVoice:Aiden, Dylan, Eric, Ryan, Serena, Vivian, Sohee, Ono_anna, Uncle_fu)和instruct。建議:CustomVoice 1.7B,Ryan 或 Aiden,指示 「友善、自然、口語化,像在告訴朋友;句子之間有清晰的停頓;加重每行的關鍵字」。takes_per_line預設為 3。tempo保持為 1.0(其他值需要rubberband)。qa_targets設定音高範圍和 ASR 匹配度(0.9)。- 一個腳本行可以攜帶
tts(用於發音的正字文字;字幕保留text)和它自己的instruct。num.json將數字對應到口語單字({"13,000": "thirteen thousand"}),這樣 ASR 比對就不會因數字而失敗。 - 一次只執行一個 TTS 程序;1.7B 模型很吃記憶體。
finalize.sh對每個錄音執行 ASR 和音高分析,每行選出一個,修剪,響度正規化至 -16 LUFS,對最終檔案重新執行 ASR,並寫出timing_narrator.js。聽過之後,將修正放入voice/picks_override.json({"l3_name": 2}),並以SKIP_PICK=1重新執行。- 語音設計(用文字描述聲音)是 Qwen3-TTS 的一種模式,
narrate.py並未驅動此模式。請在其他地方用它生成,並使用路徑 B。
路徑 B:您自己的錄音或其他 TTS
- 將每個腳本行的 WAV 檔案放入
voice/final_narrator/<id>.wav,或將原始錄音放入voice/takes/narrator/<id>_<k>.wav並像上面一樣執行finalize.sh。 - 對於已完成的音檔,請轉錄它們,寫入
voice/chosen_narrator.json作為{id: "voice/final_narrator/<id>.wav"},然後從narration/執行:
$ASR_PY $MOTION_LIB/core/voice/asr.py voice/final_narrator/*.wav > voice/asr_narrator_final.json
CHOSEN=voice/chosen_narrator.json TIMING_OUT=timing_narrator.js python3 build_timing.py voice/asr_narrator_final.json
路徑 C:佔位用
從 narration/ 資料夾執行:
python3 $MOTION_LIB/core/tools/placeholder_vo.py [--wps 3.0] [--say [VOICE]]
它會寫入靜音 WAV 檔案(或帶有 --say 的 macOS say 語音)和從 script.json 單獨產生的 timing_narrator.js,根據單字長度分配時間。--wps 3.5 到 4 接近目標語速(預設 3.0)。可以先建置剪輯並設定時間,之後再重新配音:更換 WAV 檔案,重新執行 finalize.sh,重新執行 build_vo.py,然後單字提示就會跟著更新。
交付規則
配音應是人性化、從容不迫且帶有強調的。觀眾必須能在第一次聆聽時就跟上每一行。
- 呼吸空間。 在每個句子結束和列表節拍之間要有真實的停頓(「好。好。好。」)。從 0.3-0.4 秒的行間距開始(
episode.json中的gap,預設為 0.22;gaps會在一個命名行之後增加額外節拍),並用耳朵判斷。停頓只放在句子或子句邊界:在短語內部,例如「複製了,| 透過...」,一個 0.2 秒的間隔會聽起來像延遲。使用 30 秒的上限來換取呼吸空間,而不是縮短停頓,並且永遠不要為了達到時間而降低語速。 - 強調。 每行倚重的一兩個詞(數字、轉折詞、結論)來自腳本的分鏡表。將它們作為每行的
instruct傳入。 - 語氣。 對話式且帶點趣味,不要有播音員的能量。問句聽起來像真正的問題,關鍵台詞聽起來充滿好奇,行動呼籲要溫暖。旁白者仍然不開玩笑;笑點由畫面負責。
- 複製模型(無指示)。 使用複製語音(
ref_audio+ref_text,Base 模型)時,槓桿是文字和錄音。將停頓寫入標點符號中(列表節拍之間用句號,一個簡短問題作為自己的句子)。生成一個連續錄音的多個種子(SEED_BASE,takes_per_line),選擇目標單字音高變化最多且 ASR 達到 0.9 或更好的那個,然後單獨重錄一個平淡的行(ONLY=l4_peak)並在句子邊界拼接。僅複製您有權使用的語音。 - 一次生成整個腳本 可提供一致韻律:生成一個錄音,
split_take.py會按行切割它,然後在episode.json中設定"gap": 0。如果使用者偏好,逐場景處理也沒問題。 - 在完整執行前先播放前三行給使用者聽:
ONLY=l1_hook,l2_...,l3_... narrate.sh ...。
字幕與時間設定
從 video/,一旦 episode.json 有了 scenes:
python3 $MOTION_LIB/core/tools/build_vo.py # public/vo/voiceover.wav, public/vo/captions.json, src/plan.json
python3 $MOTION_LIB/core/tools/timing_md.py # STORYBOARD.md 的時間部分
captions.json 是一個 Remotion Caption[];場景邊界來自單字時間戳;合成長度是 plan.json 的 durationInFrames。build_vo.py 會標記任何少於 1.2 秒的場景。如果沒有函式庫,請使用 Remotion 字幕技能(whisper.cpp)或任何能回傳逐字時間戳的語音轉文字工具來轉錄 WAV 檔案。
字幕是每個單字一個撕標標籤,每頁 1-3 個單字,速度為每秒 3.5-4 個單字($MOTION_LIB/style/$MOTION_STYLE/docs/style-guide.md,第 11 和 13 節)。
交接
下一步是 motion-build(暫存、場景、音效、渲染)。它會讀取 src/plan.json 和 video/STORYBOARD.md 的時間部分。任何後續的語音變更都會重新執行 build_vo.py 和 timing_md.py;場景快取會接著重新渲染所有內容。