キーフレームマップ

キャラクターのキーフレーム静止画と、その間をつなぐモーション動画を「状態遷移図」のように配置して、継ぎ目の少ない待機アニメーションを連続・ランダム再生するためのツールです。

1. このアプリでできること

• ノード＝キーフレーム静止画（ポーズ）。キャンバス上に好きなだけ置けます。
• 矢印＝ノードからノードへのモーション動画。向きが「どのポーズからどのポーズへ動くか」を表します。
• 矢印の中間に動画プレビューが表示され、シークスライダーで開始ノード・動画・終端ノードを行き来して確認できます。
• 右上の ▶ で、ノードと矢印をたどりながら静止画と動画を連続再生できます。リンク先がなければランダムに選んで再生し続けます。
• 配置と接続は JSON として保存・読み込みできます。

2. 基本の流れ

1. ペンシルモードでキャンバスをタップし、ノードを追加します（名前を入力、または画像を選択）。
2. 接続編集モードでノードを2つ選び、「選択順 →」「← 逆順」「↔ 両方」で矢印をつなぎます。
3. 矢印を選んで長押しし、モーション動画ファイルを指定します。ノードも長押しで画像を指定できます。
4. レイアウト・タグモードでノードを動かし、ピンチでプレビューの大きさを整えます。ノード・矢印にはタグも付けられます（4 章）。
5. 📁 から JSON を保存します。右上の ▶ で連続再生を確認します。

画像・動画をまとめて取り込みたいときは、📁 →「メディア再リンク」で複数のファイルを選ぶと、静止画は新規ノード、動画は未リンクの矢印として一気に追加できます（9 章）。

3. 画面のボタン

4. 編集モード

5. すべてのモードで使える操作

• タップ：ノードまたは矢印を選択（何もないところをタップすると選択解除）。
• スワイプ：キャンバスをスクロール（レイアウト・タグモードでは範囲選択、選択範囲の四角の内側から始めた場合は移動、四隅からは拡大縮小）。
• マウスのホイールボタンのドラッグ：どのモードでもキャンバスをスクロール移動します。
• 移動中の自動スクロール：ノード・未リンクの矢印を移動しているとき、ポインタを画面の端へ近づけるとキャンバスが自動でスクロールし、そのまま移動を続けられます。
• Ctrl＋左クリック（Mac は ⌘＋クリック）：ノード・矢印を選択に追加／解除します（レイアウトモードに切り替わります）。選択したものは破線の四角で囲まれ、一括で移動（四角の内側をスワイプ）・削除（Delete キー）できます。つながっている矢印は移動できませんが、Delete で接続解除できます。
• 2 本指スワイプ：どのモードでもキャンバスを移動します（レイアウト・タグモードでサイズ変更の対象を選択中でも、2 本指を平行に動かせば移動だけ行います）。
• ピンチ：キャンバスのズームアウト／ズームイン。PC ではマウスホイールでもズームできます。
• 長押し：長押ししたノード／矢印のサブメニューを表示します。範囲選択の四角の内側ではタグを追加／タグを一括削除／コピー／切り取り／削除、何もないところでは貼り付けのメニューが出ます。
  • ノード：ファイル名選択（画像）／直前の動画の最終フレームから生成／直後の動画の先頭フレームから生成（つながっている動画のフレームを静止画として設定。動画が複数あるときは選択）／ファイル解除／名前を変更／タグを追加（レイアウト・タグモードのみ）／ノードを削除（つながっていた矢印は残り、動画があれば未リンクの矢印になります。動画のない矢印は削除されます）
  • 矢印：ファイル名選択（動画）／ファイル解除／前後の静止画ノードを自動生成（未リンクの矢印のみ）／タグを追加（レイアウト・タグモードのみ）／矢印を削除（未リンクの矢印は、ファイル解除でも削除されます）

キーボード・ドラッグ＆ドロップ

