Clip

Entry formatCLIP_APPEND bytes

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.

Motion, edges, raw reports and control transfers applied on one frame. flags selects which fields follow.

The fields follow in the table's order. An entry is ≤512 bytes, one CLIP_APPEND payload.

An invalid entry (a reserved bit, a count out of range, a length >512 bytes) faults the clip when playback reaches it.

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

An edge is a level: it holds until a later tick changes it, and the box NAKs while the level is unchanged.

Several flag bits stack their fields in one tick: a move, a pan and a press on the same frame, in one report.

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

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)

Raw and transfer itemsRaw reports and control transfers on a content tick

A raw item is RAW's payload with its length, and a transfer item is TRANSFER's payload. Both need OPTION(IMPERFECT), checked as the tick plays. With the opt-in off, the item is discarded and counted in gated.

The box queues transfers (1 KiB) and runs them one at a time. Each result arrives as a CLIP_XFER event, in drain order.

The clip releases its held input on STOP, its natural end, a loop wrap, RESTART, CLEAR, a fault and a hard stop. A native report or a later raw report emitted first replaces the raw bytes.

One raw report OUT on endpoint 2, then a SET_REPORT with two bytes of OUT data on EP0.

10 01 02 02 03 00 A1 B2 C3
   flags=RAW   n=1   item[ep_num=2, dir=2 OUT, len=3, bytes=A1 B2 C3]
20 01 00 21 09 00 03 00 00 02 00 04 01
   flags=XFER  n=1   item[ep=0, setup=21 09 00 03 00 00 02 00 (wLength=2), data=04 01]

CLIP_APPENDFill the ring

Appends whole entries to the ring's tail: while stopped to preload, or while playing (streaming mode) to top up. 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.

The link is fire-and-forget, so a lost frame shows as a SEQ gap. The box then marks the clip faulted in QUERY(CLIP). Recover with CLEAR, then rebuild.

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.

Keep an append under QUERY(CLIP)'s free bytes. In streaming mode the head drains while the host appends to the tail, so free recovers as it plays. The ring is 64 KB with PSRAM and 16 KB without. Never assume a size.

  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.

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

SEQ is the append sequence. flags, dx and dy are the one XY content tick.

CLIP_CTRLDrive the playback engine

One byte of op selects an engine verb. Settings live on CLIP_SET. Opcode 0x13.

CLIP_CTRL 0x13 · payload [op u8]

Fire-and-forget

Ops 0-5 (START through TOGGLE) double as the action byte a CLIP_TRIGGER fires on a native edge or a matched packet. 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 refilled. A topping-up host or any keepalive resets the 1 s silence timer.

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 real device unplugs
link loss   the inter-chip link drops
re-clone    the box clones a device again

Each halts playback and releases the clip's lock. A hard stop (silence, RESET, detach, link loss, re-clone) also clears the ring, settings and trigger set, which a host reloads.

A hard stop moves the session count.

Library binding: Device::clip().

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

CLIP_SETSet a clip setting

Sets one clip setting, OPTION-shaped. A setting holds until changed or cleared by a hard stop. QUERY(CLIP) reads them all back. Opcode 0x14.

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

Fire-and-forget

autolock locks are clip-owned and released on STOP. A host LOCK is untouched. 0 = no auto-lock; 0x1F = every class.

A clip's motion bypasses movement riding by default, so it plays on the box's clock. ride puts it back on the ride: additive to native motion, and dropped while the mouse is still.

While rendering is on with a profile armed, a clip's cursor motion is rendered like a MOVE with no flag and rides the same way. ride then applies to the wheel and pan alone. Edges stay on the clip tick, ahead of the rendered motion.

Library binding: set_autolock, set_loop, set_retain, set_ride.

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

CLIP_TRIGGERBind a native edge or a matched packet to an engine verb

Fires a CLIP_CTRL verb on the box from a native edge (as CATCH reports it) or a matched packet, with no host round-trip, so even the first emitted report is box-timed.

Triggers are a LOCK-shaped managed set. The class byte picks the kind. An input class makes one of up to 8 bindings, keyed by (class, id, edge). A traffic class makes one of up to 8 packet triggers. Opcode 0x15.

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

Fire-and-forget

  class 0..2, 0xFF                          class 4..9
  a native edge                             a packet on a traffic surface
  button, key, media                        HID_IN, HID_OUT, VEND_INTR, VEND_BULK, CONTROL, EMIT
          |                                         |
          v                                         v
  [ 8 input bindings ]                      [ 8 packet triggers ]
    key (class, id, edge)                     key (class, id, dir, mlen, match, mask)
    the most specific acts on the edge        the most specific acts on the packet
          |                                         |
          +------------> one CLIP_CTRL op <---------+
                         0 START .. 5 TOGGLE, run on the box

Re-sending the same (class, id, edge) key replaces that binding. Clearing present removes it.

The clear-all sentinel wipes the whole set, input bindings and packet triggers alike: class = 0xFF, id = 0xFFFF, edge = 0 (both), flags = 0.

Preload the ring (and FINALIZE it for a replayable macro) before binding.

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):

Packet triggersCLIP_TRIGGER with a traffic class

A traffic class in the class byte makes a packet trigger. A packet on that surface whose head matches runs the verb, as an input edge does. The match follows the six bytes every binding has. Opcode 0x15.

CLIP_TRIGGER 0x15 · packet payload 8 + 2 x mlen bytes

Fire-and-forget

The key is (class, id, dir, mlen, match, mask). The same key overwrites, and the same key with present clear removes. The box holds 8 packet triggers beside the 8 bindings, with 112 match bytes between them.

  packet at a surface
        |
        v
  [ packet triggers ]   read the bytes as they arrived; only the most specific one acts
        |     |
        |     +--> the top-ranked trigger's verb, run on the frame clock's next tick
        |     +--> consume: the packet stops here
        v
  [ rewrite table ]     sees the packet next, and applies the top-ranked rule
        |
        v
  delivered             to the game PC (IN) or the real device (OUT)

A refused frame is dropped whole, with no reply, and leaves the set unchanged: a new key isn't added and an existing key keeps its trigger. Compare what QUERY(CLIP) reads back with what was sent.

No reply. Library binding: bind_packet, unbind_packet, clear_triggers.

Bind HID_IN interface 2, IN, to START, with consume and RUN (flags = 0x07): report ID 0x07 is the selector (slen = 1) and bit 5 of the next byte is the condition, so LEN = 12.

To remove the same trigger, keep the key and zero action, flags and slen.

04 02 00 01 00 00 00 02 07 20 FF 20
   class=4 HID_IN   id=2   dir=1 IN   action=0   flags=0   slen=0   mlen=2   match=07 20   mask=FF 20