プロジェクト仕様書 (.opm)

OpenMotion のプロジェクトファイルは、プロジェクトデータとアセットをひとまとめにしたアーカイブファイルです。

1. ファイル形式と構造

拡張子: .opm (OpenMotion Project)
実体: ZIP 形式のアーカイブ

パッケージ構造:

project.opm/
├── project.json    # プロジェクトの構成定義（メインファイル）
└── assets/         # プロジェクトで使用する外部アセット（画像、動画、音声など）

2. project.json の定義

2.1 Root Object

プロジェクトの最上位定義です。

{
  "version": "1.0.0",
  "settings": { ... },
  "assets": [ ... ],
  "easings": [ ... ],
  "timeline": { ... }
}

プロパティ	型	説明	例
`version`	`string`	プロジェクトファイル形式のバージョン。	`"1.0.0"`
`settings`	`SettingsObject`	描画・再生に関する基本設定。	(2.1.1 参照)
`assets`	`AssetObject[]`	使用する全アセットのリスト。	(2.1.2 参照)
`easings`	`EasingDefinition[]`	プロジェクト内で共有するカスタムイージング。	(2.1.3 参照)
`timeline`	`TimelineObject`	タイムラインの構造。	(2.2 参照)

2.1.1 Settings Object

"settings": {
  "fps": 60,
  "width": 1920,
  "height": 1080,
  "duration": 300
}

プロパティ	型	説明	例
`fps`	`number`	フレームレート（デフォルト: `60`）。	`60`
`width`	`number`	キャンバスの幅（ピクセル）。	`1920`
`height`	`number`	キャンバスの高さ（ピクセル）。	`1080`
`duration`	`number`	プロジェクトの総フレーム数。	`300`

2.1.2 Asset Object

{
  "id": "md5-ae52...",
  "name": "logo_animation.mp4",
  "path": "assets/ae52....mp4",
  "type": "video"
}

プロパティ	型	説明	例
`id`	`string`	アセットの一意な識別子。	`"md5-ae52..."`
`name`	`string`	元のファイル名（ユーザー表示用）。	`"logo_animation.mp4"`
`path`	`string`	パッケージ内の相対パス。	`"assets/ae52....mp4"`
`type`	`AssetType`	アセットの種類。	`"video"`

2.1.3 Easing Definition (再利用可能なイージング)

プロジェクト内で共通して使用するカスタムイージングを定義する配列です。複数のキーフレームから参照して使い回すことができます。

構造:

"easings": [
  {
    "id": "string",
    "ease": { EasingObject }
  }
]

プロパティ	型	説明
`id`	`string`	イージングの一意な識別子。タイムライン上で参照可能。
`ease`	`EasingObject`	実際のイージング構造定義 (2.5 参照)。

使用例:

{
  "id": "smooth-bounce",
  "ease": {
    "type": "bezier",
    "points": [0.68, -0.55, 0.265, 1.55]
  }
}

複数定義する場合:

"easings": [
  {
    "id": "elastic",
    "ease": { "type": "preset", "id": "easeOutElastic" }
  },
  {
    "id": "wiggle",
    "ease": {
      "type": "expression",
      "formula": "Math.sin(t * 30) * 0.5"
    }
  }
]

2.1.4 Root Object の構成例

{
  "version": "1.0.0",
  "settings": {
    "fps": 60,
    "width": 1920,
    "height": 1080,
    "duration": 600
  },
  "assets": [ ... ],
  "easings": [
    {
      "id": "re-bounce",
      "ease": { "type": "expression", "formula": "Math.abs(Math.sin(t * Math.PI))" }
    }
  ],
  "timeline": { ... }
}

2.2 Timeline Object

再生時間軸と階層構造を管理します。

プロパティ	型	説明	例
`tracks`	`TrackObject[]`	トラックの配列。	(2.2.1 参照)

2.2.1 Track Object

タイムライン上の「行」を定義します。

{
  "id": "track-v1",
  "type": "video",
  "clips": [ ... ]
}

