Skip to main content

Overview

While minimodem is designed for real-time audio transmission and reception, it also supports reading from and writing to audio files. This is invaluable for testing, debugging, offline processing, and archiving modem transmissions.

File Backend

minimodem uses libsndfile to provide comprehensive audio file format support (src/simpleaudio-sndfile.c). When you specify the --file flag, minimodem automatically switches from real-time audio to file-based I/O.

Supported Audio Formats

The file backend supports numerous audio formats through libsndfile (src/simpleaudio-sndfile.c:111-140):

Common Formats

  • WAV - Microsoft WAVE
  • AIFF - Audio IFF
  • FLAC - Free Lossless
  • OGG - Ogg Vorbis

Professional Formats

  • AU - Sun/NeXT
  • CAF - Core Audio
  • W64 - 64-bit WAVE
  • RF64 - 64-bit broadcast

Specialized Formats

  • VOC - Creative Labs
  • RAW - Raw PCM
  • IRCAM - IRCAM
  • MAT4/MAT5 - MATLAB
Format Detection: The audio format is automatically detected from the file extension. For example, .wav creates a WAV file, .flac creates a FLAC file, etc.

Writing Audio Files

Use the --file flag with --tx to write transmitted audio to a file:

Basic File Writing

# Generate 1200 baud signal to WAV file
echo "HELLO WORLD" | minimodem --tx 1200 --file output.wav

# High quality 96 kHz WAV
echo "TEST" | minimodem --tx 1200 -f output.wav -R 96000

Sample Formats

minimodem supports two sample formats:
# Default for transmit mode
echo "HELLO" | minimodem --tx 1200 -f output.wav

# Explicit specification
echo "HELLO" | minimodem --tx 1200 -f output.wav
Sample Format Selection:
  • S16: 16-bit signed integer, smaller files, sufficient for most uses
  • FLOAT: 32-bit floating point, larger files, better for audio processing
The FLOAT format is automatically required for receive mode (src/minimodem.c:786-788).

Complete Transmission Examples

# Send text to WAV file at 300 baud
echo "CQ CQ CQ DE W1ABC" | minimodem --tx 300 --file call.wav

# Send binary file with compression to FLAC
gzip -c document.pdf | minimodem --tx 1200 -f data.flac

# Create Bell 103 test file
echo "TESTING 123" | minimodem --tx 300 \
  --file test-bell103.wav \
  --samplerate 48000

# Create RTTY recording
echo "THE QUICK BROWN FOX" | minimodem --tx rtty -f rtty-test.wav

Reading Audio Files

Use the --file flag with --rx (or just no mode flag) to decode from an audio file:

Basic File Reading

# Decode from WAV file
minimodem --rx 1200 --file recording.wav

# Save decoded output
minimodem 1200 -f recording.wav > decoded.txt

# Quiet mode
minimodem 1200 -f recording.wav --quiet > data.txt 2>/dev/null

Advanced Decoding

# Decode with auto-carrier detection
minimodem --rx 1200 --file signal.wav --auto-carrier

# Decode with custom confidence threshold
minimodem 1200 -f noisy-signal.wav --confidence 1.0

# Decode with higher quality search
minimodem 1200 -f signal.wav --limit 5.0

# Decode with custom frequencies
minimodem 1200 -f signal.wav --mark 1200 --space 2400

# Decode and filter non-printable characters
minimodem 1200 -f signal.wav --print-filter

File Format Details

Sample Rate

Audio files can have any sample rate, but common values are:

48000 Hz

Default - Excellent quality, widely compatible
echo "TEST" | minimodem --tx 1200 -f out.wav -R 48000

44100 Hz

CD Quality - Slightly smaller files
echo "TEST" | minimodem --tx 1200 -f out.wav -R 44100

96000 Hz

High Resolution - Better for weak signals
echo "TEST" | minimodem --tx 1200 -f out.wav -R 96000

8000 Hz

Narrow Band - Smaller files, limited frequency range
echo "TEST" | minimodem --tx 300 -f out.wav -R 8000

Channels

minimodem only supports mono (1-channel) audio (src/minimodem.c:535):
# Correct - mono audio
echo "HELLO" | minimodem --tx 1200 -f mono.wav
Stereo Not Supported: If you try to decode a stereo file, minimodem will report an error. Convert stereo files to mono first using tools like sox or ffmpeg.

Converting Stereo to Mono

# Using sox
sox stereo.wav -c 1 mono.wav

# Using ffmpeg
ffmpeg -i stereo.wav -ac 1 mono.wav

# Then decode
minimodem 1200 --file mono.wav

Testing Workflow

Using audio files is perfect for testing and validation:
1

Generate test signal

echo "TEST MESSAGE 123" | minimodem --tx 1200 -f test.wav
2

Verify audio file

# Play the file to hear it
aplay test.wav

# Or use your audio player
vlc test.wav
3

Decode the file

minimodem --rx 1200 -f test.wav
4

Verify output

minimodem 1200 -f test.wav --quiet 2>/dev/null
# Should output: TEST MESSAGE 123

