Clip

clipOpen a clip handle

fn clip(&self) -> ClipHandle

No round-trip

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

ClipBuilderBuild the entry stream

fn new() -> ClipBuilder

No round-trip

Each method appends one per-frame entry. 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, for chaining or a loop. clear() reuses the allocation, and byte_len() is the ring space the entries take. Each one-field call wraps 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 emitted report.

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

let mut clip = ClipBuilder::new();

// move (+10, -4) AND press Left on the same frame
clip.frame(ClipFrame::new().move_by(10, -4).press(Button::LEFT));

// press once, keep moving while held, then release
clip.frame(ClipFrame::new().move_by(8, -2).press(Button::LEFT));
for _ in 0..60 { clip.move_by(8, -2); }   // Left stays down (edges are sticky)
clip.release(Button::LEFT);

ClipFrameBuild one multi-field frame

fn new() -> ClipFrame

No round-trip

One frame carries any mix of motion, edges, raw reports, and control transfers, ≤512 encoded bytes (CLIP_ENTRY_MAX). Each method takes self and returns the frame.

use medius::{Button, ClipBuilder, ClipFrame, Direction, Setup};

let mut clip = ClipBuilder::new();
clip.frame(
    ClipFrame::new()
        .move_by(4, -2)
        .press(Button::LEFT)
        .raw(2, Direction::OUT, [0x10, 0xFF, 0x05])
        .transfer(0, Setup::new(0x21, 0x09, 0x0300, 0, 2), [0x04, 0x01]),
);
device.clip().append(&clip)?;

ClipHandleFill the ring, configure, and drive playback

From Device::clip(). Every method below is fire-and-forget. query_status reads ring depth and playback state. query_config reads the config back.

lostWhether the box dropped the loaded clip

fn lost(&self) -> bool

No round-trip

A recovery restores the settings and triggers, not the ring's content. The caller rebuilds and appends the clip.

let handle = device.clip();
handle.append(&clip)?;

// later, from a loop that owns the clip
if handle.lost() {
    handle.append(&clip)?;   // reload; lost() reads false again
}

Streaming and retainedDrain-and-discard, or keep-and-replay

set_retain picks the mode 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 the ring size)
    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: built ClipBuilders)
handle.start()?;

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

TriggersRun a clip action on a native edge or a matched packet

A trigger runs one ClipAction on the box, with no host round-trip. One set holds both kinds.

  a native edge                   a packet at a traffic surface
  button, key, media              HidIn, HidOut, VendorInterrupt,
        |                         VendorBulk, Control, Emit
        v                               |
  [ input triggers ]  8                 v
    bind, unbind                  [ packet triggers ]  8
        |                           bind_packet, unbind_packet
        | action                        | action       | packet
        v                               v              v
        +-----> ClipAction <------------+        [ rewrite table ]
                run on the box                     reads it next, unless
                                                   the trigger consumed it
                                                       |
                                                       v
                                                   delivered

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; the release binding needs none.
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))?;

use medius::{ClipAction, ClipPacketTrigger, Direction, TrafficClass};

device.allow_imperfect_clones(true)?;   // first: a consuming trigger needs it
let clip = device.clip();

// Interface 2 is a vendor-page HID interface. Report ID 7 carries a button in bit 5 of its
// second byte, repeated every poll while held, so the report ID is the selector.
let held = ClipPacketTrigger::new(TrafficClass::HidIn, 2, Direction::IN, ClipAction::Start)
    .matching([0x07, 0x20], [0xFF, 0x20])
    .once_per_run(1)
    .consume();                   // the press never reaches the PC: needs the opt-in
let let_go = ClipPacketTrigger::new(TrafficClass::HidIn, 2, Direction::IN, ClipAction::Stop)
    .matching([0x07, 0x00], [0xFF, 0x20])
    .once_per_run(1);
clip.bind_packet(&held)?;
clip.bind_packet(&let_go)?;       // bound with the button up: one Stop on the next report

// A SET_REPORT on EP0 restarts the clip. A trigger that only watches needs no opt-in.
let set_report = ClipPacketTrigger::new(TrafficClass::Control, 0, Direction::OUT, ClipAction::Restart)
    .matching([0x21, 0x09], [0xFF, 0xFF]);
clip.bind_packet(&set_report)?;

// A refused bind leaves the set unchanged: compare the read-back with what was bound.
let bound = clip.query_config()?.packet_triggers;
for t in [&held, &let_go, &set_report] {
    match bound.iter().find(|e| &e.trigger == t) {
        Some(e) => println!("{:?} id {} -> {:?}, {} hits", t.class, t.id, t.action, e.hits),
        None => println!("the box did not take {t:?}"),
    }
}

clip.unbind_packet(&let_go)?;   // by key: action, consume, once_per_run and selector_len are ignored
clip.clear_triggers()?;         // both kinds

On AsyncDeviceAsyncClipHandle: control fires, queries await

AsyncDevice::clip() returns an AsyncClipHandle that keeps append, the settings, both kinds of trigger, the engine verbs and lost synchronous. query_status().await and query_config().await are futures.

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