Files
music_quiz/docs/12-decisions.md

21 KiB
Raw Blame History

12. 확정 사항 (2026-10-18 사용자 답변)

11-questions.md 질문에 대한 사용자 답변과, 답변을 구현으로 옮길 때의 해석을 적는다. 다른 문서와 다르면 이 문서가 우선이다. 답이 없던 항목(Q9, Q11~Q19)은 추천안(★)으로 진행한다.

한눈에

# 결정 영향 문서
Q1 B안: 숨긴 유튜브 플레이어(IFrame) 로 재생. 대신 모두 같은 순간에 듣고, 버퍼링으로 한 명이 못 듣는 일이 없게 한다 08
Q2 정답인식 켜짐 = 그 요소까지 정확히 쳐야 정답. 기본값: 띄어쓰기·숫자·특수문자 모두 켬 04, 05
Q3 힌트공개에 직접선택 추가(60초 뒤). 직접선택이면 힌트인원 설정이 생기고 투표로 공개 04, 05
Q4 다시듣기 투표(모두 같이 다시 듣기), 단축키 Ctrl+R, 설정에 다시듣기인원 04, 05, 06
Q5 먼저 맞힌 1명만 +1 05
Q6 재생위치 기본값: 처음부터 04
Q7 별 N개 = N단계 곡만. 한 곡이 장르·연도에 따라 여러 단계를 가질 수 있음 04, 07
Q8 문제 수 추가. 최대는 무제한(조건에 맞는 곡 수). 끝나면 이어풀기, 퀴즈 저장·불러오기 04, 05
Q9 알아서 → 추천안(같은 묶음 "또는", 다른 묶음 "그리고") 04
Q10 기본 정답방식은 제목만, 방 설정이 제목+가수면 그대로 04
채팅 도배 방지 기본 꺼짐(관리자가 켬). 채팅은 무조건 실시간. 정답 줄과 5줄 블록 사이에 다른 말이 끼지 않게 06
쿠키 유튜브 뮤직 검색은 사용자가 준 ytm_cookie.txt 사용 (music_bot_v2 쿠키와 분리) 08, 09
.9 용량 부족하면 필요 없거나 오래된 캐시 파일 삭제(작업 중인 것 제외) 09

Q1. 재생: 숨긴 IFrame + 동기화

