Skip to content

Browser DSP and workers

The browser is the RF workstation. Heavy, high-rate work stays outside React and outside the main thread. Shared/transferable buffers, bounded queues, and worker-local state separate acquisition from presentation.

This chapter describes implemented paths. The ledger and qualification notes preserve their relationship to approved requirements and unfinished acceptance work.

Realtime path

flowchart TB
    WS[Binary CU8 WebSocket] --> IN[IQ ingress worker]
    IN --> RING[Independent bounded IQ sinks<br/>shared rings or credited transfers]
    RING --> RT[Realtime DSP WASM]
    RT --> AUDIO[Audio worklet]
    RT --> FFT[Realtime 4,096-bin wide FFT]
    FFT --> STORE[SpectrumFrameStore<br/>coalesced presentation]
    RING --> DISPLAY[Dedicated spectrum worker<br/>WebGPU display FFT + frame pacer]
    DISPLAY --> STORE
    RING --> ANALYSIS[Scientific analysis worker<br/>fast FFT + 65,536–4,194,304-bin fine FFT]
    ANALYSIS --> DET[Signal detector]
    ANALYSIS -->|display fallback| STORE
    RING --> CAND[Candidate analysis worker<br/>selected parent or one VFO probe]
    RING --> INPUT[Independent decoder-input worker<br/>WASM channelizer, created with job]
    INPUT --> DEC[Isolated decoder worker]
    STORE --> CANVAS[GPU spectrum/waterfall + Canvas2D overlay<br/>or complete Canvas2D fallback]
    IN --> DVR[DVR hot tier]

The audio path and realtime wide FFT are protected. Fine analysis changes cadence with Eco/Balanced/Analysis profiles but must not block tuning or audio. The dedicated spectrum worker prepares display FFTs independently of detector analysis; when that WebGPU path is unavailable, scientific analysis also supplies the fine display. Candidate input now comes from the ingress fan-out, not through a serial dependency on the analysis worker. Decoder input likewise has its own job-local sink/channelizer; detection and candidate queues are not in series with it. The wide FFT, adaptive display FFT and selectable scientific FFT are different paths, not three names for a fixed 4,096-bin image. See the decoder input path.

Each sink has independent backpressure. Ingress copies each frame into each enabled shared ring; consumers lease a zero-copy view and commit their own read cursor. Wakeups are coalesced, not a serialized per-frame acknowledgement chain. Full-rate IQ never goes through React. The transferable fallback copies a frame for each credited sink, transfers ownership, and marks discontinuities when a sink misses input. Neither fan-out is a no-copy broadcast. A slow or failed optional consumer must not block the realtime consumer.

Receiver readiness can precede rendering of the session-open response. The client buffers early events and retains IQ/DSP/FFT/audio diagnostics. Compact status and spectrum notifications are coalesced independently of ingestion; layout and resize observation are presentation concerns, not receiver restarts.

Implementation: src/dsp/DspPipeline.ts, src/transport/iq.ingress.worker.ts, and src/dsp/SpectrumFrameStore.ts under components/rfsentry-web/.

FFT and scheduling profiles

The scientific fine FFT accepts 65,536, 131,072, 262,144, 524,288, 1,048,576, 2,097,152, and 4,194,304 bins. Its size is operator-configurable; WebGPU computes supported fine FFTs, with worker-local WASM fallback. Display FFT geometry adapts separately to the visible span; the scientific FFT, display trace, and retained waterfall row are different quantities.

Bin spacing is sample rate / FFT bins. At 2.4 MS/s, 4,096 bins give 585.94 Hz/bin, 65,536 give 36.62 Hz/bin, 1,048,576 give 2.29 Hz/bin and 4,194,304 give 0.572 Hz/bin. These are calculation examples, not a supported capture-rate limit or measurements of peak separation, cadence or throughput.

Native/GPU peak reduction bounds detector input at 262,144 bins without turning a 4M scientific selection into a 4M-element JavaScript detector scan. The dedicated display FFT chooses the smallest selected-or-lower radix-2 size targeting 8,192 source bins across the visible span, within the selected size. It emits a 32,760-bin capture-wide waterfall row and an 8,192-bin local trace before transfer to presentation. Display cadence and detector scan costs thus remain independent of the scientific FFT selection; this is not a new limit on that selection.

Scalar/SIMD realtime artifacts have 32 MiB fixed linear memory. Separate analysis artifacts have 128 MiB and support the 2M/4M fallback contract. These are build-configured WASM memories, not measurements of total resident browser RAM. The audio worker does not allocate the extreme-analysis storage.

Current profile defaults come from src/dsp/performance.ts:

