부록

  1. 로컬에서 띄우기
  2. 곡 하나를 챌린지로 만들기
  3. 곡 준비 체크리스트
  4. 용어

로컬에서 띄우기 

# 백엔드 · DB · Redis (저장소 루트)
docker compose -f docker-compose.local.yml up -d

# 프론트 (alexview/)
pnpm dev --port 3100

WSL 에서 Windows 폴더(/mnt/c/...)를 보고 있으면 코드를 고쳐도 화면이 자동으로 바뀌지 않는다. 고친 뒤 dev 서버를 다시 켠다.

곡 하나를 챌린지로 만들기

관리자 PC(WSL/리눅스, Docker 필요)에서 명령 한 번이면 된다. 자세한 설명은 저장소의 woojeongai/_docs/song-prep-pipeline.md.

cd woojeongai/tools/song_prep
export SONG_PREP_PASSWORD=...        # 관리자 비밀번호 — 코드나 기록에 남기지 않는다
python3 prepare_song.py 완성곡.wav 가사.txt --title "곡 제목"                 # 영어
python3 prepare_song.py 완성곡.wav 가사.txt --title "곡 제목" --language ko   # 한국어

하는 일: 보컬 분리 → 챌린지 등록 → 가사 저장 → 스템 업로드 → 정답 멜로디 → 가사 타이밍 두 번 인식 → 곡 전체 흐름으로 합치기 → 점검 보고. 끝나면 “확인 권장” 줄 목록이 나온다. 그 줄만 악보 스튜디오에서 들어 보고 고치면 된다.

걸리는 시간 (4분 곡, CPU)  
보컬 분리 약 3분
정답 멜로디 추출 약 40초
가사 타이밍 (medium + small) 약 2~3분

곡 준비 체크리스트

  • 가사는 Suno 에서 복사한 그대로 — [Verse] 같은 표시 줄은 자동으로 빠진다
  • 점검 보고의 주 음역이 부르는 사람 음역과 맞는가
  • 0.15초 미만 조각이 15% 를 넘지 않는가
  • 끝부분에 음표가 없다는 경고가 뜨면 연주로 끝나는 곡인지 들어 본다
  • “확인 권장” 가사 줄을 스튜디오에서 클릭해 들어 본다(그 줄 2초 앞부터 재생된다)

용어

용어 뜻
스템 완성곡을 보컬 · 반주 같은 갈래로 나눈 트랙
정답 음표 보컬(또는 멜로디 악기) 스템에서 뽑은 “이 시각에 이 음” 목록. 채점의 기준
센트 반음의 1/100. ±50센트면 반음의 절반까지 봐준다
어택 건반·줄을 새로 친 순간. 같은 음을 연달아 칠 때 음표를 나누는 기준
싱크 보정 이어폰·마이크 지연만큼 판정 시점을 옮기는 값(±300ms, 브라우저에 저장)
서버 재채점 제출한 녹음을 서버가 정답 음표와 다시 맞춰 매긴 점수. 랭킹은 이 값만 쓴다