framevideo-media

FrameVideo メディアの前処理

使用する場面

次の用途でこのスキルを使用します。

• テキスト読み上げ（TTS） — テキストからナレーション音声を生成します（ローカルの Kokoro）
• BGM — Chanjing プラットフォームから楽曲をダウンロードします
• 効果音（SFX） — 短い音声キュー（クリック音、ヒューッという音、打撃音）をダウンロードします
• 文字起こし — 音声／動画をタイムスタンプ付きの字幕に変換します（Whisper）
• 背景の削除 — 動画／画像から透過オーバーレイを作成します（u2net）
• 音声ワークフロー — コマンドを連続して実行します（TTS → 文字起こし → 字幕）

使用しない場面

次の用途にはこのスキルを使用しないでください。

• デジタルヒューマン動画 — chanjing-digital-human を使用します
• Chanjing OAuth のセットアップ — chanjing-auth を使用します
• SSML による発音制御 — framevideo-voiceover-ssml を使用します
• コンポジションの HTML — framevideo を使用します
• コンポジション内での音声再生 — framevideo を使用します（このスキルはアセットの生成のみを行います）

---

クイックスタート

3 ステップでナレーションと字幕を生成します。

# 1. Generate TTS audio
npx framevideo tts "Hello from FrameVideo" --output assets/narration.wav

# 2. Transcribe to get timestamps
npx framevideo transcribe assets/narration.wav --output assets/transcript.json

# 3. Reference in composition
# In index.html:
# <audio data-src="assets/narration.wav" data-start="0" data-track-index="10"></audio>

BGM の場合：

# 1. Authenticate (one-time)
npx framevideo auth login

# 2. Browse music
npx framevideo chanjing music list --category <id> --compact

# 3. Download
npx framevideo chanjing music download --id <music-id> --output assets/music/bg.mp3

---

BGM と効果音の使い分け

Chanjing の 2 つの音声機能は、用途に応じて使い分けてください。

• BGM：chanjing music。長い楽曲やサビには assets/music/ を使用します。data-volume="0.12" が既定値で、data-track-index="20" も既定値です。
• 効果音（SFX）：chanjing sound-effect または chanjing sfx。短いイベント音には assets/sfx/ を使用します。data-volume="0.8" が既定値で、data-track-index="30" も既定値です。
• どちらも参照する前に、プロジェクトのローカルアセットにダウンロードする必要があります。コンポジションの HTML では、Chanjing／OSS のリモート URL を直接使用しないでください。

BGM（chanjing music）

ユーザーが Chanjing ライブラリからの BGM、サウンドトラック、またはサビの抽出を求めた場合は、Chanjing OAuth 対応のプラットフォーム音楽を使用します。このコマンドは選択した楽曲をローカルのプロジェクトアセットにダウンロードし、<audio> スニペットを出力します。コンポジションの HTML に Chanjing／OSS のリモート URL を直接記述しないでください。

npx framevideo auth status
npx framevideo chanjing music categories --json
npx framevideo chanjing music list --category <category-id> --compact
npx framevideo chanjing music download --id <music-id> --output assets/music/<name>.mp3 --volume 0.12
npx framevideo chanjing music download --id <music-id> --chorus --duration 10 --json

既定値：

• --output を省略した場合、アセットは assets/music/ にダウンロードされます。
• --output では <name> と <id> のプレースホルダーを使用できます。
• BGM の推奨音量の既定値は 0.12 です。ナレーションがない場合に限り、0.22 程度まで上げてください。
• --chorus は Chanjing のサビ抽出エンドポイントを呼び出し、返された区間をダウンロードします。

効果音（chanjing sound-effect／chanjing sfx）

ユーザーが UI のクリック音、ヒューッという音、トランジション音、衝撃音、通知音、その他の短い音声キューを求めた場合は、Chanjing OAuth 対応のプラットフォーム効果音を使用します。このコマンドは選択した効果音をローカルのプロジェクトアセットにダウンロードし、<audio> スニペットを出力します。

npx framevideo auth status
npx framevideo chanjing music categories --json     # shared audio category hints
npx framevideo chanjing sound-effect list --category <category-id> --compact
npx framevideo chanjing sound-effect download --id <effect-id> --output assets/sfx/<name>.mp3 --volume 0.8
npx framevideo chanjing sfx download --id <effect-id> --start 2.4 --json

