A clip is a byte stream of variable-length entries, little-endian. The first byte of each entry is a tag: 0x00 is a gap run, any other value is a content tick's flags. One entry is one native frame.

Emit nothing for count frames. The endpoint NAKs, byte-identical to an idle mouse, so a gap is the faithful way to hold still or pace between actions.

A motion delta and/or a list of edges applied on one frame. The flags byte (nonzero, so it can't be mistaken for a gap tag) selects which fields follow.

An edge reuses INJECT's tuple, so one clip drives every input class.

An edge is a level: it sticks until a later tick changes it, and the box NAKs while it is held still. Motion (dx/dy/wheel) is a per-frame delta.

Set several flag bits and the fields stack in a single tick, so a move and a press land on the same frame and the PC sees one report. That is what keeps "aim and hold fire" faithful: motion every frame, the fire button pressed on the frame it goes down.

05 0A 00 FC FF 01 00 00 00 01
   flags=XY|EDGES   dx=+10 dy=-4   n=1   edge[class=0 button, id=0 Left, action=1 press]

Entries play out one per frame, left to right.

The bytes for three example entries: move up-right, press A, idle 5 frames.

01 0A 00 F6 FF        flags=XY,   dx=+10  dy=-10
04 01 01 04 00 01     flags=EDGES n=1  edge[class=1 key, id=0x04 'A', action=1 press]
00 05 00              tag=gap,    count=5  (NAK 5 frames)

Append a batch of whole entries to the tail of the ring. Send it while stopped to preload, or while playing (streaming mode) to keep topping up in real time. Opcode 0x12.

CLIP_APPEND 0x12 · payload = one or more whole entries

Fire-and-forget

The frame SEQ doubles as an append sequence number: the box expects each CLIP_APPEND to be the previous SEQ plus one. Because the link is fire-and-forget, a lost frame shows up as a SEQ gap, and the box marks the clip faulted in QUERY(CLIP) so the host re-syncs (CLEAR, then rebuild) instead of playing a stream with a hole in it. Pack whole entries per frame; never split one entry across two appends.

An append that doesn't fit the ring is dropped whole and faults the clip, never written as a partial entry that would desync the stream. Keep an append under QUERY(CLIP)'s free bytes to avoid it: in streaming mode the box drains from the head while you append to the tail, so a real-time host tops up as free opens back up.

  the ring, read by QUERY(CLIP):

       free                        buffered (total)
  +----------------+----------------------------------------+
  |    (append     | [e5][e6][e7][e8][e9] ...               | --> drained
  |    here, <=    |     buffered, not yet played           |     1 / frame
  |    free)       |                                        |
  +----------------+----------------------------------------+
   append > free  -->  dropped whole + clip faulted

Library binding: ClipBuilder + append, which splits a large clip into whole-entry frames for you.

Append one content tick, cursor dx = 10 (a 5-byte entry, so LEN = 5):

+--------+--------+--------+--------+--------+--------+--------+--------+
| A5     | 12     | 00     | 05 00  | 01     | 0A 00  | 00 00  | lo hi  |
+--------+--------+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | flags  | dx     | dy     | CRC16  |
+--------+--------+--------+--------+--------+--------+--------+--------+
                    ^ append seq     \- one XY content tick --/

One byte of op selects an engine verb. Opcode 0x13. There are no args: settings live on CLIP_SET, so a control frame is just the verb.

CLIP_CTRL 0x13 · payload [op u8]

Fire-and-forget

Ops 0-5 (START through TOGGLE) double as theaction byte a CLIP_TRIGGER fires on a physical edge; CLEAR and FINALIZE are host-only.

QUERY(CLIP) reports one of four states.

In streaming mode, if the ring drains with no FINALIZE, the box idles (NAKs, holding its levels) and stays playing until you refill it; a topping-up host or any keepalive holds the clip alive. A finalized clip ends when the ring empties, or replays from the head if loop is set.

STOP        an explicit STOP or CLEAR op
silence     a full 1 s of control-PC silence
RESET       a RESET command
detach      the cloned mouse unplugs
link loss   the inter-chip link drops

Each halts playback and releases the clip's lock; a hard stop (silence, RESET, detach, link loss) also flushes the ring. The 1 s safety net and a RESET reach a clip like any other injection. With movement riding on, clip motion rides native reports and is additive to the user's own movement, so the frame-exact use case runs riding off.

Library binding: Device::clip().

Start playback (op = 0, a single-byte payload so LEN = 1):

+--------+--------+--------+--------+--------+--------+
| A5     | 13     | 00     | 01 00  | 00     | lo hi  |
+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | op     | CRC16  |
+--------+--------+--------+--------+--------+--------+

Every op has the same shape; only the op byte changes.

Set one of the clip's settings, OPTION-shaped: an id byte picks the setting, a value byte carries it. A setting sticks until you change it or the clip is torn down; read them all back with QUERY(CLIP). Opcode 0x14.

CLIP_SET 0x14 · payload [id u8][value u8]

Fire-and-forget

The autolock value is a bitmask of the physical-input classes START locks while the clip plays (clip-owned, released on STOP), leaving the ones you don't name free. A host LOCK is untouched. 0 = no auto-lock; 0x1F = every class.

Library binding: set_autolock, set_loop, set_retain.

Turn looping on (id = 1, value = 1, so LEN = 2):

+--------+--------+--------+--------+--------+--------+--------+
| A5     | 14     | 00     | 02 00  | 01     | 01     | lo hi  |
+--------+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | id     | value  | CRC16  |
+--------+--------+--------+--------+--------+--------+--------+

Fire a CLIP_CTRL verb the instant the user physically moves an input (the same physical edge CATCH reports), with no host round-trip, so even the first emitted frame is box-timed. Triggers are a LOCK-shaped managed set of up to eight bindings, keyed by (class, id, edge). Opcode 0x15.

CLIP_TRIGGER 0x15 · payload [class u8][id u16][edge u8][action u8][flags u8]

Fire-and-forget

A binding is keyed by (class, id, edge), so re-sending the same key replaces it and clearing present removes it. To wipe the whole set in one frame send the clear-all sentinel: class = 0xFF, id = 0xFFFF, edge = 0 (both), flags = 0. Preload the ring (and, for a replayable macro, mark it FINALIZEd) before you bind.

Library binding: bind, unbind, clear_triggers.

Bind the A key's press to START (class = 1, id = 0x04, edge = 1 press, action = 0 start, flags = 0x01 present):

+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+
| A5     | 15     | 00     | 06 00  | 01     | 04 00  | 01     | 00     | 01     | lo hi  |
+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | class  | id     | edge   | action | flags  | CRC16  |
+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+