rdsclock 0.2.2__tar.gz → 0.3.0__tar.gz

{rdsclock-0.2.2 → rdsclock-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rdsclock
-Version: 0.2.2
+Version: 0.3.0
 Summary: Passive RDS Clock-Time receiver for FM via RTL-SDR, with multi-source consensus for GPS-denied environments
 Author-email: Mateusz Klatt <mateusz@klatt.ie>
 License-Expression: Apache-2.0
@@ -267,12 +267,12 @@ the local antenna picks up.
 
 ## Status
 
-- **0.2.2** — current release. Operator-facing polish: 250 kS/s SDR
-  captures can now play at 48 kHz audio via rational resampling, and
-  Programme Service names are displayed only after validation so
-  dynamic-PS stations do not show mixed scrolling fragments. Decoder
-  group counts and PI codes remain locked to the 0.2.1 baseline.
-  Pre-1.0; the CLI and on-disk formats may still change.
+- **0.3.0** — current release. The decoder now uses conservative
+  single-bit RDS block syndrome correction during IQ decode, allowing
+  weak captures to recover groups that previously failed when one bit
+  in a 104-bit group was wrong. Corrected groups are reported separately
+  from clean groups; group totals are intentionally not comparable with
+  0.2.x outputs. Pre-1.0; the CLI and on-disk formats may still change.
 - 240+ tests including a real-IQ regression backed by a 6 s capture
   of Polskie Radio Trójka 98.8 from Warsaw; line coverage **100 %**
   (tracked by SonarCloud).

{rdsclock-0.2.2 → rdsclock-0.3.0}/README.md

@@ -229,12 +229,12 @@ the local antenna picks up.
 
 ## Status
 
-- **0.2.2** — current release. Operator-facing polish: 250 kS/s SDR
-  captures can now play at 48 kHz audio via rational resampling, and
-  Programme Service names are displayed only after validation so
-  dynamic-PS stations do not show mixed scrolling fragments. Decoder
-  group counts and PI codes remain locked to the 0.2.1 baseline.
-  Pre-1.0; the CLI and on-disk formats may still change.
+- **0.3.0** — current release. The decoder now uses conservative
+  single-bit RDS block syndrome correction during IQ decode, allowing
+  weak captures to recover groups that previously failed when one bit
+  in a 104-bit group was wrong. Corrected groups are reported separately
+  from clean groups; group totals are intentionally not comparable with
+  0.2.x outputs. Pre-1.0; the CLI and on-disk formats may still change.
 - 240+ tests including a real-IQ regression backed by a 6 s capture
   of Polskie Radio Trójka 98.8 from Warsaw; line coverage **100 %**
   (tracked by SonarCloud).

{rdsclock-0.2.2 → rdsclock-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rdsclock"
-version = "0.2.2"
+version = "0.3.0"
 description = "Passive RDS Clock-Time receiver for FM via RTL-SDR, with multi-source consensus for GPS-denied environments"
 readme = "README.md"
 requires-python = ">=3.12"

{rdsclock-0.2.2 → rdsclock-0.3.0}/src/rdsclock/__init__.py

@@ -19,4 +19,4 @@ Modules:
                      scan / recon / demo.
 """
 
-__version__ = "0.2.2"
+__version__ = "0.3.0"

{rdsclock-0.2.2 → rdsclock-0.3.0}/src/rdsclock/decoder.py

@@ -11,7 +11,7 @@ from dataclasses import dataclass
 import numpy as np
 
 from . import dsp
-from .rds_blocks import find_groups_in_bitstream
+from .rds_blocks import _find_groups_in_bitstream_with_counts
 from .rds_clock import ClockTime
 from .rds_groups import StationInfo, parse_groups
 
@@ -25,6 +25,12 @@ class DecodeResult:
     n_bits: int
     freq_offset_hz: float
     symbol_offset: int
+    n_groups_clean: int = -1
+    n_groups_corrected: int = 0
+
+    def __post_init__(self) -> None:
+        if self.n_groups_clean < 0:
+            self.n_groups_clean = self.n_groups
 
     @property
     def clock_times(self) -> list[ClockTime]:
@@ -93,6 +99,8 @@ def decode_iq(
     emit(f"biphase matched filter + offset search (sps {sps})")
     matched = dsp.biphase_matched_filter(rds_sync, sps_bit=sps)
     best_groups: list[bytearray] | None = None
+    best_groups_clean = 0
+    best_groups_corrected = 0
     best_bits: np.ndarray | None = None
     variant_used = "biphase/none"
     sym_offset = 0
@@ -101,9 +109,18 @@ def decode_iq(
         if len(sampled) < 100:
             continue
         bits_candidate = dsp.bits_from_symbols_diff(sampled)
-        groups_candidate, variant_candidate = _best_variant_groups(bits_candidate)
-        if best_groups is None or len(groups_candidate) > len(best_groups):
+        (
+            groups_candidate,
+            variant_candidate,
+            groups_clean_candidate,
+            groups_corrected_candidate,
+        ) = _best_variant_groups(bits_candidate)
+        if best_groups is None or _group_score(
+            groups_candidate, groups_clean_candidate, groups_corrected_candidate
+        ) > _group_score(best_groups, best_groups_clean, best_groups_corrected):
             best_groups = groups_candidate
+            best_groups_clean = groups_clean_candidate
+            best_groups_corrected = groups_corrected_candidate
             best_bits = bits_candidate
             variant_used = f"biphase/off{offset}/{variant_candidate}"
             sym_offset = offset
@@ -114,28 +131,39 @@ def decode_iq(
         emit(f"clock recovery fallback: best_offset + mueller_muller (sps {sps})")
         bo_symbols, bo_sym_off = dsp.best_symbol_offset(rds_sync, sps=sps)
         bo_bits = dsp.bits_from_symbols_diff(bo_symbols)
-        bo_groups, bo_variant = _best_variant_groups(bo_bits)
+        bo_groups, bo_variant, bo_groups_clean, bo_groups_corrected = _best_variant_groups(bo_bits)
 
         mm_symbols = dsp.clock_recovery_mm(rds_sync, sps=sps)
         mm_bits = dsp.bits_from_symbols_diff(mm_symbols)
-        mm_groups, mm_variant = _best_variant_groups(mm_bits)
+        mm_groups, mm_variant, mm_groups_clean, mm_groups_corrected = _best_variant_groups(mm_bits)
 
-        if len(mm_groups) > len(bo_groups):
+        if _group_score(mm_groups, mm_groups_clean, mm_groups_corrected) > _group_score(
+            bo_groups, bo_groups_clean, bo_groups_corrected
+        ):
             groups = mm_groups
+            groups_clean = mm_groups_clean
+            groups_corrected = mm_groups_corrected
             variant_used = f"mm/{mm_variant}"
             bits = mm_bits
             sym_offset = -1  # MM has no fixed offset, only its mu state
         else:
             groups = bo_groups
+            groups_clean = bo_groups_clean
+            groups_corrected = bo_groups_corrected
             variant_used = f"bo/{bo_variant}"
             bits = bo_bits
             sym_offset = bo_sym_off
     else:
         groups = best_groups
+        groups_clean = best_groups_clean
+        groups_corrected = best_groups_corrected
         bits = best_bits
 
     info = parse_groups(groups)
-    emit(f"groups={len(groups)} variant={variant_used} freq_off={freq_off:+.1f} Hz")
+    emit(
+        f"groups={len(groups)} clean={groups_clean} corrected={groups_corrected} "
+        f"variant={variant_used} freq_off={freq_off:+.1f} Hz"
+    )
 
     return DecodeResult(
         info=info,
@@ -143,10 +171,18 @@ def decode_iq(
         n_bits=len(bits),
         freq_offset_hz=float(freq_off),
         symbol_offset=sym_offset,
+        n_groups_clean=groups_clean,
+        n_groups_corrected=groups_corrected,
     )
 
 
-def _best_variant_groups(bits: np.ndarray) -> tuple[list[bytearray], str]:
+def _group_score(
+    groups: list[bytearray], n_groups_clean: int, n_groups_corrected: int
+) -> tuple[int, int, int]:
+    return len(groups), n_groups_clean, -n_groups_corrected
+
+
+def _best_variant_groups(bits: np.ndarray) -> tuple[list[bytearray], str, int, int]:
     """Try the four bitstream polarity/order variants and return the one
     that yields the most groups.
 
@@ -163,12 +199,18 @@ def _best_variant_groups(bits: np.ndarray) -> tuple[list[bytearray], str]:
     ]
     best: list[bytearray] = []
     best_name = "normal"
+    best_clean = 0
+    best_corrected = 0
     for name, bstream in candidates:
-        g = find_groups_in_bitstream(np.ascontiguousarray(bstream))
-        if len(g) > len(best):
+        g, n_clean, n_corrected = _find_groups_in_bitstream_with_counts(
+            np.ascontiguousarray(bstream), tolerate_single_bit=True
+        )
+        if _group_score(g, n_clean, n_corrected) > _group_score(best, best_clean, best_corrected):
             best = g
             best_name = name
-    return best, best_name
+            best_clean = n_clean
+            best_corrected = n_corrected
+    return best, best_name, best_clean, best_corrected
 
 
 def decode_file(

{rdsclock-0.2.2 → rdsclock-0.3.0}/src/rdsclock/rds_blocks.py

@@ -46,6 +46,9 @@ _DATA_WORD_MASK = (1 << DATA_BITS) - 1
 _CRC_TOP_BIT = 1 << CRC_BITS
 _CRC_POLY_WITH_TOP_BIT = CRC_POLY | _CRC_TOP_BIT
 _BLOCK_WEIGHTS = (1 << np.arange(BLOCK_BITS - 1, -1, -1, dtype=np.uint32)).astype(np.uint32)
+_DATA_BIT_CORRECTION_MASKS = (1 << np.arange(DATA_BITS - 1, -1, -1, dtype=np.uint32)).astype(
+    np.uint32
+)
 
 
 def _build_crc10_table() -> np.ndarray:
@@ -93,7 +96,39 @@ def block_checkword(block26: int) -> int:
     return block26 & _BLOCK_WORD_MASK
 
 
-def block_valid(block26: int, block_no: int, version_b: bool | None = None) -> bool:
+def _block_syndrome(block26: int, offset_word: int) -> int:
+    data = block_dataword(block26)
+    return block_checkword(block26) ^ offset_word ^ crc10(data)
+
+
+def _build_single_bit_syndrome_table() -> dict[int, int]:
+    table: dict[int, int] = {}
+    clean = encode_block(0, OFFSET_A)
+    for pos in range(BLOCK_BITS):
+        corrupted = clean ^ (1 << (BLOCK_BITS - 1 - pos))
+        syndrome = _block_syndrome(corrupted, OFFSET_A)
+        if syndrome == 0 or syndrome in table:
+            raise RuntimeError(f"non-unique RDS single-bit syndrome at position {pos}")
+        table[syndrome] = pos
+    return table
+
+
+_SINGLE_BIT_SYNDROME_TABLE = _build_single_bit_syndrome_table()
+_SINGLE_BIT_SYNDROME_LOOKUP = np.full(1 << CRC_BITS, -1, dtype=np.int8)
+for _syndrome, _position in _SINGLE_BIT_SYNDROME_TABLE.items():
+    _SINGLE_BIT_SYNDROME_LOOKUP[_syndrome] = _position
+
+
+def _single_bit_error_position(block26: int, offset_word: int) -> int:
+    return _SINGLE_BIT_SYNDROME_TABLE.get(_block_syndrome(block26, offset_word), -1)
+
+
+def block_valid(
+    block26: int,
+    block_no: int,
+    version_b: bool | None = None,
+    correct_single_bit: bool = False,
+) -> bool:
     """Return True if a 26-bit word is a valid block at the given position 0..3.
 
     For block C (index 2):
@@ -104,16 +139,26 @@ def block_valid(block26: int, block_no: int, version_b: bool | None = None) -> b
     """
     if not 0 <= block_no < GROUP_BLOCKS:
         raise ValueError(f"block_no out of [0..3]: {block_no}")
-    data = block_dataword(block26)
-    expected = crc10(data)
-    received = block_checkword(block26)
     if block_no == 2:
         if version_b is True:
-            return (received ^ OFFSET_C_PRIME) == expected
-        if version_b is False:
-            return (received ^ OFFSET_C) == expected
-        return (received ^ OFFSET_C) == expected or (received ^ OFFSET_C_PRIME) == expected
-    return (received ^ OFFSETS[block_no]) == expected
+            offset_words = (OFFSET_C_PRIME,)
+        elif version_b is False:
+            offset_words = (OFFSET_C,)
+        else:
+            offset_words = (OFFSET_C, OFFSET_C_PRIME)
+    else:
+        offset_words = (OFFSETS[block_no],)
+
+    for offset_word in offset_words:
+        if _block_syndrome(block26, offset_word) == 0:
+            return True
+
+    if correct_single_bit:
+        for offset_word in offset_words:
+            if _single_bit_error_position(block26, offset_word) >= 0:
+                return True
+
+    return False
 
 
 def encode_group(words: Sequence[int], version_b: bool = False) -> list[int]:
@@ -161,20 +206,44 @@ def _coerce_bits(bits: np.ndarray) -> np.ndarray:
     return np.bitwise_and(bits, 1)
 
 
-def find_groups_in_bitstream(bits: np.ndarray) -> list[bytearray]:
+def _correct_datawords(datawords: np.ndarray, error_positions: np.ndarray) -> np.ndarray:
+    corrected = np.asarray(datawords, dtype=np.uint32).copy()
+    data_errors = (error_positions >= 0) & (error_positions < DATA_BITS)
+    if np.any(data_errors):
+        corrected[data_errors] ^= _DATA_BIT_CORRECTION_MASKS[error_positions[data_errors]]
+    return corrected
+
+
+def _drop_corrected_starts_overlapping_clean(
+    group_starts: np.ndarray, correction_counts: np.ndarray
+) -> np.ndarray:
+    clean_starts = group_starts[correction_counts[group_starts] == 0]
+    corrected_starts = group_starts[correction_counts[group_starts] > 0]
+    if len(clean_starts) == 0 or len(corrected_starts) == 0:
+        return group_starts
+
+    left = np.searchsorted(clean_starts, corrected_starts - GROUP_BITS + 1, side="left")
+    right = np.searchsorted(clean_starts, corrected_starts + GROUP_BITS, side="left")
+    corrected_without_clean_overlap = corrected_starts[left == right]
+    return np.sort(np.concatenate((clean_starts, corrected_without_clean_overlap)))
+
+
+def _find_groups_in_bitstream_with_counts(
+    bits: np.ndarray, tolerate_single_bit: bool = False
+) -> tuple[list[bytearray], int, int]:
     """Slide over a bitstream and extract groups of 4 consecutively valid blocks.
 
     Enforces version consistency: if block B advertises Version A,
     block C must use offset C; for Version B, block 3 must use offset C'.
     This significantly reduces false-positive group matches on weak streams.
 
-    Returns a list of 8-byte bytearrays (4 × big-endian 16-bit datawords).
+    Returns 8-byte bytearrays plus clean/corrected group counters.
     """
     bits = _coerce_bits(bits)
     n = len(bits)
     groups: list[bytearray] = []
     if n < GROUP_BITS:
-        return groups
+        return groups, 0, 0
 
     windows = np.lib.stride_tricks.sliding_window_view(bits, BLOCK_BITS)
     words = _bits_to_words_26(windows, assume_binary=True)
@@ -189,32 +258,111 @@ def find_groups_in_bitstream(bits: np.ndarray) -> list[bytearray]:
     valid_d = (check ^ OFFSET_D) == expected
 
     start_count = n - GROUP_BITS + 1
-    block_b_data = data[BLOCK_BITS : BLOCK_BITS + start_count]
+    block_b_slice = slice(BLOCK_BITS, BLOCK_BITS + start_count)
+    block_b_data = data[block_b_slice]
+    correction_counts = np.zeros(start_count, dtype=np.uint8)
+    error_positions_by_block: tuple[np.ndarray, ...] = ()
+
+    if tolerate_single_bit:
+        syndrome_a = check ^ OFFSET_A ^ expected
+        syndrome_b = check ^ OFFSET_B ^ expected
+        syndrome_c = check ^ OFFSET_C ^ expected
+        syndrome_c_prime = check ^ OFFSET_C_PRIME ^ expected
+        syndrome_d = check ^ OFFSET_D ^ expected
+
+        error_pos_a_all = _SINGLE_BIT_SYNDROME_LOOKUP[syndrome_a]
+        error_pos_b_all = _SINGLE_BIT_SYNDROME_LOOKUP[syndrome_b]
+        error_pos_c_all = _SINGLE_BIT_SYNDROME_LOOKUP[syndrome_c]
+        error_pos_c_prime_all = _SINGLE_BIT_SYNDROME_LOOKUP[syndrome_c_prime]
+        error_pos_d_all = _SINGLE_BIT_SYNDROME_LOOKUP[syndrome_d]
+
+        error_pos_a = error_pos_a_all[:start_count]
+        error_pos_b = error_pos_b_all[block_b_slice]
+        block_b_data = _correct_datawords(block_b_data, error_pos_b)
+    else:
+        error_pos_a = np.empty(0, dtype=np.int8)
+        error_pos_b = np.empty(0, dtype=np.int8)
+
     version_b = ((block_b_data >> 11) & 1).astype(bool)
     block_c_valid = np.where(
         version_b,
         valid_c_prime[2 * BLOCK_BITS : 2 * BLOCK_BITS + start_count],
         valid_c[2 * BLOCK_BITS : 2 * BLOCK_BITS + start_count],
     )
-    group_starts = np.flatnonzero(
-        valid_a[:start_count]
-        & valid_b[BLOCK_BITS : BLOCK_BITS + start_count]
-        & block_c_valid
-        & valid_d[3 * BLOCK_BITS : 3 * BLOCK_BITS + start_count]
-    )
+    if tolerate_single_bit:
+        error_pos_c = np.where(
+            version_b,
+            error_pos_c_prime_all[2 * BLOCK_BITS : 2 * BLOCK_BITS + start_count],
+            error_pos_c_all[2 * BLOCK_BITS : 2 * BLOCK_BITS + start_count],
+        )
+        error_pos_d = error_pos_d_all[3 * BLOCK_BITS : 3 * BLOCK_BITS + start_count]
+        block_a_clean = valid_a[:start_count]
+        block_b_clean = valid_b[block_b_slice]
+        block_d_clean = valid_d[3 * BLOCK_BITS : 3 * BLOCK_BITS + start_count]
+        block_a_corrected = error_pos_a >= 0
+        block_b_corrected = error_pos_b >= 0
+        block_c_corrected = error_pos_c >= 0
+        block_d_corrected = error_pos_d >= 0
+        correction_counts = (
+            block_a_corrected.astype(np.uint8)
+            + block_b_corrected.astype(np.uint8)
+            + block_c_corrected.astype(np.uint8)
+            + block_d_corrected.astype(np.uint8)
+        )
+        group_starts = np.flatnonzero(
+            (block_a_clean | block_a_corrected)
+            & (block_b_clean | block_b_corrected)
+            & (block_c_valid | block_c_corrected)
+            & (block_d_clean | block_d_corrected)
+            & (correction_counts <= 1)
+        )
+        group_starts = _drop_corrected_starts_overlapping_clean(group_starts, correction_counts)
+        error_positions_by_block = (error_pos_a, error_pos_b, error_pos_c, error_pos_d)
+    else:
+        group_starts = np.flatnonzero(
+            valid_a[:start_count]
+            & valid_b[block_b_slice]
+            & block_c_valid
+            & valid_d[3 * BLOCK_BITS : 3 * BLOCK_BITS + start_count]
+        )
 
     next_scan_start = 0
+    n_groups_clean = 0
+    n_groups_corrected = 0
     group_offsets = np.array([0, BLOCK_BITS, 2 * BLOCK_BITS, 3 * BLOCK_BITS], dtype=np.intp)
     for start in group_starts:
         group_start = int(start)
         if group_start >= next_scan_start:
+            datawords = data[group_start + group_offsets].astype(np.uint32, copy=True)
+            corrected_count = int(correction_counts[group_start])
+            if corrected_count:
+                for idx, error_positions in enumerate(error_positions_by_block):
+                    error_pos = int(error_positions[group_start])
+                    if 0 <= error_pos < DATA_BITS:
+                        datawords[idx] ^= _DATA_BIT_CORRECTION_MASKS[error_pos]
+                n_groups_corrected += 1
+            else:
+                n_groups_clean += 1
             buf = bytearray(8)
-            for idx, dw_raw in enumerate(data[group_start + group_offsets]):
+            for idx, dw_raw in enumerate(datawords):
                 dw = int(dw_raw)
                 buf[idx * 2] = (dw >> 8) & 0xFF
                 buf[idx * 2 + 1] = dw & 0xFF
             groups.append(buf)
             next_scan_start = group_start + GROUP_BITS
+    return groups, n_groups_clean, n_groups_corrected
+
+
+def find_groups_in_bitstream(
+    bits: np.ndarray, tolerate_single_bit: bool = False
+) -> list[bytearray]:
+    """Slide over a bitstream and extract groups of 4 consecutively valid blocks.
+
+    By default every block must pass CRC exactly. When ``tolerate_single_bit``
+    is true, a group may contain one block whose syndrome identifies a single
+    flipped bit; groups requiring two or more block corrections are dropped.
+    """
+    groups, _, _ = _find_groups_in_bitstream_with_counts(bits, tolerate_single_bit)
     return groups
 
 

{rdsclock-0.2.2 → rdsclock-0.3.0}/src/rdsclock.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rdsclock
-Version: 0.2.2
+Version: 0.3.0
 Summary: Passive RDS Clock-Time receiver for FM via RTL-SDR, with multi-source consensus for GPS-denied environments
 Author-email: Mateusz Klatt <mateusz@klatt.ie>
 License-Expression: Apache-2.0
@@ -267,12 +267,12 @@ the local antenna picks up.
 
 ## Status
 
-- **0.2.2** — current release. Operator-facing polish: 250 kS/s SDR
-  captures can now play at 48 kHz audio via rational resampling, and
-  Programme Service names are displayed only after validation so
-  dynamic-PS stations do not show mixed scrolling fragments. Decoder
-  group counts and PI codes remain locked to the 0.2.1 baseline.
-  Pre-1.0; the CLI and on-disk formats may still change.
+- **0.3.0** — current release. The decoder now uses conservative
+  single-bit RDS block syndrome correction during IQ decode, allowing
+  weak captures to recover groups that previously failed when one bit
+  in a 104-bit group was wrong. Corrected groups are reported separately
+  from clean groups; group totals are intentionally not comparable with
+  0.2.x outputs. Pre-1.0; the CLI and on-disk formats may still change.
 - 240+ tests including a real-IQ regression backed by a 6 s capture
   of Polskie Radio Trójka 98.8 from Warsaw; line coverage **100 %**
   (tracked by SonarCloud).

{rdsclock-0.2.2 → rdsclock-0.3.0}/tests/test_coverage_extra.py

@@ -186,6 +186,8 @@ class TestDecoderCoverage:
             symbol_offset=0,
         )
         assert result.clock_times == [clock]
+        assert result.n_groups_clean == 1
+        assert result.n_groups_corrected == 0
 
     def test_decode_iq_uses_default_carrier_when_auto_disabled(self, monkeypatch):
         monkeypatch.setattr(decoder.dsp, "channel_filter", lambda iq, fs: iq)
@@ -208,7 +210,7 @@ class TestDecoderCoverage:
         monkeypatch.setattr(
             decoder.dsp, "clock_recovery_mm", lambda data, sps: np.zeros(0, dtype=np.complex64)
         )
-        monkeypatch.setattr(decoder, "_best_variant_groups", lambda bits: ([], "normal"))
+        monkeypatch.setattr(decoder, "_best_variant_groups", lambda bits: ([], "normal", 0, 0))
         monkeypatch.setattr(decoder, "parse_groups", lambda groups: StationInfo())
 
         decoder.decode_iq(np.ones(65, dtype=np.complex64), auto_carrier=False)
@@ -238,8 +240,8 @@ class TestDecoderCoverage:
         )
         variants = iter(
             [
-                ([], "bo"),
-                ([bytearray(b"\x00" * 8)], "mm"),
+                ([], "bo", 0, 0),
+                ([bytearray(b"\x00" * 8)], "mm", 1, 0),
             ]
         )
         monkeypatch.setattr(decoder, "_best_variant_groups", lambda bits: next(variants))