사용자 요구: "클라이언트가 부담하는 대신 다른 사람들과 실시간 동기화, 버퍼링 때문에 한 명이 노래를 못 듣는 경우가 없게"

  • 원칙: 참가자 전원이 들을 수 있을 때만 재생이 진행된다. 시간이 지났다고 누구를 빼고 자동으로 시작하거나, 뒤늦게 중간부터 합류시키지 않는다
  • 시계 맞추기: 접속 직후와 30초마다 ping 5회로 서버 시각 차이(offset)를 잰다(왕복 시간 가장 짧은 값 사용)
  • 소리 허용(입장 시 1회): 브라우저는 사용자가 누르기 전에는 소리 있는 재생을 막을 수 있다. 그래서 방에 들어올 때 참가 (소리 켜기) 버튼을 누르게 하고, 그 클릭 안에서 플레이어 재생·음소거 해제를 한 번 해 둔다
  • 준비 단계(문제마다): 서버가 prepare{videoId, startSec} 를 보냄 → 클라이언트는 숨긴 플레이어에 곡을 음소거로 불러 실제 재생 상태(PLAYING)가 되면(광고가 있으면 광고가 끝난 뒤) 멈추고 startSec로 되돌린 뒤 audioReady 보고
    • 전원 준비되면 서버가 play{startAt}(서버 시각, 지금+800ms)을 보냄 → 모두 같은 순간에 음소거 풀고 재생
    • 안 되는 사람이 있으면 그 사람 화면은 8초·16초에 곡을 자동으로 다시 불러온다. 다른 사람 화면에는 철수님 음원 준비 중… 표시
    • 어느 한 명이라도 영상 오류(100 삭제·101/150 퍼가기 금지)가 나면 그 곡을 모두에게서 다른 곡으로 바꾼다(문제 번호는 그대로, 그 곡은 관리자 "재생 불가"로 표시)
    • 30초가 지나도 준비가 안 되면 방장에게 철수님 빼고 이번 문제 진행 버튼이 보인다. 누르면 그 사람은 이번 문제만 제외(정답 입력·점수 없음, 화면에 "음원을 불러오지 못했어요" + 다시 시도 버튼). 자동으로 빼지는 않는다
    • 접속이 끊긴 사람은 기다리지 않는다(다시 들어오면 다음 문제부터)
  • 소리 확인: 재생 직후 0.3초 안에 isMuted() == false 이고 PLAYING 인지 확인한다. 아니거나 onAutoplayBlocked 이벤트가 오면 blocked 보고 → 아래 버퍼링과 똑같이 모두 일시정지, 그 사람 화면에 크게 눌러서 소리 켜기 버튼 → 누르면 다시 준비 → 모두 같은 위치에서 재개
  • 재생 중 버퍼링: 클라이언트가 0.5초 넘게 버퍼링하면 stall 보고 → 서버가 모두 일시정지 → 그 사람이 다시 준비되면 새 play{startAt, atSec}로 모두 같은 위치에서 재개. 시간 상한으로 자동 진행하지 않고, 30초 넘게 멈춰 있으면 준비 단계와 같은 방장 버튼만 보인다
  • 시간 두 종류로 나눠 센다
    • 클립 정지(1초~1분): 시계가 아니라 재생 위치 기준(아래 "재생 길이")
    • 문제 제한 시간·힌트 자동 공개 시간: 문제 시작(첫 play)부터 흐른 시간에서 모두 멈춰 있던 시간(버퍼링·소리 차단·준비 대기로 인한 전체 일시정지)만 뺀 값. 클립이 정상적으로 끝난 뒤에도 이 시간은 계속 흐른다 → 1초 클립이 끝나도 15초 힌트, 60초 제한 시간에 정상 도달
    • 전체 일시정지 중에는 화면 타이머도 멈추고 잠시 멈춤 — 철수님 버퍼링 중 표시. 채팅과 정답 입력은 계속 받는다(모두 같은 위치까지 들은 상태라 공평)
  • 오차 보정: 1초마다 getCurrentTime()과 기대 위치를 비교해 0.3초 넘게 어긋나면 그 위치로 이동
  • 재생 길이(1초~1분): 시계로 멈추지 않고 재생 위치를 보고 멈춘다(getCurrentTime() >= 시작 + 길이 를 화면 갱신마다 + 10ms마다 검사). 실제 브라우저 시험에서 멈춘 위치 오차 −0.002~+0.010초(아래 표)
    • 각 클라이언트는 클립을 끝내면 clipEnd 보고. 서버는 전원 보고가 오거나 예상 끝 시각 + 3초가 지나면 클립 단계를 끝낸다 — 보고가 안 온 클라이언트가 있어도 그 화면에 정지 명령을 한 번 더 보내고, 문제 자체는 끝내지 않는다(정답 입력과 남은 제한 시간은 그대로 진행)
    • 이 3초 때문에 생기는 차이는 제한 시간 계산에 영향 없음(제한 시간은 위 규칙대로 문제 시작부터 셈)
  • 정답 노출 줄이기: 플레이어는 화면 밖에 숨기고 제목 표시 없음. 영상 ID는 준비 단계에서만 보내고 방 상태에는 넣지 않는다. (개발자도구로 보는 것까지는 막을 수 없음 — 사용자가 감수하기로 함)
  • 퍼가기 금지 영상: 노래 DB 매칭 때 oEmbed로 퍼가기 가능 여부를 확인해 안 되는 영상은 쓰지 않는다(07·08). 재생 중 오류 코드 101/150이 오면 그 곡은 건너뛰고 관리자 "재생 불가"로 표시
  • 실제 브라우저 시험 (2026-10-18, tools/prototypes/iframe-sync/run.ts): 시스템 Chrome, 자동재생 정책 document-user-activation-required, 곡 VO88htcm09E(광, Topic) 60초 지점
    항목 결과
    음소거 준비 시간 처음 시험 15회 중 14회 0.300.48초, 1회는 23초 동안 준비 실패 → 다시 불러오기·대기 규칙이 꼭 필요함을 확인. 고친 도구로 8회 반복(24회)은 모두 0.260.52초
    입장 클릭으로 소리 허용 클릭 안에서 곡을 소리 켠 채 불러 재생 → 4회 모두 재생 성공·음소거 아님. (처음엔 빈 플레이어에 재생을 걸어 오류 2가 났음 → 클릭 안에서 곡을 직접 불러오는 방식으로 고침)
    3명 동시 시작 후 위치 차이 2초 뒤 829ms → 10초 뒤 2048ms (보정 기준 0.3초보다 훨씬 작음)
    1초 클립, 시계 기준 정지(처음 방식) 실제 0.93~1.00초 → 위치 기준으로 바꿈
    1초 클립, 위치 기준 정지(지금 방식) 멈춘 위치 오차 −0.002~+0.010초 (4회 × 3명 + 클릭 없는 경우 4회)
    클릭 없이 음소거 해제 이 환경(헤드리스 크롬)에서는 막히지 않았음. 사파리·휴대폰은 더 엄격하므로 입장 클릭·소리 확인 절차를 그대로 둔다
    광고 자동 시험에서는 광고가 나오지 않아 미검증
  • 남은 검증 (5단계에서 사람이 직접): 프리미엄이 아닌 계정의 실제 PC 크롬·엣지, 아이폰 사파리, 안드로이드 크롬에서 광고가 붙는 곡, 입장 클릭 없이 들어온 경우, 1초 클립, 3명 이상 동시 시작을 확인하고 결과를 이 문서에 적는다
  • 서버 음원 캐시(A안)는 만들지 않는다 → yt-dlp·ffmpeg·음원 캐시 디스크 상한 항목은 하이라이트 분석용 일회성 처리 외에는 없음

