FaceLink

FaceLink превращает ограниченное описание кадра в редактируемую анимацию сцены Blender. Он предназначен для работы с превизом/болванками: актёры, реквизит и камеры остаются обычными объектами Blender с обычными ключевыми кадрами, поэтому художники могут перетаскивать, изменять тайминг и переопределять результат.

FaceLink — это не генератор видео из текста, и он не даёт LLM неограниченное выполнение Python. Модель создаёт типизированный ShotSpec; FaceLink проверяет его, компилирует в небольшой белый список операций патча, подготавливает читаемый человеком обзор в Blender и изменяет сцену только после того, как художник нажмёт Apply Staged Patch.

Демо

Это четырёхсекундное демо отрендерено из прилагаемой редактируемой сцены .blend. Движение было применено через реальный исполнитель патчей FaceLink и остаётся 24 обычными редактируемыми значениями ключевых кадров — а не сгенерированным видео, запечённым вне Blender.

Related MCP server: blender-mcp

Текущий MVP

• сканирует открытую сцену Blender и присваивает объектам стабильные идентификаторы FaceLink;

• компилирует биты move_to, turn_to, look_at, wait и play_clip;

• создаёт/обновляет редактируемые трансформации, ключевые кадры, камеры и ограничения отслеживания;

• планирует трансформации в мировом пространстве и преобразует их для родительских объектов Blender;

• предоставляет рабочий процесс через MCP-сервер для MCP-клиентов, совместимых с Codex/ChatGPT;

• поддерживает планирование с помощью OpenAI API-ключа со Structured Outputs;

• запускает локальный мост с аутентификацией только для localhost между MCP-процессом и Blender;

• поддерживает на стороне Blender этапы stage/review/apply/discard, постоянную историю аудита и безопасный откат к выбранной ревизии текущей сессии.

• отклоняет внутренне перекрывающиеся таймлайны трансформаций/действий, предупреждает перед перезаписью существующих ключевых кадров и отклоняет конфликтующие NLA-клипы FaceLink;

• предпросматривает подготовленные пути движения в мировом пространстве и прогнозируемые фрустумы камеры непосредственно в вьюпорте Blender без создания датаблоков сцены;

• сканирует явно отмеченные навигационные сетки и препятствия, планирует детерминированные многосегментные пути передвижения и предупреждает, когда заметённые границы актёра пересекают отмеченное препятствие;

• снимает отпечаток полного навигационного окружения, так что новое препятствие или изменённая навигационная сетка делает уже подготовленный план недействительным;

• инвентаризирует иерархии костей арматуры и редактируемые Actions Blender, включая каналы поз-костей, ориентации покоя, диапазоны кадров и детерминированные отпечатки содержимого;

• предлагает карты костей только для просмотра с использованием детерминированной нормализации имён, затем измеряет сопоставленную иерархию, локальные оси покоя и нормализованные по масштабу пропорции костей перед выполнением;

• копирует совместимые Actions через открытый профиль карты костей rename_only, переписывает редактируемые пути FCurve, помещает результат в NLA и удаляет созданные копии при откате;

• сэмплирует проверенные профили bake_pose в обычные редактируемые целевые Actions, исправляя различные локальные оси покоя и масштаб костей с явной политикой корневого движения и ограниченной работой;

• оценивает существующие самодостаточные ограничения и драйверы исходного рига с помощью bake_evaluated_pose, затем запекает финальную позу деформационных костей в обычный редактируемый Action;

• опционально переносит корневое движение объекта Armature как относительную дельту, сохраняющую размещение, с переводом в единицах источника или с поправкой на масштаб рига;

• предсказывает подготовленный кадр камеры без создания датаблоков сцены, измеряя размер цели, смещение центра, соответствие безопасной зоне, обрезку и окклюзию центральной точки до применения художником;

• отклоняет подготовленный план, когда ссылочная трансформация, родительская связь, блокировка или значение тайминга сцены изменились после сканирования сцены.

Поддерживаемые версии Blender

