Exporters¶

Serialise a FaceTrack to the native JSON/CSV track format, to game-engine animation assets (Unity .anim, Live2D Cubism motion3.json, Godot .tres), to stepped 2D cue lists (Rhubarb, Moho/OpenToonz, Papagayo), and to the experimental Bethesda Skyrim .lip writer plus its .fuz/.lip header tools.

`openfacefx.io_export` ¶

Exporters. Keep formats simple and engine-agnostic.

to_dict / write_json -- canonical interchange format.
write_csv -- one row per keyframe (time, channel, value), easy to load into a spreadsheet or a DAW-style curve editor.

Engine-specific exporters (Unreal AnimCurve, glTF morph-target animation, Blender F-curves) can be layered on top of FaceTrack without touching the solver.

`to_dict(track: FaceTrack) -> Dict` ¶

Source code in src/openfacefx/io_export.py

def to_dict(track: FaceTrack) -> Dict:
    d = {
        "format": "openfacefx.track",
        "version": 1,
        "fps": track.fps,
        "duration": round(track.duration, 4),
        "viseme_set": track.target_set if track.target_set is not None else VISEMES,
        "channels": [
            {
                "name": ch.name,
                "keys": [[round(k.time, 4), k.value] for k in ch.keys],
            }
            for ch in track.channels
        ],
    }
    # Additive event/take layer (issue #6): appended ONLY when present, and after
    # the base keys, so `version` stays 1 and an ordinary track serialises
    # byte-identically to previous releases. Readers ignore unknown top-level
    # keys, so this is forward-compatible in both directions.
    if getattr(track, "events", None):
        from .events import event_to_dict
        d["events"] = [event_to_dict(e) for e in track.events]
    if getattr(track, "variants", None) is not None:
        from .events import variants_to_dict
        d["variants"] = variants_to_dict(track.variants)
    return d

`write_json(track: FaceTrack, path: str) -> None` ¶

Source code in src/openfacefx/io_export.py

def write_json(track: FaceTrack, path: str) -> None:
    with open(path, "w", encoding="utf-8") as fh:
        json.dump(to_dict(track), fh, indent=2)

`write_csv(track: FaceTrack, path: str) -> None` ¶

Source code in src/openfacefx/io_export.py

def write_csv(track: FaceTrack, path: str) -> None:
    rows = ["time,channel,value"]
    for ch in track.channels:
        for k in ch.keys:
            rows.append(f"{k.time:.4f},{ch.name},{k.value:.4f}")
    with open(path, "w", encoding="utf-8") as fh:
        fh.write("\n".join(rows) + "\n")

`openfacefx.export_unity` ¶

Export a FaceTrack as a Unity .anim AnimationClip (text YAML).

The clip animates blendShape.<name> float curves on a SkinnedMeshRenderer (classID 137), so it plays through any Animator on any blendshape rig — no extra packages needed. Two naming presets cover the common conventions:

oculus -- viseme_sil .. viseme_U (Meta reference rigs, Ready Player Me; mixed case, I/O/U spelling)
vrchat -- vrc.v_sil .. vrc.v_ou (VRChat auto-detect names; lowercase, ih/oh/ou spelling)

Unity blendshape weights are 0-100 (percent), so track weights (0-1) are scaled by 100. Keyframe times are absolute seconds; the sparse RDP-reduced keys map 1:1 onto clip keys. Format derived from Unity's serialized AnimationClip (serializedVersion 6) as emitted by working generators — see docs/COMPATIBILITY.md for provenance.

`DEFAULT_EVENT_FUNC = 'OnFaceEvent'` `module-attribute` ¶

`NAMING_PRESETS: Dict[str, Dict[str, str]] = {'oculus': {v: ('viseme_' + v) for v in VISEMES}, 'vrchat': {v: ('vrc.v_' + _VRCHAT_SUFFIX.get(v, v).lower()) for v in VISEMES}}` `module-attribute` ¶

