Decoder architecture¶
Choose a decoder in the browser for interactive listening or IQ replay. Each entry in the browser catalog identifies its module by content hash and specifies its input, outputs, execution limits and ABI. For unattended GOES reception, the Pi also supports a continuous HRIT job that keeps running after the workstation closes.
Manifest and operator policy¶
The v2 manifest specifies the exact sample rates, domain, bandwidth and clock a module accepts. It also describes tuning policy, recommendations, Auto Start evidence and licensing. The build matrix records the sources, patches, toolchain and artifact hashes for each build. Contract reference · Browser decoder catalog
Recommended gain, AGC, squelch, de-emphasis and signal-follow behavior are not individual fields in this manifest. Shared receiver/DSP and assisted-activation policy own those controls. The original per-decoder policy requirement remains design scope; a decoder must not gain tuner authority by adding a manifest hint. Frequency hints rank candidates, not prove a protocol or bypass input preflight.
Common input path¶
flowchart TB
IQ[Lane CU8 IQ + sample counter] --> INGRESS[iq.ingress.worker<br/>Live or historical source]
INGRESS --> TAP[Independent bounded decoder sink]
TAP --> INPUT[decoder.input.worker]
INPUT --> DC[Lane residual DC correction]
DC --> MIX[Absolute RF to baseband]
MIX --> CHAN[WASM channelizer + rational resampler]
CHAN --> MAP[DecoderClockMapper]
MAP --> WORKER[decoder.worker]
WORKER --> WASM[Content-addressed decoder WASM]
WASM --> EVT[Bounded status/events/media/audio]
EVT --> NORM[Typed normalization]
NORM --> UI[Intelligence / workspace / archive]
Live IQ goes directly from ingress to the decoder-input worker through its own
credit-bounded transferable port. The input worker also supports shared rings;
current job activation uses credits to avoid missing an initial ring wake during
asynchronous WASM startup. Candidate/fine-analysis queues are not in series with
this path; their backpressure must not interrupt decoder continuity.
DspPipeline creates the input worker on demand and connects it to
decoder.worker with a MessagePort. Only channelized decoder-rate samples
cross that second boundary. React receives bounded status/results, not full-rate
live IQ. Replay uses the same ingress fan-out.
Input blocks carry start sample, rational sample rate, UTC/monotonic anchor, uncertainty, flags, and discontinuity information. A gap resets protocol timing that cannot span it. The exact rational rate avoids drift caused by rounding rates such as 1,488,375/2 or 1,488,375/32. See the sample-clock contract for delay, phase, and discontinuity semantics.
Decoder input is independent of volume, mute, squelch, browser AGC, de-emphasis, and the audible filter unless the manifest explicitly requires that domain. Manifested producers include complex IQ, linear audio, FM discriminator, FM multiplex, envelope/pulse, and protocol bits. A declared producer is not a claim that every protocol using that input has an implemented decoder.
ABI and isolation¶
The worker negotiates the adapter/version declared by each manifest and
validates required exports before processing. Current RF Sentry ABI modules use
rfsentry-decoder 1.2; the pinned FT8/FT4 adapters retain their declared 1.0
entry points. ABI 1.2 receives bounded float32 input and drains bounded JSON
status/event records, decoded audio, and fragmented media through explicit
consume calls. The build-time allowlist is executable policy, not permission
for a manifest to load arbitrary code. Asset length/hash and required exports
are checked against the generated catalog before processing; the build matrix
records pinned sources, readable patches, toolchain, and artifact identities.
ABI 1.2 timing includes the first output sample's job-local decoder counter,
UTC nanoseconds where available, exact rational source-sample position, clock
epoch, and discontinuity state. Multistage anti-aliasing preserves phase and
FIR group delay; timing cannot be inferred from worker-message boundaries.
Input queues, execution/memory admission, output drains, retries, events, audio,
and session-local media all remain bounded according to manifest/host policy.
.mjs loaders must be served as JavaScript under nosniff; gateway integration
tests cover this import boundary.
A module hash mismatch, ABI mismatch, trap, queue overrun, or validation timeout faults only that lane's decoder job. It cannot fault the receiver, audio, spectrum, waterfall, detection, or another lane.
Execution tiers¶
Implemented: browser workers/WASM. Every current catalog entry targets
browser-worker, including the IQ monitor and two NRSC-5 sanitizer variants.
Native C/Rust compiled to WASM remains browser work, not a native Pi process.
The catalog/worker and start policy verify adapters, artifacts and admission;
neither a source-language label nor a schema enum creates another runtime.
Continuous decoding on the Pi. An enabled appliance HRIT job takes IQ from the gateway and sends validated frame records back to its bounded RAM buffer. A workstation can read those records or a paired Server can archive them. The job has its own configuration and lifecycle. Configure a continuous job
Planned on-demand decoder broker. The schema can describe native-child.
The browser Start control currently accepts only browser-worker entries.
WebSDR Phase 7 tracks the separate proposal for launching native decoders on demand.
A future bridge must start only on selection, accept explicitly supplied
channelized audio/IQ (or a coordinated gateway tee), emit bounded structured
results, enforce CPU/memory/runtime/output limits and stop on disconnect/timeout.
It must never open a competing receiver or retune independently of session
ownership. These constraints are not permission to install native daemons now.
Planned: optional analysis host. GNU Radio, SatDump or expensive analysis may use an explicitly configured workstation bridge later; none is a mandatory Pi dependency or a currently shipped external-decoder service. Preserve the same input, ownership, provenance and bounded-result contracts.
Validation semantics¶
event.kind === "message" is not itself proof of validation. Each normalized
event records the actual mechanism where known: CRC/parity, FEC, frame sync,
or product integrity. The decoder workspace's Validated only filter uses that
explicit evidence. Synchronization, a corrected FEC frame, a checksum-valid
message, and a complete product are distinct stages.
Start policy¶
- Manifest frequency hints and lane geometry produce an immediate candidate.
- Detector/candidate evidence refines ranking asynchronously.
- Manual Start runs manifest preflight and always remains available.
- Optional, persisted/default-off Auto Start may run a bounded trial when policy allows; frequency priors alone never establish a protocol.
- Validated decoder output confirms the trial; silence/failure expires it and starts a cooldown.
Manual selection is sticky until retune or explicit return to automatic selection. Sanitizer builds are operator-only and never auto-start.
Job lifecycle¶
DecoderManager owns lane-local state: suggested, preparing, synchronizing,
running, holding, complete, stopped, cancelled, or fault. Targets are the manual
VFO/passband or a detected parent identity; manual decoding remains available
when detection is off. Retunes, incompatible mode/passband changes, target loss,
receiver release/fault, and route handoff stop or resynchronize only the affected
job. Decoders cannot retune or change gain directly; requested refinement goes
through shared assisted-activation policy, with operator pins and undo preserved.
History and bounded media can remain inspectable after a job stops. The workspace guide distinguishes stopping a job from freezing a review surface or replaying retained events.
Implemented modules¶
| Module | Input | Main output / evidence |
|---|---|---|
| IQ substrate monitor | complex IQ | ABI/timing/continuity diagnostics |
| FT8 | 12 kHz linear audio | CRC/LDPC-valid messages |
| FT4 | 12 kHz linear audio | CRC/LDPC-valid messages |
| NRSC-5 FM | 1,488,375/2 S/s complex IQ | audio/services/SIS/SIG/objects |
| NRSC-5 AM | 1,488,375/32 S/s complex IQ | audio/services/SIS/SIG/objects |
| NRSC-5 ASan | same as FM/AM | diagnostic fault evidence |
| 1090ES | 2.4 MS/s complex IQ | CRC-valid DF17/DF18 frames |
| 978 UAT | 6.25M/3 S/s complex IQ | RS-valid downlink/uplink frames |
| GOES HRIT | 1.854 MS/s complex IQ | RS-valid 892-byte CADUs |
The generated catalog is the definitive table of current manifest values: ten entries, including diagnostics, not ten fully qualified protocol families. The separate decoder roadmap preserves all requested modes and marks the implemented subsets. AM/USB/LSB/CW/NFM/WFM listening in the realtime DSP is distinct from manifested protocol modules; NRSC-5 stereo does not establish analog FM stereo or RDS support.
For UAT and GOES, the Reed Solomon correction count describes a decoded frame. Inspect higher-level evidence separately, such as an aircraft position or the completeness of a GOES image.
Ledger and qualification¶
Read docs/roadmap/decoders.md sections Phase 6A — Substrate and Contracts, 6B.0 —
Shared Foundation, 6B.1A — Exact Timing and Reference Contracts, and the
Reconciled Phase 6 Completion Ledger — 2026-08-31. Their accepted substrate
and timing slices do not establish protocol support or close later gates.
The 6B.1A continuous capture-order tap supersedes the earlier candidate-bridge
description and matches the current ingress/input-worker implementation.
The FT8/FT4 extended operator matrix, NRSC-5 acceptance matrix, and cross-decoder provenance/regression closeout remain distinct from local artifact tests. Later implemented aviation/SATCOM modules are documented on their own pages; the older Phase 6 checklist is not an exhaustive current catalog.
Implementation anchors: src/decoder/catalog.ts, DecoderManager.ts,
decoder.input.worker.ts, decoder.worker.ts, DecoderWasmAbi.ts, and
src/dsp/DspPipeline.ts. Regression anchors include decoderArtifact.test.ts,
decoderFoundation.test.ts, decoderManager.test.ts, decoderContinuity.test.ts,
and the capture/input-queue tests under components/rfsentry-web/test/.