# mLnL: mLink-annotated WAV chunk specification (v2)

A way to ship spectrograph annotations *inside* a regular WAV file so
the file stays standards-compliant audio everywhere while a viewer that
knows the format can render labelled regions (TX bursts, assertion
outcomes, impairment fires, etc.) over the audio's spectrogram.

**Status**: v2, stable. Producer: `mlink_fake_ota` (see
`src/tools/harness/fota_capture.c` + `fota_events.c`). Consumer: any
tool that walks RIFF chunks and looks for the four-CC `mLnL`.

---

## 1. WAV / RIFF refresher

A standard WAV file is a RIFF container:

```
RIFF<file_size - 8 (uint32 LE)>WAVE
  fmt <16 (uint32 LE)><PCM format fields>
  data<N (uint32 LE)><PCM samples>
  ... more chunks may follow ...
```

Each chunk = 4-byte four-CC ID + 4-byte unsigned little-endian size +
payload of exactly that many bytes + 1 pad byte if the size is odd. Per
the RIFF specification, a reader MUST skip any chunk whose ID it does
not recognise.

## 2. The mLnL chunk

```
mLnL<payload_size (uint32 LE)><JSONL bytes>(+ 1 pad if size odd)
```

ID: ASCII `mLnL` (= bytes `0x6D 0x4C 0x6E 0x4C`).

Payload: UTF-8 JSON Lines. One JSON object per line, terminated by
`\n`. Lines are emitted in chronological order of `t_start`.

A truncation marker may appear as the **last** line:

```
{"truncated":true}
```

This means the producer's in-memory buffer overflowed and some events
were dropped.

## 3. Reading the chunk

```python
def read_mlnl(path):
    with open(path, 'rb') as f:
        data = f.read()
    if data[:4] != b'RIFF' or data[8:12] != b'WAVE':
        return None
    i = 12
    while i + 8 <= len(data):
        cid = data[i:i+4]
        sz  = int.from_bytes(data[i+4:i+8], 'little')
        if cid == b'mLnL':
            return data[i+8 : i+8+sz].decode('utf-8').splitlines()
        i += 8 + sz + (sz & 1)
    return None
```

## 4. Event schema (v2)

**Every** event is a single JSON object with these REQUIRED fields:

| field    | type   | meaning |
|----------|--------|---------|
| `t_start`| number | start of the event's time range, seconds since channel start |
| `t_end`  | number | end of the event's time range, seconds; == t_start for instantaneous |
| `kind`   | string | event kind (see §4.2) |

### 4.1 Optional fields available on any kind

| field      | type   | meaning |
|------------|--------|---------|
| `f_lo`     | number | low edge of frequency annotation (Hz) |
| `f_hi`     | number | high edge of frequency annotation (Hz) |
| `f_center` | number | center frequency (Hz); alternative to `f_lo`/`f_hi` |
| `f_bw`     | number | bandwidth around `f_center` (Hz); paired with `f_center` |
| `note`     | string | free-form human-readable label (the "why this is here" line) |
| `color`    | string | suggested fill or outline colour, `#RRGGBB` |

A consumer should accept EITHER `f_lo`+`f_hi` OR `f_center`+`f_bw` (or
both -- prefer `f_lo`/`f_hi` if both are present). Events with no
frequency fields apply to the whole spectrum.

### 4.2 Kinds emitted by mlink_fake_ota today

**`tx_frame` is the primary annotation** — ONE per on-air air-frame,
sourced from the *transmitting daemon's own per-frame log event* (its
self-report, forwarded to the channel over the logging egress), NOT guessed
from the mixed audio. A whole transmission renders as its real labelled
sequence of boxes: e.g. PRESENCE + RTS in an announce channel, then N bulk
OFDM frames in the bulk band, each tagged with its LDPC rate.

