fn clip(&self) -> ClipHandle

No round-trip

Returns a ClipHandle bound to this box. Keep one handle per clip session and top it up through it: the handle owns the append-sequence counter the box uses to spot a dropped append.

fn new() -> ClipBuilder

No round-trip

Each method appends one per-frame entry, so a builder is a timeline read top to bottom. Motion is a relative delta; an edge is an Action that stays held until a later frame changes it; a gap NAKs like an idle mouse.

They take &mut self and return &mut Self, so chain them or push in a loop; clear() reuses the allocation. press/release/force_release wrap edge, which wraps frame. Reach for frame only when motion and edges share one frame.

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 fills more than one field, so a move and an edge share one entry and one wire report.

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)]);

// 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. query_status reads the ring depth and playback state; 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 X and Y 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 runs one ClipAction on the box when a physical Edge fires, with no host round-trip.

Bindings are a managed set keyed by (usage, edge), like a lock. A physical edge runs the one most-specific match, so a binding on Key::F1 resolves before an any-key one.

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. The press binding's consume locks F1
// for the whole hold, so the release binding does not need one.
clip.bind(ClipTrigger::new(Key::F1, Edge::Press, ClipAction::Start).consume())?;
clip.bind(ClipTrigger::new(Key::F1, Edge::Release, ClipAction::Stop))?;

// 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; 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