Open and index a .motn or .moti file. Required before any other tool can operate on it. Returns a summary (canvas size, frame rate, duration, layer/text-layer/published-parameter counts).

List every layer in the template's layer tree (id, name, factory kind e.g. Text/Image/Emitter/Shape/Generator, nesting depth, locked).

List every Text-factory layer with its current on-screen string and the scenenode id needed by motion_set_text.

Inspect a parameter by slash-separated name path from a scenenode, e.g. "Object/Text" or "Style/Face/Color/Red". Returns its current value/default, whether it's keyframed, and child parameter names if it's a group rather than a leaf.

List every keypoint on an animated parameter's curve, in document order, with time (seconds) and value.

List every published (rig) parameter — the controls Final Cut Pro's Inspector shows when this template is used as an FCP title/generator/ effect.

Change the on-screen string of a Text-factory layer. Font, color, and behaviors are untouched — only the text content changes.

Set a leaf parameter's static value (e.g. "Object/Face/Opacity"). Refuses to touch an already-keyframed parameter unless force=True is passed explicitly, to avoid silently breaking an existing animation — use motion_add_keypoint for animated parameters instead.

Set RGB(A) on a color parameter group, e.g. "Style/Face/Color" for a Text layer's face color (values are Motion's native 0.0-1.0 range, though Motion permits >1.0 for over-bright colors).

Start animating a leaf parameter that has NEVER been keyframed in Motion — creates its from scratch, seeded with one keypoint, so you can author dynamic/procedural motion rather than only editing curves Motion already created. Grounded in a structural scan of real Motion documents: every keyframed leaf parameter observed (Position X/Y/Z, Scale, Angle, Opacity, RGB(A) channels, behavior Amounts, ...) uses the same universal scalar curve type — Motion animates compound properties like Position or Color by keyframing each numeric child parameter independently, so target one scalar channel at a time (e.g. "Style/Face/Color/Red", not "Style/Face/Color"). Refuses a parameter that's already keyframed (use motion_add_keyframe instead) or that's a group with its own child parameters rather than a bare value. default overrides the curve's rest value; it otherwise reuses the parameter's current static value/default.

Append a keypoint to a parameter that is ALREADY keyframed in Motion (has an existing with at least one keypoint). If the parameter has never been keyframed at all, call motion_create_keyframe_curve first to seed its curve, then use this tool for every keypoint after that.

Publish an internal parameter as a rig control visible in Final Cut Pro's Inspector when this template is used as an FCP title/generator/ effect. object_id and channel come from Motion's own object graph (e.g. object="10003" channel="./1/100/101" for a layer's Position) — inspect a similar existing published target with motion_list_rig on a template you know works to find the right values for your layer.

Remove a published (rig) parameter.

Write the open, modified document to output_path. Never overwrites the originally-opened file unless output_path is the same path — pass a new filename to keep the source template untouched.

Open a file in Motion.app for visual review — this server cannot render frames or drive Motion's UI itself, so final visual QC always happens by handing the file to the app this way.

Round-trip-check a file: re-parse it fresh from disk and confirm the root is a recognizable document. Useful right after motion_save_as to confirm the write didn't corrupt the XML.