スクリプトと音声
音声はビデオの時計です。アニメーションのすべてのビートはナレーションの単語に固定されます(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 を手動で編集しないでください。クリップから再生成され、手動編集は次回実行時に失われます。
ユーザーに報告する内容:音声化された行、各クリップの長さ、発音フラグと聞こえた内容、使用された音声(まだ未確定のものには推奨デフォルト)、およびプロバイダーで消費された文字数。