Unofficial Linux port of the TinyCircuits TinyTV Converter. Converts any video into the formats that the TinyTV 2, TinyTV Mini, and TinyTV DIY Kit play from their SD cards.
TinyCircuits ships their converter app for Windows and macOS only. This project reproduces its exact encoding pipelines (same ffmpeg arguments, same per-model specs) natively on Linux, with a Qt GUI and a proper CLI.
Not affiliated with or endorsed by TinyCircuits. "TinyTV" is their product; go buy one, they're great.
-
GUI like the official app: drag-and-drop queue, batch folder conversion, TV model / scaling / format selection, audio normalization, live preview at output size, per-file progress, cancel
-
CLI for scripting and batch jobs (
tinytv-convert) -
All three devices and formats:
Device .AVI (default) .TSV .MP4 (firmware 1.3.0+) TinyTV 2 MJPEG 210x135 @ 24 fps 210x135 raw H.264 208x128 + FLAC TinyTV Mini MJPEG 64x64 @ 24 fps 64x64 raw H.264 64x64 + FLAC TinyTV DIY Kit MJPEG 96x64 @ 24 fps 96x64 raw (native) not supported -
--checkvalidator: the official app doesn't have this. The TinyTV firmware is not a general-purpose video player — it requires the MJPG fourcc, video as stream 0 / audio as stream 1, audio chunks that fit its 512-byte buffer, JPEG frames under its per-model buffer size, and frame dimensions within 10 px of the panel.tinytv-convert --checkre-implements those rules (avicheck.py) and verifies your file before it ever touches an SD card.
- Linux with Python 3.11+
ffmpeg/ffprobe5.0+ (sudo apt install ffmpegon Debian/Ubuntu/Mint)- PySide6 for the GUI (auto-installed by
install.shif missing)
git clone https://github.com/phidotphi/tinytv-converter.git
cd tinytv-converter
./install.sh # CLI + GUI + application-menu entry
./install.sh --desktop # ...plus a desktop iconGUI: launch "TinyTV Converter" from your app menu. Drag videos in, pick your TV model, hit Convert.
CLI:
# one file for a TinyTV 2, normalized audio, verified against firmware rules
.venv/bin/tinytv-convert episode.mp4 -t tv2 --normalize --check
# batch a whole folder straight onto the SD card, for a TinyTV Mini
.venv/bin/tinytv-convert ~/Videos/cartoons/ -t mini -o /media/$USER/TINYTV/
# raw TSV for the DIY kit
.venv/bin/tinytv-convert clip.mp4 -t diy -f tsvFlags: -t tv2|mini|diy (model), -f avi|tsv|mp4 (format), -s contain|cover|fill (letterbox / zoom-crop / stretch), -n/--normalize (peak-based volume normalization, same method as the official app), -o OUTDIR, --check.
Copy the converted files to the root of the TV's SD card (TinyTV 2 and Mini mount as USB drives when powered on). Each file is one "channel". A file named splash.avi plays as the power-on splash. MP4 output needs firmware 1.3.0+ and is not available for the DIY Kit.
- Encoding pipelines mirror the official TinyTVConverterApp v1.2.0 (
FFMPEGCommands.py) argument-for-argument; format constraints come from the TinyTV firmware source (SD_AVI.ino). This is a clean reimplementation, no code copied. - AVI output is confirmed playing on real TinyTV hardware. TSV and MP4 outputs are validated in software (ffprobe + the firmware-rule checker) — reports welcome if you try them on-device.
- Test suite:
pip install pytest && .venv/bin/python -m pytest— 17 tests including end-to-end conversions with real ffmpeg.
One deliberate difference from upstream: distro ffmpeg builds gate FLAC-in-MP4 behind -strict experimental, so the MP4 command includes it (the official app bundles its own ffmpeg).
Not ported (yet): the official app's second tab, which changes TV settings (volume, looping, static effect) over USB serial. Open an issue if you want it.
tinytv_converter/
├── specs.py per-model output specs + firmware constants
├── ffmpeg_cmds.py ffmpeg command builders (mirrors the official app)
├── probe.py ffprobe info + volumedetect normalization
├── convert.py conversion engine (AVI/MP4 pass, TSV interleaver)
├── avicheck.py firmware-rule validator for .avi outputs
├── cli.py tinytv-convert
└── gui.py tinytv-converter-gui (PySide6)
MIT. TinyTV, TinyCircuits, and the original converter app belong to TinyCircuits.