nexu-io/html-video — 優良食堂詳しい解説

01 / 概要

何をするものか一文で言うと

ひとことでHTMLをビデオに変換します。ローカルマシンで、エージェントと一緒に、1つのコマンドでMP4を生成します。

html-videoは、HTMLとCSSとデータを実際のMP4動画に変換するメタレイヤーです。Claude CodeやCursorなど複数のコーディングエージェントから呼び出され、Hyperframes・Remotionなど差し替え可能なレンダリングエンジンでローカルPC上に動画を書き出します。21種のテンプレートとAIサウンドトラック機能を備え、Apache-2.0ライセンスで従量課金なしという設計です。

02 / 構造

どう動くのか中核のしくみ

読み方動きの流れを図と一緒にほどきました。

中核は`render(input, ctx)`という単一のアダプタ契約です。エンジンごとの実装差はpackages/adapter-hyperframesやpackages/adapter-remotionの内部に閉じ込められています。既定エンジンのHyperframesアダプタは、Playwrightでheadless Chromiumを起動しページを録画、webmを生成してからffmpegでMP4へ変換します。フォント読み込み待ちの間にCSSアニメーションが進んでしまう問題を避けるため、goto直後に全アニメーションを一旦フリーズする処理が入っています。Remotionアダプタは既存のHTML/CSS/GSAP製フレームをRemotionのタイムラインに橋渡しする段階(Phase 1)で、外部stylesheetの`<link>`がsrcdocのペイントをブロックして画面が真っ黒になる不具合を`neutralizeBlockingResources`で回避しています。CLI(packages/cli)がエージェント検出・プロジェクト管理・スタジオサーバーを担い、テンプレートは`template.html-video.yaml`とSKILL.mdで自己記述される構成です。

03 / 体験

入れるとこんな体験になりますギット飯が実際にたどった順序

所要ギット飯が実際に導入・実行しながらたどった順序です。

STEP 01
`pnpm install`を実行すると、PlaywrightがChromiumバイナリを追加ダウンロードするため初回は数分かかり、ディスク容量も消費します。
STEP 02
`html-video doctor`相当のコマンド(packages/cli/src/commands/doctor.ts)を叩くと、ffmpegやレンダリングエンジンの有無など環境チェック結果が表示されます。
STEP 03
`list-engines`コマンドでHyperframesやRemotionなど登録済みエンジンとその対応フォーマット・最大解像度が一覧で見えます。
STEP 04
`templates`コマンドを叩くと21種のテンプレート名とジャンル(データ可視化・タイトルカード・アウトロなど)がリストされます。
STEP 05
projectコマンドでプロジェクトを作り、テンプレートのsource/index.htmlに自分のコンテンツを流し込むと、レンダリング進捗ログ(preparing→launching browser→…)が段階的に出ます。
STEP 06
studio-server(packages/cli/src/studio-server.ts)を起動すると、ブラウザ上でテンプレートギャラリーとプレビューを操作できるローカルUIが立ち上がります。

04 / 成果物

何が手に入るのか導入後に手元に残るもの

手元には実際に再生できるMP4ファイルが残ります。テンプレートごとのpreview.pngやtemplate.html-video.yamlのメタデータも参照でき、必要に応じて同じ入力をHyperframesとRemotionで見比べることも設計上は可能です。

05 / 注意

ここは先に知っておいてください先に知っておくとよいこと

正直なところ誰にでも合うとは言いにくいところです。

RemotionアダプタはpeerDependenciesがすべてoptionalな設計で、現時点ではPhase 1(既存HTML/GSAPフレームのブリッジ)止まりとREADMEにも明記されています。

Hyperframes本体パッケージはpeerDependenciesMetaでoptional扱いで、実際はChromiumが素のHTMLをそのまま実行しているため、upstreamのHyperframes動作を完全に再現している保証はありません。

フォント読み込み待ちやアニメーションのフリーズ処理、外部stylesheetのブロッキング回避など、ヘッドレスChromium特有の細かい不具合対策がコード内に複数残っており、テンプレートやエンジンの組み合わせによっては同種の未知の描画問題に当たる可能性があります。

Playwright・ffmpeg・場合によってはRemotionのbundler一式など、依存のインストール量が相応に多く、初回セットアップの負荷は軽くありません。

06 / 結論

ギット飯の結論食べてみる価値のある一膳か

ギット飯の最終判断優良食堂

HTML/CSSでデザインを組める人が、複数のコーディングエージェントとローカル環境だけで動画量産パイプラインを持ちたい場合に向いています。アダプタ契約・録画からMP4変換までの処理・テスト(neutralize-resources.test.mjsなど)がソース上で具体的に確認でき、Hyperframesエンジンが唯一の「実装済み」でRemotionは橋渡し段階、という位置づけもREADMEとpackage.jsonの記述が一致しています。この整合性から、インストールせずとも記載内容は信頼して判断材料にできると考えられます。