• Delete（Mac は delete）キー：リンク済みのノード・矢印は接続解除、未リンクのノード・矢印は削除します。ノードの接続解除は、そのノードにつながる矢印を外します（動画があれば未リンクの矢印に、なければ削除。ノードは残ります）。ノードが選択されていなければ矢印が対象です（接続編集モードで複数選択した矢印は、まとめて対象になります）。
• Ctrl+C／Ctrl+X／Ctrl+V（Mac は ⌘）：選択中のノード・矢印・範囲選択をコピー／切り取り／貼り付けします（サブメニューからも実行できます）。選択ノード同士をつなぐ矢印は一緒にコピーされ、単独で選んだ矢印や未リンクの矢印は未リンクの矢印として貼り付けられます。切り取りで選択外のノードとつながっていた矢印は、未リンクの矢印として残ります。貼り付けは、キーでは最後にポインタがあった位置（なければ画面中央）、メニューでは長押しした位置に行い、貼り付けたものは範囲選択の状態（レイアウト・タグモード）になります。コピーした内容はアプリ内にのみ保持されます。
• Ctrl+A（Mac は ⌘A）：ノードと未リンクの矢印をすべて選択します（レイアウト・タグモードに切り替わります）。
• Ctrl+Z（Mac は ⌘Z）：アンドゥ。Ctrl+Y または Ctrl+Shift+Z：リドゥ。
• ドラッグ＆ドロップ：画像・動画ファイルをキャンバスにドロップすると、📁 →「メディア再リンク」と同じ処理（9 章）で取り込みます。

6. 矢印の接続

接続編集モードで選んだ内容によって、接続ボタンの働きが変わります。

A. ノードを 2 つ以上選んだとき（一括接続）

ノードは何個でも選べます。選択順に隣り合う組（1 つ目と 2 つ目、2 つ目と 3 つ目、…）ごとに、次のとおりまとめてつなぎます。2 つだけのときは、その 1 組だけです。

• 選択順 →：選んだ順に、1 つ目 → 2 つ目 → 3 つ目 → … と矢印を引きます。
• ← 逆順：選んだ順の逆に、… → 3 つ目 → 2 つ目 → 1 つ目 と矢印を引きます。すでに逆向きの矢印があれば、向きを入れ替えます。
• ↔ 両方：各組に、選択順と逆順の 2 本の矢印を引きます。2 本は平行にずらして表示され、それぞれに別々の動画ファイルを指定できます。
• 接続解除：隣り合う組をつなぐ矢印（どちら向きも）をすべて削除します。

すでにある矢印は、動画ファイルなどの設定を保ったまま使われます（向きが違うものは向きだけ変わります）。3 つ以上を選んだときは、完了時に「追加／向きを変更／削除した矢印の本数」が表示されます。

B. ノードを 2 つ ＋ 未リンクの矢印を 1 本選んだとき

未リンクの矢印（動画はあるが、どのノードにもつながっていない矢印。画面では「未接続」と表示）を、選んだ 2 ノードの間につなぎます。動画ファイルはそのまま引き継がれます。

• 選択順 →／← 逆順：その向きの矢印として接続します。すでに同じ向きの矢印があるときは使えません。
• ↔ 両方：片方の向きにこの矢印を使い、もう片方の向きには動画なしの矢印を追加します。

未リンクの矢印は、ノードを選んだ状態でタップして選びます（選び直すと別の未リンクの矢印に切り替わります）。

なお、未リンクの矢印に動画を設定すると先頭・最終フレームのノードが自動で作られて接続されるため、通常はこの手動接続は不要です。接続を解除した矢印を、別のノードにつなぎ直したいときに使います。

B2. ノードを 1 つ ＋ 未リンクの矢印を 1 本選んだとき

選んだノードと矢印をつなぎ、もう一方の端は動画から静止画ノードを自動生成します（動画が再リンクされている必要があります）。

