Communitygithub.com

josueh04/product-video-skills

編寫產品影片旁白,並將其轉換為帶有單字時間戳、發音修正、音效甚至音量的語音片段。腳本成為時刻表,然後生成 audio/lines.tsv 和音訊檔案。

product-video-skills 是什麼?

此技能專為需要腳本、旁白、語音合成(TTS)和音效的影片製作流程而設計。它將腳本視為一系列「時刻」,每個時刻包含螢幕動作與對應的旁白句子。使用者編寫的腳本會自動轉換為 `lines.tsv` 檔案,該檔案定義每個語音片段的 ID、角色、語速和文字內容。技能核心的 `tts.py` 腳本會呼叫 ElevenLabs 或 macOS 內建的 `say` 語音引擎,為每行文字生成音訊片段,過程中會自動處理品牌名稱的發音修正、音量標準化(透過 loudnorm 確保所有片段音量一致),並在最後產生 `timings.json` 檔案,記錄每個單字的精確時間戳,供動畫合成器使用。此外,`make_sfx.py` 能從真實鍵盤敲擊聲庫中建立打字音效,並在指定時間點加入滑鼠點擊和彈出音效。此技能支援 Claude Code、Cursor 等開發代理工具,透過 CLI 指令整合進 CI/CD 流程,確保每次修改腳本或發音時,只需重新生成受影響的片段,大幅提升影片製作效率與一致性。

相容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/josueh04/product-video-skills/tree/HEAD/skills/script-and-voice

在你喜歡的 AI 中提問

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

說明文件

腳本與語音