プロパティ	型	説明	例
`id`	`string`	トラックの一意な識別子。	`"track-v1"`
`type`	`string`	トラックの属性 (`video` / `audio`)。	`"video"`
`clips`	`ClipObject[]`	配置されるクリップの配列。	(2.3 参照)

2.3 Clip Object

タイムライン上に配置された具体的な要素を定義します。

{
  "id": 1,
  "type": "Media",
  "start": 0,
  "duration": 120,
  "blendMode": "src-over",
  "properties": {
    "adjustments": [ ... ]
  }
}

プロパティ	型	説明	例
`id`	`number`	クリップの一意な数値 ID。	`1`
`type`	`ClipType`	クリップの種類。	`"Media"`
`start`	`number`	タイムライン上の開始フレーム。	`0`
`duration`	`number`	表示の長さ（フレーム数）。	`120`
`blendMode`	`BlendMode`	合成モード。	`"src-over"`
`properties`	`object`	プロパティ（変形・エフェクトなど）。	`{ ... }`

2.3.1 ClipType 一覧

タイプ	説明
`Scene`	3D空間を表現する。
`Media`	画像、動画、音声などのアセットを表示。
`Text`	テキストの描画。
`Shape`	ベクターグラフィックスを表現する。
`Adjustment`	下のレイヤーすべてに適用される調整。
`Shader`	シェーダーを用いた表現。
`Composite`	複数のクリップをまとめたコンポジション.
`Null`	制御用の透明なクリップ。

2.3.2 クリップ共通プロパティ

すべてのクリップが properties 直下に持つことができる基本パラメータです。これらはすべて AnimatedValue (2.4 参照) で定義されます。

プロパティ	型	説明	デフォルト値
`position`	`AnimatedValue[2]`	座標位置 [x, y] (px)。	`[0, 0]`
`scale`	`AnimatedValue[2]`	拡大率 [x, y] (1.0 = 100%)。	`[1.0, 1.0]`
`rotation`	`AnimatedValue`	Z軸回転 (度)。	`0`
`opacity`	`AnimatedValue`	不透明度 (0.0 - 1.0)。	`1.0`
`fps`	`AnimatedValue`	描画更新頻度。値を下げるとコマ落とし効果（ポスタリゼーション）になります。	`0.0` (制限なし)
`anchor`	`number[2]` (静的)	変形の中心点 (0.0 - 1.0)。	`[0.5, 0.5]`
`adjustments`	`object[]`	適用されるエフェクトの配列。	`[]`

2.3.3 BlendMode 一覧

サポートされている合成モードの詳細については、合成モード仕様を参照してください。

2.4 AnimatedValue Object

AnimatedValue は、単一の数値または時間経過とともに変化する値を定義するデータ構造です。OpenMotion では、キーフレームベースの「補間」と、数式ベースの「生成」を組み合わせて扱います。

指定方法	型	説明
静的 (Static)	`number`	常に一定の値を保持します。
Keyframe Object	`Keyframe Object`	`keyframes` 配列を持ち、セグメントごとに補間します。
Expression Object	`Expression Object`	時間の制限なく、数式によって値を生成し続けます。
Stack Object	`Stack Object`	複数のタイムラインや生成器を重ね合わせます。

2.4.1 Keyframe Object (キーフレームベース)

一般的な動画編集ソフトと同様の補間ロジックです。イージングは「その値に到達するまでの補間」として、セグメントの終端キーフレームに指定します。

{
  "type": "keyframe",
  "keyframes": [
    {
      "frame": 0,
      "value": 0,
      "ease": { "type": "preset", "name": "linear" }
    },
    {
      "frame": 60,
      "value": 100,
      "ease": { "type": "preset", "name": "linear" }
    }
  ]
}

プロパティ	型	説明
`type`	`string`	常に `"keyframe"`。
`keyframes`	`Keyframe[]`	キーフレームの配列。

Keyframe 構造

プロパティ	型	説明
`frame`	`number`	キーフレームを指定するフレーム番号。
`value`	`number`	その時点での値。
`ease`	`Easing`	前のキーフレームからこの値に到達するまでの補間公式 (2.5 参照)。