• 選択順 →：ノードを矢印の始点にし、動画の最終フレームのノードを終点に生成します。
• ← 逆順：ノードを矢印の終点にし、動画の先頭フレームのノードを始点に生成します。
• ↔ 両方：選択順の接続に加えて、逆向きの動画なしの矢印も追加します。
• 接続解除：選んだノードにつながる矢印をすべて外します（動画があれば未リンクの矢印に、なければ削除）。

C. リンク済みの矢印を 1 本選んだとき

• ← 逆順：矢印の向きを入れ替えます。
• ↔ 両方：逆向きの矢印（動画なし）を追加します。
• 接続解除：ノードとの接続を外して、未リンクの矢印に変換します（動画ファイルは残り、その場に残ります）。動画のない矢印は置き場がないため、削除されます。

逆向きの矢印がすでにあるときは「← 逆順」「↔ 両方」は使えません。どの場合も、2 つのノード間の矢印は向きごとに 1 本までです。

C2. リンク済みの矢印を複数選んだとき

矢印は何本でも選べます（タップするたびに追加／解除。選んだ順に、矢印の角に番号が表示されます）。

• ← 逆順：選んだ矢印の向きを、それぞれ入れ替えます（逆向きの矢印がすでにあるものは対象外）。
• ↔ 両方：選んだ矢印のそれぞれに、逆向きの矢印（動画なし）を追加します。
• 接続解除：選んだ矢印をすべてノードから外します（動画があれば未リンクの矢印に、なければ削除）。
• 📋 プロンプト：選んだ矢印の前後のファイル名と動画プロンプトを、選択順にすべてクリップボードにコピーします。矢印 1 本につき 3 行（先頭フレームのファイル名／最終フレームのファイル名／動画プロンプト）で、矢印どうしは空行で区切ります。動画プロンプトは、前後のノードに説明文があるときの、矢印の説明文です。説明文のない矢印は除外され、その本数が表示されます。選択した矢印を長押しして出るメニューの「📋 選択した N 本の前後のファイル名と動画プロンプトをコピー」からもコピーできます。

7. 動画プレビューとシーク

• 動画を指定した矢印の中間に、プレビューと再生ボタンが表示されます。プレビューの下には動画のファイル名が表示されます。未リンクの矢印は、置かれた位置にプレビューが表示されます。
• 再生前は開始ノードの静止画、再生が終わると終了ノードの静止画が表示されます（未リンクの矢印は動画のフレームが表示されます）。
• プレビュー下のスライダーをドラッグすると、シークできます。左端の青い部分が開始ノードの静止画、中央が動画、右端の青い部分が終了ノードの静止画です。
• 再生中にスライダーを動かすと一時停止し、指を離すと中間位置から再生を再開します。

8. 連続再生（▶）

右上の ▶ を押すと、大きなポップアップで再生します。右上の ✕（または Esc キー）で閉じます。

どこから始まるか

• 矢印を選択中：その動画から。
• ノードを選択中：その静止画から。
• 何も選択していない：画像・動画が指定されているものからランダムに選んで開始。

次に何が再生されるか

• 静止画のノードは、設定した秒数（初期値 1.5 秒）表示します。そのあと、ノードから出ている矢印の動画を再生します。矢印が複数あるときはランダムに選びます（動画が指定された矢印を優先）。
• 動画が終わると、矢印の先のノードの静止画へ進みます。
• 出ている矢印がない場合（未リンクの矢印の再生後も含む）は、存在する静止画または動画をランダムに選んで再生を続けます。
• 画像・動画が未指定のもの、またはファイルが再リンクされていないものは飛ばします。再生できるメディアが 1 つもない場合は、メッセージを出して閉じます。

設定（⚙）