語音是影片的時鐘。動畫的每一個節拍都錨定在旁白的某個單詞上(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 (產品名稱疊加在模糊的應用程式上)N1This 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:它會從片段重新生成,手動編輯的內容將在下一次執行時遺失。

向使用者報告:已生成語音的台詞、每個片段的持續時間、任何發音標記及其聽到的內容、所使用的語音(針對任何尚未決定的選項提供推薦預設值),以及消耗的提供者字元數。

Individual skills in this repo

This repo contains 14 individual skills — each has its own dedicated page.

josueh04/product-video-skills

Extract, once per product, everything every video of it reuses and write it to kit/ and product.yaml (design tokens, font subsets as woff2, icon subsets as SVG from the product's own icon packages, logos in light, dark and app-tile variants from the repo, a fictional cast proposed once for veto and then frozen, the canonical-names map, pronunciations, banned terms and the read-only tool list). Use it when a product is set up or its kit is missing or incomplete, when a video needs an icon, font or logo that is not in kit/ yet, when someone asks for demo names, fake customers, phone numbers or emails, when a brand word is mispronounced or an old product name shows up, and when checking that demo data is fictional.

josueh04/product-video-skills

Interview the user about a product, then create products/<slug>/ with its own git history, a filled product.yaml and linked skills, fetch its sources and build its kit. Run only when the user types /product-new.

josueh04/product-video-skills

Back every sentence of a video's narration (audio/lines.tsv) and every screen it shows with a citation into the pinned source code (role/path:line@sha) or a docs URL, mark what is visible in the UI versus backend-only, flag restricted or unreleased features, and cut or rewrite anything unbacked; writes the video's TRUTH.md and checks it with truth_check.py. Use it whenever a script or narration is drafted or edited, before voice is generated, before a build, when someone asks "can we say this?", "is this true?", "does the product really do X?", when a reviewer asks for a feature or a claim the product may not support, and when a source document (pitch deck, PRD, marketing page) makes claims the video wants to repeat.

josueh04/product-video-skills

Check a rendered product video before anyone else sees it: worker-pattern flicker, black frames, loudness and true peak, clipping, clicks at clip edges, overlapping narration, speech to text against the script, banned terms and legacy names, camera zoom, contact sheets, frame strips at transitions and parity against the approved version; then write qa/REPORT.json, the only thing deliver.py accepts. Use it after every HyperFrames render, whenever someone asks "is the render clean", "QA this", "check the video", "check the audio", "why does it flicker", "there is a click", "compare v3 with v2", "did the approved part change", or before showing, sending, uploading or delivering any MP4, even when the request does not say QA. Also use it to triage a defect a reviewer reported in a render.

josueh04/product-video-skills

The animation rules that keep HyperFrames' parallel render workers from dropping, flashing or flickering elements, plus a static lint (lint_motion.py) that finds the violations in a video's template before it costs a render. Use it whenever you write or edit GSAP tweens, timelines, cursors, camera moves, typing, scrolls or pop-ups in a HyperFrames composition or a video's src/template.tpl, whenever a render shows flicker, stutter, an element that vanishes on some frames, a title that flashes, or a "WORKER PATTERN" line from scan_render.py or qa.py, and whenever the preview looks right but the MP4 does not. Also use it to review someone else's timeline code before rendering.

josueh04/product-video-skills

Pin a product's source code (read-only exports in sources/ plus sources.lock), confirm that the pinned commit is what runs in production, and map every screen of a video brief to its route, components, i18n strings and state, written to the video's SOURCES.md. Use it whenever a video needs to know where a screen lives in the code, when sources/ is missing or stale, before ui-spec-from-code or product-truth start on a video, after the product's frontend changed ("what changed", "which videos are affected", "refresh the sources", "is this checkout current", "which commit is in prod"), and when there is no code and you need an inventory of the no-code references (recordings, recovered captures, docs) a screen can be rebuilt from.

josueh04/product-video-skills

Compose a narrated product demo in HyperFrames: the stage (the product UI rebuilt at its real viewport and scaled to 1080p, camera, rack focus with veil, chapter titles, cursor and clicks, typing, streaming text, pop-ups, toasts, scrolls, end screen and lockup) and the build.py that anchors every beat to a word of the narration. Use it whenever you write or edit a video's video/build.py, src/template.tpl or src/app.css, place a beat on a word, add a chapter, a click, a pop-up or a push-in, frame a screen, build the end screen or lockup, snapshot setup beats, or render a draft or delivery MP4 of a product video in this workbench. Also use it when someone says "the cursor is off", "too zoomed in", "too fast", "it feels chaotic", "the title flashes", "sync the UI to the voice", or asks for a walkthrough, demo or pitch video of a UI.

josueh04/product-video-skills

Gather pixel references for UI that the code cannot show, or to check a rebuild against the real thing, using frames and timed OCR text from screen recordings, captures recovered from past Claude Code session transcripts, a local instance of the app built like production, and web research for third-party apps, plus side-by-side parity images and contact sheets. Use it whenever someone hands over a screen recording (.mov or .mp4) of the product, when a screen has no usable source code (a stale checkout, another company's UI such as a sign-in page, calendar or CRM, runtime output from a backend not in the repos), when asked "what does it really look like", "match the recording", "how long does that animation take in the app", "compare our render to the real app", or when screenshots from an earlier session might already exist. Never uses the reviewer's personal browser.

josueh04/product-video-skills

Turn a product's real frontend code into 1:1 rebuild specs for a video, one read-only subagent per screen, each returning static HTML, CSS with every variable resolved to its literal value and cited (role/path:line@sha), every state, transitions with exact durations and easings, icons from the code's own icon sets, and the exact i18n strings; plus resolve_tokens.py to write the product's design tokens to kit/tokens.css. Use it whenever a screen of the product has to appear in a video, when writing or fixing video/src/app.css or the template markup, when someone asks for exact sizes, colors, fonts, paddings, animations or icons of a screen, when a rebuilt screen "looks off" next to the real app, and when the design tokens or theme of a product need extracting. Framework adapters cover Angular with PrimeNG (proven), React, Vue, Tailwind and plain HTML (unproven).

josueh04/product-video-skills

Say where this session stands in the Product Video Skills workbench (setup state, which product and video the current folder belongs to, the stage of every video) and the exact next command to type. Also answers "how do I..." questions about the workbench from its docs.

josueh04/product-video-skills

Coordinate the build of one or more signed videos of the current product with subagents (source recon, product truth, UI specs, voice, one builder per video), re-run QA itself, then deliver. A light coordinator that never builds itself. Run only when the user types /video-build.

josueh04/product-video-skills

Start a new video of the current product - create videos/<video>/, write BRIEF.md, the feature coverage matrix (COVERAGE.md) and the claims sheet (CLAIMS.md), propose chapters, then stop for the reviewer's sign-off. Never builds. Run only when the user types /video-new.

josueh04/product-video-skills

Turn a batch of reviewer feedback on the product's videos into one table per video, fix every video that got notes in parallel (one subagent each) while keeping approved parts, re-run QA and parity, bump versions and deliver. Run only when the user types /video-review.

josueh04/product-video-skills

Check this machine and install the pinned video toolchain of the Product Video Skills workbench (HyperFrames CLI, its rendering Chrome and its agent skills from the same release, the Python environment, the speech model for QA), then run the self-check. Safe to run again. `/video-setup check` only reports.

相關技能