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 | 明瞭なイギリス英語、フォーマル |
| カジュアル/ソーシャル | 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 <code>(.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 subject.mp4 -o transparent.webm # デフォルト:VP9 アルファ WebM
npx hyperframes remove-background subject.mp4 -o transparent.mov # ProRes 4444(編集用)
u2net_human_seg(MIT)を使用します。初回実行時に約168 MBの重みを~/.cache/hyperframes/background-removal/models/にダウンロードします。
レイヤー分離 (--background-output)
--background-output(または-b)を渡すと、カットアウトと一緒に2番目の透明ビデオを出力します。同じソースRGBで、アルファはmaskの代わりに255 − maskになります。カットアウトは背景が透明な被写体です。プレートは、被写体があった場所に透明な穴が開いた元の背景です。
| ファイル | アルファは… | 使用目的 |
|---|---|---|
-o subject.webm | マスク — 被写体は不透明、背景は透明 | 前景レイヤー、上に配置 |
--background-output plate.webm | 反転 — 背景は不透明、被写体領域は透明 | 下層レイヤー。このレイヤーと被写体の間にテキストやグラフィックを配置 |
両方の出力は同じ--qualityプリセットを共有し、単一の推論パスから実行されます — エンコードコストは約2倍になりますが、セグメンテーションコストは変わりません。ビデオ入力および.webm/.mov出力でのみ有効です。
穴抜きプレートであり、インペイントされたクリーンプレートではありません。 plate.webm内の被写体領域は完全に透明です — 穴を埋めるためにその下に不透明なものを合成します。--background-outputが適切なツールかどうかの単一のテスト:被写体がかつてあった場所のシルエットを通して何かが見えることはありますか?
| ユースケース | 適切なツール |
|---|---|
| カットアウトとプレートの間のテキスト/グラフィック(このコマンドの存在理由) | 穴抜き(--background-output) |
| 被写体を無関係なシーンに重ねる | subject.webmのみ;プレートは無視 |
| 部屋を_人物なしで_、他のコンテンツなしで単独で表示 | クリーンプレート — インペインター(LaMa、ProPainter、E2FGVI)が必要。このコマンドでは不可。 |
| 被写体を別の被写体に置き換える | クリーンプレート — 同上 |
ユーザーが「人物を除去した部屋」を求め、それを単独で表示する意図がある場合、--background-outputを使用しないでください。インペインターが必要であることを伝えてください。
典型的なレイヤー構成(標準的な穴抜きのユースケース):
<!-- z=1 反転アルファプレートが被写体領域以外をすべて埋める -->
<video
src="plate.webm"
data-start="0"
data-duration="6"
data-track-index="0"
muted
playsinline
></video>
<!-- z=2 グラフィック/テキストが2つのレイヤーの間にある -->
<h1 id="headline" style="z-index:2; ...">HYPERFRAMESで作ろう</h1>
<!-- z=3 カットアウトが被写体を見出しの上に浮かべる -->
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3">
<video
src="subject.webm"
data-start="0"
data-duration="6"
data-track-index="1"
muted
playsinline
></video>
</div>
これは、以下のテキスト-被写体-背後パターンと機能的に同等ですが、プロジェクトに元のpresenter.mp4を必要としません — プレートがそれを置き換えます。2つの透明レイヤーのみを提供し、ユーザーがそれらの間に任意のコンテンツをドロップできるようにする場合に便利です。
出力形式
| 形式 | タイミング |
|---|---|
.webm(VP9 + アルファ) | デフォルト。構成はこれを<video>で直接再生します。 |
.mov(ProRes 4444) | DaVinci/Premiere/FCPでの編集用。ファイルサイズが大きい。 |
.png | 単一画像のカットアウト(静止被写体、背景に重ねる)。 |
ChromeはVP9アルファをネイティブにデコードするため、.webmは他のミュート自動再生ビデオと同様に構成にプラグインできます — <video>トラックの規則についてはhyperframesスキルを参照してください。
品質プリセット
--quality fast|balanced|bestはVP9エンコーダのCRFのみを制御します — セグメンテーション品質は固定です。
| プリセット | CRF | タイミング |
|---|---|---|
fast | 30 | 反復作業、ファイルサイズ小、色の一致が緩い |
balanced | 18 | デフォルト。ほとんどの用途で視覚的に同一 |
best | 12 | マスター/最終納品。最大ファイルサイズ、最も厳密な一致 |
合成パターン — 適切なものを選択
カットアウトWebMは、ソースMP4のRGBの再エンコードコピーです。その選択は、背後に何を配置するかによって結果が異なります:
| パターン | カットアウトの背後にあるもの | 結果 |
|---|---|---|
| カットアウトを別のシーンに重ねる(最も一般的) | 静止画像、グラデーション、または無関係なビデオ | 見栄えが良い。カットアウトのRGBは被写体の唯一のソース — 二重化やエッジハローなし。これがremove-backgroundの設計目的です。 |
| カットアウトを自身のソースMP4に重ねる(テキスト-被写体-背後) | カットアウトが生成された同じMP4 | 同じ人物の2つのRGBソース。デフォルトの--quality balanced(crf 18)では二重化はほとんど目立ちません。--quality fast(crf 30)では、かすかな色のずれやエッジハローが見られます。マスターには--quality best(crf 12)を使用してください。 |
| カットアウトを同じ人物の_異なる_テイクに重ねる | 同じ被写体の映像 | 2人の別々の人物が重なっているように見えます。これを行わないでください。 |
テキスト-被写体-背後(プレゼンターの背後に見出し):
<video
src="presenter.mp4"
id="bg"
data-start="0"
data-duration="6"
data-track-index="0"
muted
playsinline
></video>
<h1 id="headline" style="z-index:2; ...">HYPERFRAMESで作ろう</h1>
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3;opacity:0">
<video
src="presenter.webm"
data-start="0"
data-duration="6"
data-track-index="1"
muted
playsinline
></video>
</div>
2つの重要なルール:
- カットアウトビデオをタイミング指定なしの
<div>でラップし、ビデオ要素自体ではなくラッパーの不透明度をアニメーション化します。フレームワークはアクティブなクリップ(data-start/data-durationを持つ要素)に不透明度1を強制するため、ビデオの不透明度を直接アニメーション化すると暗黙的に上書きされます。ラッパーにはdata-*属性がないため、CSS/GSAPで制御されます。 - 両方のビデオで
data-start="0"およびdata-media-start="0"を使用して、フレームワークがt=0から同期してデコードするようにします。カットアウトを遅延マウント(data-start=3.3)すると、シーク+ウォームアップが発生し、ベースMP4から1フレームずれて着地します — カットで1フレームの位置ずれとして見えます。
次に、GSAPでカットの時点でラッパーの不透明度を反転します:tl.set(cutoutWrap, { opacity: 1 }, 3.3)。
TTS → 文字起こし → 字幕
事前録音されたナレーションがない場合、ナレーションを生成して文字起こしに戻すことで、字幕用の単語レベルのタイムスタンプを取得します:
npx hyperframes tts script.txt --voice af_heart --output narration.wav
npx hyperframes transcribe narration.wav # → transcript.json
# あとはキャプションを付加:
npx hyperframes transcribe subtitles.vtt --from transcript.json --output captions.vtt
npx hyperframes transcribe subtitles.srt --from transcript.json --output captions.srt
--fromフラグを使用すると、文字起こしCLIが既存のtranscript.jsonに基づいてSRT/VTTを生成します。各コマンドは独立しているため、手動でテキストを編集してからtranscribeを再度実行してキャプションファイルを再生成できます。
なぜこの順序か
このコマンドによるナレーションは、通常の音声とは異なる音響特性を持っています。Whisperがそれらを文字起こしする際の精度は良好ですが、事前録音されたオーディオほど高くはありません。このワークフローにより、同一のオーディオファイルからタイムスタンプを取得できるため、手動で調整するよりもはるかに優れています。
AIエージェントがTTSと文字起こしの両方のコマンドを認識している場合、任意のスクリプトから自動的にキャプション付きナレーションを生成できます。