dtmb-sdr 0.2.0__tar.gz

dtmb_sdr-0.2.0/.gitignore

@@ -0,0 +1,28 @@
+__pycache__/
+*.py[cod]
+*.pyd
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+.mamba-env/
+.conda-pkgs/
+
+build/
+out/
+dist/
+*.egg-info/
+
+*.iq
+*.cfile
+*.cf32
+*.ci8
+*.ts
+
+captures/*
+!captures/README.md
+test_vectors/*
+!test_vectors/README.md
+scan_results/
+.DS_Store

dtmb_sdr-0.2.0/.pytest_cache/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

dtmb_sdr-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ning
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dtmb_sdr-0.2.0/Makefile

@@ -0,0 +1,18 @@
+PYTHON ?= python
+CMAKE ?= cmake
+BUILD_DIR ?= build/core-cpp
+
+.PHONY: configure build test install
+
+configure:
+	$(CMAKE) -S core/cpp -B $(BUILD_DIR) -DDTMB_CORE_BUILD_TESTS=ON
+
+build: configure
+	$(CMAKE) --build $(BUILD_DIR) --config Release
+
+test: build
+	ctest --test-dir $(BUILD_DIR) -C Release --output-on-failure
+	$(PYTHON) -m pytest tests
+
+install:
+	$(PYTHON) -m pip install -e .

dtmb_sdr-0.2.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.2
+Name: dtmb-sdr
+Version: 0.2.0
+Summary: Vendor-neutral CI8 stream to MPEG-TS DTMB receiver
+Author: dtmb-sdr contributors
+License: MIT License
+         
+         Copyright (c) 2026 Ning
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+         
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Description-Content-Type: text/markdown
+
+# dtmb-sdr
+
+A minimal, vendor-neutral DTMB receiver. It accepts interleaved signed 8-bit
+complex samples (CI8) from a file or standard input and emits MPEG transport
+stream packets to a file or standard output.
+
+```text
+CI8 file/stdin
+  -> sample-rate conversion
+  -> PN945 synchronization and C=3780 equalization
+  -> QAM64 deinterleaving and soft demapping
+  -> LDPC, BCH, and descrambling
+  -> MPEG-TS file/stdout
+```
+
+Hardware acquisition is intentionally outside this repository. Any application
+that can produce CI8 bytes at a known sample rate can feed the receiver.
+
+## Build
+
+Requirements are CMake 3.20+, a C++20 compiler, and Python 3.10+.
+
+For a released platform wheel, installation is simply:
+
+```bash
+pip install dtmb-sdr
+```
+
+The wheel contains the native receiver executables and required LDPC data; no
+separate source checkout or CMake build is required.
+
+To build from a source checkout:
+
+```bash
+python -m pip install -e ".[dev]"
+cmake -S core/cpp -B build/core-cpp -DDTMB_CORE_BUILD_TESTS=ON
+cmake --build build/core-cpp --config Release
+ctest --test-dir build/core-cpp -C Release --output-on-failure
+pytest
+```
+
+Build a distributable wheel with:
+
+```bash
+python -m build --wheel
+```
+
+Standard PyPI wheels use the portable CPU decoder. CUDA is intentionally an
+explicit source-build option because CUDA toolkit and GPU architecture support
+are platform-specific.
+
+## Decode a CI8 file
+
+```bash
+dtmb-decode \
+  --input capture.ci8 \
+  --input-rate 16000000 \
+  --output recovered.ts \
+  --acceleration cpu \
+  --error-policy continue
+```
+
+The default profile is QAM64, FEC rate 0.6, interleaver mode 2
+(`--system-info-index 22`). Profiles 19 through 24 select the supported QAM64
+FEC/interleaver combinations.
+
+Strict mode is the default. `--error-policy continue` omits unclean frames and
+adds MPEG-TS discontinuity indications before later clean output.
+
+## Optional CUDA LDPC acceleration
+
+CPU decoding is the portable baseline. Build the optional CUDA LDPC backend
+when a supported NVIDIA toolchain is available:
+
+```bash
+cmake -S core/cpp -B build/core-cpp-cuda \
+  -DDTMB_CORE_ENABLE_CUDA_LDPC=ON \
+  -DDTMB_CORE_BUILD_TESTS=ON
+cmake --build build/core-cpp-cuda --config Release
+```
+
+Then select it explicitly:
+
+```bash
+dtmb-decode \
+  --bin-dir build/core-cpp-cuda \
+  --input capture.ci8 \
+  --input-rate 16000000 \
+  --output recovered.ts \
+  --acceleration cuda
+```
+
+The CUDA backend batches LDPC codewords and reports host-to-device, kernel,
+device-to-host, and total timing metrics. CPU remains available as the
+correctness and portability reference.
+
+### Parallelism and observed acceleration
+
+The receiver uses independent concurrency at several stages:
+
+- multithreaded rational resampling and PN acquisition;
+- worker-parallel C=3780 frame equalization;
+- chunked QAM64 deinterleaving and soft demapping;
+- batched LDPC decoding on either CPU workers or CUDA kernels.
+
+One observed live-pipeline comparison used 12 CPU workers and 256-frame FEC
+batches. The CPU path processed 198,660 codewords in 30.95 seconds of measured
+FEC batch time (about 6,419 codewords/s). The CUDA path processed 267,486
+codewords in 17.22 seconds of measured FEC batch time (about 15,534
+codewords/s), while 10.41 seconds were attributed to CUDA transfer plus kernel
+execution. After normalizing by processed codewords, the observed FEC-stage
+throughput improvement was approximately 2.4x.
+
+These runs did not use an identical retained LLR stream, so the figure is an
+operational observation rather than a controlled cross-machine benchmark.
+Performance depends on the proportion of early-rejected codewords, iteration
+count, batch size, CPU, GPU, and memory-transfer overhead. Reproducible release
+claims should use the same retained LLR input and compare byte-identical output.
+
+## Decode a pipe
+
+Use `-` for stdin or stdout:
+
+```bash
+ci8-producing-command |
+  dtmb-decode --input - --input-rate 16000000 --output recovered.ts
+```
+
+The source command is deliberately unspecified: the receiver depends only on
+the byte-stream contract, not an SDR vendor or device API.
+
+## Play while decoding
+
+With ffplay:
+
+```bash
+ci8-producing-command |
+  dtmb-decode --input - --input-rate 16000000 --output - --error-policy continue |
+  ffplay -fflags nobuffer -flags low_delay -f mpegts -
+```
+
+With VLC:
+
+```bash
+ci8-producing-command |
+  dtmb-decode --input - --input-rate 16000000 --output - --error-policy continue |
+  vlc - --demux=ts
+```
+
+Playback quality depends on RF quality and FEC cleanliness. A player detecting
+a service is not evidence that the complete stream is error-free.
+
+## Inspect MPEG-TS output
+
+```bash
+dtmb-ts-analyze recovered.ts
+ffprobe -v error -show_programs -show_streams recovered.ts
+```
+
+## Scope
+
+Included:
+
+- portable C++20 receive stages;
+- CI8 file and stdin integration;
+- MPEG-TS file and stdout output;
+- required LDPC matrices;
+- core and pipeline-construction tests.
+
+Not included:
+
+- SDR drivers or hardware-control code;
+- capture recipes, device identifiers, frequencies, gains, or locations;
+- signal-generation, scanning, UI, visualization, sweep, or research tooling;
+- real broadcast captures or derived analysis artifacts.
+
+## License
+
+MIT. See [LICENSE](LICENSE) and [THIRD_PARTY.md](THIRD_PARTY.md).

dtmb_sdr-0.2.0/README.md

@@ -0,0 +1,179 @@
+# dtmb-sdr
+
+A minimal, vendor-neutral DTMB receiver. It accepts interleaved signed 8-bit
+complex samples (CI8) from a file or standard input and emits MPEG transport
+stream packets to a file or standard output.
+
+```text
+CI8 file/stdin
+  -> sample-rate conversion
+  -> PN945 synchronization and C=3780 equalization
+  -> QAM64 deinterleaving and soft demapping
+  -> LDPC, BCH, and descrambling
+  -> MPEG-TS file/stdout
+```
+
+Hardware acquisition is intentionally outside this repository. Any application
+that can produce CI8 bytes at a known sample rate can feed the receiver.
+
+## Build
+
+Requirements are CMake 3.20+, a C++20 compiler, and Python 3.10+.
+
+For a released platform wheel, installation is simply:
+
+```bash
+pip install dtmb-sdr
+```
+
+The wheel contains the native receiver executables and required LDPC data; no
+separate source checkout or CMake build is required.
+
+To build from a source checkout:
+
+```bash
+python -m pip install -e ".[dev]"
+cmake -S core/cpp -B build/core-cpp -DDTMB_CORE_BUILD_TESTS=ON
+cmake --build build/core-cpp --config Release
+ctest --test-dir build/core-cpp -C Release --output-on-failure
+pytest
+```
+
+Build a distributable wheel with:
+
+```bash
+python -m build --wheel
+```
+
+Standard PyPI wheels use the portable CPU decoder. CUDA is intentionally an
+explicit source-build option because CUDA toolkit and GPU architecture support
+are platform-specific.
+
+## Decode a CI8 file
+
+```bash
+dtmb-decode \
+  --input capture.ci8 \
+  --input-rate 16000000 \
+  --output recovered.ts \
+  --acceleration cpu \
+  --error-policy continue
+```
+
+The default profile is QAM64, FEC rate 0.6, interleaver mode 2
+(`--system-info-index 22`). Profiles 19 through 24 select the supported QAM64
+FEC/interleaver combinations.
+
+Strict mode is the default. `--error-policy continue` omits unclean frames and
+adds MPEG-TS discontinuity indications before later clean output.
+
+## Optional CUDA LDPC acceleration
+
+CPU decoding is the portable baseline. Build the optional CUDA LDPC backend
+when a supported NVIDIA toolchain is available:
+
+```bash
+cmake -S core/cpp -B build/core-cpp-cuda \
+  -DDTMB_CORE_ENABLE_CUDA_LDPC=ON \
+  -DDTMB_CORE_BUILD_TESTS=ON
+cmake --build build/core-cpp-cuda --config Release
+```
+
+Then select it explicitly:
+
+```bash
+dtmb-decode \
+  --bin-dir build/core-cpp-cuda \
+  --input capture.ci8 \
+  --input-rate 16000000 \
+  --output recovered.ts \
+  --acceleration cuda
+```
+
+The CUDA backend batches LDPC codewords and reports host-to-device, kernel,
+device-to-host, and total timing metrics. CPU remains available as the
+correctness and portability reference.
+
+### Parallelism and observed acceleration
+
+The receiver uses independent concurrency at several stages:
+
+- multithreaded rational resampling and PN acquisition;
+- worker-parallel C=3780 frame equalization;
+- chunked QAM64 deinterleaving and soft demapping;
+- batched LDPC decoding on either CPU workers or CUDA kernels.
+
+One observed live-pipeline comparison used 12 CPU workers and 256-frame FEC
+batches. The CPU path processed 198,660 codewords in 30.95 seconds of measured
+FEC batch time (about 6,419 codewords/s). The CUDA path processed 267,486
+codewords in 17.22 seconds of measured FEC batch time (about 15,534
+codewords/s), while 10.41 seconds were attributed to CUDA transfer plus kernel
+execution. After normalizing by processed codewords, the observed FEC-stage
+throughput improvement was approximately 2.4x.
+
+These runs did not use an identical retained LLR stream, so the figure is an
+operational observation rather than a controlled cross-machine benchmark.
+Performance depends on the proportion of early-rejected codewords, iteration
+count, batch size, CPU, GPU, and memory-transfer overhead. Reproducible release
+claims should use the same retained LLR input and compare byte-identical output.
+
+## Decode a pipe
+
+Use `-` for stdin or stdout:
+
+```bash
+ci8-producing-command |
+  dtmb-decode --input - --input-rate 16000000 --output recovered.ts
+```
+
+The source command is deliberately unspecified: the receiver depends only on
+the byte-stream contract, not an SDR vendor or device API.
+
+## Play while decoding
+
+With ffplay:
+
+```bash
+ci8-producing-command |
+  dtmb-decode --input - --input-rate 16000000 --output - --error-policy continue |
+  ffplay -fflags nobuffer -flags low_delay -f mpegts -
+```
+
+With VLC:
+
+```bash
+ci8-producing-command |
+  dtmb-decode --input - --input-rate 16000000 --output - --error-policy continue |
+  vlc - --demux=ts
+```
+
+Playback quality depends on RF quality and FEC cleanliness. A player detecting
+a service is not evidence that the complete stream is error-free.
+
+## Inspect MPEG-TS output
+
+```bash
+dtmb-ts-analyze recovered.ts
+ffprobe -v error -show_programs -show_streams recovered.ts
+```
+
+## Scope
+
+Included:
+
+- portable C++20 receive stages;
+- CI8 file and stdin integration;
+- MPEG-TS file and stdout output;
+- required LDPC matrices;
+- core and pipeline-construction tests.
+
+Not included:
+
+- SDR drivers or hardware-control code;
+- capture recipes, device identifiers, frequencies, gains, or locations;
+- signal-generation, scanning, UI, visualization, sweep, or research tooling;
+- real broadcast captures or derived analysis artifacts.
+
+## License
+
+MIT. See [LICENSE](LICENSE) and [THIRD_PARTY.md](THIRD_PARTY.md).

dtmb_sdr-0.2.0/THIRD_PARTY.md

@@ -0,0 +1,17 @@
+# Third-Party References
+
+## Standard
+
+| Name | Purpose | Reuse |
+|------|---------|-------|
+| GB 20600-2006 | Normative DTMB standard: PN sequences, constellation mappings, LDPC/BCH parameters, system information tables | Receiver constants and LDPC interoperability matrices |
+
+All DTMB-specific algorithms are reimplemented from the standard, not copied from other projects.
+
+## Derived Artifacts
+
+Files generated from GB 20600-2006 (not third-party code):
+
+| Artifact | Format | Purpose |
+|----------|--------|---------|
+| `python/dtmb/data/dtmb_ldpc_rate{1,2,3}.alist` | MacKay .alist | LDPC parity-check matrices for interoperability with external decoders (AFF3CT, Radford Neal's tools, etc.) |

dtmb_sdr-0.2.0/core/cpp/CMakeLists.txt

@@ -0,0 +1,95 @@
+cmake_minimum_required(VERSION 3.20)
+
+project(dtmb_core VERSION 0.2.0 LANGUAGES C CXX)
+
+option(DTMB_CORE_BUILD_TESTS "Build dtmb-core tests" ON)
+option(DTMB_CORE_ENABLE_CUDA_LDPC "Build the optional CUDA LDPC backend" OFF)
+option(DTMB_CORE_ENABLE_FFTW "Use FFTW3f when available" ON)
+
+if(DTMB_CORE_ENABLE_CUDA_LDPC)
+  enable_language(CUDA)
+  find_package(CUDAToolkit REQUIRED)
+  set(CMAKE_CUDA_STANDARD 20)
+  set(CMAKE_CUDA_STANDARD_REQUIRED ON)
+endif()
+
+add_library(dtmb_core
+  src/c3780.cpp
+  src/core.cpp
+  src/fec.cpp
+  src/frame_sync.cpp
+  src/pn_channel.cpp
+  src/resampler.cpp
+)
+add_library(dtmb::core ALIAS dtmb_core)
+target_compile_features(dtmb_core PUBLIC cxx_std_20)
+target_include_directories(dtmb_core PUBLIC
+  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+)
+
+if(DTMB_CORE_ENABLE_FFTW)
+  find_path(FFTW3F_INCLUDE_DIR NAMES fftw3.h HINTS ENV CONDA_PREFIX
+    PATH_SUFFIXES include Library/include)
+  find_library(FFTW3F_LIBRARY NAMES fftw3f libfftw3f-3 HINTS ENV CONDA_PREFIX
+    PATH_SUFFIXES lib Library/lib)
+  if(FFTW3F_INCLUDE_DIR AND FFTW3F_LIBRARY)
+    target_include_directories(dtmb_core PRIVATE "${FFTW3F_INCLUDE_DIR}")
+    target_link_libraries(dtmb_core PUBLIC "${FFTW3F_LIBRARY}")
+    target_compile_definitions(dtmb_core PRIVATE DTMB_CORE_HAVE_FFTW3F=1)
+  endif()
+endif()
+
+if(MSVC)
+  target_compile_options(dtmb_core PRIVATE /W4 /permissive-)
+else()
+  target_compile_options(dtmb_core PRIVATE -Wall -Wextra -Wpedantic)
+endif()
+
+add_executable(dtmb_core_ci8_resample tools/ci8_resample.cpp)
+target_link_libraries(dtmb_core_ci8_resample PRIVATE dtmb::core)
+
+add_executable(dtmb_core_c3780_extract tools/c3780_extract.cpp)
+target_link_libraries(dtmb_core_c3780_extract PRIVATE dtmb::core)
+
+add_executable(dtmb_core_deinterleave_qam64 tools/deinterleave_qam64.cpp)
+target_link_libraries(dtmb_core_deinterleave_qam64 PRIVATE dtmb::core)
+
+add_library(dtmb_ldpc_h_gate_support STATIC tools/ldpc_h_gate.cpp)
+target_compile_features(dtmb_ldpc_h_gate_support PUBLIC cxx_std_20)
+target_include_directories(dtmb_ldpc_h_gate_support PUBLIC tools)
+target_link_libraries(dtmb_ldpc_h_gate_support PUBLIC dtmb::core)
+
+if(DTMB_CORE_ENABLE_CUDA_LDPC)
+  add_library(dtmb_ldpc_cuda_backend STATIC tools/ldpc_cuda_backend.cu)
+  target_compile_definitions(dtmb_ldpc_cuda_backend PUBLIC DTMB_CORE_HAVE_CUDA_LDPC=1)
+  target_link_libraries(dtmb_ldpc_cuda_backend PUBLIC dtmb::core CUDA::cudart)
+else()
+  add_library(dtmb_ldpc_cuda_backend STATIC tools/ldpc_cuda_backend.cpp)
+  target_link_libraries(dtmb_ldpc_cuda_backend PUBLIC dtmb::core)
+endif()
+target_compile_features(dtmb_ldpc_cuda_backend PUBLIC cxx_std_20)
+target_include_directories(dtmb_ldpc_cuda_backend PUBLIC tools)
+
+add_executable(dtmb_core_ldpc_bch_decode tools/ldpc_bch_decode.cpp)
+target_link_libraries(dtmb_core_ldpc_bch_decode PRIVATE
+  dtmb_ldpc_h_gate_support
+  dtmb_ldpc_cuda_backend
+)
+
+install(TARGETS
+  dtmb_core_ci8_resample
+  dtmb_core_c3780_extract
+  dtmb_core_deinterleave_qam64
+  dtmb_core_ldpc_bch_decode
+  RUNTIME DESTINATION dtmb/bin
+)
+
+if(DTMB_CORE_BUILD_TESTS)
+  enable_testing()
+  add_executable(dtmb_ldpc_h_gate_tests tests/test_ldpc_h_gate.cpp)
+  target_link_libraries(dtmb_ldpc_h_gate_tests PRIVATE dtmb_ldpc_h_gate_support)
+  target_compile_definitions(dtmb_ldpc_h_gate_tests PRIVATE
+    DTMB_LDPC_RATE2_ALIST="${CMAKE_CURRENT_SOURCE_DIR}/../../python/dtmb/data/dtmb_ldpc_rate2.alist"
+  )
+  add_test(NAME dtmb_ldpc_h_gate_tests COMMAND dtmb_ldpc_h_gate_tests)
+endif()