Converterr

Why Converterr

Your TV plays HEVC and H.264 fine, but stutters on AV1, VC-1, MPEG-2 or old DivX, and a small server can't transcode those on the fly. Converterr fixes those files once and leaves everything else alone.

Screenshots

The UI follows the *arr family: sidebar, icon toolbar, dark theme.

Install

Docker is the easiest way. The image is multi-arch (amd64 and arm64).

services:
  converterr:
    image: ghcr.io/teopost/converterr:latest
    container_name: converterr
    user: "1000:1000"               # owner of your media files
    environment:
      - TZ=Europe/Rome              # the time window uses this timezone
    volumes:
      - ./config:/config            # database
      - ./cache:/cache              # ffmpeg scratch space (room for one output per worker)
      - /mnt/media/tv:/library/tv
      - /mnt/media/movies:/library/movies
    ports:
      - 8787:8787
    cpus: "3.0"                     # leave a core for your media server
    restart: unless-stopped

Open http://<host>:8787, then:

1. Settings → Profiles: check the default profile. It converts AV1/VC-1/WMV/MPEG-2/DivX3 to HEVC 720p 8-bit, CRF 26.
2. Libraries → Add Library: pick a folder and a profile, and choose whether to notify Sonarr or Radarr.
3. Click Scan. Files that need converting show up in Activity → Queue.

Build from source

git clone https://github.com/teopost/converterr
cd converterr
docker build -t converterr .          # or: cargo build --release (needs ffmpeg/ffprobe in PATH)

Sonarr & Radarr integration

Two links, one in each direction.

1. Webhook: convert right after import

In Sonarr or Radarr go to Settings → Connect → + → Webhook, enable On Import and On Upgrade, method POST, and use the URL shown on Converterr's Settings → Connect page:

http://converterr:8787/api/v1/webhook?apikey=<your api key>

Converterr probes the imported file and queues it only if the library's profile says so. A daily scan (optional) catches anything the webhook missed.

2. Rescan after conversion

Fill in the Sonarr/Radarr URL and API key on Settings → Connect and set Notify on each library. After a conversion, Converterr finds the series or movie that owns the file and triggers a rescan, so the *arr app picks up the new codec, size and extension.

Path mapping

Containers often mount the same folder at different paths. Set the library's Sonarr/Radarr path to the folder as Sonarr/Radarr sees it:

Converterr library path	Sonarr/Radarr path	Example file
/library/tv	/tv	/tv/Show/Season 1/Show - S01E01.mkv
/library/movies	/movies	/movies/Film (2020)/Film (2020).mkv

Documentation

Profiles

Setting	Meaning
Convert these codecs	Comma separated ffprobe codec names. Common ones: av1, vc1, wmv3, wmv2, mpeg2video, msmpeg4v3 (DivX 3), mpeg4 (Xvid/DivX). Empty = convert every file whose codec differs from the target.
Convert oversized files	Also convert files larger than the max width × height, whatever their codec.
Max width / height	Downscale to fit, keeping the aspect ratio. Smaller files are never upscaled. 0 = no limit.
Encoder, preset, CRF	libx265, libx264 or libsvtav1. Lower CRF = better quality and bigger files.
Pixel format	8-bit (yuv420p) for maximum compatibility, 10-bit, or keep the source. 8-bit output from HDR sources is tone-mapped.
Container / audio	MKV keeps every audio, subtitle and attachment stream; MP4 drops subtitles. Audio can be copied or re-encoded to AAC/AC3.
Keep original if not smaller	Discard the output when it isn't smaller than the source.
Extra ffmpeg arguments	Appended before the output file, e.g. -threads 3.

Workers, time window and "Convert now"

• Workers: how many conversions run at the same time (1 on a Raspberry Pi).
• Time window: workers start tasks only inside the window (windows across midnight like 22:00 → 06:00 work). When the window closes, running ffmpeg processes are suspended with SIGSTOP and resumed with SIGCONT the next time it opens.
• Convert now: on the library page select one or more files and click Convert now (or the ⚡ icon on a row). In the queue, select queued tasks and click Convert now. Forced tasks run on a dedicated extra worker, so they start even while a regular worker holds a suspended encode, and they ignore the time window.
• Pause (Activity → Queue) suspends everything, forced tasks included, until you resume.

Telegram notifications

On Settings → Connect enter a bot token (from @BotFather) and your chat id. You can reuse the bot you already use for Sonarr/Radarr. Each event can be switched on or off:

Event	Message
File(s) queued	File name, codec, resolution, size and reason. A scan sends one summary message instead of one message per file.
Conversion done	Codec and resolution before → after, size before → after and the percentage saved.
Conversion failed	File name and the error.

Settings and environment

Variable	Default	Meaning
CONVERTERR_DATA	/config	Folder holding converterr.db
CONVERTERR_PORT	8787	HTTP port
CONVERTERR_BIND	0.0.0.0	Bind address
TZ	UTC	Timezone used by the time window
RUST_LOG	info	Log level

Everything else is set in the web UI: workers, time window, scan interval, cache folder, API key, optional UI password (HTTP Basic), Sonarr/Radarr and Telegram.

How a conversion works

1. The file is probed. Its first real video stream is encoded; every audio, subtitle and attachment stream is copied as-is.
2. The output is written to /cache/task-<id>/ and checked with ffprobe: it must be readable and match the source duration.
3. It is copied next to the original as a hidden temp file and atomically renamed over it. If the extension changes (e.g. .avi → .mkv) the original is deleted. An existing file with the target name is never overwritten.
4. Sonarr/Radarr is told to rescan, and a Telegram message is sent.

FAQ

Is it related to Unmanic? It was inspired by it, but Converterr is a separate project written from scratch in Rust. Every feature is free and there are no accounts.

Hardware encoding? Not built in yet. You can pass encoder options through Extra ffmpeg arguments, but software x265 is the safe default. Some ARM v4l2 encoders are unstable.

Will it re-convert a file it already converted? No. After a conversion the file is HEVC, so the profile rules no longer match it. Failed, skipped and cancelled files are not re-queued automatically. Use Retry in History.

REST API

All endpoints live under /api/v1 and require the API key, sent as the X-Api-Key header or as ?apikey=.

Method	Path	Description
GET	/system/status	Version, ffmpeg version, statistics
GET / PUT	/settings	Read or replace the settings
GET POST / PUT DELETE	/profile, /profile/{id}	Profiles
GET POST / PUT DELETE	/library, /library/{id}	Libraries (with statistics)
POST	/library/scan, /library/{id}/scan	Start a scan
GET	/library/{id}/files?toConvert=true&search=&page=	Probed files
GET	/queue	Queued and running tasks
POST	/queue	{"paths": ["..."], "force": true}: queue files or folders, optionally converting now
POST	/queue/force	{"ids": [1, 2]}: convert queued tasks now
POST / DELETE	/queue/{id}/top, /queue/{id}	Move to top, cancel/remove
GET / DELETE	/history?status=&page=	History, clear history
POST	/history/{id}/retry	Queue a finished task again
GET	/task/{id}/log	ffmpeg command line and output
GET / POST	/workers, /workers/pause, /workers/resume	Worker state, pause switch
POST	/webhook	Sonarr/Radarr webhook receiver
POST	/test/arr, /test/telegram	Connection tests