timeqsz/motion-atoms

Motion Atoms

Agent に説明からアニメーションを作成させ、参考動画から再利用可能な動作と組み合わせを分解させます。Agent は用途と編集を観察・理解し、パッケージ内のアトム、バリデーター、レンダリングツールが実行を担当します。ユーザーは事前にエフェクトを選んだり、アトム名を覚える必要はありません。配布パッケージには 53 個の 2D アトム（8 ファミリー）が含まれており、ウェブサイトと同じ実装を使用しています。相対パスでパッケージ内のリソースにアクセスし、ウェブサイトのオンライン状態、ソースリポジトリ、npm インストールに依存しません。初回インストールは インストールと環境 を参照してください。manifest.json には、このパッケージのバージョン、ファイル、チェックサムが記録されています。

タスクに応じて読む：一度に全目次を読み込まない

タスク	最初に読む	次に参照する
説明から生成、または既存エフェクトの修正を続ける	生成と修正のループ	意図マッピング
参考動画の分解、または特定動作の実現方法の分析	動画アニメーション分解	観察結果に基づいてアトムリストと使用方法を確認。breakdown で元動画を切り出し。アニメーションタイプごとにトラックを分け、トラック間は明確に区切り、同じトラック内の複数のテキストなし動作ブロックは個別に強調表示。
2D テキスト、グラフィック、プロパティアニメーション	2D カタログ（必要なファミリーだけをフィルタ）	atoms/<ID>.md と同名の .mjs。入出力の取り決め
2D 素材ファイルのエクスポート	シーン編集	scripts/motion.mjs。正確なフィールドは MotionSpec を参照。
カクツキ、オフセット、隠れ、読み取り不能の修正	時間と画面のチェック	実際の問題を修正し、影響を受けるフレームと再生を再チェック。

制作時は、まずホスト、画角、フレームレート、ターゲット対象、納品物を明確にします。分解時は、視聴可能な動画、範囲、分析目的を確認し、元のタイムコードを保持します。ユーザーの既存の決定を尊重します。アニメーション名、パラメーター、動作はパッケージ内の説明を基準とします。

ユーザーが要求する結果を納品し、単に候補アトムを推奨するだけに留めません。既存結果の修正は、元のファイルを保持し、実際の変更内容を確認します。2D の deliver は、独立したプレビュー、編集可能なシーン、リソース、チェックレポートをパッケージ化できます。レポートでは、数値検証を視覚的な承認にすり替えてはいけません。実装能力を超える場合は、そのギャップを説明した上で、呼び出し元のホスト実装を使用し、類似したエフェクトを要件を満たしたかのように装わないでください。

制作の核心

• 用途を先に決め、動作を後で選ぶ。 明確な製品、イベント、状態の変化を組み合わせて示します。各アトムはその役割を説明できなければなりません。実際の PV の主体、リズム、つなぎを参考にし、実際に視聴して方法を抽出します。画面をそのままコピーせず、無関係なアイコン、偽のコントロール、装飾的な動きで数を稼がないでください。ウェブサイトの短編は約 5 秒、2～3 種類のアトムです。これは全ての動画の長さとアトム数の制限ではありません。
• 変化を編集し、ポスターにエフェクトを飾らない。 まず主従を整理し、入場、変化、落ち着き、退場を明確に記述します。動作間には因果関係または視覚的な繋がりがあり、重要な変化は一目でわかるようにします。各グループは主体に適した出入り方法を採用し、テキストが止まった後は十分な読む時間を確保します。不要な端の小さな文字は削除します。
• 動きは完全かつ連続的でなければならない。 中途で途切れさせず、一律に逆再生しないでください。カットは、位置、方向、速度、明るさを考慮します。有限動作と連続ループはそれぞれ設計し、ループは実際の最初と最後をチェックします。補間や公称フレームレートの引き上げで停止を隠してはいけません。
• 主体は全体として扱う。 画像、ロゴタイプ、エンブレムは共通の正しい座標とピボットを使用します。実際のマスクと描画順序が隠れを決定します。入退場ではテキストグループ全体と詳細をチェックし、ベースプレートだけを動かしてはいけません。実際の画角と表示サイズで位置合わせ、鮮明さ、クリッピングを確認します。
• 素材は動作に奉仕する。 用途に合致し、ライセンスが追跡可能なフリー商用素材を選択し、ライセンスに従ってクレジット表記とソースファイルの配布を行います。同じ素材を異なるケースに使い回さないでください。素材の読み込みサイズを制御します。ウェブサイトとプロモーションビデオで同じシーンを参照する場合、素材と動きを同期させます。
• 実際の出力で検証する。 Web ページでは実際の再生とターゲットサイズを確認します。動画制作時はまず絵コンテを書き、フレームごとにレンダリング、合成し、エンコード後の入場／定常／退場／継ぎ目をサンプリングチェックし、完全に再生します。確認していない部分についてはチェック通過を主張しません。再生可能な結果とチェック範囲を一緒に納品します。具体的な技術チェックは 時間と画面のチェック を参照してください。

2D：ホストレンダラーへの埋め込み

必要な .mjs だけをコピーします。描画が必要な場合のみ atoms/draw.mjs をコピーします。アトムは明示的なフレームで評価され、プレーヤーを内蔵しません。ホストが描画順序、座標、時間を管理します。8 つのファミリーはそれぞれ一つの質問に答えます：プロパティ（何を変えるか）、タイミング（どう変わるか）、ループ（動き続ける）、編集（誰が先か）、トランジション（出現・消滅）、テキスト（文字の動き）、テクスチャ（上に重ねる）、ジェネレート（無から生まれる）。

import move from './atoms/prop.move.mjs';
import spring from './atoms/timing.spring.mjs';
import breathe from './atoms/loop.breathe.mjs';
import { drawAtom } from './atoms/draw.mjs';

