Communitygithub.com

josueh04/product-video-skills

製品ビデオのナレーションをスクリプト化し、ワードタイミング、発音修正、効果音、ラウドネス調整を含む音声クリップに変換します。

product-video-skills とは?

このスキルは、製品ビデオ制作におけるスクリプト作成から音声クリップ生成、効果音追加までを自動化する統合パイプラインです。スクリプトを「モーメント」と呼ばれるテーブル形式で記述し、各センテンスを個別の音声クリップ(lines.tsv)に変換します。TTSエンジンはElevenLabs(有料)またはmacOSの無料sayボイスをサポートし、ブランド名の発音修正、クリップごとの音量正規化、ワード単位のタイミング情報(timings.json)を自動生成します。さらに、実際のキーストローク録音からタイピング効果音を生成し、クリックやポップ音を配置する機能も備えています。このスキルは、スクリプト変更が1クリップの再生成と後続のタイミング再計算に留まる設計で、アニメーションと音声の同期を効率的に維持します。主なユースケースは、ビデオのナレーション作成、音声キャスティング、発音修正、音量調整、効果音追加、そして無音ループ動画の制作です。

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

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

スクリプトと音声

音声はビデオの時計です。アニメーションのすべてのビートはナレーションの単語に固定されます(T[clip] + w(clip, "word")(build.py内))。そのため、スクリプトとそのクリップはアニメーションより先に作成され、センテンスを変更すると1つのクリップが再生成され、その後のすべてのタイミングが再計算されます。このスキルの基となった制作現場では、この設計により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 を lint
"$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]  # ASR はブランド単語を認識したか?
"$PVS_HOME/bin/pvs-py" "$S/make_sfx.py" <video_dir> [--list]            # sfx.tsv、またはライブラリ一覧表示

1. スクリプトはモーメントのテーブル

製品の録画は参照用であり、タイムラインではありません。実際のローディング待ちや画面遷移はビデオに含めるべきではありません。スクリプトはモーメントとして記述し、各モーメントには画面で起こること、センテンス(または無音)、その持続時間を含めます。モーメントの長さは、アクションとセンテンスのうち長い方になります。実際の待ち時間は短縮します。40秒のローディングは、思考中の状態として約2秒に圧縮します。

テーブルを BRIEF.md の ## Script セクションに、章の順序で追加します:

モーメント画面表示行テキスト(または無音)保持時間
オープニングアプリがぼやけた状態の上に製品名N1これはAcme Tasks、あなたの一日を計画するTODOリストです。0.8秒後
待機計画が構築中(無音)2.0秒

次に、ビデオのフォーマットに合ったテンプレートを選び、その構造に従ってください:references/script-templates.md(ピッチ、ツアー、ドキュメントページ、チュートリアル、無音ループ)を参照。

行の書き方とその理由:

  • 重要な機能を説明し、列挙しないでください。 UIが動作している間に、その機能が視聴者にとって何をするかを伝えてください。このスキルの基となった制作現場では、26バージョンのうち9つが、機能を説明せずに名前だけを挙げたために発生しました。COVERAGE.md には、画面上で説明が必要な機能が示されています。「説明必須」とマークされた行はすべて、それを説明する少なくとも1行が必要です。
  • 製品を一度も見たことがない人に各ステップを説明してください。 キャラクターが誰か、何を要求するか、各ステップが何をするか。説明のない速いオープニングはレビューで却下されました。
  • 1つのアイデアにつき1センテンス、1クリップにつき1センテンス。 そうすれば、センテンスを変更しても1クリップのコストで済みます。
  • カーソルが触れるものに名前を付けてください。 ビートはその単語に固定されるため、画面上の名詞とクリップ内の単語は同じでなければなりません。
  • 実際のUIラベルを使用してください。 レビュアーが別の言葉を使っていても。そうすれば、ビデオは視聴者が製品で見るものと一致します。
  • 数字と時刻は単語で書いてください(「10時」、「30分後」)。TTSエンジンは数字を一貫して読まず、音声認識によるQAは単語を比較し、数字は比較しません。
  • 待ち時間の前後に余裕を持たせてください。 電話が鳴る約3秒前、「正確な時間」ではなく「約1分」など、誰も検証できない正確な数字は避けます。
  • 完全なセンテンスで終わり、少し遅く読んでください。 最後の行がタグラインの断片だとレビューで途切れて聞こえると評価されました。CLAIMS.md のポジショニングを含む完全なセンテンスは問題ありませんでした。
  • ビデオ内では人称を統一してください。一人称の架空ユーザー(「最初に、カレンダーを接続します。」)または三人称で説明します。product.yaml の架空キャストのみを使用し、すべてのビデオで同じ名前にしてください。
  • ポジショニングはCLAIMS.mdから取得し、ソースドキュメントからは取得しません。ソースドキュメントにはチームが禁止したフレーズが含まれている可能性があり、ルールが優先されます。

