문서: 개요·구조·로그인/관리자·게임 진행·채팅·유튜브 재생 설계 초안
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
42
docs/00-overview.md
Normal file
42
docs/00-overview.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# 00. 개요
|
||||
|
||||
## 한 줄 요약
|
||||
친구들끼리 방을 만들어 노래를 듣고(또는 가사를 보고) 채팅으로 제목·가수를 맞히는 실시간 음악퀴즈 사이트. 스타크래프트 "노래 맞추기" 유즈맵의 손맛(채팅으로 바로 정답, 초성 힌트, 스킵 투표)을 웹으로 옮긴다.
|
||||
|
||||
## 기본 정보
|
||||
| 항목 | 값 |
|
||||
|---|---|
|
||||
| 리포 | https://git.tkrmagid.kr/tkrmagid/music_quiz (main) |
|
||||
| 도메인 | https://mquiz.tkrmagid.kr (DNS CNAME → tkrmagid.kr 이미 등록됨) |
|
||||
| 포트 | 호스트 2974 → 컨테이너 3000 |
|
||||
| 서버 위치 | .9 (joke-app과 같은 호스트), 앞단 NPMplus(192.168.10.3)에서 HTTPS 종료 |
|
||||
| 로그인 | 디스코드 OAuth2 (앱 ID 1561284577564037140, 앱 이름 "음악퀴즈") + 게스트 |
|
||||
| 기반 | joke-app(같이 놀자 보드게임)의 구조·로그인·관리자·UI 컴포넌트를 가져와 음악퀴즈 전용으로 변형 |
|
||||
|
||||
## 범위 (이번 버전)
|
||||
- 로비: 방 목록, 방 만들기, 코드로 참여
|
||||
- 방: 인원 무제한, 방장 설정(모드·장르·연도·난이도·정답방식 등), 준비/시작/강퇴/방장 넘기기
|
||||
- 게임: 듣고맞추기 / 가수노래 맞추기 / 가사보고 맞추기, 채팅 정답, 힌트(Ctrl+I), 스킵(Ctrl+K), 점수판
|
||||
- 채팅: 화면 가운데 아래 크게, "입력 중" 표시, 지연 없는 전송, 정답 시 5줄 공백 사이 "노래제목 - 가수" 표시
|
||||
- 노래 DB: 여러 차트/플레이리스트/다른 퀴즈 사이트에서 수집 → 연도·장르·난이도 자동 분류 → 유튜브 Topic 음원 주소 등록
|
||||
- 관리자: 노래 관리(검색·필터·추가·수정·삭제), 수집 작업, 방/사이트/사용자/관리자 설정, 감사 기록
|
||||
- 슈퍼어드민: joke-app과 같은 디스코드 ID 2명
|
||||
|
||||
## 제외
|
||||
- 컴퓨터(봇)와 대결 — joke-app의 봇 관련 코드는 가져오지 않는다
|
||||
- 유료 결제, 랭킹 시즌 같은 부가 기능 (추후 검토)
|
||||
|
||||
## 문서 목록
|
||||
| 파일 | 내용 |
|
||||
|---|---|
|
||||
| 01-architecture.md | 기술 스택, 폴더 구조, joke-app에서 가져올 것/뺄 것 |
|
||||
| 02-auth-admin.md | 디스코드 로그인, 게스트, 권한(슈퍼어드민/관리자), 관리자 페이지 |
|
||||
| 03-ui-design.md | 디자인 방향, 색, 글꼴, 화면별 구성, 아이콘 |
|
||||
| 04-room-settings.md | 방 설정 항목 전체 (모드·세부모드·장르·연도·난이도·정답·힌트·스킵) |
|
||||
| 05-game-flow.md | 라운드 진행, 정답 판정, 힌트, 스킵, 점수, 단축키 |
|
||||
| 06-chat.md | 채팅 배치, 입력 중 표시, 지연 없는 전송, 정답 표시 방식 |
|
||||
| 07-song-database.md | 노래 수집 출처, DB 구조, 난이도·연도·장르 분류 |
|
||||
| 08-youtube-playback.md | 유튜브 Topic 주소 찾기(music_bot_v2·Lavalink), 재생 방식, 하이라이트 |
|
||||
| 09-deploy-ops.md | 배포, 프록시, 인증서, 백업, 모니터링 |
|
||||
| 10-roadmap.md | 작업 순서와 마일스톤 |
|
||||
| 11-questions.md | 사용자에게 확인할 질문·요청사항 |
|
||||
86
docs/01-architecture.md
Normal file
86
docs/01-architecture.md
Normal file
@@ -0,0 +1,86 @@
|
||||
# 01. 구조와 기술 스택
|
||||
|
||||
## 결정
|
||||
joke-app과 같은 스택을 쓴다. 이미 운영 중이고 로그인·관리자·채팅·실시간 방이 검증돼 있어서, 같은 틀 위에 음악퀴즈만 새로 얹는 게 가장 빠르고 안전하다.
|
||||
|
||||
| 영역 | 선택 | joke-app과 관계 |
|
||||
|---|---|---|
|
||||
| 런타임 | Bun 1.3 + TypeScript 5.9, Bun workspaces | 같음 |
|
||||
| 서버 | Hono 4 (HTTP) + Bun.serve WebSocket `/ws`, zod 4 검증 | 같음 |
|
||||
| DB | bun:sqlite (WAL), 번호 붙은 SQL 마이그레이션 | 같음 |
|
||||
| 웹 | React 19 + Vite 8 + react-router + zustand, Pretendard | 같음 |
|
||||
| 스타일 | 손으로 쓴 CSS 변수 한 벌(`global.css`), CSS 프레임워크 없음 | 구조 같음, 색·형태는 새로 |
|
||||
| 테스트 | bun test(단위·통합) + playwright-core e2e(시스템 Chrome) | 같음 |
|
||||
| 배포 | Docker compose(프록시 모드), NPMplus 뒤 | 같음, 포트만 2974 |
|
||||
| 음원 처리 | yt-dlp + ffmpeg (서버 캐시 재생 방식일 때) | 새로 추가 |
|
||||
| 곡 수집기 | Bun 스크립트(`tools/collector`), 필요시 Python 보조(하이라이트 분석) | 새로 추가 |
|
||||
|
||||
## 폴더 구조 (예정)
|
||||
```
|
||||
music_quiz/
|
||||
├─ apps/
|
||||
│ ├─ server/ # Hono + WS + 게임 진행
|
||||
│ │ ├─ src/auth/ # joke-app에서 가져옴 (discord.ts, sessions.ts, users.ts)
|
||||
│ │ ├─ src/admin/ # roles.ts, audit, settings + 노래 관리 API
|
||||
│ │ ├─ src/rooms/ # 방, 라운드 진행(quiz-engine), 투표
|
||||
│ │ ├─ src/songs/ # 곡 조회·출제 선택·정답 판정(matcher)
|
||||
│ │ ├─ src/audio/ # 음원 캐시, 클립 스트리밍
|
||||
│ │ └─ src/db/migrations/
|
||||
│ └─ web/
|
||||
│ ├─ src/pages/ # Home, Room, Game, Admin/*
|
||||
│ ├─ src/components/ # ChatPanel, StarRating, YearRange, ArtistPicker, ...
|
||||
│ └─ src/styles/global.css
|
||||
├─ packages/shared/ # 프로토콜(zod), 정답 정규화 함수(서버·클라 공용), 장르/난이도 상수
|
||||
├─ tools/collector/ # 차트·플레이리스트 수집, 유튜브 매칭, 분류
|
||||
├─ data/seed/ # sta_songs.json 등 초기 데이터
|
||||
├─ deploy/ # Dockerfile, docker-compose.proxy.yml, npmplus 설정
|
||||
├─ assets/brand/ # 아이콘
|
||||
└─ docs/ # 이 문서들
|
||||
```
|
||||
|
||||
## joke-app에서 가져올 것
|
||||
- `auth/discord.ts`, `auth/sessions.ts`, `auth/users.ts` — 디스코드 OAuth(state 서명 쿠키), `sid` 세션 쿠키, 게스트 로그인/병합
|
||||
- `admin/roles.ts` — `SUPERADMIN_DISCORD_IDS` + `admins` 표, 감사 기록(`admin_audit`)
|
||||
- `ws/rate-limit.ts`, `db/index.ts`, 마이그레이션 001~003(사용자·세션·관리자·게스트 정리)
|
||||
- 웹: `ChatPanel`/`ChatMessage`, `useTypingSignal`(입력 중 신호), `Sheet`, `Toasts`, `SiteHeader`, `NicknameForm`, `SchemaForm`(관리자 자동 폼), 관리자 레이아웃(`.admin-layout`, `.data-table`)
|
||||
- 프로토콜 방식: `{t: ...}` JSON 메시지 + zod 판별 유니온, 방 상태 브로드캐스트
|
||||
|
||||
## 가져오지 않을 것 (컴퓨터 대결 제거)
|
||||
- `packages/shared/src/bots.ts`, `packages/games/src/bots/*`, 서버 `rooms/bots.ts`·`bot-profile.ts`·`luck*.ts`·`ai/*`
|
||||
- 프로토콜 `addBot/removeBot/botLevel`, 설정 `botChat`, "컴퓨터와 연습" 타일, `/api/quick/*`, `docker-compose.ai.yml`
|
||||
- 보드게임 엔진(`cards.ts`, `grid.ts`, `betting.ts`)과 게임 카탈로그
|
||||
- `BotActivity.tsx`는 사람 "입력 중" 표시 부분만 남긴다
|
||||
|
||||
## 바뀌는 점
|
||||
- **인원 무제한**: joke-app은 좌석(seats) 배열 + 최대 32명. 음악퀴즈는 좌석 개념 없이 `players` 목록으로 관리하고 상한을 두지 않는다. 서버 보호용 상한만 관리자 설정에 두되 기본값은 "없음".
|
||||
- **방 상태 전송**: 인원이 많아도 버티도록 전체 상태 대신 변경분만 보낸다(joke-app `view-patch.ts` 활용). 점수판은 점수 변동분만, 채팅은 개별 메시지로.
|
||||
- **게임 진행**: 턴제 엔진 대신 시간 기반 라운드 진행기(`quiz-engine`)를 서버에 둔다. 서버 시계가 기준이고 클라이언트는 `serverNow` 보정값으로 카운트다운을 그린다.
|
||||
|
||||
## 실시간 메시지 (초안)
|
||||
클라이언트 → 서버
|
||||
| t | 내용 |
|
||||
|---|---|
|
||||
| `join` / `leave` | 방 입장/퇴장 |
|
||||
| `config` | (방장) 방 설정 변경 |
|
||||
| `ready` / `start` / `kick` / `host` | 준비, 시작, 강퇴, 방장 넘기기 |
|
||||
| `chat` | 채팅 = 정답 입력 (서버가 정답 판정) |
|
||||
| `typing` | 입력 중 on/off |
|
||||
| `hint` | 힌트 요청(Ctrl+I) |
|
||||
| `skip` | 스킵 투표 토글(Ctrl+K) |
|
||||
| `audioReady` | 이번 문제 음원 준비 완료 보고 |
|
||||
|
||||
서버 → 클라이언트
|
||||
| t | 내용 |
|
||||
|---|---|
|
||||
| `room` / `patch` | 방 정보, 변경분 |
|
||||
| `round` | 문제 시작(번호, 모드, 재생 시작 시각, 길이, 음원 토큰 또는 가사 일부) |
|
||||
| `hint` | 힌트 공개(초성 등) |
|
||||
| `vote` | 스킵/힌트 투표 현황 |
|
||||
| `answer` | 정답자, 정답(제목-가수), 점수 변화 |
|
||||
| `chat` / `typing` | 채팅, 입력 중 목록 |
|
||||
| `result` | 게임 종료 결과 |
|
||||
|
||||
## 메모리·디스크 예산 (8GB 규칙)
|
||||
- 앱 컨테이너 상한 `mem_limit: 1g` (예상 사용 200~400MB)
|
||||
- 수집기·하이라이트 분석은 `systemd-run --user --scope -p MemoryMax=2G`로 따로 실행, 곡 단위로 스트리밍 처리
|
||||
- 음원 캐시는 디스크 상한(기본 5GB, 관리자 설정)을 두고 오래 안 쓴 것부터 지운다. .9 남은 용량이 이미 140GB라 원본 전체 보관은 하지 않는다 (11-questions.md 참고)
|
||||
63
docs/02-auth-admin.md
Normal file
63
docs/02-auth-admin.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# 02. 로그인 · 권한 · 관리자 페이지
|
||||
|
||||
## 로그인 (joke-app과 동일)
|
||||
### 디스코드 OAuth2
|
||||
- 시작: `GET /api/auth/discord/start?next=/r/123456`
|
||||
- `state` 24바이트 난수 → HMAC 서명 쿠키 `oauth`(10분, `path=/api/auth/discord`)
|
||||
- `https://discord.com/oauth2/authorize?client_id=1561284577564037140&response_type=code&redirect_uri=https://mquiz.tkrmagid.kr/api/auth/discord/callback&scope=identify&state=...&prompt=none`
|
||||
- 콜백: `GET /api/auth/discord/callback` → state 검증 → 토큰 교환 → `/users/@me` 조회
|
||||
- 이미 연결된 계정이면 로그인(게스트 기록은 병합), 게스트 상태면 디스코드 연결 후 회원 전환, 처음이면 회원 생성(닉네임 = `global_name ?? username`, 12자 제한)
|
||||
- 디스코드 토큰은 저장하지 않는다. scope는 `identify`만
|
||||
- **디스코드 개발자 포털에 등록해야 할 Redirect URI**: `https://mquiz.tkrmagid.kr/api/auth/discord/callback`
|
||||
(로컬 테스트용으로 `http://localhost:5173/api/auth/discord/callback`도 추가 권장)
|
||||
- 클라이언트 ID/시크릿은 `deploy/.env`(권한 600)에만 넣고 리포에는 절대 커밋하지 않는다. 호스트 비밀 저장소(`secrets.json`의 `discord.com/oauth/music_quiz`)에 보관해 두었다.
|
||||
- 클라이언트 자격으로 토큰 발급 테스트 완료 → ID·시크릿 정상, 앱 이름 "음악퀴즈", **앱 아이콘은 아직 비어 있음**(포털에서 `assets/brand/icon-discord-1024.png` 업로드 필요)
|
||||
|
||||
### 게스트
|
||||
- `POST /api/auth/guest {nickname}` (IP당 분당 20회)
|
||||
- 닉네임 2~12자, 한글/영문/숫자/`_-. `, 비속어 필터
|
||||
- 로그아웃하면 게스트 계정 삭제, 하루 미사용 게스트 자동 정리
|
||||
- 게스트도 게임은 모두 가능, 관리자는 될 수 없음
|
||||
|
||||
### 세션
|
||||
- `sid` httpOnly 쿠키(SameSite=Lax, https면 Secure), DB에는 `sha256(token)`만
|
||||
- 회원 90일 / 게스트 365일, 하루 한 번 연장
|
||||
- `/api/*` 쓰기 요청은 `Origin` 검사로 CSRF 방지
|
||||
|
||||
## 권한
|
||||
| 역할 | 정하는 방법 | 할 수 있는 것 |
|
||||
|---|---|---|
|
||||
| superadmin | 환경변수 `SUPERADMIN_DISCORD_IDS` (joke-app과 같은 값: `293719842274541579,1352267557213573160`) | 전부 + 사용자 관리 + 관리자 추가/삭제 |
|
||||
| admin | `admins` 표에 디스코드 ID 등록(로그인 전에도 미리 등록 가능) | 노래·수집·방·사이트 설정 |
|
||||
| user | 나머지 | 게임 |
|
||||
|
||||
- 요청마다 다시 계산(디스코드 연결 ID 기준). 환경변수로 정한 슈퍼어드민은 관리자 목록에 "고정"으로 보이고 삭제 불가
|
||||
- 모든 관리자 변경은 `admin_audit`에 변경 전/후 JSON으로 기록
|
||||
|
||||
## 관리자 페이지 `/admin`
|
||||
joke-app 관리자와 같은 레이아웃(왼쪽 사이드 메뉴 + 오른쪽 내용, 표는 `.data-table`)을 쓴다.
|
||||
|
||||
| 메뉴 | 내용 | 권한 |
|
||||
|---|---|---|
|
||||
| 대시보드 | 접속자 수, 진행 중 방, 전체 곡 수, 유튜브 매칭률, 가사 보유율, 최근 수집 작업, 오늘 플레이 수 | admin |
|
||||
| 노래 | 곡 목록 표 + 상세 편집 (아래) | admin |
|
||||
| 가수 | 가수 별칭(아이유 = IU = 이지은), 그룹/유닛 연결, 대표 이미지 | admin |
|
||||
| 장르 | 장르 목록 추가·이름 변경·순서·숨김 | admin |
|
||||
| 수집 | 출처별 수집 실행(멜론 연도별 등), 진행률·로그, 자동 실행 주기, 유튜브 매칭/하이라이트 분석 일괄 실행 | admin |
|
||||
| 통계 | 곡별 출제 수·정답률·평균 정답 시간 → 난이도 조정 제안(승인 버튼) | admin |
|
||||
| 방 | 진행 중 방 목록, 참가자, 강제 종료 | admin |
|
||||
| 사이트 | 사이트 이름, 공지, 점검 모드, 금칙어, 기본 방 설정, 라운드 시간 기본값, 채팅 도배 방지, 음원 캐시 상한 | admin |
|
||||
| 사용자 | 검색, 닉네임 변경, 정지, 강제 로그아웃, 삭제 | superadmin |
|
||||
| 관리자 | 디스코드 ID로 추가/삭제 | superadmin |
|
||||
| 기록 | 감사 로그(누가 언제 무엇을) | admin |
|
||||
|
||||
### 노래 관리 화면
|
||||
- **검색**: 제목·가수·별칭 통합 검색(초성 검색 지원: "ㅅㄱㅇㅈㅍㅅ" → 사건의 지평선)
|
||||
- **필터**: 장르(복수), 연도 범위, 난이도 범위, 유튜브 상태(매칭됨/후보 있음/없음/재생 불가), 가사 유무, 하이라이트 유무, 출처(멜론·지니·벅스·스타맵·노라보세 등), 활성/숨김
|
||||
- **정렬**: 최근 추가, 인기도 점수, 난이도, 연도, 정답률
|
||||
- **표 열**: 앨범아트 · 제목 · 가수 · 연도 · 장르 · 난이도(별) · 유튜브(▶ 미리듣기) · 하이라이트 · 가사 · 출처 수 · 정답률
|
||||
- **상세 편집(오른쪽 패널)**: 제목, 가수, 정답 별칭(여러 개), 연도, 장르(복수), 난이도(자동값 + 수동 고정), 유튜브 주소(`https://youtu.be/ID`) + 후보 목록에서 고르기 + 미리듣기, 하이라이트 시작점(미리듣기 중 "지금 위치로 지정"), 가사, 메모, 숨김
|
||||
- **추가**: 제목+가수만 넣으면 자동으로 멜론 정보·유튜브 후보 채움 → 확인 후 저장
|
||||
- **일괄 작업**: 선택 곡 장르/난이도 변경, 유튜브 재매칭, 숨김, 삭제(휴지통 30일 보관)
|
||||
- **가져오기/내보내기**: JSON·CSV
|
||||
- **중복 정리**: 제목·가수 정규화가 같은 곡 묶어서 보여주고 병합
|
||||
92
docs/05-game-flow.md
Normal file
92
docs/05-game-flow.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# 05. 게임 진행
|
||||
|
||||
## 큰 흐름
|
||||
```
|
||||
대기실 ─(방장 시작)→ 출제 목록 뽑기 → [문제 준비 → 문제 진행 → 정답 공개] × N → 결과
|
||||
```
|
||||
|
||||
### 1) 출제 목록 뽑기
|
||||
- 방 설정(모드·장르·연도·난이도·가수)에 맞는 곡을 DB에서 고른다. 유튜브 주소가 확인된 곡만(가사 모드는 가사가 있는 곡만)
|
||||
- 같은 게임 안에서 중복 없음, 같은 방에서 최근 3게임에 나온 곡은 뒤로 미룬다
|
||||
- 같은 가수가 연달아 나오지 않게 섞는다(가수노래 맞추기 모드 제외)
|
||||
- 조건에 맞는 곡이 문제 수보다 적으면 시작 전에 "조건에 맞는 곡이 N곡뿐이에요"라고 알려주고 그대로 시작/설정 변경 선택
|
||||
|
||||
### 2) 문제 준비 (최대 5초)
|
||||
- 서버가 다음 곡 음원을 미리 준비(현재 문제 진행 중에 다음 2곡을 미리 받아 둠)
|
||||
- 클라이언트는 음원을 받아 재생 준비 후 `audioReady` 보고
|
||||
- 전원 준비 또는 5초 경과 시 시작(늦은 사람은 늦게 들어온 만큼 건너뛰고 재생)
|
||||
- 화면: "3번째 문제" 카드 + 3·2·1 카운트
|
||||
|
||||
### 3) 문제 진행
|
||||
| 모드 | 화면 | 끝나는 조건 |
|
||||
|---|---|---|
|
||||
| 듣고맞추기 | LP가 돌아가고 재생 막대(남은 시간), 앨범아트·제목은 가림 | 정답 / 스킵 통과 / 제한 시간 |
|
||||
| 가수노래 맞추기 | 위와 같음 + 상단에 "선택한 가수" 표시 | 정답 / 스킵 / 제한 시간 |
|
||||
| 가사보고 맞추기 | 음악 없이 가사 카드(제목 단어는 ○로 가림), 남은 시간 막대 | 정답 / 스킵 / 보고맞출시간 |
|
||||
|
||||
- **듣고맞출시간**이 1초~1분이면 그만큼만 재생하고 멈춘다. 재생이 끝나도 문제는 계속(채팅으로 계속 맞힐 수 있음). `다시 듣기` 버튼으로 같은 구간을 본인만 다시 들을 수 있다(최대 3회, 11-questions.md Q4)
|
||||
- **끝까지**면 곡이 끝날 때까지 재생, 곡이 끝나면 문제 종료
|
||||
- 문제 하나의 최대 시간(제한 시간): 짧은 클립 모드 기본 60초, 끝까지 모드는 곡 길이, 관리자 설정에서 변경
|
||||
|
||||
### 4) 정답 공개 (5초)
|
||||
- 무대에 앨범아트 + `노래제목 - 가수` + 연도·장르·난이도 별 표시, 정답자 이름과 걸린 시간
|
||||
- 듣고맞추기면 음악은 그대로 이어서 5초 더(하이라이트 구간이면 그 뒤로)
|
||||
- 채팅에 5줄 정답 블록(06-chat.md)
|
||||
- 점수판 애니메이션(순위 바뀌면 자리 이동)
|
||||
|
||||
### 5) 결과
|
||||
- 순위, 점수, 맞힌 곡 수, 가장 빨리 맞힌 곡
|
||||
- 이번 게임 곡 목록(유튜브 링크 `https://youtu.be/ID` 포함) — 몰랐던 노래 다시 듣기
|
||||
- `다시 하기`(같은 설정으로 대기실 복귀), `나가기`
|
||||
|
||||
## 정답 판정
|
||||
### 정규화 (서버·클라이언트 공용, `packages/shared/answer.ts`)
|
||||
1. 유니코드 NFKC(전각→반각), 영문 소문자
|
||||
2. 괄호 안 내용 분리: `사랑을 했다(LOVE SCENARIO)` → 정답 후보 `사랑을 했다`, `LOVE SCENARIO`, `사랑을 했다 LOVE SCENARIO`
|
||||
3. `feat.`, `(Prod. …)`, `[… OST]`, `(원곡: …)` 같은 꼬리 제거한 후보도 추가
|
||||
4. 관리자가 넣은 별칭 추가(예: `좋은 날` ↔ `Good Day`, `IU` ↔ `아이유`)
|
||||
5. 정답인식 설정에 따라 비교 전에 제거
|
||||
- **띄어쓰기** 끔 → 공백 무시 (`사건의지평선` = `사건의 지평선`)
|
||||
- **숫자** 끔 → 숫자 무시, 켬 → 숫자까지 정확히 (`24시간이 모자라`)
|
||||
- **특수문자** 끔 → `!?.,'"()-~·…♡` 등 무시 (`Bubble Pop!` = `bubble pop`)
|
||||
- (해석은 11-questions.md Q2에서 확인)
|
||||
|
||||
### 정답방식별 판정
|
||||
| 방식 | 정답 조건 |
|
||||
|---|---|
|
||||
| 제목만 | 채팅(정규화) = 제목 후보 중 하나 |
|
||||
| 가수만 | 채팅 = 가수 후보 중 하나. 여러 명이 부른 곡(`허각 / 정은지`)은 그중 한 명만 맞혀도 정답 |
|
||||
| 제목+가수 | 한 줄에 둘 다, **순서 상관없이**. `광 sg워너비`, `sg워너비 광`, `sg워너비-광`, `광/sg워너비` 모두 정답. 판정: 채팅을 정규화한 뒤 `제목+가수` 또는 `가수+제목` 형태로 정확히 나뉘는지 검사(사이 구분자 `- / , 공백` 허용) |
|
||||
|
||||
- 대소문자 무시, 앞뒤 공백 무시
|
||||
- 정답이 아닌 채팅은 그냥 채팅으로 보인다
|
||||
- 오타 허용(유사도 판정)은 하지 않는다 — 유즈맵처럼 정확히 쳐야 맞음. 단, 관리자 별칭으로 흔한 표기 차이를 흡수
|
||||
|
||||
## 점수
|
||||
- 기본: 먼저 맞힌 1명 +1점 (유즈맵 방식)
|
||||
- 동점이면 맞힌 문제의 평균 정답 시간이 짧은 사람이 위
|
||||
- (선택) 추가 규칙은 11-questions.md Q5
|
||||
|
||||
## 힌트
|
||||
- **자동 공개**: 방 설정 "힌트공개" 시간(15/30/45/60초)이 지나면 공개. "없음"이면 자동 공개 안 함
|
||||
- **Ctrl+I 요청**: 누르면 힌트 투표 1표. 스킵과 같은 인원 기준을 넘으면 즉시 공개 (11-questions.md Q3)
|
||||
- 힌트 내용(단계별)
|
||||
1. 초성: `ㄱ (ㄱ) - ㅅㄱㅇㄴㅂ` (정답방식에 해당하는 부분만, 띄어쓰기 유지)
|
||||
2. (가사 모드) 가사 2줄 더 공개
|
||||
- 힌트가 공개된 뒤 맞혀도 점수는 같음(옵션으로 0.5점 검토)
|
||||
|
||||
## 스킵
|
||||
- Ctrl+K 또는 `스킵` 버튼 = 내 스킵 표 토글
|
||||
- 기준: 없음(스킵 불가) / 1명 / 2명 / 1/3 / 1/2 / 2/3 / 전체 — **현재 접속 중인 참가자 수 기준, 올림**
|
||||
- 예) 7명, 1/3 → 3명 이상 누르면 스킵
|
||||
- 진행 중 나간 사람은 표와 분모에서 빠짐
|
||||
- 화면에 `스킵 2/3` 같이 현재 표 수 표시, 누른 사람 이름 옆에 ⏭
|
||||
- 통과하면 정답 공개(정답자 없음) 후 다음 문제
|
||||
|
||||
## 중간 입장 · 퇴장
|
||||
- 게임 중에도 입장 가능(0점으로 바로 참가), 다음 문제부터 음원 재생
|
||||
- 나갔다 60초 안에 돌아오면 점수 유지
|
||||
- 방장이 나가면 가장 먼저 들어온 접속자가 방장
|
||||
|
||||
## 방장 권한
|
||||
- 설정 변경(대기실에서만), 시작, 강퇴, 방장 넘기기, 게임 중 `일시정지`/`게임 끝내기`
|
||||
63
docs/06-chat.md
Normal file
63
docs/06-chat.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# 06. 채팅
|
||||
|
||||
채팅은 이 게임의 입력 장치다. 정답도 채팅으로 치고, 분위기도 채팅에서 나온다. 그래서 화면에서 가장 크고 잘 보이는 자리에 둔다.
|
||||
|
||||
## 배치
|
||||
- 게임 화면 **가운데 아래**에 넓게(PC 최대 폭 880px, 화면 높이의 약 55%). 위쪽 무대(LP/가사 카드/힌트)는 높이를 줄여 채팅에 자리를 내준다.
|
||||
- 입력창은 채팅 영역 맨 아래 가운데, 높이 56px, 글자 18px. 게임 중에는 **항상 포커스**(아무 키나 누르면 입력창으로 이동, joke-app의 "Enter로 채팅 포커스" 확장).
|
||||
- 왼쪽: 점수판, 오른쪽: 지난 문제 목록. 1100px 미만에서는 양옆이 접히고 채팅이 전체 폭을 쓴다. 휴대폰에서는 무대를 상단 띠로 줄이고 채팅이 화면 대부분.
|
||||
- 대기실에서도 같은 채팅 패널을 쓴다(위치만 오른쪽 아래).
|
||||
|
||||
## 말풍선 대신 "한 줄 로그"
|
||||
joke-app은 말풍선이지만, 빠르게 많이 오가는 정답 채팅에는 유즈맵처럼 **한 줄 로그**가 훨씬 잘 읽힌다.
|
||||
```
|
||||
사금향 : 광
|
||||
철수 : sg워너비 광
|
||||
영희 : 아 이거 뭐였지
|
||||
```
|
||||
- 이름 색은 사용자별 고정 색상(joke-app `--name-h` 방식), 본인 줄은 옅은 배경
|
||||
- 시스템 줄(입장/퇴장/스킵/힌트)은 회색 작은 글씨로 가운데
|
||||
- 최근 200줄 유지, 위로 스크롤하면 자동 스크롤 멈춤 + "새 메시지 ↓" 버튼
|
||||
|
||||
## 입력 중 표시
|
||||
- joke-app `useTypingSignal` 그대로: 입력 시작 시 `{t:'typing', on:true}`, 2초마다 갱신, 비우거나 보내면 off
|
||||
- 서버는 1초에 한 번으로 묶어서 중계
|
||||
- 입력창 바로 위에 표시: `철수님이 입력 중…`, 2명이면 `철수, 영희님이 입력 중…`, 3명 이상이면 `철수, 영희 외 3명이 입력 중…` (점 세 개 애니메이션)
|
||||
|
||||
## 지연 없는 전송
|
||||
- 보내는 즉시 내 화면에 먼저 표시(낙관적 표시), 서버 확인이 오면 확정 — 체감 지연 0
|
||||
- 서버는 받은 채팅을 **정답 판정과 동시에** 바로 방 전체에 중계(별도 큐·지연 없음)
|
||||
- 도배 방지는 지연 대신 토큰 버킷(초당 6회, 순간 12회)으로만 막고, 넘치면 그 줄만 거절하고 안내
|
||||
- WebSocket 한 연결로 처리, 메시지 크기 200자 제한(joke-app `CHAT_MAX`)
|
||||
- 정답 판정 순서는 **서버 도착 순서**가 기준(동시에 맞히면 먼저 도착한 사람)
|
||||
|
||||
## 정답 표시 (스타크래프트 방식)
|
||||
누군가 정답을 치면 채팅에 그 줄을 정답 색(초록 굵게)으로 표시하고, 바로 아래에 **공백 5줄**을 넣고 그 가운데(3번째 줄)에 정답을 크게 보여준다.
|
||||
```
|
||||
철수 : sg워너비 광 ← 정답 줄(초록 + ✔)
|
||||
← 공백 1
|
||||
← 공백 2
|
||||
광 (狂) - SG워너비 ← 공백 3 자리에 정답 (가운데, 크게, 금색 밑줄)
|
||||
← 공백 4
|
||||
← 공백 5
|
||||
영희 : 아 이거였네
|
||||
```
|
||||
- 정답 문구 형식은 항상 `노래제목 - 가수`
|
||||
- 스킵으로 넘어간 문제도 같은 5줄 블록으로 정답을 보여주되 회색(정답자 없음)
|
||||
- 5줄 블록은 채팅 기록에 그대로 남아서 스크롤로 다시 볼 수 있다
|
||||
|
||||
## 단축키
|
||||
| 키 | 동작 |
|
||||
|---|---|
|
||||
| Ctrl + I | 힌트 요청 |
|
||||
| Ctrl + K | 스킵 투표 (다시 누르면 취소) |
|
||||
| Enter | 전송 |
|
||||
| Esc | 입력 지우기 |
|
||||
| ↑ | 내가 마지막에 보낸 말 다시 불러오기 |
|
||||
|
||||
- 브라우저 기본 동작(Ctrl+K = 주소창 검색, Ctrl+I = 기울임 등)은 게임 화면에서만 막는다(`preventDefault`)
|
||||
- 화면에 버튼도 같이 둔다: `힌트 (Ctrl+I)` `스킵 (Ctrl+K)` — 휴대폰은 버튼으로
|
||||
|
||||
## 채팅 내용 보호
|
||||
- 비속어 필터(사이트 설정 금칙어), 방장 채팅 끄기 옵션은 두지 않음(채팅이 곧 입력이라)
|
||||
- 정답 판정 전에 정답과 너무 비슷한 오답(한 글자 차이)은 그대로 공개된다 — 유즈맵 감성 유지. 필요하면 "정답에 가까운 오답 가리기" 옵션을 추후 추가
|
||||
71
docs/08-youtube-playback.md
Normal file
71
docs/08-youtube-playback.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# 08. 유튜브 Topic 주소 찾기 · 재생 · 하이라이트
|
||||
|
||||
## 1. 유튜브 Topic 음원 주소 찾기
|
||||
"Topic" 채널(`가수명 - Topic`)에 올라오는 영상은 음원사가 유튜브에 직접 제공하는 공식 음원(Art Track)이다. 뮤직비디오와 달리 인트로·대사·광고성 장면이 없어서 퀴즈용으로 가장 깔끔하다.
|
||||
|
||||
### 사용하는 것
|
||||
- **music_bot_v2** (`git.tkrmagid.kr/tkrmagid/music_bot_v2`)의 유튜브 뮤직 검색 코드 `bot/src/utils/api/YoutubeMusic.ts`
|
||||
- `music.youtube.com/youtubei/v1/search`를 `WEB_REMIX` 클라이언트로 호출, 쿠키 + `SAPISIDHASH`로 인증, 커버/MR/노래방 결과를 뒤로 미는 `JUNK_RE` 필터 포함
|
||||
- **Lavalink** (192.168.10.6:2333, v4.2.2, youtube-plugin 1.18.2 + LavaSrc 4.8.3)
|
||||
- 후보 검색 보조(`ytsearch:`), 재생 가능 여부·길이 확인(`/v4/loadtracks?identifier=https://youtu.be/ID`)
|
||||
|
||||
### 직접 확인한 사실 (2026-10-18)
|
||||
| 시험 | 결과 |
|
||||
|---|---|
|
||||
| Lavalink `ytmsearch:아이유 Love wins all` | HTTP 200, `empty` (music_bot_v2 코드 주석대로 ytmsearch는 비어서 못 씀) |
|
||||
| 로그인 없이 YT Music 검색 API | 아티스트/재생목록만 나오고 "노래" 탭이 아예 없음 → 쿠키 인증이 필요 |
|
||||
| 일반 유튜브 검색 `SG워너비 광(狂)` | 1위 `광 (狂)` / 채널 `SG Wannabe - Topic` ✔ |
|
||||
| 일반 유튜브 검색 `이문세 깊은 밤을 날아서` | 아티스트 공식 채널의 Art Track(제목이 곡명 그대로) ✔ |
|
||||
| 일반 유튜브 검색 `아이유 Love wins all` | 상위 6개에 Topic 없음(MV·라이브만) → YT Music 노래 검색이 꼭 필요한 경우 |
|
||||
| yt-dlp `https://youtu.be/VO88htcm09E` (광) | 채널 `SG Wannabe - Topic`, 설명 `Provided to YouTube by Genie Music`, 길이 237초, **가장 많이 다시 본 구간 75.8초**(후렴) |
|
||||
| yt-dlp `JleoAppaxi0` (Love wins all MV) | 가장 많이 다시 본 구간 161.5초 |
|
||||
|
||||
### 매칭 순서 (`tools/collector/youtube-match.ts`)
|
||||
1. **YT Music 노래 검색**(music_bot_v2 방식, 쿠키 인증) `"{가수} {제목}"` → 노래 결과의 `videoId`
|
||||
- `music.youtube.com/watch?v=ID` 주소를 `www.youtube.com/watch?v=ID`로 바꾸고 최종 저장은 **`https://youtu.be/ID`**
|
||||
2. 못 찾으면 **일반 유튜브 검색** `"{가수} {제목}"`, `"{가수} - Topic {제목}"` → 채널명이 `- Topic`으로 끝나는 결과 우선
|
||||
3. 그래도 없으면 **Lavalink `ytsearch:`** 결과 중 `author`가 `- Topic`으로 끝나는 것
|
||||
4. 후보 점수 매기기
|
||||
- 채널 `- Topic` +50, 영상 설명에 `Provided to YouTube by` +30, 공식 아티스트 채널 +15
|
||||
- 제목 일치(정규화 후) +30, 가수 일치 +20
|
||||
- 길이가 멜론 곡 길이와 ±5초 +20, ±15초 초과 −30
|
||||
- `MV`, `Live`, `커버`, `cover`, `MR`, `inst`, `노래방`, `1시간`, `가사`, `lyrics`, `sped up`, `remix`(원곡이 리믹스가 아닐 때) −40
|
||||
5. 최고 점수 ≥ 80 → 자동 확정(`matched`), 50~79 → `candidate`(관리자 확인 대기), 그 아래 → `none`
|
||||
6. 확정된 주소는 Lavalink `loadtracks`로 한 번 더 재생 가능 확인(지역 제한·삭제 영상 걸러냄), 주 1회 재확인
|
||||
|
||||
### 요청 속도
|
||||
- 곡당 검색 1~3회, 2초 간격, 하루 최대 3,000곡. 차단 신호(HTTP 429, 봇 확인 페이지) 보이면 자동 중단 후 다음 날 재개
|
||||
|
||||
## 2. 재생 방식
|
||||
두 가지 중 하나를 고른다 (11-questions.md Q1). **A안 추천**.
|
||||
|
||||
### A안: 서버 음원 캐시 + 구간 스트리밍 (추천)
|
||||
- 서버가 `yt-dlp`로 해당 곡 음원만 받아(opus/m4a, 곡당 3~5MB) 디스크 캐시에 두고, 문제마다 필요한 구간만 `ffmpeg`로 잘라 일회용 주소(`/api/audio/{토큰}`)로 보낸다
|
||||
- 장점
|
||||
- **정답이 새지 않음**: 브라우저에 유튜브 ID나 제목이 전혀 안 감(유튜브 플레이어를 쓰면 개발자도구로 영상 ID가 보여서 검색 한 번이면 정답)
|
||||
- **광고 없음**: 공식 음원은 수익화 영상이라 유튜브 플레이어로 틀면 문제 도중 광고가 나올 수 있음
|
||||
- **정확한 길이**: 1초/3초도 정확히 그 길이만 재생, 하이라이트 시작점도 정확
|
||||
- 모두 같은 순간에 시작(서버 기준 시각에 맞춰 재생)
|
||||
- 단점: 서버가 음원을 받는 시간(곡당 2~5초, 다음 곡을 미리 받아서 감춤), 디스크 사용(캐시 상한 5GB ≈ 1,200곡, 오래 안 쓴 것부터 삭제), 유튜브 차단 대응 필요(music_bot_v2의 쿠키·poToken 갱신 방식 재사용)
|
||||
|
||||
### B안: 유튜브 플레이어(IFrame)를 화면 뒤에 숨겨서 재생
|
||||
- 장점: 서버 부담 없음, 구현 간단
|
||||
- 단점: 위 A안 장점이 전부 반대(영상 ID 노출, 광고, 버퍼링으로 1초 모드 부정확, 일부 영상은 퍼가기 금지)
|
||||
|
||||
## 3. 재생 위치 "처음부터 / 하이라이트부터"
|
||||
하이라이트 = 그 곡에서 가장 유명한 부분(대개 후렴). 곡마다 `highlight_ms`를 저장한다.
|
||||
|
||||
구하는 순서
|
||||
1. **유튜브 "가장 많이 다시 본 구간"** — 조회수가 충분한 영상은 `yt-dlp`가 재생 구간별 인기도(heatmap)를 준다. 가장 높은 구간 시작점을 쓴다(MV와 Topic 영상 길이가 같으면 MV 쪽 heatmap도 활용)
|
||||
2. **음원 분석** — 캐시된 음원으로 반복 구간(후렴) 찾기(크로마 자기유사도 방식, Python `librosa`, 곡당 1~2초, 메모리 300MB 이하)
|
||||
3. **관리자 지정** — 관리자 노래 편집 화면에서 미리듣기 중 "지금 위치를 하이라이트로" 버튼
|
||||
4. 셋 다 없으면 곡 길이의 30% 지점(대부분 첫 후렴 근처)
|
||||
|
||||
- 우선순위: 관리자 지정 > heatmap > 음원 분석 > 30% 규칙
|
||||
- "듣고맞출시간"이 하이라이트 이후 남은 길이보다 길면 남은 곳까지만
|
||||
|
||||
## 4. 가사 (가사보고 맞추기)
|
||||
- 멜론 곡 상세 페이지의 가사를 수집해 DB에 저장(가사 없는 곡은 이 모드에서 제외)
|
||||
- 출제할 때 보여줄 부분: 후렴 아닌 1절 가운데 4줄 → 시간이 지나거나 힌트를 쓰면 2줄씩 추가
|
||||
- 가사 안에 **제목 단어가 있으면 `○○`로 가림** (예: "사건의 지평선" → "○○○ ○○○")
|
||||
- 영어 가사만 있는 곡은 그대로, 일본어 곡은 원문(번역 없음)
|
||||
BIN
docs/research/machugi-quiz-landing.jpg
Normal file
BIN
docs/research/machugi-quiz-landing.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 52 KiB |
BIN
docs/research/machugi-quiz-play.jpg
Normal file
BIN
docs/research/machugi-quiz-play.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
BIN
docs/research/machugi-quiz-wrong.jpg
Normal file
BIN
docs/research/machugi-quiz-wrong.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 59 KiB |
Reference in New Issue
Block a user