Communitygithub.com

LingoJack/jcli

HyperFrames HTML を使用したビデオ合成、アニメーション、タイトルカード、オーバーレイ、キャプション、ナレーション、音声反応型ビジュアル、シーントランジションを作成します。HTMLベースの動画コンテンツ構築、音声に同期したキャプション/字幕生成、テキスト読み上げナレーション、音楽駆動型アニメーション、アニメーションテキストハイライト、シーン切り替えなどをカバーします。

jcli とは?

**LingoJack/jcli** は、HyperFrames フレームワークを利用して HTML ベースの動画コンテンツを包括的に作成・編集するためのスキルです。このスキルは、タイトルカード、オーバーレイ、キャプション、ナレーション、音声に反応するビジュアル、シーントランジションなど、動画制作に必要なあらゆる要素を HTML、CSS、GSAP アニメーションで構成する方法を定義します。特に、デザインシステム (design.md) に基づくブランドカラーやフォントの適用、プロンプト拡張による意図の明確化、レイアウト優先のアニメーション設計(「レイアウト→アニメーション」の順序)を重視します。また、変数パラメータ化により、1つの合成テンプレートから異なるコンテンツ(タイトル、価格、テーマ色など)を動的にレンダリングできます。このスキルは、Claude Code、Cursor、Codex、Windsurf、GitHub Copilot、Aider などの主要な AI エージェントで使用可能で、CLI コマンド(init、preview、render)やメディア前処理コマンド(tts、transcribe)はそれぞれ別のスキル (hyperframes-cli、hyperframes-media) に委譲します。

対応~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/LingoJack/jcli/tree/HEAD/.jcli/skills/hyperframes

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

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

ドキュメント

HyperFrames

HTML が動画の唯一の情報源です。コンポジションは、タイミング用の data-* 属性、アニメーション用の GSAP タイムライン、および外観用の CSS を備えた HTML ファイルです。フレームワークがクリップの可視性、メディア再生、およびタイムライン同期を処理します。

アプローチ

発見(探索的なリクエストのみ)

「製品紹介動画を作って」「ブランド用に何か作って」など、ユーザーが方向性を決めていない自由なリクエストに対しては、色を選ぶ前に意図を理解します。

  • 視聴者 – 誰が見るのか? 開発者? 経営陣? 一般消費者?
  • プラットフォーム – どこで再生されるのか? ソーシャルメディア(15秒)、ウェブサイトのヒーロー、製品デモ、社内?
  • 優先事項 – 最も重要なのは何か? モーションの品質? コンテンツの正確性? ブランドの忠実性? 速度?
  • バリエーション – ユーザーは複数のオプションを望んでいるのか、それとも最高の1案だけか?

「タイトルカードを追加して」「シーン3のタイミングを修正して」などの具体的なリクエストに対しては、発見フェーズをスキップします。

探索的なリクエストでは、単なる色の変更ではなく、テンポ、エネルギー、または構造的アプローチが異なる、意味のある2~3のバリエーションを提供することを検討します。1つは安全/予想通り、もう1つは野心的なものを。必須ではありません。適切な場合に使えるツールです。

ステップ1:デザインシステム

プロジェクトに design.md または DESIGN.md が存在する場合は、最初にそれを読みます(大文字小文字の両方を確認してください。Linuxでは別のファイルです)。ブランドカラー、フォント、制約の情報源です。正確な値を使用し、色を発明したりフォントを代用したりしないでください。どのような形式でも機能します(YAML frontmatter、散文、テーブル – 値を抽出するだけです)。

ローカルに見つからないフォント(fonts/ ディレクトリに .woff2 ファイルがない、組み込みフォントではない)が指定されている場合は、HTML を書く前にユーザーに警告します:「design.md に [フォント名] が指定されていますが、フォントファイルが見つかりません。.woff2 ファイルを fonts/ に追加するか、最も近い組み込みの代替フォントにフォールバックします。」

design.md が存在しない場合は、ユーザーに選択肢を提供します。

  1. ユーザーがスタイルや雰囲気を指定した場合 → visual-styles.md を読み、8つの名前付きプリセットから最も近いものを選びます。
  2. オプションを視覚的に閲覧したい場合 → デザインピッカーを実行します:references/design-picker.md を読み、完全なワークフローを確認します。これは視覚的なピッカーページを提供します。ユーザーはブラウザで雰囲気、パレット、タイポグラフィ、モーションを設定し、生成された design.md をコピーして会話に貼り付けます。
  3. スキップして高速に進みたい場合 → 雰囲気、ライト/ダーク、ブランドカラー/フォントを尋ねます。次に、house-style.md からパレットを選びます。

