FaceLink

FaceLink verwandelt eine eingeschränkte Shot-Beschreibung in bearbeitbare Blender-Szenenanimation. Es zielt auf Previs/White-Model-Arbeit ab: Schauspieler, Requisiten und Kameras bleiben gewöhnliche Blender-Objekte mit gewöhnlichen Keyframes, sodass Künstler das Ergebnis ziehen, neu timen und überschreiben können.

FaceLink ist kein Text-zu-Video-Generator und gibt einem LLM keine uneingeschränkte Python-Ausführung. Das Modell erzeugt eine typisierte ShotSpec; FaceLink validiert sie, kompiliert sie in eine kleine Whitelist von Patch-Operationen, inszeniert eine menschenlesbare Überprüfung in Blender und ändert die Szene erst, nachdem der Künstler Apply Staged Patch drückt.

Demo

Diese viersekündige Demo wird aus der enthaltenen bearbeitbaren .blend-Szene gerendert. Die Bewegung wurde durch FaceLinks echten Patch-Executor angewendet und bleibt 24 gewöhnliche bearbeitbare Keyframe-Werte – kein generiertes Video, das außerhalb von Blender gebacken wurde.

Related MCP server: blender-mcp

Aktuelles MVP

• scannt die offene Blender-Szene und vergibt Objekten stabile FaceLink-IDs;

• kompiliert move_to, turn_to, look_at, wait und play_clip-Beats;

• erstellt/aktualisiert bearbeitbare Transforms, Keyframes, Kameras und Tracking-Constraints;

• plant Transforms im Weltraum und konvertiert sie für parentete Blender-Objekte;

• stellt den Workflow über einen MCP-Server für Codex/ChatGPT-kompatible MCP-Clients bereit;

• unterstützt OpenAI-API-Key-Planung mit Structured Outputs;

• führt eine nur auf localhost laufende, authentifizierte Brücke zwischen dem MCP-Prozess und Blender aus;

• unterstützt Blender-seitiges Stage/Review/Apply/Discard, persistente Audit-Historie und sicheres Rollback auf eine ausgewählte aktuelle Sitzungsrevision.

• lehnt intern überlappende Transform-/Action-Zeitlinien ab, warnt vor dem Überschreiben vorhandener Keyframes und lehnt kollidierende FaceLink-NLA-Clips ab;

• zeigt gestaffelte Weltraum-Bewegungspfade und vorhergesagte Kamera-Frusten direkt im Blender-Viewport an, ohne Szenen-Datablocks zu erstellen;

• scannt explizit markierte Navigationsmeshes und Hindernisse, plant deterministische Multi-Segment- Lokomotionspfade und warnt, wenn die gesweepten Grenzen eines Akteurs ein markiertes Hindernis schneiden;

• erstellt Fingerabdrücke der gesamten Navigationsumgebung, sodass ein neu hinzugefügtes Hindernis oder ein bearbeitetes Navigationsmesh einen bereits gestaffelten Plan ungültig macht;

• inventarisiert Armature-Bone-Hierarchien und bearbeitbare Blender-Actions, einschließlich Pose-Bone- Kanälen, Ruheorientierungen, Framebreichweiten und deterministischen Inhalts-Fingerabdrücken;

• schlägt nur zur Überprüfung gedachte Bone-Maps mittels deterministischer Namensnormalisierung vor und misst dann die gemappte Hierarchie, lokale Ruheachsen und skalen-normalisierte Bone-Proportionen vor der Ausführung;

• kopiert kompatible Actions über ein offenes rename_only-Bone-Map-Profil, schreibt bearbeitbare FCurve-Pfade neu, platziert das Ergebnis in NLA und entfernt erstellte Kopien beim Rollback;

• sampelt überprüfte bake_pose-Profile in gewöhnliche bearbeitbare Ziel-Actions und korrigiert unterschiedliche lokale Ruheachsen und Bone-Skala mit expliziter Root-Motion-Politik und begrenzter Arbeit;

