mctl

A self-hosted media library manager with hardware-accelerated transcoding, audio track management, and a real-time web interface.

Features

• Media library browser — scans configured directories, displays codec, resolution, bitrate, audio tracks, and file size for each file
• Hardware-accelerated transcoding — supports NVIDIA NVENC, Intel QSV, AMD AMF, and VAAPI with automatic device detection; smart CUDA fallback for incompatible source files
• Audio track management — extract, remove, and add audio tracks; external audio track library with per-file history
• Original backups — optionally keeps a backup copy of the original file before transcoding, with one-click restore
• Notification center — persistent in-app notifications for all background operations with real-time delivery via WebSockets
• Operation history — per-file log of all transcoding and audio operations
• Thumbnail preview — auto-generated thumbnails for each video file
• Statistics — tracks total files transcoded and disk space saved

Requirements

For hardware acceleration:

• NVIDIA: CUDA-capable GPU with NVENC support
• Intel: VA-API or QSV-capable iGPU/dGPU
• AMD: VAAPI or AMF-capable GPU

Installation

Docker (recommended)

# 1. Clone the repository
git clone https://github.com/yourname/mctl.git
cd mctl

# 2. Create the data directory and copy the config
mkdir data
cp config.example.json data/config.json

# 3. Edit data/config.json — add your media directory paths
# 4. Mount them in docker-compose.yml (see Configuration below)

# 5. Build and run
docker compose up -d

Open http://localhost:5000. On first run you will be prompted to create an admin account.

Manual (local development)

Requirements: Python 3.10+, ffmpeg and ffprobe in PATH, Node.js 18+ and npm.

# 1. Clone the repository
git clone https://github.com/yourname/mctl.git
cd mctl

# 2. Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate

# 3. Install Python dependencies
pip install -r requirements.txt

# 4. Install Node dependencies and build CSS
npm install
npm run build-release

# 5. Run
python app.py

Open http://localhost:5000.

Configuration

config.json is automatically created from config.example.json on first run.

For Docker, place your config at data/config.json and mount your media directories in docker-compose.yml:

volumes:
  - ./data:/data
  - /your/nas/films:/media/films:ro
  - /your/nas/series:/media/series:ro

Then reference those paths in data/config.json:

{
    "directories": ["/media/films", "/media/series"],
    "cache_dir": "/data/cache",
    "transcoded_directory": "/data/transcoded_files",
    "audio_tracks_directory": "/data/audio-tracks"
}

For local development, paths can be relative or absolute:

{
    "directories": ["/path/to/your/media"],
    "cache_dir": "cache",
    "transcoded_directory": "transcoded_files",
    "audio_tracks_directory": "audio-tracks"
}

Environment variables (Docker / advanced):

Frontend development

# Watch SCSS and rebuild on changes
npm run watch

# Production build
npm run build-release

Tech stack

• Backend: Python, Flask, Flask-SocketIO, SQLite
• Frontend: Vanilla JS, Bootstrap 5, DataTables, Socket.IO client
• Styling: SCSS compiled via Gulp, Tokyo Night color theme, JetBrains Mono font
• Media processing: ffmpeg, ffprobe

License

This project is licensed under the GNU General Public License v3.0 — see the LICENSE file for details.