FaceLink

FaceLinkは、制約されたショット記述を編集可能なBlenderシーンアニメーションに変換します。プリビズ/ホワイトモデル向けのツールです。アクター、小道具、カメラは通常のBlenderオブジェクトと通常のキーフレームのままなので、アーティストは結果をドラッグし、リタイムし、上書きできます。

FaceLinkはテキストをビデオに変換するツールではなく、LLMに無制限のPython実行を許可するものでもありません。モデルは型付きのShotSpecを生成し、FaceLinkがそれを検証し、ホワイトリスト化された少数のパッチ操作にコンパイルし、Blender内で人間が読めるレビューをステージングし、アーティストがApply Staged Patchを押した後にのみシーンを変更します。

デモ

この4秒のデモは、同梱の編集可能な.blendシーンからレンダリングされたものです。モーションはFaceLinkの実際のパッチ実行によるもので、Blenderの外部で焼き込まれた生成済みビデオではなく、24個の編集可能な普通のキーフレーム値として残っています。

Related MCP server: blender-mcp

現在のMVP

• 開いているBlenderシーンをスキャンし、オブジェクトに安定したFaceLink IDを割り当てます;

• move_to、turn_to、look_at、wait、play_clipのビートをコンパイルします;

• 編集可能なトランスフォーム、キーフレーム、カメラ、トラッキング制約を作成・更新します;

• ワールド空間でトランスフォームを計画し、ペアレント化されたBlenderオブジェクト用に変換します;

• Codex/ChatGPT互換のMCPクライアントに対して、MCPサーバー経由でワークフローを公開します;

• OpenAI APIキーとStructured Outputsによるプランニングをサポートします;

• MCPプロセスとBlenderの間に、localhost専用の認証付きブリッジを実行します;

• Blender側でのステージ/レビュー/適用/破棄、永続的な監査履歴、選択した現セッションのリビジョンへの安全なロールバックをサポートします;

• 内部で重複するトランスフォーム/アクションのタイムラインを拒否し、既存のキーフレームを上書きする前に警告し、衝突するFaceLink NLAクリップを拒否します;

• シーンのデータブロックを作成せずに、ステージされたワールド空間のモーションパスと予測カメラフラスタムをBlenderのビューポートに直接プレビューします;

• 明示的にマークされたナビゲーションメッシュと障害物をスキャンし、決定論的なマルチセグメント移動経路を計画し、アクターの通過範囲がマークされた障害物と交差する場合に警告します;

• ナビゲーション環境全体のフィンガープリントを取得するため、新しく追加された障害物や編集されたナビゲーションメッシュは、すでにステージされたプランを無効化します;

• アーマチュアのボーン階層と編集可能なBlenderアクションのインベントリを作成します。ポーズボーンチャンネル、静止方向、フレーム範囲、決定論的なコンテンツフィンガープリントなどを含みます;

• 決定論的な名前正規化を使用したレビュー専用のボーンマップを提案し、実行前にマップされた階層、ローカル静止軸、スケール正規化されたボーンプロポーションを評価します;

• 互換性のあるアクションをオープンなrename_onlyボーンマッププロファイルでコピーし、編集可能なFCurveパスを書き換え、NLAに配置し、ロールバック時に作成したコピーを削除します;

• レビュー済みのbake_poseプロファイルを通常の編集可能なターゲットActionsにサンプリングし、異なるローカル静止軸やボーンのスケールを、明示的なルートモーションポリシーと限られた作業量で修正します;

• bake_evaluated_poseで既存の自己完結型ソースリグの制約とドライバーを評価し、最終的な変形ボーンのポーズを通常の編集可能なActionにベイクします;

• オプションでアーマチュアオブジェクトのルートモーションを、ソース単位またはリグスケールを調整した並進で、配置を保持する相対デルタとして転送します;

• シーンのデータブロックを作成せずにステージされたカメラフレームを予測し、アーティストが適用する前に、ターゲットサイズ、センターオフセット、セーフエリアの適合、クリッピング、中心点のオクルージョンを計測します;

• 参照されているシーンを適用する前に、参照されるトランスフォーム、親リンク、ロック、シーンタイミングの値がシーンスキャン後に変更された場合、ステージ済みプランを拒否します。

対応Blenderバージョン

• 主対応: Blender 4.5 LTS (4.5.12で検証済み)

• 最小: Blender 4.2 LTS

• ベストエフォート: Blender 5.x

開発マシンにあるBlender 4.0.2の導入は、拡張機能のベースラインより前のものです。FaceLinkのソースは、スモークテストのためにそこに読み込むことはできますが、4.0はサポートを宣言したバージョンではありません。

