liebharc/homr

homr – AI 기반 광학 악보 인식: 악보 이미지를 MusicXML로 변환

기능

• 악보 사진이나 PDF를 음악 프로그램(예: MuseScore)에서 읽을 수 있는 디지털 형식인 MusicXML 파일로 변환합니다.
• 변환은 명령줄 도구(homr <이미지>)를 통해 로컬에서 실행됩니다. 출력 파일은 입력 이미지와 같은 위치에 저장됩니다.

작동 방식

1. 세그멘테이션 – UNet 스타일 신경망(oemer 프로젝트에서 차용)이 이미지를 스캔하여 기본 시각 요소(오선, 음표 머리, 기둥, 쉼표, 음자리표, 마디선 등)를 식별합니다. 각 요소에 대한 경계 상자를 생성합니다.
2. 오선 재구성 – 감지된 요소를 사용하여 '오선 앵커'(음자리표, 마디선)를 찾고 오선 간격(단위 크기)을 추정합니다. 이를 통해 사진이 기울어져 있거나 간격이 고르지 않아도 오선을 재구성할 수 있습니다. 브레이스/브래킷도 감지되어 큰 보표(피아노)나 여러 성부를 병합할 수 있습니다.
3. 기호 인식 – 각 오선은 왜곡 보정(원근 보정)되어 트랜스포머 모델(Polyphonic‑TrOMR 기반)에 입력됩니다. 트랜스포머는 음표 길이, 음높이, 임시표, 쉼표, 연음부, 일부 아티큘레이션 기호의 시퀀스를 예측합니다. 모델은 또한 각 기호의 대략적인 이미지 위치를 출력하며, 이는 MusicXML에 주석으로 저장됩니다.
4. MusicXML 내보내기 – 기호 시퀀스는 MuseScore, Sibelius 또는 기타 악보 소프트웨어에서 열 수 있는 표준 MusicXML 파일로 변환됩니다.

시작하기

• Python 3.11/3.12가 필요합니다.
• uv(가장 빠른 방법) 또는 Poetry로 설치합니다. CPU 추론을 위한 uv 예시:

  uvx --from 'homr[cpu]' homr path/to/score.png
  

• GPU 가속을 위해 extra를 cuda(NVIDIA) 또는 rocm(AMD)으로 바꿉니다.
• 여러 이미지를 한 번에 실행: homr img1.png img2.png → img1.musicxml, img2.musicxml 생성.
• 외부 도구 relieur로 여러 MusicXML 파일을 결합할 수 있습니다.

데모 및 리소스

• 온라인 빠른 데모: https://homr.site (또는 제공된 Colab 노트북 실행).
• Android 프론트엔드: Andromr 앱이 이 라이브러리를 내부적으로 사용합니다.

현재 제한 사항

• 높은 음자리표와 낮은 음자리표의 음높이와 리듬에 중점을 둡니다.
• 강약 기호, 일부 기호를 제외한 아티큘레이션, 더블 샤프/플랫, 기타 고급 기보 기호는 처리하지 않습니다.

기술적 하이라이트

• 2단계 파이프라인(세그멘테이션 → 트랜스포머)은 최신 OMR 연구를 반영합니다.
• oemer의 사전 훈련된 UNet 모델과 Polyphonic‑TrOMR의 트랜스포머 모델을 사용합니다.
• MusicXML의 각 음표에 위치 주석(<!-- imgpos: x, y -->)을 추가하여 후처리를 용이하게 합니다.

사용 대상

• 인쇄된 악보를 빠르게 디지털화하려는 음악가나 아키비스트.
• 음악 관련 머신러닝 파이프라인을 실험하는 연구자.
• 악보를 입력으로 필요로 하는 앱(연습 앱, 음악 검색 엔진 등)을 개발하는 개발자.

인용 학술 연구에 homr을 포함하는 경우 README에 명시된 원본 oemer 및 Polyphonic‑TrOMR 프로젝트를 인용하세요.

---

요약 – homr은 최신 딥러닝(UNet + 트랜스포머)을 적용하여 악보 이미지를 편집 가능한 MusicXML 파일로 변환하는 오픈소스 Python 도구로, 간단한 명령줄 명령으로 CPU 또는 GPU에서 실행할 수 있습니다.