• Основная: Blender 4.5 LTS (протестировано с 4.5.12)

• Минимальная: Blender 4.2 LTS

• По возможности: Blender 5.x

Установка Blender 4.0.2, найденная на машине разработки, предшествует базовой линии расширений. Исходный код FaceLink всё ещё можно загрузить там для смоук-тестирования, но 4.0 не является заявленной поддерживаемой версией.

Установка альфа-релиза

Скачайте FaceLink-Setup-0.3.8.exe со страницы релиза FaceLink 0.3.8 Alpha, откройте его, выберите Check setup, затем Install FaceLink.

Этот альфа-EXE ещё не подписан кодом, поэтому Windows SmartScreen может показать предупреждение о неизвестном издателе. Проверьте его по SHA256SUMS.txt релиза перед выбором More info → Run anyway и используйте только файлы, загруженные с официальной страницы релиза FaceLink.

FaceLink не включает Blender. Он обнаруживает существующую официальную установку Blender 4.2 или новее, что сохраняет размер релиза небольшим и позволяет каждому художнику выбрать Blender 4.5 LTS или более новую совместимую версию. Если Blender отсутствует, установите его с официальной страницы Blender LTS.

Графический установщик содержит хост FaceLink, расширение, манифест контрольных сумм и безопасный бэкенд PowerShell в одном небольшом EXE. Он проверяет встроенные файлы, обнаруживает Python и Blender, устанавливает оба компонента FaceLink и безопасно настраивает общий локальный файл MCP для ChatGPT Desktop/Codex. Он не запрашивает права администратора и не хранит API-ключ.

Для ручной установки в Windows храните четыре сырых файла релиза вместе и запустите:

.\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, чтобы проверить все разрешённые пути без установки чего-либо. Передайте -BlenderExe C:\path\to\blender.exe, когда Blender портативный или не находится по обычному пути. Передайте -SkipMcpConfiguration, чтобы оставить локальную конфигурацию MCP нетронутой. Для существующего расширения FaceLink обновите его из настроек Blender или удалите старую версию перед запуском шага установки расширения.

После запуска моста FaceLink в Blender проверьте полную настройку:

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

Диагностика никогда не печатает API-ключи или токен носителя моста Blender. Отсутствующий API-ключ — это только предупреждение, потому что MCP-клиент может использовать свою собственную модель.

Чтобы установить два компонента вручную, продолжите ниже.

В Blender 4.2 или новее откройте Edit → Preferences → Get Extensions → Install from Disk, выберите facelink-0.3.8.zip, включите FaceLink, откройте вкладку FaceLink на боковой панели 3D Viewport и нажмите 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-клиента и безопасного рабочего процесса stage/review/apply.

Установка для разработки

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

Для воспроизводимой матрицы приёмки с несколькими версиями, включая реальную установку расширения:

./scripts/run_acceptance.ps1

Харнесс записывает JUnit, покрытие, JSON для каждого Blender и журналы команд в artifacts/. См. 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 и откройте вкладку FaceLink на боковой панели 3D Viewport. Нажмите 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 desktop, Codex CLI и расширение Codex IDE используют эту локальную конфигурацию. 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, спланируйте, скомпилируйте и подготовьте результат одной командой:

$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) и root_motion (scale, preserve или drop). FaceLink сэмплирует собственный диапазон кадров исходного Action, записывает обычные ключи location/rotation/scale в нормальный целевой Action и помещает его в тот же редактируемый NLA-рабочий процесс. Каналы Action на уровне объекта опускаются, если object_motion не указан явно; в противном случае корневое движение должно быть на сопоставленной корневой поз-кости. Этот первый адаптер требует эквивалентной сопоставленной родительской иерархии и несвязанных исходных/целевых деформационных костей. См. profiles/mixamo_to_facelink_compact_bake.json и examples/baked_retargeted_clip_shot.json.