Q2. 정답인식 기본값

  • 켜짐 = 그 요소까지 똑같이 쳐야 정답, 꺼짐 = 무시하고 비교
  • 새 방 기본값: 띄어쓰기 켬, 숫자 켬, 특수문자 켬(가장 엄격). 대소문자는 항상 무시
  • 엄격 모드라도 관리자 별칭으로 흔한 표기 차이(광 / 광 (狂), 괄호 속 영어 제목 등)는 흡수한다 — 정답 후보 만들기 규칙(05)은 그대로

Q3. 힌트

  • 힌트공개 선택지: 없음 / 15초 / 30초 / 45초 / 60초 / 직접선택
  • 직접선택일 때만 방 설정에 힌트인원(이상) 이 보인다. 선택지는 스킵인원과 같음(1명, 2명, 1/3, 1/2, 2/3, 전체), 기본 1/3
  • 게임 화면 아래 투표 줄: 스킵 1/3 옆에 힌트 0/3 을 같이 표시(직접선택일 때만)
  • 힌트 버튼·Ctrl+I 동작
    • 직접선택: 내 힌트 표 토글, 기준을 넘으면 모두에게 공개
    • 없음: 누르면 "이 방은 힌트가 꺼져 있어요" 안내(버튼은 흐리게)
    • 15~60초: 누르면 "힌트는 N초 뒤에 공개돼요"(남은 초), 공개된 뒤면 "이미 공개된 힌트예요"

Q4. 다시듣기 투표

  • 듣기 모드(듣고맞추기·가수노래)에서 문제 진행 중 다시듣기 표를 모아 기준을 넘으면 모두 같이 같은 구간을 처음부터 다시 듣는다(동기화 방식 그대로)
  • 단축키 Ctrl+R(게임 화면에서는 새로고침 대신 다시듣기, preventDefault), 버튼 다시듣기 (Ctrl+R)
  • 방 설정 다시듣기인원(이상): 없음 / 1명 / 2명 / 1/3 / 1/2 / 2/3 / 전체, 기본 1/3
  • 다시 들으면 표는 초기화되고, 또 모으면 또 들을 수 있다(문제당 횟수 제한 없음)
  • 짧은 클립(1초~1분)이면 문제 제한 시간을 다시 들은 시각부터 다시 센다. "끝까지"면 다시 들은 시각 + 곡 길이까지
  • 투표 줄 표시: 스킵 1/3 · 힌트 0/3 · 다시듣기 2/3
  • 가사보고 모드에서는 다시듣기 없음(버튼 숨김)

