Skip to content

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

  1. Manifest frequency hints and lane geometry produce an immediate candidate.
  2. Detector/candidate evidence refines ranking asynchronously.
  3. Manual Start runs manifest preflight and always remains available.
  4. Optional, persisted/default-off Auto Start may run a bounded trial when policy allows; frequency priors alone never establish a protocol.
  5. 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/.