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 <コード>(.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": "こんにちは", "start": 0.0, "end": 0.5 },
{ "id": "w1", "text": "世界。", "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(編集用)
w hyperframes remove-background portrait.jpg -o cutout.png # 単一画像の切り抜き
npx hyperframes remove-background subject.mp4 -o subject.webm \
--background-output plate.webm # 両方のレイヤーを1パスで
npx hyperframes remove-background subject.mp4 -o transparent.webm --device cpu
npx hyperframes remove-background --info # 検出されたプロバイダー
u2net_human_seg(MIT ライセンス)を使用。初回実行時に約 168 MB の重みを ~/.cache/hyperframes/background-removal/models/ にダウンロードします。
レイヤー分離(--background-output)
--background-output(または -b)を渡すと、切り抜きとは別に2番目の透明動画を出力します。同じソース RGB ですが、アルファはマスクの代わりに 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 | 同じ人物の RGB ソースが2つ。デフォルトの --quality balanced(crf 18)では二重化はほとんど見えません。--quality fast(crf 30)ではかすかな色ずれ/エッジハローが見える可能性があります。マスター用に --quality best(crf 12)を使用。 |
| 同じ人物の_別テイク_に重ねる | 同じ被写体の別の映像 | 別々の人物が重なっているように見えます。行わないでください。 |
テキスト背後被写体(プレゼンターの後ろに見出し):
<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を持つ要素)に対して opacity: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
これにより、ナレーション(narration.wav)と単語レベルのタイムスタンプ(transcript.json)の両方が得られます。transcript.json を hyperframes スキルのキャプションレンダラに渡すと、ナレーションと完全に同期したクローズドキャプションが生成されます。
パイプライン内の各ステップは独立して再実行可能です。ナレーションを編集した場合は transcribe を再実行するだけでキャプションを更新できます。