既定値：

• --output を省略した場合、アセットは assets/sfx/ にダウンロードされます。
• --output では <name> と <id> のプレースホルダーを使用できます。
• 効果音の推奨音量の既定値は 0.8 です。音声キューと全体のミックスに応じて、0.6-1 を使用してください。
• 効果音ではサビの抽出はサポートされていません。

テキスト読み上げ（tts）

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

Chanjing 対応の音声生成リクエスト

ユーザーが Chanjing の音声生成、プラットフォーム音声、デジタルヒューマンのナレーション、または Chanjing 対応の音声アセットを求めた場合は、ローカルの Kokoro TTS を既定で使用せず、chanjing-digital-human スキルを呼び出してください。ローカルの npx framevideo tts を使用するのは、ユーザーがオフライン音声を明示的に希望する場合、または Chanjing の認証が利用できない間の仮音声を受け入れる場合に限ります。

npx framevideo tts "Text here" --voice af_nova --output narration.wav
npx framevideo tts script.txt --voice bf_emma --output narration.wav
npx framevideo 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 framevideo tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
npx framevideo 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/framevideo/tts/ にキャッシュされます）。

文字起こし（transcribe）

単語レベルのタイムスタンプを含む、正規化された transcript.json を生成します。

npx framevideo transcribe audio.mp3
npx framevideo transcribe video.mp4 --model small --language es
npx framevideo transcribe subtitles.srt          # import existing
npx framevideo transcribe subtitles.vtt
npx framevideo 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 のインポート方法については、framevideo/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 framevideo remove-background subject.mp4 -o transparent.webm  # default: VP9 alpha WebM
npx framevideo remove-background subject.mp4 -o transparent.mov   # ProRes 4444 (editing)
npx framevideo remove-background portrait.jpg -o cutout.png       # single-image cutout
npx framevideo remove-background subject.mp4 -o subject.webm \
  --background-output plate.webm                                   # both layers in one pass
npx framevideo remove-background subject.mp4 -o transparent.webm --device cpu
npx framevideo remove-background --info                           # detected providers

u2net_human_seg（MIT）を使用します。初回実行時に、重みデータ約 168 MB が ~/.cache/framevideo/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 FRAMEVIDEO</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	画像1枚の切り抜きです（静止した被写体を背景の上に重ねます）。

Chrome は VP9 のアルファをネイティブでデコードするため、.webm は他のミュート自動再生動画と同様に合成に組み込めます。<video> トラックの規約については framevideo スキルを参照してください。

品質プリセット

--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）を使用してください。
切り抜きを同じ人物の_別テイク_に重ねる	同じ被写体の映像	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 FRAMEVIDEO</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 → 文字起こし → キャプション

事前に録音されたナレーションがない場合は、生成してから文字起こしし、キャプション用の単語単位のタイムスタンプを取得します。

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

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

---

検証

アセットの前処理後に、次を実行します。

# Verify audio files
npx framevideo inspect   # Check audio levels and duration

# Test in preview
npx framevideo preview   # Verify audio plays correctly in composition

手動での確認：

1. ファイルパス — アセットが正しいディレクトリ（assets/music/、assets/sfx/ など）に保存されていること
2. 音量レベル — BGM は 0.12〜0.22、SFX は 0.6〜1.0、ナレーションはデフォルト
3. 文字起こしの精度 — transcript.json の単語境界を確認
4. 背景除去の品質 — 透明な動画を確認し、エッジにアーティファクトがないこと
5. 統合 — アセットがコンポジション HTML 内で正しく参照されていること

---

連携

このスキルは、以下で使用されるアセットを生成します。

• framevideo — コンポジション HTML 内の参照用音声／動画
• framevideo-voiceover-ssml — TTS 生成前に SSML マークアップを適用
• chanjing-digital-human — ナレーション用のローカル TTS の代替
• website-to-framevideo — ステップ 4 でこのスキルを音声生成に使用

---

クレジットと参考資料

• Kokoro TTS：https://github.com/hexgrad/kokoro
• Whisper による文字起こし：https://github.com/openai/whisper
• u2net による背景除去：https://github.com/xuebinqin/U-2-Net
• Chanjing プラットフォーム：https://www.chanjing.cc