docs/analyze-api-spec.md

Analyze API Spec (단일 스태프 / v1)

이 문서는 **단일 진실 공급원(SSOT)**이다. 구현·테스트·프론트 계약은 여기 정의한 스키마와 의미를 따른다.

• 엔드포인트: POST /analyze
• 출력: 모바일/웹에서 바로 쓸 수 있는 JSON 한 덩어리(MusicXML 등은 HTTP 응답에 포함하지 않음; 서버 내부 전용 가능).
• 예시 응답 묶음: docs/analyze-response-format-examples.json

---

1) 제품 범위 (심플 모드)

1.1 입력 이미지에 대한 가정

1. 한 이미지 = 오선(staff) 정확히 한 줄만 있다고 가정한다.
   • 복수 줄(예: 피아노 대보표), 합창 다중 스태프 등은 이 스펙의 범위 밖이다.
2. 사진은 인쇄 악보를 카메라로 찍은 뒤 크롭한 것일 수 있다.
   • 종이 휘어짐, 기울기, 조명, 손글씨 낙서 등이 있을 수 있으며, 서버는 전처리(OpenCV 등) + 필요 시 딥러닝 기반 OMR으로 이에 대응한다(구현 디테일은 코드·별도 문서; 여기서는 입출력 계약만 고정한다).

1.2 음향 내용에 대한 가정

• 단선율(단음) 또는 **화음(동시에 울리는 음, 최대 2성부)**이 올 수 있다.
• 화음인 경우, 결과 멜로디 시퀀스는 항상 “가장 높은 음표”만 사용한다(2성부를 한 음으로 줄이는 규칙).
• 음자리표(clef) 와 조표(key signature) 는 이미지 맨 앞에서 잘려 나갔을 수 있다. 이 두 정보는 항상 클라이언트가 요청과 함께 제공한다(아래 score_context).

1.3 여러 장 이미지

• 한 요청에 여러 이미지를 보낼 수 있다. 파일 **업로드 순서 = 악보 읽는 순서(왼쪽→오른쪽 이어짐)**이다.
• 서버는 이미지마다 독립적으로 인식 파이프라인을 돌릴 수 있다.
• 응답의 멜로디 타임라인은 하나로 병합한다. 즉, onset_div / duration_div 는 마치 한 장짜리 입력이었던 것처럼 이어진 단일 시퀀스다.

---

2) 요청 (Request)

2.1 전송 형식

• Content-Type: multipart/form-data

2.2 필드

필드	필수	설명
score_context	예	JSON 문자열. 음높이 해석에 필요한 clef·조표(및 선택 필드). 형식은 §2.3.
file	조건부	단일 이미지 (jpg, jpeg, png, webp).
files	조건부	동일 키 반복으로 여러 이미지. 예: -F "files=@a.png" -F "files=@b.png"
options	아니오	JSON 문자열. 형식은 §2.4.

규칙:

• file 과 files 중 하나는 반드시 존재해야 한다.
• 둘 다 있으면 files 우선한다.
• score_context 가 없거나 JSON 파싱 실패 시 400.

2.3 score_context (JSON 객체)

필수:

키	타입	설명
clef	string	음자리표. 허용 값: treble, bass. (추후 alto, tenor 등 확장 가능하나 v1 구현은 treble/bass 우선.)
key_signature	object	조표.
key_signature.fifths	integer	장조 기준 조표의 샵/플랫 개수. 범위 -6 ~ 6. 음수=플랫, 양수=샵, 0=다장조.

선택 (v1에서 권장·기본값 있음):

키	타입	기본	설명
time_signature	string	"4/4"	"<beats>/<beat-type>" 형식. 예: "3/4", "6/8".
tempo_bpm_reference	number | null	null	UI·클릭 트랙용 참고 템포. 미지정 시 프론트가 자체 기본값 사용.
divisions	integer	4	한四分音符(4분음표)를 몇 개의 division 단위로 쪼갤지. 응답 timeline.divisions 와 동일해야 한다.

적용 범위:

• v1에서는 score_context 를 해당 요청의 모든 이미지에 동일 적용한다.
• 장차 “이미지마다 다른 clef/key”가 필요하면 score_context 배열(파일 순서와 동일 길이) 등으로 버전 업한다.

2.4 options (JSON 객체)

기본값 예시:

{
  "return_debug": false,
  "quantization": "1/8"
}

키	타입	기본	설명
return_debug	boolean	false	true 이면 meta.debug 등 디버그 전용 필드 포함 가능.
quantization	string	"1/8"	리듬 양자화 그리드. 허용: "1/4", "1/8", "1/16".

2.5 용량·포맷 제한 (비기능)

• 이미지 1장 최대 10MB, 요청 합계 최대 30MB (구현은 기존 상수와 맞출 수 있음).
• 지원 확장자: jpg, jpeg, png, webp.
• 권장: 긴 변 4096px 이하 등(구현체 권고).

---

3) 응답 (Response) — HTTP 200

Content-Type: application/json

3.1 최상위 구조

{
  "request_id": "uuid",
  "source": { "total_images": 2, "filenames": ["oneline_0.png", "oneline_1.png"] },
  "score_context": { "clef": "treble", "key_signature": { "fifths": -1 }, "time_signature": "4/4", "tempo_bpm_reference": null, "divisions": 4, "source": "client" },
  "timeline": { "divisions": 4, "time_signature": "4/4", "tempo_bpm_reference": null },
  "melody": {
    "voice_id": "melody1",
    "reduction_rule": "top_note_max_two_parts",
    "events": []
  },
  "segment_map": [],
  "warnings": [],
  "meta": {}
}

3.2 필드 설명

