MUSIXQUARE

---

Overview

MUSIXQUARE transforms smartphones, tablets, and desktop computers into a zero-installation, synchronized multi-speaker wireless sound system.

By combining low-latency Web Audio DSP graphs, peer-to-peer WebRTC data/media transports, and Cloudflare distributed edge services (Durable Objects, D1, R2), MUSIXQUARE enables real-time collaborative listening, spatial speaker role mapping, YouTube Together synchronization, and desktop system audio streaming across heterogeneous hardware.

---

Product Demo

Click the image above to watch the official MUSIXQUARE demonstration video on YouTube.

Direct Video Link: https://youtu.be/VbFwgt4l3Gc

---

System Architecture

The architecture map below is a point-in-time overview that groups MUSIXQUARE into 24 functional districts. The source tree, executable contracts, and maintained references classified in the documentation hub remain authoritative as module and dependency counts evolve.

Architecture Layout Breakdown

Column	Layer	Districts Included	Focus & Responsibilities
Col 1	Client & Presentation	BOOTSTRAP, FRAMEWORKLESS UI, CHAT & COMMANDS, ACCOUNT & AUTH, I18N LOCALES, BROWSER RUNTIME	Modular bootstrap entry, frameworkless vanilla DOM views, in-room chat and slash commands, session/auth identity, 30+ locale dictionaries, and UI-kit prototype runtimes.
Col 2	Core Domain & Governance	CORE & STATE, ROOM AUTHORITY, DIAGNOSTICS & REC, STATIC INVARIANT GUARDS	Core application state machines, event bus, room lease authority and lifecycles, flight recorder diagnostics, and static invariant CI gates / type-safety architecture contracts.
Col 3	Real-Time Media Pipeline	AUDIO GRAPH & DSP, PLAYBACK ENGINE, PLAYLIST & QUEUE, SYNC & NTP CLOCK, SYSTEM AUDIO SFU, STORAGE & CHUNKS, YOUTUBE TOGETHER, REMOTE SHARE R2	Web Audio DSP topology (5-band EQ, convolution reverb, stereo widener), audio playback controller, track queue, RTT drift sync, desktop audio SFU, and P2P R2 sharing.
Col 4	Distributed Cloud & Infra	NETWORK & WEBRTC, PRO ROOM CLIENT, CLOUDFLARE WORKERS, CLOUDFLARE DO ACTOR, CLOUDFLARE D1 SQL, PLAYWRIGHT E2E & CHAOS	Peer-to-peer WebRTC mesh data channels, Pro Room client protocol, Cloudflare Workers API routes and signaling relays, Durable Object actors, D1 SQLite schemas, and E2E chaos suites.

---

Key Features

• 6-Digit Room Access:
  • 100000 to 999999: Temporary Standard Rooms coordinated by a browser host over WebRTC, with Cloudflare signaling/TURN in production and temporary private R2 fallback when direct file delivery is unavailable.
  • 000000 to 099999: Persistent PRO Rooms backed by dedicated Cloudflare Durable Object actors with durable state and multi-device persistence.
• Dynamic Speaker Role Routing:
  • Assign connected devices in real time to Center (Stereo), Left Channel, Right Channel, or Subwoofer (Low-pass filtered).
• Browser-Native Web Audio DSP:
  • In-browser 5-band parametric equalizer, convolution reverb engine, Haas stereo widener, and virtual psychoacoustic bass enhancer.
• Latency-Aware Clock Synchronization:
  • Standard rooms utilize rolling host-relative RTT probing; PRO rooms operate via server-coordinated epoch timelines with two-phase prepare/commit rendezvous scheduling.
• YouTube Together Synchronization:
  • Synchronized playback across heterogeneous network topologies with automatic drift detection, seek compensation, and buffering state alignment.
• Desktop System Audio Streaming (Beta):
  • Broadcast low-latency tab or system audio from a desktop Chromium browser, with one publisher and up to three receivers.
  • PRO rooms use verified LAN-direct WebRTC when available; if any route is unavailable or fails, all listeners are routed together through Cloudflare Realtime SFU. See the PRO room architecture for route and privacy details.
• Private Media & Queue Management:
  • In-memory browser playback for Standard Rooms, temporary private R2 fallback for remote file delivery, and persistent private R2 object storage for PRO Rooms.
  • Before AudioBuffer decode, each device estimates decoded PCM and the projected working set and shows a local, non-blocking warning when that device tier may be at risk. If metadata cannot be read, Standard Rooms retain the legacy warning for encoded files above 200 MiB; remote-share and PRO storage limits remain hard limits.
• Localized UI:

---

Translation contributions

Suggest better wording in any of our 42 languages, including English and Korean, or recommend an existing proposal at Translate. Maintainers review proposals before they appear in a release.

Thank you to everyone who helps translate MUSIXQUARE. Your time and care mean a lot.

---

Room Types Comparison