• 静止画の再生秒数：静止画を表示する秒数（0.1〜60 秒、初期値 1.5 秒）。
• 同じ箇所の最大ループ回数（1〜99、初期値 5）：連続再生中に同じノード／矢印へ入ろうとして回数がこの値に達すると、強制的にランダムなノードまたは矢印へジャンプして再生を再開し、回数はリセットされます。
• LM Studio のURL／モデルID／タグの語彙／ネガティブリスト／タグの最大数：画像の自動タグ付け用の設定です（12 章）。🔌 接続テストで、入力中のURLに接続できるか、使えるモデルは何かを確認できます。
• Gemini の API キー／モデルID：Gemini API でのタグ付け・説明文の生成用の設定です。モデルIDが空のときは、既定の gemini-3.1-flash-lite を使います（🔌 接続テストで、使えるモデルを確認できます）。
• 設定は端末のブラウザに保存されます。再生中に変更した値は、次の切り替えから反映されます。

縮小表示

• ✕ の左隣の ▢（最大化）と、その左隣の –（縮小表示）で、再生ウインドウの大きさを切り替えます。
• 縮小表示中はウインドウが右下に小さく表示され、キャンバスを操作できます。再生中のノードまたは矢印は黄色で強調され、画面の外にあるときは自動でそこへ移動します。

9. 保存と読み込み

• 保存（JSON）：ノードの名前・静止画ファイル名・位置・プレビューサイズ、矢印の位置・向き・動画ファイル名・プレビューサイズを保存します。
• 読み込み（JSON）：保存した JSON から復元します。
• 保存（ZIP）：JSON（keyframe-map.json）と、使われている画像・動画ファイルを 1 つの ZIP（keyframe-map.zip）にまとめて保存します。画像・動画は media/ フォルダに入ります（再リンクされていないメディアは含まれません）。
• 読み込み（ZIP）：ZIP 内の JSON と画像・動画を取り込み、ノード・矢印とメディアを再リンクなしで復元します。現在の内容は置き換わります。ファイルが大きいと時間がかかることがあります。
• メディア再リンク：JSON には画像・動画そのものは入らず、ファイル名とハッシュ値（ファイルの内容から計算した識別値）が入ります。読み込み後に「メディア再リンク」で画像・動画をまとめて選ぶと、まずファイル名が一致するものに割り当てます。ファイル名が見つからない場合は、ハッシュ値が一致するファイルを探して割り当て、JSON 内のファイル名も新しい名前に更新します。ファイルをリネームしたあとでも読み込めます。
• 該当しないファイルは新規として読み込み：JSON のどのファイル名にもハッシュ値にも該当しなかったファイルは、次のように新しく追加されます。
  • 静止画 → 新規ノード（ノード名はファイル名）
  • 動画 → 未リンクの矢印として追加され、先頭フレームと最終フレームが静止画ノードとして自動生成されます。「先頭フレームのノード → 動画の矢印 → 最終フレームのノード」の順に自動で接続されます。
  追加したものは、既存の内容の下に並び、表示位置も自動で移動します（動画は 1 行に 2 セットずつ）。読み込めなかったファイルは追加されません。
• 先頭・最終フレームの自動生成：未リンクの矢印に動画ファイルが設定されたときは、再リンクだけでなく、ペンシルモードの「動画から作成」や、長押しメニューの「ファイル名選択（動画）」でも同じように生成・接続されます。生成した静止画は 動画名_first.png／動画名_last.png という名前で、このアプリ内にだけ保持されます。📁 →「生成した静止画を保存」でファイルとして保存でき、次回のメディア再リンクで動画と一緒に選べば元どおりリンクされます。フレームを生成できなかった場合は、未リンクの矢印のまま残ります。
• 動画の再リンク時の静止画の補完：再リンクした動画が既存のリンク済みの矢印（ファイル名またはハッシュ値が一致）に当たった場合でも、その前後のノードの静止画が空であれば、動画の先頭・最終フレームから生成して設定します。画像名は入っているがファイルが未リンクのノードでも、自動生成されたと推定されるもの（ノード名の末尾が「先頭」「最終」、または画像名が _first／_last で終わるもの）は、矢印の始点側なら先頭フレーム、終点側なら最終フレームから再生成します。
• 新規作成：現在の内容を破棄して、まっさらな状態にします。
• 編集内容は端末のブラウザにも自動保存されます。ただし画像・動画は保存されないため、ブラウザを開き直したら再リンクが必要です。

