Communitygithub.com

shinyobjectz/reactable

HyperFrames構成向けのアセットプリプロセッシング — テキスト読み上げ音声(Kokoro)、オーディオ・ビデオ文字起こし(Whisper)、透明オーバーレイ用背景除去(u2net)。音声生成、字幕用文字起こし、映像・画像の背景除去、またはこれらの連携(TTS→文字起こし→字幕)に使用します。各コマンドは初回実行時にモデルをダウンロードします。

reactable とは?

HyperFrames Media Preprocessingは、HyperFrames構成(オーディオ・ビデオ要素を含むHTMLページ)で使用するアセットを生成する3つのCLIコマンドスイートです。`tts`コマンドは、ローカルのKokoro-82Mモデルを使用してテキストから自然な音声を生成し、APIキーを必要としません。`transcribe`コマンドは、OpenAI Whisperを利用してオーディオまたはビデオから単語レベルのタイムスタンプを含む転写JSONを生成します。`remove-background`コマンドは、u2net_human_segを使用してビデオや画像から背景を除去し、透明なWebM(VP9 + アルファ)、ProRes 4444 MOV、またはPNGカットアウトを生成します。これらのコマンドは初回実行時にモデルをダウンロードし、`~/.cache/hyperframes/`にキャッシュします。このツールは、特にAIエージェントがHyperFramesのメディアリッチなインタラクティブコンテンツ用のアセットを準備する際に役立ちます。これにより、事前に録音された音声や手動で編集されたビデオなしで、完全に自動化されたパイプラインを可能にします。

対応~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/shinyobjectz/reactable/tree/HEAD/skill/vendored/hyperframes-media

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

プレビュー

スキル README より

ドキュメント

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)は、非英語のオーディオを文字起こしする代わりに翻訳して英語に変換します。これにより元の言語が静かに破壊されます。

  1. 言語が既知で非英語の場合 → --model small --language <code>(.enサフィックスなし)
  2. 言語が既知で英語の場合 → --model small.en
  3. 言語が不明の場合 → --model small(.enなし、--languageなし)— whisperが自動検出

デフォルトモデルはsmallであり、small.enではありません。

モデルサイズ

モデルサイズ速度使用タイミング
tiny75 MB最速クイックプレビュー、パイプラインのテスト
base142 MB高速短いクリップ、明瞭なオーディオ
small466 MB中程度デフォルト — ほとんどのコンテンツ
medium1.5 GB低速重要なコンテンツ、ノイズの多いオーディオ、音楽
large-v33.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タイミング
fast30反復作業、ファイルサイズ小、色の一致が緩い
balanced18デフォルト。ほとんどの用途で視覚的に同一
best12マスター/最終納品。最大ファイルサイズ、最も厳密な一致

合成パターン — 適切なものを選択

カットアウト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つの重要なルール:

  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 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と文字起こしの両方のコマンドを認識している場合、任意のスクリプトから自動的にキャプション付きナレーションを生成できます。

関連スキル