Monochrome

An open-source, privacy-respecting, ad-free music app.

Website - Donate - Features - Usage - Self-Hosting - Contributing

---

What is Monochrome?

Monochrome is an open-source, privacy-respecting, ad-free web music player. It provides a beautiful, minimalist interface for streaming high-quality music without the clutter of traditional streaming platforms.

Features

Audio Quality

• High-quality High-Res/lossless audio streaming
• Support for local music files
• API caching for improved performance

Interface

• Dark, minimalist interface optimized for focus
• Animated Album Covers For Supported Albums
• Customizable themes & Community Theme Store
• Accurate and unique audio visualizer
• Offline-capable Progressive Web App (PWA)
• Media Session API integration for system controls

Library & Organization

• Recently Played tracking for easy history access
• Comprehensive Personal Library for favorites
• Queue management with shuffle and repeat modes
• Native Podcast support & organization
• Playlist import from other platforms
• Public playlists for social sharing
• Smart recommendations for new songs, albums & artists
• Infinite Recommendation Radio
• Explore Page (Hot & New) for discovering newly added music and whats trending overall or within each genre

Lyrics & Metadata

• Lyrics support with karaoke mode
• Genius integration for lyrics
• Track downloads with automatic metadata embedding

Integrations

• Account system for cross-device syncing
• Customizable & Public Profiles
• Real-time Listening Parties for synced playback with friends
• Last.fm and ListenBrainz integration for scrobbling
• OAuth support (Google, Discord, GitHub, Spotify)
• Unreleased music from ArtistGrid
• Dynamic Discord Embeds
• Artist Biography + Social Links for learning more about your favorite artists
• Multiple API instance support with failover

Power User Features

• Keyboard shortcuts & Command Palette (CTRL+K) for power users

---

Quick Start

Live Instance

Our Recommended way to use monochrome is through our official instance:

monochrome.st

For alternative instances, check INSTANCES.md.

---

Self-Hosting

NOTE: Accounts will not work on self-hosted instances. Our Appwrite authentication system only allows authorized domains.

We had to heavily customize the authentication system and write several custom scripts to support features like SMTP and Google OAuth (which are currently bugged in Appwrite). Because of this, we can no longer provide a self-hostable accounts system.

[!WARNING] You will not be able to stream music after self-hosting and placing the website on a domain. Our API is configured to only accept official instances of Monochrome so you can only stream music on localhost after self-hosting. However, if you have a working and paid HiFi API endpoint then Settings > Instances > Turn on Dev Mode > Place your endpoint there.

Option 1: Docker (Recommended)

git clone https://github.com/monochrome-music/monochrome.git
cd monochrome/docker
docker compose up -d

Visit http://localhost:3000

Tailscale Access

Visit http://<tailscale_server_hostname_or_ip>:3000

By default, the app uses Vite preview, which restricts access to localhost.
To allow access over Tailscale:

1. Open vite.config.js

2. Uncomment and configure the preview section:

preview: {
    host: true,
    allowedHosts: ['<your_tailscale_hostname>'], // e.g. pi5.tailf5f622.ts.net
},

3. Restart with a fresh container (if already running):

docker compose down
docker compose up -d

For development mode and advanced setups, see DOCKER.md.

Option 2: Manual Installation

Prerequisites

• Bun (Preferred) or Node.js (Version 20+ or 22+ recommended)
• Git

Apple Music Search

Monochrome requests an Apple Music developer token from https://am-mint.binimum.org/token in the browser and caches it locally until the JWT expires. Apple Music supplies catalog ordering and autocomplete suggestions; when token minting, Apple's API, or CORS is unavailable, Monochrome automatically uses its existing search ordering.

When Apple exposes editorial motion artwork for a matched album, Monochrome also uses its square HLS video cover on album and now-playing surfaces, with the static cover retained as the fallback.

PocketBase Schema

The current PocketBase collection schema is stored in database/pb_schema.json. Import this schema into a fresh PocketBase instance when setting up account data storage.

Local Development

1. Clone the repository:

   git clone https://github.com/monochrome-music/monochrome.git
   cd monochrome
   

2. Install dependencies:

   bun install
   # or
   npm install # NPM is included with Node.js
   

3. Start the development server:

   bun run dev
   # or
   npm run dev
   

4. Open your browser: Navigate to http://localhost:5173/

Building for Production

bun run build
# or
npm run build

---

Usage

Basic Usage

1. Visit the Website or your local development server
2. Search for your favorite artists, albums, or tracks
3. Click play to start streaming
4. Use the media controls to manage playback, queue, and volume

Keyboard Shortcuts

Account Features

To sync your library, history, and playlists across devices:

1. Click the "Accounts" Section
2. Sign in with Google or Email
3. Your data will automatically sync across all devices

---

Contributing

We welcome contributions from the community! Please see our Contributing Guide for:

• Setting up your development environment
• Code style and linting
• Project structure
• Before You Contribute
• Commit message conventions
• Deployment information

---

Made with ❤️ by the Monochrome team

Star History