docker-mediaproc: FFmpeg, Sox, and ImageMagick Over SSH

Posted on by

I keep ending up in the same situation. I’ve got a server somewhere with files that need media processing — videos to transcode, audio to convert, images to resize — and the tools aren’t installed. Or they’re the wrong version. Or the server is some minimal cloud instance with nothing but Python and nginx on it.

The obvious fix is a Docker container with everything pre-installed. But then you need a way to interact with it remotely — upload files, run commands, download results. The usual answer is wrapping everything in an HTTP API, which means writing a whole web server just to call ffmpeg -i input.mp4 output.wav.

So I built docker-mediaproc on top of docker-lockbox. FFmpeg 7.1, Sox, ImageMagick, and 2200+ fonts in a locked-down container accessible over SSH. Upload files, run commands, download results. No HTTP server, no API framework, no shell access.

What’s Inside

This is lockbox with media tools installed and whitelisted. That’s it. No custom code, no wrappers, no middleware. The Dockerfile installs the tools, the allowed.json tells lockbox which commands are permitted, and lockbox handles everything else — SSH auth, command validation, file operations, path sandboxing.

The allowed commands:

  • ffmpeg — video/audio encoding, transcoding, filtering
  • ffprobe — media file analysis
  • sox — audio processing
  • soxi — audio file info
  • convert — ImageMagick image conversion/manipulation
  • identify — ImageMagick image file info
  • magick — ImageMagick CLI

FFmpeg comes with frei0r video effect plugins, LADSPA audio plugins (SWH, TAP, CMT), and LV2 support. Not just the bare encoder — the full plugin ecosystem for effects and filters.

Setup

# One-liner install
curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-mediaproc/main/install.sh | sudo bash
# Add your SSH key
cat ~/.ssh/id_rsa.pub >> ~/.mediaproc/authorized_keys
# Start
mediaproc start -d
ssh -p 2222 mediaproc@localhost "ffmpeg -version"
mediaproc start -d               # detached
mediaproc start -d -p 22         # custom port (default 2222)
mediaproc start -d -c 4          # limit to 4 CPUs
mediaproc start -d -r 4g         # limit to 4GB RAM
mediaproc start -d -s 2g         # limit swap to 2GB
mediaproc start -d -f /path/to/fonts  # custom fonts directory
mediaproc stop
mediaproc status
mediaproc logs
mediaproc upgrade
mediaproc uninstall

The installer creates ~/.mediaproc/ with docker-compose, a CLI wrapper, and a .env that persists all flags. All settings stick between restarts.

Usage

Upload files, run commands, download results. All file paths are relative to /work inside the container.

# Upload a video, transcode it, download the result
ssh mediaproc@host "put input.mp4" < input.mp4 ssh mediaproc@host "ffmpeg -i /work/input.mp4 -c:v libx264 /work/output.mp4" ssh mediaproc@host "get output.mp4" > output.mp4
# Get video info as JSON
ssh mediaproc@host "ffprobe -v quiet -print_format json -show_format /work/video.mp4"
# Apply frei0r glow effect
ssh mediaproc@host "ffmpeg -i /work/in.mp4 -vf frei0r=glow:0.5 /work/out.mp4"
# Convert audio format
ssh mediaproc@host "sox /work/input.wav /work/output.mp3"
# Resize image
ssh mediaproc@host "convert /work/input.png -resize 50% /work/output.png"
# Create thumbnail
ssh mediaproc@host "convert /work/input.jpg -thumbnail 200x200 /work/thumb.jpg"

File management works the same as any lockbox container — put, get, list-files, create-dir, remove-file, and the rest. All sandboxed to /work, no escape possible.

Fonts

Over 2200 fonts pre-installed, covering pretty much every script and use case. This matters for ffmpeg text overlays and ImageMagick text rendering — nothing worse than getting □□□□ because the container doesn’t have the right font.

  • Core — DejaVu, Liberation, Ubuntu, Roboto, Open Sans
  • Emoji & CJK — Noto Color Emoji, Noto Sans CJK (Chinese, Japanese, Korean)
  • Monospace — Fira Code, Hack, Inconsolata
  • International — Arabic, Thai, Khmer, Lao, Tibetan, Indic scripts

Need more? Mount your custom fonts to /usr/share/fonts/custom and the container rebuilds the font cache automatically on startup.

The Bottom Line

FFmpeg 7.1, Sox, and ImageMagick in a locked-down container. Upload files over SSH, run commands, download results. No shell access, no HTTP API to maintain, no tools to install on the host. Seven commands whitelisted, everything else blocked.

Go grab it: github.com/psyb0t/docker-mediaproc

Licensed under WTFPL — because media processing shouldn’t require a license lawyer.