A comprehensive music video management and discovery platform that helps you organize, discover, and stream your music video collection with intelligent artist management and advanced search capabilities.
- 🎯 Advanced Artist Management - Multi-criteria search and bulk operations
- 🔍 Comprehensive Video Discovery - Dual-source integration (IMVDb + YouTube)
- 🖼️ Advanced Thumbnail Management - Multi-source search and cropping
- 📁 Intelligent Organization - Automatic folder creation and cleanup
- 🔎 Advanced Search System - Real-time suggestions and filtering
- ⚡ Bulk Operations - Multi-select editing and batch processing
- 📺 Video Streaming - Built-in player with transcoding support
- 💚 System Health Monitoring - Comprehensive diagnostics
- ⚙️ Database-Driven Settings - Complete configuration management
- 📥 Download Management - Queue visualization and progress tracking
- 🎨 Modern UI - Left sidebar navigation with theme system
- 📺 MvTV Continuous Player - Cinematic mode for uninterrupted viewing
- 🎭 Genre Management - Automatic genre tagging and filtering
- 🔐 User Authentication - Role-based access control with security features
- 🎨 Advanced Theme System - 7 built-in themes with export/import functionality
Released: March 19, 2026
Note: This is a pre-production release following SemVer 0.x conventions. The software is feature-complete but undergoing testing and validation before the official v1.0.0 production release.
- 🔒 CVE-2026-32597: PyJWT 2.8.0 → 2.12.0 — missing
critheader validation (HIGH) - 🔒 CVE-2026-32274: black 24.3.0 → 26.3.1 — arbitrary cache file write (HIGH)
- 🐛 #197: Docker containers no longer log
git not founderrors on every health check;git_branchnow shown correctly in the sidebar - 🐛 #199: Credentials set during the installation wizard are now used for login — default
admin/mvidarrno longer overrides the wizard setup - 🐛 #200: Thumbnails are now downloaded immediately when a video download completes — no more placeholder until the first page view; YouTube URL fallback chain added (
maxresdefault→hqdefault→mqdefault)
Upgrade Note: No database migrations required. Docker image rebuild recommended.
- Auto-download scheduling priority fix, auto_download_max_videos raised from 10 to 50
- Multiple security CVEs patched (Flask, werkzeug, Pillow, PyJWT)
- Fixed allowed_video_types and 20+ artist settings not saving correctly
- VEVO/Official channel name cleanup during playlist sync
- Celery worker logging fix, authentication added to 36 API endpoints
- 🔐 API Security: Added authentication to 36 unprotected API endpoints across 6 files
- 🔐 Global 401 Interceptor: Unauthenticated users redirected to login instead of seeing error counts
- 🎬 Discovery Fix: Videos no longer set to WANTED when artist
auto_downloadis disabled - 🗑️ Artist Deletion: Fixed 500 error from orphaned playlist/download foreign key references
- 📺 Playlist Auto-Sync: YouTube monitored playlists now auto-sync every 6 hours via Celery scheduled task
- 🧹 Cleanup: Removed obsolete po-token-provider process causing FATAL crashes on startup
- 🛡️ WAF Fixes: Resolved false positives blocking URLs, cookies, and Range headers
- 📺 Video Streaming: Range header no longer blocked by security middleware
- 🔐 Auth Bridge: Fixed Flask-to-FastAPI session bridge for consistent authentication
- 📺 Playlist Sync: Fixed not detecting new videos in YouTube playlists
- ⚡ Rate Limiting: Set to 300/min with static files exempt
- 🔧 CI/CD: 28 files reformatted with black 24.3.0
- 🔐 Auth Consolidation: Unified SimpleAuth + SessionStore authentication system
- 🚫 Backdoors Removed: Eliminated
/test-loginand credential reset endpoints - 🔒 Bcrypt Passwords: Upgraded from SHA-256 to bcrypt with lazy migration on login
- 🛡️ SSRF Protection: Safe tar extraction, upload sanitization, restricted proxy hosts
- 🔑 Redis Auth: Redis authentication enabled, secure cookies enforced
- 🐛 49 Vulnerabilities Fixed: 8 critical, 12 high, 16 medium, 13 low
- 11 CVEs fixed via dependency updates
- Video downloads now respect user quality settings (was defaulting to 360p)
- YouTube discovery API key caching bug fixed
- Complete fix of artist thumbnail system (0% → 87% bulk scan success)
- Manual thumbnail setting fixed, Google Images priority, Wikimedia compatibility
- Redis configuration environment variables (REDIS_HOST, REDIS_PORT)
- Per-artist video type filtering for autodownload (Issue #191)
- Extended YouTube discovery (live performances, concerts, acoustic versions)
- Increased max_videos_per_discovery from 5 to 50
- Fixed blacklist not saving info (Issue #190)
- Fixed non-existent fields from blacklist POST endpoint
- Blacklist API/model mismatch fixes
- Pagination fixes
- Database-driven scheduling with web UI management
- Code cleanup & optimization (71.4% size reduction)
- Security hardening (30 issues fixed)
- Docker architecture simplification (3-container deployment)
- Complete subtitle implementation (WebVTT, SRT, ASS, SSA, SUB)
- Smart YouTube language resolution
- User testing fixes (8/8 critical issues resolved)
- 100% Flask to FastAPI migration complete
Simple 3-Container Architecture:
- mvidarr - FastAPI application + Celery worker (managed by supervisord)
- mariadb - Database
- redis - Cache and job queue
Installation Steps:
-
Clone the repository:
git clone https://github.com/prefect421/mvidarr.git cd mvidarr -
Create your environment file:
cp .env.example .env
-
Edit .env with your configuration:
nano .env # or use your preferred editorRequired settings:
DB_PASSWORD- Set a secure database passwordMYSQL_ROOT_PASSWORD- Set a secure root passwordSECRET_KEY- Generate with:openssl rand -hex 32MUSIC_VIDEOS_PATH- Path to your music video collection
-
Start MVidarr:
docker-compose up -d
-
Access the application:
- Open your browser to
http://localhost:5000 - Default login:
admin/admin(change immediately) - Complete the first-run setup wizard
- Open your browser to
Docker Images:
- Latest:
ghcr.io/prefect421/mvidarr:latest - Specific version:
ghcr.io/prefect421/mvidarr:v0.11.9
What's Running:
- All background jobs (Celery) run automatically inside the main container
- Supervisord manages both FastAPI and Celery processes
- Simple, efficient, and optimized for home users
Prerequisites:
- Python 3.12+
- MariaDB 11.4+ (recommended)
- FFmpeg (for video processing)
Installation:
# Clone and setup
git clone https://github.com/prefect421/mvidarr.git
cd mvidarr
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt
# Start FastAPI application
python fastapi_app.pyProduction Service:
# Install as systemd service (recommended)
sudo cp mvidarr.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable mvidarr.service
sudo systemctl start mvidarr.service
# Check service status
sudo systemctl status mvidarr.serviceAccess: http://localhost:5000
- Installation Guide - Docker, Manual, and Unraid installation
- Unraid Installation - Complete Unraid setup guide
- User Guide - Feature documentation and tutorials
- Configuration Guide - Settings and customization
- Troubleshooting - Common issues and solutions
- API Documentation - REST API reference and OpenAPI docs
- Deployment Guide - Production deployment with background jobs
- Docker Optimization - Container optimization
- Security Implementation - Security features
- Architecture - System architecture and design
MVidarr is built with modern, high-performance architecture:
- Backend: FastAPI (Python 3.12+) with async operations and advanced features
- API Layer: Comprehensive FastAPI with versioning, request logging, and auto-generated clients
- Template System: Async Jinja2 templates with performance optimization and caching
- WebSocket Support: Native FastAPI WebSockets for real-time features
- Background Jobs: Celery + Redis for reliable metadata enrichment and processing
- Database: MariaDB 11.4+ with async connection pooling and optimization
- Frontend: Modern HTML5/CSS3/JavaScript with ES6+ async patterns
- Performance: Multi-layer caching (Memory + Redis), compression, and optimization
- Testing: Enterprise-grade validation and load testing frameworks
- Media Processing: FFmpeg, yt-dlp for video downloading and processing
- Authentication: Secure user management with role-based access control
- Security: bcrypt password hashing, session management, audit logging
- Containerization: Optimized Docker Compose with multi-stage builds, automated monitoring, and 1.41GB production images
Configuration is managed through:
- Database settings (preferred for production)
- Environment variables
- Docker Compose environment files
Key environment variables:
# Database
DB_HOST=mariadb
DB_PASSWORD=secure_password
SECRET_KEY=your-secret-key
# External APIs
IMVDB_API_KEY=your-imvdb-key
YOUTUBE_API_KEY=your-youtube-key
# Background Jobs (New!)
REDIS_URL=redis://redis:6379/0
CELERY_BROKER_URL=redis://redis:6379/0
BACKGROUND_JOBS_ENABLED=trueMVidarr includes comprehensive security features:
- Multi-user authentication with role-based access (Admin, Manager, User, ReadOnly)
- Secure password hashing with bcrypt
- Session management with secure tokens and expiration
- Account lockout protection against brute force attacks
- Password reset functionality with secure tokens
- Audit logging for user actions and system events
- SQL injection prevention with parameterized queries and ORM
- Docker security with non-root containers and isolated networking
- Personal Music Video Collections - Organize and stream your collection
- Music Discovery - Find new videos through integrated search
- Media Center Integration - Works with Plex and other media servers
- Home Entertainment - MvTV mode for continuous viewing
- Music Research - Advanced search and filtering capabilities
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create a virtual environment:
python -m venv venv - Activate it:
source venv/bin/activate(Linux/macOS) orvenv\Scripts\activate(Windows) - Install dev dependencies:
pip install -r requirements.txt - Run tests:
pytest
This project is licensed under the MIT License - see the LICENSE file for details.
- yt-dlp - Video download and processing
- IMVDb - Music video metadata database
- YouTube API - Video discovery and streaming
- Flask - Web framework
- MariaDB - Database engine
- Documentation: Check the docs/ directory
- Issues: Report bugs via GitHub Issues
- Community: Join our discussions
MVidarr v0.11.9 - Built with ❤️ for music video enthusiasts
