drumsergio/audio-transcoder repository overview

A containerized service that watches a source folder and automatically transcodes audio files to multiple formats simultaneously.

Keep one library in several formats: lossless for the archive, lossy for phones and cars. Drop a FLAC into the source folder and the ALAC, MP3, AAC and Opus copies appear in their own trees.

⁠Features

• Watches the source folder and reacts to new, changed, renamed and deleted files.
• Writes any number of outputs in one pass, in ALAC, AAC, MP3, Opus, FLAC or WAV at the bitrate you pick.
• Mirrors the Artist/Album folder tree in every output.
• Copies lossy sources (MP3, M4A, Ogg, Opus, WMA) unchanged instead of inflating them into a lossless output.
• Fails loudly on a source that does not decode cleanly, and writes no output for it.
• Keeps ReplayGain, MusicBrainz ids, ISRC, label and sort tags in ALAC and AAC copies.
• Optionally measures every file and writes ReplayGain 2.0 track gain into the source and every output, so the whole library plays at one volume.
• Fetches synced .lrc lyrics, and writes nothing when no real lyrics are found.
• Embeds cover art if you want it.
• Writes atomically and removes orphaned outputs, but never deletes anything when a folder looks empty.
• Handles Unicode file names.
• Ships as a small container on Python 3.14-slim with FFmpeg.

⁠Quick start

curl -fsSL -o config.yaml https://raw.githubusercontent.com/GeiserX/audio-transcode-watcher/main/config.example.yaml
docker run -d --name audio_transcoder -e CONFIG_FILE=/app/config.yaml \
  -v ./config.yaml:/app/config.yaml:ro -v /path/to/flac:/music/flac:ro -v /path/to/mp3:/music/mp3 \
  drumsergio/audio-transcoder:0.7.1

Edit config.yaml first so its outputs match the folders you mount; the example writes ALAC, MP3 and AAC. Getting started⁠ has Docker Compose and the full docker run.

⁠Documentation

• Getting started⁠: Docker Compose and Docker CLI
• Configuration⁠: the full YAML example, supported codecs, CONFIG_JSON
• Usage⁠: what happens once it runs, and the verification tool
• How it works⁠: sync and watch mode, folder mirroring, safety guards, performance
• Development⁠: tests, building the image, contributing
• Roadmap⁠
• Changelog⁠

⁠Related projects

⁠License

GPL-3.0-or-later⁠