nrsc5_resample_tool

Overview

nrsc5_resample_tool is a command-line utility designed to read I/Q data from WAV files (common output from SDR software), optionally apply frequency shifting, resample the data to specific rates required by the open source NRSC5 (HD Radio) decoder, apply amplitude scaling, and output the result as raw complex samples (either 8-bit unsigned or 16-bit signed). Its main purpose is to take I/Q files recorded by various SDR programs and process them into a format suitable for playback with the open-source nrsc5 decoder.

It leverages a multi-threaded pipeline (Reader -> Processor -> Writer) to improve performance on multi-core systems. It uses the liquid-dsp library for high-quality resampling and frequency shifting (NCO), libsndfile for robust WAV file handling, and expat for parsing XML metadata found in some SDR recording formats.

Core Features

• Reads 2-channel (I/Q) WAV files: 8-bit Signed/Unsigned PCM, 16-bit Signed PCM.
• Outputs raw complex samples in specified formats:
  • cu8: Complex Unsigned 8-bit (Target Rate: 1488375.0 Hz)
  • cs16_fm: Complex Signed 16-bit (Target Rate: 744187.5 Hz)
  • cs16_am: Complex Signed 16-bit (Target Rate: 46511.71875 Hz)
• High-quality resampling using liquid-dsp (msresamp_crcf).
• Optional frequency shifting using liquid-dsp NCO (nco_crcf):
  • -F : Apply an absolute frequency shift.
  • -c : Shift based on input file metadata (requires center frequency info in file).
  • -x: Option to apply the shift after resampling (useful if shift exceeds input Nyquist).
• Customizable amplitude scaling (-s ) applied before resampling.
• Parses SDR metadata from:
  • SDR Console / SDRuno / SDRconnect auxi chunks (XML or Binary format via expat/custom parsing).
  • SDR# filename patterns (Timestamp and Frequency).
• Utilizes a multi-threaded pipeline (Reader, Processor, Writer) with thread-safe queues for efficient processing.
• Output to file (-f) or stdout (-o).
• Cross-platform: Builds and runs on Linux, macOS (POSIX) and Windows. Handles platform differences (paths, binary stdout).
• Provides progress indication and informative configuration summary (when not writing to stdout).
• Includes Nyquist warnings for potentially problematic frequency shifts.

Building the Tool (CMake)

This project uses CMake for building. Ensure you have CMake, a C compiler, and the required dependencies (libsndfile, liquid-dsp, expat) installed.

1. Navigate to the root directory of the project in your terminal.
2. Create a build directory:

   mkdir build

3. Change into the build directory:

   cd build

4. Run CMake to configure the project. You might need to tell CMake where to find dependencies if they aren't in standard locations (e.g., using -DCMAKE_PREFIX_PATH=/path/to/libs or toolchain files for vcpkg).

   cmake ..

   (Use cmake .. -G "Your Generator" if needed, e.g., for Visual Studio on Windows).

5. Build the project (the -j 4 suggests using 4 parallel jobs, adjust as needed):

   make -j 4

   (Or use the appropriate build command for your generator, e.g., cmake --build . --config Release for MSVC).

6. (Optional) Install the executable to the location specified in CMakeLists.txt (often /usr/local/bin or similar):

   sudo make install

   (Requires appropriate permissions).

After building or downloading, the executable (e.g., nrsc5_resample_tool.exe or nrsc5_resample_tool) will be located in the build directory (or the installation path).

