Melodee

A music system designed to manage and stream music libraries with tens of millions of songs

Features • Quick Start • Documentation • Contributing • Support

---

🎵 Overview

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.

Key Capabilities

• 📁 Smart Media Processing: Automatically converts, cleans, and validates inbound media
• 🎛️ Staging Workflow: Manual editing capabilities before adding to production libraries
• 🔄 Automated Jobs: Cron-like scheduling for library scanning and updates
• 🎵 OpenSubsonic API: Compatible with popular Subsonic and OpenSubsonic clients
• 🌐 Melodee API: Fast restful API
• 🌐 Modern Web UI: Blazor Server interface with Radzen UI components
• 🐳 Container Ready: Full Docker/Podman support with PostgreSQL

🚀 Quick Start

Prerequisites

• Podman or Docker
• Podman Compose (for Podman users)

🐍 Automated Setup (Recommended)

For a fully automated setup, run our Python setup script:

# Download and run the setup script
curl -O https://raw.githubusercontent.com/melodee-project/melodee/main/scripts/setup_melodee.py
python3 scripts/setup_melodee.py

The script will:

• Check for required dependencies (Git, Docker/Podman)
• Clone the Melodee repository (if not already present)
• Generate a secure environment configuration
• Build and start the containers automatically
• Wait for the service to be healthy
• Provide you with the URL to access the Blazor Admin UI

🐳 Manual Deploy with Podman

1. Clone the repository

   git clone https://github.com/melodee-project/melodee.git
   cd melodee

2. Configure environment variables

   # Copy and edit the example environment file
   cp example.env .env
   nano .env

   Update the following variables in .env:

   # Database password (change this!)
   DB_PASSWORD=your_secure_password_here
   
   # Port configuration
   MELODEE_PORT=8080

3. Deploy the application

   # Using Podman Compose
   podman-compose up -d
   
   # Or using Docker Compose
   docker compose up -d

4. Access the application

   • 📚 Read the documentation on how to get started
   • Web Interface: http://localhost:8080
   • Register as a new user, the first user will be setup as administrator
   • Configure clients to connect to your server
   • Enjoy an ad-free and self-hosted music streaming service 🎉

📦 Updating Melodee

To update to the latest version:

# Stop the current deployment
podman-compose down

# Pull the latest changes
git pull origin main

# Rebuild and restart
podman-compose up -d --build

Note: Database migrations are handled automatically during container startup.

🏠 Homelab Deployment

Melodee is designed to run in homelab environments with support for various hardware configurations:

• Single Board Computers: Raspberry Pi 4/5, Rock 5B, Odroid N2+
• Home Servers: Intel NUC, custom builds, used desktops
• NAS Integration: Mount external storage for large music collections
• Container Orchestration: Docker Compose, Podman Compose, or Docker Swarm

For detailed homelab deployment guides, check out our documentation.

🗂️ Volume Management

Melodee uses several persistent volumes for data storage:

Volume	Purpose	Description
melodee_storage	Music Library	Processed and organized music files
melodee_inbound	Incoming Media	New media files to be processed
melodee_staging	Staging Area	Media ready for manual review
melodee_user_images	User Content	User-uploaded avatars
melodee_playlists	Playlists	Admin defined (json base) dynamic playlists
melodee_db_data	Database	PostgreSQL data

To backup your data:

# Backup volumes
podman volume export melodee_storage > melodee_storage_backup.tar
podman volume export melodee_db_data > melodee_db_backup.tar

# Restore volumes
podman volume import melodee_storage melodee_storage_backup.tar
podman volume import melodee_db_data melodee_db_backup.tar

✨ Features

🎛️ Media Processing Pipeline

1. Inbound Processing

   • Converts media to standard formats
   • Applies regex-based metadata rules
   • Validates file integrity and metadata

2. Staging Management

   • Manual editing of metadata before production
   • Album art management
   • Quality control workflow

3. Production Libraries

   • Automated scanning and indexing
   • Multiple storage library support
   • Real-time updates

🔌 Plugin Architecture

• Media Format Support: AAC, AC3, M4A, FLAC, OGG, APE, MP3, WAV, WMA, and more
• Metadata Sources: iTunes, Last.FM, MusicBrainz, Spotify, Brave Search
• File Parsers: NFO, M3U, SFV metadata files

🌐 OpenSubsonic API

Full compatibility with Subsonic 1.16.1 and OpenSubsonic specifications:

• Real-time transcoding (including OGG and Opus)
• Playlist management
• User authentication and permissions
• Album art and metadata serving

Tested Clients

• MeloAmp (desktop)
• Melodee Player (Android Auto)
• Airsonic (refix)
• Dsub
• Feishin
• Symphonium
• Sublime Music
• Supersonic
• Ultrasonic

🎯 Job Engine

• Cron-like scheduling system
• Configurable scan intervals
• Background processing
• Progress monitoring

🔐 Authentication

Melodee supports multiple authentication methods:

• Username/Password: Traditional authentication with JWT tokens
• Google Sign-In: OAuth 2.0 authentication via Google (configurable)

API Authentication

All API endpoints (except public endpoints) require a Bearer token:

curl -H "Authorization: Bearer <JWT_TOKEN>" https://your-server/api/v1/albums

Token Refresh

Melodee implements secure token rotation:

• Access tokens: Short-lived (15 minutes default)
• Refresh tokens: Long-lived (30 days default) with automatic rotation

Google Sign-In Configuration

To enable Google Sign-In, configure the following in appsettings.json:

{
  "Auth": {
    "Google": {
      "Enabled": true,
      "ClientId": "your-google-client-id.apps.googleusercontent.com",
      "AllowedHostedDomains": [],
      "AutoLinkEnabled": false
    },
    "SelfRegistrationEnabled": true
  }
}

For API documentation including authentication endpoints, access /swagger on a running instance.

🏗️ 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

1. Clone the repository

   git clone https://github.com/melodee-project/melodee.git
   cd melodee

2. Install .NET 10 SDK

   # Follow instructions at https://dotnet.microsoft.com/download

3. Run locally

   dotnet run --project src/Melodee.Blazor

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💬 Support

• Melodee Music System: Home
• Discord: Join our community
• Issues: GitHub Issues
• Discussions: GitHub Discussions

📚 Documentation

For comprehensive documentation, including installation guides, configuration options, homelab deployment strategies, and API references, visit https://www.melodee.org.

🙏 Acknowledgments

• Built with .NET 10
• UI powered by Radzen Blazor Components
• Compatible with OpenSubsonic specification
• Music metadata from MusicBrainz, Last.FM, Spotify, and Brave Search

---

Made with ❤️ by the Melodee community