design.md はブランドを定義します。ビデオ構成ルールを定義するものではありません。 それらは references/video-composition.md と house-style.md から来ます。ブランドカラーは、Web UI の不透明度ではなく、ビデオに適したスケールで使用します。

ステップ2:プロンプト拡張

常にすべてのコンポジションに対して実行します(単一シーンの作品と些細な編集を除く)。このステップは、ユーザーの意図を design.md と house-style.md に基づいて具体化し、すべての下流エージェントが同じように読む一貫した中間表現を生成します。

完全なプロセスと出力形式については、references/prompt-expansion.md を参照してください。

ステップ3:計画

HTML を書く前に、高レベルで考えます。

  1. 何を – 視聴者は何を体験すべきか? ストーリーの流れ、重要な瞬間、感情的なビートを特定します。
  2. 構造 – いくつのコンポジション? サブコンポジションかインラインか? どのトラックが何を運ぶか(ビデオ、オーディオ、オーバーレイ、キャプション)。
  3. リズム – 実装前にシーンのリズムを宣言します。どのシーンがクイックヒットか、ホールドか、シェーダーはどこに配置するか、エネルギーがどこでピークになるか。パターンに名前を付けます:fast-fast-SLOW-fast-SHADER-hold。リズムテンプレートについては references/beat-direction.md を参照。
  4. タイミング – どのクリップが長さを決めるか、トランジションはどこに配置するか、ペースはどうか。
  5. レイアウト – まず最終状態を構築します。以下の「レイアウトをアニメーションより先に」を参照。
  6. アニメート – 次に、以下のルールを使用してモーションを追加します。

依頼されたものを作成します。 「タイトルカード」のリクエストは、「タイトルカード + 3つの追加シーン + 環境音楽 + キャプション」のリクエストではありません。すべてのシーン、すべての要素、すべてのトゥイーンは、その存在価値を証明する必要があります。追加のシーンや要素が作品を真に向上させる場合は、提案はしますが、追加はしません。

小さな編集(色の修正、タイミングの調整、1つの要素の追加)の場合は、ルールに直接スキップします。

レイアウトをアニメーションより先に

すべての要素を、最も見える瞬間(完全に入力され、正しく配置され、まだ終了していないフレーム)に配置します。これを最初に静的な HTML+CSS として記述します。まだ GSAP は使用しません。

なぜこれが重要なのか: 要素をアニメーションの開始状態(画面外、スケール0、不透明度0)に配置し、そこから本来あるべき位置にトゥイーンすると、最終的なレイアウトを推測していることになります。重なりはビデオがレンダリングされるまで見えません。最初に最終状態を構築することで、モーションを追加する前にレイアウトの問題を確認して修正できます。

プロセス

  1. 各シーンのヒーローフレームを特定します – 最も多くの要素が同時に表示される瞬間。これが構築するレイアウトです。
  2. そのフレームの静的な CSS を記述します。.scene-content コンテナは、width: 100%; height: 100%; padding: Npx; と display: flex; flex-direction: column; gap: Npx; box-sizing: border-box を使用して、シーン全体を埋める必要があります。パディングを使用してコンテンツを内側に押し込みます – コンテンツコンテナに position: absolute; top: Npx を使用しないでください。絶対配置されたコンテンツコンテナは、コンテンツが残りのスペースよりも高い場合にオーバーフローします。position: absolute は装飾要素のみに予約します。
  3. gsap.from() でエントランスを追加 – 画面外/非表示から CSS 位置へアニメーションします。CSS 位置が基本 truth であり、トゥイーンはそこに到達するまでの過程を記述します。(data-composition-src を介してロードされたサブコンポジションでは、gsap.fromTo() を優先します – references/motion-principles.md の負荷分散 GSAP ルールを参照)。
  4. gsap.to() でイグジットを追加 – CSS 位置から画面外/非表示へアニメーションします。

例

/* scene-content がシーンを埋め、パディングがコンテンツを配置 */
.scene-content {
  display: flex;
  flex-direction: column;
  justify-content: center;
  width: 100%;
  height: 100%;
  padding: 120px 160px;
  gap: 24px;
  box-sizing: border-box;
}
.title {
  font-size: 120px;
}
.subtitle {
  font-size: 42px;
}
/* コンテナは任意のシーンサイズ(1920x1080、1080x1920など)に対応。
   パディングがコンテンツを配置。Flex + gap が間隔を処理。 */

