SonomaDocs

Room server

Listening rooms need a small WebSocket server that relays "what's playing" between people. It's server/server.js, about 60 lines, with no database.

#Run it

bash
npm install
npm run server            # ws://localhost:8787
PORT=9000 npm run server  # another port

Point Sonoma at it under Settings → Listening rooms (for friends on the internet, use your public address, e.g. wss://rooms.example.com).

#Running it publicly

Put it behind a reverse proxy that adds TLS, so clients can use wss://. With Caddy:

text
rooms.example.com {
	reverse_proxy 127.0.0.1:8787
}

Keep it running with systemd (/etc/systemd/system/sonoma-rooms.service):

ini
[Unit]
Description=Sonoma listening rooms
After=network.target

[Service]
WorkingDirectory=/opt/sonoma
ExecStart=/usr/bin/node server/server.js
Environment=PORT=8787
Restart=always
User=www-data

[Install]
WantedBy=multi-user.target

The server has no accounts: anyone who knows a room code can join.

#Protocol

All messages are JSON. The server adds serverTime (ms since epoch) to everything it sends.

#Client → server

typeFieldsMeaning
joinroom, profile: { name, avatar, color }Join or create a room (code is upper-cased, max 16 chars). The first person becomes host.
statetrack: { title, artist, duration }, playing, positionHost only: what's playing and where.
chattextChat message (max 500 chars).
sync—Ask for the current state again.
pingtClock check; answered with pong.

#Server → client

typeFieldsMeaning
joinedroom, you, host, stateYou're in. host tells you if you're the host.
membersmembers: [{ id, profile, host }]Sent whenever someone joins or leaves.
statestate: { track, playing, position, updatedAt }The host's playback.
chatfrom, textA chat message.
promoted—The host left and you're the new host.
pongtReply to ping; use serverTime to estimate clock offset.
errormessageE.g. "Room is full" (20 people max).

#Staying in sync

Clients estimate the clock offset from ping/pong, then compute where the host is right now:

text
expected = position + (playing ? (now + offset - updatedAt) / 1000 : 0)

and seek when they drift more than 0.6 s. The host re-sends its state every 5 seconds while playing.