Look4Sat-mckero/feature/cw/DEEPCW.md

DeepCW Decoder — module documentation

The feature:cw module decodes Morse code (CW) with the DeepCW neural model instead of a classical DSP detector. This document records the architecture, the model provenance, the pitfalls we hit on real devices, and the verification results. It exists so the next person does not have to re-derive any of it.

Architecture

microphone (44.1 kHz PCM float)
        │  AudioCapture.audioFlow()  → ~100 ms chunks
        ▼
CwDecodeScreen (feature:cw, pure Compose)
        │  decoder.processBuffer(chunk)      waterfall.pushSamples(chunk)
        ▼                                    ▼
CwDeepDecoder (core:data)             CwWaterfallState (feature:cw)
   resample → 3200 Hz                    resample → 3200 Hz
   CwDeepBuffer (20 s rolling)           CwDeepSpectrogram.compute
   CwDeepSpectrogram.compute             → rolling spectrogram history
   ONNX Runtime session.run             → Canvas waterfall
   CwCtcDecoder.greedy                  (400–1200 Hz band, same magnitudes
   → decodedText StateFlow               the model sees)

Why the split. core:domain must stay pure Kotlin/JVM (KMP migration headroom, per AGENTS.md), so the ONNX Runtime dependency — which ships native libraries — lives in core:data behind the ICwDecoder interface. The spectrogram front-end (CwDeepSpectrogram) and CTC collapse (CwCtcDecoder) are pure Kotlin and live in core:domain, where they are unit-tested against the Python reference with golden vectors.

Streaming model, not incremental. DeepCW is a whole-utterance CTC model. It rewrites earlier characters as more context arrives, so incremental appending is wrong. The decoder keeps a rolling buffer capped at 20 s and re-runs the whole window every 1.5 s, replacing the displayed text outright. 20 s is the smallest window that hits 0 % CER on the reference clip and the largest that keeps inference comfortably faster than real time (measured ~14× headroom on a server CPU; timed per-window on device and reported via lastInferenceMs).

Model

	fp32 (original)	int8 (shipped)
Size	15,139,839 bytes	4,248,808 bytes
Derivation	—	quantize_dynamic (weights → QUInt8, activations float32)
Input	spectrogram [1,1,T,65] float32	unchanged
Output	log_probs [1,T,42] float32	unchanged
In APK	no (available as a release asset)	yes (assets/deepcw/model.onnx)

The int8 model ships inside the APK: it is ~4× smaller and measurably identical to fp32 on synthetic CW at SNR ≥ −4 dB (both degrade together below that). The fp32 model is published as a separate release asset for anyone who wants the highest-fidelity reference. Both are AGPL-3.0-only — see licenses/NOTICE.md for provenance, commit SHA and hashes.

Audio must be packaged uncompressed (noCompress += "onnx" in the app module): ONNX Runtime mmap's assets and refuses compressed ones.

Pitfalls fixed on real devices (release-only)

1. R8 minification breaks the JNI binding. isMinifyEnabled = true in the convention plugin, but onnxruntime-android ships no consumer ProGuard rules, so ai.onnxruntime.* got renamed and native code crashed with no Java stack trace. Fixed with -keep class ai.onnxruntime.** { *; } in app/proguard-rules.pro. Symptom was the exact "flash to home screen, empty crash log" we chased.
2. Model load in init{} took down the whole composable on failure; moved to lazy ensureLoaded() with an errorMessage path.
3. Default thread count saturated all cores and starved audio capture/UI; capped setIntraOpNumThreads to cores−1 (max 4).
4. Compose snapshot state written from the audio thread crashes at runtime with no log from business-class instrumentation; the waterfall now uses a MutableStateFlow revision counter, and both the row deque and the pending buffer are lock-guarded.
5. LaunchedEffect { launch { collect() } } leaked a second AudioRecord when toggling; collection now runs directly in the effect body keyed on (isListening, permissionGranted).

Diagnostics (no-adb): MainApplication already writes uncaught exceptions to files/crash_log.txt. The decoder additionally persists load/inference failures to files/deepcw_load_error.txt / files/deepcw_infer_error.txt and step markers to files/probe_cw.txt (load_begin → load_session_ok → infer_begin → infer_done).

Verification

• Golden vectors: CwDeepSpectrogramTest + CwDeepGoldenVectorTest pin the Kotlin spectrogram to the Python reference across 5005 values (tolerance 1e-4). 79 domain tests pass.
• End-to-end on server: real 20 s noisy CW audio → resample → spectrogram → ONNX → greedy CTC reproduces CQ CQ DE BG7NTA BG7NTA K 5NN TU 73 character-for-character (~1 s inference, fp32).
• On device (release APK): decodes 40 WPM CW at high accuracy. Some UI latency is expected on the first decode cycle (model load + first inference); sustained decoding stays real-time.