@@ -248,6 +250,8 @@ class TestDecoderCoverage:
         result = decoder.decode_iq(np.ones(65, dtype=np.complex64), auto_carrier=False)
 
         assert result.n_groups == 1
+        assert result.n_groups_clean == 1
+        assert result.n_groups_corrected == 0
         assert result.symbol_offset == -1
 
     def test_decode_file_autodetects_u8_when_complex_sniff_is_invalid(self, monkeypatch):

{rdsclock-0.2.2 → rdsclock-0.3.0}/tests/test_rds_blocks.py

@@ -1,8 +1,11 @@
 """Tests for the block layer: CRC, block encode/decode, syndromes, bitstream."""
 
 import numpy as np
+import pytest
 
+import rdsclock.rds_blocks as rds_blocks
 from rdsclock.rds_blocks import (
+    _SINGLE_BIT_SYNDROME_TABLE,
     BLOCK_BITS,
     DATA_BITS,
     GROUP_BITS,
@@ -12,6 +15,8 @@ from rdsclock.rds_blocks import (
     OFFSETS,
     _bits_to_words_26,
     _crc10_many,
+    _drop_corrected_starts_overlapping_clean,
+    _find_groups_in_bitstream_with_counts,
     bits_to_word,
     block_dataword,
     block_valid,
@@ -112,6 +117,32 @@ class TestEncodeBlock:
         assert block_valid(blk_c, 2)
         assert block_valid(blk_c_prime, 2)
 
+    def test_single_bit_syndrome_table_covers_block_positions(self):
+        assert len(_SINGLE_BIT_SYNDROME_TABLE) == BLOCK_BITS
+        assert set(_SINGLE_BIT_SYNDROME_TABLE.values()) == set(range(BLOCK_BITS))
+        assert 0 not in _SINGLE_BIT_SYNDROME_TABLE
+
+    def test_single_bit_syndrome_table_rejects_collisions(self, monkeypatch):
+        monkeypatch.setattr(rds_blocks, "_block_syndrome", lambda block, offset: 1)
+        with pytest.raises(RuntimeError, match="non-unique"):
+            rds_blocks._build_single_bit_syndrome_table()
+
+    def test_block_valid_can_accept_one_single_bit_error_when_requested(self):
+        data = 0xBEEF
+        blk = encode_block(data, OFFSET_A)
+        corrupted_data = blk ^ (1 << (BLOCK_BITS - 1 - 3))
+        corrupted_crc = blk ^ (1 << (BLOCK_BITS - 1 - 20))
+        corrupted_double = corrupted_data ^ (1 << (BLOCK_BITS - 1 - 20))
+
+        assert not block_valid(corrupted_data, 0)
+        assert block_valid(corrupted_data, 0, correct_single_bit=True)
+        assert block_valid(corrupted_crc, 0, correct_single_bit=True)
+        assert not block_valid(corrupted_double, 0, correct_single_bit=True)
+
+        blk_c_prime = encode_block(data, OFFSET_C_PRIME)
+        corrupted_c_prime = blk_c_prime ^ (1 << (BLOCK_BITS - 1 - 4))
+        assert block_valid(corrupted_c_prime, 2, correct_single_bit=True)
+
 
 class TestEncodeGroup:
     def test_basic_a_version(self):
@@ -188,6 +219,69 @@ class TestBitstream:
     def test_find_groups_short_stream_returns_empty(self):
         assert find_groups_in_bitstream(np.zeros(GROUP_BITS - 1, dtype=np.uint8)) == []
 
+    def test_find_groups_can_recover_one_corrupted_data_bit(self):
+        words = (0xCAFE, 0x4000, 0x1234, 0x5678)
+        bits = blocks_to_bits(encode_group(words)).copy()
+        bits[BLOCK_BITS + 4] ^= 1  # block B version bit: raw data would select C'.
+
+        assert find_groups_in_bitstream(bits) == []
+        groups, n_clean, n_corrected = _find_groups_in_bitstream_with_counts(
+            bits, tolerate_single_bit=True
+        )
+
+        assert n_clean == 0
+        assert n_corrected == 1
+        assert len(groups) == 1
+        assert group_bytes_to_words(groups[0]) == words
+
+    def test_find_groups_can_recover_one_corrupted_crc_bit_without_changing_data(self):
+        words = (0xCAFE, 0x4000, 0x1234, 0x5678)
+        bits = blocks_to_bits(encode_group(words)).copy()
+        bits[3 * BLOCK_BITS + 20] ^= 1
+
+        groups = find_groups_in_bitstream(bits, tolerate_single_bit=True)
+
+        assert len(groups) == 1
+        assert group_bytes_to_words(groups[0]) == words
+
+    def test_find_groups_drops_candidates_requiring_two_corrections(self):
+        bits = blocks_to_bits(encode_group((0xCAFE, 0x4000, 0x1234, 0x5678))).copy()
+        bits[3] ^= 1
+        bits[3 * BLOCK_BITS + 20] ^= 1
+
+        groups, n_clean, n_corrected = _find_groups_in_bitstream_with_counts(
+            bits, tolerate_single_bit=True
+        )
+
+        assert groups == []
+        assert n_clean == 0
+        assert n_corrected == 0
+
+    def test_corrected_group_starts_do_not_displace_overlapping_clean_starts(self):
+        correction_counts = np.zeros(400, dtype=np.uint8)
+        correction_counts[[40, 260]] = 1
+        starts = np.array([40, 120, 260], dtype=np.intp)
+
+        filtered = _drop_corrected_starts_overlapping_clean(starts, correction_counts)
+
+        np.testing.assert_array_equal(filtered, np.array([120, 260], dtype=np.intp))
+        np.testing.assert_array_equal(
+            _drop_corrected_starts_overlapping_clean(
+                np.array([40], dtype=np.intp), correction_counts
+            ),
+            np.array([40], dtype=np.intp),
+        )
+
+    def test_find_groups_tolerant_mode_rejects_random_noise_smoke(self):
+        """Single-bit correction must not turn random noise into many fake groups."""
+        noise = np.random.RandomState(42).randint(0, 2, size=10_000).astype(np.uint8)
+        groups, n_clean, n_corrected = _find_groups_in_bitstream_with_counts(
+            noise, tolerate_single_bit=True
+        )
+
+        assert len(groups) < 10
+        assert n_clean + n_corrected == len(groups)
+
 
 class TestDifferential:
     def test_roundtrip(self):

{rdsclock-0.2.2 → rdsclock-0.3.0}/tests/test_real_iq_regression.py

@@ -13,6 +13,8 @@ FIXTURE = Path(__file__).parent / "fixtures" / "trojka_98p8_6s_250k_u8.iq"
 def test_trojka_98p8_real_iq_decodes_groups_and_polskie_radio_pi():
     result = decode_file(str(FIXTURE), fs=250_000, fmt="u8")
 
-    assert result.n_groups >= 10
+    assert result.n_groups_clean + result.n_groups_corrected == result.n_groups
+    assert result.n_groups_clean + result.n_groups_corrected >= 30
+    assert result.n_groups_corrected < result.n_groups_clean * 0.5
     assert result.info.pi is not None
     assert (result.info.pi & 0xFF00) == 0x3200