README.en.md

Music Together

A real-time collaborative listening platform. Run one server, then join the same rooms, queue, and synchronized playback from the web, Android, or Windows desktop client.

Simplified Chinese

Overview

Music Together consists of a Node.js server and several clients. The server coordinates rooms, identities, queues, voting, chat, and playback timing. Clients render the experience, play audio, and integrate with their host platform. All clients use the same HTTP and WebSocket protocol, so they can join the same room across devices.

Platform	Implementation	Current location	Best for
Web	React + Vite	main branch	Browsers, mobile browsers, and quick deployment
Android	Kotlin + Jetpack Compose + Media3	codex/android-native-client, v2.2.5	Native background playback, system media controls, and multi-server lobby
Windows desktop	Electron + React + TypeScript	codex/windows-native-client	Installed desktop experience and standalone windows

The Android and desktop clients are currently maintained in their own branches and do not include the server. Deploy or run the main branch server first, then configure its address in the client.

Screenshots

Web Desktop

1	2	3	4	5

Web Mobile

1	2	3	4	5

Native Android Client

Launch	1	2	3	4

Windows Desktop Client

1	2	3	4	5

Capabilities

• Real-time room synchronization with clock correction, scheduled actions, progress reporting, and drift correction
• NetEase Cloud Music, QQ Music, Kugou, Kugou Concept, and Bilibili sources
• Platform sign-in and playlists through QR/Cookie login, with quality selection based on account capability
• Rooms, password rooms, invite links, queue management, chat, roles, votes, and hidden rooms
• Sequential, single-loop, list-loop, and shuffle playback with word-by-word, translated, romanized, and Ruby lyrics
• One shared room protocol across the web, Android native player, and Windows desktop client

Architecture

Web client / Android client / Windows desktop client
                    │ HTTP + WebSocket
                    ▼
          Music Together Node.js server
                    │
     Rooms, clock sync, authentication, music and lyric proxy

The server persists room data and server-side account configuration. Music-platform cookies are sent only to the connected Music Together server. Bilibili and proxy-required audio are routed through the server so platform credentials are not exposed to other room members.

Web and Server Development

Prerequisites

• Node.js 22+
• pnpm 10+

Start locally

git clone https://github.com/LiuYunLingNai/music-together.git
cd music-together
pnpm install --frozen-lockfile
pnpm dev

• Web client: http://localhost:5173
• Server: http://localhost:3001

In default auto mode, the web client connects to the server at its current origin. Set CLIENT_URL when deploying frontend and backend separately or when an explicit origin allowlist is required.

Android Client

The Android app is native, not a WebView wrapper. It uses Kotlin, Jetpack Compose, OkHttp WebSocket, and Media3 ExoPlayer. It supports a multi-server lobby, background playback, system media controls, chat, queue management, search, platform accounts/playlists, votes, and word-by-word lyrics.

Build a debug APK

Requires JDK 17-21 (the Android Studio bundled JBR is recommended) and Android SDK 36:

git clone --branch codex/android-native-client --single-branch https://github.com/LiuYunLingNai/music-together.git
cd music-together/packages/android-client
.\gradlew.bat testStandardDebugUnitTest assembleStandardDebug

The APK is written to app/build/outputs/apk/standard/debug/app-standard-debug.apk.

• Android emulator to a server on the development machine: http://10.0.2.2:3001
• Physical device on a LAN: use the computer's LAN address, for example http://192.168.1.8:3001
• Use HTTPS for public servers. The app can store multiple server addresses and aggregate their rooms in one lobby.

The Android branch ships standard and vivo variants. Its GitHub Actions workflow builds Debug/Release APKs and a standard AAB.

Windows Desktop Client

The desktop client is an Electron, React, and TypeScript application with its own interface rather than loading the web app URL. The current branch builds Windows installers and portable executables, while retaining AppImage and deb Linux targets.

It includes server connection settings, room discovery and reconnecting, NTP clock sync, rooms/password rooms, search, queue, chat, transport controls, and Apple Music-style lyrics.

Develop and package

Requires Node.js 22+:

git clone --branch codex/windows-native-client --single-branch https://github.com/LiuYunLingNai/music-together.git
cd music-together
npm ci
npm run dev

Useful verification and packaging commands:

npm run typecheck
npm test
npm run build
npm run dist:win

Artifacts are written to release/. Windows targets are NSIS and Portable. Run npm run dist:linux for AppImage and deb packages.

Deploy the Server with Docker

docker run -d --name music-together --restart unless-stopped \
  -p 3001:3001 \
  -v /path/to/music-together-data:/app/data \
  ghcr.io/LiuYunLingNai/music-together:latest

Replace /path/to/music-together-data with a persistent host directory. It holds the server database and account-related data; recreating a container without the mount loses that data.

When serving HTTPS through Nginx, Caddy, 1Panel, or another reverse proxy, forward X-Forwarded-Proto so the server can set secure cookies correctly. Configure public clients with the proxied HTTPS address.

Repository Layout

The main branch:

packages/
  client/   Web React app
  server/   Node.js server
  shared/   Shared types, constants, and permissions

Native-client branches:

codex/android-native-client
  packages/android-client/   Kotlin/Compose Android app

codex/windows-native-client
  electron/ + src/           Electron desktop app

Documentation

• Web and server architecture
• Android client README
• Windows desktop client README

License

AGPL-3.0