10. JSON の形式

{
  "app": "keyframe-map",
  "version": 1,
  "nodes": [
    { "id": "a1", "name": "待機A", "x": 0, "y": 0,
      "imageFile": "idle_a.png", "imageHash": "sha256:3f2a…",
      "previewW": 160, "previewH": 90,
      "tags": ["立ち", "笑顔"] }
  ],
  "arrows": [
    { "id": "r1", "from": "a1", "to": "b2",
      "x": 120, "y": 40, "angle": 15.0,
      "videoFile": "a_to_b.mp4", "videoHash": "sha256:9c1e…",
      "previewW": 200, "previewH": 113, "tags": ["手を振る"] },
    { "id": "r2", "from": null, "to": null,
      "x": 300, "y": 400, "angle": null,
      "videoFile": "free.mp4", "videoHash": "sha256:41bd…",
      "previewW": 200, "previewH": 113 }
  ]
}

• x y（ノード）：キャンバス上の中心座標。
• from to（矢印）：始点・終点のノード id。両方 null のときは未リンクの矢印です（videoFile が必要です）。
• x y angle（矢印）：矢印の中間座標と向き（度）。つながっている矢印ではノードの位置から再計算されるため記録用の値です。未リンクの矢印では x y がプレビューの中心位置として使われ、angle は null です。
• previewW previewH：プレビューの幅・高さ。
• tags（ノード・矢印）：タグ名の配列。タグがないときは省略されます（省略された JSON も読み込めます）。
• imageHash videoHash：ファイル内容の SHA-256 ハッシュ。32MB を超えるファイルは処理を軽くするため、サイズと先頭・中央・末尾の一部から計算します（sha256q: で始まります）。

11. ヒント・注意

• 画像・動画は同名のファイルを同じものとして扱います。別の内容でファイル名が重なると、あとから選んだものに置き換わります。
• ファイルの中身を書き換えて同じ名前で保存し直した場合は、名前が一致するのでそのままリンクされ、ハッシュは新しい内容に更新されます。
• 動画の対応形式はブラウザによって異なります（MP4/H.264 が最も広く再生できます）。
• フルスクリーンに対応していないブラウザ（iPhone の Safari など）では、「ホーム画面に追加」してアプリとして開くと全画面で使えます。
• ヘルプは新しいタブで開きます。アプリのタブに戻れば、編集中の状態と読み込んだメディアはそのまま残っています。

12. 編集メニュー（アンドゥ／リドゥ・自動並べ替え）

モードボタンの右隣の 🛠 編集 の先頭に ↶ アンドゥ／↷ リドゥ があります。ノード・矢印の追加や削除、接続、移動、サイズ変更、並べ替えなどを最大 50 回分まで戻せます（画像・動画ファイルの取り込み自体は戻せません）。

同じメニューから、ノードを自動で並べ替えます。ノードの位置が変わるだけで、接続や動画・画像の設定は変わりません。

• タグの類似度でソート：ノードに付けたタグが似ているもの（共通するタグの割合が高いもの）が近くに並ぶ順を基準にします。同じタグ構成のノードは名前順（数字は数の大きさで比較）のままで、タグのないノードは最後に名前順で並びます。
• 画像の類似度でソート：似た画像が近くに並ぶ順を基準にします。この並びを矢印の交差の削減よりも優先して配置します（動画から自動生成した静止画も同様）。画像のないノードは最後に名前順で並びます。比べ方は次の2つを混ぜています。
  • 画像認識（CLIP）：端末の中で画像認識モデルを動かし、ポーズ・表情・雰囲気の近さを数値にして比べます。画像は外部に送信されません。初回のみモデル（約90MB）のダウンロードが必要で（確認ダイアログが出ます）、以降はブラウザのキャッシュから読み込みます。計算結果は画像のハッシュ値ごとにこの端末に保存するため、2回目以降は新しい画像の分だけ計算します。
  • 画素の特徴：キャラクター部分を切り出して縮小し、全画像に共通する成分（背景や同じ服など）を引いたうえで、色・輪郭・位置とサイズの違いを比べます。
  モデルを読み込めない場合（オフラインでの初回など）や、ダウンロードをキャンセルした場合は、画素の特徴だけで並べ替えます。完了時のメッセージにどちらで比べたかが表示されます。