アルファリリースのインストール

FaceLink 0.3.8 AlphaリリースからFaceLink-Setup-0.3.8.exeをダウンロードし、開いて、Check setup を選択し、次に Install FaceLink を選択します。

このアルファ版EXEはまだコード署名されていないため、Windows SmartScreenは発行元不明の警告を表示する場合があります。More info → Run anywayを選ぶ前に、リリースのSHA256SUMS.txtと照合して、公式のFaceLink公開ページからダウンロードしたファイルのみを使用してください。

FaceLinkはBlenderを同梱しません。既存の公式Blender 4.2以降のインストールを検出するので、リリースを小さく保て、各アーティストがBlender 4.5 LTSや互換性のある新しいバージョンを選べます。Blenderがない場合は、公式のBlender LTSページからインストールしてください。

グラフィカルインストーラーには、FaceLinkホスト、拡張機能、チェックサムマニフェスト、安全なPowerShellバックエンドが1つの小さなEXEに含まれています。埋め込まれたファイルを検証し、PythonとBlenderを検出し、両方のFaceLinkコンポーネントをインストールし、共有のローカルChatGPT Desktop/Codex MCPファイルを安全に設定します。管理者アクセスを要求せず、APIキーも保存しません。

手動Windowsインストールの場合は、4つの生のリリースファイルをまとめて置いて、次のコマンドを実行します:

.\install-windows.ps1 `
  -WheelPath .\facelink-0.3.8-py3-none-any.whl `
  -ExtensionZipPath .\facelink-0.3.8.zip `
  -ChecksumsPath .\SHA256SUMS.txt

このスクリプトは、リリースのハッシュを検証し、Python 3.11+とBlender 4.2+を見つけ、分離されたFaceLinkホストを作成し、拡張機能をインストールし、正確なfacelink-mcp.exeパスを設定します。-PlanOnlyを渡すと、何もインストールせずに解決されたパスをすべて表示します。Blenderがポータブルな場所や通常の場所以外にある場合は、-BlenderExe C:\path\to\blender.exeを渡してください。-SkipMcpConfigurationを渡すと、ローカルのMCP設定を変更しません。既存のFaceLink拡張機能がある場合は、拡張機能インストール手順の前に、その版を更新するか、BlenderのPreferencesで古いバージョンを削除してください。

BlenderでFaceLinkのブリッジを起動した後、接続全体を検証します:

facelink doctor --blender-exe C:\path\to\blender.exe

この診断はAPIキーやBlenderブリッジのベアラートークンを印刷しません。APIキーがないというブラウザまはMCPクライアントが独自のモデルを使えるため、警告のみです。

2つのコンポーネントを手動でインストールするには、以下に続きます。

Blender 4.2以降では、Edit →Preferences → Get Extensions → Install from Disk を開き、facelink-0.3.8.zip を選択し、FaceLink を有効にし、3DビューポートのサイドバーにあるFaceLinkタブを開き、Start Bridge を押します。

Pythonホストを、分離されたPython 3.11以降の環境にインストールします:

py -3.11 -m venv .venv
.\.venv\Scripts\python -m pip install .\facelink-0.3.8-py3-none-any.whl
.\.venv\Scripts\facelink-mcp

リリースのSHA256SUMS.txtを使用して、ダウンロードしたすべての成果物を検証してください。MCPクライアントの設定と安全なステージ/レビュー/適用ワークフローについては、以下を参照してください。

開発用インストール

cd E:\FaceLink
$env:UV_CACHE_DIR='E:\CodexData\Work\FaceLink\uv-cache'
uv sync --extra dev
uv run pytest

再現可能なマルチバージョン受入マトリックスは、実際の拡張インストールを含めて、次のとおりです:

./scripts/run_acceptance.ps1

ハーネスは、artifacts/の下にJUnit、カバレッジ、BlenderジョブとJSON、コマンドログを書き出します。正確なゲートと既知の除外については、docs/TESTING.mdを参照してください。

Blender拡張をビルドします:

$env:FACELINK_BLENDER_EXE='C:\path\to\Blender\blender.exe' # optional if on PATH
./scripts/build_extension.ps1

次にBlender 4.5で、Edit →Preferences → Get Extensions → Install from Diskを選択し、dist/facelink-0.3.8.zipを選択してFaceLinkを有効化し、3DビューポートサイドバーのFaceLinkタブを開いてStart Bridgeを押します。

MCPサーバを実行します:

uv run facelink-mcp

共有ローカルChatGPT Desktop/Codex設定を安全に作成または更新します:

uv run facelink configure-mcp `
  --mcp-launcher E:\FaceLink\.venv\Scripts\facelink-mcp.exe `
  --instance-dir E:\CodexData\Work\FaceLink\instances

FaceLinkは、既存の~/.codex/config.toml をバックアップし、無関係な設定を保持し、明確にマークされたブロックだけを所有します。生成されるOpenAI互換設定はTOMLです:

[mcp_servers.facelink]
command = "E:\\FaceLink\\.venv\\Scripts\\facelink-mcp.exe"
enabled = true

[mcp_servers.facelink.env]
FACELINK_INSTANCE_DIR = "E:\\CodexData\\Work\\FaceLink\\instances"

ChatGPTデスクトップアプリ、Codex CLI、CodexIDE拡張はこのローカル設定を共有します。Web上のChatGPTはローカルMCP設定を読み出さないため、個別にホストされたプラグインが必要です。OpenAI公式MCPドキュメントを参照してください。同じFACELINK_INSTANCE_DIRが将来のBlender用に設定されます。インストール後はBlenderとMCPクライアントを再起動してください。

MCPクライアントでは、安全な既定の手順は次のとおりです:

1. scan_scene

2. ユーザーの自然言語リクエストを型付きショットに変換してpreview_shotを呼び出します

3. stage_scene_patchを呼び出します

4. ユーザーにBlenderでサマリーを確認させ、Apply Staged PatchまたはDiscardを押させる

この方法は、MCPクライアント内のモデルを使用します。FaceLink自体にAPIキーは必要ありません。apply_scene_patchは、上級者向けのバイパスとして、依然として利用できます。

BYOKプランニング

$env:OPENAI_API_KEY='your-key'
uv run facelink plan --brief "Cube walks to Marker in 2 seconds, camera follows Cube" `
  --snapshot scene.json --out shot.json

