DSDcc Digital Speech Decoder

DSDcc is a C++ library and binary for digital speech decoding. Unlike the original DSD project, it is designed as a library where the user pushes new samples to a central decoder object, making it suitable for integration into software like Qt applications (e.g., SDRangel) without requiring complex threading models.

Key Features:

• Push-based API: Facilitates easy integration into existing software loops.
• Supported Formats: DMR/MOTOTRBO, D-Star, dPMR, and Yaesu System Fusion (YSF).
• Flexible Output: Supports audio output as L+R (stereo) with L=R for easier integration.
• Optional mbelib: You can compile without mbelib to extract raw MBE frames, which helps avoid potential patent/licensing issues associated with mbelib.

The library is organized around several key classes within the DSDcc namespace:

• DSDDecoder: The central orchestration object. It manages synchronization, global state, and holds the DSDOpts and DSDState objects.
• DSDOpts: Handles configuration options for the decoder.
• DSDState: Manages runtime data and the current state of the decoder.
• DSDSymbol: Responsible for symbol and dibit processing. Use pushSample() to feed it data.
• DSDMBEDecoder: A wrapper around mbelib that converts AMBE frames into 8 kS/s (or upsampled 48 kS/s) audio.
• DSDDMR, DSDdPMR, DSDDstar, DSDYSF: Specialized decoders for DMR, dPMR, D-Star, and Yaesu System Fusion respectively. They utilize DSDMBEDecoder for audio production.
• DVController: A helper class used for handling AMBE3000 serial devices via processDVSerial.

To enable mbelib support (required for full AMBE audio decoding), you must have mbelib installed on your system and use the -DUSE_MBELIB=ON flag during the CMake configuration step. If mbelib is installed in a non-standard location, you must explicitly provide the include and library paths.

Full CMake command with custom installation and mbelib:

cmake -Wno-dev -DCMAKE_INSTALL_PREFIX=/opt/install/dsdcc -DUSE_MBELIB=ON -DLIBMBE_INCLUDE_DIR=/opt/install/mbelib/include -DLIBMBE_LIBRARY=/opt/install/mbelib/lib/libmbe.so ..

To use DSDcc in your own C++ application, follow this general integration pattern. All components reside in the DSDcc namespace.

1. Allocate a DSDcc::DSDDecoder object.
2. Configure the decoder using DSDOpts and DSDState objects via DSDDecoder methods.
3. Initialize your input stream (file or network).
4. Loop:
   • Fetch a sample from the stream.
   • Call DSDDecoder::pushSample() (or use DSDSymbol::pushSample()).
   • If using mbelib: Check for available audio output from the decoder and push it to your audio device/stream.
   • If using SerialDV: Use DSDcc::DVController::processDVSerial to handle serial data, then check for and push available audio.
5. Cleanup: Close streams and destroy objects.

The .dis files in the samples directory are S16LE 48 kS/s single channel (mono) discriminator output samples. To process these files, you can pipe them into the dsdccx binary using the sox utility.

To play a sample through your audio device, use a pipeline that converts the .dis file to a raw stream, pipes it to dsdccx for decoding, and then pipes the output to a player like play.

sox -t s16 -r 48k -c 1 dmr_it_8.dis -t s16 -r 48k -c 1 - | /opt/install/dsdcc/bin/dsdccx -T3 -i - -fa -o - | play -q -t s16 -r 8k -c 1 -

To support DVSI AMBE3000 serial devices (like the ThumbDV dongle) in the dsdccx binary, you must install [SerialDV] and provide its paths to CMake using -DLIBSERIALDV_INCLUDE_DIR and -DLIBSERIALDV_LIBRARY.

Full CMake command with custom installation and SerialDV:

cmake -Wno-dev -DCMAKE_INSTALL_PREFIX=/opt/install/dsdcc -DLIBSERIALDV_INCLUDE_DIR=/opt/install/serialdv/include/serialdv -DLIBSERIALDV_LIBRARY=/opt/install/serialdv/lib/libserialdv.so ..

If using a ThumbDV dongle with dsdccx, the device may fail if the kernel's FTDI driver does not have low latency enabled. You can force low latency for your specific device (e.g., /dev/ttyUSB0) using one of the following commands:

echo 1 | sudo tee /sys/bus/usb-serial/devices/ttyUSB0/latency_timer
# OR
sudo setserial /dev/ttyUSB0 low_latency

The dsdccx binary is designed for shell integration using pipes. It reads from stdin and writes to stdout. A common pattern is to pipe UDP discriminator output from socat into dsdccx and then into a playback utility like sox.

Example: Pipe UDP to playback:

socat stdout udp-listen:9999 | /opt/install/dsdcc/bin/dsdccx -i - -fa -o - | play -q -t s16 -r 8k -c 1 -

Options:

• -h: Display online help.
• -i <input>: Input source.
• -o <output>: Output destination.
• -M <file>: Since version 1.6, sends traffic status messages to a specified file.

When using the provided .dis samples, you may need specific dsdccx flags to ensure correct decoding based on the signal protocol:

• DMR (Digital Mobile Radio): If the signal uses DMR slot #2, you must specify -T2 (slot #2) or -T3 (slots #1 and #2 mixed) to receive output.
• dPMR (digital PMR): Since dPMR is a 2400 baud protocol, you must specify the -d0 option to get an output.
• D-Star: Samples are available both with headers (dstar_f1zil_1.dis) and captured on the fly without headers (dstar_f1zil_2.dis).
• Yaesu System Fusion (YSF): Available via ysf_f5zoo.dis.

-T2 : DMR slot #2
-T3 : DMR slots #1 and #2 mixed
-d0  : dPMR (2400 baud protocol)