const subject = { points: [[-50,-50],[50,-50],[50,50],[-50,50]], closed: true, fill: true };
const curve = (t) => spring({ frame: t, durationFrames: 1 }).value;   // タイミング：カーブのみ提供
function renderFrame(ctx, frame) {
  const shape = move({ frame, durationFrames: 30, subject, params: { fromPx: -200, toPx: 0 }, ease: curve });
  const breath = breathe({ frame, startFrame: 30, durationFrames: 90 });   // ループ：上に重ねる
  drawAtom(ctx, { ...shape, scale: shape.scale * breath.scale }, { x: 320, y: 200, color: '#f4f1ea' });
}

• 独立関数の params は変更項目のみ渡せます。MotionSpec clips は全パラメーターを完全に記述しなければなりません。 これらの二つの取り決めを混在させないでください。
• 同時に組み合わせる場合、まず役割と writes を確認します。位置と角度は加算、スケールと透明度と伸縮は乗算、フィルターは順次連結、編集アトムは copies を返し、ホストはコピーのオフセットと遅延に従ってそれぞれ描画します。一つの主体の輪郭出力を、オブジェクト展開で二つの layers を重ねて実現してはいけません。
• MotionSpec で同じプロパティのプロパティアニメーションを記述する場合、時間が重なってはいけません。前後で引き継ぐことができます。前段の終端値と後段の開始値は接続されなければなりません。タイミング、ループ、編集、テクスチャは重畳されます。ファイルエクスポートは、ウェブサイトのループ再生戦略を自動的に引き継ぎません。
• グラフィック座標は主体の原点を基準とします。テキスト位置は最初の行の左端ベースラインです。デバイスフォント（system、mono）は直接使用でき、正確なクロスマシングリフが必要な場合のみ固定フォントアセットが必要です。
• 実行可能な最小限の例：atoms/example.html（配列 × オフセット × 移動 × スプリング）。

2D：素材ファイルの納品

以下のコマンドは、解凍後の motion-atoms/ 内で実行します。出力は自分の作業ディレクトリに書き込みます。エクスポート前に、必要に応じてローカルのブラウザ/FFmpeg を検出しますが、基本的な情報検索時にこれらのツールを要求してはいけません。

node scripts/motion.mjs describe transition.slices
node scripts/motion.mjs scaffold transition.slices --out work/slices.scene.json --width 1920 --height 1080 --fps 30 --duration 60
node scripts/motion.mjs validate work/slices.scene.json
node scripts/motion.mjs frames work/slices.scene.json --out work/check --frames 0,20,40,59 --transparent
node scripts/motion.mjs render work/slices.scene.json --out work/slices.mov --transparent

複数アトムのシーンは直接使用できます。例：

node scripts/motion.mjs preview assets/examples/showcase.scene.json --out work/showcase.html
node scripts/motion.mjs breakdown assets/examples/showcase.scene.json --out work/showcase-breakdown.gif --title "オープニング · アトム分解"

preview は HTML であり、動画ではありません。render は MP4（不透明）、MOV/WebM（透明可）を出力します。frames は PNG を出力します。breakdown は画面下部にアトムのタイムラインを追加し、GIF、MP4、または WebM を出力します。入力がシーンファイルの場合は自身が作成したアニメーションを説明し、入力が分解ファイルの場合は参考動画のクリップを切り出して分解します（動画アニメーション分解 を参照）。verified: true はサイズ、フレーム数、長さなどのファイルチェックのみを証明し、構図、リズム、または隠れの正しさを証明しません。納品前に 画面チェック に従ってエンコード結果と実際の再生を確認し、実際のチェック範囲を説明します。ファイルパス、シーンパス、フレームレート、長さ、透明度チャンネルを返します。これらの素材にオーディオトラックはありません。

能力の境界

• 動画の分解は Agent がホストの再生、フレーム抽出、音声分析ツールを使用して観察・完了します。パッケージ内の CLI に動画認識コマンドはなく、breakdown は Agent が作成した分解ファイルに従って元動画のクリップを切り出し、下部にアトムのタイムラインを描画します。このパッケージの範囲を超える動作も分析できますが、直接使用可能、部分的に近似、ホストで別途実装を区別しなければなりません。完成動画から元のプロジェクトファイル、プラグイン、正確なパラメーターを断言してはいけません。切り出した元動画は分析のみに使用し、素材として再配布してはいけません。
• 2D シーンは text / path ノードのみで、画像、動画、オーディオ、親子グループ、z-index フィールドはありません。プロパティ、カーブ、コピー出力はホストが画像や動画に適用できます。ジオメリアトムは折れ線グラフィックのみを処理します。画像と動画の合成はホストが担当します。
• トランジションとテクスチャはテキストとグラフィックに使用できます。テキストのバウンディングボックスは、レンダリング時の実際の字形で測定されます。ループとビートはオーディオを読み取りません。
• デフォルトの例と scaffold はシステムフォントを使用し、パッケージ内にフォントライブラリは含まれません。クロスマシンでの一貫性が必要な場合、ホストがライセンスを得た固定フォントを提供し、パスとハッシュを宣言して字形をチェックします。
• 現在、3D アトムはありません。3D シーンはホストが独自に実装します。
• 映像全体の制作は、呼び出し元の絵コンテ、音声、編集、納品フローを継続して使用します。この Skill は特定のホスト、視覚スタイル、統一トランジションを強制しません。

参考と謝辞

本パッケージが属する MotionFlux プロジェクトの初期アニメーションインデックス構想は、Kazuki Akamine（赤嶺一希）の Motion Periodic Table を参考にしています。基礎的なアニメーションの整理と表示に関するインスピレーションに感謝します。MotionFlux は独立したプロジェクトです。