Q7. 난이도 N단계만 + 단계 중복

  • 별 N개 = 정확히 N단계 곡만 출제
  • 한 곡이 여러 단계를 가질 수 있다. 예) 어떤 발라드가 전체 기준으로는 5단계지만 발라드 안에서는 2단계, 90년대 곡 안에서는 3단계
  • 저장: song_levels(song_id, scope, level) — scope 는 all(전체), genre:<장르ID>, decade:<1990> 처럼 기준을 적는다
  • 출제 판정: 방에서 고른 장르·연도에 해당하는 기준(all + 고른 장르들 + 고른 연도 범위가 걸치는 10년 단위) 중 어느 하나라도 단계가 N이면 출제 후보
    • 그래서 같은 곡이 3단계 방에도, 5단계 방에도 나올 수 있다(사용자 설명대로 "단계가 중복되는 노래")
  • 관리자 노래 편집에서 기준별 단계를 보고 고칠 수 있게 한다. 자동 계산은 all 먼저, 곡이 충분히 쌓인 장르·연대부터 기준별로 계산
  • (해석이 다르면 알려 주세요 — 예: "단계를 범위로 저장" 등)

Q8. 문제 수 · 이어풀기 · 저장/불러오기

  • 문제 수 선택지: 10 / 20 / 30 / 50 / 100 / 무제한(N곡) — N은 지금 조건에 맞는 곡 수를 실시간 표시. 기본 30
    • 무제한 = 조건에 맞는 곡을 다 낼 때까지(또는 방장이 끝낼 때까지)
  • 이어풀기(결과 화면 버튼, 방장): 같은 설정으로 바로 이어서 시작, 이번 퀴즈에서 나온 곡은 모두 빼고 출제. 점수는 이어서 쌓인다. (다시 하기는 점수 0부터, 나온 곡 제외 없음)
    • 남은 곡이 없으면 "조건에 맞는 곡을 모두 풀었어요"
  • 저장: 방장이 대기실·결과 화면(또는 게임 중 일시정지)에서 퀴즈 저장 → 이름을 붙여 방장 계정에 저장. 저장 내용: 방 설정, 지금까지 나온 곡 목록, 참가자별 점수(계정 기준), 진행 문제 수
    • 디스코드 로그인 사용자만 저장 가능(게스트는 안내), 계정당 최대 20개, 오래된 것부터 지우지는 않고 직접 삭제
  • 불러오기: 대기실에서 방장이 퀴즈 불러오기 → 목록에서 선택 → 설정·나온 곡 목록·점수가 복원되고, 시작하면 나온 곡을 빼고 이어서 출제. 그 방에 다시 들어온 참가자는 저장된 점수를 이어받는다

Q10. 가수노래 맞추기 정답방식

  • 새 방 기본은 "제목만". 방장이 정답방식을 "제목+가수"로 해 두면 가수노래 모드에서도 그대로 제목+가수

채팅 (사용자 추가 요구)

  • 도배 방지 기본 꺼짐. 관리자 사이트 설정에 채팅 도배 방지 켜기/끄기와 수치(초당 횟수, 순간 횟수)를 둔다
  • 무조건 실시간: 서버는 채팅을 받는 즉시 정답 판정과 중계를 한 번에 처리한다(대기열·묶음 전송·지연 없음). 묶어서 보내는 건 "입력 중" 표시뿐
  • 정답 블록이 끊기지 않게
    • 정답이면 서버는 chat을 따로 보내지 않고 정답 줄 + 공백 5줄 블록을 한 덩어리 메시지(answer) 로 보낸다 → 그 사이에 다른 메시지가 들어갈 자리가 없음
    • 모든 채팅·정답 메시지에 방 단위 순번(seq)을 붙이고, 화면은 순번대로 그린다
    • 내가 보낸 말은 바로 화면에 보이되(지연 0) 확정 전에는 항상 맨 아래 "보내는 중" 자리에 둔다. 서버 확인이 오면 순번 자리에 들어간다 → 정답이 내 말보다 먼저 서버에 도착했으면 내 말은 블록 아래로 간다
    • 결과: 공백 블록 바로 위 줄이 항상 정답 줄