または、実行中のBlenderシーンをスキャンして、プラン、コンパイル、ステージを1つのコマンドで行えます:

$env:OPENAI_API_KEY='your-key'
uv run facelink workflow `
  --brief "Cube walks to Marker in 2 seconds, camera follows Cube"

このコマンドは何も適用しません。ステージされた結果をBlenderで確認し、承認してください。

既存のActionを、ボーン名の異なる互換アーマチュアに対象とするには、レビュー済みのオープンなプロファイルを渡します:

uv run facelink validate-profile `
  --profile profiles/mixamo_to_facelink_compact.json

uv run facelink suggest-profile `
  --snapshot scene.json --source-rig source-armature-id `
  --target-rig target-armature-id --action "Mixamo Walk" `
  --name "Reviewed map" --out suggestion.json

uv run facelink analyze-profile `
  --profile profiles/mixamo_to_facelink_compact.json `
  --snapshot scene.json --source-rig source-armature-id `
  --target-rig target-armature-id --out compatibility.json

uv run facelink plan `
  --brief "Apply Mixamo Walk to the target rig for two seconds" `
  --snapshot scene.json `
  --retarget-profile profiles/mixamo_to_facelink_compact.json `
  --out shot.json

提案は自動的に適用されることはなく、常にreview_required: trueを持ちます。互換性の結果はsafe、review、bake_required、incompatibleのいずれかです。コンパイラーは、階層、静止方向、比率のベイクが必要な場合、rename_onlyをブロックします。FaceLinkはActionsと参照するリグの両方をフィンガープリント化するため、スキャン後のカーブや静止ポーズの編集はミューティーション前に失敗します。また、異なるサイズのリグ間でのスケール調整されていないポーズボーンの移動チャンネルもブロックします。生成されたActionsとNLAストリップは、通常の編集可能なBlenderデータのままです。profiles/README.mdとexamples/retargeted_clip_shot.jsonを参照してください。

解析でbake_required(ローカル静止軸またはリグのスケールが異なるため)と表示された場合は、レビュー済みプロファイルをadapter: "bake_pose"に変更し、明示的なsource_rigを設定し、必要に応じてsample_step (1-16)

キャラクター全体の移動がソースのArmatureオブジェクト上にある場合は、object_motion: "preserve" または "scale" をどちらかのベイクアダプターに追加します。FaceLinkはソースオブジェクトの最初のサンプリングフレームに対する相対的なトランスフォームを使用し、ターゲットの現在のワールドトランスフォームの後にその差分を適用し、通常のオブジェクトの位置・回転・スケールのFCurveを同じ生成されたActionに書き込みます。scale は差分の移動量をマッピング済みリグのメディアン長さの比率で乗算します。preserve はソースの単位を保持します。バージョン1では、親なしのソース/ターゲットArmatureと、オブジェクトコンストレイントや駆動されたターゲットオブジェクトのトランスフォームがないことが必要です。profiles/object_motion_bake.json と examples/object_motion_clip_shot.json を参照してください。

