hyperframes-media

HyperFrames メディアの前処理

コンポジション用のアセットを生成する3つのCLIコマンドです：tts（音声合成）、transcribe（タイムスタンプ）、remove-background（透明な動画）。それぞれ初回実行時にモデルをダウンロードし、~/.cache/hyperframes/ にキャッシュします。出力をプロジェクトに配置し、コンポジションのHTMLから参照してください。音声／動画要素の規約については hyperframes スキルを参照してください。

テキスト読み上げ（tts）

Kokoro-82M を使ってローカルで音声を生成します。API キーは不要です。

npx hyperframes tts "Text here" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma --output narration.wav
npx hyperframes tts --list                       # all 54 voices

音声の選択

コンテンツに合わせて音声を選びます。デフォルトは 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分を超える入力は、セグメントに分割するとよい場合があります。

必要条件

kokoro-onnx と soundfile を含む Python 3.8 以降（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          # import existing
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json

言語に関するルール（厳守）

ユーザーが音声は英語だと明示していない限り、.en モデルは絶対に使用しないでください。 .en モデル（small.en、medium.en）は、英語以外の音声を文字起こしするのではなく、英語に翻訳します。これにより、元の言語が気付かれないまま失われます。

1. 言語が既知で英語以外 → --model small --language <code>（.en サフィックスなし）
2. 言語が既知で英語 → --model small.en
3. 言語が不明 → --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  # default: VP9 alpha WebM
npx hyperframes remove-background subject.mp4 -o transparent.mov   # ProRes 4444 (editing)
npx hyperframes remove-background portrait.jpg -o cutout.png       # single-image cutout
npx hyperframes remove-background subject.mp4 -o subject.webm \
  --background-output plate.webm                                   # both layers in one pass
npx hyperframes remove-background subject.mp4 -o transparent.webm --device cpu
npx hyperframes remove-background --info                           # detected providers

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 プリセットを共有し、1 回の推論パスで生成されます。エンコードのコストはおよそ 2 倍になりますが、セグメンテーションのコストは変わりません。動画入力と .webm／.mov 出力でのみ有効です。

穴を開けたプレートであり、インペイント済みのクリーンプレートではありません。 plate.webm の被写体領域は完全に透明です。穴を埋めるには、その下に不透明なコンテンツを合成してください。--background-output が適切なツールかどうかを判断する基準は 1 つです。被写体がいた場所で、そのシルエットを通して何かが見える場面はありますか？

ユースケース	適切なツール
切り抜きとプレートの間にテキスト／グラフィックを配置（このコマンドの本来の用途）	穴を開けたプレート（--background-output）
被写体を無関係なシーンに配置	subject.webm のみを使用し、プレートは無視
他のコンテンツを重ねずに、人物のいない部屋だけを表示	クリーンプレート — インペインター（LaMa、ProPainter、E2FGVI）が必要です。このコマンドでは対応できません。
被写体を別の被写体に置き換え	クリーンプレート — 上記と同じです

ユーザーが「人物を取り除いた部屋」を求めていて、単独で表示する意図がある場合は、--background-output を使わないでください。インペインターが必要だと伝えてください。

一般的なレイヤー構成（穴を開けたプレートの代表的なユースケース）：

<video
  src="plate.webm"
  data-start="0"
  data-duration="6"
  data-track-index="0"
  muted
  playsinline
></video>


<h1 id="headline" style="z-index:2; ...">MAKE IT IN HYPERFRAMES</h1>


<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 + alpha)	デフォルトです。コンポジションでは <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; ...">MAKE IT IN 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 つあります。

1. 切り抜き動画をタイミング属性のない <div> で囲み、動画要素ではなくラッパーの不透明度をアニメーションさせます。フレームワークはアクティブなクリップ（data-start／data-duration を持つ要素）の不透明度を強制的に 1 にするため、動画の不透明度を直接アニメーションさせると、気づかないうちに上書きされます。ラッパーには data-* 属性がないため、CSS／GSAP で制御できます。
2. 両方の動画で 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 → Transcribe → キャプション

録音済みのナレーションがない場合は、音声を生成して文字起こしすることで、キャプション用の単語単位のタイムスタンプを取得できます。

npx hyperframes tts script.txt --voice af_heart --output narration.wav
npx hyperframes transcribe narration.wav   # → transcript.json

Whisper は生成された音声から正確な単語の境界を抽出するため、手作業で調整しなくても、キャプションのタイミングが音声の進行に合います。