---
## What is Monochrome?
**Monochrome** is an open-source, privacy-respecting, ad-free [TIDAL](https://tidal.com) web UI, built on top of [Hi-Fi](https://github.com/binimum/hifi-api). It provides a beautiful, minimalist interface for streaming high-quality music without the clutter of traditional streaming platforms.
---
## Features
### Audio Quality
- High-quality Hi-Res/lossless audio streaming
- Support for local music files
- Intelligent API caching for improved performance
### Interface
- Dark, minimalist interface optimized for focus
- 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
- Playlist import from other platforms
- Public playlists for social sharing
- Smart recommendations for new songs, albums & artists
### 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
- Last.fm and ListenBrainz integration for scrobbling
- Unreleased music from [ArtistGrid](https://artistgrid.cx)
- Dynamic Discord Embeds
- Multiple API instance support with failover
### Power User Features
- Keyboard shortcuts for power users
---
## Quick Start
### Live Instance
Our Recommended way to use monochrome is through our official instance:
**[monochrome.tf](https://monochrome.tf)**
For alternative instances, check [INSTANCES.md](INSTANCES.md).
---
## Self-Hosting
NOTE: We only allow authorized domains to use our firebase authentication system, so unless you switch to your own firebase project, accounts wont work.
### Option 1: Docker (Recommended)
```bash
git clone https://github.com/monochrome-music/monochrome.git
cd monochrome
docker compose up -d
```
Visit `http://localhost:3000`
### Tailscale Access
Visit `http://: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: [''], // e.g. pi5.tailf5f622.ts.net
},
```
3. Restart with a fresh container (if already running):
```bash
docker compose down
docker compose up -d
```
For PocketBase, development mode, and advanced setups, see [DOCKER.md](DOCKER.md).
### Option 2: Manual Installation
#### Prerequisites
- [Node.js](https://nodejs.org/) (Version 20+ or 22+ recommended)
- [Bun](https://bun.sh/) or [npm](https://www.npmjs.com/)
#### 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
```
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 |
| `→` | Next track |
| `←` | Previous track |
| `↑` | Volume up |
| `↓` | Volume down |
| `M` | Mute/Unmute |
| `L` | Toggle lyrics |
| `F` | Fullscreen |
| `/` | Focus search |
### 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
---