• どちらも、ノードと動画プレビューが重ならない間隔の格子に置いたうえで、ノード同士を入れ替えて矢印の交差やノードを貫く矢印ができるだけ減るようにします。あわせて、矢印の向きができるだけ右向き（→）になるようにします（左向きは強く、縦向きは弱く避けます。往復の2本の矢印は対象外）。交差がなければ基準の並びがそのまま保たれます。
• 未リンクの矢印は、ノードの下に動画名の順で並びます。
• 並べ替えたあと、全体が画面に収まるように表示を合わせます。アンドゥで配置と表示を元に戻せます。
• 矢印が多く込み入った図では、交差を完全になくせないことがあります。完了時のメッセージに交差の件数が表示されます。数秒かかることがあります。

画像にタグ付け（LM Studio）

🛠 →「🤖 画像にタグ付け（LM Studio）」で、LM Studio で動かしている画像対応モデル（Qwen の Vision モデルなど）に画像を送り、ポーズ・表情・向き・動作を表すタグを自動で付けます。付いたタグは「タグの類似度でソート」にそのまま使えます。

• 対象：ノードを選択中ならそのノード、何も選んでいなければタグのない画像ノードすべて。付いているタグは消さず、追加します。1回の実行は、アンドゥで一度に戻せます。
• 送るもの：キャラクター部分を切り出して 512px に縮小した画像だけです。送信先は ⚙ 設定の URL のサーバー（実行前に確認が出ます）。
• 設定（⚙）：URL（初期値 http://localhost:1234/v1。http://localhost:1234 のようにポートまでの入力でも、/v1 を補います）、モデルID（空なら画像対応らしいモデルを自動選択）、タグの語彙（任意）、タグの語彙（ネガティブリスト）、タグの最大数（1〜20、初期値 8）。語彙を入れると、その中からだけタグを選ばせます。ネガティブリストに入れたタグは、使わないよう指示し、返ってきても除外します（全画像に共通して役に立たないタグや、不正確なタグを外すのに使います。全角・半角と大文字・小文字は区別しません）。ネガティブリストは新しく付けるタグにだけ働き、すでに付いているタグは変わりません（外すときは範囲選択の長押しメニューの「タグを一括削除」）。語彙が空のときは、すでに使っているタグを優先して再利用させます。
• 中止：実行中にもう一度同じメニューを開くと「⏹ タグ付けを中止」になります。それまでに付いたタグは残ります。
• LM Studio 側の準備：画像対応モデルを読み込み、Developer（サーバー）の設定で「Enable CORS」をオンにして、サーバーを起動します。他の端末から使うときは「Serve on Local Network」もオンにします。⚙ の「思考を飛ばす」（初期値オン）は、空の thinking ブロックを返答の先頭に入れて、思考なしで即答させます。サーバーが受け付けない場合は自動で外して再試行します。結果が reasoning_content 側に入るモデルでも、そちらから読み取ります。
• 接続できないとき：このアプリが https://（GitHub Pages など）で開かれていると、ブラウザは http:// の LAN 内アドレス（例 http://192.168.…）への接続をブロックします。PC のブラウザで使うなら http://localhost:1234/v1 のままで接続できます。iPad など別の端末から使うときは、LM Studio を HTTPS で公開する（Tailscale Serve、Cloudflare Tunnel など）必要があります。公開する場合は、第三者に使われないようアクセス制限をかけてください。