Status: version 1 release candidate. This file is the authoritative cross-product protocol specification. Implementations must reject, not guess at, unsupported data.
The stream is full-duplex over an ADB-forwarded local socket. All integers are unsigned concepts encoded in network byte order (big-endian), except sequence is represented in the current implementations by a non-negative signed 32-bit integer. EOF terminates the session.
Every frame starts with 16 bytes:
| Offset | Size | Field | Rule |
|---|---|---|---|
| 0 | 4 | Magic | ASCII-equivalent integer ASUB / 0x41535542 |
| 4 | 2 | Version | 1 |
| 6 | 2 | Type | Enumerated below |
| 8 | 4 | Payload length | 0–65,536 control; 0–8,192 PCM |
| 12 | 4 | Sequence | Normal frames must strictly increase within a connection; terminal ERROR may use reserved sequence 0 |
Types:
| ID | Name | Direction / purpose |
|---|---|---|
| 1 | HELLO | Host to Android; first frame and authentication |
| 2 | READY | Android to host; accepted format/configuration |
| 3 | START_STREAM | Reserved for an explicit post-handshake start gate |
| 4 | PCM | Host to Android; complete frame-aligned PCM chunk |
| 5 | STATS | Request/response for bounded playback statistics |
| 6 | PING | Heartbeat request |
| 7 | PONG | Heartbeat response |
| 8 | ERROR | Bounded sanitized error information |
| 9 | STOP | Graceful session termination |
Unknown magic, version, type, length, order, or direction is a protocol error. No payload length may be used for allocation before its type-specific bound is checked.
Version 1 HELLO is exactly 40 bytes:
| Offset | Size | Field |
|---|---|---|
| 0 | 32 | 256-bit session token generated by Windows CSPRNG |
| 32 | 4 | Sample rate; permitted range 8,000–192,000 |
| 36 | 1 | Channels; version 1 permits 1 or 2 |
| 37 | 1 | Bits per sample; version 1 requires 16 |
| 38 | 2 | Reserved; send zero |
The Android receiver compares the token in constant time with the token passed during the explicit ADB launch. The token is never persisted or logged. Each reconnect creates a new socket name, token, and generation.
Version 1 READY is 16 bytes: accepted sample rate, channel count, bits per sample, and configured AudioTrack buffer frames, each as a 32-bit integer.
PCM contains signed little-endian PCM16 samples despite the big-endian control
header. Payloads must be nonempty, no larger than 8,192 bytes, and aligned to
channels * 2 bytes. Production tuning will normally use 5–20 ms chunks.
The receiver queue applies a duration-based live-edge policy: it retains the newest 40 ms of complete PCM chunks (or one indivisible input chunk), with a separate hard cap of 32 chunks. When the duration or chunk cap is reached, it drops complete oldest chunks, increments dropped-frame statistics, and never grows without limit. This deliberately bounds post-stall latency instead of allowing a long backlog to play out after the producer and AudioTrack return to the same real-time rate.
The host sends an empty STATS request every three seconds after READY. Android returns the 92-byte big-endian playback-progress payload below. The Windows host still accepts the 24-byte legacy and 60-byte enhanced prefixes for compatibility:
| Offset | Size | Field |
|---|---|---|
| 0 | 8 | Total PCM frames received by the playback worker |
| 8 | 8 | Total PCM frames dropped by the bounded playback queue |
| 16 | 4 | Current queued chunk count |
| 20 | 4 | Configured AudioTrack buffer frames |
| 24 | 4 | Current queued PCM frames |
| 28 | 4 | AudioTrack buffer capacity frames |
| 32 | 4 | AudioTrack start-threshold frames (API 31+, otherwise configured buffer) |
| 36 | 4 | AudioTrack underrun count |
| 40 | 4 | Routed output device type (TYPE_BUILTIN_SPEAKER is expected) |
| 44 | 4 | Audio-focus state (0 none, 1 gained, 2 ducked, 3 transient loss, 4 permanent loss) |
| 48 | 4 | Current music-stream volume |
| 52 | 4 | Maximum music-stream volume |
| 56 | 4 | Queue high-water mark in frames |
| 60 | 8 | Total PCM frames successfully written to AudioTrack |
| 68 | 8 | Cumulative AudioTrack playback-head frames, including 32-bit wrap handling |
| 76 | 4 | Milliseconds since the last successful AudioTrack write |
| 80 | 4 | Milliseconds since the playback head last advanced |
| 84 | 4 | Current AudioTrack play state |
| 88 | 4 | Actual AudioTrack performance mode after compatibility fallback |
This response also acts as the active heartbeat. The Windows native layer validates the exact 24-, 60-, or 92-byte length before decoding and exposes these counters through the FFI diagnostics API. PING/PONG remains supported for protocol tests and future peers.
ERROR payloads are bounded UTF-8 diagnostic text. Capability negotiation,
sequence rollover, and timestamp semantics remain future-version work;
normal sequence numbers are strictly increasing for the lifetime of one
connection; a terminal ERROR may use reserved sequence 0.
Focus, route, and queue state are reported in enhanced STATS rather than as
separate control messages. The Windows host requires companion application
exactly version code 7, requires the installed base APK SHA-256 to exactly
match the APK bundled with that host build, and validates READY fields before
starting capture. A fatal handshake ERROR is reported to the Dart supervisor
immediately rather than waiting for the connection deadline.
Before a distributable Windows package is created, the build also verifies the companion APK signature and requires its sole signer certificate SHA-256 to match the separately configured stable release identity. Runtime exact-file matching complements that build-time identity check; it does not replace it.