NewsRead README 데모 비디오
하나의 명령어로 표준 데모 mp4를 생성합니다:
.claude/skills/demo-video/scripts/run_demo.sh [output.mp4]
# 기본 출력: docs/assets/newsread-demo.mp4
파이프라인: 격리된 백엔드 부팅(:8010, newsread_test DB) → 데모 콘텐츠 시드 → 프론트엔드 부팅(:3010, dev 모드) → 스크립트된 Playwright 투어 녹화(시스템 Chrome, 헤드리스, 애니메이션 커서 + 캡션 삽입) → ffmpeg로 H.264 mp4 변환. 서버는 종료되며 테스트 DB만 사용됩니다. 사용자의 실제 docker-compose 스택(:3000/:8000)은 전혀 건드리지 않습니다.
조정 가능한 설정: DEMO_SCHEME=dark|light (기본값 dark), DEMO_SPEED=1.15 (mp4 재생 속도), CHROME_PATH (대체 브라우저 바이너리).
전제 조건 (보통 이 머신에 이미 갖춰져 있음)
- :5433 포트에서 docker-compose Postgres 실행 중 (
newsread_testDB만 사용) backend/.venv동기화됨 (uv sync),frontend/node_modules설치됨- ffmpeg PATH에 등록, Google Chrome 설치
- 인터넷 접속 가능 — 투어에서 실시간 HN 댓글, 카탈로그 피드 미리보기, picsum 썸네일을 가져옴. 오프라인이면 비디오는 여전히 녹화되지만 해당 섹션이 저하됨.
- 포트 8010/3010 사용 가능; arq 워커가 test DB에 대해 실행 중이면 안 됨 (가짜 데모 피드를 새로고침하려 시도함 — 해롭지는 않지만 지저분함).
표준 투어가 보여주는 내용 (~80초, 속도 증가 전)
- 로딩 중인 받은 편지함 위의 타이틀 카드
- 받은 편지함 스크롤 — 자동 읽기로 기사가 지나갈 때마다 표시; 읽지 않은 알약 카운트 감소
- 주력 기사 ("SQLite: 35% faster than the filesystem") — 마크다운 AI 요약
- 관련 보도 — 시드된 임베딩 클러스터가 SAME STORY + 관련 계층 생성
- 실시간 Hacker News 댓글 (실제 HN 스레드에서 "Show comments")
- 카탈로그 — "nasa" 검색, 피드 미리보기 모달 열기, 빠른 설정으로 구독
- 아웃트로 카드
구성 요소 (데모를 변경하려면 수정)
scripts/seed_demo_data.py— 데모 사용자 (demo/demo-pass-1234), 4개의 가짜 피드, 마크다운 티저 요약이 있는 ~16개의 수작업 기사, 수작업 pgvector 임베딩 (cosine ~0.08 → "같은 기사", ~0.50 → "관련", 무작위 ≈ 직교 → 숨김). 주력 기사의 HN 스레드 ID는 Algolia API를 통해 실시간으로 확인됨. 멱등적;newsread_test가 아닌 DB URL은 거부함.scripts/record_tour.js— 장면 목록. 먼저 기록되지 않은 웜업 패스를 수행하여 Next dev 모드 컴파일과 이미지 캐싱을 완료한 후 녹화.scripts/demo_helpers.js— 삽입된 커서/캡션/타이틀 카드 오버레이 및 인간 속도 입력 기본 요소. 스크롤은 실제 휠 이벤트를 사용하므로 IntersectionObserver 자동 읽기가 사용자에게 보이는 것과 정확히 동일하게 동작함.scripts/convert_to_mp4.sh— webm → H.264/yuv420p/faststart mp4.
결과 확인
확인하지 않은 비디오를 출시하지 마세요. 스팟 체크 프레임 추출:
ffmpeg -i docs/assets/newsread-demo.mp4 -vf fps=1/6 /tmp/demo-frames/f%02d.png
몇 개를 읽어보세요 — 캡션이 읽기 쉬운지, 요약/관련/HN 섹션이 실제로 나타났는지, 구독 버튼이 "Subscribed"로 바뀌었는지 확인. 섹션이 누락된 경우 리코더 로그와 $WORK/backend.log를 확인하세요 (작업 디렉토리는 실행 시작 시 출력됨).
README에 넣기
GitHub은 웹 편집기에서 업로드된 mp4에 대해서만 비디오 플레이어를 렌더링합니다 (README.md 편집 중 드래그 앤 드롭하면 github.com/user-attachments/assets/... URL이 생성됨) — 경로로 참조된 커밋된 .mp4는 인라인으로 렌더링되지 않습니다. 따라서 완성된 mp4를 사용자에게 전달하고 github.com에서 README로 드래그 앤 드롭하도록 알려주세요. docs/assets/ 아래에 표준 복사본으로 파일을 커밋하는 것은 여전히 괜찮습니다.
알려진 문제점
- 카탈로그 장면에서 구독은 백엔드에서 해당 피드의 동기식 실제 가져오기를 트리거합니다 — 신뢰할 수 있는 피드를 선택하세요 (투어는 "nasa"를 검색함); 대기는 최대 30초 허용.
POST /api/feeds를 통해 시드하지 마세요 — 피드 URL을 동기식으로 가져옵니다. 시드 스크립트는 ORM 행을 직접 삽입합니다.- 프론트엔드 AI 요약 UI는
/api/ai/status가 미구성 상태를 보고하면 완전히 숨겨집니다;run_demo.sh는 렌더링을 위해 플레이스홀더NEWSREAD_OPENAI_API_KEY를 내보냅니다. LLM은 절대 호출되지 않습니다: 요약은 미리 채워져 있으며, 요약 엔드포인트는 요약이 존재하면 단락 회로로 동작합니다. - 시드된 벡터의 임베딩
model태그는 서버의NEWSREAD_OPENAI_EMBEDDING_MODEL과 일치해야 합니다 —run_demo.sh가 두 프로세스 모두에 대해 내보냅니다; 서버와 다른 환경 변수로 시드 스크립트를 실행하지 마세요.