腳本與語音
語音是影片的時鐘。動畫的每一個節拍都錨定在旁白的某個單詞上(T[clip] + w(clip, "word"),位於 build.py 中),因此腳本及其片段應在動畫之前生成,修改一句話只會重建一個片段,並重新計算其後所有內容的時間。在這些技能所源自的製作流程中,因為這種設計,更換整個 TTS 引擎可以在無需手動編輯的情況下,重新調整已完成的影片時間。如果先製作動畫再配語音,則每次修改都需手動拉伸音訊或拖動節拍。
所有檔案僅寫入 <video_dir>/audio/ 目錄(以及 BRIEF.md 中的腳本區段)。每個句子都必須在 TRUTH.md 中有依據,並遵守 CLAIMS.md;如果所需的句子沒有來源,請要求驗證或將其刪除。
腳本(如 docs/contracts.md 中所定義):
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
S="$PVS_HOME/skills/script-and-voice/scripts"
"$PVS_HOME/bin/pvs-py" "$S/check_script.py" <video_dir> # 檢查 lines.tsv 格式
"$PVS_HOME/bin/pvs-py" "$S/tts.py" <video_dir> [--only N3,N4] [--provider say] [--force] [--restore]
"$PVS_HOME/bin/pvs-py" "$S/pronounce_check.py" <video_dir> [--only N3] # 自動語音辨識是否正確識別了品牌詞?
"$PVS_HOME/bin/pvs-py" "$S/make_sfx.py" <video_dir> [--list] # 生成 sfx.tsv,或列出音效庫
1. 腳本是一張時刻表
產品的錄製畫面是參考,而非時間軸:實際的載入等待和螢幕變化不應出現在影片中。將腳本寫成一系列「時刻」,每個時刻包含螢幕上發生的事、對應的句子(或靜默)以及持續時間。一個時刻的持續時間由其動作和句子中較長者決定。壓縮真實的等待時間:四十秒的載入過程,大約濃縮成兩秒的思考狀態。
將表格以章節順序新增到 BRIEF.md 的 ## Script 下方:
| Moment (時刻) | On screen (螢幕畫面) | Line (行號) | Text (or silence) (文字或靜默) | Holds (停頓) |
|---|---|---|---|---|
| Opening (開場) | Product name over the app out of focus (產品名稱疊加在模糊的應用程式上) | N1 | This is Acme Tasks, the to-do list that plans your day. (這是 Acme Tasks,能為你規劃一天的待辦清單。) | 0.8 s after (結束後停 0.8 秒) |
| Wait (等待) | The plan is being built (正在建立計劃) | (silence) (靜默) | 2.0 s |
然後,根據影片格式選擇範本並遵循其結構:請參閱 references/script-templates.md(包含:提案、導覽、文件頁面、教學、無聲循環)。
如何書寫台詞及其原因:
- 解釋重要功能,但不要列出它們。 在 UI 執行某個功能時,告訴觀眾這個功能對他們有什麼幫助。在這些技能所源自的製作流程中,26 個版本中有 9 個版本需要修改,是因為影片只提到了功能名稱卻沒有解釋它。COVERAGE.md 會指出哪些功能必須在螢幕上解釋:每個標記為 "must explain" 的行,都需要至少一行台詞來說明它。
- 對從未見過該產品的人解釋每個步驟。 說明角色是誰、他們要求什麼、每個步驟的作用。一個節奏太快且未經解釋的開場在審查中被拒絕了。
- 一句話一個想法,一個片段一句話。 這樣修改一句話只會影響一個片段。
- 在游標觸碰某個元素時,說出該元素的名稱。 動畫節拍會錨定在這些單詞上,因此螢幕上的名詞和音訊中的單詞必須一致。
- 使用真實的 UI 標籤,即使審查者使用其他詞彙。這樣影片才能與觀眾在產品中看到的內容相符。
- 用文字書寫數字和時間(例如 "ten a.m."、"thirty minutes later")。TTS 引擎讀取數字時不一致,而且語音轉文字的品質檢查比對的是單詞,而非數字。
- 在等待前後保留一些空閒時間。 例如,電話鈴響前約三秒,或使用 "about a minute" 而非一個無人能驗證的精確數字。
- 以完整的句子結尾,並以稍慢的速度朗讀。 在審查中,如果最後一句是標語片段,聽起來會像被切斷;而一個包含 CLAIMS.md 定位的完整句子則不會有此問題。
- 保持影片中人稱一致:使用第一人稱作為虛構使用者("First, I connect my calendar."),或用第三人稱描述他們。僅使用 product.yaml 中定義的虛構角色,並在所有影片中使用相同的名稱。
- 產品定位來自 CLAIMS.md,而非原始文件:原始文件可能包含團隊已禁止使用的詞語,此時應以規則為準。
2. lines.tsv
audio/lines.tsv,使用 Tab 分隔,標題行爲 id role speed text,每個片段依照播放順序佔用一行,# 開頭的行為註解。完整格式以及 build.py 如何讀取結果:請參閱 references/audio-formats.md。
- id:旁白使用
N1、N2、N7b;其他角色使用不同字母前綴(A1代表客服人員,C1代表客戶)。在 N7 和 N8 之間插入一行並命名為N7b,可以保持其他所有 ID 及其錨點的穩定性。 - role:對應
product.yaml中voice.roles的某個鍵值(narrator、agent、customer,或朗讀變體如narrator_close,參見第 3 節)。語音的選擇依據的是角色,而非 ID。 - speed:預設為 1.0,範圍 0.7 到 1.2。開場和結尾台詞可使用 0.9 到 0.96。
- text:必須與螢幕上顯示以及字幕完全一致,並使用產品名稱的標準拼寫。切勿在此處書寫發音重拼;發音相關設定位於 product.yaml 中。
在修改已交付版本的台詞前,請先將 lines.tsv 複製為 lines-v<N>.tsv,將 timings.json 複製為 timings-v<N>.json,以便能夠重建先前版本。
每次編輯後執行 check_script.py。它會檢查重複的 ID、未知的角色、超出範圍的語速、超過 40 個單詞的片段、禁用詞語、never_say 片語、腳本中的舊名稱和重拼詞,並對過長的片段、數字和破折號發出警告。在生成語音前修復所有錯誤:禁用詞語一旦進入 TTS 就需要重新錄製,而進入最終渲染則會導致版本更新。
3. 選角
在提議語音前,請先閱讀 references/casting-and-pronunciation.md。簡而言之:
- 優先選擇聽起來自然的語音。產品預設語音和最便宜的模型在審查中被認為「非常假」;對角色而言,市面上最自然的模型是值得的。
- 在上下文中試聽:每個角色提供兩行連續的真實台詞,每個角色試聽三到六個候選者。
- 對於每個選擇,以封閉式問題提出建議,並附上推薦的預設選項(例如:「旁白:語音 B,溫暖且從容。保留此選項嗎?」)。開放的選項列表可能會好幾天都沒有回覆。
- 決定每個角色的處理方式:通話中的角色使用
treatment: phone,錄製的會議使用treatment: room,旁白則無需任何處理。 - 逐行朗讀(更平穩、更慢、風格更少)是一種角色變體,它指向同一個語音但使用其他設定,因此選擇存在於配置中,重新執行時仍然有效。
voice.provider: say(或 --provider say)使用免費的 macOS 語音和 whisper 來獲取單字時間戳。在開發金鑰之前,將其用於草稿、測試和時間調整;最終交付時應使用真實語音。
4. 生成音訊片段
"$PVS_HOME/bin/pvs-py" "$S/tts.py" <video_dir>
對於每行台詞,它僅為 TTS 重新拼寫品牌詞,將未經修改的原始錄音保留在 audio/raw/ 目錄中(先前的錄音會移至 audio/raw/prev/),修剪靜音,重新取樣為 48 kHz 單聲道,應用角色的處理方式,標準化至 voice.clip_lufs(使用 ffmpeg loudnorm,兩次通過;峰值低於 -1.5 dBTP),淡入淡出,並將該片段的條目合併到 audio/timings.json 中。
每個處理步驟存在的理由:
- 原始錄音始終被歸檔,並始終作為來源。 早期某客戶端在一次完整重新渲染後,從一個過時的原始檔案進行標準化;現在,每個片段都會從產生它的原始錄音重建。
- 音訊尾部最多在最後一個單詞後 0.6 秒處被切斷,並附帶淡出。 TTS 錄音可能以點擊聲或另一個短語的開頭結尾;曾有一個這樣的點擊聲作為「奇怪的中斷」出現在音訊中。
- 每個片段具有相同音量。 在標準化之前,某個角色語音比旁白大了 6 dB。
- 未更改的台詞會被跳過(根據文字、語音和設定的雜湊值,記錄在
audio/raw/cache.json),因此編輯一行台詞後進行完整執行,只會呼叫提供者一次。如果只更改了clip_lufs或處理方式,則會從歸檔的原始錄音免費重建片段。使用--force無論如何都會要求新的錄音。
金鑰由腳本從環境變數或 PVS_HOME/.env 檔案讀取,且絕不會被輸出。切勿自行讀取 .env 檔案,也切勿在對話中要求金鑰:如果缺少金鑰,請告訴使用者自行將該行新增到 .env 檔案中,或切換為 say。
在任何新的錄音後執行 pronounce_check.py。它會在沒有提示的情況下轉錄每個片段,標記未被識別的品牌和角色詞、被聽到的舊名稱,以及偏移的母音(第 5 節)。標記代表需要聆聽,而非重新生成:ASR 可能會誤聽實際上正確說出的品牌詞。
5. 發音
腳本和螢幕保留真實拼寫。product.pronounce 僅更改發送給 TTS 的內容,且 tts.py 會將時間戳對應回來,因此 timings.json 在 w 中保留螢幕上的單詞,在 say 中保留重拼({"w": "Acme", "say": "AK-mee", ...})。build.py 中的錨點使用螢幕上的單詞。
product:
pronounce:
Acme: AK-mee # 單純的重拼
Acme Tasks: {say: AK-mee Tasks, vowel: ae, confusable: ey} # 包含母音檢查
當審查者表示名稱聽起來不對時,請在一行台詞上嘗試三到四種重拼方案,使用母音檢查來評估它們,保留通過檢查的方案,然後檢查所有包含該單詞的其他台詞行:不同錄音之間提供的結果可能不同。詳細資訊和母音表:references/casting-and-pronunciation.md。
6. 錄音
- 除非使用者另有指示,否則每行台詞最多錄製兩次;提供者的配額通常是團隊共享的。在執行完整運行前,先說明它將消耗多少個字元數。
- 僅重新生成需要修改的台詞:
tts.py <video_dir> --only N7 --force。 - 如果新的錄音效果更差,使用
--only N7 --restore將其與時間戳一起換回。 - 對於語氣意見(「太嗨」、「聽起來像半句話」),請製作兩到三個變體,作為角色變體或語速變化,讓審查者可以與前一句台詞在上下文進行比較。
- 修改台詞的順序為:複製版本檔案、編輯該行、
check_script.py、tts.py --only <id>、pronounce_check.py --only <id>,然後合成器進行重建;該片段之後的所有內容會自動移動。
7. 音效
僅使用來自 HyperFrames 附帶音效庫的錄製音效(使用 make_sfx.py --list 列出)。合成的打字音效聽起來「像吸管,而不是鍵盤」,合成的呼嘯聲聽起來像「白噪音」,因此在審查中被拒絕;腳本也會拒絕呼嘯聲和漸強音,且除非簡報要求,否則旁白下方不會有任何音樂。這些技能所源自的製作流程最終交付的成品沒有背景音樂,也沒有音訊閃避(Ducking),但沒有人覺得缺少什麼。
- 打字音效:
typing_track(text, start, cps)使用從真實錄音中剪出的單個按鍵聲建立音軌,空格鍵敲擊聲較重,並具有種子驅動的節奏,因此它是確定性的,同樣的文字聽起來總是一樣。讓它的持續時間正好等於顯示文字的節拍長度(dur=),並讓打出的單詞與說出的單詞同時出現。 - 點擊和彈出音效:在游標按下影格時使用
library_sfx("click", start)。 audio/sfx/CREDITS.md列出了使用的每個音效庫檔案及其許可證。- 建議的音量:旁白 1.0,角色 1.0,點擊聲 0.35(拖曳釋放時為 0.22),打字聲 0.45,彈出聲 0.12 至 0.3。同一個音軌上的兩個片段絶對不能重疊:一個片段必須在前一個片段結束至少 0.02 秒後開始,或將其移至另一個音軌。
build.py 會匯入這些函數;make_sfx.py <video_dir> 配合 audio/sfx.tsv 可以從命令列預先建立相同的檔案(格式在腳本的 docstring 中)。
8. 移交給合成器
在 <video_dir>/audio/ 目錄下交付:lines.tsv、clips/<id>.wav、timings.json,以及包含 CREDITS.md 的 sfx/ 目錄。告知合成器每個節拍應錨定到哪些單詞(游標觸碰的名詞、打字效果落定的單詞),以及來自時刻表的等待時間。切勿手動編輯 timings.json:它會從片段重新生成,手動編輯的內容將在下一次執行時遺失。
向使用者報告:已生成語音的台詞、每個片段的持續時間、任何發音標記及其聽到的內容、所使用的語音(針對任何尚未決定的選項提供推薦預設值),以及消耗的提供者字元數。