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).