Когда исходный Action анимирует контрольные кости или пользовательские свойства, а исходные деформационные кости получают своё финальное движение через ограничения/драйверы, используйте adapter: "bake_evaluated_pose". Проверенная bone_map сопоставляет исходные деформационные кости — не каналы контроллера — с целевыми деформационными костями. Версия 1 допускает только зависимости от того же объекта/данных исходной арматуры, отклоняет внешние вспомогательные объекты и переменные, управляемые сценой, и по-прежнему требует эквивалентной сопоставленной родительской иерархии плюс несвязанные/неуправляемые целевые кости. Она не обнаруживает контроллеры и не конвертирует системы IK/FK автоматически. См. profiles/controller_to_deform_evaluated_bake.json и examples/evaluated_retargeted_clip_shot.json.

Если общее движение объекта хранится на исходном объекте Armature, добавьте object_motion: "preserve" или "scale" в любой из bake-адаптеров. FaceLink использует трансформ исходного объекта относительно его первого сэмплированного кадра, применяет эту дельту после текущего мирового трансформа целевого объекта и записывает обычные FCurves положения/поворота/масштаба объекта в тот же сгенерированный 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. Исполняемые снапшоты отката намеренно остаются только в рамках сессии, поскольку содержат живые ссылки на datablock'и Blender. Откат более старой ревизии также откатывает все более новые ревизии FaceLink для сохранения линейного состояния сцены.

API-ключ необязателен, когда MCP-клиент сам выполняет планирование на основе языковой модели. Подписки ChatGPT и биллинг OpenAI API раздельны; членство в ChatGPT не является API-ключом. См. docs/ARCHITECTURE.md о границе доверия.

Рабочий процесс навигации

Выберите проходимый меш и используйте FaceLink → Navigation → Navmesh. Выберите стены, реквизит или другие блокирующие объекты и отметьте их как Obstacle. Бит move_to по умолчанию сохраняет прямую линию прежнего поведения; установите path_mode в navmesh, чтобы маршрут проходил через соединённые навигационные треугольники. Компилятор распределяет обычные редактируемые keyframe'ы положения по дистанции пути и принудительно задаёт линейную интерполяцию, чтобы изогнутые ручки не выходили за пределы проходимого коридора.

Навигация намеренно явная. FaceLink не угадывает по именам объектов и не молча считает каждый меш препятствием. Текущее планирование v0.3.0 проецируется на XY и предназначено для одноуровневых previs-этажей; многоуровневые этажи, живые движущиеся препятствия и маршрутизация толпы пока не поддерживаются. См. examples/navmesh_walk_shot.json.

Предварительная проверка композиции камеры

Кадры камеры с целью проверяются на этапе staging. FaceLink проецирует мировые границы цели в предсказанный кадр камеры и сообщает об обрезке, небезопасных полях, размере объекта и смещении центра. Read-only рейкаст 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 — это альфа для рецензирования создателями, а не готовая анимационная система. Она выполняет ограниченный pose-baking с учётом трансформов для проверенных маппингов и может оценивать существующие ограничения и драйверы, когда все зависимости остаются на явном исходном арматуре. Она также может переносить движение объектов Armature без родительских связей и ограничений, не сдвигая начальное размещение цели. Она не выводит контроллеры, не переводит системы IK/FK, не следует за внешними вспомогательными объектами, не решает разные иерархии родительских связей в маппинге, не обрабатывает корни объектов с родителями/ограничениями, не синтезирует отсутствующее движение и не оценивает визуальный результат. Многоуровневая навигация, многошотовая последовательность и визуальные diff-оверлеи остаются последующей работой.

Релиз для Windows теперь имеет однократный графический установщик, безопасную локальную конфигурацию MCP, безопасный для секретов environment doctor и воспроизводимую демонстрацию на реальном Blender. Прежде чем продвигать эту альфу шире, протестируйте установку с пользователями-неразработчиками и завершите покрытие установки для Linux/macOS.

Лицензия

FaceLink — свободное программное обеспечение, распространяемое под GNU GPL версии 3 или любой более поздней версией. Дистрибутив расширения Blender включает тот же текст лицензии.