docs/frontend-integration-guide.md

Frontend Integration Guide — 단일 스태프 Analyze API (v1)

POST /analyze 를 호출해 한 줄 오선 악보 사진(1장 또는 여러 장)을 보내고, 병합된 단일 멜로디 JSON을 받는다. 이전 다중 스태프·합창 스펙과 호환되지 않는다(필드 구조가 단순화됨).

상세 계약: docs/analyze-api-spec.md (SSOT).

---

1) 한 줄 요약

항목	내용
입력 이미지	한 장당 staff 한 줄만 있다고 가정
Clef / 조표	이미지에 없을 수 있음 → score_context 로 필수 전달
화음	최대 2성부; 응답 멜로디는 항상 최고음만
여러 장	업로드 순서 = 악보 진행 순서; 서버는 장별 분석 후 melody.events 하나로 병합
재생 핵심	timeline + melody.events + (표시용) score_context

---

2) 요청 만들기

2.1 multipart/form-data

• score_context (필수): JSON 문자열 한 덩어리.
  • 최소: { "clef": "treble", "key_signature": { "fifths": 0 } }
  • 선택: time_signature, tempo_bpm_reference, divisions (기본 4/4, null, 4)
• files: 같은 필드명으로 여러 번 붙이거나, 단일 file 사용.
• options: JSON 문자열. 보통 { "return_debug": false, "quantization": "1/8" }.

2.2 fetch 예시 (브라우저)

const scoreContext = {
  clef: "treble",
  key_signature: { fifths: -1 },
  time_signature: "4/4",
  tempo_bpm_reference: 72,
  divisions: 4,
};

const form = new FormData();
form.append("score_context", JSON.stringify(scoreContext));
form.append("options", JSON.stringify({ return_debug: false, quantization: "1/8" }));

for (const file of fileListFromInput) {
  form.append("files", file, file.name);
}

const res = await fetch("/analyze", { method: "POST", body: form });
const data = await res.json();
if (!res.ok) throw new Error(JSON.stringify(data));

2.3 curl 예시

curl -X POST http://localhost:8000/analyze \
  -F 'score_context={"clef":"treble","key_signature":{"fifths":-1},"time_signature":"4/4","divisions":4}' \
  -F 'options={"return_debug":false,"quantization":"1/8"}' \
  -F "files=@sample_imgs/sample_oneline_0.png" \
  -F "files=@sample_imgs/sample_oneline_chord.png"

---

3) 응답 읽기

3.1 최소 구독 필드

• melody.events: 재생·편집의 본체. 시간 순.
• timeline.divisions: duration_div / onset_div 의 척도(한 4분음표 = divisions).
• timeline.time_signature: 마디 길이 해석·UI용.
• score_context: 조표·clef 표시(서버 에코; 클라이언트가 보낸 값이 정답).

3.2 이벤트 타입

• note: step, octave, alter, duration_div, onset_div 필수. pitch_midi 가 있으면 재생에 사용 가능.
• rest: duration_div, onset_div 만으로 충분.

시간 계산:

• 절대 시각(초)은 서버가 강제하지 않는다.
• beat = onset_div / divisions 로 마디 내 위치를 계산할 수 있다.

3.3 여러 장 이미지 UI 연동

• segment_map: 각 원본 이미지가 melody.events 의 어느 인덱스 구간에 해당하는지.
• events[].segment_order / bbox: 특정 음을 원본 크롭 위에 하이라이트할 때 사용(없을 수 있음).

3.4 warnings

• 치명적이지 않아도 품질 저하를 나타낼 수 있다.
• UI에서는 토스트/배지로 노출하고, 사용자에게 “자동 인식이 불안정할 수 있음”을 안내하는 용도를 권장.

---

4) 오류 처리

코드	프론트 액션 예시
400	score_context / options / 파일 필드 검증
413	업로드 전 클라이언트에서 용량 사전 차단
415	확장자 필터
422	“이 사진은 한 줄 악보로 인식되지 않았습니다” + 재촬영 안내

---

5) 마이그레이션 메모 (기존 프론트 대비)

• detection.staffs[].voices[] 구조 제거 → melody 단일 블록으로 통합.
• score_type_estimate, is_accompaniment, include_accompaniment 옵션: v1 스펙 없음.
• Clef/key 는 더 이상 “서버 추정”이 아니라 클라이언트가 score_context 로 제공해야 함.

---

6) 참고 파일

• docs/analyze-api-spec.md — 필드·의미·경고 코드 전체
• docs/analyze-response-format-examples.json — 복붙 가능한 예시 JSON