fn clip(&self) -> ClipHandle

Returns a ClipHandle bound to this box. The handle owns the append-sequence counter the box uses to spot a dropped append, so keep one handle for a clip session (top it up through that handle) rather than reopening one per append.

fn new() -> ClipBuilder

Each method appends one per-frame entry, so a builder is a timeline read top to bottom. Motion is a relative delta; an edge (button, key, or media) is an Action that stays held until a later frame changes it; a gap is N idle frames (the box NAKs, like an idle mouse). The methods take &mut self and return &mut Self, so chain them or push in a loop; clear() reuses the allocation.

press/release/force_release are wrappers over edge, which is a wrapper over frame. Reach for frame only when you need motion and edges (or several edges) on the same frame, e.g. moving while a button is held, which is how a faithful recording of "aim and hold fire" looks.

use medius::{ClipBuilder, Button, Key};

let mut clip = ClipBuilder::new();
for _ in 0..200 { clip.move_by(10, 0); }   // 200 box-timed frames of +10 dx
clip.press(Button::Left)                   // a click, held for 20 frames
    .gap(20)
    .release(Button::Left);
clip.press(Key::A)                         // then type 'a'
    .gap(3)
    .release(Key::A);

frame is the one builder call that fills more than a single field, so it's how a move and an edge share a frame: one entry, one wire report. Edges are sticky, so a hold is a press once then plain motion until the release.

use medius::{Action, Button, ClipBuilder};

let mut clip = ClipBuilder::new();

// move (+10, -4) AND press Left on the same frame
clip.frame(10, -4, 0, &[(Button::Left.into(), Action::Press)]);

// "aim and hold fire": press once, keep moving while held, then release
clip.frame(8, -2, 0, &[(Button::Left.into(), Action::Press)]);
for _ in 0..60 { clip.move_by(8, -2); }   // Left stays down (edges are sticky)
clip.frame(0, 0, 0, &[(Button::Left.into(), Action::SoftRelease)]);

From Device::clip(). Every method below is fire-and-forget: it queues a frame and returns. The auto-lock, loop, and retain settings and the trigger set are the clip's config; the engine verbs drive playback. query_status reads the ring depth and playback state, and query_config reads the config back.

A clip runs in one of two shapes, chosen by set_retain before the first append.

streaming (drain-and-discard)
    append ──▶ [ e4 e3 e2 ] ──▶ play ──▶ freed     (unbounded, top up forever)
                   box reclaims each entry once played; no replay

retained (keep-and-replay, up to 64 KiB)
    append ──▶ [ e0 e1 e2 e3 e4 ] ──▶ finalize ──▶ sealed
               base │──▶ play cursor ──▶ end
                    └──── start / loop rewinds to base ◀────┘

// Streaming: preload, play with auto-lock, then top up in real time, pacing against free.
use medius::{Blanket, ClipState};
use std::time::Duration;

let handle = device.clip();       // device: an open Device
handle.set_autolock(&[Blanket::Aim])?;   // lock only the aim axes while playing
handle.append(&clip)?;                    // preload (clip, next_chunk: ClipBuilders you built)
handle.start()?;

loop {
    let s = handle.query_status()?;
    if s.state == ClipState::Idle { break; }           // done, or stopped
    if s.free as usize > next_chunk.as_bytes().len() {
        handle.append(&next_chunk)?;                   // stream more while there's room
    }
    std::thread::sleep(Duration::from_millis(5));
}
handle.stop()?;

A ClipTrigger binds one Edge of a usage to one ClipAction, so the box drives playback itself with no host round-trip.

Bindings are a managed set keyed by (usage, edge), like a lock: bind adds or overwrites, unbind drops one, and clear_triggers wipes them. A physical edge runs the one most-specific match, so a binding on Key::F1 beats an any-key binding.

use medius::{Button, ClipAction, ClipTrigger, Edge, Key};

let clip = device.clip();
clip.set_retain(true)?;      // set the mode before loading
clip.append(&recording)?;
clip.finalize()?;            // close it so it can replay

// Hold-to-play: F1 down starts, F1 up stops. Consume F1 so the game never sees it.
clip.bind(ClipTrigger::new(Key::F1, Edge::Press, ClipAction::Start).consume())?;
clip.bind(ClipTrigger::new(Key::F1, Edge::Release, ClipAction::Stop).consume())?;

// Or one side-button that toggles play/stop:
clip.bind(ClipTrigger::new(Button::Side1, Edge::Press, ClipAction::Toggle))?;

AsyncDevice::clip() returns an AsyncClipHandle that keeps append, the settings, and the engine verbs synchronous (they just queue a frame), while query_status().await and query_config().await are futures like the other queries.

let device = Device::find()?.into_async();
let handle = device.clip();
handle.append(&clip)?;          // sync, no await
handle.start()?;                // sync
let s = handle.query_status().await?;   // the query awaits