誤り – ハードコードされた寸法と絶対配置:

.scene-content {
  position: absolute;
  top: 200px;
  left: 160px;
  width: 1920px;
  height: 1080px;
  display: flex; /* ... */
}
// ステップ3: それらの位置へアニメーション
 tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
 tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
 tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);

// ステップ4: それらの位置からアニメーション
 tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
 tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
 tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);

要素が時間を共有する場合

要素 A が同じエリアで要素 B が入る前に終了する場合、両方ともそれぞれのヒーローフレームに対して正しい CSS 位置を持つ必要があります。タイムラインの順序により、それらが視覚的に共存することはありません。ただし、レイアウトステップをスキップすると、タイミングエラーにより偶発的に重なるケースを見逃します。

意図的な重なりとしてカウントされるもの

レイヤー効果(テキストの背後にあるグロー、シャドウ要素、背景パターン)と z スタックデザイン(カードスタック、深度レイヤー)は意図的なものです。レイアウトステップは、意図しない重なり(2つの見出しが互いに重なる、統計がラベルを覆う、コンテンツがフレームからはみ出す)を捕捉することに関するものです。

データ属性

すべてのクリップ

属性必須値
idはい一意の識別子
data-startはい秒数またはクリップ ID 参照 ("el-1"、"intro + 2")
data-durationimg/div/composition は必須秒数。ビデオ/オーディオはメディア長がデフォルト。
data-track-indexはい整数。同じトラックのクリップは重なりません。
data-media-startいいえソースへのトリムオフセット(秒)
data-volumeいいえ0-1(デフォルト 1)

data-track-index は視覚的なレイヤリングに影響しません – CSS z-index を使用します。

コンポジションクリップ

属性必須値
data-composition-idはい一意のコンポジション ID
data-startはい開始時間(ルートコンポジション:"0" を使用)
data-durationはいGSAP タイムラインの長さよりも優先
data-width / data-heightはいピクセル寸法(1920x1080または1080x1920)
data-composition-srcいいえ外部 HTML ファイルへのパス
data-variable-valuesいいえサブコンポジションホスト上のインスタンスごとの変数オーバーライドの JSON オブジェクト

ルートの <html> 要素上:

属性必須値
data-composition-variablesいいえ宣言された変数の JSON 配列(id/type/label/default) – Studio 編集 UI を駆動し、getVariables() にデフォルトを提供

コンポジション構造

data-composition-src を介してロードされるサブコンポジションは、<template> ラッパーを使用します。スタンドアロンコンポジション(メインの index.html)は <template> を使用しません – data-composition-id div を直接 <body> 内に配置します。スタンドアロンファイルで <template> を使用すると、すべてのコンテンツがブラウザから非表示になり、レンダリングが壊れます。

サブコンポジション構造:

<template id="my-comp-template">
  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
    <!-- content -->
    <style>
      [data-composition-id="my-comp"] {
        /* scoped styles */
      }
    </style>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
    <script>
      window.__timelines = window.__timelines || {};
      const tl = gsap.timeline({ paused: true });
      // tweens...
      window.__timelines["my-comp"] = tl;
    </script>
  </div>
</template>

ルートでの読み込み:<div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>

変数(パラメータ化されたコンポジション)

同じコンポジションを、ソース HTML を編集せずに、異なるコンテンツ(タイトル、テーマ色、価格、キャプション)でレンダリングします。

3ステップのパターン:

  1. 宣言:コンポジションの <html> ルートで data-composition-variables を使用して変数を宣言します。各エントリには id、type(string、number、color、boolean、enumのいずれか)、label、default が必要です。Enum エントリには options: [{value, label}, ...] も必要です。
  2. 読み取り:コンポジションのスクリプト内で window.__hyperframes.getVariables() を使用して解決された値を読み取ります。宣言されたデフォルト + インスタンスごとのオーバーライド + CLI オーバーライドのマージ結果を返します。
  3. オーバーライド:レンダリング時に npx hyperframes render --variables '{...}'(トップレベル)またはホスト要素の data-variable-values='{...}'(サブコンポジションのインスタンスごと)を使用します。
