Python SSTV (Robot36) Implementation

This project code was generated by Gemini.

This project contains a pure Python implementation of an SSTV (Slow Scan Television) Encoder and Decoder, specifically for the Robot36 mode.

Google Colab Support

This project includes a fully functional Jupyter Notebook for running Video SSTV generation in the cloud (Google Colab).

• Notebook File: SSTV_Video_Gen.ipynb
• Features:
  • Upload local video or Mount Google Drive.
  • Full GUI parameter control (Bitrate, Presets, Glitch Effects).
  • Cloud GPU/CPU rendering.
  • Custom Resolution: Supports non-standard resolutions (e.g. 144p, 1080p, or custom aspect ratios) via the Custom preset.

Auto-Generation

You can regenerate the notebook from the latest source code by running:

python3 generate_notebook.py

This ensures the notebook always contains the latest logic from video_sstv.py and decoder.py.

Files

• common.py: Shared constants and utility functions (YUV conversion).
• encoder.py: Converts an image to a Robot36 .wav audio file.
• decoder.py: Decodes a Robot36 .wav audio file back to an image.

Requirements

You need to install the following Python libraries:

pip install numpy scipy pillow

Usage

Encoder (Image -> Audio)

python encoder.py <input_image.jpg> <output_audio.wav>

• Input image will be automatically resized to 320x240.
• Output is a standard WAV file.

Decoder (Audio -> Image)

python decoder.py <input_audio.wav> <output_image.png>

• Supports WAV files (mono recommended).
• Will attempt to auto-detect sync pulses and reconstruct the image.

Advanced Usage (Filter Tool)

The sstv_filter.py script provides a convenient way to encode, optionally compress (simulate radio interference/codec loss), and decode in one go.

python sstv_filter.py <input_image> <output_image> [options]

Options

• --preset <name>: fast resolution switching.
  • default: 320x240 (Standard)
  • ntsc: 720x480
  • 480p: 854x480
  • 720p: 1280x720
• --res <WxH>: Custom resolution (e.g. --res 640x480).
• --bitrate <320k|64k|1k...>: Simulate audio compression degradation.
  • Examples: 320k (High Quality), 64k (Medium), 1k (Extreme).
  • Short flag: -k <bitrate>.
• --save-audio <path>: Save the intermediate WAV file.

Example

# Convert image to NTSC sstv, apply heavy compression (16k), and decode results
python sstv_filter.py test.jpg output.png --preset ntsc -k 16k --save-audio signal.wav

Video SSTV Tool (video_sstv.py)

A powerful tool to convert video files into SSTV aesthetic animations. It processes the video frame-by-frame, applying the SSTV encoding/decoding process (imperfect modulation) to create authentic-looking analog glitches.

Features

• Parallel Processing: Uses multiple CPU cores for fast conversion.
• GPU Acceleration: Supports NVIDIA (CUDA) and Apple Silicon (MPS) for demodulation speedup.
• Robustness: Handles imperfect sync and headerless streams.
• Resume Capability: Intermediate frames are saved safely, allowing you to resume interrupted jobs.

Usage

Basic Conversion:

python video_sstv.py input.mp4 output.mp4 --preset ntsc --bitrate 16k

Advanced Options:

• --no-video: Only generate frame images (no final video assembly). Useful if you want to edit frames manually in Premiere/AE.
• --frames-dir <path>: Specify where to save the processed frame images.
  • Default: ./<video_name>_frames
  • Files persist after completion unless --clean-frames is used.
• --clean-frames: Automatically delete the frames folder after successful video assembly.
• --start <N> --end <M>: Process only a specific range of frames.
  • Example: --start 100 --end 200
• --index-mode <input|output>: Specify if start/end refers to source video frames (input) or target video frames (output). Default is input.

Acceleration:

• --workers <N>: Number of parallel processes (Default: CPU count).
• --device <cpu|cuda|mps>: Force a specific compute device.

Robustness

The decoder has been enhanced to handle missing sync pulses (common in compressed or noisy audio). It uses time-based line indexing to maintain correct image height and synchronization even when signal quality is poor.

Notes

• This is a simplified implementation focusing on the Robot36 mode.
• The decoder uses Hilbert transform for demodulation, which provides good quality but requires a clean signal.
• If the image comes out slanted, it is due to sample rate mismatch between recording and playback devices (clock skew).