유튜브 뮤직 쿠키

  • 사용자가 준 ytm_cookie.txt 를 호스트 비밀 위치 /home/claude/.config/music_quiz/ytm_cookie.txt(권한 600)에 보관. 리포에는 넣지 않는다
  • 쓰는 곳: 노래 수집기의 YT Music 노래 검색(music_bot_v2 방식 SAPISIDHASH), 관리자 "곡 추가" 자동 채우기. 컨테이너에는 읽기 전용으로 연결(YT_COOKIE_PATH)
  • music_bot_v2 쿠키와는 분리해서 쓴다 → 차단돼도 봇에는 영향 없음
  • 쿠키 만료(로그인 필요 응답) 감지 시 관리자 대시보드에 "쿠키 갱신 필요" 표시

.9 용량

  • 이미 있는 것: docker-disk-guard.sh(남은 공간 50GB 미만이면 도커 빌드 캐시·이름 없는 이미지 삭제), disk85-alert.sh(85% 이상 알림)
  • 추가: disk-low-cleanup.sh — 남은 공간이 50GB 미만일 때 다시 받으면 되는 캐시만 지운다
    • 지움: pip·uv·npm·bun·node-gyp 설치 캐시(도커 빌드 캐시는 기존 docker-disk-guard.sh가 같은 기준으로 처리)
    • 안 지움: ~/.tmp(파일이 오래됐다고 작업이 끝났다는 보장이 없음), 모델(huggingface 등), 브라우저(playwright), 프로젝트 폴더, DB·백업, 실행 중인 설치 작업이 있으면 그 캐시
  • Q1이 B안이라 음원 캐시가 없어 이 프로젝트가 쓰는 디스크는 DB 정도(수백 MB)

4단계 확인 (2026-10-18, 사용자: "추천대로 진행")

  1. 방은 서버 메모리에만 둔다. 서버를 다시 켜면(업데이트) 방이 사라지고, 그 방에 있던 화면에는 "서버가 업데이트되면서 방이 닫혔어요" 안내가 나온다(새로고침해도 같은 안내, 탭별 sessionStorage)
  2. 4단계에 간단한 대기실 채팅을 넣는다: 한 줄 로그, 입장·퇴장·방장 바뀜 시스템 줄, 내 말 먼저 표시, 새로 들어온 사람에게 최근 100줄. 정답 판정·"입력 중"은 6단계
  3. "조건에 맞는 곡"은 원곡이 확정된 곡만 센다. 원곡 확인 중인 곡 수를 따로 보여 준다. 후보 영상만 있는 곡으로 미리 하기는 하지 않는다(팬 영상 섞임). 수집기가 따로 돌기 때문에 대기실 곡 수는 1분마다 다시 센다
  4. 게스트도 방을 만들 수 있다. 퀴즈 저장은 디스코드 계정만(5단계)
  5. 비밀번호 방은 열린 방 목록에 🔒로 보이고 들어갈 때 비밀번호를 묻는다. 비밀번호를 정하기 전에는 잠기지 않는다고 방장에게 안내
  6. 방 공개 기본값은 공개. 비공개 방은 목록에 안 나오고 코드·링크로만 들어온다

5~7단계 확인 (2026-10-18, 사용자: "나머지 전부 진행", 문서 추천안대로)

  1. 마지막 사람이 나가면 방을 바로 닫는다(사용자 요청). 끊김은 60초 자리 유지, 만들고 아무도 안 들어간 방은 5분
  2. 게임 시작은 방장이 언제든(준비는 표시만). 곡이 문제 수보다 적으면 "N곡뿐이에요" 확인 뒤 시작
  3. 정답은 첫 재생(3·2·1이 끝난 뒤)부터 인정. 카운트다운 중에 친 말은 그냥 채팅
  4. 게임 중에 들어온 사람·다시 연결한 사람은 다음 문제부터 정답 인정(지금 문제는 채팅만). 그 문제의 참가자 명단은 문제를 준비할 때 정함
  5. 문제 제한 시간: 짧은 클립은 사이트 설정 문제 하나의 제한 시간(기본 60초)과 클립 길이+5초 중 긴 쪽, "끝까지"는 곡이 끝나면 문제도 끝, 가사 모드는 보고맞출시간(무제한이면 맞히거나 스킵할 때까지)
  6. 정답 공개 5초 동안 음악은 이어서 나온다(각자 화면에서, 동기화 없이)
  7. 재생위치 "하이라이트부터": 관리자 지정·heatmap 값이 없으면 곡 길이의 30% 지점. 끝나기 5초 전보다 뒤면 처음부터
  8. 소리 허용 클릭: 대기실의 참가 (소리 켜기) 또는 게임 화면 덮개 버튼. 클릭 안에서 소리 0으로 짧은 곡을 한 번 틀었다 멈춘다
  9. 가사 카드: 두 번 이상 나오는 줄(후렴)을 뺀 첫 덩어리의 가운데 4줄, 제목 단어는 ○, 힌트가 나오면 2줄 더
  10. 초성 힌트: 한글은 초성, 영문 단어는 첫 글자 + _(예: L___ W___ A__), 정답방식이 제목+가수면 제목 - 가수 둘 다
  11. 점수판 순위: 점수 → 평균 정답 시간. 같으면 같은 순위
  12. 퀴즈 저장: 결과 화면(또는 방장이 일시정지한 동안), 저장하면 설정·나온 곡·점수(계정별). 불러오면 방 이름·공개 설정은 지금 방 것을 유지
  13. 남은 사람 검증(사람 손으로): 광고가 붙는 곡, 아이폰 사파리, 안드로이드 크롬, 클릭 없이 들어온 경우 — Q1 "남은 검증" 그대로

