A Docker-based application that automatically converts video files to audio formats (MP3/FLAC) while preserving metadata and folder structure for Plex compatibility.
- 🔄 Automatic Monitoring: Watches directories for new video files using efficient inotify
- 🎵 Format Support: Converts MKV, WebM, MP4, AVI, MOV, WMV to MP3 or FLAC
- 📝 Metadata Preservation: Embeds title, artist, album, and track information
- 📁 Folder Structure: Maintains original directory structure in output
- ⚡ Parallel Processing: Configurable concurrent conversion jobs
- 🛡️ File Safety: Prevents processing of partial/incomplete files
- 🔄 Retry Logic: Automatic retry with exponential backoff for failed conversions
- ❤️ Health Monitoring: Built-in health check and metrics endpoints
- 🔒 Security: Runs as non-root user in container
- 🌐 Multi-Architecture: Supports both x86_64 and ARM64 platforms
docker run -d \
--name vidaud \
-v /path/to/videos:/input:ro \
-v /path/to/audio:/output \
-p 8080:8080 \
ghcr.io/devsecninja/vidaud:latest-
Download the compose file:
curl -O https://raw.githubusercontent.com/devsecninja/vidaud/main/docker-compose.yml
-
Edit the volumes in
docker-compose.yml:volumes: - /your/video/path:/input:ro # Replace with your video directory - /your/audio/path:/output # Replace with your audio directory
-
Start the service:
docker-compose up -d
-
Check the health:
curl http://localhost:8080/health
All configuration is done through environment variables. Here are the most commonly used options:
| Variable | Default | Description |
|---|---|---|
OUTPUT_FORMAT |
mp3 |
Output format: mp3 or flac |
MP3_BITRATE |
320 |
MP3 bitrate in kbps (128, 192, 320) |
FLAC_BIT_DEPTH |
16 |
FLAC bit depth (16, 24) |
MAX_PARALLEL_JOBS |
4 |
Number of concurrent conversion jobs |
SKIP_EXISTING |
true |
Skip conversion if output file exists |
LOG_LEVEL |
INFO |
Logging level (DEBUG, INFO, WARN, ERROR) |
High-Quality FLAC Output:
docker run -d \
--name vidaud-flac \
-v /path/to/videos:/input:ro \
-v /path/to/audio:/output \
-e OUTPUT_FORMAT=flac \
-e FLAC_BIT_DEPTH=24 \
-e FILENAME_PREFIX="lossless_" \
ghcr.io/devsecninja/vidaud:latestPerformance Tuning:
docker run -d \
--name vidaud-performance \
-v /path/to/videos:/input:ro \
-v /path/to/audio:/output \
-e MAX_PARALLEL_JOBS=8 \
-e STABILITY_PERIOD_SECONDS=10 \
--cpus="4.0" \
--memory="4g" \
ghcr.io/devsecninja/vidaud:latest📋 See Configuration Reference for all available options and detailed examples.
curl http://localhost:8080/healthcurl http://localhost:8080/metrics# View container logs
docker logs vidaud
# Follow logs in real-time
docker logs -f vidaudThe application intelligently extracts metadata from filenames and folder structures:
Artist - Title.mp4→ Artist and Title metadata01 - Song Title.mp4→ Track number and Title metadata/Artist/Album/Song.mp4→ Artist, Album, and Title metadata
Input: MKV, WebM, MP4, AVI, MOV, WMV Output: MP3 (320kbps, 44.1kHz) or FLAC (lossless)
Permission Errors:
- Ensure the container user (UID 1000) has write access to output directory
- Use
sudo chown -R 1000:1000 /your/audio/path
No Files Processed:
- Check that input files are in supported formats
- Verify files are stable (not being written to)
- Check logs:
docker logs vidaud
High CPU Usage:
- Reduce
MAX_PARALLEL_JOBSfor lower-end systems - Set Docker resource limits:
--cpus="2.0" --memory="2g"
Health Check Issues:
- Ensure port 8080 is accessible
- Check container status:
docker ps - View detailed logs for error messages
docker run -d \
--name vidaud-debug \
-v /path/to/videos:/input:ro \
-v /path/to/audio:/output \
-e LOG_LEVEL=DEBUG \
ghcr.io/devsecninja/vidaud:latest- Configuration Reference - Complete configuration options and examples
- Contributing Guide - Development setup and guidelines
- Code Quality - Development tools and standards
Contributions are welcome! Please see the Contributing Guide for development setup and guidelines.
This project is licensed under the MIT License - see the LICENSE file for details.
- FFmpeg Team - This project relies on the excellent FFmpeg library
- FFmpeg Test Samples - Integration tests use official test samples
⭐ Star this repository if you find it useful!