2. lines.tsv

audio/lines.tsv、タブ区切り、ヘッダー id role speed text、再生順に1行1クリップ、# 行はコメントです。完全なフォーマットと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ではなくroleが音声を選びます。
  • 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、不明なrole、範囲外のspeed、40語超のクリップ、禁止用語、never_sayフレーズ、レガシー名、スクリプト内の発音書き換えを検出し失敗します。また、長いクリップ、数字、ダッシュについては警告します。音声化する前にすべてのエラーを修正してください。禁止フレーズがTTSに渡されるとテイクのコストが発生し、レンダリングに達するとバージョンのコストが発生します。

3. キャスティング

音声を提案する前に references/casting-and-pronunciation.md を読んでください。要約:

  • 最初にリアルな音声を提案してください。製品のデフォルト音声と最も安いモデルはレビューで「非常に偽物」と評価されました。最も自然なモデルがキャラクターには価値があります。
  • コンテキストでオーディションを行います。ロールごとに実際の連続した2行、ロールごとに3〜6人の候補。
  • 各選択を拒否権付きで、推奨デフォルトを含むクローズドクエスチョンとして提案します(「ナレーター:音声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、2パス、ピーク -1.5 dBTP未満)、両端をフェードし、クリップのエントリを audio/timings.json にマージします。

各処理ステップの存在理由:

  • 生テイクは常にアーカイブされ、常にソースです。 以前のクライアントでは、フル再レンダリング後に古い生ファイルから正規化していました。ここでは、クリップは常にそれを生成したテイクから再構築されます。
  • 末尾は最後の単語から最大0.6秒後にカットされ、フェードされます。 TTSテイクはクリックや別のフレーズの開始で終わることがあり、そのようなクリックが「変なカット」として出荷されました。
  • すべてのクリップは同じラウドネスです。 あるキャラクターの音声は、正規化前はナレーターより6 dB大きくなっていました。
  • 変更のない行はスキップされます(audio/raw/cache.json のテキスト、音声、設定のハッシュによる)。そのため、1行編集後にフル実行してもプロバイダー呼び出しは1回です。clip_lufs や処理のみが変更された場合、クリップはアーカイブテイクから無料で再構築されます。--force は強制的に新しいテイクを要求します。

キーはスクリプトが環境変数または PVS_HOME/.env から読み取り、決して出力されません。自分で .env を読んだり、チャットでキーを要求したりしないでください。キーがない場合は、ユーザーに自分で .env に行を追加するよう伝えるか、say に切り替えてください。

新しいテイクのたびに pronounce_check.py を実行してください。ASRにプロンプトを与えずに各クリップを文字起こしし、認識されなかったブランド単語やキャスト単語、聞かれたレガシー名、および逸脱した母音(セクション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}   # 第一母音チェック付き

レビュアーが名前の発音が間違っていると言った場合、1行に対して3〜4つの発音書き換えを試し、母音チェックで測定し、合格したものを保持し、その単語が含まれる他のすべての行もチェックしてください。プロバイダーはテイクごとに異なります。詳細と母音テーブル:references/casting-and-pronunciation.md。

6. テイク

  • ユーザーが特に指示しない限り、1行につき最大2テイク。プロバイダーのクォータは通常チームで共有されます。フル実行に必要な文字数を実行前に伝えてください。
  • 必要な行のみを再生成:tts.py <video_dir> --only N7 --force。
  • 新しいテイクが悪化した場合、--only N7 --restore でタイミングごと元に戻します。
  • トーンノート(「盛りすぎ」「半分のセンテンスのように聞こえる」)の場合、ロールバリアントまたは速度変更として2〜3つのバリエーションを作成し、レビュアーが前後の行と一緒にコンテキストで比較できるようにします。
  • 行を変更する場合の手順:バージョンファイルをコピーし、行を編集し、check_script.py、tts.py --only <id>、pronounce_check.py --only <id>、その後コンポーザーが再構築。そのクリップ以降のすべては自動的に移動します。

7. 効果音

HyperFramesに同梱されているライブラリの録音されたサウンドのみを使用します(make_sfx.py --list)。合成されたタイピング音は「ストローのようだ」、合成されたウィッシュ音は「ホワイトノイズ」とレビューで評価されたため、ウィッシュやライザーはスクリプトによって拒否され、ブリーフで要求されない限りナレーションの下に音楽は一切入りません。このスキルの基となった制作現場では、音楽ベッドもダッキングもなしで出荷され、誰も気にしませんでした。

  • タイピング: 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。同じオーディオトラック上の2つのクリップは決して重なってはいけません。クリップは前のクリップが終了してから少なくとも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.

関連スキル