다음 문제까지 (2026-10-18, 사용자: "바로 다음문제 버튼도 스킵처럼 인원설정, 나머지는 추천대로")

  1. 방 설정 다음 문제까지 5/10/15/30초(기본 5초)가 서버 고정 5초를 대신한다. 맞힘·스킵·시간 초과·마지막 문제 모두 같은 시간
  2. 정답 공개 동안 노래는 계속 나온다(5~7단계 6번 그대로, 길이만 방 설정)
  3. 다음문제인원(이상)(기본 1/3명): 정답 공개 중 ⏭ 다음 문제(Ctrl+K) 표가 이 인원 이상이면 바로 넘어감. 방장 전용이 아니라 스킵처럼 투표, 기준은 방에 접속 중인 사람 수
  4. 관리자 사이트의 새 방 기본값·잠금, 퀴즈 저장·불러오기에 같이 들어간다(예전 저장본은 기본값 5초·1/3명)

새로고침 이어하기·업데이트 알림·곡 제목 특수문자 (2026-10-19, 사용자: 질문은 알아서 결정)

  1. 퀴즈 중 새로고침(같은 계정이 60초 안에 돌아옴)은 그 문제부터 그대로 이어서 한다. 5~7단계 4번의 "다시 연결한 사람은 다음 문제부터"를 이렇게 바꾼다. 처음 들어온 사람은 그대로 다음 문제부터
    • 노래가 나오는 중이면 서버가 catchup(영상, 서버 기준 시작 시각·위치)을 보내고, 새 화면은 소리를 끈 채 같은 위치에 맞춰 둔다. 브라우저는 클릭 전 소리를 막으므로 참가 (소리 켜기)를 누르는 순간 다른 사람과 같은 위치에서 소리가 난다. 다른 사람은 멈추지 않는다
    • 준비(prepare) 중이면 새 화면에 prepare를 다시 보내고 방은 그 사람의 준비를 기다린다(예전에는 이때 문제가 멈춘 채 안 넘어갈 수 있었음)
    • 방장이 끊기면 15초 동안 방장을 유지한다. 그 안에 돌아오면 그대로, 아니면 접속 중인 다음 사람에게 넘어간다(5초마다 확인). 스스로 나가기는 지금처럼 바로 넘어감
    • 서버 업데이트(재시작) 때는 지금처럼 방이 닫힌다(방은 메모리에만 있음)
  2. 업데이트 알림은 joke-app과 같다: 웹 빌드 id(<meta name="mq-build">)가 서버와 다르면 위쪽에 "업데이트 내용이 있습니다 · 지금 새로고침하기 · ✕". 퀴즈 중에도 바로 띄우고 저절로 새로고침하지 않는다
  3. 곡 제목·가수의 HTML 특수문자(&#x27;, &amp;)는 수집할 때 풀어서 저장한다. 이미 저장된 곡은 cli.ts fix-text로 한 번 고치고, 고친 곡은 원곡 찾기를 다시 하며, 깨진 키 때문에 생긴 중복은 오래된 곡으로 합친다