2.4.2 Expression Object (時間生成器)

クリップの開始からの経過時間（または絶対時間）に基づき、数式で値を算出します。セグメントの継ぎ目という概念がなく、常に計算されます。

{
  "type": "expression",
  "formula": "Math.sin(time * 2) * 50"
}

プロパティ	型	説明
`type`	`string`	常に `"expression"`。
`formula`	`string`	JavaScript 互換の数式。変数 `time`（秒）を利用可能。

2.4.3 Stack Object (多重構造)

複数の AnimatedValue をレイヤーとして持ち、それぞれが独自のタイムラインやエクスプレッションを保持できます。最終的にすべてのレイヤーの結果が合成されます。

{
  "type": "stack",
  "mode": "add",
  "layers": [
    { "weight": 1.0, "value": { "type": "keyframe", "keyframes": [...] } },
    { "weight": 0.5, "value": { "type": "expression", "formula": "..." } }
  ]
}

プロパティ	型	説明
`type`	`string`	常に `"stack"`。
`mode`	`string`	`add` (加算), `multiply` (乗算), `mix` (平均)。
`layers`	`Array`	合成するレイヤーの配列。

Layer 構造

プロパティ	型	説明
`value`	`AnimatedValue`	適用するアニメーションデータ（Static 以外）。

2.5 Easing (補間ファンクション)

Easing は、Timeline 内のキーフレーム間で、開始値( $V_1$ )から終了値( $V_2$ )への遷移（進行度）をどのように変換するかを定義します。入力 $t$ (0.0 - 1.0) に対して出力 $v$ を返す関数です。

2.5.1 preset (プリセット)

内蔵された補間関数を名前で指定します。

{
  "type": "preset",
  "id": "easeInOutQuad"
}

基本プリセット (Standard)

ID	説明
`linear`	線形補間。開始から終了まで一定の速度で変化します。
`none`	無し。次のキーフレームに到達するまで現在の値を維持し、その瞬間にパッと切り替わります（階段状）。
`step`	ステップ。区間の中央（進行度 0.5）で、次の値に瞬時に切り替わります。

外部プリセット (Easings.net)

easings.net に掲載されているすべての関数が利用可能です。

例: easeInSine, easeOutExpo, easeInOutBack, easeOutBounce など。
各関数の具体的なカーブ形状や挙動については、リンク先のサイトを参照してください。

2.5.2 power (累乗)

数学的な累乗を用いた自由度の高い補間です。

{
  "type": "power",
  "power": 2.5,
  "dir": "inOut"
}