コマンドラインからFaceLinkのリビジョンを検査またはロールバックします:

uv run facelink history
uv run facelink rollback --revision rev-0123456789abcdef

リビジョンのメタデータは .blend ファイルに保存されます。実行可能なロールバックスナップショットは、ライブのBlenderデータブロック参照を含むため、意図的にセッション内のみに留められます。古いリビジョンにロールバックすると、線形なシーン状態を維持するために、それより新しいすべてのFaceLinkリビジョンもロールバックされます。

MCPクライアントが言語モデルのプランニング自体を実行する場合、APIキーはオプションです。ChatGPTのサブスクリプションとOpenAI APIの課金は別物です。ChatGPTのメンバーシップはAPIキーではありません。信頼境界については docs/ARCHITECTURE.md を参照してください。

ナビゲーションのワークフロー

歩行可能なメッシュを選択し、FaceLink → Navigation → Navmesh を使用します。壁、小道具、その他のブロッキングオブジェクトを選択し、Obstacle としてマークします。move_to ビートはデフォルトで従来の直線を維持します。path_mode を navmesh に設定すると、接続されたナビゲーショントライアングルを通る経路を取ります。コンパイラは通常の編集可能な位置キーフレームをパス距離に基づいて分配し、線形補間を強制するため、曲線ハンドルが歩行可能なコリドーから外れることはありません。

ナビゲーションは意図的に明示的です。FaceLinkはオブジェクト名から推測したり、すべてのメッシュを暗黙的に障害物として扱ったりしません。現在のv0.3.0のプランニングはXY平面に投影され、単一レベルのプリビズフロアを対象としています。複数階のフロア、ライブで移動する障害物、群衆ルーティングはまだサポートされていません。examples/navmesh_walk_shot.json を参照してください。

カメラ構図のプリフライト

ターゲットを持つカメラショットは、ステージング中にチェックされます。FaceLinkはターゲットのワールド空間バウンドを予測されたカメラフレームに投影し、クリッピング、安全でないマージン、被写体サイズ、センターオフセットを報告します。読み取り専用のBlenderレイキャストは、別のオブジェクトがターゲットの中心をブロックしている場合に報告します。dolly_in は開始位置と終了位置の両方をチェックします。しきい値は camera.composition で型指定され、ShotSpecに表示されたままとなり、明示的に無効化できます。examples/composition_checked_shot.json を参照してください。

これは決定的なプリフライトであり、芸術的な品質スコアではありません。レンダリング、ビジョンモデルの使用、ライティングの判定、複雑な被写体のすべての部分が遮蔽されていないことの保証は行いません。バージョン0.3.3はレンズシフトなしの透視カメラを評価し、他の投影タイプは誤解を招くメトリクスを返す代わりにサポート対象外として報告します。

リポジトリマップ

src/facelink/          Core schemas, compiler, bridge client, providers, CLI and MCP server
blender_extension/    Zero-dependency Blender extension and local bridge
schemas/              Portable JSON Schema for integrations
examples/             Example editable shot specifications
tests/                 Unit tests and a Blender headless smoke test
scripts/               Build and verification scripts
docs/                  Architecture, protocol and development notes

プロジェクトのステータス

バージョン0.3.8はクリエイターレビュー用のアルファ版であり、まだ本番用のアニメーションシステムではありません。レビュー済みマッピングに対して境界付きのトランスフォーム対応ポーズベイクを実行し、すべての依存関係が明示的なソースアーマチュア上に留まる場合に既存のコンストレイントとドライバーを評価できます。また、ターゲットの開始位置を移動せずに、親なし・コンストレイントなしのArmatureオブジェクトのモーションを転送できます。コントローラーの推論、IK/FKシステムの変換、外部ヘルパーオブジェクトの追従、異なるマッピング済み親階層の解決、親付き/コンストレイント付きオブジェクトルートの処理、欠落したモーションの合成、視覚的結果の判定は行いません。マルチレベルナビゲーション、マルチショットシーケンス、ビジュアル差分オーバーレイは今後の作業です。

Windowsリリースには、単一ファイルのグラフィカルインストーラー、安全なローカルMCP設定、シークレットセーフな環境ドクター、再現可能な実Blenderデモが含まれるようになりました。このアルファ版をより広く宣伝する前に、非開発者ユーザーでのインストールテストと、Linux/macOSのインストールカバレッジの完了が必要です。

ライセンス

FaceLinkは GNU GPLバージョン3以降 の下でライセンスされたフリーソフトウェアです。Blender拡張機能の配布物には同じライセンス文が含まれています。