Profile Automatic display target Fast detector interval Fine detector interval Candidate analysis interval
Eco 20 Hz, wide history 180 ms Disabled 1,000 ms
Balanced 30 Hz, fine history 90 ms 260 ms 250 ms
Analysis 60 Hz, fine history 45 ms 120 ms 100 ms

These are scheduling targets, not measured throughput guarantees. Explicit display refresh choices include 30/60/90/120 Hz and measured-display matching. The dedicated GPU display prepares ahead of presentation to absorb asynchronous readback: Balanced and Analysis have base preparation targets of 60/90 Hz and paced queues of four/six results. A higher requested display rate can raise the preparation target. This must not increase scientific evidence merely because more display frames were prepared.

Performance controls and roadmap

The UI offers Eco, Balanced and Analysis, defaulting to Balanced on fresh lanes. App.tsx:setDetectionProfile updates lane scheduling/display configuration; it does not retune hardware, change capture rate or reset DVR duration. The storage controls independently own hot duration/bytes, warm-tier retention and evidence protection. A profile's decoder cost admission is not a global promise of a particular number of active jobs.

Use Signal detection to stop detector-only work independently of the profile. Manual tuning, audio, the waterfall and a manual decoder can keep running. To reduce the amount of IQ sent across the LAN, select a lower supported capture rate and check that the signal still fits in the capture.

The receiver roadmap records the original benchmark targets and proposed low-bandwidth transport. For unattended GOES reception today, configure a continuous HRIT job on the appliance.

Waterfall presentation and retained rows

Waterfall history is capture-wide and independent of the current panel size or view span. Raw FFT bins feed its rows; smoothing applies only to the upper spectrum trace. Reduction retains peaks rather than averaging narrow signals out of sight. Auto/manual level choices persist, and the wide and fine automatic level models remain independent.

Exactly one history is visible: wide for Eco, fine for Balanced/Analysis. The wide history is not an underlay to the fine history. WebGPU or WebGL2 renders the spectrum/history with a separately completed, transparent Canvas2D overlay for scales, VFO and annotations. The compatibility path publishes one complete opaque off-DOM Canvas2D frame. Both paths preserve one exclusive history rather than compositing two histories with conflicting levels or row geometry.

Resize, pan and zoom re-project existing rows. Capture-center/rate changes remap their RF geometry where possible and preserve screen-relative fallback pixels for non-overlapping captures rather than blacking out the history. Displayed row geometry remains stable. The VFO marker below the spectrum is a faint one-physical-pixel line, not a broad stripe over received evidence.

Detector event outlines travel with their captured rows and remain clickable while visible. Live boxes use published absolute-RF edges, stay inside the waterfall, and do not follow a moving power peak. A live box suppresses its own historical outline; the retained outline returns after the occurrence ends.

Implementation: src/ui/SpectrumCanvas.tsx, src/ui/waterfallModel.ts, src/ui/WebGpuSpectrumRenderer.ts, and src/ui/WebGlSpectrumRenderer.ts. The DVR chapter covers the separate capture-time visual archive; rendering history is not the authoritative raw-IQ record.

Audio continuity

The worklet starts after a bounded 2,048-sample prime, rebuffers after underrun, and rejects repeated or out-of-order blocks. Startup silence while priming is not an underrun. Sequence gaps, underrun/overflow samples and events, queue depth, rebuffering, limiting and invalid samples remain observable without publishing React state in the audio sample hot path.

Implementation: src/dsp/AudioEngine.ts and public/audio-worklet.js.

Frequency domains

RF Sentry keeps these values distinct:

  • hardware capture center — tuner center producing the source IQ;
  • operator RF/VFO — desired signal in absolute RF coordinates;
  • digital mixer offset — VFO minus capture center after route translation;
  • baseband/audio frequency — frequency within a demodulated domain;
  • display center/span — a presentation window over retained FFT history.

Moving a VFO inside the capture does not retune hardware. Panning within the capture does not move the VFO; crossing the capture boundary uses a controlled handoff and preserves the VFO while its passband fits. See local tuning. Decoder evidence reports the frequency domain and units instead of labeling every offset as absolute RF.

Channelization and decoder input

The decoder bridge receives complete raw-IQ blocks under explicit credit control. Its input worker applies lane-local residual DC correction (when enabled), frequency translation, anti-alias filtering, and exact rational resampling with the content-addressed channelizer WASM. It emits bounded decoder-rate blocks to a decoder-specific worker.

flowchart TB
    CU8[CU8 capture] --> F32[Unsigned centering<br/>complex float]
    F32 --> DC[Optional residual DC correction]
    DC --> MIX[NCO frequency translation]
    MIX --> FIR[Multistage anti-alias FIR]
    FIR --> RAT[Exact rational resampler]
    RAT --> CLOCK[Sample/time mapper]
    CLOCK --> ABI[Decoder ABI worker]

