문서: IFrame 재생을 전원 준비 보장 방식으로 보강(자동 진행 없음·소리 허용·일시정지 중 시간 정지·위치 기준 클립), 실제 브라우저 시험 결과·도구 추가, 디스크 정리에서 ~/.tmp 제외

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
EJClaw
2026-10-18 19:28:10 +09:00
parent 9f814682cb
commit 0a55c9d6e7
7 changed files with 161 additions and 13 deletions

1
.gitignore vendored
View File

@@ -1 +1,2 @@
tools/report/report.html
node_modules/

View File

@@ -12,10 +12,10 @@
- 문제 수 "무제한"이면 조건에 맞는 곡을 모두 출제. 이어풀기·불러오기면 이미 나온 곡은 빼고 뽑는다
- 조건에 맞는 곡이 문제 수보다 적으면 시작 전에 "조건에 맞는 곡이 N곡뿐이에요"라고 알려주고 그대로 시작/설정 변경 선택
### 2) 문제 준비 (최대 15초)
### 2) 문제 준비
- 서버가 `prepare{videoId, startSec}` 전송 → 각자 숨긴 유튜브 플레이어에 음소거로 불러 시작 위치까지 버퍼링 후 `audioReady` 보고 (12 문서 Q1)
- 전원 준비되면 `play{startAt}`로 모두 같은 순간 시작. 15초가 지나도 안 된 사람은 준비되는 즉시 현재 위치로 합류
- 재생 중 누군가 버퍼링하면 모두 일시정지 후 같은 위치에서 재개(문제당 최대 10초)
- **전원 준비되어야** `play{startAt}`로 모두 같은 순간 시작(시간이 지났다고 자동으로 시작하지 않음). 늦는 사람은 자동 다시 불러오기, 30초 넘으면 방장이 그 사람만 이번 문제에서 뺄 수 있음
- 재생 중 누군가 버퍼링하거나 소리가 막히면 모두 일시정지 후 같은 위치에서 재개. 멈춘 동안 제한 시간·힌트 시간은 줄지 않음 (12 문서 Q1)
- 화면: "3번째 문제" 카드 + 3·2·1 카운트
### 3) 문제 진행

View File

@@ -55,7 +55,10 @@
- 약점과 대응
- 영상 ID 노출 → 준비 단계에만 전송, 방 상태에 미포함(완전 차단은 불가, 사용자 감수)
- 광고 → 준비 단계에서 음소거로 먼저 재생해 광고를 흘려보내고, 실제 곡이 재생되기 시작한 뒤에야 `audioReady`
- 버퍼링·1초 모드 오차 → 서버 시각 기준 시작·정지, 버퍼링 시 모두 일시정지 후 재개, 1초마다 위치 보정
- 소리 차단(자동재생 정책) → 입장 때 `참가 (소리 켜기)` 클릭으로 허용받고, 재생 직후 음소거 해제·재생 상태를 확인, `onAutoplayBlocked`나 확인 실패면 모두 멈추고 그 사람에게 `눌러서 소리 켜기`
- 버퍼링·준비 실패 → 전원 준비 전에는 시작하지 않음, 재생 중 버퍼링이면 모두 일시정지 후 같은 위치에서 재개(시간 상한으로 자동 진행 안 함, 30초 넘으면 방장이 그 사람만 이번 문제 제외 가능)
- 1초 모드 오차 → 시계가 아니라 재생 위치를 보고 정지, 1초마다 위치 보정
- 실제 브라우저 시험 결과와 남은 수동 검증 목록은 12-decisions.md Q1
- 퍼가기 금지 영상 → 매칭 때 oEmbed(`https://www.youtube.com/oembed?url=https://youtu.be/ID`)가 401이면 제외, 재생 오류 101/150이면 건너뛰고 "재생 불가" 표시
## 3. 재생 위치 "처음부터 / 하이라이트부터"

View File

