ak:hyperframes は何をしますか?
HeyGen の hyperframes CLI をラップし、HTML ファーストでプログラム的に動画を生成します。このスキルはドキュメントとラッパーのみであり、HeyGen のソースコードをベンダリングしたり、HeyGen のエージェントスキルをコピーしたりしていません。以下のすべてのコマンドは、公開されている npm パッケージを npx で実行し、既知の正常なバージョンに固定されています。
使用するタイミング
- HTML/CSS からレンダリングされる短尺の縦型ソーシャル動画(1080×1920、9:16)。
- React コンポーネントやタイムラインエディタではなく、HTML 構成として作成されたプロダクトローンチクリップ、プロモループ、モーショングラフィックス。
data-composition-id/data-startタイミング属性を含む HTML マークアップが構成の真実の源泉となるタスク(references/composition-basics.md を参照)。
React ファーストの構成、フレーム精度の補間カーブ、Remotion のオーディオ/キャプションエコシステムには適していません。その代替として、インストール済みの remotion スキル(React ベースのプログラム動画生成)もご利用いただけます。また、純粋な FFmpeg/ImageMagick エンコードタスクにも適していません。その代替として ak-media-processing スキルをご利用ください。
前提条件
- Node.js 22+
PATHに FFmpeg がインストールされていること- オプション: リモートレンダリング用の HeyGen クラウド/ラムダ API キー(
HEYGEN_API_KEY)。ローカルレンダリングはキーなしで動作します。
レンダリング作業を開始する前に、バンドルされている検証スクリプトを実行してください:
node scripts/verify-prereqs.mjs
# または、機械可読な出力を得るには:
node scripts/verify-prereqs.mjs --json
各プラットフォームのインストール手順と固定バージョン確認の注意事項については、references/env-and-deps.md を参照してください。
固定 CLI バージョン
以下のすべての呼び出しは [email protected] に固定されています。これは 2026-08-07 時点の最新公開バージョンです(npm view hyperframes version で確認)。アップグレード時は、このファイルと references/render-workflow.md の固定バージョンを 1 箇所で更新してください。スクリプトやドキュメント内で、固定されていない npx -y hyperframes ... を実行しないでください。
ワークフロー
標準ループは init → HTML編集 → preview → lint → render です。各ステージの具体的な呼び出しの詳細は references/render-workflow.md にあります。簡略版は以下の通り:
# 1. 新しいコンポジションプロジェクトをスキャフォールド
npx -y [email protected] init my-composition --resolution portrait
# 2. 生成された HTML コンポジションを編集(data-composition-id / data-start / data-width / data-height の契約については composition-basics.md を参照)
# 3. ローカル開発サーバーでプレビュー
npx -y [email protected] preview my-composition
# 4. レンダリング前にコンポジションを lint(不正なタイミング属性をキャッチ)
npx -y [email protected] lint my-composition
# 5. MP4 にレンダリング
npx -y [email protected] render my-composition --output ./assets/videos/my-composition.mp4
render の前に必ず lint を実行してください。lint がクリーンなコンポジションは、lint をスキップして直接レンダリングする場合よりも、レンダリングステップで失敗する頻度が大幅に低くなります。
コンポジション契約
HyperFrames コンポジションは、ルート要素に data-composition-id、data-start、data-width、data-height 属性が注釈されたプレーンな HTML ファイルです。完全な属性リファレンスと縦型 1080×1920 の例については、references/composition-basics.md を参照してください。
参考資料
- references/heygen-skills.md — このラッパーが再実装せずに参照する 25 の HeyGen エージェントスキル。より深い HyperFrames 固有の専門知識(アニメーション、キーフレーム、キャプション、プロダクトローンチテンプレートなど)が必要な場合は、
npx -y [email protected] skillsでインストールしてください。 - references/composition-basics.md — HTML コンポジション属性契約の完全な縦型プリセット例。
- references/render-workflow.md —
init → edit → preview → lint → renderフローのすべての固定呼び出しを含む完全版。 - references/env-and-deps.md — プラットフォームごとの Node/FFmpeg/API キーのセットアップ。
トラブルシューティング
| 症状 | 対応 |
|---|---|
command not found: ffmpeg | node scripts/verify-prereqs.mjs を実行し、あなたのプラットフォームに正確な修正方法を確認してください。 |
npx hyperframes が不明なフラグを報告 | このファイルの固定バージョンが上流より遅れている可能性があります。固定を更新する前に、npx -y [email protected] --help を実行して現在のフラグを確認してください。 |
render が白または短い MP4 で失敗 | 最初に lint を実行してください。ほとんどのレンダリング失敗は、lint でキャッチされる不正な data-start/data-composition-id 属性が原因です。 |
| リモート/クラウドレンダリングが必要 | HEYGEN_API_KEY を references/env-and-deps.md に従って設定し、hyperframes cloud render(render フラグではなく、別のトップレベルコマンド)を使用してください。references/render-workflow.md を参照。 |
関連項目
- インストール済みの remotion スキル(
ak-remotion)— React ベースのプログラム動画生成。構成が HTML マークアップではなく、自然に React コンポーネントツリーになる場合に使用します。 - ak-html-video スキル — 別の HTML から MP4 へのラッパー(
nexu-io/html-video)。独自のテンプレート/Studio ワークフローを持ちます。タスクが HeyGen HyperFrames コンポジションである場合に限り、ak-hyperframes を使用してください。 - ak-motion-graphics スキル — リポジトリ内のすべての動画/モーションスキルと外部モーションスキルパックをルーティングします。