fix(cw): stop the decoder claiming a healthy signal it cannot hear

With tone shift off and the operator tuned outside 400-1200 Hz, the page did not
go quiet - it went confidently wrong. Three measurements, all reproduced against
the real spectrogram path:

estimatedPitch is (32 + loudestBin) * 12.5 - shiftHz with the bin confined to
0..64, so with no shift applied it can only ever report 400-1200 Hz. It cannot
express 1500 Hz, and it does not try: it publishes whichever window edge the
leakage piles against. For a 1500 Hz tone that is 1200 Hz.

That leakage is not faint. The waterfall normalises to the loudest value on
screen, so 50 of 65 bins clear the 0.06 draw threshold and the picture shows a
keyed-looking column pinned to the right edge - the 1200 Hz column runs 25 times
the 400 Hz one.

signalStrength is prominence over the window mean, so the same leakage scores
0.78 and paints the meter to 78% of full width.

So the operator got a strong-signal bar, a plausible 1200 Hz readout, a picture
that looked like a signal, and an empty transcript, with nothing saying why.

The scan that can see past the window now runs whether or not shifting is
enabled - it is the only measurement that can - and publishes through a new
detectedToneHz flow kept separate from estimatedPitch. Overloading the latter is
what let the 1200 Hz claim out in the first place, so the two meanings stay in
two flows. The shift decision still only happens when the setting is on. Cost is
one 121-bin scan every 2 s.

The meter now reads zero when a tone is out of range and not being shifted in: it
is a claim that something decodable is present, and in that state nothing is.

A line under the waterfall says which case the operator is in - the tone was
moved in, or it is out of range and tone shift is off, naming the frequency and
the remedy. Strings in all nine locales; feature:cw only had five, so values-es,
values-ru, values-si and values-uk are new, with the Turkish apostrophe escaped.

CwToneShifterTest pins the premise the hint rests on: that the scan reports tones
the model window excludes, at 120, 250, 1400 and 1500 Hz.
This commit is contained in:
mckero committed 2026-08-23 01:42:37 +00:00
1 parent 23f47d9122
commit 4cb03111bc
13 files changed
+125 -6

No files matched your search

@@ -43,9 +43,25 @@ interface ICwDecoder {
*/
val historyText: StateFlow<String>
/** Detected tone frequency in Hz, or null before a tone is found. */
/**
* Pitch of the tone the model is decoding, in Hz, or null before one is found.
*
* Derived from the spectrogram, so it can only ever report a frequency inside the
* model's analysis window. For the pitch of a tone the model cannot see, use
* [detectedToneHz].
*/
val estimatedPitch: StateFlow<Float?>
/**
* Pitch of the loudest tone in the raw audio, in Hz, or null when none stands out.
*
* Unlike [estimatedPitch] this is measured before any shifting and over the full
* audio bandwidth, so it can report a tone the model's window excludes — which is
* the only way to tell the operator that nothing is being decoded because their tone
* is out of range.
*/
val detectedToneHz: StateFlow<Float?>
/** Current shift applied to bring the tone into the model's window, 0f when idle. */
val activeShiftHz: StateFlow<Float>
@@ -94,6 +94,26 @@ class CwToneShifterTest {
}
}
/**
* The decoder runs this scan even with shifting switched off, purely to tell the
* operator why nothing is decoding. That only works if the scan reaches past the
* model's window: the spectrogram's own pitch readout cannot, being confined to the
* window by construction, and it reports edge leakage as though it were the tone.
*/
@Test
fun `the scan reports tones the model window excludes`() {
for (tone in listOf(120.0, 250.0, 1400.0, 1500.0)) {
val analysis = CwToneShifter.analyse(cwTone(tone), sampleRate)
val reported = analysis.toneHz
assertNotNull("$tone Hz went undetected, so the UI has nothing to report", reported)
assertEquals("$tone Hz was misreported", tone, reported!!.toDouble(), 30.0)
assertFalse(
"$tone Hz must read as outside the window",
CwToneShifter.isInsideWindow(reported)
)
}
}
/**
* The waterfall draws a marker at [CwToneShifter.TARGET_HZ] to show the operator where
* a shifted tone is being delivered. Moving the target outside the model's window, or