Module tap 

Contract F — the vision-tap wire format.

The frozen seam between the video pipeline (the writer, ados-video) and the vision engine (the reader, ados-vision). A tap carries decoded rawvideo frames from the encode pipeline to the engine over a Unix socket: the engine connects as a client, the writer serves the socket and streams [header][pixels] per frame.

Framing (v2): a 24-byte little-endian header, then byte_len raw pixel bytes:

magic:u32=0x41445654 ("ADVT") | format:u8 | _pad:u8 | width:u16 | height:u16 | _pad:u16 | byte_len:u32 | ts_mono_ns:u64

ts_mono_ns is host CLOCK_MONOTONIC ns stamped by the writer at frame arrival. Self-describing so a consumer can size a ring without a side channel. This module is the single definition both sides build against — freeze it here, change both sides in the same version bump (the same frozen-wire-contract discipline the mavlink, state, and plugin sockets already follow, now extended to the vision seam).

Structs

TapHeader

A decoded tap frame header.

Enums

TapHeaderError

A malformed tap header.

Constants

TAP_CONTRACT_VERSION

The tap wire-contract version. Bump on any framing change; both the writer and the reader must move together.

TAP_HEADER_LEN

Fixed header length in bytes.

TAP_MAGIC

Header magic — ASCII “ADVT”, little-endian.

TAP_MAX_FRAME

Cap a single tapped frame so a corrupt header cannot drive an unbounded allocation. 4K RGB24 is ~25 MiB; 64 MiB is a generous ceiling.

Functions

decode_tap_header

Decode a tap frame header.

encode_tap_header

Encode the tap frame header. The writer prepends this to each frame’s pixels.

format_from_tag

The FrameFormat for a wire tag, or None for an unknown tag.

format_tag

The pixel-format wire tag for a FrameFormat.

write_tap_frame

Write one [header][pixels] tap frame to w. The shared writer the video pipeline shim and any producer use so the framing matches the reader exactly.