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 9 and Blazor. It provides a complete solution for processing, organizing, and serving large music libraries through both restful and OpenSubsonic-compatible APIs.

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)

🐳 Deploy with Podman

1. Clone the repository

   git clone https://github.com/sphildreth/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.

🗂️ 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
• 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

🏗️ 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 9.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/sphildreth/melodee.git
   cd melodee

2. Install .NET 9 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

🙏 Acknowledgments

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

---

Made with ❤️ by the Melodee community