• wertet vorhandene eigenständige Quell-Rig-Constraints und Treiber mit bake_evaluated_pose aus und backt dann die endgültige Deform-Bone-Pose in eine gewöhnliche bearbeitbare Action;

• überträgt optional die Root-Motion des Armature-Objekts als platzierungserhaltendes relatives Delta, mit Quell-Einheiten- oder Rig-Skala-angepasster Übersetzung;

• sagt den gestaffelten Kamerarahmen voraus, ohne Szenen-Datablocks zu erstellen, und misst Zielgröße, Zentrumsversatz, Safe-Area-Passung, Clipping und Zentrumspunkt-Okklusion, bevor der Künstler anwendet;

• lehnt einen gestaffelten Plan ab, wenn sich ein referenzierter Transform, eine Parent-Verbindung, eine Sperre oder ein Szenen-Timing-Wert nach dem Szenen-Scan geändert hat.

Unterstützte Blender-Versionen

• Primär: Blender 4.5 LTS (getestet mit 4.5.12)

• Minimum: Blender 4.2 LTS

• Best effort: Blender 5.x

Die auf dem Entwicklungsrechner gefundene Blender-4.0.2-Installation stammt aus der Zeit vor der Erweiterungs-Baseline. FaceLinks Quellcode kann dort weiterhin für Smoke-Tests geladen werden, aber 4.0 ist keine deklarierte unterstützte Version.

Die Alpha-Version installieren

Laden Sie FaceLink-Setup-0.3.8.exe von der FaceLink 0.3.8 Alpha-Version herunter, öffnen Sie sie, wählen Sie Check setup, dann Install FaceLink.

Diese Alpha-EXE ist noch nicht code-signiert, daher zeigt Windows SmartScreen möglicherweise eine Warnung zu einem unbekannten Herausgeber. Verifizieren Sie sie gegen die SHA256SUMS.txt der Version, bevor Sie More info → Run anyway wählen, und verwenden Sie nur Dateien, die von der offiziellen FaceLink-Versionsseite heruntergeladen wurden.

FaceLink bündelt kein Blender. Es erkennt eine vorhandene offizielle Blender-4.2-oder-neuer-Installation, was die Version klein hält und jedem Künstler die Wahl lässt, Blender 4.5 LTS oder eine neuere kompatible Version zu verwenden. Wenn Blender fehlt, installieren Sie es von der offiziellen Blender-LTS-Seite.

Der grafische Installer enthält den FaceLink-Host, die Erweiterung, das Prüfsummen-Manifest und das sichere PowerShell-Backend in einer kleinen EXE. Er verifiziert die eingebetteten Dateien, erkennt Python und Blender, installiert beide FaceLink-Komponenten und konfiguriert sicher die gemeinsame lokale ChatGPT-Desktop/Codex- MCP-Datei. Er fordert keinen Administratorzugriff an und speichert keinen API-Key.

Für eine manuelle Windows-Installation halten Sie die vier rohen Versionsdateien zusammen und führen Sie aus:

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

Das Skript verifiziert die Versions-Hashes, findet Python 3.11+ und Blender 4.2+, erstellt einen isolierten FaceLink-Host, installiert die Erweiterung und konfiguriert den genauen facelink-mcp.exe-Pfad. Übergeben Sie -PlanOnly, um jeden aufgelösten Pfad zu inspizieren, ohne etwas zu installieren. Übergeben Sie -BlenderExe C:\path\to\blender.exe, wenn Blender portabel oder nicht auf einem herkömmlichen Pfad ist. Übergeben Sie -SkipMcpConfiguration, um die lokale MCP-Konfiguration unangetastet zu lassen. Für eine vorhandene FaceLink-Erweiterung aktualisieren Sie sie über Blender-Preferences oder entfernen Sie die alte Version, bevor Sie den Erweiterungs-Installationsschritt ausführen.

Nachdem Sie FaceLinks Brücke in Blender gestartet haben, validieren Sie das vollständige Setup:

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