```
tx_frame          t_start = frame key-down, t_end = key-up, placed at the
                  ACTUAL on-air anchor + the frame's sample offset (NOT the
                  modem's render/intent time -- see note below)
                  fields:
                    node   u32   transmitting node_id (attribution + color)
                    seq    int   0-based index of this frame within the PTT
                    n      int   total frames in this PTT  -> "seq of n"
                    frame  str   mLink frame name (vocabulary below)
                    ch     str   daemon channel: EMERGENCY / ANNOUNCE_0|1|2 /
                                 BULK  (the region the frame occupies)
                    rate   str?  LDPC rate of a bulk OFDM frame
                                 ("1/2","2/3","3/4","5/6"); absent on announce
                    f_lo   num   low edge of `ch`'s band (Hz; see §4.4)
                    f_hi   num   high edge of `ch`'s band (Hz)
                    sched_offset_ms num  intent->air latency of this burst:
                                 (on-air rising edge) - (modem render time).
                                 A "modem wants vs actually does" metric;
                                 coarse (block-quantized, multi-stage).
                    color  str   #RRGGBB, stable per node
                    note   str   pre-formatted "node N <frame> [rate]"

control           t_start == t_end ; one channel control verb dispatched
                  fields: command, req_id?
assertion_passed  t_start = watch start, t_end = match observation
                  fields: name, slack_s, note, color (green default
                          #3CB371), f_lo?, f_hi?
assertion_failed  t_start = watch start, t_end = watch deadline
                  fields: name, reason, note, color (red default
                          #D62828), f_lo?, f_hi?
```

**`frame` vocabulary** (announce family/subtype + bulk; render verbatim):
`PRESENCE/AUTO`, `PRESENCE/OPERATOR`, `PRESENCE/GEOPOLL`,
`PRESENCE/GEOPOLL_RESP`, `PRESENCE/SEED`, `PRESENCE/SEED_ACK`, `BULK/RTS`,
`BULK/ACK`, `BULK/DNAK`, `BULK/SBSERIES`, `BULK/SBRTS`, `BULK/RETX_RTS`,
`BULK/SB_RETX_RTS`, `BULK/INET_REQ`, `BULK` (one OFDM data frame),
`SHORTBURST` (one strung-announce data frame), `RELAY` (plus the relay
handshake subtypes `RELAY/REQUEST`, `RELAY/OFFER`, `RELAY/SELECT`,
`RELAY/FOR`, `RELAY/RESULT`, and the strung emergency rebroadcast
`RELAY/EMERG` / Authoritative ACK `RELAY/EMERG_ACK`), `APRS`. New names
appear as the protocol grows — treat `frame` as a free-form short string.

**REMOVED — `tx_burst`** (energy-detected): the channel's old *guess* at "a
station keyed, roughly narrow or wide," from mixed-audio energy + an HF ratio +
manual `tag_next_burst` labels. Replaced by `tx_frame` (the daemon knows exactly
what it keyed) and no longer emitted; `tag_next_burst` is gone too. A pre-2026-
05-28 wav may still contain `tx_burst`; treat it as opaque/legacy.

**On-air anchoring (why `sched_offset_ms` exists).** The daemon emits its
`tx_frame` log when it *renders* a transmission (its intent), but the audio only
reaches the air after the keying/buffering pipeline. The producer buffers each
node's frames as the logs arrive (intent time) and places them only once the
node's *actual* on-air energy rising edge is observed (air time) -- so the boxes
land on the real signal. `sched_offset_ms = air_time - intent_time` is that gap,
reported per burst. It's a useful "modem wants vs actually does" metric but
coarse (block-quantized; conflates render/queue/buffer/transit), so read it as
an indicator, not a precise stopwatch.

`channel_up` / `channel_down` are not emitted: the wav itself bounds the
session (first/last sample == up/down edge).

Future kinds reserved (not all emitted yet):

```
rx_event          a receiver's decode/deliver outcome
                  ({ node, from, snr_db, frame|kind, ... })
impairment_fire   { name, ... }
```

Consumers should ignore unknown kinds gracefully.

### 4.3 Field conventions

- `node` is a 32-bit unsigned integer (the registered node_id).
- Frequencies are in Hz, durations in seconds, amplitudes in
  channel-internal units roughly [-1, +1] before auto-gain.
- `command` matches the verbs in `tools/harness/fota_control.h`.
- `name` (for assertions) should ideally read as a hypothesis like
  `IF SEED THEN B SEED_ACK WITHIN 4s` -- the renderer uses it as the
  region label.

### 4.4 Channel -> spectral band

