README.md

---
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](https://huggingface.co/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` — 데스큐 비활성화

## 빠른 시작

```bash
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`를 따릅니다.