Die Diagnose gibt niemals API-Keys oder das Blender-Bridge-Bearer-Token aus. Ein fehlender API-Key ist nur eine Warnung, da ein MCP-Client sein eigenes Modell verwenden kann.

Um die beiden Komponenten manuell zu installieren, fahren Sie unten fort.

In Blender 4.2 oder neuer öffnen Sie Edit → Preferences → Get Extensions → Install from Disk, wählen Sie facelink-0.3.8.zip, aktivieren Sie FaceLink, öffnen Sie den FaceLink-Tab in der 3D-Viewport- Seitenleiste und drücken Sie Start Bridge.

Installieren Sie den Python-Host in einer isolierten Python-3.11-oder-neuer-Umgebung:

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

Verwenden Sie SHA256SUMS.txt aus der Version, um jedes heruntergeladene Artefakt zu verifizieren. Fahren Sie unten mit der MCP-Client-Konfiguration und dem sicheren Stage/Review/Apply-Workflow fort.

Für die Entwicklung installieren

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

Für die reproduzierbare Multi-Version-Akzeptanzmatrix, einschließlich echter Erweiterungsinstallation:

./scripts/run_acceptance.ps1

Das Harness schreibt JUnit-, Coverage-, pro-Blender-JSON- und Befehlsprotokolle unter artifacts/. Siehe docs/TESTING.md für die genauen Gates und bekannten Ausschlüsse.

Die Blender-Erweiterung bauen:

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

Dann in Blender 4.5: Edit → Preferences → Get Extensions → Install from Disk, wählen Sie dist/facelink-0.3.8.zip, aktivieren Sie FaceLink und öffnen Sie den FaceLink-Tab in der 3D-Viewport- Seitenleiste. Drücken Sie Start Bridge.

Den MCP-Server ausführen:

uv run facelink-mcp

Sicher die gemeinsame lokale ChatGPT-Desktop/Codex-Konfiguration erstellen oder aktualisieren:

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

FaceLink sichert eine vorhandene ~/.codex/config.toml, bewahrt nicht zusammenhängende Einstellungen und besitzt nur seinen klar markierten Block. Die resultierende OpenAI-kompatible Konfiguration ist 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"

Die ChatGPT-Desktop-App, die Codex-CLI und die Codex-IDE-Erweiterung teilen sich diese lokale Konfiguration. ChatGPT im Web liest keine lokale MCP-Konfiguration und würde ein separat gehostetes Plugin erfordern. Siehe die offizielle OpenAI-MCP-Dokumentation. Dieselbe FACELINK_INSTANCE_DIR wird für zukünftige Blender-Prozesse gesetzt; starten Sie Blender und den MCP-Client nach der Installation neu.

Mit einem MCP-Client ist die sichere Standardsequenz:

1. scan_scene

2. die natürliche Sprach-Anfrage des Benutzers in einen typisierten Shot umwandeln und preview_shot aufrufen

3. stage_scene_patch aufrufen

4. den Benutzer die Zusammenfassung in Blender prüfen lassen und Apply Staged Patch oder Discard drücken

Dieser Pfad verwendet das bereits im MCP-Client verfügbare Modell; FaceLink selbst benötigt keinen API-Key. apply_scene_patch bleibt als expliziter Power-User-Bypass verfügbar.

BYOK-Planung

$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

Oder die laufende Blender-Szene scannen, planen, kompilieren und das Ergebnis in einem Befehl stagen:

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

Der Befehl wendet nichts an. Überprüfen und genehmigen Sie das gestaffelte Ergebnis in Blender.

Um eine vorhandene Action auf eine kompatible Armature mit unterschiedlichen Bone-Namen auszurichten, übergeben Sie ein überprüftes offenes Profil:

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