power: 累乗の指数 ( $n$ )。1.0で linear、2.0で Quad、3.0で Cubic となります。
dir: 補間の方向。各計算式は以下の通りです（ $t$ $t$ は進行度 0.0〜1.0）。
- in: $v = t^n$ $v = t^{n}$
```
v = Math.pow(t, n);
```
- out: $v = 1 - (1-t)^n$ $v = 1 - (1 - t)^{n}$
```
v = 1 - Math.pow(1 - t, n);
```
- inOut: $v = \begin{cases} \frac{(2t)^n}{2} & (t < 0.5) \\ 1 - \frac{(2-2t)^n}{2} & (t \geq 0.5) \end{cases}$ $v = {\frac{( 2 t ) ^{n}}{2} 1 - \frac{( 2 - 2 t ) ^{n}}{2} (t < 0.5) (t \geq 0.5)$
```
v = t < 0.5 ? Math.pow(2 * t, n) / 2 : 1 - Math.pow(-2 * t + 2, n) / 2;
```
- outIn: $v = \begin{cases} \frac{1 - (1-2t)^n}{2} & (t < 0.5) \\ \frac{1 + (2t-1)^n}{2} & (t \geq 0.5) \end{cases}$ $v = {\frac{1 - ( 1 - 2 t ) ^{n}}{2} \frac{1 + ( 2 t - 1 ) ^{n}}{2} (t < 0.5) (t \geq 0.5)$
```
v =
  t < 0.5
    ? (1 - Math.pow(1 - 2 * t, n)) / 2
    : (1 + Math.pow(2 * t - 1, n)) / 2;
```

2.5.3 bezier (ベジェ)

3次ベジェ曲線を使用して、CSS cubic-bezier と同様の制御を行います。

{
  "type": "bezier",
  "points": [0.42, 0.0, 0.58, 1.0]
}

points: [x1, y1, x2, y2] の 4 つの数値。
$x$ 軸は時間（0〜1）、 $y$ 軸は進行度（0〜1、オーバーシュートにより一時的に範囲外も可）。

2.5.4 elastic (エラスティック)

振動しながら収束するエラスティックな補間です。

{
  "type": "elastic",
  "oscillation": 10.0,
  "outStrength": 2.5
}

プロパティ	型	説明
`type`	`string`	常に `"elastic"。`
`oscillation`	`number`	揺れの速さ（振動の周波数係数）。
`outStrength`	`number`	outの強さ（減衰の指数）。

$y = 1 - \cos(a \cdot x) \cdot (1-x)^p$

y = 1 - Math.cos(a * x) * Math.pow(1 - x, p);

$x$ : 進行度（0.0〜1.0）
$a$ : oscillation の値
$p$ : outStrength の値

2.5.5 custom (プロジェクト定義の参照)

Root Object で定義したイージングを参照します。参照先は 0.0〜1.0 の補間関数 として扱われます。

{
  "type": "custom",
  "id": "my-easing",
  "multiplier": 1.0
}

プロパティ	型	説明
`type`	`string`	常に `"custom"。`
`id`	`string`	参照するイージングの ID。
`multiplier`	`number`	形状のスケーリング係数（デフォルト: `1.0`）。

計算式:

$V = V_1 + (V_2 - V_1) \times f(t) \times multiplier$

注意: 開始値と終了値が同じ場合（ $V_1 = V_2$ ）、正規化が不可能なため、イージングは無視され Linear として動作します。

3. project.json の全体例

{
  "version": "1.0.0",
  "settings": {
    "fps": 60,
    "width": 1920,
    "height": 1080,
    "duration": 300
  },
  "assets": [ ... ],
  "easings": [
    {
      "id": "my-wiggle",
      "ease": {
        "type": "expression",
        "formula": "Math.sin(t * 30) * 0.5"
      }
    }
  ],
  "timeline": {
    "tracks": [
      {
        "id": "v1",
        "type": "video",
        "clips": [
          {
            "id": 1,
            "type": "Media",
            "start": 0,
            "duration": 120,
            "blendMode": "src-over",
            "properties": {
              "adjustments": [],
              "assetId": "md5-ae52...",
              "position": [
                0,
                {
                  "keyframes": [
                    { "frame": 0, "value": 0, "ease": "my-wiggle" },
                    { "frame": 60, "value": 500 }
                  ]
                }
              ],
              "scale": [1.0, 1.0],
              "rotation": 0,
              "opacity": 1.0,
              "fps": 12.0
            }
          }
        ]
      }
    ]
  }
}

1. ファイル形式と構造​

2. project.json の定義​

2.1 Root Object​

2.1.1 Settings Object​

2.1.2 Asset Object​

2.1.3 Easing Definition (再利用可能なイージング)​

2.1.4 Root Object の構成例​

2.2 Timeline Object​

2.2.1 Track Object​

2.3 Clip Object​

2.3.1 ClipType 一覧​

2.3.2 クリップ共通プロパティ​

2.3.3 BlendMode 一覧​

2.4 AnimatedValue Object​

2.4.1 Keyframe Object (キーフレームベース)​

Keyframe 構造​

2.4.2 Expression Object (時間生成器)​

2.4.3 Stack Object (多重構造)​

Layer 構造​

2.5 Easing (補間ファンクション)​

2.5.1 preset (プリセット)​

基本プリセット (Standard)​

外部プリセット (Easings.net)​

2.5.2 power (累乗)​

2.5.3 bezier (ベジェ)​

2.5.4 elastic (エラスティック)​

2.5.5 custom (プロジェクト定義の参照)​

3. project.json の全体例​