ARKit to MetaHuman Documentation

Installation

How to install ARKit to MetaHuman?

The add-on supports Blender 3.3 or newer through a legacy add-on install. Blender 4.2 or newer can also install it as an extension.

Legacy install: open Edit > Preferences > Add-ons, click Install, choose the downloaded zip, and enable ARKit to MetaHuman.

Extension install: open Edit > Preferences > Get Extensions, click Install from Disk, choose the extension zip, and enable the add-on if it is not enabled automatically.

Quick Start

Rename a facial rig in a few steps.

Select the mesh or meshes with ARKit facial shape keys.
Open the 3D Viewport sidebar with N and choose the ARKit tab.
Choose the scope, then click Preview Renames and review the report.
Click Apply Renames.
Optional: click Save Report to write the last report to a text file.

Applying the operation twice is safe. Keys that already use their target name are reported as Already Renamed and are not changed again.

Scope & Options

What each setting does.

Active Mesh	Process only the active object.
Selected Meshes	Process every selected object. This is the default.
All Meshes	Process every object in the current view layer.
Update Animation & Drivers	Rewrite shape key F-curves, NLA strip actions and shape key drivers. Enabled by default.
Skip Missing Keys	Apply the available renames and report missing sources. Disable it to cancel the whole run when any mapping source is missing.

What Gets Changed

The operation is limited to shape key names and their references.

Matching source keys	Renamed to the mapped MetaHuman Live Link target.
Values, sliders, mute, vertex groups, relative keys	Preserved and snapshotted before the rename, then verified afterwards.
Key order	Preserved.
Current action and NLA actions	Shape key F-curve paths are rewritten to the new names.
Drivers on the shape key data-block	`key_blocks[...]` paths are rewritten.
Basis	Never renamed.
Unmapped keys	Left untouched and listed in the report.
Linked-library data	Reported as read-only and skipped.

Reading the Report

Every run writes a report to Text Editor > Text as ARKit2MH_report.

Renamed	The source key was renamed successfully.
Already Renamed	The target name already exists; no change was needed.
Missing Sources	The ARKit key is not present in that shape key data-block.
Conflicts	The target exists. The source is left untouched.
Unmapped Keys	Existing keys outside the mapping; they are not changed.
Read-Only Data	Linked-library shape keys that Blender does not allow editing.
Errors	Blender refused the rename or the post-rename verification failed.

Save Report exports the current report as a plain text file. The report also lists reference updates and warns when an action is shared by multiple data-blocks.

Conflicts & Missing Keys

How to resolve the two common blockers.

A conflict means the target name already exists on the same shape key data-block. Blender would normally append .001; this add-on refuses to do that. Rename or remove the existing target key, then run the rename again.

A missing source means the ARKit key was not found. With Skip Missing Keys enabled, the remaining available keys are renamed. A rig without a Neutral key reports that single missing entry and still renames the other matching keys.

Animation & Drivers

Keeping the rig connected after the rename.

With Update Animation & Drivers enabled, the add-on rewrites shape key paths in the active action and in actions used by NLA strips. It supports both legacy actions and layered actions. Drivers attached to the shape key data-block are rewritten as well.

If an action is shared by other data-blocks, the report warns about it. Object-level drivers that reference key_blocks[...] outside the shape key data-block are not rewritten and should be checked manually.

Built-in Mapping

52 ARKit pairs plus Neutral to Default. Targets are applied verbatim, including case.

