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 서버를 통해 워크플로를 노출합니다.

• Structured Outputs를 사용한 OpenAI API 키 계획을 지원합니다.

• MCP 프로세스와 Blender 사이에 localhost 전용 인증 브리지를 실행합니다.

• Blender 측 스테이지/리뷰/적용/폐기, 영구 감사 기록 및 선택한 현재 세션 리비전으로의 안전한 롤백을 지원합니다.

• 내부적으로 겹치는 트랜스폼/액션 타임라인을 거부하고, 기존 키프레임을 덮어쓰기 전에 경고하며, 충돌하는 FaceLink NLA 클립을 거부합니다.

• 씬 데이터블록을 생성하지 않고 스테이징된 월드 공간 모션 경로와 예측 카메라 프러스텀을 Blender 뷰포트에서 직접 미리 봅니다.

• 명시적으로 표시된 내비게이션 메시와 장애물을 스캔하고, 결정적 다중 세그먼트 이동 경로를 계획하며, 배우의 스윕 경계가 표시된 장애물과 교차할 때 경고합니다.

• 전체 내비게이션 환경을 지문화하여 새로 추가된 장애물이나 편집된 내비게이션 메시가 이미 스테이징된 계획을 무효화합니다.

• 포즈 본 계층 구조와 편집 가능한 Blender Actions(포즈 본 채널, 휴지 방향, 프레임 범위 및 결정적 콘텐츠 지문 포함)를 인벤토리화합니다.

• 결정적 이름 정규화를 사용하여 리뷰 전용 본 매핑을 제안한 다음, 실행 전에 매핑된 계층 구조, 로컬 휴지 축 및 스케일 정규화된 본 비율을 측정합니다.

• 열린 rename_only 본 매핑 프로필을 통해 호환되는 Actions를 복사하고, 편집 가능한 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에서도 로드할 수 있지만, 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 백엔드가 하나의 작은 EXE에 포함되어 있습니다. 포함된 파일을 검증하고, Python과 Blender를 감지하고, 두 FaceLink 구성 요소를 설치하고, 공유 로컬 ChatGPT Desktop/Codex MCP 파일을 안전하게 구성합니다. 관리자 액세스를 요청하거나 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를 전달하세요. Blender가 휴대용이거나 일반적인 경로에 없는 경우 -BlenderExe C:\path\to\blender.exe를 전달하세요. 로컬 MCP 구성을 건드리지 않으려면 -SkipMcpConfiguration을 전달하세요. 기존 FaceLink 확장 프로그램이 있는 경우 Blender Preferences에서 업데이트하거나 확장 프로그램 설치 단계를 실행하기 전에 이전 버전을 제거하세요.

Blender에서 FaceLink의 브리지를 시작한 후 전체 설정을 검증하세요:

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를 활성화하고, 3D Viewport 사이드바의 FaceLink 탭을 열고 Start Bridge를 누르세요.

격리된 Python 3.11 이상 환경에 Python 호스트를 설치하세요:

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 Viewport 사이드바의 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 및 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의 기본 프레임 범위를 샘플링하고, 일반 대상 Action에 선형 위치/회전/스케일 키를 작성하며, 동일한 편집 가능한 NLA 워크플로에 배치합니다. object_motion이 명시적이지 않으면 오브젝트 수준 Action 채널은 생략됩니다. 그렇지 않으면 루트 모션은 매핑된 루트 포즈 본에 있어야 합니다. 이 첫 번째 어댑터는 동등한 매핑된 부모 계층 구조와 제약되지 않은 소스/대상 변형 본을 요구합니다. 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을 참조하세요.

If the overall character movement lives on the source Armature object, add
object_motion: "preserve" or "scale" to either bake adapter. FaceLink uses the source
object's transform relative to its first sampled frame, applies that delta after the target's
current world transform, and writes ordinary object location/rotation/scale FCurves into the
same generated Action. scale multiplies delta translation by the mapped-rig median length
ratio; preserve keeps source units. Version 1 requires unparented source/target Armatures with
no object constraints or driven target object transforms. See
profiles/object_motion_bake.json and
examples/object_motion_clip_shot.json.

Inspect or roll back FaceLink revisions from the command line:

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

Revision metadata is stored in the .blend file. Executable rollback snapshots intentionally
remain session-only because they contain live Blender datablock references. Rolling back to a
previous revision also rolls back every newer FaceLink revision to preserve a linear scene state.

An API key is optional when an MCP client performs the language-model planning itself.
ChatGPT subscriptions and OpenAI API billing are separate; a ChatGPT membership is not an
API key. See docs/ARCHITECTURE.md for the trust boundary.

Navigation workflow

Select a walkable mesh and use FaceLink → Navigation → Navmesh. Select walls, props or
other obstructing objects and mark them as Obstacle. A move_to beat keeps the legacy
straight line by default; set path_mode to navmesh to route through connected navigation
triangles. The compiler distributes ordinary editable location keyframes by path distance and
forces linear interpolation so curved handles do not leave the walkable corridor.

Navigation is deliberately explicit. FaceLink neither infers from object names nor silently
treats every mesh as an obstacle. Current v0.3.0 planning is projected onto XY and is intended
for single-level previs floors. Multi-level floors, live moving obstacles and crowd routing are
not yet supported. See examples/navmesh_walk_shot.json.

Camera composition preflight

Camera shots with a target are checked during staging.
FaceLink projects the target's world-space bounds into the predicted camera frame and reports
clipping, risky, subject size and center offset. A read-only Blender ray cast reports when another
object blocks the target center.
dolly_in checks both start and end positions. Thresholds are typed in
camera.composition, visible in the ShotSpec and can be disabled explicitly.
See examples/composition_checked_shot.json.

This is a deterministic preflight, not a visual quality score. It does not render anything,
does not use a vision model, does not evaluate lighting, and does not guarantee that every part
of a complex subject is unoccluded. Version 0.3.3 evaluates perspective cameras without an FOV
offset and reports other projection types as unsupported rather than returning misleading metrics
.

Repository map

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

Project status

Version 0.3.8 is a creator-review alpha, not yet a production animation system. It performs
bounded transform-aware pose baking for reviewed mappings and can evaluate existing constraints
and drivers when all dependencies remain on the source armature. It is also able to transfer
unparented, unconstrained Armature-object motion without moving the target's starting placement.
It cannot infer all controllers, translate IK/FK systems, follow external helper objects, solve
different parented hierarchies, handle parented or constrained object roots, continue generating
missing motion, or evaluate the final visual result. Multi-level navigation, sequencing,
and visual diff overlays remain follow-up work.

The Windows release now has a single-file, curated installer, safe local MCP configuration,
a secret-safe environment doctor, and a reproducible real Blender demo. Before promoting this
alpha widely, test installation with non-developers and complete Linux/macOS installation coverage.

License

FaceLink is free software licensed under the GNU GPL version 3 or any later version.
The Blender distribution also contains the full license text.