<!doctype html>
<html
  data-composition-variables='[
  {"id":"title","type":"string","label":"Title","default":"Hello"},
  {"id":"theme","type":"enum","label":"Theme","default":"light","options":[
    {"value":"light","label":"Light"},
    {"value":"dark","label":"Dark"}
  ]}
]'
>
  <body>
    <div data-composition-id="root" data-width="1920" data-height="1080">
      <h1 id="hero" class="clip" data-start="0" data-duration="3"></h1>
      <script>
        const { title, theme } = window.__hyperframes.getVariables();
        document.getElementById("hero").textContent = title;
        document.body.dataset.theme = theme;
      </script>
    </div>
  </body>
</html>
# 開発プレビューは宣言されたデフォルトを使用
npx hyperframes preview

# オーバーライドを使用してレンダリング
npx hyperframes render --variables '{"title":"Q4 Report","theme":"dark"}' --output q4.mp4

# または JSON ファイルから
npx hyperframes render --variables-file ./vars.json

サブコンポジションのインスタンスごとの値: 同じ getVariables() が data-composition-src を介してロードされたサブコンポジション内で機能します。各ホスト要素は独自の値を渡します。

<div
  data-composition-id="card-pro"
  data-composition-src="compositions/card.html"
  data-variable-values='{"title":"Pro","price":"$29"}'
></div>
<div
  data-composition-id="card-enterprise"
  data-composition-src="compositions/card.html"
  data-variable-values='{"title":"Enterprise","price":"$99"}'
></div>

コンポジションの統合

ルートの index.html は、複数のコンポジションを1つのタイムラインに編成します。ホスト要素は、兄弟クリップとのタイミング関係を記述します。

サブコンポジションの連鎖

コンポジションは他のコンポジションをネストできます。サブコンポジション内のホスト要素は、その親コンポジションのタイムラインに参加します。getVariables() はネストされたコンポジションでも機能し、各レベルは独自の data-composition-variables 宣言と data-variable-values オーバーライドを持ちます。

トランジション

すべてのトランジションはクリップの data-start / data-duration とは別であり、GSAP によって制御されます。data-transition 属性はクリップに適用されます。

値効果
crossfade現在のクリップの exit オーバーラップトゥイーンと次のクリップの entrance オーバーラップトゥイーン
wipe-left, wipe-right, wipe-up, wipe-downウェイプ(次のクリップが前のクリップを覆う)
reveal前のクリップがめくれて次のクリップを表示
shader-*カスタム GLSL シェーダートランジション(shader-wave、shader-blur) – セットアップについては references/shaders.md を参照

ルート index.html での使用:

<div id="scene-1" data-start="0" data-duration="5" data-track-index="1">...</div>
<div id="scene-2" data-start="5" data-duration="5" data-transition="crossfade" data-track-index="1">...</div>

必要な場合を除き、のクリップに data-transition を設定する必要はありません。デフォルトでは遷移はありません。

クリップのモーション

エントランス

要素を CSS で配置された最終位置に残し、gsap.from() を使用してアニメーションでそこに到達します。

// 良い:要素は CSS で配置され、gsap.from がエントランスを定義
tl.from(".title", { y: 80, opacity: 0, duration: 0.8, ease: "power3.out" }, 0);

イグジット

gsap.to() を使用して非表示または画面外へアニメーションします。

// 良い:gsap.to がイグジット方法を定義。要素は CSS によって配置されます。
tl.to(".title", { y: -80, opacity: 0, duration: 0.5, ease: "power2.in" }, 3);

持続的な可視性

一部の要素(背景、終了しないオーバーレイ)は、画面に残る必要があります。シーン内にいる間はイグジットを適用しないでください。

ロゴ連続性

ブランドロゴは、(最長クリップ)内で持続し、1つのみが画面上にあるようにする必要があります。ロゴを異なる位置に再アニメーションしないでください – ルートコンポジションで1つのロゴ要素を管理します。

モーション設計の原則

完全なモーション設計の原則、高度な GSAP パターン、GSAP フリップ、スクロールトリガー、負荷分散されたアニメーションパターンについては、references/motion-principles.md を参照してください。

スキーマ

トップレベル(index.html)

{
  "type": "composition",
  "files": ["index.html", ...],
  "compositionId": "root",
  "width": 1920,
  "height": 1080
}

スクリプト内手順

{
  "steps": [
    {"step": 1, "action": "read design.md"},
    {"step": 2, "action": "prompt expansion"},
    {"step": 3, "action": "plan composition"},
    {"step": 4, "action": "write HTML"}
  ]
}

2つのフェーズ

フェーズ焦点出力
計画コンセプト、構造、タイミングマークダウン概要
実装HTML+CSS+JSファイル

リファレンス

関連スキル