Skip to content

ADR 0008: Client-side IQ timeshift

  • Status: accepted
  • Date: 2026-09-05 (tiered-storage amendment 2026-09-24)

Context

Freezing rendered waterfall pixels or buffering demodulated audio cannot let an operator retune, reclassify, or decode an earlier signal. The browser already receives acquisition-framed raw IQ and fans it out to independent realtime, spectrum, analysis, candidate, and decoder workers. The physical receiver must continue acquiring live IQ while an operator investigates that history.

Decision

The ingress worker owns a segmented raw-IQ timeline before the existing DSP branches. Recent IQ remains in a hot browser-RAM tier. Once it ages beyond the operator's Hot RAM Minimum/Target policy, immutable batches transfer to a dedicated OPFS worker and the ingress worker releases their payloads. Seeking or playback reads required warm segments into a bounded RAM cache. Each live WebSocket ArrayBuffer remains the authoritative allocation while hot and is copied only into the already bounded consumer rings. Every frame retains its source sample counter, monotonic time, RF/tuner center, sample rate and format, gain, PPM, flags, and applicable UTC clock anchor. Geometry, settings, counter, and continuity changes create explicit acquisition segments.

A presentation-source epoch distinguishes current receiver IQ from historical replay and every seek discontinuity. Historical frames re-enter the same DSP, spectrum, detector, candidate, and decoder inputs used for live reception. Workers reset only their local stream state at an epoch boundary; stale output from an older presentation source is rejected. Detection time advances from the source frame's monotonic clock rather than browser wall time.

The waterfall additionally maintains a tiered visual index keyed by capture time and acquisition RF center/sample rate. This is a derived cache, not an alternative IQ record. A seek restores time-eligible rows into the existing display renderer instead of remounting or blanking it; replayed IQ can replace the corresponding cached row. The cache follows the raw-IQ retention boundary and clears on full receiver-session release, while a presentation-source reset preserves it. Older exact row representations are batched to an OPFS sidecar and paged around the historical cursor; native Float32 remains the default. Detector annotations reset at a source boundary and rebuild from the replayed analysis rather than carrying future live-state overlays onto historical pixels.

The visual cache defaults to retaining each emitted wide/fine display row as native Float32, with no further downsampling, quantization, or insertion-time buffer copy. Optional per-lane 1/2, 1/4, and 1/8 peak-preserving resolution and 16-bit or 8-bit dB encoding reduce future row payloads; older rows are not synchronously repacked or deleted when the preference changes. These are visual-cache preferences, not changes to the selected scientific FFT or raw IQ. The UI accounts and reports cached row payload separately from raw IQ; JavaScript object and renderer overhead remain additional. The raw-IQ Hot RAM Target does not impose a hidden ceiling on visual history.

The default policy keeps at least 60 seconds hot and uses 1 GB as the Hot RAM Target. Crossing that target triggers a rebalance toward 90 percent to avoid per-frame RAM/disk churn; reducing it applies the same policy immediately. The Hot RAM Minimum still takes priority when its raw IQ physically requires more than the target. Total retention defaults to six hours with a 100 GB warm-disk budget. Warm IQ plus waterfall storage respects the configured disk budget and browser quota. IQ never enters localStorage; only per-lane preferences do. OPFS is origin-private storage on the browser client—not the RF appliance—and a storage fault degrades to bounded RAM while remaining explicit in the UI. Browser memory warnings are shown only when the client exposes a meaningful used/limit pair.

Pausing changes only the browser presentation source. Hardware routing, sample rate, tuner gain, PPM, and physical center remain live and read-only during historical review. The historical VFO can move anywhere its complete passband fits inside the selected acquisition segment. Playback uses source timestamps at one real-time rate and never silently catches or labels itself live.

When retention pressure reaches the investigated frame, the default policy protects that interval and stops recording newer live history. An optional protect-live policy returns presentation to live instead. Go Live preserves a continuous timeline when possible and clears/restarts it only after live history was deliberately sacrificed.

Consequences

One logical raw timeline supports pause, seek, historical tuning, audio, detection, classification, and protocol decoders without a parallel DSP implementation. Large recent histories intentionally consume substantial client memory, while longer histories primarily consume client-local browser storage. The UI must make Hot RAM Target/minimum conflicts, discarded live history, historical position, and acquisition containment explicit. A future durable recorder can export selected intervals, but persistence and SigMF capture are separate from this browser-RAM decision.