Practical Applications

Create Test Signals

#!/bin/bash
# Generate test signals at various baud rates
for baud in 300 1200 4800; do
    echo "TEST at ${baud} baud" | \
        minimodem --tx ${baud} --file test-${baud}.wav
done

Archive Transmissions

# Record and timestamp transmission
DATE=$(date +%Y%m%d-%H%M%S)
cat message.txt | minimodem --tx 1200 -f "tx-${DATE}.flac"

# Compress for long-term storage
xz tx-${DATE}.flac

Process Recorded Audio

# Decode recording from radio/phone
minimodem 1200 --file radio-recording.wav > decoded.txt

# Batch process multiple recordings
for file in recordings/*.wav; do
    echo "Processing $file..."
    minimodem 1200 -f "$file" --quiet > "${file%.wav}.txt" 2>/dev/null
done

Quality Testing

# Generate reference signal
echo "The quick brown fox jumps over the lazy dog" | \
    minimodem --tx 1200 -f reference.wav

# Add noise (using sox)
sox reference.wav -p synth whitenoise vol 0.1 | \
    sox -m reference.wav - noisy.wav

# Test decode quality
minimodem 1200 -f noisy.wav --confidence 1.0

Format Conversion

# Decode from one format and encode to another
minimodem 1200 -f input.wav --quiet 2>/dev/null | \
    minimodem --tx 1200 -f output.flac

# Change sample rate
minimodem 1200 -f input-48k.wav --quiet 2>/dev/null | \
    minimodem --tx 1200 -f output-96k.wav -R 96000

Performance Considerations

File Mode vs Real-Time Mode

File mode has different characteristics than real-time mode:

File Mode

  • No real-time constraints
  • Can process faster than real-time
  • No audio buffer underruns
  • Suitable for batch processing
  • No interactive timing features

Real-Time Mode

  • Must keep up with audio stream
  • Processes at exactly 1× speed
  • Possible audio glitches
  • Interactive features enabled
  • Leader/trailer tones added

Processing Speed

File decoding can be much faster than real-time:
# Time how long it takes to decode
time minimodem 1200 -f long-recording.wav > output.txt

# A 60-second audio file might decode in 2-3 seconds

Technical Details

File Backend Implementation

The sndfile backend (src/simpleaudio-sndfile.c:160-220):
int sa_sndfile_open_stream(
    simpleaudio *sa,
    const char *backend_device,
    sa_direction_t sa_stream_direction,
    sa_format_t sa_format,
    unsigned int rate, unsigned int channels,
    char *app_name, char *stream_name)
{
    const char *path = stream_name;
    
    // Open file for read or write
    SNDFILE *s = sf_open(path,
        sa_stream_direction == SA_STREAM_RECORD ? SFM_READ : SFM_WRITE,
        &sfinfo);
}

Sample Format Handling

Reading samples (src/simpleaudio-sndfile.c:43-74):
switch ( sa->format ) {
    case SA_SAMPLE_FORMAT_FLOAT:
        n = sf_readf_float(s, buf, nframes);
        break;
    case SA_SAMPLE_FORMAT_S16:
        n = sf_readf_short(s, buf, nframes);
        break;
}
Writing samples (src/simpleaudio-sndfile.c:77-100):
switch ( sa->format ) {
    case SA_SAMPLE_FORMAT_FLOAT:
        n = sf_writef_float(s, buf, nframes);
        break;
    case SA_SAMPLE_FORMAT_S16:
        n = sf_writef_short(s, buf, nframes);
        break;
}

PEAK Chunk

For floating-point WAV/AIFF files, minimodem disables the PEAK chunk header (src/simpleaudio-sndfile.c:203-210):
// Turn off the PEAK chunk to ensure reproducible files
sf_command(s, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_FALSE);
This ensures that the same input always produces byte-identical output files, which is important for testing and verification.

Troubleshooting

Error: filename.wav: System errorSolutions:
  • Check file exists and is readable
  • Verify file extension matches format
  • Try absolute path: --file /full/path/to/file.wav
  • Check file permissions
Error: minimodem was configured without sndfileSolutions:
  • Rebuild minimodem with libsndfile support
  • Check build configuration: minimodem --version
  • Use package manager to install version with file support
Error: input stream must be 1-channel (not 2)Solutions:
  • Convert stereo to mono: sox stereo.wav -c 1 mono.wav
  • Or with ffmpeg: ffmpeg -i stereo.wav -ac 1 mono.wav
Symptoms: Garbled output or low confidenceSolutions:
  • Check sample rate: --samplerate 48000
  • Try auto-carrier: --auto-carrier
  • Lower confidence threshold: --confidence 1.0
  • Increase search limit: --limit 5.0
  • Verify file isn’t corrupted: Play it with audio player
Symptoms: WAV files are very largeSolutions:
  • Use FLAC compression: --file output.flac
  • Lower sample rate: --samplerate 44100
  • Use S16 format instead of FLOAT
  • Compress after: xz output.wav

See Also

Build docs developers (and LLMs) love