M3W

Self-hosted Music Player
Own your music. Play anywhere.

中文 • Features • Quick Start • Docs

---

Why Self-Host?

"Due to licensing restrictions, this song is no longer available in your region."

— Every streaming service, eventually

With M3W, your music stays yours. No songs mysteriously disappearing. No "this content is unavailable." No algorithms deciding what you can listen to.

Features

• 🎵 Multiple Libraries — Organize music into separate collections
• 📝 Cross-Library Playlists — Mix songs from different libraries
• 📱 Mobile-First — Designed for phones, works on desktop
• 🔌 Offline Mode — Full functionality without an account or internet
• 🏠 Self-Hosted — Your data stays on your server, forever
• ⚡ PWA Ready — Install as an app, play cached music offline

Quick Start

Online Demo

Try M3W at m3w.test3207.top

• Online Mode: Sign in with GitHub for multi-device sync
• Offline Mode: Click "Offline Mode" to use locally in your browser

⚠️ Demo data is reset periodically. For permanent storage, deploy your own instance.

Self-Hosted Deployment

Deploy M3W with Docker Compose (PostgreSQL + MinIO included):

# Download compose file
curl -sL https://raw.githubusercontent.com/test3207/m3w/main/docker/examples/simple/docker-compose.yml \
  -o docker-compose.yml

# Configure environment (edit docker-compose.yml)
# - Set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET for login
# - Or leave empty for offline-only mode

# Start all services
docker compose up -d

# Visit http://localhost:4000

See Deployment Guide for detailed configuration options.

Build from Source

git clone https://github.com/test3207/m3w.git
cd m3w
node scripts/setup.cjs   # Install deps, start containers, run migrations
npm run dev              # http://localhost:3000

Requires Node.js 25+ and Docker/Podman. See Development Guide.

Screenshots

Screenshots coming soon

How It Works

+---------------------------------------------+
|                   Browser                   |
|                                             |
|  +---------+  +---------+  +---------+      |
|  |Libraries|  |Playlists|  | Player  |      |
|  +---------+  +---------+  +---------+      |
|                    |                        |
|         +----------+----------+             |
|         |  Offline Mode (PWA) |             |
|         | IndexedDB + Cache   |             |
|         +----------+----------+             |
+--------------------+------------------------+
                     |
                     v (optional)
          +----------------------+
          |  Self-Hosted Server  |
          | PostgreSQL  + MinIO  |
          +----------------------+

Offline Mode: Everything runs in your browser. Music files are cached locally.

With Server: Sync across devices, persistent storage, GitHub authentication.

Tech Stack

Documentation

Document	Description
Deployment Guide	Docker Compose deployment options
Development Guide	Local development setup
PWA & Offline	Offline functionality details
LAN Access	Access from other devices

Roadmap

✅ Completed

• Core playback with offline PWA support
• Multi-library & playlist management
• Mobile-first responsive UI
• GitHub OAuth authentication
• Demo mode with periodic data reset
• Offline browsing for logged-in users

📋 Planned

• Guest data migration to account
• Lyrics display
• Desktop app

See GitHub Issues for detailed progress.

Contributing

Contributions are welcome! Please read the Development Guide first.

# Fork, clone, then:
git checkout -b feature/your-feature
npm run test
npm run lint
git commit -m "feat: your feature"

License

MIT © 2025 test3207