Raw recordings retain source samples and processing settings; correction is not destructively written into the evidence.

The candidate and decoder paths use the project-owned C/WASM block channelizer for source-rate numerical work. Bounded TypeScript feature/classification and lifecycle policy follow channelization; they are not a replacement for those source-rate loops. The acceleration ledger records this scalar/SIMD boundary.

Worker ownership

Owner High-level responsibility
Main React tree operator intent, compact status, layout
IQ ingress worker WebSocket framing, sample continuity, independent fan-out
Realtime DSP worker demodulation, audio, display FFT
Dedicated spectrum worker WebGPU display FFT preparation and paced results
Spectrum store/UI renderer retained rows, coalesced notifications, GPU/Canvas presentation
Fine-analysis worker large FFTs, noise/evidence grids, detector
Candidate worker bounded modulation/protocol hypotheses
Decoder-input worker mixing, channelization, exact resampling
Decoder worker isolated content-addressed WASM ABI module
Aviation/SATCOM workers incremental intelligence and product assembly
Storage workers IndexedDB/OPFS queries, migration, retention

High-rate decoder events do not replace root React lane state per frame. Validated evidence flows immediately to its owning intelligence service, while compact status is coalesced for presentation. Start, stop, fault, validation, and operator actions remain immediate.

Detector and classifier

The fast detector owns existence and parent identity. It uses frequency-local fast/slow noise models and a persistent absolute-RF evidence grid. Fine FFT evidence may refine the boundary of an already confirmed wide signal but cannot create one by itself.

Candidate analysis examines only an operator-selected signal or one automatic VFO probe. It reports ranked hypotheses, including Unknown and artifact, not calibrated probabilities. Frequency/service metadata is a prior. Actual decoder validation can strengthen a recommendation through a bounded trial.

See Detection and Auto Start for boundary evidence, parent grouping, classification stability, and the difference between selecting a signal and explicitly activating it.

Raw-IQ quality and correction

Raw CU8 quality uses complete 65,536-complex-sample windows, independent of WebSocket packet size. Gaps reset a partial window; samples on opposite sides of a discontinuity are never treated as contiguous. Warning assertion and recovery use distinct-window hysteresis plus a readable minimum hold, with fixed UI slots to avoid layout churn. These are sample-quality facts, not protocol validation or calibrated received power.

Optional residual DC correction is lane-local and precedes VFO translation in realtime DSP, spectrum/analysis, and decoder channelizers. Raw DVR/recording samples remain unchanged. Neither painting over FFT bins nor relabeling the operation as hardware calibration is an equivalent implementation. The receiver chapter explains its operator control and the risk to a real zero-centered signal.

Implementation: src/detection/IqQualityAnalyzer.ts, the DSP workers, and src/dsp/dcCorrection.ts.

WASM integration checks

The browser DSP link has an explicit worker-callable export allowlist in components/rfsentry-web/tools/build-dsp.sh. Add new exports there and exercise them through the instantiated browser WASM artifact. Passing a native DSP test does not prove that the shipped worker can call the function. See the build chapter for the pinned toolchain and checks.

GPU and browser-managed memory

GPU buffers, decoded image surfaces, ImageBitmaps, canvases, Blob URLs, and WASM linear memory are not all visible in the legacy JavaScript heap metric. RF Sentry separately accounts for known hot IQ, decoder heaps, preview caches, and GPU allocations where possible. Resource ownership and explicit release matter more than attempting to raise Chrome's heap flag.

Ledger and qualification

The receiver/DSP roadmap retains the acceleration requirements and acceptance boundary. Current scientific resolution extends through 4M; separate ingress, display and analysis workers and GPU/Canvas fallbacks preserve the protected realtime path.

The acceleration checkpoint records implementation and automated qualification plus a specific live 120 Hz confirmation. Its broader live-RF acceptance matrix remains open: Eco/Balanced/Analysis, 2.4/3.2 MS/s, representative FFT tiers, WFM/FT8/HD paths, decoder transitions, dual lanes, audio continuity and actual WebGPU/WebGL2/Canvas fallback behavior. Dated Pi 4 or Chrome/GTX 1080 Ti benchmarks are not fresh measurements of the current appliance/client.

The Phase 2 Correction Acceptance Contract and Deferred Phase 2 Closeout Backlog also retain detector/evidence/isolation proof work. Having these paths in code, or successfully rebuilding documentation, does not close those gates. The source-document reconciliation maps the relevant ledger sections to these chapters. This documentation pass changes no ledger checkbox and claims no new live acceptance.