Attribute	Standard Room	Persistent PRO Room
Code Range	100000 - 999999	000000 - 099999
Lifecycle	Temporary; terminates when browser host departs	Persistent across empty-room sleep/wake cycles
Password	Optional, host-chosen 8-digit access PIN	Optional, owner-chosen 8-digit room password
Authority Model	Browser host authoritative over WebRTC P2P	Cloudflare Durable Object server-authoritative state
Storage Backend	Browser RAM, direct WebRTC, or temporary private R2	Private Cloudflare R2 object storage (1 GiB / room, 200 MiB / file)
Presence Model	Host-managed peer roster	Server-tracked heartbeats and participant session recovery

PRO access remains operator-controlled. It may be issued directly or redeemed through a one-time operator voucher; there is no paid plan or public checkout.

To inquire about PRO access, email [email protected] or contact us on the official MUSIXQUARE Discord server.

---

Technology Stack

• Frontend Core: TypeScript (Strict Mode), Vite, HTML5 Web Audio API, WebRTC (RTCDataChannel, RTCPeerConnection), frameworkless HTML/CSS/DOM controllers.
• Signaling & Edge Backend: Cloudflare Workers, Cloudflare Durable Objects (Stateful Actors), Cloudflare D1 (Serverless SQL), Cloudflare R2 (Object Storage).
• Transport Adapters: Cloudflare TURN / STUN infrastructure, PeerJS local development adapter.
• Quality & Verification: Vitest, Playwright E2E and recovery/chaos scenarios, custom TypeScript AST invariant guards.

---

Local Development

Use the exact Node.js version in .node-version (24.22.2). Corepack then selects the pinned [email protected] from package.json:

Installation & Startup

corepack npm ci
npm run dev

Open http://localhost:3000 in your browser.

Localhost selects PeerJS for Standard-room signaling, and ordinary UI work needs no Cloudflare credentials. By default, both Vite dev and preview fail closed: the five production-proxy routes and all other unconfigured relative /api/* paths return local 503 responses. Loopback origins also keep PRO, TURN, and Realtime requests local: PRO resolves to same-origin /api/pro-room, while TURN and Realtime stop after their relative API request fails, so no implicit retry reaches musixquare.com.

For an intentional non-E2E production integration, set VITE_MUSIXQUARE_ALLOW_LOCAL_PRODUCTION_API_FALLBACK=true in untracked .env.local, then restart the dev server or rebuild before preview. A validated VITE_PRO_ROOM_ENDPOINT is an explicit override and takes precedence. Separately, MUSIXQUARE_DEV_PROXY_PRODUCTION_API=true forwards only the five named routes in Vite dev; preview never enables that proxy. Any production-backed option can consume real quota or state, so remove it after the integration run. Read CONTRIBUTING.md and the configuration reference before exercising any production-backed flow.

Test & Verification Pipeline

# Run unit and integration tests
npm test

# Run strict TypeScript compiler verification
npm run typecheck

# Run codebase linter
npm run lint

# Verify Cloudflare Worker contracts and syntax
npm run check:workers

# Run full production build with invariant validation
npm run build:checked

---

Security & Privacy Policy

• Zero Credential Exposure: Public repository contains no secrets, private keys, or credentials.
• Fail-Closed Endpoints: Backend routes reject unauthorized requests by default unless explicitly authenticated with scoped capability tokens.
• Proof-of-Work Rate Limiting: Token minting utilizes short-lived proof-of-work challenges to safeguard against resource exhaustion.
• RAM-Only Browser Media: Decoded audio buffers and streamed media chunks remain in volatile memory and are not persisted to unencrypted local storage.
• LAN Candidate Privacy: PRO LAN-direct system audio exchanges only bounded UDP host candidates between authenticated room participants through the authoritative signaling service. A valid UUID-shaped remote .local name may prove RFC 6762 local-link scope without exposing or probing a caller-selected numeric destination. Numeric remote candidates, other hidden or malformed names, and global or ambiguous address evidence select SFU. The product never weakens the test or adds TURN merely to preserve the optimization.

---

License

Copyright (c) 2025-2026 MUSIXQUARE.

MUSIXQUARE is open-source software licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).

The AGPL governs copyright permissions for the software, including covered interface code and assets. It does not grant permission to use the MUSIXQUARE Marks or any protected, distinctive, non-functional, source-identifying overall visual presentation in a manner likely to make an independent product or service appear official, affiliated, sponsored, endorsed, or operated by MUSIXQUARE. Replacing the name, logo, or icon alone may not be sufficient where the remaining public presentation is still likely to cause confusion. See the Trademark Policy, practical Brand and Fork Identification Guide, and AGPLv3 Section 7 Additional Terms.

The additional terms apply prospectively only to first-party material that expressly incorporates them. They do not revoke or narrow AGPL permissions for older copies, or prohibit distinctly branded commercial or non-commercial forks.

Third-Party Notices

• PeerJS: MIT License (see THIRD-PARTY-NOTICES.md)
• qrcode & content-shield: MIT License (see THIRD-PARTY-NOTICES.md)
• Google Material Icons: Apache License 2.0 (see distributed license)
• Pretendard Font: SIL Open Font License 1.1 (see PRETENDARD_LICENSE.txt)
• Noto Sans Fonts: SIL Open Font License 1.1 (see the Latin/Cyrillic license, CJK license, and Thai license)