README

convert-samples
===============

The active repository is at https://codeberg.org/glv/convert-samples

convert-samples is a command-line program to convert samples received from
software defined radios from one format to another.


## Usage

convert-samples -f <fmt> -t <fmt> [-i <file>] [-o <file>] [-r <ratio>] [-s <shift>]

Options:
  -f <fmt>
    Format of input samples.
  -t <fmt>
    Format of output samples.
  -i <file>  [default: stdin]
    Read input samples from 'file'.
  -o <file>  [default: stdout]
    Write output samples to 'file'.
  -r <ratio>  [default: 1.0]
    Resample using the given ratio.
  -s <shift>  [default: 0.0]
    Shift frequencies, where 'shift' is the frequency shift in Hertz
    divided by the sample rate.

Supported formats:
  - s8: signed 8 bit integer
  - u8: unsigned 8 bit integer
  - s16: signed 16 bit integer
  - u16: unsigned 16 bit integer
  - s32: signed 32 bit integer
  - u32: unsigned 32 bit integer
  - f32: 32 bit float
  - cs8: complex made of signed 8 bit integers
  - cu8: complex made of unsigned 8 bit integers
  - cs16: complex made of signed 16 bit integers
  - cu16: complex made of unsigned 16 bit integers
  - cs32: complex made of signed 32 bit integers
  - cu32: complex made of unsigned 32 bit integers
  - cf32: complex made of 32 bit floats


## Examples

Convert samples from the cf32 format used by GNU Radio to the cs8 format used
by HackRF:

    convert-samples -f cf32 -t cs8 -i samples.cf32 -o samples.cs8


Convert samples from the cu8 format used by RTL-SDR to the cs16 format used
by BladeRF:

    convert-samples -f cu8 -t cs16 -i samples.cu8 -o samples.cs16


Convert samples from the cf32 format to the cs8 format, and also double the
sample rate:

    convert-samples -f cf32 -t cs8 -i samples.cf32 -o samples.cs8 -r 2.0

Let's suppose that we have samples in cu8 format at 2000000 S/s with a signal
of interest at 400 kHz having a 10 kHz bandwidth. We would like to have samples
in cf32 format with only the wanted signal. To do that we can shift the
frequencies by -400 kHz to put the signal in the center of the spectrum,
and reduce the sample rate to 25000 S/s:
  - shift: -400000 / 2000000 = -0.2
  - ratio: 25000 / 2000000 = 0.0125

    convert-samples -f cu8 -t cf32 -i samples.cu8 -o signal.cf32 -r 0.0125 -s -0.2


## Compilation

convert-samples requires the following dependencies:
  - libliquid (https://github.com/jgaeddert/liquid-dsp)

It can be compiled with the usual:

    ./autogen.sh
    ./configure
    make