Melodee is a comprehensive music management and streaming system built with .NET 10 and Blazor. It provides a complete solution for processing, organizing, and serving large music libraries through both RESTful and OpenSubsonic-compatible APIs.
Designed with homelab enthusiasts in mind, Melodee runs efficiently on a wide range of hardware from single-board computers like Raspberry Pi to full server setups, making it perfect for self-hosted music streaming in home environments.
🌐 Try the Demo
Experience Melodee before installing! Our official demo server is available at:
<div align="center">
Made with ❤️ by the Melodee community
</div>
Mel0deeR0cks!
Or Register: Create a free non-admin account (no email verification required)
Reset Cycle: All user data is purged every 24 hours at midnight UTC
What You Can Test
✅ Browse & Stream: Pre-loaded sample music (permissively licensed)
✅ Create Playlists: Build and share custom playlists
✅ Search: Test full-text search across artists, albums, and songs
✅ Multiple Clients: Compatible with Subsonic, OpenSubsonic, and Jellyfin clients
✅ API Explorer: Interactive API documentation at /scalar/v1
✅ User Requests: Submit requests for missing albums or songs
Demo Limitations
❌ No File Uploads: Upload functionality is disabled for security
❌ No Admin Access: Admin features are not available to demo users
⚠️ Limited Concurrent Users: Maximum 100 simultaneous connections
🔄 24-Hour Reset: All user accounts and data are deleted daily
Note: The demo server is for testing only. For production use, please install Melodee on your own infrastructure.
Key Capabilities
📁 Smart Media Processing: Automatically converts, cleans, and validates inbound media
🎛️ Staging Workflow: Optional manual editing before adding to production libraries
⚡ Automatic Ingestion: Drop files → play music (validated albums flow through automatically)
🔄 Automated Jobs: Cron-based scheduling with intelligent job chaining
📝 User Requests: Submit and track requests for missing albums/songs, with automatic completion when matches are detected
🎙️ Podcast Support: Subscribe to podcasts, auto-download episodes, playback tracking with resume positions
🎵 OpenSubsonic API: Compatible with popular Subsonic and OpenSubsonic clients
🎬 Jellyfin API: Compatible with Jellyfin music clients (Finamp, Feishin, Streamyfin)
🌐 Melodee API: Fast RESTful API for custom integrations
🌐 Modern Web UI: Blazor Server interface with Radzen UI components
🎛️ Jukebox: Server-side playback with queue/control support (OpenSubsonic jukeboxControl; MPV/MPD backends)
🎉 Party Mode: Shared listening sessions with a collaborative queue and DJ/Listener roles
🐳 Container Ready: Full Docker/Podman support with PostgreSQL
🎶 Music Ingestion Pipeline
Melodee features a fully automated music ingestion pipeline. Simply drop your music files into the inbound folder and they'll be processed, validated, and made available for streaming—typically within 15-20 minutes.
| Step | What Happens | Automatic? |
|------|--------------|------------|
| 1. Drop | Place music files (MP3, FLAC, etc.) in the inbound folder | You do this |
| 2. Process | Files are scanned, metadata extracted, validated, and moved to staging | ✅ Automatic |
| 3. Review | Albums marked "Ok" are automatically promoted; others await manual review | ✅ Automatic for valid albums |
| 4. Move | Validated albums move from staging to storage library | ✅ Automatic |
| 5. Index | Albums in storage are indexed into the database | ✅ Automatic |
| 6. Stream | Music is available via OpenSubsonic API and web player | Ready to play! |
Automatic vs Manual Mode
Automatic Mode (Default): Jobs chain together—when one completes successfully, it triggers the next. Well-tagged music flows from inbound to playable without intervention.
Manual Mode: Trigger jobs individually from the admin UI for troubleshooting or when you want to review albums before promotion. Manual triggers don't chain, giving you full control.
When Manual Review is Needed
Albums that don't pass validation (missing tags, artwork issues, etc.) stay in staging for manual review. You can:
Edit metadata and artwork in the web UI
Mark albums as "Ok" when ready
Use the "Move Ok" button to promote them
Delete albums that shouldn't be imported
🚀 Quick Start
🌐 Try the Demo First!
Before installing, test drive Melodee on our demo server:
# Find highly-rated jazz you haven't heard recently
genre:Jazz rating:>=4 lastPlayedAt:<-90d
# Pink Floyd albums from the 70s
artist:"Pink Floyd" year:1970-1979
# Recently added music you haven't played yet
added:-7d plays:0
See the full MQL Documentation for complete field reference and examples.
🔌 Plugin Architecture
Media Format Support: AAC, AC3, M4A, FLAC, OGG, APE, MP3, WAV, WMA, and more
For API documentation including authentication endpoints, access /scalar/v1 on a running instance. Download the OpenAPI specification at /openapi/v1.json. For OpenSubsonic API, refer to the OpenSubsonic specification.
🏗️ Architecture
Components
| Component | Description | Technology |
|-----------|-------------|------------|
| Melodee.Blazor | Web UI and OpenSubsonic API server | Blazor Server, Radzen UI |
| Melodee.Cli | Command-line interface | .NET Console App |
| Melodee.Common | Shared libraries and services | .NET Class Library |
System Requirements
.NET 10.0 or later
PostgreSQL 17 (included in container deployment)
2GB RAM minimum (4GB recommended)
Storage: Varies based on music library size
🤝 Contributing
We welcome contributions! Please see our Contributing Guide for details.
Development Setup
Clone the repository
git clone https://github.com/melodee-project/melodee.git
cd melodee
Install .NET 10 SDK
# Follow instructions at https://dotnet.microsoft.com/download
For comprehensive documentation, including installation guides, configuration options, homelab deployment strategies, and API references, visit https://www.melodee.org.