Vorschläge werden niemals automatisch angewendet und tragen immer review_required: true. Das Kompatibilitätsergebnis ist safe, review, bake_required oder incompatible. Der Compiler blockiert rename_only, wenn Hierarchie, Ruheorientierung oder Proportionen Backen erfordern. FaceLink erstellt Fingerabdrücke sowohl der Actions als auch der referenzierten Rigs, sodass Kurven- oder Ruhepose-Bearbeitungen nach dem Scan vor der Mutation fehlschlagen; es blockiert auch unskalierte Pose-Bone-Übersetzungskanäle über unterschiedlich große Rigs. Generierte Actions und NLA-Streifen bleiben gewöhnliche bearbeitbare Blender-Daten. Siehe profiles/README.md und examples/retargeted_clip_shot.json.

Wenn die Analyse bake_required sagt, weil lokale Ruheachsen oder Rig-Skala unterschiedlich sind, ändern Sie das überprüfte Profil auf adapter: "bake_pose", setzen Sie sein explizites source_rig und optional sample_step (1-16) und root_motion (scale, preserve oder drop). FaceLink sampelt die native Framebreichweite der Quell-Action, schreibt lineare Location/Rotation/Scale-Keys in eine normale Ziel-Action und legt sie in denselben bearbeitbaren NLA-Workflow. Objekt-Level-Action-Kanäle werden weggelassen, es sei denn, object_motion ist explizit; andernfalls muss Root-Motion auf einem gemappten Root-Pose- Bone liegen. Dieser erste Adapter erfordert äquivalente gemappte Parent-Hierarchie und uneingeschränkte Quell-/Ziel-Deform-Bones. Siehe profiles/mixamo_to_facelink_compact_bake.json und examples/baked_retargeted_clip_shot.json.

Wenn die Quell-Action Controller-Bones oder Custom Properties animiert und die Quell-Deform-Bones ihre endgültige Bewegung durch Constraints/Treiber erhalten, verwenden Sie adapter: "bake_evaluated_pose". Die überprüfte bone_map mappt Quell-Deform-Bones – nicht die Controller-Kanäle – auf Ziel-Deform-Bones. Version 1 erlaubt nur Abhängigkeiten auf demselben Quell-Armature-Objekt/Daten, lehnt externe Hilfsobjekte und szenengesteuerte Variablen ab und erfordert weiterhin äquivalente gemappte Parent-Hierarchie plus uneingeschränkte/ungedriverte Ziel-Bones. Es entdeckt keine Controller oder konvertiert IK/FK-Systeme automatisch. Siehe profiles/controller_to_deform_evaluated_bake.json und examples/evaluated_retargeted_clip_shot.json.

Wenn sich die gesamte Objektbewegung auf dem Quell-Armature-Objekt befindet, füge object_motion: "preserve" oder "scale" zu einem der beiden Bake-Adapter hinzu. FaceLink verwendet die Transformation des Quellobjekts relativ zu seinem ersten abgetasteten Frame, wendet diese Delta nach der aktuellen Welt-Transformation des Zielobjekts an und schreibt gewöhnliche Objekt-Location/Rotation/Scale-FCurves in denselben generierten Action. scale multipliziert die Delta-Translation mit dem Median-Verhältnis der Längen des gemappten Rigs; preserve behält Quell-Einheiten bei. Version 1 erfordert unparented Quell-/Ziel-Armatures mit keinen Objekt-Constraints oder getriebenen Zielobjekt-Transformationen. Siehe profiles/object_motion_bake.json und examples/object_motion_clip_shot.json.

FaceLink-Revisionen von der Kommandozeile aus inspizieren oder zurücksetzen:

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

Revisions-Metadaten werden in der .blend-Datei gespeichert. Ausführbare Rollback-Snapshots bleiben bewusst nur für die Sitzung bestehen, da sie Live-Blender-Datablock-Referenzen enthalten. Das Zurücksetzen auf eine ältere Revision setzt auch jede neuere FaceLink-Revision zurück, um einen linearen Szenenzustand zu bewahren.

Ein API-Schlüssel ist optional, wenn ein MCP-Client die Sprachmodell-Planung selbst durchführt. ChatGPT-Abonnements und OpenAI-API-Abrechnung sind getrennt; eine ChatGPT-Mitgliedschaft ist kein API-Schlüssel. Siehe docs/ARCHITECTURE.md für die Vertrauensgrenze.