Windows Users: This is a command-line application. You must run it from a terminal like Command Prompt (cmd.exe), PowerShell, or Windows Terminal. Do not simply double-click the .exe file. You also need the runtime DLLs for libsndfile, liquid-dsp, expat, pthreads (e.g., libwinpthread-1.dll), and potentially the C runtime (e.g., libgcc_s_seh-1.dll for MinGW) to be accessible (either in the same directory as the executable or in the system's PATH). Using vcpkg often simplifies managing these dependencies.

Command-Line Options

The tool accepts the following command-line arguments:

Usage: ./nrsc5_resample_tool -i <input.wav> -m <mode_name> [-s <scale_value>] [-F <shift_freq_hz>] [-c <target_freq_hz>] [-x] { -f <output_file> | -o }

Options:
  -i <file>            I/Q input file (8-bit Signed/Unsigned WAV or 16-bit Signed WAV (Required).
  -m <mode_name>       Output mode (Required): cu8, cs16_fm, cs16_am
  -s <value>           Scaling factor applied before resampling (effectively scales input samples).
                                (Optional, Default: 0.02000 for cu8, 0.500 for cs16). Affects amplitude.
  -F <shift_freq_hz>   Apply frequency shift in Hz before resampling.
                                Mutually exclusive with -c. (Optional).
  -c <target_freq_hz>  Shift signal so original center frequency moves to <target_freq_hz> (Requires center frequency metadata).
                                Mutually exclusive with -F. (Optional).
  -x                   Apply frequency shift AFTER resampling (default is before).
                                Useful if required shift exceeds input Nyquist limit.
  -f <file>            Output to file.
  -o                   Output to stdout (binary format, suppresses most messages).
Note: -f and -o are mutually exclusive; -F and -c are mutually exclusive.

Usage Examples

Example 1: Basic Conversion (16-bit WAV to CU8 File)

Convert a standard 16-bit signed IQ recording to the cu8 format required by `nrsc5`, using default scaling.

$ ./nrsc5_resample_tool -i recording_16bit.wav -m cu8 -f output.cu8

---Input Details---
Input File:        /path/to/recording_16bit.wav
Input Format:      16-bit Signed PCM
Input Rate:        2048000.0 Hz
Input File Size:   1.91 GB
Timestamp:         01-15-2024 10:30:05 UTC
Center Frequency:  97.900000 MHz
SDR Software:      SDR Console 3.3
---Output Details---
Output Mode:       cu8 (Unsigned 8-bit Complex)
Output Rate:       1488375 Hz
Scale Factor:      0.02000
Frequency Shift:   +0.00 Hz (Applied Before Resampling)
Output File:       /path/to/output.cu8

Starting Resample...

Processed 500000000 / 500000000 input frames (100.0%)... Done.

Total output frames generated: 363373
Total output samples generated: 726746
Output File Size: 726.75 KB

Resample operation completed successfully.

Example 2: Conversion with Absolute Frequency Shift and Scaling

Convert a 16-bit signed WAV, apply a +400 kHz frequency shift (-F), use custom scaling, and output as cu8.

$ ./nrsc5_resample_tool -i sdrsharp_rec_16bit.wav -m cu8 -F 400000 -s 0.015 -f output_shifted.cu8

---Input Details---
Input File:        /data/sdrsharp_rec_16bit.wav
Input Format:      16-bit Signed PCM
Input Rate:        1800000.0 Hz
Input File Size:   1.02 GB
Timestamp:         2024-01-15 11:05:20 UTC
Center Frequency:  101.100000 MHz
SDR Software:      SDR#
---Output Details---
Output Mode:       cu8 (Unsigned 8-bit Complex)
Output Rate:       1488375 Hz
Scale Factor:      0.01500
Frequency Shift:   +400000.00 Hz (Applied Before Resampling)
Output File:       /data/output_shifted.cu8

Starting Resample...

Processed 284444444 / 284444444 input frames (100.0%)... Done.

Total output frames generated: 235994
Total output samples generated: 471988
Output File Size: 471.99 KB

Resample operation completed successfully.

Example 3: Metadata Shift to Target Frequency, Output to Stdout for nrsc5

Convert a 16-bit signed WAV file recorded by SDR Console (assume its metadata indicates 93.3 MHz), shift it so the signal is centered at 98.5 MHz (-c 98.5e6), and pipe the resulting cu8 output directly to the nrsc5 decoder.

$ ./nrsc5_resample_tool -i sdrc_rec_16bit.wav -m cu8 -c 98.5e6 -o | nrsc5 -r - 0

(Binary data piped to nrsc5...)
(No progress or summary printed to stderr when using -o)

Note: When using -o, most informational messages are suppressed to keep stderr clean. Only fatal errors are typically printed. The binary output goes directly to standard output.