• request_id: 추적·로그용 UUID.
• source: 입력 요약. filenames 는 업로드 순서와 동일한 원본 파일명(없으면 서버가 부여한 placeholder 가능).
• score_context: 요청을 정규화·에코한 값. source: "client" 고정(서버가 조성을 이미지에서 읽지 않음을 명시).
• timeline: 전역 리듬 해석 기준. divisions 는 한 4분음표 = divisions 디비전 (MusicXML 관례와 동일).
• melody: 병합된 단일 성부 결과.
  • reduction_rule: 화음 처리 규칙. v1 고정 문자열 top_note_max_two_parts (최대 2성부일 때 최고음만 채택).
• segment_map: 각 입력 이미지가 병합 events 의 어느 구간에 대응하는지(편집·하이라이트용). §3.4.
• warnings: 인식·품질 경고 코드 문자열 배열.
• meta: 파이프라인 모드, 이미지별 전처리 요약, return_debug 시 디버그 등.

3.3 melody.events[] (Event)

시간 순서로 정렬. onset_div 는 병합 후 전역 타임라인 기준.

공통:

필드	타입	필수	설명
event_id	string	예	클라이언트 편집·키 안정용 고유 ID.
type	string	예	"note" | "rest"
duration_div	integer	예	길이(division). 양의 정수.
onset_div	integer	예	시작 시각(division). 0 이상 정수.

type === "note" 일 때 추가:

필드	타입	필수	설명
step	string	예	C, D, …, B
octave	integer	예	Scientific pitch octave.
alter	integer	예	임시표: -1 플랫, 0 없음, 1 샵, 2 더블샵 등.
pitch_midi	integer	아니오	0–127. 있으면 재생기가 우선 사용 가능.
confidence	number	아니오	0–1 근사.
segment_order	integer	아니오	이 이벤트가 기원한 입력 이미지 순번(1-based).
bbox	array	아니오	해당 이미지 원본 픽셀 좌표계 [x, y, width, height] .

type === "rest" 일 때:

• step / octave / alter 는 포함하지 않는다(또는 모두 생략).

병합 규칙 (논리):

• 이미지 k 의 첫 이벤트의 onset_div 는, 직전 이미지들에서 계산된 누적 길이(또는 인식된 마디 경계) 직후부터 이어진다.
• 구현체는 픽셀·OMR 기반으로 간격을 추정할 수 있으므로, 마지막 음과 다음 이미지 첫 음 사이에 작은 gap 이 생기면 warnings 에 코드로 남길 수 있다.

3.4 segment_map[]

각 입력 세그먼트별 메타:

필드	타입	설명
segment_id	string	예: seg1
order	integer	1-based, 업로드 순서.
filename	string	원본 파일명.
width	integer	원본 이미지 너비.
height	integer	원본 이미지 높이.
event_index_range	object	start / end (inclusive) — melody.events 배열 인덱스. 병합 결과가 비어 있으면 동일 인덱스로 표현 가능.

3.5 warnings (예시 코드)

서버는 필요한 만큼 추가할 수 있다. 예:

• staff_count_mismatch_expected_one: 한 이미지에서 검출된 staff 후보가 1이 아님.
• line_break_between_images: 다중 이미지 병합 시 경계 휴리스틱 사용.
• timing_from_pixel_gaps_heuristic: 리듬이 픽셀 간격 추정에 의존.
• annotation_overlap_detected: 낙서·원 등이 음표와 겹칠 가능.
• neural_omr_model_unavailable: 신경망 비활성/실패 후 폴백.
• large_deskew_correction_applied: 큰 기울기 보정.

3.6 meta (권장 하위 필드)

• pipeline_mode: string — 예: single_staff_v1.
• preprocess.segments[]: 이미지별 전처리 요약(원본/작업 해상도, deskew 각도, 조명 정규화 여부 등). 기존 구현과 동일한 정보 성격을 유지하되, 필드는 구현에 맞게 채운다.
• debug: options.return_debug === true 일 때만.

---

4) 오류 응답

HTTP	조건
400	파일 누락, score_context 누락/파싱 실패, 잘못된 options
413	용량 초과
415	미지원 확장자
422	이미지는 있으나 신뢰할 만한 단일 스태프를 만들 수 없음, 또는 유효한 이벤트가 없음
500	서버 내부 오류

오류 바디는 FastAPI 기본 detail 또는 아래 형태의 JSON 중 하나로 통일할 수 있다(구현 시 한 가지로 고정 권장):

{
  "error": {
    "code": "UNPROCESSABLE_STAFF_LAYOUT",
    "message": "Expected exactly one staff per image.",
    "details": { "segment_order": 2, "detected_staff_candidates": 2 }
  }
}

---

5) 구현·품질 로드맵 (요약)

1. 단일 스태프 ROI 정규화(곡선 오선 보정은 단계적 도입 가능).
2. 노트·쉼표·beam 등 인식(딥러닝 + 규칙 폴백).
3. 화음 → 최고음 리덕션.
4. 다중 이미지 순서 병합 및 segment_map / segment_order 채우기.
5. 회귀 테스트: sample_imgs/sample_oneline_0.png, sample_imgs/sample_oneline_chord.png 및 연속 두 장 시나리오.

---

6) 명시적으로 하지 않는 것 (v1)

• 다중 스태프 악보 타입 추정(a/b/c 등) 및 반주 분리.
• 성부 라벨 soprano/alto 등 자동 추정.
• MusicXML을 HTTP 응답 본문으로 반환.
• 이미지에서 clef/key 자동 판독(클라이언트 제공이 SSOT).

---

7) SSOT 변경 절차

스키마·의미 변경 시 반드시 다음을 함께 갱신한다.

1. 이 문서 (docs/analyze-api-spec.md)
2. docs/frontend-integration-guide.md
3. docs/analyze-response-format-examples.json