Navigations-Workflow

Wähle ein begehbares Mesh aus und verwende FaceLink → Navigation → Navmesh. Wähle Wände, Requisiten oder andere blockierende Objekte aus und markiere sie als Obstacle. Ein move_to-Beat behält die bestehende gerade Linie standardmäßig bei; setze path_mode auf navmesh, um durch verbundene Navigationsdreiecke zu routen. Der Compiler verteilt gewöhnliche bearbeitbare Location-Keyframes nach Pfaddistanz und erzwingt lineare Interpolation, sodass gebogene Handles die begehbare Korridor nicht verlassen können.

Navigation ist bewusst explizit. FaceLink errät keine Objektnamen oder behandelt nicht stillschweigend jedes Meshl-Objekt als Hindernis. Die derzeitige Planung in v0.3.0 wird auf XY projiziert und ist für einzelne Previs-Bodenebenen gedacht; gestapelte Stockwerke, live bewegte Hindernisse und Menschenmengen-Routing sind noch nicht unterstützt. Siehe examples/messwalk_walk_shot.json.

Kamera-Kompositions-Vorabprüfung

Kameraeinstellungen mit einem Ziel werden während des Stagings überprüft. FaceLink projiziert die Weltgrenzen des Targets in die vorhergesagte Kameraperspektive und meldet Beschnitt, unsichere Ränder, die Objektgröße und Abweichung der Konturzone. Ein schreibgeschützter Blender-Raycast meldet, wenn ein anderes Objekt das Zielzentrum blockiert. dolly_in beditiert sowohl Start als auch Ende. Schwellenwerte sind in camera.composition eingetragen, bleiben im ShotSpec sichtbar und können explizit deaktiviert werden. Siehe examples/composition_checked_shot.json.

Dies ist eine deterministische Vorabprüfung, keine künstlerische Qualitätsbewertung. Sie rendert nicht, verwendet kein Visuelles modell, bewertes Licht nicht und garantiert nicht, dass jeder Teil eines komplexen Subjekts nicht verdeckt ist. Version 0.3.3 benötigt Perspektivkameras ohne Objektivverschiebung und meldet andere Projektionstypen als nicht unterstützt, anstatt irreführende Metriken in den Ausgaben zu liefern.

Repository-Karte

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

Projektstatus

Version 0.3.8 ist eine Creator-Review-Alpha, noch kein Produktions- Animationssystem in Produktionsreife. Dieses Bake-Tool führt begrenztes transformbewusste Pose-Baking für geprüfte Mappings durch und kann bestehende Constraints und Treiber auswerten, wenn jede Abhängigkeit auf der erkannten Quell-Armature. Es kann auch unparented, unconstrained Armature-Objekt-Bewegung übertragen, ohne die Startplatzierung des Ziels zu verschieben. Das Tool ist keine Inferenzkontrolle, kein Übersetzer für IK/FK-Systeme, folgt keine externen Hilfsobjekte, löst keine unterschiedlich gemappten Parent-Hierarchien, behandelt keine parenthaltenden/constructierten Objekt-Root, synthesiert keine fehlende Bewegung und beurteiltund keine visuelle Ergebnisse. Multi-Level-Navigation, Multi-Shot-Sequenzierung und visuelle Diff-Overlay bleiben Folgeaufgaben.

Der Windows-Release verfügt nun über einen einzelnen Datei-Bildschirminstaller, eine sichere lokale MCP-Konfiguration, einen secretsicheren Umgebungs-Doctor und eine reproduDa blenden-Remake-Demonstration. Vor der breiteren Bereitstellung dieser Alpha sollten Sie die Installation mit Nicht-Entwicklern testen und die Linux/macOS-Installationsabdeckung vollständig zcoverage shließen.

Lizenz

FaceLink ist freie Software, die unter der GNU-GPL-Version 3 oder jeder neueren Version lizenziert ist. Die Blender-Erweiterungsverbreitung enthält bleibt denselben Lizenztext enthalten.