-
-
Connecting mobile devices to laptop via scanning QR codes
Inspiration
Immersive, room-filling audio usually requires dedicated speakers, wiring, and expensive equipment, even though people already have capable laptops, phones, and tablets in the room. Music is also inherently social. Unisong makes those existing devices work together as one listening system.
What it does
Unisong runs a host application on macOS or Windows. Devices on the same Wi-Fi network join by scanning a QR code through a browser or dedicated mobile client. The host adds music, creates playlists, and controls playback for the room.
Before playback, every active device prepares the track and reports readiness. Unisong then schedules a shared start time so the devices begin together. A reconnecting or foregrounded device catches up to the current position instead of waiting for the next track.
Unisong supports local music folders, macOS Music-library imports, saved playlists, built-in public-domain sample tracks, lyrics, cover art, per-device controls, audio extraction from local videos or supported links, and light and dark themes.
How I built it
The desktop host is built with Electron. It starts a Python gRPC core that owns authoritative room time and scheduled events, plus a FastAPI gateway that serves HTTP APIs, WebSockets, local media, and browser clients.
Clients estimate their offset from the room clock, prepare audio, report readiness and route latency, and schedule playback against a server-provided timestamp.
Codex was my primary engineering collaborator during Build Week. I supplied real multi-device logs, product requirements, and failure scenarios. Codex helped trace behavior across Electron, FastAPI, WebSockets, gRPC, Web Audio, and iOS; implement focused fixes; extract clearer module boundaries; add regression tests; and iterate on the desktop, browser, installer, and website experience. I made the product decisions, synchronization policy, interface direction, and final acceptance decisions.
Build Week scope
Unisong existed before OpenAI Build Week. This submission covers only the meaningful extensions completed during the official submission period.
The pre-event baseline is Git commit 306d361. The eligible work is documented by more than 80 dated commits in 306d361..HEAD.
Build Week additions include improved readiness-gated playback, browser and mobile catch-up, foreground recovery, safer next-track preloading, ordered device admission, Windows cold-start protection, audio extraction, licensing, diagnostics, cross-platform packaging, a public download website, major state-boundary refactoring, and expanded automated tests.
Challenges
Synchronization is not a single timer problem. Browsers throttle background pages, mobile audio sessions suspend, downloads finish at different times, output routes have different latency, and clocks drift independently. Devices may also reconnect while a track is already playing or while the next track is being preloaded.
The key was treating preparation, readiness, scheduling, playback, suspension, and catch-up as explicit states instead of hiding them behind immediate play commands.
Accomplishments
- Readiness-gated scheduled playback across different client types
- Immediate reconnect and foreground catch-up
- Safer preloaded next-track handoff
- FIFO admission when a device slot becomes available
- A complete macOS and Windows host experience
- Browser onboarding through QR codes
- Focused regression tests and compact synchronization reports
- Clearer playlist, library, extraction, and server architecture
What I learned
Reliable synchronized playback depends as much on lifecycle modeling and diagnostics as on clock mathematics. Codex was most effective when given concrete logs and explicit product constraints, followed by manual testing on real devices.
What's next
The next steps are publishing the dedicated iOS and Android clients, signing and notarizing installers, expanding automated multi-client testing, and improving adaptive latency handling across more devices and audio routes.
Log in or sign up for Devpost to join the conversation.