15 KiB
15 KiB
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.30 0.48초, 1회는 23초 동안 준비 실패 → 다시 불러오기·대기 규칙이 꼭 필요함을 확인. 고친 도구로 8회 반복(24회)은 모두 0.260.52초입장 클릭으로 소리 허용 클릭 안에서 곡을 소리 켠 채 불러 재생 → 4회 모두 재생 성공·음소거 아님. (처음엔 빈 플레이어에 재생을 걸어 오류 2가 났음 → 클릭 안에서 곡을 직접 불러오는 방식으로 고침) 3명 동시 시작 후 위치 차이 2초 뒤 8 29ms → 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·백업, 실행 중인 설치 작업이 있으면 그 캐시
- 지움: pip·uv·npm·bun·node-gyp 설치 캐시(도커 빌드 캐시는 기존
- Q1이 B안이라 음원 캐시가 없어 이 프로젝트가 쓰는 디스크는 DB 정도(수백 MB)