JellyConvert

Converts any video file into the most compatible format possible, to allow DirectPlay. Meant for Jellyfin servers with very weak hardware that doesn't do transcoding.

Usage

Requirements

• Python 3.9+
• ffmpeg / ffprobe (Debian: sudo apt install ffmpeg)
• Optional: an NVIDIA GPU with the proprietary driver for GPU encoding. Without one, the script encodes on the CPU.

Basic use

python3 jellyconvert.py /media/raw/Movies /media/raw/Shows -o /media/jellyfin

• Folders are scanned recursively, and single files work too.
• Each input folder is mirrored inside the output folder, e.g. /media/raw/Shows/Charmed/S01/e01.mkv → /media/jellyfin/Shows/Charmed/S01/e01.mp4.
• Files already in the output folder (any video with the same name) are skipped, so an interrupted run can simply be started again.
• The first output line shows whether the GPU or the CPU is used.

Preview what would happen without converting anything:

python3 jellyconvert.py /media/raw -o /media/jellyfin --dry-run

Common options

Option	Default	Description
--gpu-quality N	23	GPU quality; higher = smaller files, lower quality
--cpu	off	Never use the GPU (slower, smallest files)
--crf N	21	CPU quality; higher = smaller files, lower quality
--preset NAME	slow	CPU speed: medium / veryfast are faster, files a bit bigger
--maxrate RATE	4M	Video bitrate cap, e.g. 3M
--audio-channels 2|6	2	6 keeps 5.1 surround instead of downmixing to stereo
--audio-bitrate RATE	160k	AAC bitrate for stereo tracks
--force-encode	off	Re-encode even videos that are already compatible
--overwrite	off	Convert even if the output already exists
--delete-source	off	Delete originals after a verified successful conversion
--dry-run	off	Show the plan only

Run python3 jellyconvert.py --help for the full list.

Good to know

• Videos that are already compatible (H.264, 720p or smaller, under the bitrate cap) are copied without re-encoding, which takes seconds and loses no quality.
• If the GPU fails on a file, that file is redone on the CPU automatically.
• Damaged files are detected and repaired where possible. Their originals are never deleted, even with --delete-source.
• Ctrl+C stops cleanly and removes the unfinished file.
• For long runs over SSH, start the script inside tmux or screen.
• The exit code is 1 if any file failed; failed files are listed at the end.