README.md

metadata

title: Stella Score Reader
emoji: 🏢
colorFrom: yellow
colorTo: gray
sdk: docker
pinned: false

stella_score_reader_backend

인쇄 악보를 카메라로 찍어 크롭한 한 줄 오선(staff) 이미지를 입력으로 받아, 모바일 앱이 바로 재생/편집할 수 있는 단일 멜로디 JSON을 반환하는 OMR API 서버입니다.

현재 목표는 단일 엔드포인트 POST /analyze(v1 단일 스태프 스펙)를 안정적으로 제공하는 것입니다.

핵심 목표

• 입력: 이미지당 오선 한 줄만 있다고 가정한 크롭 사진 1장 또는 여러 장(순서대로 이어짐)
• 음자리표·조표는 잘려 나갈 수 있으므로, multipart 필드 score_context(JSON) 로 반드시 전달
• 출력: melody.events 하나로 병합된 JSON(다장이면 시간축만 이어 붙임). MusicXML 등은 API 응답에 포함하지 않음
• 화음(최대 2성부)은 최고음으로 줄여 멜로디에 반영

자세한 계약은 docs/analyze-api-spec.md를 따릅니다.

문서

• API/데이터 모델 상세: docs/analyze-api-spec.md
• 프론트 연동 가이드(필드 사전): docs/frontend-integration-guide.md
• 응답 JSON 형태 예시(참고용): docs/analyze-response-format-examples.json

기술 스택

• Python 3.11+
• FastAPI
• OpenCV (opencv-python-headless)
• NumPy
• PyTorch(CPU) + transformers(기본 모델: Flova/omr_transformer)
• 전처리: score_preprocess.py(긴 변 상한 축소, LAB 조명 정규화, CLAHE, bilateral, 소각도 데스큐 등; bbox는 업로드 원본 픽셀로 역변환)
• 오선 국소 보정: staff_rectify.py(샘플링 + 다항식 세로 remap)
• 환경 변수:
  • STELLA_OMR_DISABLE=1 — 신경망 끄고 OpenCV만(로컬·테스트)
  • STELLA_OMR_MODEL_ID — 다른 HF 모델 ID
  • STELLA_OMR_MAX_LENGTH — Donut generate 토큰 상한(기본 1024, 모델 decoder.max_length보다 작지 않게 반영)
  • STELLA_OMR_MAX_LENGTH_CAP — 위 값의 하드 상한(기본 2048, OOM·지연 완화)
  • STELLA_MAX_EVENTS_PER_STAFF — 응답에 넣는 음 이벤트 개수 상한 per 스태프(기본 256, 예전 64에서 상향)
  • STELLA_PREPROCESS_MAX_SIDE — 다운스케일 상한(기본 4096, 최소 512로 클램프)
  • STELLA_SKIP_DESKEW=1 — 데스큐 비활성화

빠른 시작

pip install -r requirements.txt
uvicorn main:app --reload

서버 실행 후 Swagger UI:

• http://127.0.0.1:8000/docs

현재 구현 상태

• GET /: 헬스 체크
• POST /analyze (v1):
  • 필수 score_context + 단건/다건 file / files + 선택 options
  • 전처리 → 단일 스태프 검증(정확히 1줄) → staff_rectify → Flova/omr_transformer → 실패 시 OpenCV 노트헤드 폴백
  • 응답: melody, segment_map, timeline, score_context(에코), meta.pipeline_mode = single_staff_v1

구현 기준은 docs/analyze-api-spec.md를 따릅니다.