`write_unity_anim(track: FaceTrack, path: str, naming: str = 'oculus', mesh_path: str = 'Body', clip_name: Optional[str] = None, sample_rate: int = 60, loop: bool = False, include_all_visemes: bool = True, names: Optional[Dict[str, str]] = None, events: bool = True, event_func_map: Optional[Dict[str, str]] = None, event_message_options: int = 1) -> None` ¶

Write track as a Unity AnimationClip.

mesh_path is the transform path from the Animator's GameObject to the SkinnedMeshRenderer's (empty string if they are the same object). include_all_visemes also emits a constant-0 curve for every viseme the track never fires, so stale weights from a previous clip are cleared. names overrides the preset with an explicit viseme -> blendshape map.

The optional event layer (issue #6) fills the clip's m_Events array: each resolved :class:~openfacefx.events.Event becomes an AnimationEvent that Unity SendMessage-invokes on the Animator's GameObject. event_func_map maps event type -> handler method name (default OnFaceEvent for all); the event name and its JSON payload ride in the single stringParameter as name|{json}. event_message_options defaults to 1 (DontRequireReceiver) so a clip with no handler wired up does not error at runtime. Set events=False to omit them. A track with no events writes a byte-identical m_Events: [] -- exactly as before this feature.

Source code in src/openfacefx/export_unity.py

def write_unity_anim(
    track: FaceTrack,
    path: str,
    naming: str = "oculus",
    mesh_path: str = "Body",
    clip_name: Optional[str] = None,
    sample_rate: int = 60,
    loop: bool = False,
    include_all_visemes: bool = True,
    names: Optional[Dict[str, str]] = None,
    events: bool = True,
    event_func_map: Optional[Dict[str, str]] = None,
    event_message_options: int = 1,
) -> None:
    """Write ``track`` as a Unity AnimationClip.

    ``mesh_path`` is the transform path from the Animator's GameObject to the
    SkinnedMeshRenderer's (empty string if they are the same object).
    ``include_all_visemes`` also emits a constant-0 curve for every viseme the
    track never fires, so stale weights from a previous clip are cleared.
    ``names`` overrides the preset with an explicit viseme -> blendshape map.

    The optional event layer (issue #6) fills the clip's ``m_Events`` array: each
    resolved :class:`~openfacefx.events.Event` becomes an ``AnimationEvent`` that
    Unity SendMessage-invokes on the Animator's GameObject. ``event_func_map``
    maps event ``type`` -> handler method name (default ``OnFaceEvent`` for all);
    the event ``name`` and its JSON payload ride in the single ``stringParameter``
    as ``name|{json}``. ``event_message_options`` defaults to ``1``
    (``DontRequireReceiver``) so a clip with no handler wired up does not error at
    runtime. Set ``events=False`` to omit them. A track with no events writes a
    byte-identical ``m_Events: []`` -- exactly as before this feature.
    """
    if names is None:
        try:
            names = NAMING_PRESETS[naming]
        except KeyError:
            raise ValueError(
                f"unknown naming preset {naming!r}; use one of "
                f"{sorted(NAMING_PRESETS)} or pass names=") from None

    by_name = {c.name: c for c in track.channels}
    blocks = []
    for viseme in VISEMES:
        ch = by_name.get(viseme)
        if ch is not None and ch.keys:
            keys = [(k.time, k.value * 100.0) for k in ch.keys]
        elif include_all_visemes and viseme in names:
            keys = [(0.0, 0.0)]
        else:
            continue
        blocks.append(_curve_block(names[viseme], mesh_path, keys))

    float_curves = "".join(blocks).rstrip("\n") if blocks else "  []"
    m_events = _events_yaml(track, event_func_map, event_message_options) \
        if events else " []"
    body = _HEADER.format(
        name=clip_name or "OpenFaceFX_Lipsync",
        float_curves=float_curves,
        editor_curves=float_curves,   # duplicated so the clip is editable
        sample_rate=sample_rate,
        stop_time=_num(track.duration),
        loop=1 if loop else 0,
        m_events=m_events,
    )
    with open(path, "w", encoding="utf-8", newline="\n") as fh:
        fh.write(body)

`openfacefx.export_live2d` ¶

Export a FaceTrack as a Live2D Cubism motion3.json.

Cubism runtimes play lip-sync as parameter curves baked into a motion3.json; a model's model3.json declares a Groups: LipSync list so those curves retarget onto whatever parameter Ids a given rig exposes (https://docs.live2d.com/en/cubism-sdk-manual/lipsync/). The editor's own audio pipeline is volume-only, so phoneme-accurate curves are a quality upgrade.

Two targeting modes:

Default (zero config) -- collapse the whole viseme track to a single ParamMouthOpenY curve: the summed weight of every non-silence viseme, clamped to 0..1. That is an openness/loudness proxy (it equals 1 - sil on normalised coarticulation output) and matches the one mouth-open parameter almost every Cubism model exposes. The target Id is configurable (ParamMouthOpenY is the Cubism default, not a hard requirement).
Per-parameter -- pass a viseme -> ParamId map (e.g. the ParamA/I/U/ E/O convention some VTuber rigs use, which is not a standard) and get one curve per distinct parameter.

Both modes are just a :func:retarget -- summed, clamped contributions on the union of key times -- so the writer only ever serialises a track whose channel names are already Cubism parameter Ids.

Curves use linear segments only (segment id 0): a leading (t, v) point, then one (t, v) point per following keyframe. The Meta counts MUST equal what the Curves array actually contains -- Cubism loaders trust them and walk past the data otherwise -- so they are derived from the emitted segments, never guessed.

`DEFAULT_MOUTH_PARAM = 'ParamMouthOpenY'` `module-attribute` ¶

`lipsync_param_ids(model3_path: str) -> List[str]` ¶

The parameter Ids of a model3.json's Groups: LipSync entry.

Cubism models list the parameters driven by lip-sync here, so pointing the exporter at a model auto-discovers its mouth parameter(s). Returns [] when the file has no LipSync group.

Source code in src/openfacefx/export_live2d.py

def lipsync_param_ids(model3_path: str) -> List[str]:
    """The parameter Ids of a ``model3.json``'s ``Groups: LipSync`` entry.

    Cubism models list the parameters driven by lip-sync here, so pointing the
    exporter at a model auto-discovers its mouth parameter(s). Returns ``[]``
    when the file has no LipSync group.
    """
    with open(model3_path, encoding="utf-8") as fh:
        data = json.load(fh)
    for group in data.get("Groups", []):
        if group.get("Name") == "LipSync":
            return list(group.get("Ids", []))
    return []

`write_live2d_motion(track: FaceTrack, path: str, *, params: Optional[Dict[str, str]] = None, mouth_param: str = DEFAULT_MOUTH_PARAM, fps: Optional[float] = None, loop: bool = False) -> None` ¶

Write track as a Cubism motion3.json (Version 3).

params (viseme -> ParamId) selects per-parameter mode; the default None collapses to a single mouth_param curve. fps overrides the track's own rate in the Meta block (Cubism plays the curves by time regardless). Output is pure-stdlib JSON with LF line endings; the Meta counts are computed from the emitted Curves so they cannot drift.

Source code in src/openfacefx/export_live2d.py

def write_live2d_motion(
    track: FaceTrack,
    path: str,
    *,
    params: Optional[Dict[str, str]] = None,
    mouth_param: str = DEFAULT_MOUTH_PARAM,
    fps: Optional[float] = None,
    loop: bool = False,
) -> None:
    """Write ``track`` as a Cubism ``motion3.json`` (Version 3).

    ``params`` (``viseme -> ParamId``) selects per-parameter mode; the default
    ``None`` collapses to a single ``mouth_param`` curve. ``fps`` overrides the
    track's own rate in the ``Meta`` block (Cubism plays the curves by time
    regardless). Output is pure-stdlib JSON with LF line endings; the ``Meta``
    counts are computed from the emitted ``Curves`` so they cannot drift.
    """
    mapping = _collapse_mapping(params, mouth_param)
    baked = retarget(track, mapping)

    curves = []
    total_segments = total_points = 0
    duration = 0.0
    for ch in baked.channels:
        if not ch.keys:
            continue
        seg = _segments(ch.keys)
        n_seg, n_pt = _count(seg)
        total_segments += n_seg
        total_points += n_pt
        duration = max(duration, ch.keys[-1].time)
        curves.append((ch.name, seg))

    rate = track.fps if fps is None else fps
    lines = [
        "{",
        '  "Version": 3,',
        '  "Meta": {',
        f'    "Duration": {_num(duration)},',
        f'    "Fps": {_num(rate)},',
        f'    "Loop": {"true" if loop else "false"},',
        '    "AreBeziersRestricted": true,',
        f'    "CurveCount": {len(curves)},',
        f'    "TotalSegmentCount": {total_segments},',
        f'    "TotalPointCount": {total_points},',
        '    "UserDataCount": 0,',
        '    "TotalUserDataSize": 0',
        "  },",
        '  "Curves": [',
    ]
    last = len(curves) - 1
    for i, (name, seg) in enumerate(curves):
        comma = "" if i == last else ","
        lines += [
            "    {",
            '      "Target": "Parameter",',
            f'      "Id": {json.dumps(name)},',
            f'      "Segments": {json.dumps(seg)}',
            "    }" + comma,
        ]
    lines += ["  ]", "}"]
    with open(path, "w", encoding="utf-8", newline="\n") as fh:
        fh.write("\n".join(lines) + "\n")

`openfacefx.export_godot` ¶

Export a FaceTrack as a Godot 4 Animation text resource (.tres).

Godot has no first-party lip-sync; the community bakes mouth data into AnimationPlayer animations (rhubarb-lipsync integrations, godot-baked- lipsync). This writes that artifact directly: a [gd_resource type="Animation" format=3] resource (format=3 is Godot 4; 2 is Godot 3) with one value track per active viseme, keyed with the existing RDP-reduced keyframes and linear interpolation.

Each track drives a blend shape by node path, e.g.::

tracks/0/path = NodePath("Head:blend_shapes/viseme_aa")

so it plays through any MeshInstance3D whose mesh exposes those shape keys. Godot blend-shape weights are 0..1 (unlike Unity's 0..100), so channel values are written straight through. Shape naming reuses the Unity exporter's presets (oculus viseme_* / vrchat vrc.v_*); pass names for a custom viseme -> shape map. The node name is configurable (default Head).

A consumer loads the resource into an AnimationLibrary and adds it to an AnimationPlayer whose root_node makes the paths resolve; those runtime nodes stay engine-side and out of scope here. Value tracks (not the importer- only blend_shape track type) keep the resource hand-writable and stdlib- serialisable. Text output, LF line endings.

`write_godot_anim(track: FaceTrack, path: str, *, naming: str = 'oculus', node: str = 'Head', names: Optional[Dict[str, str]] = None, include_all_visemes: bool = True) -> None` ¶

Write track as a Godot 4 Animation .tres.

node is the animated node's name relative to the AnimationPlayer's root_node (the blend shapes live at <node>:blend_shapes/<shape>). naming picks a built-in shape-name preset; names overrides it with an explicit viseme -> shape map. include_all_visemes also writes a constant-0 track for every viseme the track never fires, clearing any weight a previous animation left on that shape.

Track key times are absolute seconds, so the source fps does not appear in the resource. The [resource] header follows Godot's text saver, which omits any property left at its class default -- loop_mode (0), step (1/30) and resource_name (empty for animations) never appear, and length only when it is not the 1.0 default -- so the output matches what the editor would re-save.

Source code in src/openfacefx/export_godot.py

def write_godot_anim(
    track: FaceTrack,
    path: str,
    *,
    naming: str = "oculus",
    node: str = "Head",
    names: Optional[Dict[str, str]] = None,
    include_all_visemes: bool = True,
) -> None:
    """Write ``track`` as a Godot 4 ``Animation`` ``.tres``.

    ``node`` is the animated node's name relative to the AnimationPlayer's
    ``root_node`` (the blend shapes live at ``<node>:blend_shapes/<shape>``).
    ``naming`` picks a built-in shape-name preset; ``names`` overrides it with
    an explicit ``viseme -> shape`` map. ``include_all_visemes`` also writes a
    constant-0 track for every viseme the track never fires, clearing any weight
    a previous animation left on that shape.

    Track key times are absolute seconds, so the source fps does not appear in
    the resource. The ``[resource]`` header follows Godot's text saver, which
    omits any property left at its class default -- ``loop_mode`` (0),
    ``step`` (1/30) and ``resource_name`` (empty for animations) never appear,
    and ``length`` only when it is not the 1.0 default -- so the output matches
    what the editor would re-save.
    """
    if names is None:
        try:
            names = NAMING_PRESETS[naming]
        except KeyError:
            raise ValueError(
                f"unknown naming preset {naming!r}; use one of "
                f"{sorted(NAMING_PRESETS)} or pass names=") from None

    by_name = {c.name: c for c in track.channels}
    tracks = []
    for viseme in VISEMES:
        ch = by_name.get(viseme)
        if ch is not None and ch.keys:
            times = [k.time for k in ch.keys]
            values = [k.value for k in ch.keys]
        elif include_all_visemes and viseme in names:
            times, values = [0.0], [0.0]
        else:
            continue
        tracks.append((names[viseme], times, values))

    header = '[gd_resource type="Animation" format=3]\n\n[resource]\n'
    if track.duration != 1.0:                       # 1.0 is Animation's default
        header += f"length = {_fnum(track.duration)}\n"
    blocks = [
        _track_block(i, f"{node}:blend_shapes/{shape}", times, values)
        for i, (shape, times, values) in enumerate(tracks)
    ]
    with open(path, "w", encoding="utf-8", newline="\n") as fh:
        fh.write(header + "".join(blocks))

`openfacefx.export_cues` ¶

Rhubarb-dialect cue exporters: stepped mouth-shape lists for 2D hosts.

The engine-agnostic FaceTrack is a bundle of smooth, overlapping viseme curves. A whole ecosystem of indie 2D lip-sync hosts instead wants a stepped cue list -- one mouth shape held per interval. This module flattens a track to that representation (the single highest-weight channel wins at every sampled frame) and serialises it in the formats those hosts read:

Rhubarb Lip Sync TSV / XML / JSON -- write_rhubarb_{tsv,xml,json}
Moho / OpenToonz switch data (.dat) -- write_moho_dat
Papagayo-NG (.pgo) -- write_pgo

Shape vocabulary is handled for you: a track in the Oculus-15 viseme set is retargeted through the built-in rhubarb / preston_blair presets; a track already in Rhubarb A-H/X (or Preston-Blair) shapes is passed through untouched; anything else is rejected with a clear error. Times and frames are quantised exactly as the reference tools emit them -- Rhubarb prints seconds as %.2f; Moho/Papagayo frames are 1-based and truncated (1 + int(fps * seconds)). Pure stdlib serialisation, LF line endings.

`Cue = Tuple[float, float, str]` `module-attribute` ¶

`RHUBARB_EXTENDED_FALLBACK = {k: (v[0][0]) for k, v in (PRESET_FALLBACKS['rhubarb'].items())}` `module-attribute` ¶

`dominant_cues(track: FaceTrack, rest_name: str = 'X', silence_floor: float = _SILENCE_FLOOR) -> List[Cue]` ¶

Flatten track to (start, end, shape) runs by dominant channel.

At each frame (sampled at the track's own fps) the single highest-weight channel wins; a frame with nothing above silence_floor becomes rest_name. Adjacent equal-shape frames merge into one run, and the runs tile [0, duration] with no gaps.