ARKit source	MetaHuman Live Link target
`Neutral`	`Default`
`EyeBlinkLeft`	`ctrl_expressions_eyeblinkl`
`EyeLookDownLeft`	`ctrl_expressions_eyelookdownl`
`EyeLookOutLeft`	`ctrl_expressions_eyelookleftl`
`EyeLookInLeft`	`ctrl_expressions_eyelookrightl`
`EyeLookUpLeft`	`ctrl_expressions_eyelookupl`
`EyeSquintLeft`	`ctrl_expressions_eyesquintinnerl`
`EyeWideLeft`	`ctrl_expressions_eyewidenl`
`EyeBlinkRight`	`ctrl_expressions_eyeblinkr`
`EyeLookDownRight`	`ctrl_expressions_eyelookdownr`
`EyeLookInRight`	`ctrl_expressions_eyelookleftr`
`EyeLookOutRight`	`ctrl_expressions_eyelookrightr`
`EyeLookUpRight`	`ctrl_expressions_eyelookupr`
`EyeSquintRight`	`ctrl_expressions_eyesquintinnerr`
`EyeWideRight`	`ctrl_expressions_eyewidenr`
`JawForward`	`ctrl_expressions_jawfwd`
`JawLeft`	`ctrl_expressions_jawleft`
`JawRight`	`ctrl_expressions_jawright`
`JawOpen`	`ctrl_expressions_jawOpen`
`MouthClose`	`ctrl_expressions_mouthlipspurseul`
`MouthFunnel`	`ctrl_expressions_mouthfunnelul`
`MouthPucker`	`ctrl_expressions_mouthlipspurseur`
`MouthLeft`	`ctrl_expressions_mouthleft`
`MouthRight`	`ctrl_expressions_mouthright`
`MouthSmileLeft`	`ctrl_expressions_mouthcornerpulll`
`MouthSmileRight`	`ctrl_expressions_mouthcornerpullr`
`MouthFrownLeft`	`ctrl_expressions_mouthcornerdepressl`
`MouthFrownRight`	`ctrl_expressions_mouthcornerdepressr`
`MouthDimpleLeft`	`ctrl_expressions_mouthdimplel`
`MouthDimpleRight`	`ctrl_expressions_mouthdimpler`
`MouthStretchLeft`	`ctrl_expressions_mouthstretchl`
`MouthStretchRight`	`ctrl_expressions_mouthstretchr`
`MouthRollLower`	`ctrl_expressions_mouthlowerliprollinl`
`MouthRollUpper`	`ctrl_expressions_mouthupperliprollinl`
`MouthShrugLower`	`ctrl_expressions_jawchinraisedl`
`MouthShrugUpper`	`ctrl_expressions_jawchinraiseul`
`MouthPressLeft`	`ctrl_expressions_mouthpressdl`
`MouthPressRight`	`ctrl_expressions_mouthpressdr`
`MouthLowerDownLeft`	`ctrl_expressions_mouthlowerlipdepressl`
`MouthLowerDownRight`	`ctrl_expressions_mouthlowerlipdepressr`
`MouthUpperUpLeft`	`ctrl_expressions_mouthupperlipraisel`
`MouthUpperUpRight`	`ctrl_expressions_mouthupperlipraiser`
`BrowDownLeft`	`ctrl_expressions_browdownl`
`BrowDownRight`	`ctrl_expressions_browdownr`
`BrowInnerUp`	`ctrl_expressions_browlaterall`
`BrowOuterUpLeft`	`ctrl_expressions_browraiseouterl`
`BrowOuterUpRight`	`ctrl_expressions_browraiseouterr`
`CheekPuff`	`ctrl_expressions_mouthcheekblowl`
`CheekSquintLeft`	`ctrl_expressions_eyecheekraisel`
`CheekSquintRight`	`ctrl_expressions_eyecheekraiser`
`NoseSneerLeft`	`ctrl_expressions_nosewrinklel`
`NoseSneerRight`	`ctrl_expressions_nosewrinkler`
`TongueOut`	`ctrl_expressions_tongueout`

Several names look asymmetric on purpose and are not corrected: MouthClose and MouthPucker use the purse targets, BrowInnerUp maps to browlaterall, CheekPuff maps to mouthcheekblowl, and JawOpen keeps its mixed-case target. The eye In and Out targets also follow the supplied list.

Limitations

Scope of the add-on.

Only existing object shape keys are processed. The add-on does not create keys, edit mesh data, merge duplicates or change expressions. Pose bones and other rig controls are out of scope.

The mapping is built in and is not edited from the panel. Every install uses the same reviewed list so results stay consistent across machines.