258 lines
6.9 KiB
Markdown
258 lines
6.9 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="#installation">Installation</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](https://github.com/binimum/hifi-api). It provides a beautiful, minimalist interface for streaming high-quality music without the clutter of traditional streaming platforms.
|
|
|
|
<p align="center">
|
|
<a href="https://monochrome.tf/#album/90502209">
|
|
<img width="2559" height="1439" alt="image" src="https://github.com/user-attachments/assets/7973ea9f-c4aa-4c12-b476-f388f614db38" alt="Monochrome UI" width="800">
|
|
</a>
|
|
</p>
|
|
|
|
---
|
|
|
|
## 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://<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 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
|
|
|
|
---
|
|
|
|
<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">
|
|
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>
|