IUEM
AI 가 만든 곡을 노래방처럼 부르면 음정·박자를 재서 점수와 발성 진단을 주고,
같은 곡을 리듬 게임으로도 칠 수 있는 서비스입니다.
노래방 기계는 점수만 주고 끝납니다. 이 서비스는 왜 그 점수가 나왔는지를 같이 말합니다 —
고음에서 무너졌는지, 박자가 계속 늦는지, 숨이 모자라 음이 아래로 쳐지는지.
혼자 기획부터 배포까지 했습니다. 커밋 229개.
팀 프로젝트도 있습니다 — 5인 팀의 채용 관리 시스템 Arda 에서 백엔드를 맡았습니다.
코드와 담당 범위 ·
돌아가는 서비스 ·
프로젝트 소개
(서비스와 소개 문서는 팀 SEUK 가 운영합니다)
무엇이 도는가
| 모드 | 하는 일 | 경로 |
|---|
| 노래방 | 반주에 맞춰 부르면 정답 음표와 대조해 음정·박자를 재고, 발성 8가지를 진단해 조언과 다음 곡을 준다 | /music-challenge/[id]/play |
| 리듬 게임 | 떨어지는 노트를 박자에 맞춰 친다. 4키·7키 × 쉬움·보통·어려움 | /rhythm/[id] |
| 악보 스튜디오 | 관리자가 곡을 올려 정답 음표와 가사 타이밍을 만든다 | /music-challenge/[id]/studio |
| OCR | 사진에서 글자를 읽는다 (Flutter 앱) | app.woojeongalex.cloud |
구조
브라우저 ──→ Next.js 라우트 ──→ FastAPI ──→ PostgreSQL
(React 19) (Vercel·서울) (EC2·Docker) S3
브라우저는 백엔드를 직접 부르지 않습니다. Next.js 라우트 핸들러가 한 번 받아 넘깁니다 —
백엔드 주소와 토큰이 브라우저 번들에 들어가지 않게 하려는 것입니다.
woojeongalex.cloud/
├─ woojeongai/ 백엔드 — FastAPI · 클린/헥사고날
├─ alexview/ 프론트엔드 — Next.js
├─ flutter/ OCR 모바일·웹 앱
├─ _docs/ 설명서 · 인수인계
├─ jekyll/ 개발 기록 — GitHub Pages 로 자동 배포
├─ alexthegreat/ Flutter 실험 — 서비스에 들어가지 않는다
└─ a2a-mcp/ 에이전트 간 통신(A2A·MCP) 실험 — 서비스에 들어가지 않는다
위 셋(woojeongai · alexview · flutter)이 실제로 돌아가는 것이고,
아래 셋은 따로 해 본 것을 같은 저장소에 둔 것입니다.
백엔드 계층
포트와 어댑터. 안쪽(도메인·유스케이스)은 바깥쪽(FastAPI·DB·S3)을 모릅니다.
adapter/inbound/api/ HTTP 가 들어오는 곳
app/ports/input/ 유스케이스 인터페이스
app/use_cases/ 흐름 조립
app/ports/output/ 바깥에 요구하는 인터페이스
adapter/outbound/ 실제 구현 (PG · S3 · librosa)
domain/ 순수 규칙 — 아무것도 import 하지 않는다
dependencies/ 조립
domain/ 에 있는 것은 전부 DB 도 서버도 없이 값만 넣어 검증할 수 있는 순수 함수입니다 —
채점, 발성 진단, 다음 곡 추천, 채보 생성, 리듬 판정.
채점
브라우저와 서버가 같은 규칙으로 채점합니다.
화면 점수는 부르는 동안 바로 보여 주기 위한 것이고, 랭킹에 들어가는 것은 서버 점수뿐입니다 —
브라우저 쪽 값은 사용자가 바꿀 수 있기 때문입니다.
| 항목 | 기준 |
|---|
| 음정 | ±50센트 만점 · ±100센트 절반 |
| 박자 | 음표 시작 후 0.2초 안에 들어오면 제때 |
| 합산 | 음정 75% + 박자 25%, 긴 음표일수록 크게 반영 |
| 옥타브 | 따지지 않는다 (한 옥타브 낮춰 불러도 정답) |
쓰는 모델과 알고리즘
| 어디 | 무엇 | 왜 |
|---|
| 브라우저 실시간 음높이 | YIN (직접 구현) | FFT 최고점 방식은 배음이 센 목소리·기타에서 한 옥타브 위를 자주 잡는다. YIN 은 주기 자체를 찾는다 |
| 서버 정답 멜로디 | librosa pyin | 운영 서버 RAM 이 912MB 라 신경망 추정기를 올릴 자리가 없다. 그리고 같은 곡은 같은 악보가 나와야 쌓인 랭킹의 기준이 흔들리지 않는다 |
| 보컬 분리 | Demucs (htdemucs) | 완성곡을 그대로 쓰면 반주 음까지 정답 음표로 잡힌다. 곡 생성 쪽이 스템을 주면 그쪽이 품질이 더 좋아 그걸 쓴다 |
| 가사 타이밍 | faster-whisper medium + small | 한 번의 인식은 맞았는지 검증할 방법이 없다. 독립인 두 결과가 일치하면 믿고, 갈리면 사람이 그 줄만 듣는다 |
| 조언·추천 | 규칙 기반 | 예전엔 LLM 이었다. 재지 않은 것을 지어냈다(§아래) |
LLM 을 뺀 이유
조언은 원래 외부 LLM 이 썼습니다. 지금은 없습니다.
처음엔 비용 때문이었습니다 — 제출마다 녹음을 통째로 보내고 있었고, 재 보니 9.77MB 였습니다.
고치면서 출력을 봤더니 "표현력이 좋습니다" 같은 말을 하고 있었습니다. 표현력은 잰 적이 없습니다.
그래서 채점이 이미 훑은 (시각, 음높이) 프레임을 한 번 더 읽어 발성 8가지를 재고,
가장 크게 무너진 하나를 골라 말하도록 바꿨습니다. 같은 입력이면 같은 문장이 나오고,
재지 않은 것은 말하지 않습니다.
교체 지점은 인터페이스(AIEvaluatorPort)로 남겨 뒀습니다. 모델을 다시 붙이려면 어댑터만 갈아 끼우면 됩니다.
이 저장소가 부르는 유료 API 는 없습니다. 무거운 계산은 전부 자체 서버에서 합니다.
띄우기
백엔드
docker compose -f docker-compose.yaml -f docker-compose.local.yml up -d pgvector backend
http://localhost:8000 · 문서 /docs. ./woojeongai 를 바인드 마운트하므로 코드 수정이 바로 반영됩니다.
프론트엔드
cd alexview && pnpm install && pnpm dev
작업 후 검사
cd woojeongai && ~/.venvs/lint/bin/ruff check . --fix
cd alexview && pnpm type-check
자세한 것은 _docs/manual.md 에 있습니다 — 구조·운영·배포·곡 준비 절차 10장.
솔직한 부분
- 실험실 화면 3개(보컬 분석·악기 튜닝·스피치)는 화면만 있고 실측 분석이 아직 안 붙었습니다. 사이트에도 그렇게 적어 뒀습니다.
- 채점 기준이 사람에게 가혹할 수 있습니다. 원곡에서 뽑은 진짜 가수 목소리를 그대로 넣었더니 100점이 아니라 91점이 나왔습니다. 곡 하나로만 확인한 것이라 더 봐야 합니다.
- 의존성 목록에 잔재가 있습니다. 걷어낸 기능이 쓰던 패키지가
requirements.txt 에 남아 이미지가 필요보다 큽니다.
- 리듬 게임의 비트 격자를 드럼에 맞춰 곡의 실제 박과 47
93% 까지 올렸습니다. 그 전은 03.6% 였습니다. 아직 더 올릴 여지가 있습니다.
