401 lines
11 KiB
Markdown
401 lines
11 KiB
Markdown
<p align="center">
|
|
<a href="https://monochrome.tf">
|
|
<img src="https://github.com/monochrome-music/monochrome/blob/main/public/assets/512.png?raw=true" alt="Monochrome Logo" width="150px">
|
|
</a>
|
|
</p>
|
|
|
|
<h1 align="center">Monochrome</h1>
|
|
|
|
<p align="center">
|
|
<strong>An open-source, privacy-respecting, ad-free music app.</strong>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="https://monochrome.tf">Website</a> -
|
|
<a href="https://ko-fi.com/monochromemusic">Donate</a> -
|
|
<a href="#features">Features</a> -
|
|
<a href="#usage">Usage</a> -
|
|
<a href="#self-hosting">Self-Hosting</a> -
|
|
<a href="CONTRIBUTING.md">Contributing</a>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="https://github.com/monochrome-music/monochrome/stargazers">
|
|
<img src="https://img.shields.io/github/stars/monochrome-music/monochrome?style=for-the-badge&color=ffffff&labelColor=000000" alt="GitHub stars">
|
|
</a>
|
|
<a href="https://github.com/monochrome-music/monochrome/forks">
|
|
<img src="https://img.shields.io/github/forks/monochrome-music/monochrome?style=for-the-badge&color=ffffff&labelColor=000000" alt="GitHub forks">
|
|
</a>
|
|
<a href="https://github.com/monochrome-music/monochrome/issues">
|
|
<img src="https://img.shields.io/github/issues/monochrome-music/monochrome?style=for-the-badge&color=ffffff&labelColor=000000" alt="GitHub issues">
|
|
</a>
|
|
</p>
|
|
|
|
---
|
|
|
|
## What is Monochrome?
|
|
|
|
**Monochrome** is an open-source, privacy-respecting, ad-free [TIDAL](https://tidal.com) web UI, built on top of Hi-Fi. It provides a beautiful, minimalist interface for streaming high-quality music without the clutter of traditional streaming platforms.
|
|
|
|
[](https://monochrome.tf/album/90502209)
|
|
|
|
## [](https://monochrome.tf/album/413189044)
|
|
|
|
## 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
|
|
- High-quality Music Videos
|
|
- 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](https://artistgrid.cx)
|
|
- 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.tf](https://monochrome.tf)** / **[monochrome.samidy.com](https://monochrome.samidy.com)**
|
|
|
|
For alternative instances, check [INSTANCES.md](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.
|
|
|
|
### Option 1: Docker (Recommended)
|
|
|
|
```bash
|
|
git clone https://github.com/monochrome-music/monochrome.git
|
|
cd monochrome/docker
|
|
cp .env.example .env # or copy from .env.local
|
|
docker compose up -d
|
|
```
|
|
|
|
Visit `http://localhost:3000`
|
|
|
|
---
|
|
|
|
### Synology NAS Setup
|
|
|
|
This guide covers running Monochrome on a Synology NAS using Docker.
|
|
|
|
#### Prerequisites
|
|
|
|
- Docker Package installed on your Synology
|
|
- SSH access to your NAS (optional, for troubleshooting)
|
|
|
|
#### Step 1: Prepare Directories
|
|
|
|
1. Create a shared folder for Monochrome (e.g., `docker/monochrome`)
|
|
2. Upload the project files to this folder, or clone directly via SSH:
|
|
```bash
|
|
cd /volume1/docker/monochrome
|
|
git clone https://github.com/monochrome-music/monochrome.git .
|
|
```
|
|
|
|
#### Step 2: Configure Environment
|
|
|
|
1. Navigate to the `docker` folder
|
|
2. Copy the `.env` file (or create from `.env.local`):
|
|
```bash
|
|
cd docker
|
|
cp .env.local .env
|
|
```
|
|
3. Edit `.env` with your settings:
|
|
|
|
```bash
|
|
# Port for the web interface
|
|
MONOCHROME_PORT=3000
|
|
|
|
# Enable authentication (set to true to require login)
|
|
AUTH_ENABLED=false
|
|
|
|
# Secret key - generate with: openssl rand -base64 32
|
|
AUTH_SECRET=your-random-secret-key-here
|
|
|
|
# PocketBase URL (internal Docker network)
|
|
POCKETBASE_URL=http://pocketbase:8090
|
|
|
|
# Session duration (7 days in milliseconds)
|
|
SESSION_MAX_AGE=604800000
|
|
|
|
# PocketBase Admin credentials
|
|
PB_ADMIN_EMAIL=admin@monochrome.local
|
|
PB_ADMIN_PASSWORD=your-secure-password
|
|
TZ=Asia/Ho_Chi_Minh # Adjust to your timezone
|
|
POCKETBASE_PORT=8090
|
|
```
|
|
|
|
#### Step 3: Start the Container
|
|
|
|
Using SSH or the Docker UI:
|
|
|
|
```bash
|
|
cd /volume1/docker/monochrome/docker
|
|
docker compose up -d
|
|
```
|
|
|
|
Or in Docker Desktop / Container Manager:
|
|
|
|
1. Navigate to your project folder
|
|
2. Select `docker-compose.yml`
|
|
3. Click "Run"
|
|
|
|
#### Step 4: Access the Application
|
|
|
|
- **Local:** `http://<your-nas-ip>:3000`
|
|
- **External:** Set up Synology Reverse Proxy (see below)
|
|
|
|
#### Optional: Set Up Reverse Proxy (HTTPS)
|
|
|
|
1. Go to **Control Panel > Application Portal > Reverse Proxy**
|
|
2. Click **Create**
|
|
3. Configure:
|
|
- **Source:**
|
|
- Protocol: HTTPS
|
|
- Hostname: `monochrome.yourdomain.com` (your domain)
|
|
- Port: 443
|
|
- **Destination:**
|
|
- Protocol: HTTP
|
|
- Hostname: `localhost`
|
|
- Port: 3000
|
|
4. Save and access via `https://monochrome.yourdomain.com`
|
|
|
|
#### Optional: Enable User Authentication
|
|
|
|
1. Edit `.env`:
|
|
```bash
|
|
AUTH_ENABLED=true
|
|
```
|
|
2. Restart the container:
|
|
```bash
|
|
docker compose down && docker compose up -d
|
|
```
|
|
|
|
#### Common Commands
|
|
|
|
```bash
|
|
# View logs
|
|
docker compose logs -f
|
|
|
|
# Restart
|
|
docker compose restart
|
|
|
|
# Update & rebuild
|
|
docker compose pull && docker compose up -d --build
|
|
|
|
# Stop
|
|
docker compose down
|
|
|
|
# Stop and remove data (WARNING: loses all user data)
|
|
docker compose down -v
|
|
|
|
# Backup PocketBase data
|
|
docker compose exec pocketbase tar czf - /pb_data > ../backup_monochrome.tar.gz
|
|
|
|
# Restore PocketBase data
|
|
docker compose exec pocketbase tar xzf - -C / < ../backup_monochrome.tar.gz
|
|
```
|
|
|
|
### 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:
|
|
|
|
```js
|
|
preview: {
|
|
host: true,
|
|
allowedHosts: ['<your_tailscale_hostname>'], // e.g. pi5.tailf5f622.ts.net
|
|
},
|
|
```
|
|
|
|
3. Restart with a fresh container (if already running):
|
|
|
|
```bash
|
|
docker compose down
|
|
docker compose up -d
|
|
```
|
|
|
|
For development mode and advanced setups, see [DOCKER.md](DOCKER.md).
|
|
|
|
### Option 2: Manual Installation
|
|
|
|
#### Prerequisites
|
|
|
|
- [Bun](https://bun.sh/) (Preferred) or [Node.js](https://nodejs.org/) (Version 20+ or 22+ recommended)
|
|
|
|
#### Local Development
|
|
|
|
1. **Clone the repository:**
|
|
|
|
```bash
|
|
git clone https://github.com/monochrome-music/monochrome.git
|
|
cd monochrome
|
|
```
|
|
|
|
2. **Install dependencies:**
|
|
|
|
```bash
|
|
bun install
|
|
# or
|
|
npm install # NPM is included with Node.js
|
|
```
|
|
|
|
3. **Start the development server:**
|
|
|
|
```bash
|
|
bun run dev
|
|
# or
|
|
npm run dev
|
|
```
|
|
|
|
4. **Open your browser:**
|
|
Navigate to `http://localhost:5173/`
|
|
|
|
#### Building for Production
|
|
|
|
```bash
|
|
bun run build
|
|
# or
|
|
npm run build
|
|
```
|
|
|
|
---
|
|
|
|
## Usage
|
|
|
|
### Basic Usage
|
|
|
|
1. Visit the [Website](https://monochrome.tf) 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
|
|
|
|
| Shortcut | Action |
|
|
| ------------- | ---------------------------- |
|
|
| `Space` | Play / Pause |
|
|
| `→` | Seek forward 10s |
|
|
| `←` | Seek backward 10s |
|
|
| `Shift` + `→` | Next track |
|
|
| `Shift` + `←` | Previous track |
|
|
| `↑` | Volume up |
|
|
| `↓` | Volume down |
|
|
| `M` | Mute / Unmute |
|
|
| `S` | Toggle shuffle |
|
|
| `R` | Toggle repeat |
|
|
| `Q` | Open queue |
|
|
| `L` | Toggle lyrics |
|
|
| `/` | Focus search |
|
|
| `Esc` | Close modals |
|
|
| `[` | Previous visualizer preset |
|
|
| `]` | Next visualizer preset |
|
|
| `\` | Toggle visualizer auto-cycle |
|
|
| `Ctrl` + `K` | Command Palette |
|
|
|
|
### 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](CONTRIBUTING.md) for:
|
|
|
|
- Setting up your development environment
|
|
- Code style and linting
|
|
- Project structure
|
|
- Before You Contribute
|
|
- Commit message conventions
|
|
- Deployment information
|
|
|
|
---
|
|
|
|
<p align="center">
|
|
<a href="https://fmhy.net/audio#streaming-sites">
|
|
<img src="https://raw.githubusercontent.com/monochrome-music/monochrome/refs/heads/main/public/assets/asseenonfmhy880x310.png" alt="As seen on FMHY" height="50">
|
|
</a>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="https://notbyai.fyi">
|
|
<img src="https://i.samidy.xyz/Developed-By-Humans-Not-By-AI-Badge-black%402x.png" alt="Developed by Humans" height="50">
|
|
</a>
|
|
</p>
|
|
|
|
<p align="center">
|
|
Made with ❤️ by the Monochrome team
|
|
</p>
|
|
|
|
## Star History
|
|
|
|
<a href="https://www.star-history.com/#monochrome-music/monochrome&type=date&logscale&legend=top-left">
|
|
<picture>
|
|
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=monochrome-music/monochrome&type=date&theme=dark&logscale&legend=top-left" />
|
|
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=monochrome-music/monochrome&type=date&logscale&legend=top-left" />
|
|
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=monochrome-music/monochrome&type=date&logscale&legend=top-left" />
|
|
</picture>
|
|
</a>
|