> ## Documentation Index
> Fetch the complete documentation index at: https://docs.almond.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# motion.build / motion.list

> Build reference motions from recorded sessions — teleoperated or hand-guided.

Reference motions are uniform-rate, both-arm joint trajectories stored on the robot in `~/.almond/motions/`, so the same motion can be replayed on that robot again and again and the tracking metrics compared 1:1 with [`tune.motion`](/cli/tune-motion). Build one from a recording here, or generate one ([`motion.chirp`](/cli/tune-tf), `scripts/creep_motions.py`). A few are built in — generated in code, the same on every robot, no file needed: `slow_osc` (the slow-motion acceptance test), `fast_swing` (large fast swings), each with a `_left` mirror, and `hold` (40 s still). A file of the same name in `~/.almond/motions/` overrides a built-in.

`motion.build` postprocesses a flight-recorder capture into one, from either recorder:

* **Teleop** (`axol teleop --teleop.record PREFIX`): the final guarded command stream (`_cmd` stage), clipped to the engaged span.
* **Gravity comp** (`axol gravity-comp --record PREFIX`): the measured arm-joint positions of the hand-guided session (`_gc` stage). There is no engage state, so the still lead-in/lead-out is trimmed instead — start and end the demonstration with the arms briefly at rest.

Either way, the stream is resampled onto a uniform grid, zero-phase low-pass smoothed (keeping the operator's intent, dropping hand tremor and network jitter), and projected waypoint-by-waypoint through the same collision-aware solver the teleop return-to-rest uses — the stored motion is joint-limit- and self-collision-safe by construction.

| Flag | Description |
| - | - |
| `prefix` | Flight-recorder prefix from `axol teleop --teleop.record PREFIX` (reads `<prefix>_cmd.npz`, and `<prefix>_ik.npz` for the engaged-span clip) or `axol gravity-comp --record PREFIX` (reads `<prefix>_gc.npz`). A bare name (no `/`) resolves in the recordings directory `~/.almond/recordings/` — where bare recording names are written. **Optional**: omitted, the newest recording in that directory is used |
| `--name NAME` | Motion name; written to `~/.almond/motions/<name>.npz`. **Optional**: defaults to the recording's name |
| `--out PATH` | Write to an explicit path instead of `~/.almond/motions/` |
| `--rate HZ` | Uniform playback rate (default: 240 — the production control rate; `tune.motion` replays at the motion's stored rate) |
| `--cutoff HZ` | Zero-phase low-pass cutoff (default: 6.0 — keeps deliberate motion, drops hand tremor and network jitter) |
| `--time-scale X` | Stretch playback time (2.0 = half speed; default: 1.0) |
| `--no-project` | Skip the collision-aware waypoint projection |
| `--notes TEXT` | Free-form provenance note stored in the motion metadata |

```bash theme={null}
axol teleop --teleop.record rec1          # record via teleop, or ...
axol gravity-comp --record rec1           # ... by hand-guiding the arms
axol motion.build                                # newest recording, named after it
axol motion.build rec1 --name reach-slow --time-scale 2.0
axol motion.list                                 # the built-ins and ~/.almond/motions
```

Every build also saves a **before/after tuning-run artifact** (`kind=build`, `~/.almond/diagnostics/tuning/`): the clipped raw command recording and the built motion side by side per joint, with per-joint change RMS/max and peak velocities. The diagnostics dashboard charts it like any other tuning run (zoom / fullscreen), so the effect of the smoothing pass and the collision projection is directly visible before the motion is ever replayed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.