@@ -41,4 +41,4 @@
## 디스크
- .9 남은 공간 약 140GB(72% 사용). 음원 캐시가 없어서 이 프로젝트는 DB 정도만 쓴다
- 용량이 부족해지면(남은 공간 50GB 미만) `~/disk-low-cleanup.sh`가 다시 받으면 되는 캐시(pip·uv·npm·bun 캐시, `~/.tmp` 3일 지난 파일, 도커 빌드 캐시)만 지운다. 모델·프로젝트·DB·실행 중인 작업은 건드리지 않는다 (12 문서)
- 용량이 부족해지면(남은 공간 50GB 미만) `~/disk-low-cleanup.sh`가 다시 받으면 되는 설치 캐시(pip·uv·npm·bun)만 지운다(도커 빌드 캐시는 `docker-disk-guard.sh`). `~/.tmp`·모델·프로젝트·DB·실행 중인 작업은 건드리지 않는다 (12 문서)

View File

@@ -23,16 +23,31 @@
## Q1. 재생: 숨긴 IFrame + 동기화
사용자 요구: "클라이언트가 부담하는 대신 다른 사람들과 실시간 동기화, 버퍼링 때문에 한 명이 노래를 못 듣는 경우가 없게"
- **원칙: 참가자 전원이 들을 수 있을 때만 재생이 진행된다.** 시간이 지났다고 누구를 빼고 자동으로 시작하거나, 뒤늦게 중간부터 합류시키지 않는다
- **시계 맞추기**: 접속 직후와 30초마다 ping 5회로 서버 시각 차이(`offset`)를 잰다(왕복 시간 가장 짧은 값 사용)
- **준비 단계(문제마다)**: 서버가 `prepare{videoId, startSec}` 를 보냄 → 클라이언트는 숨긴 플레이어에 곡을 **음소거로** 불러 `startSec`로 옮긴 뒤 실제로 재생이 시작되면(광고가 있으면 광고가 끝난 뒤) 멈추고 `audioReady` 보고
- 모두 준비되면 서버가 `play{startAt}`(서버 시각, 지금+600ms)을 보냄 → 모두 같은 순간에 음소거 풀고 재생
- 준비 대기는 최대 15초. 그때까지 안 된 사람은 화면에 "음원 준비 중"으로 표시하고, 준비되는 즉시 지금 위치로 건너뛰어 합류
- **재생 중 버퍼링**: 클라이언트가 0.5초 넘게 버퍼링하면 `stall` 보고 → 서버가 **모두 일시정지** → 그 사람이 다시 준비되면 새 `play{startAt, atSec}`로 모두 같은 위치에서 재개
- 한 문제에서 이렇게 멈출 수 있는 총 시간은 10초(관리자 설정). 넘으면 그 사람만 따라잡기 방식으로 바뀌고 다른 사람은 멈추지 않음
- **소리 허용(입장 시 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초마다 `getCurrentTime()`과 기대 위치를 비교해 0.3초 넘게 어긋나면 그 위치로 이동
- **재생 길이**: 1초~1분은 서버가 정한 시각에 각자 멈춤(시계 보정 기준). 서버도 같은 시각을 기준으로 진행
- **재생 길이(1초~1분)**: 시계로 멈추지 않고 **재생 위치**를 보고 멈춘다(`getCurrentTime() >= 시작 + 길이` 를 화면 갱신마다 검사, 오차 약 0.02초). 서버는 모든 클라이언트가 클립을 끝냈다고 보고하거나 예상 시각 + 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초 지점
| 항목 | 결과 (4회 반복) |
|---|---|
| 음소거 준비 시간 | 0.30~0.48초 (12회 중 11회). **1회는 23초 동안 준비 실패** → 다시 불러오기·대기 규칙이 꼭 필요함을 확인 |
| 3명 동시 시작 후 위치 차이 | 2초 뒤 8~29ms → 10초 뒤 25~47ms (보정 기준 0.3초보다 훨씬 작음) |
| 1초 클립(시계 기준 정지) | 실제 0.93~1.00초 → 그래서 위의 "재생 위치 기준 정지"로 바꿈 |
| 클릭 없이 음소거 해제 | 이 환경에서는 막히지 않았음. 하지만 사파리·휴대폰은 더 엄격해서 입장 클릭과 소리 확인 절차를 그대로 둔다 |
| 광고 | 자동 시험에서는 광고가 나오지 않아 확인 못 함 |
- **남은 검증 (5단계에서 사람이 직접)**: 프리미엄이 아닌 계정의 실제 PC 크롬·엣지, 아이폰 사파리, 안드로이드 크롬에서 광고가 붙는 곡, 입장 클릭 없이 들어온 경우, 1초 클립, 3명 이상 동시 시작을 확인하고 결과를 이 문서에 적는다
- 서버 음원 캐시(A안)는 만들지 않는다 → yt-dlp·ffmpeg·음원 캐시 디스크 상한 항목은 하이라이트 분석용 일회성 처리 외에는 없음
## Q2. 정답인식 기본값
@@ -97,6 +112,6 @@
## .9 용량
- 이미 있는 것: `docker-disk-guard.sh`(남은 공간 50GB 미만이면 도커 빌드 캐시·이름 없는 이미지 삭제), `disk85-alert.sh`(85% 이상 알림)
- 추가: `disk-low-cleanup.sh` — 남은 공간이 50GB 미만일 때 다시 받으면 되는 **캐시만** 지운다
- 지움: pip·uv·npm·bun 설치 캐시, `~/.tmp` 의 3일 지난 파일, 도커 빌드 캐시
- 안 지움: 모델(huggingface 등), 브라우저(playwright), 프로젝트 폴더, DB·백업, 실행 중인 설치 작업이 있으면 그 캐시
- 지움: pip·uv·npm·bun·node-gyp 설치 캐시(도커 빌드 캐시는 기존 `docker-disk-guard.sh`가 같은 기준으로 처리)
- 안 지움: `~/.tmp`(파일이 오래됐다고 작업이 끝났다는 보장이 없음), 모델(huggingface 등), 브라우저(playwright), 프로젝트 폴더, DB·백업, 실행 중인 설치 작업이 있으면 그 캐시
- Q1이 B안이라 음원 캐시가 없어 이 프로젝트가 쓰는 디스크는 DB 정도(수백 MB)

View File

@@ -0,0 +1,70 @@
<!doctype html>
<html><head><meta charset="utf-8"><title>iframe sync probe</title></head>
<body>
<button id="join">참가 (소리 켜기)</button>
<div style="position:absolute;left:-10000px;top:0;width:200px;height:200px"><div id="yt"></div></div>
<script>
// Probe page for the hidden-IFrame playback design (docs/12-decisions.md Q1).
// Exposes window.probe for the playwright runner (run.ts).
const log = [];
const ev = (k, v) => log.push({ t: Math.round(performance.now()), k, v });
let player, readyResolve;
const apiReady = new Promise(r => (readyResolve = r));
window.onYouTubeIframeAPIReady = () => {
player = new YT.Player('yt', {
width: 200, height: 200,
playerVars: { autoplay: 0, controls: 0, disablekb: 1, fs: 0, rel: 0, playsinline: 1 },
events: {
onReady: () => { ev('ready'); readyResolve(); },
onStateChange: e => ev('state', e.data),
onError: e => ev('error', e.data),
onAutoplayBlocked: () => ev('autoplayBlocked'),
},
});
};
const s = document.createElement('script'); s.src = 'https://www.youtube.com/iframe_api'; document.head.appendChild(s);
const waitState = (want, ms) => new Promise(res => {
const t0 = performance.now();
const iv = setInterval(() => {
if (player.getPlayerState() === want) { clearInterval(iv); res(true); }
else if (performance.now() - t0 > ms) { clearInterval(iv); res(false); }
}, 20);
});
// gesture unlock: called from the join button click handler
document.getElementById('join').onclick = () => { ev('gesture'); window.__gesture = true; };
window.probe = {
log, apiReady: () => apiReady,
// Prepare: muted load at startSec, wait until really playing, then pause -> ready
async prepare(id, startSec) {
const t0 = performance.now();
player.mute();
player.loadVideoById({ videoId: id, startSeconds: startSec });
const ok = await waitState(YT.PlayerState.PLAYING, 20000);
player.pauseVideo();
await waitState(YT.PlayerState.PAUSED, 3000);
player.seekTo(startSec, true);
return { ok, ms: Math.round(performance.now() - t0), dur: player.getDuration(), at: player.getCurrentTime() };
},
// Play unmuted at wall-clock epoch ms `at`, stop after clipMs (0 = keep playing)
play(at, clipMs) {
return new Promise(res => {
setTimeout(async () => {
const startWall = Date.now();
player.unMute(); player.playVideo();
const playing = await waitState(YT.PlayerState.PLAYING, 5000);
const firstPlayingWall = Date.now();
const muted = player.isMuted();
if (!clipMs) return res({ playing, muted, lateMs: firstPlayingWall - at });
setTimeout(() => {
const pos = player.getCurrentTime();
player.pauseVideo();
res({ playing, muted, lateMs: firstPlayingWall - at, startWall, stopPos: pos });
}, at + clipMs - Date.now());
}, Math.max(0, at - Date.now()));
});
},
pos: () => player.getCurrentTime(),
state: () => player.getPlayerState(),
muted: () => player.isMuted(),
};
</script></body></html>

View File

@@ -0,0 +1,59 @@
// Real-browser probe of the hidden YouTube IFrame playback design (docs/12-decisions.md Q1).
// Usage: bun tools/prototypes/iframe-sync/run.ts (needs playwright-core + /usr/bin/google-chrome)
// Checks: autoplay policy with/without a user gesture, prepare (muted preload) time,
// synchronized unmuted start across 3 clients, 1-second clip accuracy, drift over 10s.
import { chromium } from "playwright-core";
const html = await Bun.file(new URL("./player.html", import.meta.url)).text();
const server = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: () => new Response(html, { headers: { "content-type": "text/html" } }) });
const url = `http://localhost:${server.port}/`;
const VIDEO = process.env.VIDEO ?? "VO88htcm09E"; // SG워너비 광(狂) Topic
const START = Number(process.env.START ?? 60);
// Real-browser autoplay policy: sound needs a user activation.
const browser = await chromium.launch({ executablePath: "/usr/bin/google-chrome", headless: true,
args: ["--autoplay-policy=document-user-activation-required"] });
async function client(gesture: boolean) {
const ctx = await browser.newContext();
const page = await ctx.newPage();
await page.goto(url);
await page.evaluate(() => (window as any).probe.apiReady());
if (gesture) await page.click("#join");
return page;
}
const p = (page: any, fn: string, ...a: any[]) => page.evaluate(([fn, a]: any) => (window as any).probe[fn](...a), [fn, a]);
const out: Record<string, unknown> = {};
// 1) no gesture: can a muted preload run, and does unmuted play get blocked?
{
const page = await client(false);
out.noGesture_prepare = await p(page, "prepare", VIDEO, START);
out.noGesture_play = await p(page, "play", Date.now() + 300, 1500);
out.noGesture_events = (await page.evaluate(() => (window as any).probe.log)).filter((e: any) => e.k !== "state");
await page.context().close();
}
// 2) three clients with a gesture: synchronized start, 1s clip, then 10s drift
{
const pages = await Promise.all([client(true), client(true), client(true)]);
out.prepare = await Promise.all(pages.map(pg => p(pg, "prepare", VIDEO, START)));
const at = Date.now() + 800;
out.clip1s = await Promise.all(pages.map(pg => p(pg, "play", at, 1000)));
// drift: re-prepare then play 10s continuously, sample positions at the same wall instants
await Promise.all(pages.map(pg => p(pg, "prepare", VIDEO, START)));
const at2 = Date.now() + 800;
out.longStart = await Promise.all(pages.map(pg => p(pg, "play", at2, 0)));
const samples: number[][] = [];
for (let i = 0; i < 5; i++) {
await Bun.sleep(2000);
samples.push(await Promise.all(pages.map(pg => p(pg, "pos"))));
}
out.driftSamples = samples.map(s => ({ pos: s.map(x => +x.toFixed(3)), spreadMs: Math.round((Math.max(...s) - Math.min(...s)) * 1000) }));
out.gestureEvents = (await pages[0].evaluate(() => (window as any).probe.log)).filter((e: any) => e.k !== "state");
}
console.log(JSON.stringify(out, null, 1));
await browser.close();
server.stop();