서비스 모음으로 돌아가기
Developer Brief
JukeRoom
같이 듣는 음악
로그인 없이 4자리 코드로 입장해 같은 공간의 사람들이 하나의 플레이리스트를 함께 만드는 실시간 음악 서비스입니다. 호스트 화면이 실제 YouTube 영상을 재생하고, 게스트는 곡을 검색·추가하며 Supabase Realtime으로 재생 상태를 함께 봅니다.
기술 스택
Next.js 16React 19TypeScriptTailwind CSS 4SupabaseTanStack Querynext-intlreact-youtube
아키텍처
별도 로그인 없이 같은 공간의 사람들이 4자리 코드로 모여 하나의 플레이리스트를 함께 만드는 실시간 서비스입니다. 호스트 화면이 실제 음악을 재생하는 단일 재생 주체(single source of truth)가 되고, 게스트는 곡을 추가하며 재생 상태를 실시간으로 함께 봅니다.
Application
- Next.js 16 App Router 기반, 호스트(재생 화면)와 게스트(대기열·곡 추가) 페이지를 분리
- react-youtube(YouTube IFrame Player API)로 호스트 화면에서 실제 영상·오디오 재생
- 서버 상태는 TanStack Query로 관리하고, Supabase Realtime 이벤트 수신 시 쿼리를 무효화해 최신 대기열을 반영
- next-intl로 한국어·영어 다국어 라우팅([locale] 세그먼트) 구성
Realtime Sync
- 방·대기열·재생 위치(play_index)를 Supabase(Postgres)에 저장하고 postgres_changes로 구독
- 호스트가 곡을 넘기면 rooms.play_index를 갱신 → 게스트는 Realtime UPDATE를 받아 동일한 '현재 곡'을 표시
- playlist 테이블 변경(곡 추가)도 별도 채널로 구독해 모든 참여자 화면에 즉시 반영
- 연결이 끊겨도 수동 재연결 버튼으로 쿼리 재요청 + 채널 재구독(subscriptionKey)해 복구
Auth & Data
- 로그인 없이 4자리 방 코드로 입장. RLS에서 anon 역할의 read/insert/update만 허용해 마찰 없는 참여 보장
- rooms·playlist 테이블을 Supabase Realtime publication에 등록
- ON DELETE CASCADE로 방 삭제 시 연결된 대기열도 자동 정리
Search & Ops
- 곡 검색은 API Key가 필요 없는 Invidious 퍼블릭 인스턴스를 우선 사용하고, 실패 시 공식 YouTube Data API로 폴백
- URL 직접 추가는 무료 oEmbed로 제목·썸네일 조회
- Vercel Cron이 매일 2일 이상 지난 방을 service-role 어드민 클라이언트로 정리
- Vercel 배포, qrcode.react로 방 URL을 QR로 공유
문제 · 해결
문제
모바일 절전·네트워크 변경 등으로 Realtime WebSocket 구독이 조용히 끊기면 대기열·재생 상태가 더 이상 갱신되지 않음
해결
수동 재연결 버튼에서 쿼리를 invalidate해 최신 데이터를 다시 받고, subscriptionKey를 증가시켜 채널을 cleanup 후 재구독하도록 구성
문제
공식 YouTube Data API 검색은 호출당 할당량(quota) 소모가 커서 무료로 운영하기 부담스러움
해결
API Key가 필요 없는 Invidious 퍼블릭 인스턴스를 우선 사용하고, 모든 인스턴스가 실패할 때만 공식 API로 폴백. URL 추가는 무료 oEmbed로 처리해 호출 비용을 최소화
스크린샷
