Title

README excerpt

# Kpop Fan Chant Battle

**집을 콘서트장으로 바꾸는 AI 팬챈트 리듬 게임**

Kpop Fan Chant Battle은 단순한 "응원법 외우기" 앱이 아닙니다.  
BTS 뮤직비디오를 보며 실제 콘서트처럼 타이밍에 맞춰 팬챈트를 외치고, AI가 실시간으로 반응해주는 **홈 콘서트 트레이닝 경험**입니다.

콘서트에 직접 가지 못해도, 집에서 마이크 하나로
- 응원법을 즐겁게 연습하고,
- 내 리듬/정확도를 확인하고,
- 점점 더 "무대에 맞는 응원"으로 업그레이드할 수 있습니다.

## Why This Matters

기존 응원법 연습은 보통 이런 문제가 있습니다.

- 혼자 연습하면 내가 잘하고 있는지 알기 어렵다.
- 타이밍이 맞는지, 에너지가 충분한지 피드백이 없다.
- 반복 연습이 금방 지루해진다.

이 프로젝트는 이 문제를 다음 방식으로 해결합니다.

- **MV 싱크 기반 플레이**: 실제 곡 흐름에 맞춰 응원
- **실시간 AI 판정**: phrase 단위 타이밍/정확도/에너지 채점
- **즉시 코칭**: 플레이 중 바로 수정할 포인트 안내
- **최종 스타일 리포트**: 내 응원 스타일 요약 + 아바타 카드 생성

## What You Feel In Demo

- 왼쪽: 몰입형 MV 스테이지
- 오른쪽: HIT FRAME, 판정, Combo, Energy/Joy, 가사/응원 타이밍 HUD
- 흐름: `캘리브레이션 -> START -> Song Run -> AI 결과`

한 곡을 끝내면 "연습"이 아니라, 짧은 "공연"을 끝낸 느낌이 들도록 설계했습니다.

## Current Lineup, Future Scale

현재는 데모 집중을 위해 BTS 2곡을 탑재했습니다.

- `BTS - Dynamite`
- `BTS - Butter`

하지만 구조는 **확장형 TrackPack** 기반이라, 이후에는

- 더 많은 아티스트
- 더 많은 곡
- 더 다양한 응원법 포맷

을 같은 파이프라인으로 추가할 수 있습니다.

## AI Pipeline (핵심 설계)

1. `POST /api/session/start`  
   트랙 로딩 + 판정 컨텍스트 준비
2. `POST /api/judge/phrase`  
   실시간 phrase 판정 (Gemini Flash)
3. `POST /api/coach/live`  
   누적 퍼포먼스 기반 라이브 코칭 생성
4. `POST /api/profile/finalize`  
   최종 스타일 분석/리포트 생성 (Gemini Pro 우선)
5. `POST /api/profile/avatar`  
   스타일 카드 이미지 생성

요약하면, **실시간성은 Flash**, **최종 분석은 Pro**, **실패 시 fallback**으로
게임 템포를 끊지 않도록 설계했습니다.

## Local Run

```bash
npm install
cp .env.example .env.local
npm run dev
```

브라우저에서 [http://localhost:3000](http: