HyperFrames メディア前処理
コンポジションのアセットを生成する3つのCLIコマンド:tts(音声合成)、transcribe(文字起こし)、remove-background(透明な動画)。各コマンドは初回実行時にモデルをダウンロードし、~/.cache/hyperframes/にキャッシュします。出力をプロジェクトに配置し、コンポジションHTMLから参照します。音声/動画要素の規則については、hyperframesスキルを参照してください。
テキスト読み上げ(tts)
Kokoro-82Mを使用してローカルで音声ファイルを生成します。APIキーは不要です。
npx hyperframes tts "ここにテキスト" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma --output narration.wav
npx hyperframes tts --list # 全54種類の音声を表示
音声の選択
コンテンツに合わせて音声を選択します。デフォルトは af_heart です。
| コンテンツタイプ | 音声 | 理由 |
|---|---|---|
| 製品デモ | af_heart/af_nova | 温かみがあり、プロフェッショナル |
| チュートリアル | am_adam/bf_emma | 中立で、聞き取りやすい |
| マーケティング | af_sky/am_michael | エネルギッシュまたは権威的 |
| ドキュメント | bf_emma/bm_george | 明瞭なイギリス英語、フォーマル |
| カジュアル/SNS | af_heart/af_sky | 親しみやすく、自然 |
多言語対応
音声IDの最初の文字で言語をエンコードしています:a=アメリカ英語、b=イギリス英語、e=スペイン語、f=フランス語、h=ヒンディー語、i=イタリア語、j=日本語、p=ブラジルポルトガル語、z=中国語(北京語)。CLIは接頭辞から音素化ロケールを自動検出します。音声がテキストと一致する場合は--langは不要です。
npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
npx hyperframes tts "今日はいい天気ですね" --voice jf_alpha --output ja.wav
自動検出を上書きする場合のみ--langを使用します(様式化されたアクセント用)。有効なコード:en-us、en-gb、es、fr-fr、hi、it、pt-br、ja、zh。英語以外の音素化には、システム全体にespeak-ngが必要です(brew install espeak-ng / apt-get install espeak-ng)。
速度
0.7-0.8— チュートリアル、複雑なコンテンツ、アクセシビリティ1.0— 自然なペース(デフォルト)1.1-1.2— イントロ、トランジション、アップビートなコンテンツ1.5+— 適切な場面は稀。注意深くテスト
長いスクリプト
数段落を超える場合は、.txtファイルに書き込んでパスを渡します。約5分以上の音声入力は、セグメントに分割すると効果的な場合があります。
必要条件
Python 3.8以上、kokoro-onnxおよびsoundfile(pip install kokoro-onnx soundfile)。初回使用時にモデルをダウンロード(約311 MB + 約27 MBの音声、~/.cache/hyperframes/tts/にキャッシュ)。
文字起こし(transcribe)
単語レベルのタイムスタンプを含む正規化された transcript.json を生成します。
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model small --language es
npx hyperframes transcribe subtitles.srt # 既存の字幕をインポート
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json
言語ルール(譲歩不可)
ユーザーが明示的に音声が英語であると指定した場合を除き、.enモデルは絶対に使用しないでください。 .enモデル(small.en、medium.en)は、英語以外の音声を文字起こしせずに英語に翻訳します。これにより、元の言語が黙って失われます。
- 言語が既知で英語以外 →
--model small --language <コード>(.en接尾辞なし) - 言語が既知で英語 →
--model small.en - 言語が不明 →
--model small(.enなし、--languageなし)— Whisperが自動検出
デフォルトモデルは small であり、small.en ではありません。
モデルサイズ
| モデル | サイズ | 速度 | 使用する場面 |
|---|---|---|---|
tiny | 75 MB | 最速 | クイックプレビュー、パイプラインのテスト |
base | 142 MB | 高速 | 短いクリップ、明瞭な音声 |
small | 466 MB | 中程度 | デフォルト — ほとんどのコンテンツ |
medium | 1.5 GB | 低速 | 重要なコンテンツ、ノイズのある音声、音楽 |
large-v3 | 3.1 GB | 最低速 | プロダクション品質 |
ボーカルを含む音楽:最低でも medium から開始。生成されたトラックは、手動でSRT/VTTをインポートする必要があることがよくあります。キャプション品質チェック(すべての文字起こし後に必須)、クリーニングJS、リトライルール、OpenAI/Groq APIインポートパスについては、hyperframes/references/transcript-guide.mdを参照してください。
出力形式
コンポジションは単語オブジェクトのフラットな配列を消費します。idフィールド(w0、w1、...)は、キャプションオーバーライドで安定した参照を行うために正規化中に追加されます。後方互換性のため、省略可能です。
[
{ "id": "w0", "text": "Hello", "start": 0.0, "end": 0.5 },
{ "id": "w1", "text": "world.", "start": 0.6, "end": 1.2 }
]
背景除去(remove-background)
動画や画像から背景を除去し、コンポジション内で透明なオーバーレイとして配置できるようにします(例:背景プレートの上に浮かぶアバター)。
npx hyperframes remove-background avatar.mp4 -o transparent.webm # デフォルト:VP9アルファWebM
npx hyperframes remove-background avatar.mp4 -o transparent.mov # ProRes 4444(編集用)
px hyperframes remove-background portrait.jpg -o cutout.png # 単一画像の切り抜き
npx hyperframes remove-background avatar.mp4 -o transparent.webm --device cpu
npx hyperframes remove-background --info # 検出されたプロバイダーを表示
u2net_human_seg(MITライセンス)を使用。初回実行時に約168 MBの重みを~/.cache/hyperframes/background-removal/models/にダウンロードします。
出力形式
| 形式 | 使用する場面 |
|---|---|
.webm(VP9 + アルファ) | デフォルト。コンポジションで<video>を使って直接再生します。 |
.mov(ProRes 4444) | DaVinci/Premiere/FCPでの編集用。ファイルサイズが大きくなります。 |
.png | 単一画像の切り抜き(静止した被写体、背景に重ねる場合)。 |
ChromeはVP9アルファをネイティブでデコードするため、.webmは他のミュート自動再生ビデオと同様にコンポジションに組み込めます。<video>トラックの規則についてはhyperframesスキルを参照してください。
TTS → 文字起こし → キャプション
録音済みのナレーションがない場合、音声を生成してから文字起こしすることで、キャプション用の単語レベルのタイムスタンプを取得できます。
npx hyperframes tts script.txt --voice af_heart --output narration.wav
npx hyperframes transcribe narration.wav # → transcript.json
Whisperは生成された音声から正確な単語境界を抽出するため、手動調整なしでキャプションのタイミングが配信に一致します。