sstv-tool

single-file sstv encoder/decoder for ctf work, radio experiments, and quick image/audio round-trips.

developer: @uckix

what it does

• decodes wav / mp3 / ogg / flac / m4a / aac / opus into images
• auto-detects supported sstv modes from the vis header during decode
• encodes images into wav / mp3 / ogg / flac / m4a / aac / opus
• supports forced mode selection with -m
• works as a single-file cli script

supported modes

• MartinM1
• MartinM2
• ScottieS1
• ScottieS2
• ScottieDX

requirements

python packages:

pip install -r requirements.txt

system dependency:

• ffmpeg is required for anything that is not plain .wav

install

git clone https://github.com/uckix/sstv_decoder_encoder.git
cd sstv-tool
pip install -r requirements.txt

optional:

chmod +x tool.py

usage

show help

python tool.py --help

show version

python tool.py --version

list supported modes

python tool.py --list-modes

decode with auto-detect

python tool.py -i input.wav -o out.png
python tool.py -i input.mp3 -o out.png
python tool.py -i input.ogg -o out.png

force decode mode

use this when auto-detect fails or the file has a noisy/custom preamble.

python tool.py -i input.wav -o out.png -m ScottieS1

encode into audio

python tool.py -i in.png -o out.wav -m ScottieS1
python tool.py -i in.jpg -o out.ogg -m MartinM1
python tool.py -i in.jpg -o out.mp3 -m ScottieDX

quality notes

for the cleanest results:

• encode to wav when possible
• decode to png when possible
• use ScottieDX for a slower but usually stronger signal
• use sharp, high-contrast source images
• avoid lossy chains like jpg -> mp3 -> jpg

how mode detection works

when decoding, the script scans the beginning of the audio for the standard sstv vis header:

• 1900 hz leader
• 1200 hz break
• 1900 hz leader
• vis bits that identify the mode

if the vis code matches one of the supported modes, the tool decodes the image automatically.

examples

decode a challenge file:

python tool.py -i challenge.wav -o decoded.png

encode a png as scottie dx:

python tool.py -i image.png -o signal.wav -m ScottieDX

limitations

• this project currently supports only the 5 listed modes
• some noisy or custom ctf files may need manual mode forcing with -m
• very lossy audio can break header detection or reduce decoded image quality

project layout

sstv-tool/
├── README.md
├── requirements.txt
├── .gitignore
└── tool.py

disclaimer

this is a practical utility script meant for learning, ctf use, and experimentation. it is not a full replacement for mature radio/sstv suites.