Self-hosted real-time music sharing platform
Create rooms, search for music together, and stream to all participants via WebSocket — everyone hears the same moment.
🇺🇸 English | 🇰🇷 한국어
- Real-time Audio Streaming — WebSocket binary (fMP4 AAC) played via MSE, no file downloads
- Cast / AirPlay — Stream room audio to external speakers (Chromecast, HomePod, Apple TV)
- Room-based Listening — Create/join rooms, synchronized music queue sharing
- Queue Management — Drag & drop reordering, vote skip, Auto DJ
- Synced Lyrics — Line/word-level karaoke, AI translation (Gemini) & pronunciation guide
- Chat & Reactions — Real-time chat, floating emoji reactions
- Permission System — Granular per-room + per-account permission management
- Guest Access — Invite code based, join without an account
- Admin Back-office — Dashboard, user/room/track management, audit logs, IP bans
- Mobile Ready — Responsive design, iOS Safari compatible (ManagedMediaSource)
- i18n — Korean/English with next-intl, cookie-based locale detection
- Self-hosted — GHCR Docker images, single
docker compose upto run
| Layer | Technology |
|---|---|
| Server | NestJS 11, TypeORM, PostgreSQL 16, raw ws WebSocket |
| Client | Next.js 16, React 19, Tailwind 4, zustand, react-query, next-intl |
| Auth | Passport (Google OAuth + Local JWT) |
| Audio | media resolver → ffmpeg (fMP4 AAC) → WebSocket binary → Browser MSE |
| Lyrics | syncedlyrics (Musixmatch) + Gemini AI translation |
| Infra | Docker, GitHub Actions, GHCR |
ShareAux is built around "listening together in the same room," making real-time sync critical.
| WebSocket (current) | HLS/DASH | |
|---|---|---|
| Latency | 1–2s | 3–10s |
| Sync | All participants hear the same point | Segment-level delay makes sync difficult |
| Server Load | Direct delivery (100 users × 16KB/s ≈ 1.6MB/s) | Same without CDN, lower with CDN |
| External Deps | None | CDN costs if needed |
| Self-hosting | Single server, self-contained | No benefit without CDN |
In a self-hosted environment without CDN, switching to HLS would only increase latency with no load reduction. For rooms under 100 users, direct WebSocket delivery is the simplest and lowest-latency approach.
# 1. Clone and configure
git clone https://github.com/Protomothis/ShareAux.git
cd ShareAux
cp .env.example .env
# Change JWT_SECRET in .env!
# Google login, lyrics translation, etc. are optional.
# 2. Run (GHCR images — no build needed)
docker compose -f docker-compose.ghcr.yml up -d
# 3. Access
# http://localhost:8080 → Admin account setup screen on first visit.💡 To build from source, use
docker compose up -dinstead.
See the Development Guide for details.
# Required: Node.js 22+, PostgreSQL 16, ffmpeg, media resolver, python3
# Start DB
docker compose up db -d
# Start server + client
./dev.sh up- Access —
http://localhost:8080(or your configured domain) - Create Admin — Setup screen appears automatically on first visit
- Create Invite Code — Admin page (
/admin) → Invite Codes → New - Invite Friends — Share the code for guest access or registration
- Create Room — Room list → + button → Enter name → Create
- Listen Together — Search tracks → Add to queue → Real-time streaming to all 🎶
💡 HTTPS is required for iOS Safari compatibility.
| Item | Minimum | Recommended |
|---|---|---|
| RAM | 512MB | 1GB+ |
| Disk | 1GB | 5GB+ (track cache) |
| CPU | 1 core | 2+ cores (concurrent streaming) |
| Docker | 20.10+ | Latest |
| Network | WebSocket support required | HTTPS + domain |
| Scale | Bandwidth | Memory |
|---|---|---|
| 1 room × 10 users | ~1.3Mbps | ~100MB |
| 5 rooms × 20 users | ~13Mbps | ~400MB |
| 10 rooms × 50 users | ~64Mbps | ~800MB |
| 10 rooms × 100 users (extreme) | ~128Mbps | ~1GB |
ffmpeg processes (1 per room) are the main CPU consumer. Memory is Node.js + ffmpeg + WS connections combined.
- Features — Rooms, playback, lyrics, chat, permissions, admin
- Deployment Guide — Docker setup, env vars, reverse proxy
- FAQ — Playback issues, iOS, configuration
- Development Guide — Local dev environment, tools, project structure
- Architecture — System design, audio pipeline, WebSocket protocol
- AI Agent Rules — For AI coding assistants (Copilot, Cursor, Kiro, etc.)
See the Deployment Guide for the full list.
| Variable | Required | Description |
|---|---|---|
DATABASE_URL |
Yes | PostgreSQL connection string |
JWT_SECRET |
Yes | JWT signing secret |
GOOGLE_CLIENT_ID |
No | Google OAuth client ID |
GOOGLE_CLIENT_SECRET |
No | Google OAuth client secret |
GEMINI_API_KEY |
No | Gemini API key (lyrics translation) |
CLIENT_URL |
Yes | Client URL (CORS) |
ShareAux is an open-source educational and portfolio project developed to learn and demonstrate web technologies such as real-time audio streaming, WebSocket communication, and MSE (Media Source Extensions). It is not a commercial music streaming service.
- Designed for private, small-scale, personal use
- Private operation via invite codes is strongly recommended
- Does not store music files; streams in real-time from external sources
- Copyright compliance for hosted content is the instance operator's responsibility
- Includes default privacy policy (
/privacy) and terms of service (/terms). Modify for your deployment - Google OAuth usage may require a privacy policy URL
AGPL-3.0. See LICENSE.