`tx_frame` carries both the daemon channel name (`ch`) and the resolved
band (`f_lo`/`f_hi`). The mapping (mLink's finalized spectrum allocation):

| `ch`         | band (Hz)     | mode / center        |
|--------------|---------------|----------------------|
| `EMERGENCY`  | 125 .. 175    | NB8FSK, 150 Hz       |
| `ANNOUNCE_0` | 265 .. 535    | QPSK, 400 Hz         |
| `ANNOUNCE_1` | 665 .. 935    | QPSK, 800 Hz         |
| `ANNOUNCE_2` | 1065 .. 1335  | QPSK, 1200 Hz        |
| `BULK`       | 1594 .. 2906  | OFDM, 2250 Hz center |

The three announce channels are ~270 Hz wide and non-overlapping, so a
PRESENCE/RTS box and the bulk blob of the same transmission land in clearly
separate horizontal lanes. A renderer can trust `f_lo`/`f_hi` directly or
re-derive from `ch` via this table.

## 5. Rendering tips for a spectrograph

- Time axis: `t_start` and `t_end` map directly to the wav's time axis
  (sample N = t * sample_rate). Draw the annotation as a horizontal
  span over [t_start, t_end].
- Frequency axis: if the event has `f_lo`/`f_hi`, render as a rectangle
  spanning [t_start, t_end] x [f_lo, f_hi]. If only `f_center`/`f_bw`,
  use [f_center - f_bw/2, f_center + f_bw/2]. If neither, span the
  full frequency axis.
- For `tx_frame` (the main case): render a filled / translucent box over
  [t_start, t_end] x [f_lo, f_hi] in the frame's `color`; label it with
  `frame` (or the pre-formatted `note`). Because each frame carries its own
  exact band, consecutive frames of one transmission draw as a readable
  sequence -- a narrow PRESENCE then RTS in an announce lane, then the bulk
  frames stacked in the bulk lane. Use `seq`/`n` to show position
  ("3/6") and `rate` to annotate the LDPC ramp on bulk frames.
- For `assertion_passed`: thin outlined rectangle in green (use `color`
  field if present, else `#3CB371`); label with `note`.
- For `assertion_failed`: thin outlined rectangle in red (or `color`);
  label with `note`. This is the "we were expecting something here
  and it never arrived" overlay -- visually distinguishing it from
  passes is the point.
- For `control`: vertical markers at `t_start` (zero-width).
- Per-node colors are stable across the run (the producer cycles a
  built-in palette by node_id); consumers may honour them or override
  with their own per-node scheme.
- Layer order: `tx_frame` (background fill) -> assertion outcomes (mid-
  layer outlines) -> `control` markers (top). Keep opacity moderate so
  overlapping annotations stay legible.
- `tx_burst` is no longer emitted (removed). Only a legacy pre-2026-05-28 wav
  carries it; render `tx_frame` and ignore `tx_burst` if present.

## 6. Producer responsibilities

1. Write `fmt ` + `data` chunks first in standard form (file plays as
   plain audio for any tool).
2. Append `mLnL` after `data` with the JSONL bytes.
3. Patch the outer RIFF size at file offset 4 to `file_size - 8`.
4. Pad to even byte boundary if needed (single `\0` byte; not counted
   in the chunk size field).
5. Emit JSONL in monotonic `t_start` order.
6. Each line is a single JSON object terminated by `\n` -- no
   multi-line objects, no trailing commas.

## 7. Consumer responsibilities

- Treat any unknown chunk ID as opaque -- skip it per RIFF rules.
- Walk chunks from the start; don't assume `mLnL` is at a fixed offset.
- Handle a `{"truncated":true}` last-line case as a status flag.
- Tolerate unknown fields and unknown `kind` values.

## 8. Version + compatibility

The chunk ID `mLnL` corresponds to schema v2 (this document). v1 (now
deprecated) used `{t_s, kind, ...}` with paired `*_start`/`*_stop`
events; v2 collapses pairs into ranges with `t_start`/`t_end` and adds
the frequency / note / color fields. Within v2: `tx_frame` (the
daemon-sourced per-frame kind, with `node/seq/n/frame/ch/rate/f_lo/f_hi/
sched_offset_ms/color/note`) was added 2026-05-28 and is the primary
annotation, anchored on the actual on-air edge; the energy-detected
`tx_burst` and the `tag_next_burst` verb were removed in its favour.
Consumers MUST tolerate both presence and absence of all optional fields
and unknown `kind`s.

If we need an incompatible schema change later, we'll mint a new
four-CC (`mLn3` etc.) and keep `mLnL` reserved for v2.

## 9. References

- mLink producer source: `src/tools/harness/fota_capture.c`
  (`append_riff_chunk` + `fota_capture_write_wav_with_annotations`)
- Event emitter: `src/tools/harness/fota_events.{c,h}`
- `tx_frame` ingest (forwarded-log -> annotation): the FOTA_MSG_LOG handler
  + `ingest_log_event` in `src/tools/harness/mlink_fake_ota.c`; the daemon
  side emits `tx_frame` in `src/protocol/tx_render.c`.
- Assertion engine: `src/tools/harness/fota_assert.{c,h}`
- RIFF specification: Microsoft Multimedia Programming Interface and
  Data Specifications 1.0 (1991).