Initial deployment: Score to MML converter

- Gradio web UI with queue (max 10, concurrency 1)
- Audiveris OMR built from source (Java 25)
- PDF max 5 pages limit
- JVM heap capped at 1500m for HF Spaces 2GB RAM
- Preprocessing optional (default: none)
- Upscale limited to PIL 2x/3x (no waifu2x)

.dockerignore

@@ -0,0 +1,33 @@
+__pycache__/
+*.pyc
+.git/
+.gradio/
+models/
+dataset/
+backup/
+dist/
+build/
+*.pt
+*.png
+*.jpg
+*.jpeg
+*.musicxml
+*.mml
+*.txt
+*.zip
+*.spec
+*.stackdump
+resume_state.json
+app_local/
+app_web/
+scripts/
+tests/
+sample_data/
+artifacts/
+python/
+run_*.py
+compare_*.py
+convert_*.py
+debug_*.py
+discord_*.py
+test_*.py

Dockerfile

@@ -0,0 +1,64 @@
+# ==============================================================================
+# Stage 1: Build Audiveris from source (needs JDK 25 + Gradle)
+# ==============================================================================
+FROM eclipse-temurin:25-jdk AS audiveris-builder
+
+RUN apt-get update && apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Clone Audiveris source
+RUN git clone --depth 1 https://github.com/Audiveris/audiveris.git /audiveris
+
+WORKDIR /audiveris
+
+# Build Audiveris (installDist creates bin/ + lib/ with all JARs)
+RUN chmod +x gradlew && \
+    ./gradlew :app:installDist -x test -x javadoc --no-daemon
+
+# ==============================================================================
+# Stage 2: Runtime image (JRE 25 + Python 3.11 + Tesseract)
+# ==============================================================================
+FROM eclipse-temurin:25-jre
+
+# Install Python, Tesseract, and system deps
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        python3 \
+        python3-pip \
+        python3-venv \
+        tesseract-ocr \
+        tesseract-ocr-eng \
+        libgl1 \
+        libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy built Audiveris
+COPY --from=audiveris-builder /audiveris/app/build/install/app /opt/audiveris
+
+# Make Audiveris script executable
+RUN chmod +x /opt/audiveris/bin/Audiveris
+
+# Set up Python virtual env (HF Spaces best practice)
+RUN python3 -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# Install Python dependencies
+COPY requirements-server.txt /tmp/requirements.txt
+RUN pip install --no-cache-dir -r /tmp/requirements.txt
+
+# Copy application code
+WORKDIR /app
+COPY core/ ./core/
+COPY app_gradio.py .
+COPY convert_3part.py .
+
+# Environment variables
+ENV AUDIVERIS_BIN=/opt/audiveris/bin/Audiveris
+ENV AUDIVERIS_MAX_HEAP=1500m
+ENV JAVA_TOOL_OPTIONS="-Djava.awt.headless=true"
+ENV MAX_PDF_PAGES=5
+ENV GRADIO_SERVER_NAME=0.0.0.0
+ENV GRADIO_SERVER_PORT=7860
+
+EXPOSE 7860
+
+CMD ["python", "app_gradio.py", "--port", "7860"]

README.md

@@ -1,11 +1,23 @@
 ---
-title: Score To MML
-emoji: 🔥
-colorFrom: indigo
+title: Score to MML Converter
+emoji: 🎵
+colorFrom: blue
 colorTo: purple
 sdk: docker
-pinned: false
-short_description: Convert Image of Score to MML
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 악보 → MML 변환기
+
+PDF 또는 이미지 악보를 업로드하면 마비노기 MML로 변환합니다.
+
+## 기능
+- PDF / PNG / JPG 악보 입력
+- Audiveris OMR 엔진으로 음표 인식
+- MusicXML → MML 자동 변환
+- MML / MXL / XML 다운로드
+
+## 제한사항
+- PDF 최대 5페이지
+- 동시 처리: 1건 (큐 대기 최대 10명)
+- 복잡한 악보는 인식 정확도가 떨어질 수 있습니다

app_gradio.py

@@ -0,0 +1,162 @@
+"""
+app_gradio.py
+
+Gradio 웹 UI — 악보(PDF/PNG/JPG) 업로드 → MML 변환 결과 반환.
+
+실행:
+    python app_gradio.py
+
+외부 접속:
+    python app_gradio.py --share
+
+Hugging Face Spaces 배포:
+    Dockerfile에서 ENTRYPOINT로 실행됨
+"""
+
+import argparse
+import datetime
+import os
+import tempfile
+from pathlib import Path
+
+import gradio as gr
+
+from core.convert_pipeline import run_score_pipeline
+
+
+SUPPORTED_EXTENSIONS = [".pdf", ".png", ".jpg", ".jpeg"]
+MAX_PDF_PAGES = int(os.environ.get("MAX_PDF_PAGES", "5"))
+
+_PREPROCESS_MAP = {"없음": "none", "Otsu": "otsu", "Adaptive": "adaptive", "대비강화": "contrast"}
+_UPSCALE_MAP = {
+    "없음": "none",
+    "PIL 2×": "pil_2", "PIL 3×": "pil_3",
+}
+
+
+def _check_pdf_pages(file_path: str) -> str | None:
+    """PDF 페이지 수 제한 검사. 초과 시 에러 메시지 반환."""
+    if Path(file_path).suffix.lower() != ".pdf":
+        return None
+    try:
+        import fitz
+        doc = fitz.open(file_path)
+        count = doc.page_count
+        doc.close()
+        if count > MAX_PDF_PAGES:
+            return f"PDF가 {count}페이지입니다. 최대 {MAX_PDF_PAGES}페이지까지 지원합니다."
+    except Exception:
+        pass
+    return None
+
+
+def convert(file_path: str, preprocess: str, dpi: int, upscale: str, progress=gr.Progress()) -> tuple[str, str | None, list, list, str]:
+    if file_path is None:
+        return "", None, [], [], "파일을 업로드해주세요."
+
+    ext = Path(file_path).suffix.lower()
+    if ext not in SUPPORTED_EXTENSIONS:
+        return "", None, [], [], f"지원하지 않는 파일 형식입니다: {ext}\n지원 형식: PDF, PNG, JPG"
+
+    page_err = _check_pdf_pages(file_path)
+    if page_err:
+        return "", None, [], [], page_err
+
+    try:
+        combined, mxl_paths, xml_paths, warnings = run_score_pipeline(
+            input_path=file_path,
+            preprocess_mode=_PREPROCESS_MAP.get(preprocess, "none"),
+            dpi=dpi,
+            upscale_mode=_UPSCALE_MAP.get(upscale, "none"),
+            on_progress=lambda frac, desc: progress(frac, desc=desc),
+            correct_xml=False,
+        )
+    except Exception as e:
+        return "", None, [], [], f"변환 중 오류 발생:\n{e}"
+
+    # MML 파일 생성: 입력파일명_mml_YYYYMMDD_HHMMSS.mml
+    stem = Path(file_path).stem
+    ts = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+    mml_filename = f"{stem}_mml_{ts}.mml"
+    mml_path = Path(tempfile.gettempdir()) / mml_filename
+    mml_path.write_text(combined, encoding="utf-8")
+
+    warnings_text = "\n".join(f"[WARN] {w}" for w in warnings) if warnings else "경고 없음"
+    return combined, str(mml_path), mxl_paths, xml_paths, warnings_text
+
+
+def build_ui() -> gr.Blocks:
+    with gr.Blocks(title="악보 → MML 변환기") as demo:
+        gr.Markdown("# 악보 → MML 변환기")
+        gr.Markdown("PDF 또는 이미지 악보를 업로드하면 마비노기 MML로 변환해드립니다.")
+
+        with gr.Row():
+            with gr.Column():
+                file_input = gr.File(
+                    label="악보 파일 (PDF, PNG, JPG)",
+                    file_types=[".pdf", ".png", ".jpg", ".jpeg"],
+                )
+                preprocess_radio = gr.Radio(
+                    choices=["없음", "Otsu", "Adaptive", "대비강화"],
+                    value="없음",
+                    label="전처리 (없음=원본, Otsu=깨끗한스캔, Adaptive=조명불균일, 대비강화=흐린스캔)",
+                )
+                dpi = gr.Radio(
+                    choices=[150, 300, 450, 600],
+                    value=300,
+                    label="DPI (PDF만 해당, 300 권장)",
+                )
+                upscale_radio = gr.Radio(
+                    choices=["없음", "PIL 2×", "PIL 3×"],
+                    value="없음",
+                    label="업스케일 (PIL 리사이즈 — 저해상도 스캔에 효과적)",
+                )
+                convert_btn = gr.Button("변환 시작", variant="primary")
+
+            with gr.Column():
+                mml_output = gr.Textbox(
+                    label="MML 결과  (위: 전체화음 N파트 / 구분선 / 아래: 3파트)",
+                    lines=25,
+                    show_copy_button=True,
+                    placeholder="변환 결과가 여기에 표시됩니다.",
+                )
+                mml_file_output = gr.File(
+                    label="MML 다운로드",
+                    file_count="single",
+                )
+                mxl_output = gr.File(
+                    label="MXL 다운로드 (압축 MusicXML)",
+                    file_count="multiple",
+                )
+                xml_output = gr.File(
+                    label="XML 다운로드 (Soundslice 등 호환)",
+                    file_count="multiple",
+                )
+                warnings_output = gr.Textbox(
+                    label="경고",
+                    lines=4,
+                    placeholder="경고 메시지",
+                )
+
+        convert_btn.click(
+            fn=convert,
+            inputs=[file_input, preprocess_radio, dpi, upscale_radio],
+            outputs=[mml_output, mml_file_output, mxl_output, xml_output, warnings_output],
+        )
+
+    return demo
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--share", action="store_true", help="외부 공유 링크 생성")
+    parser.add_argument("--port", type=int, default=7860, help="포트 번호 (기본: 7860)")
+    args = parser.parse_args()
+
+    demo = build_ui()
+    demo.queue(max_size=10, default_concurrency_limit=1)
+    demo.launch(
+        share=args.share,
+        server_name="0.0.0.0",
+        server_port=args.port,
+    )

convert_3part.py

@@ -0,0 +1,858 @@
+#!/usr/bin/env python3
+"""
+convert_3part.py
+마비노기 1인 악보용 MusicXML → 3파트 MML 변환기
+
+절대 규칙:
+ 1. 절대 시간축 기준
+ 2. <duration>/<divisions> 로 실제 길이 계산
+ 3. <chord> note = 직전 non-chord note와 같은 시작점
+ 4. <backup>/<forward> 반영
+ 5. tie(start/stop) 동일 pitch 병합
+ 6. <harmony> 무시
+ 7. tempo: <sound tempo> 우선, 없으면 metronome, 기본값 120
+ 8. 동시 3음 이하 그대로
+ 9. 동시 4음 이상 → 최상성+최하성+화성 대표 1음으로 축약
+10. 출력 Part 1=Melody, Part 2=Chord1/Sub, Part 3=Chord2/Bass 고정
+11. 내부 계산은 Fraction 고정밀, 최종 출력 직전에만 MML 토큰으로 변환
+12. pitch/start/duration/tempo 보존 최우선; slur/layout/harmony text 무시
+
+Usage:
+    python convert_3part.py file1.mxl [file2.mxl ...] -o output.txt [--append]
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+import zipfile
+import xml.etree.ElementTree as ET
+from fractions import Fraction
+from functools import lru_cache
+from typing import List, Tuple, Optional, Dict
+
+# ─────────────────────────────────────────────────────────────────
+# 상수
+# ─────────────────────────────────────────────────────────────────
+QUARTER_TICKS = 12   # quarter note = 12 ticks
+WHOLE_TICKS   = 48   # whole note   = 48 ticks
+
+STEP_TO_SEMI: Dict[str, int] = {
+    'C': 0, 'D': 2, 'E': 4, 'F': 5, 'G': 7, 'A': 9, 'B': 11
+}
+SEMI_TO_NOTE: Dict[int, str] = {
+    0: 'c', 1: 'c+', 2: 'd', 3: 'd+', 4: 'e',
+    5: 'f', 6: 'f+', 7: 'g', 8: 'g+', 9: 'a', 10: 'a+', 11: 'b'
+}
+
+# (tick, MML token) — 내림차순 정렬 (DP greedy용)
+MML_DUR_TABLE: List[Tuple[int, str]] = sorted([
+    (48, '1'),  (36, '2.'), (24, '2'),  (18, '4.'), (16, '3'),
+    (12, '4'),  (9,  '8.'), (8,  '6'),  (6,  '8'),  (4,  '12'),
+    (3,  '16'), (2,  '24'), (1,  '48'),
+], reverse=True)
+
+MML_TICK_TO_TOKEN: Dict[int, str] = dict(MML_DUR_TABLE)
+
+
+# ─────────────────────────────────────────────────────────────────
+# MXL / XML 열기
+# ─────────────────────────────────────────────────────────────────
+def open_mxl_or_xml(path: str) -> str:
+    """MXL(zip) 또는 일반 XML/MusicXML 파일에서 MusicXML 문자열 반환"""
+    if path.lower().endswith('.mxl'):
+        with zipfile.ZipFile(path) as zf:
+            # META-INF/container.xml 에서 rootfile 경로 찾기
+            try:
+                container = zf.read('META-INF/container.xml')
+                croot = ET.fromstring(container)
+                for elem in croot.iter():
+                    if '}' in elem.tag:
+                        elem.tag = elem.tag.split('}')[1]
+                rf = croot.find('.//rootfile')
+                xml_name = rf.attrib['full-path'] if rf is not None else ''
+            except Exception:
+                xml_name = ''
+            if not xml_name:
+                # fallback: 첫 번째 .xml 또는 .musicxml 파일
+                xml_name = next(
+                    (n for n in zf.namelist()
+                     if n.endswith('.xml') or n.endswith('.musicxml')),
+                    ''
+                )
+            if not xml_name:
+                raise FileNotFoundError(f'MXL 안에서 MusicXML을 찾지 못함: {path}')
+            return zf.read(xml_name).decode('utf-8', errors='replace')
+    else:
+        with open(path, encoding='utf-8', errors='replace') as f:
+            return f.read()
+
+
+# ─────────────────────────────────────────────────────────────────
+# MusicXML 파싱
+# ─────────────────────────────────────────────────────────────────
+def strip_ns(root: ET.Element) -> None:
+    """namespace 제거"""
+    for elem in root.iter():
+        if '}' in elem.tag:
+            elem.tag = elem.tag.split('}')[1]
+
+
+def parse_tempo(root: ET.Element) -> int:
+    """규칙 7: <sound tempo> 우선, 없으면 metronome, 기본 120"""
+    for sound in root.iter('sound'):
+        t = sound.attrib.get('tempo')
+        if t:
+            try:
+                return int(float(t))
+            except ValueError:
+                pass
+    for metro in root.iter('metronome'):
+        bpm = metro.findtext('per-minute')
+        if bpm:
+            try:
+                return int(float(bpm))
+            except ValueError:
+                pass
+    return 120
+
+
+def frac_tick(raw_dur: int, divisions: int) -> Fraction:
+    """XML raw duration → Fraction ticks (규칙 2)"""
+    if divisions <= 0:
+        divisions = 1
+    return Fraction(raw_dur * QUARTER_TICKS, divisions)
+
+
+# <type> 요소 기반 duration 폴백 테이블 (divisions 오류 시 사용)
+_TYPE_TICKS: dict = {
+    'breve': Fraction(96), 'whole': Fraction(48), 'half': Fraction(24),
+    'quarter': Fraction(12), 'eighth': Fraction(6), '16th': Fraction(3),
+    '32nd': Fraction(3, 2), '64th': Fraction(3, 4),
+}
+
+
+def _dur_from_type(note_elem: ET.Element) -> Optional[Fraction]:
+    """<type> + <dot> 요소로 duration(ticks) 계산. 없으면 None."""
+    t = note_elem.findtext('type')
+    if t not in _TYPE_TICKS:
+        return None
+    ticks = _TYPE_TICKS[t]
+    for _ in note_elem.findall('dot'):
+        ticks = ticks * Fraction(3, 2)
+    return ticks
+
+
+def parse_part(part_elem: ET.Element) -> Tuple[List[dict], Fraction]:
+    """
+    단일 <part>를 절대 시간축으로 파싱 (규칙 1~6).
+    Returns: (events, total_ticks)
+      event = {'start': Fraction, 'dur': Fraction, 'midi': int, 'tie': frozenset}
+    """
+    events: List[dict] = []
+    measure_start = Fraction(0)
+    divisions = 1
+    divisions_valid = False  # XML에서 유효한 divisions 값(>0)을 읽었는지 여부
+
+    for m in part_elem.findall('measure'):
+        # attributes 우선 확인
+        attr = m.find('attributes')
+        if attr is not None:
+            d = attr.findtext('divisions')
+            if d:
+                divisions = int(d)
+                if divisions > 0:
+                    divisions_valid = True
+
+        # divisions=0 인 implicit 마디는 Audiveris 아티팩트 — 건너뜀
+        if not divisions_valid and m.get('implicit') == 'yes':
+            continue
+
+        def get_dur(raw_dur: int, note_elem: Optional[ET.Element] = None) -> Fraction:
+            """divisions 유효하면 계산값 사용, 아니면 <type> 기반 폴백."""
+            if divisions_valid:
+                return frac_tick(raw_dur, divisions)
+            if note_elem is not None:
+                t = _dur_from_type(note_elem)
+                if t is not None:
+                    return t
+            return frac_tick(raw_dur, max(divisions, 1))
+
+        cursor = Fraction(0)      # 마디 내 raw cursor (frac ticks)
+        max_cursor = Fraction(0)
+        last_note_start: Optional[Fraction] = None
+
+        for child in m:
+            tag = child.tag
+            if tag == 'backup':
+                # 규칙 4: backup
+                raw = int(child.findtext('duration', '0'))
+                cursor -= get_dur(raw)
+
+            elif tag == 'forward':
+                # 규칙 4: forward
+                raw = int(child.findtext('duration', '0'))
+                cursor += get_dur(raw)
+                max_cursor = max(max_cursor, cursor)
+
+            elif tag == 'harmony':
+                # 규칙 6: harmony 무시
+                pass
+
+            elif tag == 'note':
+                raw_dur = int(child.findtext('duration', '0'))
+                dur_f = get_dur(raw_dur, child)
+
+                is_chord = child.find('chord') is not None
+                is_rest  = child.find('rest')  is not None
+                is_grace = child.find('grace') is not None
+
+                # 규칙: grace 기본 제거
+                if is_grace:
+                    if not is_chord:
+                        # grace는 duration=0 이 많지만 혹시 있으면
+                        cursor += dur_f
+                        max_cursor = max(max_cursor, cursor)
+                    continue
+
+                # 규칙 3: chord note는 직전 non-chord note와 같은 시작점
+                if is_chord:
+                    note_start = last_note_start if last_note_start is not None else cursor
+                else:
+                    note_start = cursor
+                    last_note_start = cursor
+
+                tie_types = frozenset(t.attrib.get('type') for t in child.findall('tie'))
+
+                if not is_rest:
+                    p = child.find('pitch')
+                    if p is not None:
+                        step   = p.findtext('step', 'C')
+                        octave = int(p.findtext('octave', '4'))
+                        alter  = int(float(p.findtext('alter', '0')))
+                        midi = (octave + 1) * 12 + STEP_TO_SEMI.get(step, 0) + alter
+                        abs_start = measure_start + note_start
+                        staff = int(child.findtext('staff', '1'))
+                        events.append({
+                            'start': abs_start,
+                            'dur':   dur_f,
+                            'midi':  midi,
+                            'tie':   tie_types,
+                            'staff': staff,
+                        })
+
+                # cursor 갱신 (규칙 3: chord는 cursor 이동 안 함)
+                if not is_chord:
+                    cursor += dur_f
+                    max_cursor = max(max_cursor, cursor)
+                else:
+                    max_cursor = max(max_cursor, note_start + dur_f)
+
+        measure_start += max_cursor
+
+    return events, measure_start
+
+
+def parse_xml_string(xml_str: str) -> Tuple[List[dict], Fraction, int]:
+    """MusicXML 문자열 → (모든 파트 이벤트 합산, 총 ticks, tempo)"""
+    root = ET.fromstring(xml_str.encode('utf-8', errors='replace')
+                         if isinstance(xml_str, str) else xml_str)
+    strip_ns(root)
+    tempo = parse_tempo(root)
+
+    all_events: List[dict] = []
+    total_dur = Fraction(0)
+
+    for part in root.findall('part'):
+        evs, part_dur = parse_part(part)
+        all_events.extend(evs)
+        total_dur = max(total_dur, part_dur)
+
+    return all_events, total_dur, tempo
+
+
+# ─────────────────────────────────────────────────────────────────
+# 타이 병합 (규칙 5)
+# ─────────────────────────────────────────────────────────────────
+def merge_ties(events: List[dict]) -> List[dict]:
+    """동일 pitch의 tie start→stop 연결을 지속음으로 병합"""
+    out: List[dict] = []
+    # midi → index in out
+    ongoing: Dict[int, int] = {}
+
+    for e in sorted(events, key=lambda x: (x['start'], x['midi'])):
+        midi = e['midi']
+        tie  = e['tie']
+
+        if 'stop' in tie and midi in ongoing:
+            prev = out[ongoing[midi]]
+            # 연속(직전 note의 끝 == 현재 시작)이어야 병합
+            if prev['start'] + prev['dur'] == e['start']:
+                prev['dur'] += e['dur']
+                if 'start' not in tie:
+                    del ongoing[midi]
+                continue  # 현재 이벤트를 별도 추가하지 않음
+
+        # 새 이벤트로 추가
+        new_ev = {k: v for k, v in e.items()}
+        out.append(new_ev)
+        if 'start' in tie:
+            ongoing[midi] = len(out) - 1
+
+    return out
+
+
+# ─────────────────────────────────────────────────────────────────
+# 동시음 축약 (규칙 8~9)
+# ─────────────────────────────────────────────────────────────────
+def _best_middle(pitches: List[int], top: int, bot: int) -> Optional[int]:
+    """
+    top/bot 제외 후보에서 화성 정체성을 가장 살리는 1음 반환.
+    제거 우선순위: 옥타브 중복 > 완전5도 중복 > 통과음
+    """
+    candidates = [p for p in pitches if p != top and p != bot]
+    if not candidates:
+        return None
+
+    top_cls = top % 12
+    bot_cls = bot % 12
+
+    # 1단계: top/bot과 옥타브 중복 제거
+    f1 = [p for p in candidates if p % 12 not in (top_cls, bot_cls)]
+    if f1:
+        candidates = f1
+
+    # 2단계: top의 완전5도(7반음 아래) 음 제거
+    p5_cls = (top_cls - 7) % 12
+    f2 = [p for p in candidates if p % 12 != p5_cls]
+    if f2:
+        candidates = f2
+
+    # 3단계: 화음 내 우선 음정 (단3/장3/단7 등) 기준 선택
+    PREFERRED_INTERVALS = {3: 0, 4: 1, 10: 2, 9: 3, 7: 4, 8: 5, 5: 6, 2: 7}
+
+    def harmony_score(p: int):
+        interval = (top - p) % 12
+        return (PREFERRED_INTERVALS.get(interval, 10), -p)
+
+    return min(candidates, key=harmony_score)
+
+
+def reduce_simultaneous(events: List[dict]) -> List[dict]:
+    """
+    규칙 8~9: 같은 start_tick에서 4음 이상 동시 시작이면 3음으로 축약.
+    """
+    by_start: Dict[Fraction, List[dict]] = {}
+    for e in events:
+        by_start.setdefault(e['start'], []).append(e)
+
+    result: List[dict] = []
+    for start in sorted(by_start):
+        group = sorted(by_start[start], key=lambda x: -x['midi'])
+        if len(group) <= 3:
+            result.extend(group)
+        else:
+            top = group[0]
+            bot = group[-1]
+            pitches = [ev['midi'] for ev in group]
+            mid_pitch = _best_middle(pitches, top['midi'], bot['midi'])
+
+            kept = [top]
+            if mid_pitch is not None:
+                # group에서 해당 pitch의 이벤트 찾기 (top/bot 제외)
+                for ev in group[1:-1]:
+                    if ev['midi'] == mid_pitch:
+                        kept.append(ev)
+                        break
+            kept.append(bot)
+            result.extend(kept)
+
+    return result
+
+
+# ─────────────────────────────────────────────────────────────────
+# 3트랙 배정 (규칙 10)
+# ─────────────────────────────────────────────────────────────────
+def assign_3_tracks(
+    events: List[dict],
+    total_dur: Fraction
+) -> Tuple[List[dict], List[dict], List[dict]]:
+    """
+    이벤트를 Melody(0) / Chord1(1) / Bass(2) 3트랙으로 배정.
+    동시 시작: 고음→Melody, 중간→Chord1, 저음→Bass.
+    단독음: 빈 트랙에 Melody 우선 배정.
+    """
+    tracks: List[List[dict]] = [[], [], []]
+    track_end = [Fraction(-1)] * 3  # 각 트랙의 현재 점유 끝 tick
+
+    by_start: Dict[Fraction, List[dict]] = {}
+    for e in events:
+        by_start.setdefault(e['start'], []).append(e)
+
+    for start in sorted(by_start):
+        group = sorted(by_start[start], key=lambda x: -x['midi'])
+        n = len(group)
+
+        if n >= 3:
+            # 3음: 고→0(Melody), 중→1(Chord1), 저→2(Bass)
+            for tidx, ev in [(0, group[0]), (1, group[1]), (2, group[-1])]:
+                tracks[tidx].append(ev)
+                track_end[tidx] = ev['start'] + ev['dur']
+
+        elif n == 2:
+            # 2음: 고→Melody, 저→Bass 시도
+            pairs = [(0, group[0]), (2, group[1])]
+            for tidx, ev in pairs:
+                if track_end[tidx] <= ev['start']:
+                    tracks[tidx].append(ev)
+                    track_end[tidx] = ev['start'] + ev['dur']
+                elif track_end[1] <= ev['start']:
+                    tracks[1].append(ev)
+                    track_end[1] = ev['start'] + ev['dur']
+                # 모두 겹치면 skip (손실 허용)
+
+        else:  # n == 1
+            ev = group[0]
+            # 빈 트랙에 Melody 우선
+            assigned = False
+            for tidx in [0, 1, 2]:
+                if track_end[tidx] <= ev['start']:
+                    tracks[tidx].append(ev)
+                    track_end[tidx] = ev['start'] + ev['dur']
+                    assigned = True
+                    break
+            # 모두 busy면 pitch가 가장 가까운 트랙에 강제 배정
+            if not assigned:
+                closest = min(
+                    range(3),
+                    key=lambda i: abs(
+                        (tracks[i][-1]['midi'] if tracks[i] else 60) - ev['midi']
+                    )
+                )
+                tracks[closest].append(ev)
+                track_end[closest] = max(track_end[closest], ev['start'] + ev['dur'])
+
+    # 각 트랙 start 기준 정렬
+    for i in range(3):
+        tracks[i].sort(key=lambda e: (e['start'], -e['midi']))
+
+    return tracks[0], tracks[1], tracks[2]
+
+
+# ─────────────────────────────────────────────────────────────────
+# 틱 → MML 토큰 분해 (규칙 11)
+# ─────────────────────────────────────────────────────────────────
+@lru_cache(maxsize=4096)
+def _decompose_dp(rem: int) -> Optional[tuple]:
+    """DP로 rem 틱을 MML 토큰 틱 리스트로 분해 (최소 토큰 수)"""
+    if rem == 0:
+        return ()
+    best: Optional[tuple] = None
+    for tick, _ in MML_DUR_TABLE:
+        if tick <= rem:
+            tail = _decompose_dp(rem - tick)
+            if tail is not None:
+                cand = (tick,) + tail
+                if best is None or len(cand) < len(best):
+                    best = cand
+    return best
+
+
+def decompose_duration(ticks: Fraction) -> List[Tuple[int, str]]:
+    """Fraction 틱 → [(tick, MML_token), ...] (규칙 11)"""
+    iticks = round(float(ticks))
+    iticks = max(0, iticks)
+    if iticks == 0:
+        return []
+    parts = _decompose_dp(iticks)
+    if parts is None:
+        raise ValueError(f'분해 불가: {ticks} → {iticks} ticks')
+    return [(t, MML_TICK_TO_TOKEN[t]) for t in parts]
+
+
+# ─────────────────────────────────────────────────────────────────
+# MML 빌드
+# ─────────────────────────────────────────────────────────────────
+def _midi_to_oct_note(midi: int) -> Tuple[int, str]:
+    return midi // 12 - 1, SEMI_TO_NOTE[midi % 12]
+
+
+def build_track_mml(events: List[dict], total_dur: Fraction, optimize: bool = True) -> str:
+    """이벤트 리스트 + 총 길이 → MML 문자열 (MML@ 와 ; 제외)
+
+    optimize=True:
+    - ±1 옥타브 이동: oN 대신 >/< 사용
+    - 같은 음표길이 3개 이상 연속: lN 설정 후 suffix 생략
+    """
+    # Phase 1: raw 토큰 생성
+    # ('oct', int) | ('note', str, str) | ('rest', str) | ('tie',)
+    raw: List[tuple] = []
+    cur_time = Fraction(0)
+    cur_oct: Optional[int] = None
+
+    for e in events:
+        if e['start'] > cur_time:
+            for _, tok in decompose_duration(e['start'] - cur_time):
+                raw.append(('rest', tok))
+            cur_time = e['start']
+        if e['start'] < cur_time:
+            continue
+
+        octave, note = _midi_to_oct_note(e['midi'])
+        if cur_oct != octave:
+            raw.append(('oct', octave))
+            cur_oct = octave
+
+        dur_parts = decompose_duration(e['dur'])
+        for i, (_, tok) in enumerate(dur_parts):
+            raw.append(('note', note, tok))
+            if i < len(dur_parts) - 1:
+                raw.append(('tie',))
+        cur_time = e['start'] + e['dur']
+
+    if cur_time < total_dur:
+        for _, tok in decompose_duration(total_dur - cur_time):
+            raw.append(('rest', tok))
+
+    # Phase 2: 연속 같은 duration run 길이 계산 (optimize 시에만 사용)
+    n = len(raw)
+    run_len = [1] * n
+    if optimize:
+        for i in range(n - 2, -1, -1):
+            a, b = raw[i], raw[i + 1]
+            if a[0] in ('note', 'rest') and b[0] in ('note', 'rest'):
+                da = a[2] if a[0] == 'note' else a[1]
+                db = b[2] if b[0] == 'note' else b[1]
+                if da == db:
+                    run_len[i] = run_len[i + 1] + 1
+
+    # Phase 3: 출력 생성
+    pieces: List[str] = []
+    cur_oct = None
+    cur_len: Optional[str] = None
+
+    for i, t in enumerate(raw):
+        if t[0] == 'oct':
+            new_oct = t[1]
+            if cur_oct is not None:
+                diff = new_oct - cur_oct
+                if optimize and diff == 1:
+                    pieces.append('>')
+                elif optimize and diff == -1:
+                    pieces.append('<')
+                else:
+                    pieces.append(f'o{new_oct}')
+            else:
+                pieces.append(f'o{new_oct}')
+            cur_oct = new_oct
+        elif t[0] == 'tie':
+            pieces.append('&')
+        elif t[0] == 'rest':
+            suffix = t[1]
+            if optimize and run_len[i] >= 3 and suffix != cur_len:
+                pieces.append(f'l{suffix}')
+                cur_len = suffix
+            pieces.append('r' if suffix == cur_len else 'r' + suffix)
+        elif t[0] == 'note':
+            note, suffix = t[1], t[2]
+            if optimize and run_len[i] >= 3 and suffix != cur_len:
+                pieces.append(f'l{suffix}')
+                cur_len = suffix
+            pieces.append(note if suffix == cur_len else note + suffix)
+
+    return ''.join(pieces)
+
+
+# ─────────────────────────────────────────────────────────────────
+# 변환 파이프라인
+# ─────────────────────────────────────────────────────────────────
+def convert_files(file_paths: List[str], optimize: bool = True) -> Tuple[str, str, str, int]:
+    """
+    여러 파일(페이지 순서)을 연결해 3파트 MML로 변환.
+    Returns: (melody_mml, chord1_mml, bass_mml, tempo)
+    """
+    all_events: List[dict] = []
+    total_dur = Fraction(0)
+    tempo = 120
+
+    for path in file_paths:
+        xml_str = open_mxl_or_xml(path)
+        evs, dur, bpm = parse_xml_string(xml_str)
+        # 페이지 오프셋 적용
+        for e in evs:
+            e['start'] += total_dur
+        all_events.extend(evs)
+        total_dur += dur
+        tempo = bpm
+
+    # 파이프라인
+    all_events = merge_ties(all_events)          # 규칙 5
+    all_events = reduce_simultaneous(all_events) # 규칙 8~9
+
+    mel, ch1, bas = assign_3_tracks(all_events, total_dur)  # 규칙 10
+
+    melody_mml = build_track_mml(mel, total_dur, optimize=optimize)
+    chord1_mml = build_track_mml(ch1, total_dur, optimize=optimize)
+    bass_mml   = build_track_mml(bas, total_dur, optimize=optimize)
+
+    return melody_mml, chord1_mml, bass_mml, tempo
+
+
+def format_output(melody: str, chord1: str, bass: str, tempo: int) -> str:
+    """
+    3파트 MML 결과를 텍스트 형식으로 포매팅.
+    마비노기 1인 악보용: MML@p1,p2,p3; 통합 포맷으로 출력.
+    """
+    lines = [
+        'Part 1',
+        f'MML@{melody};',
+        '',
+        'Part 2',
+        f'MML@{chord1};',
+        '',
+        'Part 3',
+        f'MML@{bass};',
+    ]
+    return '\n'.join(lines)
+
+
+# ─────────────────────────────────────────────────────────────────
+# 가야금 모드
+# ─────────────────────────────────────────────────────────────────
+
+def _clamp_midi_to_range(midi: int, lo: int, hi: int) -> int:
+    """MIDI 번호를 lo~hi 범위 안���로 12반음 단위로 조정."""
+    while midi > hi:
+        midi -= 12
+    while midi < lo:
+        midi += 12
+    return midi
+
+
+def convert_files_gayageum(file_paths: List[str], optimize: bool = True) -> Tuple[str, str, str, int]:
+    """
+    가야금 모드 변환.
+    Staff 1(오른손) → 농현(o5~o8, MIDI 72~107): MIDI +48 후 클램프
+    Staff 2(왼손)  → 평음(o1~o4, MIDI 24~59): 범위 벗어나면 클램프
+    합산 후 3파트로 압축.
+    Returns: (melody_mml, chord1_mml, bass_mml, tempo)
+    """
+    all_events: List[dict] = []
+    total_dur = Fraction(0)
+    tempo = 120
+
+    for path in file_paths:
+        xml_str = open_mxl_or_xml(path)
+        evs, dur, bpm = parse_xml_string(xml_str)
+        for e in evs:
+            e['start'] += total_dur
+        all_events.extend(evs)
+        total_dur += dur
+        tempo = bpm
+
+    all_events = merge_ties(all_events)
+    staff_map = split_by_staff(all_events)
+
+    mapped: List[dict] = []
+
+    # Staff 1: 오른손 → 농현 (o5~o8, MIDI 72~107)
+    for e in staff_map.get(1, []):
+        ne = dict(e)
+        ne['midi'] = _clamp_midi_to_range(e['midi'] + 48, 72, 107)
+        mapped.append(ne)
+
+    # Staff 2: 왼손 → 평음 (o1~o4, MIDI 24~59)
+    for e in staff_map.get(2, []):
+        ne = dict(e)
+        ne['midi'] = _clamp_midi_to_range(e['midi'], 24, 59)
+        mapped.append(ne)
+
+    mapped = reduce_simultaneous(mapped)
+    mel, ch1, bas = assign_3_tracks(mapped, total_dur)
+
+    melody_mml = build_track_mml(mel, total_dur, optimize=optimize)
+    chord1_mml = build_track_mml(ch1, total_dur, optimize=optimize)
+    bass_mml   = build_track_mml(bas, total_dur, optimize=optimize)
+
+    return melody_mml, chord1_mml, bass_mml, tempo
+
+
+# ─────────────────────────────────────────────────────────────────
+# staff 기반 분리
+# ─────────────────────────────────────────────────────────────────
+
+def split_by_staff(events: List[dict]) -> Dict[int, List[dict]]:
+    """이벤트를 staff 번호별로 분리. {staff_num: [events]}"""
+    result: Dict[int, List[dict]] = {}
+    for e in events:
+        s = e.get('staff', 1)
+        result.setdefault(s, []).append(e)
+    return result
+
+
+def convert_files_by_staff(file_paths: List[str], optimize: bool = True) -> Tuple[Dict[int, str], Fraction, int]:
+    """
+    Staff별로 MML을 분리해서 반환.
+    Returns: ({staff_num: mml_str}, total_dur, tempo)
+    """
+    all_events: List[dict] = []
+    total_dur = Fraction(0)
+    tempo = 120
+
+    for path in file_paths:
+        xml_str = open_mxl_or_xml(path)
+        evs, dur, bpm = parse_xml_string(xml_str)
+        for e in evs:
+            e['start'] += total_dur
+        all_events.extend(evs)
+        total_dur += dur
+        tempo = bpm
+
+    all_events = merge_ties(all_events)
+    staff_events = split_by_staff(all_events)
+
+    staff_mmls: Dict[int, str] = {}
+    for staff_num, evs in sorted(staff_events.items()):
+        # staff 내 동시음을 높은음 순으로 n개 트랙으로 분리
+        tracks = assign_n_tracks(evs, total_dur)
+        # 각 트랙을 MML로 변환 후 합산 (staff 하나 = 여러 트랙 가능)
+        track_mmls = [build_track_mml(t, total_dur, optimize=optimize) for t in tracks]
+        staff_mmls[staff_num] = track_mmls  # 트랙 리스트로 저장
+
+    return staff_mmls, total_dur, tempo
+
+
+def format_output_by_staff(staff_mmls: Dict[int, list], total_dur: Fraction, tempo: int) -> str:
+    """
+    Staff별 MML을 파트 형태로 출력.
+    Staff 1 = 오른손(멜로디), Staff 2 = 왼손(베이스) 순.
+    """
+    lines = []
+    part_num = 1
+    for staff_num, track_mmls in sorted(staff_mmls.items()):
+        hand = '오른손' if staff_num == 1 else '왼손' if staff_num == 2 else f'Staff {staff_num}'
+        for i, mml in enumerate(track_mmls, 1):
+            lines.append(f'Part {part_num}  [{hand} Track {i}]')
+            lines.append(f'MML@{mml};')
+            lines.append('')
+            part_num += 1
+    return '\n'.join(lines)
+
+
+# ─────────────────────────────────────────────────────────────────
+# --all-notes 모드: 동시음 전부 포함, 파트 수 = 최대 동시음 수
+# ─────────────────────────────────────────────────────────────────
+
+def assign_n_tracks(events: List[dict], total_dur: Fraction) -> List[List[dict]]:
+    """
+    동시음을 높은음 순으로 N개 트랙에 배정. 음 하나도 버리지 않음.
+    N = 전체 악보에서 동시에 울리는 음의 최대 개수.
+    Returns: N개 트랙 리스트 (각 트랙은 event dict 리스트)
+    """
+    if not events:
+        return [[]]
+
+    # 각 시작 시점의 동시음 개수 파악 → 최대값 N
+    from collections import defaultdict
+    start_groups: dict = defaultdict(list)
+    for e in events:
+        start_groups[e['start']].append(e)
+
+    max_poly = max(len(g) for g in start_groups.values())
+    n = max(max_poly, 1)
+
+    tracks: List[List[dict]] = [[] for _ in range(n)]
+
+    for start, group in sorted(start_groups.items()):
+        # 높은음 순 정렬
+        sorted_group = sorted(group, key=lambda e: e['midi'], reverse=True)
+        for i, ev in enumerate(sorted_group):
+            tracks[i % n].append(ev)
+
+    return tracks
+
+
+def format_output_n(tracks: List[List[dict]], total_dur: Fraction, tempo: int, optimize: bool = True) -> str:
+    """
+    N파트 MML 결과를 텍스트 형식으로 포매팅.
+    Part 1 ~ Part N 형식.
+    """
+    lines = []
+    for i, track in enumerate(tracks, 1):
+        mml = build_track_mml(track, total_dur, optimize=optimize)
+        lines.append(f'Part {i}')
+        lines.append(f'MML@{mml};')
+        lines.append('')
+    return '\n'.join(lines)
+
+
+def convert_files_all_notes(file_paths: List[str]) -> Tuple[List[List[dict]], Fraction, int]:
+    """
+    여러 파일을 연결해 N파트(최대 동시음 수)로 변환.
+    Returns: (tracks, total_dur, tempo)
+    """
+    all_events: List[dict] = []
+    total_dur = Fraction(0)
+    tempo = 120
+
+    for path in file_paths:
+        xml_str = open_mxl_or_xml(path)
+        evs, dur, bpm = parse_xml_string(xml_str)
+        for e in evs:
+            e['start'] += total_dur
+        all_events.extend(evs)
+        total_dur += dur
+        tempo = bpm
+
+    all_events = merge_ties(all_events)
+    tracks = assign_n_tracks(all_events, total_dur)
+
+    return tracks, total_dur, tempo
+
+
+# ─────────────────────────────────────────────────────────────────
+# CLI
+# ─────────────────────────────────────────────────────────────────
+def main():
+    parser = argparse.ArgumentParser(description='MusicXML → 3파트 MML 변환기')
+    parser.add_argument('files', nargs='+', help='입력 MXL/XML 파일 (페이지 순서)')
+    parser.add_argument('-o', '--output', help='출력 파일 경로')
+    parser.add_argument('--append', action='store_true',
+                        help='기존 파일 하단에 구분선과 함께 추가')
+    parser.add_argument('--all-notes', action='store_true',
+                        help='동시음 전부 포함, 파트 수=최대 동시음 수 모드')
+    parser.add_argument('--gayageum', action='store_true',
+                        help='가야금 모드: 오른손→농현(o5~o8), 왼손→평음(o1~o4), 3파트 출력')
+    args = parser.parse_args()
+
+    print(f'변환 중: {args.files}', file=sys.stderr)
+
+    if args.gayageum:
+        melody, chord1, bass, tempo = convert_files_gayageum(args.files)
+        result_text = format_output(melody, chord1, bass, tempo)
+        print('가야금 모드: 오른손→농현(o5~o8), 왼손→평음(o1~o4)', file=sys.stderr)
+    elif args.all_notes:
+        tracks, total_dur, tempo = convert_files_all_notes(args.files)
+        result_text = format_output_n(tracks, total_dur, tempo)
+        print(f'파트 수: {len(tracks)}', file=sys.stderr)
+    else:
+        melody, chord1, bass, tempo = convert_files(args.files)
+        result_text = format_output(melody, chord1, bass, tempo)
+
+    if args.output:
+        if args.append:
+            SEP = '\n' + '-' * 40 + '\n'
+            with open(args.output, 'a', encoding='utf-8') as f:
+                f.write(SEP)
+                f.write(result_text)
+                f.write('\n')
+        else:
+            with open(args.output, 'w', encoding='utf-8') as f:
+                f.write(result_text)
+                f.write('\n')
+        print(f'저장: {args.output}', file=sys.stderr)
+    else:
+        print(result_text)
+
+
+if __name__ == '__main__':
+    main()

core/__init__.py

@@ -0,0 +1 @@
+# core package

core/convert_pipeline.py

@@ -0,0 +1,413 @@
+"""
+core/convert_pipeline.py
+
+악보(PDF/PNG/JPG) → MML 변환 파이프라인.
+
+run_score_pipeline() 하나를 호출하면:
+  1. PDF → 300DPI PNG 분리 (fitz)
+  2. 선택적 전처리 (Grayscale + Otsu 이진화, cv2)
+  3. Audiveris OMR → MXL 파일
+  4. convert_3part.convert_files_all_notes()  → 전체 화음(N파트)
+  5. convert_3part.convert_files()            → 3파트
+  6. 결과 텍스트 반환 (N파트 위 / 구분선 / 3파트 아래)
+
+환경변수:
+  AUDIVERIS_BIN=<경로>  Audiveris 실행 파일
+  AUDIVERIS_JAR=<경로>  Audiveris.jar (java -jar 방식)
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+SEP = "\n" + "-" * 40 + "\n"
+
+WAIFU2X_DEFAULT = r"C:\tools\waifu2x-ncnn-vulkan\waifu2x-ncnn-vulkan-20250915-windows\waifu2x-ncnn-vulkan.exe"
+
+# ─────────────────────────────────────────────────────────────────
+# Audiveris 경로 확인
+# ─────────────────────────────────────────────────────────────────
+
+def _get_audiveris_cmd(image_path: str, output_dir: str) -> list[str]:
+    bin_path = os.environ.get("AUDIVERIS_BIN", "")
+    jar_path = os.environ.get("AUDIVERIS_JAR", "")
+    if bin_path:
+        return [bin_path, "-batch", "-export", "-output", output_dir, "--", image_path]
+    if jar_path:
+        max_heap = os.environ.get("AUDIVERIS_MAX_HEAP", "1500m")
+        return ["java", f"-Xmx{max_heap}", "-jar", jar_path, "-batch", "-export", "-output", output_dir, "--", image_path]
+    raise RuntimeError(
+        "Audiveris 환경변수가 설정되지 않았습니다.\n"
+        "  set AUDIVERIS_BIN=C:\\path\\to\\Audiveris.exe"
+    )
+
+
+# ─────────────────────────────────────────────────────────────────
+# PDF → PNG
+# ─────────────────────────────────────────────────────────────────
+
+def _pdf_to_pngs(pdf_path: str, out_dir: str, dpi: int = 300) -> list[str]:
+    import fitz
+    doc = fitz.open(pdf_path)
+    mat = fitz.Matrix(dpi / 72, dpi / 72)
+    paths = []
+    for i, page in enumerate(doc):
+        pix = page.get_pixmap(matrix=mat)
+        p = Path(out_dir) / f"page_{i+1:02d}.png"
+        pix.save(str(p))
+        paths.append(str(p))
+    return paths
+
+
+# ─────────────────────────────────────────────────────────────────
+# PNG 복사 + DPI 메타데이터 설정
+# ─────────────────────────────────────────────────────────────────
+
+def _copy_with_scale(src: str, dst: str, scale: float = 1.0) -> None:
+    """이미지를 복사하면서 scale 배율로 업스케일. scale=1이면 그대로 복사."""
+    from PIL import Image
+    img = Image.open(src)
+    if scale != 1.0:
+        new_w = int(img.width * scale)
+        new_h = int(img.height * scale)
+        img = img.resize((new_w, new_h), Image.LANCZOS)
+    # RGBA/팔레트 모드는 Audiveris가 처리 못할 수 있음 → RGB로 변환
+    if img.mode not in ("RGB", "L"):
+        img = img.convert("RGB")
+    img.save(dst)
+
+
+# ─────────────────────────────────────────────────────────────────
+# waifu2x-ncnn-vulkan 업스케일
+# ─────────────────────────────────────────────────────────────────
+
+def _upscale_waifu2x(src: str, dst: str, scale: int = 2, noise: int = 1) -> None:
+    """waifu2x-ncnn-vulkan으로 업스케일 + 노이즈 제거.
+    scale: 2/4/8/16/32 (waifu2x는 2의 거듭제곱만 지원)
+    noise: -1(없음) / 0~3
+    """
+    exe = os.environ.get("WAIFU2X_BIN", WAIFU2X_DEFAULT)
+    if not Path(exe).exists():
+        raise RuntimeError(
+            f"waifu2x-ncnn-vulkan 실행 파일을 찾을 수 없습니다: {exe}\n"
+            "환경변수 WAIFU2X_BIN 또는 기본 경로를 확인하세요."
+        )
+    cmd = [exe, "-i", src, "-o", dst, "-s", str(scale), "-n", str(noise), "-f", "png"]
+    proc = subprocess.run(cmd, capture_output=True, timeout=300)
+    if proc.returncode != 0 or not Path(dst).exists() or Path(dst).stat().st_size == 0:
+        stderr = proc.stderr.decode("utf-8", errors="ignore")[-300:]
+        raise RuntimeError(f"waifu2x 실패 (exit {proc.returncode}): {stderr}")
+
+
+# ─────────────────────────────────────────────────────────────────
+# 전처리 (Grayscale + Otsu 이진화)
+# ─────────────────────────────────────────────────────────────────
+
+def _deskew(gray_img):
+    """OpenCV로 기울기 보정. grayscale ndarray 입력 → 보정된 ndarray 반환."""
+    import cv2
+    import numpy as np
+    coords = np.column_stack(np.where(gray_img < 128))
+    if len(coords) < 10:
+        return gray_img
+    angle = cv2.minAreaRect(coords)[-1]
+    if angle < -45:
+        angle = 90 + angle
+    h, w = gray_img.shape
+    center = (w // 2, h // 2)
+    M = cv2.getRotationMatrix2D(center, angle, 1.0)
+    return cv2.warpAffine(gray_img, M, (w, h), flags=cv2.INTER_LINEAR,
+                          borderMode=cv2.BORDER_REPLICATE)
+
+
+def _preprocess(src: str, dst: str, mode: str = "otsu") -> None:
+    import cv2
+    import numpy as np
+
+    if mode == "otsu":
+        img = cv2.imread(src, cv2.IMREAD_COLOR)
+        gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+        gray = cv2.GaussianBlur(gray, (3, 3), 0)
+        gray = _deskew(gray)
+        _, binary = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+        cv2.imwrite(dst, binary)
+
+    elif mode == "adaptive":
+        img = cv2.imread(src, cv2.IMREAD_COLOR)
+        gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+        gray = cv2.GaussianBlur(gray, (3, 3), 0)
+        gray = _deskew(gray)
+        binary = cv2.adaptiveThreshold(
+            gray, 255,
+            cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
+            cv2.THRESH_BINARY, 15, 10,
+        )
+        cv2.imwrite(dst, binary)
+
+    elif mode == "contrast":
+        from PIL import Image, ImageEnhance
+        img = Image.open(src)
+        img = ImageEnhance.Contrast(img).enhance(2.0)
+        img = ImageEnhance.Sharpness(img).enhance(1.5)
+        if img.mode not in ("RGB", "L"):
+            img = img.convert("RGB")
+        img.save(dst)
+
+
+# ─────────────────────────────────────────────────────────────────
+# PNG → MXL (Audiveris)
+# ─────────────────────────────────────────────────────────────────
+
+_AUDIVERIS_MAX_PX = 4800  # 이 값 초과 시 비율 유지하며 축소
+
+
+def _normalize_png(src: str, dst: str) -> None:
+    """PIL로 RGB/L 정규화 + 최대 해상도 캡 적용 후 저장 — Audiveris 호환 보장."""
+    from PIL import Image
+    Image.MAX_IMAGE_PIXELS = None  # waifu2x 고배율 출력 허용 (바로 축소하므로 안전)
+    img = Image.open(src)
+    img = img.convert("RGB")  # Audiveris는 RGB를 가장 안정적으로 처리
+    max_dim = max(img.width, img.height)
+    if max_dim > _AUDIVERIS_MAX_PX:
+        ratio = _AUDIVERIS_MAX_PX / max_dim
+        img = img.resize(
+            (int(img.width * ratio), int(img.height * ratio)),
+            Image.LANCZOS,
+        )
+    img.save(dst, format="PNG")
+
+
+def _run_audiveris(png_path: str, mxl_save_dir: str, on_line=None) -> tuple[Optional[str], str]:
+    """
+    PNG 한 장을 Audiveris로 처리 → (MXL 파일 경로, 에러메시지).
+    실패 시 (None, 에러메시지) 반환.
+    on_line: Audiveris 출력 한 줄씩 전달받는 콜백 (optional)
+    """
+    # Audiveris 전 PIL 정규화 (waifu2x/전처리 후 포맷 이슈 방지)
+    norm_path = png_path.replace(".png", "_norm.png")
+    _normalize_png(png_path, norm_path)
+
+    with tempfile.TemporaryDirectory() as tmp:
+        cmd = _get_audiveris_cmd(norm_path, tmp)
+        proc = subprocess.Popen(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+        )
+        stdout_lines = []
+        for raw in proc.stdout:
+            line = raw.decode("utf-8", errors="ignore").rstrip()
+            if line:
+                stdout_lines.append(line)
+                if on_line:
+                    on_line(line)
+        proc.wait()
+
+        mxl_files = list(Path(tmp).rglob("*.mxl"))
+        if not mxl_files:
+            stdout_tail = "\n".join(stdout_lines[-10:])
+            err = f"exit code {proc.returncode} / stdout: {stdout_tail}"
+            return None, err
+
+        dest = Path(mxl_save_dir) / f"{Path(png_path).stem}.mxl"
+        shutil.copy2(mxl_files[0], dest)
+
+        # XML 추출 (압축 해제)
+        xml_dest = Path(mxl_save_dir) / f"{Path(png_path).stem}.xml"
+        import zipfile as _zf
+        with _zf.ZipFile(dest) as zf:
+            xml_members = [n for n in zf.namelist()
+                           if n.lower().endswith(".xml") and "container" not in n.lower()]
+            if xml_members:
+                xml_dest.write_bytes(zf.read(xml_members[0]))
+
+        return str(dest), ""
+
+
+# ─────────────────────────────────────────────────────────────────
+# 메인 파이프라인
+# ─────────────────────────────────────────────────────────────────
+
+def run_score_pipeline(
+    input_path: str,
+    preprocess_mode: str = "none",
+    dpi: int = 300,
+    upscale_mode: str = "none",
+    save_dir: str = "",
+    on_progress=None,
+    correct_xml: bool = False,
+) -> tuple[str, list[str], list[str]]:
+    """
+    악보 파일(PDF/PNG/JPG) → MML 텍스트 변환.
+
+    Args:
+        input_path:      입력 파일 경로
+        preprocess_mode: 전처리 모드 — "none" / "otsu" / "adaptive" / "contrast"
+        dpi:             PDF 렌더링 해상도
+        upscale_mode:    업스케일 모드 — "none" / "pil_2"~"pil_5" / "waifu2x_2" / "waifu2x_4"
+        save_dir:        MXL 및 페이지 PNG를 저장할 폴더.
+                         비어 있으면 temp 폴더 사용 후 자동 삭제.
+
+    Returns:
+        (combined_text, mxl_paths, warnings)
+        combined_text: N파트(전체화음) + 구분선 + 3파트
+        mxl_paths: 생성된 MXL 파일 경로 목록 (다운로드용)
+    """
+    # convert_3part 함수 import (프로젝트 루트 기준)
+    project_root = Path(__file__).parent.parent
+    if str(project_root) not in sys.path:
+        sys.path.insert(0, str(project_root))
+    from convert_3part import (
+        convert_files_all_notes, format_output_n,
+        convert_files, format_output,
+    )
+
+    warnings: list[str] = []
+    ext = Path(input_path).suffix.lower()
+
+    work_dir = save_dir if save_dir else tempfile.mkdtemp(prefix="sml_pipe_")
+    pages_dir = Path(work_dir) / "pages"
+    mxl_dir   = Path(work_dir) / "mxl"
+    pages_dir.mkdir(parents=True, exist_ok=True)
+    mxl_dir.mkdir(parents=True, exist_ok=True)
+
+    def _prog(frac: float, desc: str) -> None:
+        if on_progress:
+            on_progress(frac, desc)
+
+    try:
+        # ── 1. 입력 → PNG 목록 ──────────────────────────────────────
+        _prog(0.0, "페이지 분리 중...")
+        if ext == ".pdf":
+            raw_pngs = _pdf_to_pngs(input_path, str(pages_dir), dpi=dpi)
+        else:
+            dest = str(pages_dir / f"page_01.png")
+            _copy_with_scale(input_path, dest, scale=1.0)
+            raw_pngs = [dest]
+        total = len(raw_pngs)
+        orig_pngs = list(raw_pngs)  # 업스케일 이전 원본 PNG 목록 (교정 비교용)
+
+        # ── 1-b. 업스케일 ────────────────────────────────────────────
+        if upscale_mode.startswith("pil_"):
+            scale = int(upscale_mode.split("_")[1])
+            scaled_pngs = []
+            for i, src in enumerate(raw_pngs):
+                _prog(0.05 + 0.10 * i / total, f"업스케일 중... ({i+1}/{total})")
+                dst = src.replace(".png", f"_x{scale}.png")
+                _copy_with_scale(src, dst, scale=float(scale))
+                scaled_pngs.append(dst)
+            raw_pngs = scaled_pngs
+        elif upscale_mode.startswith("waifu2x_"):
+            scale = int(upscale_mode.split("_")[1])
+            scaled_pngs = []
+            for i, src in enumerate(raw_pngs):
+                _prog(0.05 + 0.15 * i / total, f"waifu2x 업스케일 중... ({i+1}/{total})")
+                dst = src.replace(".png", f"_w2x.png")
+                _upscale_waifu2x(src, dst, scale=scale, noise=1)
+                scaled_pngs.append(dst)
+            raw_pngs = scaled_pngs
+
+        # ── 2. 선택적 전처리 ────────────────────────────────────────
+        if preprocess_mode != "none":
+            processed_pngs = []
+            for i, src in enumerate(raw_pngs):
+                _prog(0.20 + 0.05 * i / total, f"전처리 중... ({i+1}/{total})")
+                dst = src.replace(".png", "_pre.png").replace(".jpg", "_pre.jpg").replace(".jpeg", "_pre.jpeg")
+                _preprocess(src, dst, mode=preprocess_mode)
+                processed_pngs.append(dst)
+        else:
+            processed_pngs = raw_pngs
+
+        # ── 3. Audiveris → MXL ──────────────────────────────────────
+        mxl_paths = []
+        for i, png in enumerate(processed_pngs):
+            _prog(0.25 + 0.60 * i / total, f"Audiveris OMR 중... ({i+1}/{total}페이지)")
+            def _auv_line(line: str, _i=i, _total=total) -> None:
+                # Audiveris 로그에서 의미있는 줄만 추려 progress 설명 업데이트
+                if any(k in line for k in ("INFO", "WARN", "Sheet", "Page", "System", "Measure", "Staff")):
+                    short = line.split("]")[-1].strip()[:80]
+                    _prog(0.25 + 0.60 * _i / _total, f"[{_i+1}/{_total}] {short}")
+            mxl_path, err = _run_audiveris(png, str(mxl_dir), on_line=_auv_line)
+            if mxl_path:
+                mxl_paths.append(mxl_path)
+            else:
+                warnings.append(f"MXL 생성 실패 (스킵): {Path(png).name} — {err}")
+
+        if not mxl_paths:
+            warn_detail = "\n".join(warnings)
+            raise RuntimeError(f"변환된 페이지가 없습니다. 모든 페이지에서 Audiveris 실패.\n{warn_detail}")
+
+        # ── 3-b. XML 자동 교정 (선택적) ─────────────────────────────
+        mxl_paths_for_convert = mxl_paths
+
+        if correct_xml and mxl_paths:
+            try:
+                from core.xml_corrector import XMLCorrector
+            except ImportError as _ie:
+                warnings.append(f"[교정 스킵] xml_corrector 의존성 없음: {_ie}")
+            else:
+                _prog(0.85, "XML 자동 교정 중...")
+                corrector = XMLCorrector()
+                corrected: list[str] = []
+
+                for i, mxl_p in enumerate(mxl_paths):
+                    _prog(
+                        0.85 + 0.03 * i / len(mxl_paths),
+                        f"XML 교정 중... ({i+1}/{len(mxl_paths)})",
+                    )
+                    stem = Path(mxl_p).stem
+                    # 업스케일/전처리 접미사 제거 → 원본 PNG stem 추출
+                    import re as _re
+                    _m = _re.match(r"(page_\d+)", stem)
+                    base_stem = _m.group(1) if _m else stem
+                    raw_png = next(
+                        (p for p in orig_pngs if Path(p).stem == base_stem),
+                        None,
+                    )
+                    if raw_png is None:
+                        warnings.append(f"[교정 스킵] {stem}: 원본 PNG 없음")
+                        continue
+                    out_xml = str(mxl_dir / f"{stem}_corrected.xml")
+                    try:
+                        res = corrector.correct(mxl_p, raw_png, out_xml)
+                        corrected.append(out_xml)
+                        warnings += [f"[교정] {w}" for w in res.warnings]
+                        warnings.append(
+                            f"[교정] {stem}: {res.measures_corrected}개 수정, "
+                            f"{res.measures_fallback}개 fallback"
+                        )
+                    except Exception as _e:
+                        warnings.append(f"[교정 실패] {stem}: {_e}")
+
+                if corrected:
+                    mxl_paths_for_convert = corrected
+
+        # ── 4. MXL → MML (전체 화음, N파트) ────────────────────────
+        _prog(0.88, "MML 변환 중 (전체 화음)...")
+        tracks, total_dur, tempo = convert_files_all_notes(mxl_paths_for_convert)
+        all_notes_text = format_output_n(tracks, total_dur, tempo)
+
+        # ── 5. MXL → MML (3파트) ────────────────────────────────────
+        _prog(0.94, "MML 변환 중 (3파트)...")
+        melody, chord1, bass, tempo3 = convert_files(mxl_paths_for_convert)
+        three_part_text = format_output(melody, chord1, bass, tempo3)
+
+        # ── 6. 결합 ─────────────────────────────────────────────────
+        _prog(0.99, "결과 정리 중...")
+        combined = all_notes_text.rstrip() + SEP + three_part_text.rstrip() + "\n"
+
+        xml_paths = [str(p).replace(".mxl", ".xml")
+                     for p in [Path(m) for m in mxl_paths]
+                     if Path(str(p).replace(".mxl", ".xml")).exists()]
+
+    except Exception:
+        shutil.rmtree(work_dir, ignore_errors=True)
+        raise
+
+    return combined, mxl_paths, xml_paths, warnings

core/measure_verifier.py

@@ -0,0 +1,916 @@
+"""
+measure_verifier.py — CV 기반 마디별 음표 검증 및 피치 교정
+단독 구현: cv2, numpy, xml.etree 외 외부 core 모듈 의존 없음
+"""
+
+import os
+import re
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+from typing import Optional
+
+import cv2
+import numpy as np
+
+# ─────────────────────────────────────────────────────────
+# YOLOv8 notehead 모델 (학습 완료 후 자동 로드)
+# ─────────────────────────────────────────────────────────
+_YOLO_MODEL = None
+_YOLO_MODEL_PATH = os.path.join(
+    os.path.dirname(__file__), '..', 'models', 'notehead_yolo', 'weights', 'best.pt'
+)
+
+
+def _load_yolo_model():
+    global _YOLO_MODEL
+    if _YOLO_MODEL is None:
+        from ultralytics import YOLO
+        _YOLO_MODEL = YOLO(_YOLO_MODEL_PATH)
+    return _YOLO_MODEL
+
+
+# ─────────────────────────────────────────────────────────
+# Data Classes
+# ─────────────────────────────────────────────────────────
+
+@dataclass
+class NoteInfo:
+    pitch: str        # "C4", "G5", "rest", "?"
+    duration: float   # quarter note = 1.0
+    is_chord: bool = False
+
+
+@dataclass
+class TimePoint:
+    notes: list        # list[NoteInfo]
+    quarter_length: float  # beat offset within measure
+
+
+@dataclass
+class MeasureInfo:
+    number: int
+    timepoints: list   # list[TimePoint]
+    total_beats: float = 0.0  # 이 마디의 총 박자 수 (quarter note = 1)
+
+
+@dataclass
+class NoteHead:
+    x: int
+    y: int
+    w: int
+    h: int
+    filled: bool
+
+
+@dataclass
+class Cluster:
+    x_center: float
+    noteheads: list    # list[NoteHead]
+
+
+@dataclass
+class VerifyResult:
+    status: str        # "OK" or "FLAG"
+    cv_count: int
+    xml_count: int
+    diff: int
+
+
+@dataclass
+class MeasureResult:
+    number: int
+    verify: VerifyResult
+    corrected_timepoints: Optional[list] = None  # list[TimePoint]; None if FLAG
+    cv_clusters: list = field(default_factory=list)
+
+
+@dataclass
+class VerificationReport:
+    measures: list     # list[MeasureResult]
+    ok_count: int = 0
+    flag_count: int = 0
+
+
+# ─────────────────────────────────────────────────────────
+# 0. 내부 CV 유틸
+# ─────────────────────────────────────────────────────────
+
+def _to_binary_inv(arr: np.ndarray) -> np.ndarray:
+    """BGR/GRAY → 이진화 반전 (흰=전경, 검=배경)."""
+    if arr.ndim == 3:
+        gray = cv2.cvtColor(arr, cv2.COLOR_BGR2GRAY)
+    else:
+        gray = arr
+    _, binary = cv2.threshold(gray, 180, 255, cv2.THRESH_BINARY_INV)
+    return binary
+
+
+def _remove_staff_lines(binary: np.ndarray) -> np.ndarray:
+    """수평 모폴로지로 5선 제거."""
+    kernel_w = max(30, binary.shape[1] // 5)
+    horiz = cv2.getStructuringElement(cv2.MORPH_RECT, (kernel_w, 1))
+    lines = cv2.morphologyEx(binary, cv2.MORPH_OPEN, horiz)
+    return cv2.subtract(binary, lines)
+
+
+def _detect_staff_lines_y(binary: np.ndarray) -> list:
+    """
+    수평 투영으로 5선 y좌표 검출.
+    반환: y좌표 리스트 (위→아래 정렬). 검출 실패 시 빈 리스트.
+    """
+    h, w = binary.shape
+    proj = binary.sum(axis=1)
+    threshold = w * 255 * 0.3  # 행 너비의 30% 이상
+
+    in_line = False
+    groups = []
+    start = 0
+    for y in range(h):
+        if proj[y] >= threshold:
+            if not in_line:
+                start = y
+                in_line = True
+        else:
+            if in_line:
+                groups.append((start + y) // 2)
+                in_line = False
+    if in_line:
+        groups.append((start + h) // 2)
+
+    if len(groups) < 5:
+        return []
+    # 여러 시스템이 있을 경우 첫 5개만
+    return groups[:5]
+
+
+def _detect_staff_spacing(arr: np.ndarray) -> float:
+    """
+    수평 투영으로 5선 간격(픽셀) 반환.
+    검출 실패 시 이미지 높이 / 8 반환.
+    """
+    binary = _to_binary_inv(arr)
+    lines = _detect_staff_lines_y(binary)
+    if len(lines) < 2:
+        return arr.shape[0] / 8.0
+    spacings = [lines[i + 1] - lines[i] for i in range(len(lines) - 1)]
+    return float(np.median(spacings))
+
+
+def _detect_systems(inv: np.ndarray) -> list:
+    """
+    오선 라인 기반 시스템 y범위 검출.
+    오선(staff line): 행 너비의 30% 이상이 전경 픽셀 → 강한 수평선
+    이런 라인들을 그룹핑해 각 시스템의 y1, y2 반환.
+    반환: list of (y1, y2) tuples.
+    """
+    h, w = inv.shape
+    proj = inv.sum(axis=1).astype(float)
+
+    # 오선 라인 기준: 행 너비 30% 이상 (악보 전체를 가로지르는 선만 포함)
+    staff_threshold = w * 255 * 0.30
+
+    # 오선 행 마킹
+    is_staff_row = proj >= staff_threshold
+
+    # 인접한 오선 행을 묶어 "staff line band" 생성
+    bands = []  # [(y_center), ...]
+    in_band = False
+    band_start = 0
+    for y in range(h):
+        if is_staff_row[y]:
+            if not in_band:
+                band_start = y
+                in_band = True
+        else:
+            if in_band:
+                bands.append((band_start + y) // 2)
+                in_band = False
+    if in_band:
+        bands.append((band_start + h) // 2)
+
+    if len(bands) < 5:
+        # staff line 검출 실패 → 낮은 threshold로 재시도 (노이즈 많은 이미지)
+        fallback_thr = w * 255 * 0.10
+        active = proj >= fallback_thr
+        gap_thr = max(80, h // 15)
+        min_h = max(80, h // 20)
+        systems = []
+        in_sys = False
+        sys_start = 0
+        gap_count = 0
+        for y in range(h):
+            if active[y]:
+                if not in_sys:
+                    sys_start = y
+                    in_sys = True
+                gap_count = 0
+            else:
+                if in_sys:
+                    gap_count += 1
+                    if gap_count > gap_thr:
+                        sys_end = y - gap_count
+                        if sys_end - sys_start >= min_h:
+                            systems.append((sys_start, sys_end))
+                        in_sys = False
+                        gap_count = 0
+        if in_sys and h - 1 - sys_start >= min_h:
+            systems.append((sys_start, h - 1))
+        return systems
+
+    # staff line band 간격(spacing) 추정 — 인접 5개 밴드의 median 간격
+    spacings = [bands[i + 1] - bands[i] for i in range(min(9, len(bands) - 1))]
+    staff_spacing = float(np.median(spacings))
+
+    # 같은 시스템에 속하는 band 그룹핑
+    # 피아노 그랜드 스태프: treble↔bass 갭 ≈ 8×staff_spacing → 10배로 여유 확보
+    # inter-system 갭은 보통 15×spacing 이상이므로 안전
+    group_threshold = staff_spacing * 10
+    groups = [[bands[0]]]
+    for b in bands[1:]:
+        if b - groups[-1][-1] <= group_threshold:
+            groups[-1].append(b)
+        else:
+            groups.append([b])
+
+    # 각 그룹의 y범위 → 시스템 범위 (여백 추가)
+    margin = max(5, int(staff_spacing * 0.5))
+    systems = []
+    for g in groups:
+        if len(g) < 2:
+            continue  # 단일 라인은 오선 시스템이 아님
+        y1 = max(0, g[0] - margin)
+        y2 = min(h - 1, g[-1] + margin)
+        systems.append((y1, y2))
+
+    return systems
+
+
+def _detect_barlines(inv: np.ndarray, y1: int, y2: int) -> list:
+    """
+    수직 투영으로 마디선 x좌표 검출.
+    반환: barline x좌표 리스트 (정렬됨).
+    barline 조건: 시스템 높이의 50% 이상 채움 + 피크 너비 < 20px
+    """
+    crop = inv[y1:y2, :]
+    if crop.shape[0] < 10 or crop.shape[1] < 10:
+        return []
+
+    h_crop, w_crop = crop.shape
+    proj = crop.sum(axis=0).astype(float)
+
+    # barline은 시스템 높이의 70% 이상을 채우는 수직선
+    # (treble+bass 개별 줄기가 각각 ~30% → 합 ~60% < 70% → 차단)
+    threshold = h_crop * 255 * 0.70
+
+    # 좌우 여백(음자리표, 괄호 영역) 무시: 너비의 8% ~ (끝-5px)
+    left_margin = int(w_crop * 0.08)
+    right_margin = w_crop - 5
+
+    barlines = []
+    in_peak = False
+    peak_start = 0
+    for x in range(left_margin, right_margin):
+        if proj[x] >= threshold:
+            if not in_peak:
+                peak_start = x
+                in_peak = True
+        else:
+            if in_peak:
+                peak_width = x - peak_start
+                # 진짜 barline은 얇음 (너비 < 20px)
+                if peak_width < 20:
+                    barlines.append((peak_start + x) // 2)
+                in_peak = False
+    if in_peak and (w_crop - peak_start) < 20:
+        barlines.append((peak_start + right_margin) // 2)
+
+    # 너무 가까운 barline 제거 (최소 간격: 너비의 10%)
+    min_spacing = max(50, w_crop // 10)
+    filtered = []
+    for bl in barlines:
+        if not filtered or bl - filtered[-1] >= min_spacing:
+            filtered.append(bl)
+
+    return filtered
+
+
+def _detect_noteheads_cv(arr: np.ndarray, left_skip_px: int = 0) -> list:
+    """
+    CC(connected components) 기반 notehead 검출 — fallback용.
+    YOLOv8 모델이 없을 때 자동으로 사용됨.
+    """
+    binary = _to_binary_inv(arr)
+
+    spacing = _detect_staff_spacing(binary)
+    spacing = max(spacing, 4.0)
+
+    min_w    = max(4,  int(spacing * 0.7))
+    max_w    = max(min_w + 1, int(spacing * 1.6))
+    min_h    = max(3,  int(spacing * 0.7))
+    max_h    = max(min_h + 1, int(spacing * 1.1))
+    min_area = max(10, int(spacing ** 2 * 0.4))
+    max_area = max(min_area + 1, int(spacing ** 2 * 3.0))
+    beam_max_h = int(spacing * 2.2)
+
+    no_lines = _remove_staff_lines(binary)
+    n, labels, stats, centroids = cv2.connectedComponentsWithStats(no_lines, connectivity=8)
+
+    noteheads = []
+    for i in range(1, n):
+        bx, by, bw, bh, area = stats[i]
+        cx = int(centroids[i][0])
+
+        if (min_area <= area <= max_area and
+                min_w <= bw <= max_w and
+                min_h <= bh <= max_h and
+                0.5 <= bw / bh <= 1.8):
+            if cx >= left_skip_px:
+                cy = int(centroids[i][1])
+                fill_ratio = area / (bw * bh)
+                noteheads.append(NoteHead(cx, cy, bw, bh, fill_ratio > 0.42))
+            continue
+
+        if (area > min_area and bw > max_w and min_h <= bh <= beam_max_h):
+            comp_mask = (labels[by:by + bh, bx:bx + bw] == i).astype(np.uint8)
+            col_proj = comp_mask.sum(axis=0).astype(float)
+            max_proj = col_proj.max()
+            if max_proj > 0:
+                peak_thresh = max_proj * 0.65
+                in_pk = False
+                pk_start = 0
+                end = len(col_proj)
+                for xi in range(end + 1):
+                    above = (xi < end and col_proj[xi] >= peak_thresh)
+                    if above and not in_pk:
+                        pk_start = xi
+                        in_pk = True
+                    elif not above and in_pk:
+                        pk_w = xi - pk_start
+                        if min_w <= pk_w <= max_w + 6:
+                            px_cx = bx + (pk_start + xi) // 2
+                            if px_cx >= left_skip_px:
+                                row_proj = comp_mask[:, pk_start:xi].sum(axis=1)
+                                px_cy = by + int(np.argmax(row_proj)) if row_proj.sum() > 0 else by + bh // 2
+                                ph = min(bh, int(spacing * 1.1))
+                                noteheads.append(NoteHead(px_cx, px_cy, pk_w, ph, True))
+                        in_pk = False
+
+    row_bin = max(1, int(spacing * 1.5))
+    noteheads.sort(key=lambda nh: (nh.y // row_bin, nh.x))
+    return noteheads
+
+
+def _detect_noteheads(arr: np.ndarray, left_skip_px: int = 0) -> list:
+    """
+    notehead 검출 진입점 (마디 crop 단위 호출용 — fallback CC 방식).
+    전체 페이지에서 YOLO 검출이 필요하면 _detect_noteheads_full_page() 사용.
+    """
+    return _detect_noteheads_cv(arr, left_skip_px)
+
+
+def _detect_noteheads_full_page(img: np.ndarray) -> list:
+    """
+    전체 페이지 이미지에 YOLO를 한 번 실행해 모든 notehead 반환.
+    반환: list of NoteHead (페이지 절대 좌표).
+    YOLO 모델 없으면 빈 리스트 반환 → run_verification에서 CC 방식으로 대체.
+    """
+    if not os.path.exists(_YOLO_MODEL_PATH):
+        return []
+    try:
+        model = _load_yolo_model()
+        results = model(img, imgsz=1280, conf=0.25, verbose=False)[0]
+    except Exception:
+        return []
+
+    binary = _to_binary_inv(img)
+    spacing = max(_detect_staff_spacing(img), 4.0)
+    noteheads = []
+    for box in results.boxes:
+        x1, y1, x2, y2 = box.xyxy[0].tolist()
+        cx = int((x1 + x2) / 2)
+        cy = int((y1 + y2) / 2)
+        bw = int(x2 - x1)
+        bh = int(y2 - y1)
+        roi = binary[max(0, int(y1)):max(1, int(y2)), max(0, int(x1)):max(1, int(x2))]
+        fill_ratio = roi.sum() / (255 * roi.size) if roi.size > 0 else 0.5
+        noteheads.append(NoteHead(cx, cy, bw, bh, fill_ratio > 0.42))
+
+    row_bin = max(1, int(spacing * 1.5))
+    noteheads.sort(key=lambda nh: (nh.y // row_bin, nh.x))
+    return noteheads
+
+
+# ─────────────────────────────────────────────────────────
+# 1. MusicXML 파싱
+# ─────────────────────────────────────────────────────────
+
+def _parse_pitch(note_el) -> str:
+    """음표 element에서 피치 문자열 추출. rest이면 'rest' 반환."""
+    if note_el.find('rest') is not None:
+        return 'rest'
+    pitch_el = note_el.find('pitch')
+    if pitch_el is None:
+        return 'rest'
+    step = pitch_el.findtext('step', 'C')
+    octave = pitch_el.findtext('octave', '4')
+    alter_text = pitch_el.findtext('alter', '0')
+    try:
+        alter = int(float(alter_text))
+    except ValueError:
+        alter = 0
+    suffix = '#' if alter == 1 else ('b' if alter == -1 else '')
+    return f"{step}{suffix}{octave}"
+
+
+def parse_xml_measures(xml_str: str) -> list:
+    """
+    MusicXML string → list[MeasureInfo]
+    첫 번째 파트의 마디별 음표를 파싱.
+    Audiveris가 복수의 시각적 마디를 하나의 XML 마디로 병합하는 경우
+    박자 수 기준으로 자동 분할한다 (예: 8��� 마디 → 4박짜리 2개).
+    """
+    xml_clean = re.sub(r'\s+xmlns[^"]*"[^"]*"', '', xml_str)
+
+    try:
+        root = ET.fromstring(xml_clean)
+    except ET.ParseError:
+        return []
+
+    parts = root.findall('.//part')
+    if not parts:
+        return []
+
+    # 첫 번째 파트만 사용: 멀티파트 악보에서 각 시스템(행)은 첫 파트(P.I 등)에 대응
+    # 전체 파트 합산 시 XML count 과대 계산 → 중복 시스템 제거 후 첫 파트와 비교
+    parts = parts[:1]
+
+    # measure_number → beat → list[NoteInfo]
+    from collections import defaultdict
+    all_measure_beats: dict = defaultdict(lambda: defaultdict(list))
+    measure_order: list = []  # 마디 번호 순서 유지
+    measure_max_beats: dict = {}  # mn → 마디 총 박자 수 (첫 파트 기준)
+
+    divisions = 1
+    beats_per_measure = 4.0
+
+    for pi, part in enumerate(parts):
+        divisions = 1
+        beats_per_measure = 4.0
+
+        for measure_el in part.findall('measure'):
+            number_str = measure_el.get('number', '0')
+            try:
+                mn = int(number_str)
+            except ValueError:
+                mn = 0
+            if mn not in all_measure_beats:
+                measure_order.append(mn)
+
+            attrs = measure_el.find('attributes')
+            if attrs is not None:
+                div_el = attrs.find('divisions')
+                if div_el is not None and div_el.text:
+                    divisions = int(div_el.text)
+                time_el = attrs.find('time')
+                if time_el is not None:
+                    try:
+                        beats = float(time_el.findtext('beats', '4'))
+                        beat_type = float(time_el.findtext('beat-type', '4'))
+                        beats_per_measure = beats * (4.0 / beat_type)
+                    except (ValueError, ZeroDivisionError):
+                        pass
+
+            current_beat = 0.0
+            last_beat = 0.0
+            max_beat_this = 0.0  # 이 마디에서 도달한 최대 박자
+
+            for child in measure_el:
+                tag = child.tag
+                if tag == 'note':
+                    is_chord = child.find('chord') is not None
+                    is_grace = child.find('grace') is not None
+                    dur_el = child.find('duration')
+                    duration = 0.0
+                    if dur_el is not None and dur_el.text and not is_grace:
+                        try:
+                            duration = int(dur_el.text) / divisions
+                        except (ValueError, ZeroDivisionError):
+                            pass
+                    pitch = _parse_pitch(child)
+                    note_beat = last_beat if is_chord else current_beat
+                    all_measure_beats[mn][round(note_beat, 6)].append(
+                        NoteInfo(pitch=pitch, duration=duration, is_chord=is_chord)
+                    )
+                    if not is_chord and not is_grace:
+                        last_beat = current_beat
+                        current_beat += duration
+                        max_beat_this = max(max_beat_this, current_beat)
+                elif tag == 'backup':
+                    dur_el = child.find('duration')
+                    if dur_el is not None and dur_el.text:
+                        try:
+                            current_beat -= int(dur_el.text) / divisions
+                            current_beat = max(0.0, current_beat)
+                        except (ValueError, ZeroDivisionError):
+                            pass
+                elif tag == 'forward':
+                    dur_el = child.find('duration')
+                    if dur_el is not None and dur_el.text:
+                        try:
+                            current_beat += int(dur_el.text) / divisions
+                            max_beat_this = max(max_beat_this, current_beat)
+                        except (ValueError, ZeroDivisionError):
+                            pass
+
+            # 첫 파트에서만 박자 수 기록 (모든 파트 동일하므로)
+            if pi == 0 or mn not in measure_max_beats:
+                measure_max_beats[mn] = max(measure_max_beats.get(mn, 0.0), max_beat_this)
+
+    # all_measure_beats → list[MeasureInfo] 변환
+    # Audiveris가 여러 시각적 마디를 하나로 병합한 경우 (total_beats > beats_per_measure * 1.5)
+    # beats_per_measure 단위로 분할한다.
+    measures = []
+    seq = 1
+    for mn in sorted(set(measure_order)):
+        beat_map = all_measure_beats[mn]
+        timepoints_all = [
+            TimePoint(notes=beat_map[b], quarter_length=b)
+            for b in sorted(beat_map.keys())
+        ]
+        total_beats = measure_max_beats.get(mn, beats_per_measure)
+
+        if total_beats > beats_per_measure * 1.5 and beats_per_measure > 0:
+            # 분할 필요: beats_per_measure 간격으로 서브마디 생성
+            n_sub = max(2, round(total_beats / beats_per_measure))
+            sub_beats = beats_per_measure
+            for sub_i in range(n_sub):
+                lo = sub_i * sub_beats
+                hi = lo + sub_beats
+                sub_tps = [
+                    TimePoint(notes=tp.notes, quarter_length=tp.quarter_length - lo)
+                    for tp in timepoints_all
+                    if lo <= tp.quarter_length < hi
+                ]
+                measures.append(MeasureInfo(number=seq, timepoints=sub_tps, total_beats=sub_beats))
+                seq += 1
+        else:
+            measures.append(MeasureInfo(number=seq, timepoints=timepoints_all, total_beats=total_beats))
+            seq += 1
+
+    return measures
+
+
+# ─────────────────────────────────────────────────────────
+# 2. Notehead 클러스터링
+# ─────────────────────────────────────────────────────────
+
+def cluster_noteheads(noteheads: list, staff_spacing_px: float) -> list:
+    """
+    notehead x좌표 기준 클러스터링.
+    threshold = staff_spacing_px * 0.5 이내면 같은 타임포인트.
+    반환: list[Cluster] (x_center 순 정렬)
+    """
+    if not noteheads:
+        return []
+
+    threshold = max(staff_spacing_px * 0.8, 8.0)
+    sorted_nh = sorted(noteheads, key=lambda nh: nh.x)
+
+    clusters = []
+    group = [sorted_nh[0]]
+
+    for nh in sorted_nh[1:]:
+        if nh.x - group[-1].x <= threshold:
+            group.append(nh)
+        else:
+            x_center = sum(n.x for n in group) / len(group)
+            clusters.append(Cluster(x_center=x_center, noteheads=list(group)))
+            group = [nh]
+
+    if group:
+        x_center = sum(n.x for n in group) / len(group)
+        clusters.append(Cluster(x_center=x_center, noteheads=list(group)))
+
+    return clusters
+
+
+# ─────────────────────────────────────────────────────────
+# 3. 마디별 검증
+# ─────────────────────────────────────────────────────────
+
+def verify_measure(cv_clusters: list, xml_timepoints: list) -> VerifyResult:
+    """
+    CV 클러스터 수 vs XML 타임포인트 수 비교.
+    rest 전용 타임포인트는 xml_timepoints에서 제외하고 넘겨야 함.
+    """
+    cv_count = len(cv_clusters)
+    xml_count = len(xml_timepoints)
+    diff = abs(cv_count - xml_count)
+    status = "OK" if diff <= 1 else "FLAG"
+    return VerifyResult(status=status, cv_count=cv_count, xml_count=xml_count, diff=diff)
+
+
+# ─────────────────────────────────────────────────────────
+# 4. 피치 추정
+# ─────────────────────────────────────────────────────────
+
+_DIATONIC_STEPS = ['C', 'D', 'E', 'F', 'G', 'A', 'B']
+_DIATONIC_SEMITONES = {'C': 0, 'D': 2, 'E': 4, 'F': 5, 'G': 7, 'A': 9, 'B': 11}
+
+# 다이아토닉 스텝 → 피치 문자열 (E4 = step 0 기준)
+# E는 CDEFGAB에서 인덱스 2, 옥타브 4
+_E4_TOTAL_INDEX = 4 * 7 + 2  # octave*7 + step_index
+
+
+def _diatonic_to_pitch(steps_from_ref: int, ref_total_index: int) -> str:
+    """
+    ref_total_index 기준 다이아토닉 단계 → 피치 문자열.
+    total_index = octave * 7 + step_index (CDEFGAB 인덱스)
+    """
+    total = ref_total_index + steps_from_ref
+    octave, step_idx = divmod(total, 7)
+    if step_idx < 0:
+        step_idx += 7
+        octave -= 1
+    step = _DIATONIC_STEPS[step_idx % 7]
+    return f"{step}{octave}"
+
+
+def estimate_pitch_from_y(y_px: float, staff_bands: list, clef: str = 'treble') -> str:
+    """
+    staff_bands: 5개 y좌표 (위→아래 = line5..line1 for treble).
+    clef: 'treble' | 'bass'
+    반환: 피치 문자열 e.g. "C4", "G5", "?" (검출 실패)
+    """
+    if len(staff_bands) < 5:
+        return '?'
+
+    spacing = (staff_bands[4] - staff_bands[0]) / 4.0
+    if spacing <= 0:
+        return '?'
+
+    half_spacing = spacing / 2.0
+
+    if clef == 'treble':
+        # 아래 선(staff_bands[4]) = E4, ref_total_index = 4*7+2 = 30
+        ref_y = staff_bands[4]
+        ref_total = _E4_TOTAL_INDEX
+    elif clef == 'bass':
+        # 아래 선 = G2, total_index = 2*7+4 = 18
+        ref_y = staff_bands[4]
+        ref_total = 2 * 7 + 4  # G2
+    else:
+        return '?'
+
+    dy = ref_y - y_px  # 양수 = 아래 선 위쪽 = 높은 음
+    steps = round(dy / half_spacing)
+    return _diatonic_to_pitch(steps, ref_total)
+
+
+# ──────────────────────────────────────────────────────��──
+# 5. 피치 교정
+# ─────────────────────────────────────────────────────────
+
+def _pitch_to_sort_key(pitch: str) -> int:
+    """피치 문자열 → 정렬 키. 'rest'/'?' → -999."""
+    if pitch in ('rest', '?'):
+        return -999
+    try:
+        step = pitch[0]
+        rest = pitch[1:]
+        alter = 0
+        if '#' in rest:
+            alter = 1
+            rest = rest.replace('#', '')
+        elif 'b' in rest:
+            alter = -1
+            rest = rest.replace('b', '')
+        octave = int(rest)
+        return octave * 12 + _DIATONIC_SEMITONES.get(step, 0) + alter
+    except (ValueError, IndexError):
+        return -999
+
+
+def correct_measure_pitches(
+    cv_clusters: list,
+    xml_timepoints: list,
+    staff_bands: list,
+    clef: str = 'treble',
+) -> list:
+    """
+    개수가 일치하는 마디에서 CV y좌표로 각 음표 피치 교정.
+    cv_clusters와 xml_timepoints는 같은 길이이어야 함.
+    반환: 교정된 list[TimePoint]
+    """
+    corrected = []
+    for cluster, tp in zip(cv_clusters, xml_timepoints):
+        # notehead를 y 오름차순 (위→아래 = 높음→낮음)으로 정렬
+        sorted_nhs = sorted(cluster.noteheads, key=lambda nh: nh.y)
+        # xml 음표를 피치 내림차순 (높은 음 먼저)으로 정렬
+        sorted_notes = sorted(
+            tp.notes,
+            key=lambda ni: _pitch_to_sort_key(ni.pitch),
+            reverse=True,
+        )
+
+        new_notes = []
+        for idx, note in enumerate(sorted_notes):
+            if note.pitch == 'rest':
+                new_notes.append(NoteInfo(pitch='rest', duration=note.duration, is_chord=note.is_chord))
+            elif idx < len(sorted_nhs):
+                est = estimate_pitch_from_y(sorted_nhs[idx].y, staff_bands, clef)
+                new_notes.append(NoteInfo(pitch=est, duration=note.duration, is_chord=note.is_chord))
+            else:
+                new_notes.append(note)
+
+        corrected.append(TimePoint(notes=new_notes, quarter_length=tp.quarter_length))
+
+    return corrected
+
+
+# ─────────────────────────────────────────────────────────
+# 6. 전체 파이프라인
+# ─────────────────────────────────────────────────────────
+
+def run_verification(png_path: str, xml_str: str) -> VerificationReport:
+    """
+    원본 PNG + MusicXML string → 마디별 검증/교정 결과 반환.
+
+    파이프라인:
+    1. 이미지 로드 & 이진화
+    2. 시스템(악단) y범위 검출
+    3. 시스템별 마디선 x좌표 검출 → 마디 crop
+    4. MusicXML 파싱
+    5. 마디별: notehead 검출 → 클러스터링 → verify → 피치 교정
+    6. VerificationReport 반환
+    """
+    img = cv2.imread(png_path)
+    if img is None:
+        raise FileNotFoundError(f"이미지를 열 수 없음: {png_path}")
+
+    inv = _to_binary_inv(img)
+    h_img, w_img = inv.shape
+    min_measure_width = max(20, w_img // 25)
+
+    # YOLO 모델이 있으면 전체 페이지에 한 번 실행 (crop 단위 X)
+    page_noteheads = _detect_noteheads_full_page(img)
+    use_yolo = len(page_noteheads) > 0
+
+    systems = _detect_systems(inv)
+    if not systems:
+        return VerificationReport(measures=[], ok_count=0, flag_count=0)
+
+    # 같은 행의 중복 시스템 제거 (2대 피아노 등 멀티파트 악보 대응)
+    # 기준 높이: 전체 시스템 높이의 중앙값 (merged 시스템이 섞여도 단일 파트 높이 기준 유지)
+    if len(systems) > 1:
+        all_heights = [y2 - y1 for y1, y2 in systems]
+        all_heights_sorted = sorted(all_heights)
+        ref_h = all_heights_sorted[len(all_heights_sorted) // 2]  # 중앙값
+        # 단일 파트 높이에 맞게 조정: 중앙값이 너무 크면(merged) 최솟값 사용
+        min_h = all_heights_sorted[0]
+        if ref_h > min_h * 1.5:
+            ref_h = min_h
+
+        deduped = [systems[0]]
+        for i in range(1, len(systems)):
+            prev_y2 = deduped[-1][1]
+            ny1, ny2 = systems[i]
+            gap = ny1 - prev_y2
+            if gap >= ref_h * 0.7:
+                deduped.append((ny1, ny2))
+            # gap < 기준높이의 70% → 같은 행의 다른 파트, 스킵
+        systems = deduped
+
+    all_xml_measures = parse_xml_measures(xml_str)
+    measure_map = {m.number: m for m in all_xml_measures}
+
+    results: list = []
+    n_systems = len(systems)
+    n_xml = len(all_xml_measures)
+
+    # 시스템별 XML 마디 수 분배 (최대한 균등하게)
+    xml_per_sys: list = []
+    remaining_xml = n_xml
+    for si in range(n_systems):
+        remaining_sys = n_systems - si
+        n_this = max(1, round(remaining_xml / remaining_sys))
+        xml_per_sys.append(n_this)
+        remaining_xml -= n_this
+    # 남거나 부족한 경우 마지막 시스템에 조정
+    if xml_per_sys:
+        xml_per_sys[-1] += n_xml - sum(xml_per_sys)
+        xml_per_sys[-1] = max(1, xml_per_sys[-1])
+
+    measure_idx = 1
+
+    for si, (y1, y2) in enumerate(systems):
+        barline_xs = _detect_barlines(inv, y1, y2)
+        n_xml_this = xml_per_sys[si] if si < len(xml_per_sys) else 1
+
+        if len(barline_xs) < 2:
+            measure_boundaries = [(0, w_img)]
+        else:
+            # 너무 가까운 barline 제거
+            filtered_bl = [barline_xs[0]]
+            for bl in barline_xs[1:]:
+                if bl - filtered_bl[-1] >= min_measure_width:
+                    filtered_bl.append(bl)
+
+            # open_x: 시스템 시작 = 이미지 왼쪽 엣지
+            # 첫 번째 barline이 왼쪽 여백(너비의 15%) 이내에 있으면 시스템 엣지/클레프 영역으로 간주해 스킵
+            left_edge_threshold = w_img * 0.15
+            if filtered_bl[0] < left_edge_threshold:
+                # 첫 barline이 클레프/조표 영역 끝 → 스킵
+                open_x = filtered_bl[1] if len(filtered_bl) >= 2 else filtered_bl[0]
+                close_x = filtered_bl[-1]
+                internal = filtered_bl[2:-1] if len(filtered_bl) >= 3 else []
+            else:
+                # 모든 barline이 실제 마디선 → 이미지 왼쪽을 시작점으로
+                open_x = 0
+                close_x = filtered_bl[-1]
+                internal = filtered_bl[:-1]
+
+            n_internal_needed = n_xml_this - 1
+
+            if n_internal_needed <= 0 or not internal:
+                selected = []
+            elif n_internal_needed >= len(internal):
+                selected = internal
+            else:
+                # XML 마디 박자 수 기반 가중 예상 위치 계산
+                # measure_idx 기준으로 이 시스템에 할당된 XML 마디들의 박자 비율 사용
+                total_w = close_x - open_x
+                sys_measures = all_xml_measures[measure_idx - 1: measure_idx - 1 + n_xml_this]
+                durations = [max(m.total_beats, 1.0) for m in sys_measures]
+                total_dur = sum(durations)
+                if total_dur > 0:
+                    cumul = [sum(durations[:k + 1]) for k in range(len(durations) - 1)]
+                    expected = [open_x + total_w * c / total_dur for c in cumul]
+                else:
+                    expected = [open_x + total_w * (k + 1) / (n_internal_needed + 1)
+                                for k in range(n_internal_needed)]
+                selected = []
+                used = set()
+                for exp_x in expected:
+                    best = min((bl for bl in internal if id(bl) not in used),
+                               key=lambda b: abs(b - exp_x),
+                               default=None)
+                    if best is not None:
+                        selected.append(best)
+                        used.add(id(best))
+                selected = sorted(selected)
+
+            final_bl = [open_x] + selected + [close_x]
+            measure_boundaries = [(final_bl[i], final_bl[i + 1])
+                                  for i in range(len(final_bl) - 1)]
+
+        for mi, (x1, x2) in enumerate(measure_boundaries):
+            measure_crop = img[y1:y2, x1:x2]
+
+            if measure_crop.shape[0] < 10 or measure_crop.shape[1] < 10:
+                continue
+
+            xml_measure = measure_map.get(measure_idx)
+            if xml_measure is None:
+                measure_idx += 1
+                continue
+
+            # rest 전용 타임포인트 제외
+            xml_tps = [
+                tp for tp in xml_measure.timepoints
+                if any(n.pitch != 'rest' for n in tp.notes)
+            ]
+
+            # 마디 내 staff 정보 검출
+            crop_binary = _to_binary_inv(measure_crop)
+            staff_ys = _detect_staff_lines_y(crop_binary)
+            staff_spacing = _detect_staff_spacing(measure_crop)
+
+            if use_yolo:
+                # 페이지 절대 좌표에서 이 마디 범위(x1~x2, y1~y2) 내 notehead 필터링
+                # NoteHead 좌표를 crop 기준으로 변환
+                noteheads = [
+                    NoteHead(nh.x - x1, nh.y - y1, nh.w, nh.h, nh.filled)
+                    for nh in page_noteheads
+                    if x1 <= nh.x < x2 and y1 <= nh.y < y2
+                ]
+            else:
+                noteheads = _detect_noteheads(measure_crop)
+            clusters = cluster_noteheads(noteheads, staff_spacing)
+            verify = verify_measure(clusters, xml_tps)
+
+            corrected = None
+            if verify.status == "OK" and len(staff_ys) >= 5:
+                corrected = correct_measure_pitches(clusters, xml_tps, staff_ys)
+
+            results.append(MeasureResult(
+                number=measure_idx,
+                verify=verify,
+                corrected_timepoints=corrected,
+                cv_clusters=clusters,
+            ))
+            measure_idx += 1
+
+    ok_count = sum(1 for r in results if r.verify.status == "OK")
+    flag_count = sum(1 for r in results if r.verify.status == "FLAG")
+    return VerificationReport(measures=results, ok_count=ok_count, flag_count=flag_count)

core/mml_converter.py

@@ -0,0 +1,283 @@
+"""
+core/mml_converter.py
+
+NoteEvent 파트 리스트를 마비노기 MML 문자열로 변환.
+
+마비노기 MML 형식:
+  MML@<멜로디>,<화음1>,<화음2>;
+  음표: o<옥타브><음이름>[<길이>]  예) o4c4 = C4 4분음표, l4 선언 후 c
+  쉼표: r[<길이>]                  예) r4 = 4분음표 쉼표
+  기본길이: l<N>                   예) l8 → 이후 길이 생략 시 8분음표
+  옥타브 상승: >  하강: <
+  타이: c4&c8  (같은 음 연결)
+  템포: t<BPM>                     예) t120
+
+지원 길이 (4분음표 = duration 1.0):
+  1, 1., 2, 2., 4, 4., 8, 8., 16, 16., 32, 32., 64
+
+표현 불가 길이: & 타이로 그리디 분해 (예: 1.25박 → 4&16)
+잔여 오차 > 0.01박이면 근사 경고 발생.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+
+from .models import NoteEvent
+
+# MIDI 피치 → 음이름 (옥타브 없이)
+_PITCH_TO_NOTE_SHARP = {
+    0: "c", 1: "c+", 2: "d", 3: "d+", 4: "e",
+    5: "f", 6: "f+", 7: "g", 8: "g+", 9: "a",
+    10: "a+", 11: "b",
+}
+_PITCH_TO_NOTE_FLAT = {
+    0: "c", 1: "d-", 2: "d", 3: "e-", 4: "e",
+    5: "f", 6: "g-", 7: "g", 8: "a-", 9: "a",
+    10: "b-", 11: "b",
+}
+
+# (duration_in_beats, mml_length_string) — 반드시 내림차순 정렬
+_DURATION_MAP: list[tuple[float, str]] = [
+    (4.0,     "1"),    # 온음표
+    (3.0,     "1."),   # 점온음표
+    (2.0,     "2"),    # 2분음표
+    (1.5,     "2."),   # 점2분음표
+    (1.0,     "4"),    # 4분음표
+    (0.75,    "4."),   # 점4분음표
+    (0.5,     "8"),    # 8분음표
+    (0.375,   "8."),   # 점8분음표
+    (0.25,    "16"),   # 16분음표
+    (0.1875,  "16."),  # 점16분음표
+    (0.125,   "32"),   # 32분음표
+    (0.09375, "32."),  # 점32분음표
+    (0.0625,  "64"),   # 64분음표
+]
+
+
+def _mml_duration(lengths: list[str]) -> float:
+    """MML 길이 문자열 리스트의 실제 재생 박수 합산."""
+    dur_lookup = {mml_len: dur_val for dur_val, mml_len in _DURATION_MAP}
+    return sum(dur_lookup.get(l, 0.0) for l in lengths)
+
+
+def _duration_to_lengths(duration: float) -> tuple[list[str], bool]:
+    """
+    duration → MML 길이 문자열 리스트 (& 타이 그리디 분해 포함).
+
+    - 정확히 표현 가능 → 단일 원소, is_approximate=False
+    - 분해 가능      → 복수 원소, is_approximate=False
+    - 잔여 오차 > 0.01박 → is_approximate=True
+
+    4박(온음표)을 초과하는 duration은 온음표를 반복 사용하여 정확히 표현.
+
+    예:
+        1.0  → (["4"],        False)
+        0.75 → (["4."],       False)
+        1.25 → (["4", "16"],  False)   ← 1.0 + 0.25
+        8.0  → (["1","1"],    False)   ← 4.0 + 4.0
+    """
+    lengths: list[str] = []
+    remaining = duration
+
+    while remaining > 0.001:
+        found = False
+        for dur_val, mml_len in _DURATION_MAP:
+            if dur_val <= remaining + 0.001:
+                lengths.append(mml_len)
+                remaining -= dur_val
+                found = True
+                break
+        if not found:
+            break
+
+    if not lengths:
+        # 너무 작아 표현 불가 — 가장 가까운 값으로 근사
+        best = min(_DURATION_MAP, key=lambda x: abs(x[0] - duration))
+        return [best[1]], True
+
+    return lengths, remaining > 0.01
+
+
+def _midi_to_octave_note(pitch: int, prefer_sharps: bool = True) -> tuple[int, str]:
+    """MIDI 번호 → (옥타브, 음이름). 기준: o4c = C4 (MIDI 60)."""
+    octave = (pitch // 12) - 1
+    note_map = _PITCH_TO_NOTE_SHARP if prefer_sharps else _PITCH_TO_NOTE_FLAT
+    return octave, note_map[pitch % 12]
+
+
+def convert_part_to_mml(
+    notes: list[NoteEvent],
+    prefer_sharps: bool = True,
+) -> tuple[str, list[str]]:
+    """
+    단일 파트의 NoteEvent 리스트를 MML 본문 문자열로 변환.
+    (MML@ 와 ; 제외 — convert_parts_to_mml에서 조합)
+
+    최적화:
+      - l<N> : 가장 빈도 높은 길이를 기본값으로 선언, 이후 생략
+      - > / <: 1옥타브 이동 시 oN 대신 > / < 사용 (1글자 절감)
+      - &    : 표현 불가 길이를 타이로 분해
+
+    Returns:
+        (body_string, warnings)
+        빈 파트 → ("r1", [])
+    """
+    if not notes:
+        return "r1", []
+
+    sorted_notes = sorted(notes, key=lambda n: n.start)
+    warnings: list[str] = []
+
+    # MML에서 표현 가능한 최소 단위: 64분음표(0.0625박)
+    # 이보다 작은 gap은 표현 불가이므로 skip
+    _MIN_GAP = 0.0625 - 0.001
+
+    # ------------------------------------------------------------------
+    # Pass 1: l 최적화 — mml_pos 기반으로 gap 포함 길이 빈도 카운트
+    # ------------------------------------------------------------------
+    length_counter: Counter = Counter()
+    mml_pos_scan = 0.0
+    for note in sorted_notes:
+        gap = note.start - mml_pos_scan
+        if gap >= _MIN_GAP:
+            gap_lengths, _ = _duration_to_lengths(gap)
+            length_counter[gap_lengths[0]] += 1
+            mml_pos_scan += _mml_duration(gap_lengths)
+        dur_lengths, _ = _duration_to_lengths(note.duration)
+        length_counter[dur_lengths[0]] += 1
+        mml_pos_scan += _mml_duration(dur_lengths)
+
+    default_len = length_counter.most_common(1)[0][0] if length_counter else "4"
+
+    # ------------------------------------------------------------------
+    # Pass 2: 토큰 생성
+    #
+    # mml_pos: MML이 실제로 재생한 위치 (근사된 duration 누적)
+    # gap은 note.start - mml_pos 기준으로 계산 → 근사 오차가 다음 음에 누적되지 않음
+    # ------------------------------------------------------------------
+    tokens: list[str] = [f"l{default_len}"]
+    current_octave = -1
+    mml_pos = 0.0
+
+    def emit(name: str, lengths: list[str]) -> None:
+        """name('r' 또는 음이름) + lengths 리스트 → 토큰 추가 (& 분해 포함)."""
+        for i, lstr in enumerate(lengths):
+            tok = name if lstr == default_len else f"{name}{lstr}"
+            tokens.append(f"&{tok}" if i > 0 else tok)
+
+    for note in sorted_notes:
+        gap = note.start - mml_pos
+        if gap >= _MIN_GAP:
+            lengths, approx = _duration_to_lengths(gap)
+            if approx:
+                warnings.append(f"쉼표 길이 근사: {gap:.3f}박 → r{lengths[0]}")
+            emit("r", lengths)
+            mml_pos += _mml_duration(lengths)
+        # gap < _MIN_GAP: 표현 불가 미세 갭(주로 3잇단음표 반올림 오차) — skip
+
+        if note.pitch == 0:
+            lengths, approx = _duration_to_lengths(note.duration)
+            if approx:
+                warnings.append(f"쉼표 길이 근사: {note.duration:.3f}박 → r{lengths[0]}")
+            emit("r", lengths)
+            mml_pos += _mml_duration(lengths)
+        else:
+            octave, note_name = _midi_to_octave_note(note.pitch, prefer_sharps)
+            lengths, approx = _duration_to_lengths(note.duration)
+            if approx:
+                warnings.append(
+                    f"음표 길이 근사: pitch={note.pitch}, "
+                    f"{note.duration:.3f}박 → {note_name}{lengths[0]}"
+                )
+
+            # 옥타브 변경: 1칸 이동은 > / <, 2칸 이상이거나 처음은 oN
+            if octave != current_octave:
+                if current_octave == -1:
+                    tokens.append(f"o{octave}")
+                elif octave == current_octave + 1:
+                    tokens.append(">")
+                elif octave == current_octave - 1:
+                    tokens.append("<")
+                else:
+                    tokens.append(f"o{octave}")
+                current_octave = octave
+
+            emit(note_name, lengths)
+            mml_pos += _mml_duration(lengths)
+
+    return "".join(tokens), warnings
+
+
+def _split_to_lanes(notes: list[NoteEvent]) -> list[list[NoteEvent]]:
+    """
+    한 파트 내에서 시간상 겹치는 노트를 레인(sub-part)으로 분배.
+
+    노트를 start 순으로 정렬 후, 각 노트를 재생 가능한 첫 번째 레인에 배치.
+    재생 가능 조건: 레인의 마지막 노트 종료 시각 <= 현재 노트 시작 시각.
+    조건을 만족하는 레인이 없으면 새 레인 생성.
+
+    결과 레인의 각 노트는 서로 겹치지 않으므로 convert_part_to_mml이
+    처음부터 정확한 시간 계산으로 변환 가능.
+    """
+    lanes: list[list[NoteEvent]] = []
+    lane_end: list[float] = []  # 각 레인의 마지막 노트 종료 시각
+
+    for note in sorted(notes, key=lambda n: n.start):
+        placed = False
+        for i, end_time in enumerate(lane_end):
+            if note.start >= end_time - 0.001:
+                lanes[i].append(note)
+                lane_end[i] = note.start + note.duration
+                placed = True
+                break
+        if not placed:
+            lanes.append([note])
+            lane_end.append(note.start + note.duration)
+
+    return lanes
+
+
+def convert_parts_to_mml(
+    parts: list[list[NoteEvent]],
+    prefer_sharps: bool = True,
+    tempo: int = 0,
+) -> tuple[str, list[str], list[str]]:
+    """
+    파트 리스트 전체를 마비노기 MML로 변환.
+
+    각 파트 내 시간상 겹치는 노트는 레인으로 분리되어 별도 MML 파트로 출력.
+    각 레인은 시작 시각부터 쉼표를 삽입해 타이밍을 정확히 유지.
+
+    Args:
+        parts:         split_parts() 반환값 (파트별 NoteEvent 리스트)
+        prefer_sharps: True = 올림표(+), False = 내림표(-)
+        tempo:         BPM. 0이면 t 생략.
+
+    Returns:
+        (combined_mml, part_mmls, all_warnings)
+        combined_mml: "MML@[t<BPM>]<part1>,\n<part2>,\n..."  (참고용, 파트 수 제한 없음)
+        part_mmls:    ["MML@[t<BPM>]<part1>;", "MML@...", ...]  (파트별 개별 문자열)
+        all_warnings: 경고 목록
+    """
+    bodies: list[str] = []
+    all_warnings: list[str] = []
+
+    for part_idx, part_notes in enumerate(parts, start=1):
+        lanes = _split_to_lanes(part_notes)
+        for lane_idx, lane_notes in enumerate(lanes):
+            body, warnings = convert_part_to_mml(lane_notes, prefer_sharps)
+            bodies.append(body)
+            label = f"Part {part_idx}" if lane_idx == 0 else f"Part {part_idx}-{lane_idx + 1}"
+            for w in warnings:
+                all_warnings.append(f"{label}: {w}")
+
+    if not bodies:
+        bodies.append("r1")
+
+    tempo_str = f"t{tempo}" if tempo > 0 else ""
+    part_mmls = [f"MML@{tempo_str}{b};" for b in bodies]
+    combined = ",\n".join(bodies)
+    combined_mml = f"MML@{tempo_str}{combined};"
+
+    return combined_mml, part_mmls, all_warnings

core/models.py

@@ -0,0 +1,151 @@
+"""
+core/models.py
+
+내부 데이터 구조 정의.
+모든 core 모듈 간에 공유되는 데이터 클래스.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class NoteEvent:
+    """
+    악보에서 추출한 단일 음표/쉼표 이벤트.
+
+    pitch=0 이면 쉼표(rest)로 취급.
+    duration은 4분음표 기준의 비율 (예: 1.0 = 4분음표, 0.5 = 8분음표, 2.0 = 2분음표).
+    """
+    pitch: int          # MIDI 번호 (0 = rest, 60 = C4)
+    start: float        # 시작 시각 (4분음표 기준 beat)
+    duration: float     # 지속 시간 (4분음표 기준 beat)
+    staff: int = 1      # 보표 번호 (1 = 상단, 2 = 하단)
+    voice: int = 1      # 성부 번호
+    part_hint: Optional[int] = None  # 파트 배분 힌트 (None = 미지정)
+
+
+@dataclass
+class ConvertOptions:
+    """
+    변환 파이프라인 옵션.
+    """
+    part_count: int = 0          # 출력 파트 수 (0 = 동시 발음 수 기준 자동 감지)
+    strict_mode: bool = False    # True이면 경고를 에러로 처리
+    prefer_sharps: bool = True   # True = 올림표(#), False = 내림표(b)
+    mock_mode: bool = True       # True이면 MockOMRAdapter 사용
+    default_tempo: int = 120     # 기본 템포 BPM
+    pdf_dpi: int = 150           # PDF 렌더링 해상도
+                                 # 150dpi: 빠른 처리, 기본값
+                                 # 300dpi: Audiveris 실제 사용 시 권장 (인식률 향상)
+    preprocess_enabled: bool = True   # OpenCV 전처리 사용 여부 (audiveris 모드만 적용)
+    blur_enabled: bool = True         # GaussianBlur 노이즈 제거 사용 여부
+    binarize_enabled: bool = False    # 이진화 사용 여부 (기본 off: Audiveris 자체 이진화 신뢰)
+    binarize_method: str = "otsu"     # 이진화 방식: "otsu" | "adaptive" (binarize_enabled=True 시)
+    deskew_enabled: bool = False      # 기울기 보정 (실험적, 기본 off)
+    debug_dir: str = ""               # 중간 결과물 저장 디렉토리 (빈 문자열 = 저장 안 함)
+    engine: str = ""                  # OMR 엔진 지정: "" | "audiveris" | "homr" | "oemer" | "clarity"
+                                      # 빈 문자열이면 mock_mode에 따라 자동 선택
+    pdf_pages: list = field(default_factory=list)
+                                      # 처리할 PDF 페이지 번호 목록 (1-based). 빈 리스트 = 전체 처리
+                                      # 예) [1, 3] → 1, 3페이지만 처리
+
+
+@dataclass
+class ConvertResult:
+    """
+    변환 결과.
+
+    mml: 마비노기 MML 완성 문자열 "MML@p1,p2,p3;"
+    part1/2/3: 파트별 본문 문자열 (MML@, ; 제외, 내부 검사용)
+    """
+    success: bool
+    mml: str = ""              # 최종 마비노기 MML "MML@[t<BPM>]p1,p2,p3;"
+    part1: str = ""            # Part 1 본문 (내부 검사/디버그용)
+    part2: str = ""
+    part3: str = ""
+    warnings: list[str] = field(default_factory=list)
+    debug_info: dict = field(default_factory=dict)
+
+    def parts(self) -> list[str]:
+        """파트 본문 목록을 리스트로 반환."""
+        return [self.part1, self.part2, self.part3]
+
+    def format_output(self) -> str:
+        """콘솔/파일 출력용 포맷. 파트별 개별 MML@...;로 출력."""
+        lines = []
+        for i, mml in enumerate([self.part1, self.part2, self.part3], start=1):
+            lines.append(f"Part {i}")
+            lines.append(mml if mml else "MML@r1;")
+            lines.append("")
+        if self.warnings:
+            lines.append("--- Warnings ---")
+            for w in self.warnings:
+                lines.append(f"  [WARN] {w}")
+        return "\n".join(lines).strip()
+
+
+@dataclass
+class WarningMessage:
+    """경고 메시지 (필요시 구조화된 경고로 사용)."""
+    code: str
+    message: str
+    context: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# 멀티 엔진 비교용 데이터 구조
+# ---------------------------------------------------------------------------
+
+@dataclass
+class EngineRunResult:
+    """
+    단일 OMR 엔진 실행 결과.
+
+    자동 점수만으로 최종 판정을 내리지 않는다.
+    heuristic_summary는 참고 지표일 뿐, 최종 품질 판단은 사용자가 직접 확인해야 한다.
+    """
+    engine_name: str
+    success: bool
+    stage: str = ""             # 실패 단계: "init" | "preprocess" | "omr" | "parse" | "convert"
+    warnings: list[str] = field(default_factory=list)
+    error_message: str = ""
+
+    # 출력 파일 경로 (저장된 경우)
+    output_xml_path: str = ""   # 엔진 출력 MusicXML 경로
+    output_mml_path: str = ""   # 저장된 MML 텍스트 파일 경로
+    output_notes_json_path: str = ""  # 저장된 notes.json 경로
+    output_notes_txt_path: str = ""   # 저장된 notes.txt 경로
+    output_debug_path: str = ""       # 저장된 debug.json 경로
+
+    # 정량 지표 (참고용)
+    note_count: int = 0
+    chord_count: int = 0          # 동시 발음 노트 그룹 수
+    part_note_counts: list[int] = field(default_factory=list)
+    warning_count: int = 0
+
+    # 상세 데이터
+    debug_info: dict = field(default_factory=dict)
+    heuristic_summary: dict = field(default_factory=dict)
+    mml_parts: list[str] = field(default_factory=list)
+    notes_dump: list[dict] = field(default_factory=list)  # 사람이 검토하기 좋은 노트 목록
+
+
+@dataclass
+class ComparisonReport:
+    """
+    여러 OMR 엔진 비교 실행 결과 집계.
+
+    중요: user_review_priority=True 는 항상 True여야 한다.
+    최종 엔진 선택은 사용자가 직접 결과를 들어보고 판단한다.
+    suggested_engine은 단순 참고용이며 자동 결정이 아니다.
+    """
+    input_file: str
+    timestamp: str = ""
+    runs: list[EngineRunResult] = field(default_factory=list)
+    user_review_priority: bool = True   # 항상 True — 최종 판정은 사용자 직접 확인
+    comparison_summary: str = ""
+    notes_for_manual_review: list[str] = field(default_factory=list)
+    suggested_engine: str = ""  # 자동 참고 추천 (최종 판정 아님)

core/music_parser.py

@@ -0,0 +1,376 @@
+"""
+core/music_parser.py
+
+OMR 결과를 NoteEvent 리스트로 변환하는 파서.
+
+지원 형식:
+  - "mock_events": MockOMRAdapter 출력 (dict 리스트)
+  - "musicxml":    MusicXML 문자열 (score-partwise 형식, stdlib xml.etree 파싱)
+
+MusicXML 파싱 처리 범위:
+  - 단음/화음(<chord>) 처리
+  - 쉼표(<rest>) → pitch=0 NoteEvent로 변환 (offset 흐름 유지)
+  - <backup>/<forward> 처리 (다성부 offset 유지)
+  - <divisions> 변경 추적
+  - <key><fifths> 조표 파싱 → 음표 반음 보정
+  - <sound tempo=""> 템포 파싱
+  - voice/staff 정보 보존
+  - namespace 자동 제거
+  - 타이(<tie>) 처리: 같은 피치 음표 duration 합산
+
+미지원:
+  - score-timewise 형식
+  - grace note (skip)
+  - 슬러(articulation)
+  - 반복기호 펼치기 (D.S. / D.C. / Coda / Segno)
+"""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from dataclasses import replace as dc_replace
+from typing import List
+
+from .models import NoteEvent
+
+
+class ParseError(Exception):
+    """파싱 오류. 어떤 파일/단계에서 실패했는지 포함."""
+    pass
+
+
+# ---------------------------------------------------------------------------
+# 공개 인터페이스
+# ---------------------------------------------------------------------------
+
+def parse_omr_result(omr_result: dict) -> tuple[List[NoteEvent], dict]:
+    """
+    OMR 결과 dict를 (NoteEvent 리스트, 메타데이터 dict)로 변환.
+
+    메타데이터 키:
+      - "tempo": int  (BPM, 0이면 미발견)
+
+    Raises:
+        ParseError: 알 수 없는 형식이거나 파싱 실패 시
+    """
+    fmt = omr_result.get("format")
+
+    if fmt == "mock_events":
+        notes = _parse_mock_events(omr_result["data"])
+        return notes, {"tempo": 0}
+    elif fmt == "musicxml":
+        return _parse_musicxml(omr_result["data"])
+    else:
+        raise ParseError(f"지원하지 않는 OMR 결과 형식: '{fmt}'")
+
+
+def parse_musicxml_file(xml_path: str) -> tuple[List[NoteEvent], dict]:
+    """
+    MusicXML 파일 경로에서 직접 파싱. 테스트 및 직접 사용에 유용.
+
+    Returns:
+        (notes, metadata) — parse_omr_result와 동일한 형식
+
+    Raises:
+        ParseError: 파일 읽기 실패 또는 파싱 오류
+    """
+    try:
+        with open(xml_path, "r", encoding="utf-8", errors="replace") as f:
+            xml_string = f.read()
+    except OSError as e:
+        raise ParseError(f"MusicXML 파일 읽기 실패 ({xml_path}): {e}")
+    return _parse_musicxml(xml_string, source_hint=xml_path)
+
+
+# ---------------------------------------------------------------------------
+# 내부 구현
+# ---------------------------------------------------------------------------
+
+def _parse_mock_events(raw_notes: list) -> List[NoteEvent]:
+    events = []
+    for raw in raw_notes:
+        try:
+            event = NoteEvent(
+                pitch=int(raw["pitch"]),
+                start=float(raw["start"]),
+                duration=float(raw["duration"]),
+                staff=int(raw.get("staff", 1)),
+                voice=int(raw.get("voice", 1)),
+                part_hint=raw.get("part_hint"),
+            )
+            events.append(event)
+        except (KeyError, ValueError) as e:
+            raise ParseError(f"음표 데이터 파싱 오류: {raw!r} — {e}")
+
+    events.sort(key=lambda n: (n.start, n.staff, n.voice))
+    return events
+
+
+# MIDI 음계 반음 수: C=0, D=2, E=4, F=5, G=7, A=9, B=11
+_STEP_SEMITONE = {"C": 0, "D": 2, "E": 4, "F": 5, "G": 7, "A": 9, "B": 11}
+
+# 조표 샤프/플랫 순서
+_KEY_SHARPS = ["F", "C", "G", "D", "A", "E", "B"]  # 1♯=F#, 2♯=F#C#, ...
+_KEY_FLATS  = ["B", "E", "A", "D", "G", "C", "F"]  # 1♭=B♭, 2♭=B♭E♭, ...
+
+
+def _get_key_alters(fifths: int) -> dict[str, int]:
+    """
+    조표 fifths 값 → {음이름: alter} 딕셔너리.
+
+    예: fifths=2 (D장조) → {"F": 1, "C": 1}
+        fifths=-1 (F장조) → {"B": -1}
+    """
+    alters: dict[str, int] = {}
+    if fifths > 0:
+        for i in range(min(fifths, 7)):
+            alters[_KEY_SHARPS[i]] = 1
+    elif fifths < 0:
+        for i in range(min(-fifths, 7)):
+            alters[_KEY_FLATS[i]] = -1
+    return alters
+
+
+def _parse_tempo(root: ET.Element) -> int:
+    """
+    루트 요소에서 첫 번째 <sound tempo="N"/> 값을 반환.
+    없으면 0 반환.
+    """
+    for elem in root.iter("sound"):
+        tempo_str = elem.get("tempo")
+        if tempo_str:
+            try:
+                return int(float(tempo_str))
+            except (ValueError, TypeError):
+                pass
+    return 0
+
+
+def _parse_musicxml(xml_string: str, source_hint: str = "") -> tuple[List[NoteEvent], dict]:
+    """
+    MusicXML 문자열을 (NoteEvent 리스트, 메타데이터)로 변환.
+
+    Args:
+        xml_string:  MusicXML XML 문자열
+        source_hint: 오류 메시지에 포함할 파일명/경로 (선택)
+
+    Returns:
+        (events, metadata) — metadata에 "tempo" 포함
+    """
+    src = f" ({source_hint})" if source_hint else ""
+
+    try:
+        root = ET.fromstring(xml_string)
+    except ET.ParseError as e:
+        raise ParseError(f"MusicXML XML 구문 오류{src}: {e}")
+
+    # namespace 제거 (xmlns가 있어도 동일하게 처리)
+    for elem in root.iter():
+        if "}" in elem.tag:
+            elem.tag = elem.tag.split("}")[1]
+
+    root_tag = root.tag
+    if root_tag != "score-partwise":
+        raise ParseError(
+            f"지원하지 않는 MusicXML 루트 요소{src}: '{root_tag}'\n"
+            f"  score-partwise 형식만 지원합니다. "
+            f"score-timewise는 MuseScore/Audiveris에서 변환 가능합니다."
+        )
+
+    # 템포 추출
+    tempo = _parse_tempo(root)
+
+    events: List[NoteEvent] = []
+    # 타이 추적: key=(part_id, pitch, voice, staff) → events 리스트 인덱스
+    tie_pending: dict[tuple, int] = {}
+
+    for part_idx, part_elem in enumerate(root.findall("part")):
+        part_id = part_elem.get("id", f"P{part_idx + 1}")
+        divisions = 1            # <divisions>: 4분음표당 XML duration 단위
+        measure_start = 0.0      # 현재 마디의 시작 beat
+        key_alters: dict[str, int] = {}  # 조표 반음 보정 (음이름 → alter)
+
+        for measure_elem in part_elem.findall("measure"):
+            current_beat = 0.0       # 마디 내 현재 위치
+            prev_note_beat = 0.0     # 직전 비-chord 음표의 시작 위치 (chord 처리용)
+            max_beat = 0.0           # 마디 내 도달한 최대 위치 (backup 후에도 유지)
+
+            for child in measure_elem:
+                tag = child.tag
+
+                # attributes: divisions, key 업데이트
+                if tag == "attributes":
+                    div_elem = child.find("divisions")
+                    if div_elem is not None and div_elem.text:
+                        try:
+                            divisions = int(div_elem.text)
+                        except ValueError:
+                            pass
+
+                    key_elem = child.find("key")
+                    if key_elem is not None:
+                        fifths_elem = key_elem.find("fifths")
+                        if fifths_elem is not None and fifths_elem.text:
+                            try:
+                                key_alters = _get_key_alters(int(fifths_elem.text))
+                            except ValueError:
+                                pass
+
+                elif tag == "note":
+                    note_event = _parse_note(
+                        child, divisions, part_idx,
+                        measure_start, current_beat, prev_note_beat,
+                        part_id, source_hint, key_alters,
+                    )
+                    if note_event is not None:
+                        # 타이 처리 (쉼표 제외)
+                        if note_event.pitch != 0:
+                            tie_stop = any(
+                                t.get("type") == "stop"
+                                for t in child.findall("tie")
+                            )
+                            tie_start = any(
+                                t.get("type") == "start"
+                                for t in child.findall("tie")
+                            )
+                            tie_key = (
+                                part_id,
+                                note_event.pitch,
+                                note_event.voice,
+                                note_event.staff,
+                            )
+                            if tie_stop and tie_key in tie_pending:
+                                # 이전 타이 음표에 duration 합산
+                                idx = tie_pending.pop(tie_key)
+                                old = events[idx]
+                                events[idx] = dc_replace(
+                                    old, duration=old.duration + note_event.duration
+                                )
+                                if tie_start:
+                                    tie_pending[tie_key] = idx
+                                # 새 이벤트는 추가하지 않음
+                            else:
+                                events.append(note_event)
+                                if tie_start:
+                                    tie_pending[tie_key] = len(events) - 1
+                        else:
+                            events.append(note_event)
+
+                    # chord가 아닌 경우에만 위치 전진
+                    is_chord = child.find("chord") is not None
+                    dur_beats = _get_duration_beats(child, divisions)
+                    if not is_chord:
+                        prev_note_beat = current_beat
+                        current_beat += dur_beats
+                        max_beat = max(max_beat, current_beat)
+
+                elif tag == "backup":
+                    dur_beats = _get_duration_beats(child, divisions)
+                    current_beat = max(0.0, current_beat - dur_beats)
+
+                elif tag == "forward":
+                    dur_beats = _get_duration_beats(child, divisions)
+                    current_beat += dur_beats
+                    max_beat = max(max_beat, current_beat)
+
+            # backup이 있어도 마디 길이는 최대 도달 위치 기준
+            measure_start += max_beat
+
+    if not events:
+        return [], {"tempo": tempo}
+
+    events.sort(key=lambda n: (n.start, n.staff, n.voice))
+    return events, {"tempo": tempo}
+
+
+def _parse_note(
+    note_elem: ET.Element,
+    divisions: int,
+    part_idx: int,
+    measure_start: float,
+    current_beat: float,
+    prev_note_beat: float,
+    part_id: str,
+    source_hint: str,
+    key_alters: dict[str, int],
+) -> NoteEvent | None:
+    """
+    단일 <note> 요소를 NoteEvent로 변환.
+
+    grace note처럼 duration이 없는 경우는 None 반환 (skip).
+    key_alters: 조표에서 파생된 {음이름: alter} 딕셔너리.
+                <alter> 태그가 없는 음표의 반음 보정에 사용.
+    """
+    is_chord = note_elem.find("chord") is not None
+    is_rest = note_elem.find("rest") is not None
+
+    dur_beats = _get_duration_beats(note_elem, divisions)
+    if dur_beats == 0.0:
+        # grace note 또는 duration 0 — skip
+        return None
+
+    note_beat = prev_note_beat if is_chord else current_beat
+    abs_start = measure_start + note_beat
+
+    voice_elem = note_elem.find("voice")
+    voice = int(voice_elem.text) if voice_elem is not None and voice_elem.text else 1
+
+    staff_elem = note_elem.find("staff")
+    if staff_elem is not None and staff_elem.text:
+        staff_raw = int(staff_elem.text)
+    else:
+        # <staff> 없으면 voice를 staff 대리자로 사용 (Audiveris 등)
+        # voice별로 파트가 분리되도록 함
+        staff_raw = voice
+    # part 간 staff 번호가 겹치지 않도록 전역 고유값으로 변환
+    # ex) P1/staff1=1, P1/staff2=2, P2/staff1=11, P2/staff2=12
+    staff = part_idx * 10 + staff_raw
+
+    if is_rest:
+        return NoteEvent(
+            pitch=0,
+            start=abs_start,
+            duration=dur_beats,
+            staff=staff,
+            voice=voice,
+        )
+
+    pitch_elem = note_elem.find("pitch")
+    if pitch_elem is None:
+        return None
+
+    step_elem = pitch_elem.find("step")
+    octave_elem = pitch_elem.find("octave")
+    alter_elem = pitch_elem.find("alter")
+
+    step = step_elem.text.strip().upper() if step_elem is not None and step_elem.text else "C"
+    octave = int(octave_elem.text) if octave_elem is not None and octave_elem.text else 4
+
+    # <alter> 명시 시 우선 사용, 없으면 조표 기본값 적용
+    if alter_elem is not None and alter_elem.text:
+        alter = int(float(alter_elem.text))
+    else:
+        alter = key_alters.get(step, 0)
+
+    semitone = _STEP_SEMITONE.get(step, 0)
+    pitch = (octave + 1) * 12 + semitone + alter
+    pitch = max(0, min(127, pitch))
+
+    return NoteEvent(
+        pitch=pitch,
+        start=abs_start,
+        duration=dur_beats,
+        staff=staff,
+        voice=voice,
+    )
+
+
+def _get_duration_beats(elem: ET.Element, divisions: int) -> float:
+    """<duration> 요소를 4분음표 기준 beats로 변환."""
+    dur_elem = elem.find("duration")
+    if dur_elem is None or not dur_elem.text:
+        return 0.0
+    try:
+        return int(dur_elem.text) / max(1, divisions)
+    except (ValueError, ZeroDivisionError):
+        return 0.0

core/mxl_mml_converter.py

@@ -0,0 +1,239 @@
+"""
+core/mxl_mml_converter.py
+
+ChatGPT 변환 코드 그대로 사용 (로직 변경 없음).
+파이프라인 인터페이스(convert_xml_pages_to_mml_parts)만 래퍼로 추가.
+"""
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from typing import List, Tuple
+
+# ---------------------------------------------------------------------------
+# ChatGPT 코드 — 하나도 바꾸지 않음
+# ---------------------------------------------------------------------------
+
+STEP_TO_SEMI = {'C':0,'D':2,'E':4,'F':5,'G':7,'A':9,'B':11}
+SEMI_TO_NOTE = {
+    0:'c',1:'c+',2:'d',3:'d+',4:'e',5:'f',6:'f+',7:'g',8:'g+',9:'a',10:'a+',11:'b'
+}
+# quarter=12 ticks, whole=48
+DUR_TOKEN = {
+    48:'1', 36:'2.', 24:'2', 18:'4.', 16:'3', 15:'4&16', 12:'4', 9:'8.', 8:'6',
+    6:'8', 4:'12', 3:'16', 2:'24', 1:'48'
+}
+# Components that can be emitted as single token (excluding composites encoded above)
+SINGLE_DURS = [48,36,24,18,16,12,9,8,6,4,3,2,1]
+
+
+def parse_events(root):
+    part=root.find('part')
+    events=[]
+    abs_time=0   # 48 ticks/whole 기준 정규화된 누적 시간
+    divisions=1
+    measure_bounds=[]
+    for m in part.findall('measure'):
+        # 이 마디의 divisions 먼저 확인
+        attr=m.find('attributes')
+        if attr is not None:
+            d=attr.findtext('divisions')
+            if d is not None:
+                divisions=int(d)
+
+        # 마디 내부는 raw tick으로 추적, 저장 시 정규화
+        scale_num=48
+        scale_den=divisions*4
+        def norm(raw): return raw*scale_num//scale_den
+
+        measure_start=abs_time
+        cursor_raw=0   # 마디 내 raw tick (마디 시작 기준 상대값)
+        max_cursor_raw=0
+        last_start_raw=None
+
+        for child in m:
+            if child.tag=='attributes':
+                pass  # 이미 처리
+            elif child.tag=='backup':
+                cursor_raw -= int(child.findtext('duration'))
+            elif child.tag=='forward':
+                cursor_raw += int(child.findtext('duration'))
+                max_cursor_raw=max(max_cursor_raw,cursor_raw)
+            elif child.tag=='note':
+                dur_raw=int(child.findtext('duration','0'))
+                start_raw=cursor_raw if child.find('chord') is None else last_start_raw
+                if child.find('rest') is None:
+                    p=child.find('pitch')
+                    midi=(int(p.findtext('octave'))+1)*12+STEP_TO_SEMI[p.findtext('step')]+int(p.findtext('alter','0'))
+                    events.append({
+                        'start': measure_start+norm(start_raw),
+                        'dur':   norm(dur_raw),
+                        'midi':  midi,
+                        'voice': child.findtext('voice','1'),
+                        'measure': int(m.attrib['number']),
+                        'tie': tuple(t.attrib.get('type') for t in child.findall('tie')),
+                    })
+                if child.find('chord') is None:
+                    last_start_raw=start_raw
+                    cursor_raw += dur_raw
+                    max_cursor_raw=max(max_cursor_raw,cursor_raw)
+                else:
+                    max_cursor_raw=max(max_cursor_raw,start_raw+dur_raw)
+
+        abs_time=measure_start+norm(max_cursor_raw)
+        measure_bounds.append((int(m.attrib['number']), measure_start, abs_time))
+    return events, abs_time, divisions, measure_bounds
+
+
+def merge_ties(events):
+    out=[]
+    ongoing={}
+    for e in sorted(events, key=lambda e:(e['start'], e['midi'], e['voice'])):
+        key=(e['midi'], e['voice'])
+        tie=set(e['tie'])
+        if 'stop' in tie and key in ongoing:
+            idx=ongoing[key]
+            prev=out[idx]
+            if prev['start']+prev['dur']==e['start']:
+                prev['dur'] += e['dur']
+                prev['measure_end'] = e['measure']
+                if 'start' not in tie:
+                    del ongoing[key]
+                continue
+        new={k:v for k,v in e.items() if k!='tie'}
+        new['measure_start']=e['measure']
+        new['measure_end']=e['measure']
+        out.append(new)
+        if 'start' in tie:
+            ongoing[key]=len(out)-1
+    return out
+
+
+def assign_tracks(events):
+    tracks=[]
+    for e in sorted(events, key=lambda e:(e['start'], -e['midi'], e['dur'])):
+        free=[(i,t) for i,t in enumerate(tracks) if t['end']<=e['start']]
+        if free:
+            def score(item):
+                i,t=item
+                same = 1 if (t.get('last_pitch')==e['midi'] and t['end']==e['start']) else 0
+                dist = abs((t.get('last_pitch',e['midi']))-e['midi'])
+                return (-same, dist, -t['end'], i)
+            idx,_=min(free,key=score)
+        else:
+            idx=len(tracks)
+            tracks.append({'end':0,'last_pitch':None,'events':[]})
+        t=tracks[idx]
+        t['events'].append(e)
+        t['end']=e['start']+e['dur']
+        t['last_pitch']=e['midi']
+    order=sorted(range(len(tracks)), key=lambda i: -(sum(e['midi'] for e in tracks[i]['events'])/len(tracks[i]['events'])))
+    reordered=[]
+    for old_idx in order:
+        reordered.append({'events':sorted(tracks[old_idx]['events'], key=lambda e:(e['start'], -e['midi']))})
+    return reordered
+
+
+def decompose_duration(total):
+    from functools import lru_cache
+    @lru_cache(None)
+    def dp(rem):
+        if rem==0:
+            return []
+        best=None
+        for d in SINGLE_DURS:
+            if d<=rem:
+                tail=dp(rem-d)
+                if tail is not None:
+                    cand=[d]+tail
+                    if best is None or len(cand)<len(best):
+                        best=cand
+        return best
+    res=dp(total)
+    if res is None:
+        raise ValueError(f'cannot decompose {total}')
+    return res
+
+
+def midi_to_oct_note(midi):
+    return midi//12 - 1, SEMI_TO_NOTE[midi%12]
+
+
+def emit_event(pieces, cur_oct, midi, dur):
+    octave,note = midi_to_oct_note(midi)
+    if cur_oct != octave:
+        pieces.append(f'o{octave}')
+        cur_oct=octave
+    parts=decompose_duration(dur)
+    for i,d in enumerate(parts):
+        pieces.append(note + DUR_TOKEN[d])
+        if i != len(parts)-1:
+            pieces.append('&')
+    return cur_oct
+
+
+def emit_rest(pieces, dur):
+    for d in decompose_duration(dur):
+        pieces.append('r'+DUR_TOKEN[d])
+
+
+def build_track_mml(track_events, total_dur):
+    pieces=[]
+    cur_oct=None
+    cur_time=0
+    for e in track_events:
+        if e['start']<cur_time:
+            raise ValueError('overlap')
+        if e['start']>cur_time:
+            emit_rest(pieces, e['start']-cur_time)
+            cur_time=e['start']
+        cur_oct = emit_event(pieces, cur_oct, e['midi'], e['dur'])
+        cur_time = e['start']+e['dur']
+    if cur_time<total_dur:
+        emit_rest(pieces, total_dur-cur_time)
+    return ''.join(pieces)
+
+
+# ---------------------------------------------------------------------------
+# 파이프라인 인터페이스 (래퍼)
+# ---------------------------------------------------------------------------
+
+def convert_xml_pages_to_mml_parts(
+    xml_strings: List[str],
+) -> Tuple[List[str], List[str]]:
+    """
+    여러 페이지의 MusicXML 문자열을 MML 파트 리스트로 변환.
+
+    Returns:
+        (part_mmls, warnings)
+    """
+    all_events = []
+    total_offset = 0
+    warnings: List[str] = []
+
+    for page_idx, xml_str in enumerate(xml_strings, start=1):
+        try:
+            xml_bytes = xml_str.encode('utf-8') if isinstance(xml_str, str) else xml_str
+            root = ET.fromstring(xml_bytes)
+            # namespace 제거 (namespace가 있는 XML 대응)
+            for elem in root.iter():
+                if '}' in elem.tag:
+                    elem.tag = elem.tag.split('}')[1]
+            page_events, page_dur, _divisions, _bounds = parse_events(root)
+        except Exception as e:
+            warnings.append(f'페이지 {page_idx} 파싱 오류: {e}')
+            continue
+
+        page_merged = merge_ties(page_events)
+
+        for ev in page_merged:
+            ev['start'] += total_offset
+
+        all_events.extend(page_merged)
+        total_offset += page_dur
+
+    if not all_events:
+        return ['MML@r1;'], warnings
+
+    tracks = assign_tracks(all_events)
+    mml_parts = [f"MML@{build_track_mml(t['events'], total_offset)};" for t in tracks]
+    return mml_parts, warnings

core/omr_adapter.py

@@ -0,0 +1,788 @@
+"""
+core/omr_adapter.py
+
+OMR 엔진 추상화 계층.
+
+실제 OMR 구현은 이 모듈 안에서만 교체된다.
+다른 core 모듈들은 OMRAdapter 인터페이스만 사용한다.
+
+구현체:
+  - MockOMRAdapter:      테스트/개발용. 이미지 읽지 않고 고정 데이터 반환.
+  - AudiverisOMRAdapter: Audiveris CLI를 subprocess로 호출. MusicXML 반환.
+  - HOMROMRAdapter:      HOMR (pip install homr) CLI를 subprocess로 호출.
+  - OeMeROMRAdapter:     OeMeR/oemer (pip install oemer) CLI를 subprocess로 호출.
+  - ClarityOMRAdapter:   Clarity-OMR (github: clquwu/Clarity-OMR) CLI를 호출.
+                         PDF → MusicXML. GPU/CPU 자동 선택.
+
+환경변수:
+  AUDIVERIS_BIN=<경로>   Audiveris 실행 파일 (직접 실행 방식)
+  AUDIVERIS_JAR=<경로>   Audiveris.jar (java -jar 방식)
+  HOMR_CMD=<경로>        homr 실행 파일 또는 명령어 (기본: python -m homr)
+  OEMER_CMD=<경로>       oemer 실행 파일 또는 명령어 (기본: oemer)
+  CLARITY_OMR_DIR=<경로> Clarity-OMR 레포지토리 루트 (omr.py가 있는 폴더)
+  CLARITY_DEVICE=<값>    "cuda" | "cpu" | "auto" (기본: "auto")
+                         auto이면 torch.cuda.is_available()로 자동 선택
+  CLARITY_PYTHON=<경로>  Clarity-OMR 실행에 사용할 python 경로
+                         (기본: 현재 프로세스의 sys.executable)
+
+주의:
+  HOMR/OeMeR/Clarity는 import 단계에서 체크하지 않는다.
+  실행(run()) 시점에만 환경을 검사한다.
+
+Audiveris 출력 구조:
+  <output_dir>/<image_basename>/<image_basename>.mxl  (또는 .xml)
+  .mxl은 ZIP 형식의 MusicXML 아카이브
+"""
+
+from __future__ import annotations
+
+import abc
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import zipfile
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import Optional
+
+
+class OMRAdapter(abc.ABC):
+    """OMR 엔진 추상 인터페이스."""
+
+    @abc.abstractmethod
+    def run(self, image_path: str) -> dict:
+        """
+        이미지를 분석하여 OMR 결과를 반환.
+
+        Returns:
+            dict:
+              - "format": "mock_events" | "musicxml"
+              - "data": 결과 데이터 (mock_events면 list[dict], musicxml이면 XML 문자열)
+              - "source_path": 원본 이미지 경로
+              - "metadata": 부가 정보
+        """
+        ...
+
+    @abc.abstractmethod
+    def is_available(self) -> bool:
+        """이 어댑터를 실행할 수 있는지 확인 (실행 시점 검사)."""
+        ...
+
+
+class MockOMRAdapter(OMRAdapter):
+    """
+    테스트 및 개발용 Mock OMR 어댑터.
+
+    실제 이미지 분석 없이 C장조 스케일 + 화음 + 베이스 데이터를 반환.
+    """
+
+    def run(self, image_path: str, debug_dir: str = "") -> dict:
+        mock_notes = [
+            # staff=1 (상단 보표) — 멜로디
+            {"pitch": 60, "start": 0.0,  "duration": 1.0, "staff": 1, "voice": 1},
+            {"pitch": 62, "start": 1.0,  "duration": 1.0, "staff": 1, "voice": 1},
+            {"pitch": 64, "start": 2.0,  "duration": 1.0, "staff": 1, "voice": 1},
+            {"pitch": 65, "start": 3.0,  "duration": 1.0, "staff": 1, "voice": 1},
+            {"pitch": 67, "start": 4.0,  "duration": 1.0, "staff": 1, "voice": 1},
+            {"pitch": 69, "start": 5.0,  "duration": 1.0, "staff": 1, "voice": 1},
+            {"pitch": 71, "start": 6.0,  "duration": 1.0, "staff": 1, "voice": 1},
+            {"pitch": 72, "start": 7.0,  "duration": 2.0, "staff": 1, "voice": 1},
+            # staff=1 — 화음 (voice 2)
+            {"pitch": 64, "start": 0.0,  "duration": 1.0, "staff": 1, "voice": 2},
+            {"pitch": 65, "start": 1.0,  "duration": 1.0, "staff": 1, "voice": 2},
+            {"pitch": 67, "start": 2.0,  "duration": 1.0, "staff": 1, "voice": 2},
+            {"pitch": 67, "start": 3.0,  "duration": 1.0, "staff": 1, "voice": 2},
+            {"pitch": 69, "start": 4.0,  "duration": 1.0, "staff": 1, "voice": 2},
+            {"pitch": 71, "start": 5.0,  "duration": 1.0, "staff": 1, "voice": 2},
+            {"pitch": 72, "start": 6.0,  "duration": 1.0, "staff": 1, "voice": 2},
+            {"pitch": 72, "start": 7.0,  "duration": 2.0, "staff": 1, "voice": 2},
+            # staff=2 (하단 보표) — 베이스
+            {"pitch": 48, "start": 0.0,  "duration": 2.0, "staff": 2, "voice": 1},
+            {"pitch": 53, "start": 2.0,  "duration": 2.0, "staff": 2, "voice": 1},
+            {"pitch": 55, "start": 4.0,  "duration": 2.0, "staff": 2, "voice": 1},
+            {"pitch": 48, "start": 6.0,  "duration": 2.0, "staff": 2, "voice": 1},
+        ]
+        return {
+            "format": "mock_events",
+            "data": mock_notes,
+            "source_path": image_path,
+            "metadata": {
+                "key_signature": "C",
+                "time_signature": "4/4",
+                "tempo": 120,
+                "note_count": len(mock_notes),
+            },
+        }
+
+    def is_available(self) -> bool:
+        return True
+
+
+class AudiverisOMRAdapter(OMRAdapter):
+    """
+    Audiveris 기반 실제 OMR 어댑터.
+
+    subprocess로 Audiveris CLI를 호출하고 MusicXML 결과를 반환.
+    임시 출력 디렉토리는 run() 완료 후 자동 정리.
+    """
+
+    def __init__(self, jar_path: str = "", bin_path: str = ""):
+        # bin_path: audiveris 실행 파일 직접 경로
+        # jar_path: Audiveris.jar 경로 (java -jar 방식)
+        self.jar_path = jar_path
+        self.bin_path = bin_path
+
+    def _build_command(self, image_path: str, output_dir: str) -> list:
+        if self.bin_path:
+            return [
+                self.bin_path,
+                "-batch", "-export",
+                "-output", output_dir,
+                "--", image_path,
+            ]
+        max_heap = os.environ.get("AUDIVERIS_MAX_HEAP", "1500m")
+        return [
+            "java", f"-Xmx{max_heap}", "-jar", self.jar_path,
+            "-batch", "-export",
+            "-output", output_dir,
+            "--", image_path,
+        ]
+
+    def run(self, image_path: str, debug_dir: str = "") -> dict:
+        tmp_dir = tempfile.mkdtemp(prefix="score_to_mml_aud_")
+        try:
+            result = self._run_in_dir(image_path, tmp_dir)
+            if debug_dir:
+                xml_path = result["metadata"].get("musicxml_path", "")
+                if xml_path and Path(xml_path).exists():
+                    shutil.copy2(xml_path, str(Path(debug_dir) / Path(xml_path).name))
+            return result
+        finally:
+            shutil.rmtree(tmp_dir, ignore_errors=True)
+
+    def _run_in_dir(self, image_path: str, tmp_dir: str) -> dict:
+        cmd = self._build_command(image_path, tmp_dir)
+
+        try:
+            proc = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=180,
+            )
+        except FileNotFoundError as e:
+            raise RuntimeError(
+                f"Audiveris 실행 파일을 찾을 수 없습니다: '{cmd[0]}'\n"
+                f"  - AUDIVERIS_BIN 또는 AUDIVERIS_JAR 환경변수를 확인하세요.\n"
+                f"  - java -jar 방식이라면 java가 PATH에 있는지 확인하세요.\n"
+                f"  원본 오류: {e}"
+            )
+        except subprocess.TimeoutExpired:
+            raise RuntimeError(
+                f"Audiveris 실행 타임아웃 (180초 초과)\n"
+                f"  입력 파일: {image_path}\n"
+                f"  이미지가 너무 크거나 시스템이 느린 경우 발생할 수 있습니다."
+            )
+
+        if proc.returncode != 0:
+            stdout_tail = proc.stdout[-800:] if proc.stdout else "(없음)"
+            stderr_tail = proc.stderr[-800:] if proc.stderr else "(없음)"
+            raise RuntimeError(
+                f"Audiveris 실행 실패 (exit code {proc.returncode})\n"
+                f"  명령: {' '.join(cmd)}\n"
+                f"  입력: {image_path}\n"
+                f"  STDOUT (마지막 800자):\n{stdout_tail}\n"
+                f"  STDERR (마지막 800자):\n{stderr_tail}"
+            )
+
+        xml_path = _find_musicxml_output(tmp_dir, image_path)
+        if xml_path is None:
+            stdout_tail = proc.stdout[-400:] if proc.stdout else "(없음)"
+            raise RuntimeError(
+                f"Audiveris 출력에서 MusicXML 파일(.mxl/.xml)을 찾을 수 없습니다.\n"
+                f"  출력 디렉토리: {tmp_dir}\n"
+                f"  Audiveris가 정상 종료(exit 0)했지만 출력 파일이 없는 경우:\n"
+                f"    - 이미지 품질이 너무 낮거나\n"
+                f"    - Audiveris 설정에서 -export 옵션이 필요하거나\n"
+                f"    - 악보를 인식하지 못한 경우일 수 있습니다.\n"
+                f"  STDOUT:\n{stdout_tail}"
+            )
+
+        xml_string = _read_musicxml(xml_path)
+
+        return {
+            "format": "musicxml",
+            "data": xml_string,
+            "source_path": image_path,
+            "metadata": {
+                "musicxml_path": xml_path,
+                "audiveris_stdout_tail": proc.stdout[-300:] if proc.stdout else "",
+            },
+        }
+
+    def is_available(self) -> bool:
+        if self.bin_path:
+            return Path(self.bin_path).exists()
+        if not self.jar_path or not Path(self.jar_path).exists():
+            return False
+        # jar 방식이면 java도 필요
+        try:
+            result = subprocess.run(
+                ["java", "-version"],
+                capture_output=True,
+                timeout=5,
+            )
+            return result.returncode == 0
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            return False
+
+
+class ClarityOMRAdapter(OMRAdapter):
+    """
+    Clarity-OMR 기반 OMR 어댑터.
+
+    PDF를 입력으로 받아 MusicXML을 출력한다.
+    이미지(PNG/JPG 등)가 입력되면 Pillow로 임시 PDF 변환 후 처리한다.
+    GPU가 있으면 자동으로 CUDA를 사용한다.
+
+    설치:
+      git clone https://github.com/clquwu/Clarity-OMR
+      cd Clarity-OMR
+      pip install torch torchvision  # GPU: --index-url 옵션 추가
+      pip install -r requirements.txt
+
+    환경변수:
+      CLARITY_OMR_DIR: Clarity-OMR 레포 루트 경로 (필수, omr.py가 있는 폴더)
+      CLARITY_DEVICE:  "cuda" | "cpu" | "auto" (기본: "auto")
+      CLARITY_PYTHON:  python 실행 파일 경로 (기본: 현재 프로세스의 sys.executable)
+    """
+
+    def __init__(self, omr_dir: str = "", device: str = "", python_path: str = ""):
+        self.omr_dir = omr_dir or os.environ.get("CLARITY_OMR_DIR", "")
+        self.device = device or os.environ.get("CLARITY_DEVICE", "auto")
+        self.python_path = python_path or os.environ.get("CLARITY_PYTHON", "")
+
+    def _resolve_device(self) -> str:
+        """사용할 디바이스("cuda" 또는 "cpu")를 결정."""
+        if self.device in ("cuda", "cpu"):
+            return self.device
+        # auto: torch로 CUDA 가용 여부 확인
+        try:
+            import torch
+            return "cuda" if torch.cuda.is_available() else "cpu"
+        except ImportError:
+            return "cpu"
+
+    def _get_python(self) -> str:
+        """Clarity-OMR 실행에 사용할 python 경로."""
+        return self.python_path or sys.executable
+
+    def _image_to_pdf(self, image_path: str, tmp_dir: str) -> str:
+        """
+        이미지를 임시 PDF로 변환 (Pillow 사용).
+        Clarity-OMR이 PDF 입력만 지원하기 때문에 필요.
+        """
+        try:
+            from PIL import Image
+        except ImportError:
+            raise RuntimeError(
+                "이미지를 PDF로 변환하려면 Pillow가 필요합니다.\n"
+                "  설치: pip install Pillow\n"
+                "  또는 처음부터 PDF 파일을 입력으로 사용하세요."
+            )
+        img = Image.open(image_path).convert("RGB")
+        pdf_path = str(Path(tmp_dir) / (Path(image_path).stem + "_clarity_input.pdf"))
+        img.save(pdf_path, "PDF", resolution=300)
+        return pdf_path
+
+    def run(self, image_path: str, debug_dir: str = "") -> dict:
+        if not self.omr_dir:
+            raise RuntimeError(
+                "CLARITY_OMR_DIR 환경변수가 설정되지 않았습니다.\n"
+                "  Clarity-OMR 레포지토리 루트 경로를 설정하세요.\n"
+                "  예) set CLARITY_OMR_DIR=C:\\path\\to\\Clarity-OMR"
+            )
+
+        tmp_dir = tempfile.mkdtemp(prefix="score_to_mml_clarity_")
+        try:
+            # PDF가 아닌 경우 변환
+            if image_path.lower().endswith(".pdf"):
+                pdf_path = image_path
+            else:
+                pdf_path = self._image_to_pdf(image_path, tmp_dir)
+
+            stem = Path(pdf_path).stem
+            output_path = str(Path(tmp_dir) / (stem + ".musicxml"))
+            device = self._resolve_device()
+            python = self._get_python()
+            omr_script = str(Path(self.omr_dir) / "omr.py")
+
+            cmd = [python, omr_script, pdf_path, "-o", output_path, "--device", device]
+
+            try:
+                proc = subprocess.run(
+                    cmd,
+                    capture_output=True,
+                    text=True,
+                    timeout=600,
+                    cwd=self.omr_dir,
+                )
+            except FileNotFoundError as e:
+                raise RuntimeError(
+                    f"Clarity-OMR 실행 파일을 찾을 수 없습니다.\n"
+                    f"  python: {python}\n"
+                    f"  omr.py: {omr_script}\n"
+                    f"  CLARITY_OMR_DIR 경로가 올바른지 확인하세요.\n"
+                    f"  원본 오류: {e}"
+                )
+            except subprocess.TimeoutExpired:
+                raise RuntimeError(
+                    f"Clarity-OMR 실행 타임아웃 (600초 초과)\n"
+                    f"  입력 파일: {pdf_path}\n"
+                    f"  첫 실행 시 HuggingFace에서 모델 다운로드가 필요할 수 있습니다."
+                )
+
+            # -o 옵션 경로 우선, 없으면 tmp_dir 전체 탐색
+            xml_path: Optional[str] = None
+            if Path(output_path).exists():
+                xml_path = output_path
+            else:
+                xml_path = _find_any_musicxml(tmp_dir, stem)
+
+            if xml_path is None:
+                stdout_tail = proc.stdout[-400:] if proc.stdout else "(없음)"
+                stderr_tail = proc.stderr[-400:] if proc.stderr else "(없음)"
+                raise RuntimeError(
+                    f"Clarity-OMR 출력에서 MusicXML 파일을 찾을 수 없습니다.\n"
+                    f"  출력 디렉토리: {tmp_dir}\n"
+                    f"  returncode: {proc.returncode}\n"
+                    f"  device: {device}\n"
+                    f"  STDOUT:\n{stdout_tail}\n"
+                    f"  STDERR:\n{stderr_tail}"
+                )
+
+            if debug_dir:
+                shutil.copy2(xml_path, str(Path(debug_dir) / Path(xml_path).name))
+
+            xml_string = _read_musicxml(xml_path)
+            return {
+                "format": "musicxml",
+                "data": xml_string,
+                "source_path": image_path,
+                "metadata": {
+                    "musicxml_path": xml_path,
+                    "device": device,
+                    "clarity_stdout_tail": proc.stdout[-300:] if proc.stdout else "",
+                    "clarity_stderr_tail": proc.stderr[-300:] if proc.stderr else "",
+                    "clarity_returncode": proc.returncode,
+                },
+            }
+        finally:
+            shutil.rmtree(tmp_dir, ignore_errors=True)
+
+    def is_available(self) -> bool:
+        if not self.omr_dir:
+            return False
+        return (Path(self.omr_dir) / "omr.py").exists()
+
+
+# ---------------------------------------------------------------------------
+# 내부 유틸
+# ---------------------------------------------------------------------------
+
+def _find_any_musicxml(output_dir: str, stem: str = "") -> Optional[str]:
+    """
+    디렉토리에서 MusicXML 파일을 탐색. HOMR/OeMeR 등 범용 출력 탐색에 사용.
+
+    탐색 순서:
+    1. stem 기반 정확한 파일명 (stem.musicxml, stem.mxl, stem.xml)
+    2. 전체 재귀 탐색 (*.musicxml, *.mxl, *.xml)
+    """
+    out = Path(output_dir)
+
+    if stem:
+        for ext in (".musicxml", ".mxl", ".xml"):
+            candidate = out / (stem + ext)
+            if candidate.exists():
+                return str(candidate)
+
+    for pattern in ("*.musicxml", "*.mxl", "*.xml"):
+        matches = sorted(out.rglob(pattern))
+        if matches:
+            return str(matches[0])
+
+    return None
+
+
+def _find_musicxml_output(output_dir: str, image_path: str) -> Optional[str]:
+    """
+    Audiveris 출력 디렉토리에서 MusicXML 파일을 탐색.
+
+    탐색 순서:
+    1. <output_dir>/<image_stem>/<image_stem>.(mxl|xml)  — 예상 위치
+    2. <output_dir>/**/*.mxl, *.xml                       — recursive fallback
+    """
+    out = Path(output_dir)
+    stem = Path(image_path).stem
+
+    for ext in (".mxl", ".xml"):
+        candidate = out / stem / (stem + ext)
+        if candidate.exists():
+            return str(candidate)
+
+    for pattern in ("*.mxl", "*.xml"):
+        matches = sorted(out.rglob(pattern))
+        if matches:
+            return str(matches[0])
+
+    return None
+
+
+def _read_musicxml(xml_path: str) -> str:
+    """
+    .mxl(ZIP) 또는 .xml 파일에서 MusicXML 문자열을 읽어 반환.
+    """
+    if xml_path.lower().endswith(".mxl"):
+        return _extract_xml_from_mxl(xml_path)
+    with open(xml_path, "r", encoding="utf-8", errors="replace") as f:
+        return f.read()
+
+
+def _extract_xml_from_mxl(mxl_path: str) -> str:
+    """
+    MXL (ZIP 형식 MusicXML) 파일에서 XML 내용을 추출.
+
+    META-INF/container.xml의 rootfile 경로를 우선 사용하고,
+    실패 시 ZIP 안의 첫 번째 .xml 파일을 반환.
+    """
+    with zipfile.ZipFile(mxl_path, "r") as zf:
+        # META-INF/container.xml → rootfile full-path
+        try:
+            container_raw = zf.read("META-INF/container.xml").decode("utf-8")
+            container_root = ET.fromstring(container_raw)
+            for elem in container_root.iter():
+                local = elem.tag.split("}")[-1] if "}" in elem.tag else elem.tag
+                if local == "rootfile":
+                    rootfile_path = elem.get("full-path")
+                    if rootfile_path and rootfile_path in zf.namelist():
+                        return zf.read(rootfile_path).decode("utf-8", errors="replace")
+        except (KeyError, ET.ParseError):
+            pass
+
+        # fallback: ZIP 안 첫 번째 .xml
+        xml_entries = [
+            n for n in zf.namelist()
+            if n.endswith(".xml") and not n.startswith("META-INF")
+        ]
+        if xml_entries:
+            return zf.read(xml_entries[0]).decode("utf-8", errors="replace")
+
+    raise RuntimeError(f"MXL 파일에서 MusicXML을 찾을 수 없습니다: {mxl_path}")
+
+
+class HOMROMRAdapter(OMRAdapter):
+    """
+    HOMR 기반 OMR 어댑터.
+
+    설치: pip install homr
+    참고: https://github.com/liebharc/homr
+
+    환경변수:
+      HOMR_CMD: homr 실행 명령 (기본: python -m homr)
+                예) HOMR_CMD=homr  또는  HOMR_CMD=C:\\path\\to\\homr.exe
+
+    출력: 입력 이미지와 같은 디렉토리에 <stem>.musicxml 생성
+          → tmp_dir에서 실행하면 tmp_dir에 출력됨
+    """
+
+    def __init__(self, cmd: str = ""):
+        self.cmd = cmd or os.environ.get("HOMR_CMD", "")
+
+    def _build_command(self, image_path: str) -> list[str]:
+        if self.cmd:
+            return [self.cmd, image_path]
+        # 현재 Python 환경 Scripts 탐색
+        homr_exe = str(Path(sys.executable).parent / "Scripts" / "homr.exe")
+        if Path(homr_exe).exists():
+            return [homr_exe, image_path]
+        # Python 3.10 환경 Scripts 탐색 (homr는 3.10+ 전용)
+        py310_homr = Path(r"C:\Users\Park\AppData\Local\Programs\Python\Python310\Scripts\homr.exe")
+        if py310_homr.exists():
+            return [str(py310_homr), image_path]
+        return [sys.executable, "-m", "homr", image_path]
+
+    def run(self, image_path: str, debug_dir: str = "") -> dict:
+        tmp_dir = tempfile.mkdtemp(prefix="score_to_mml_homr_")
+        try:
+            # 입력 파일을 tmp_dir에 복사 (출력이 입력과 같은 디렉토리에 생성되는 경우 대비)
+            img_filename = Path(image_path).name
+            tmp_input = str(Path(tmp_dir) / img_filename)
+            shutil.copy2(image_path, tmp_input)
+
+            cmd = self._build_command(tmp_input)
+            # PYTHONUTF8=1: 한국어 Windows CP949 환경에서 musicxml 패키지 인코딩 오류 방지
+            run_env = {**os.environ, "PYTHONUTF8": "1"}
+            try:
+                proc = subprocess.run(
+                    cmd,
+                    capture_output=True,
+                    text=True,
+                    timeout=300,
+                    cwd=tmp_dir,
+                    env=run_env,
+                )
+            except FileNotFoundError as e:
+                raise RuntimeError(
+                    f"HOMR 실행 파일을 찾을 수 없습니다: '{cmd[0]}'\n"
+                    f"  설치: pip install homr\n"
+                    f"  또는 HOMR_CMD 환경변수를 설정하세요.\n"
+                    f"  원본 오류: {e}"
+                )
+            except subprocess.TimeoutExpired:
+                raise RuntimeError(
+                    f"HOMR 실행 타임아웃 (300초 초과)\n"
+                    f"  입력 파일: {image_path}"
+                )
+
+            xml_path = _find_any_musicxml(tmp_dir, Path(image_path).stem)
+            if xml_path is None:
+                stdout_tail = proc.stdout[-400:] if proc.stdout else "(없음)"
+                stderr_tail = proc.stderr[-400:] if proc.stderr else "(없음)"
+                raise RuntimeError(
+                    f"HOMR 출력에서 MusicXML 파일을 찾을 수 없습니다.\n"
+                    f"  출력 디렉토리: {tmp_dir}\n"
+                    f"  returncode: {proc.returncode}\n"
+                    f"  STDOUT:\n{stdout_tail}\n"
+                    f"  STDERR:\n{stderr_tail}"
+                )
+
+            if debug_dir:
+                dest = Path(debug_dir) / Path(xml_path).name
+                shutil.copy2(xml_path, str(dest))
+
+            xml_string = _read_musicxml(xml_path)
+            return {
+                "format": "musicxml",
+                "data": xml_string,
+                "source_path": image_path,
+                "metadata": {
+                    "musicxml_path": xml_path,
+                    "homr_stdout_tail": proc.stdout[-300:] if proc.stdout else "",
+                    "homr_stderr_tail": proc.stderr[-300:] if proc.stderr else "",
+                    "homr_returncode": proc.returncode,
+                },
+            }
+        finally:
+            shutil.rmtree(tmp_dir, ignore_errors=True)
+
+    def is_available(self) -> bool:
+        if self.cmd:
+            p = Path(self.cmd)
+            if p.is_absolute():
+                return p.exists()
+            return shutil.which(self.cmd) is not None
+        # 현재 Python 환경 homr.exe 탐색
+        homr_exe = Path(sys.executable).parent / "Scripts" / "homr.exe"
+        if homr_exe.exists():
+            return True
+        # Python 3.10 환경 탐색 (homr는 3.10+ 전용)
+        py310_homr = Path(r"C:\Users\Park\AppData\Local\Programs\Python\Python310\Scripts\homr.exe")
+        if py310_homr.exists():
+            return True
+        return False
+
+
+class OeMeROMRAdapter(OMRAdapter):
+    """
+    OeMeR (oemer) 기반 OMR 어댑터.
+
+    설치: pip install oemer
+    참고: https://github.com/BreezeWhite/oemer
+
+    환경변수:
+      OEMER_CMD: oemer 실행 명령 (기본: oemer)
+                 예) OEMER_CMD=oemer  또는  OEMER_CMD=C:\\path\\to\\oemer.exe
+
+    출력: 입력 이미지와 같은 디렉토리에 <stem>.musicxml 생성
+    """
+
+    def __init__(self, cmd: str = ""):
+        self.cmd = cmd or os.environ.get("OEMER_CMD", "oemer")
+
+    def _build_command(self, image_path: str) -> list[str]:
+        return [self.cmd, image_path]
+
+    def run(self, image_path: str, debug_dir: str = "") -> dict:
+        tmp_dir = tempfile.mkdtemp(prefix="score_to_mml_oemer_")
+        try:
+            # 입력 파일을 tmp_dir에 복사 (출력이 입력과 같은 디렉토리에 생성됨)
+            img_filename = Path(image_path).name
+            tmp_input = str(Path(tmp_dir) / img_filename)
+            shutil.copy2(image_path, tmp_input)
+
+            cmd = self._build_command(tmp_input)
+            try:
+                proc = subprocess.run(
+                    cmd,
+                    capture_output=True,
+                    text=True,
+                    timeout=600,  # 첫 실행 시 모델 다운로드 포함해 최대 10분
+                    cwd=tmp_dir,
+                )
+            except FileNotFoundError as e:
+                raise RuntimeError(
+                    f"OeMeR 실행 파일을 찾을 수 없습니다: '{cmd[0]}'\n"
+                    f"  설치: pip install oemer\n"
+                    f"  또는 OEMER_CMD 환경변수를 설정하세요.\n"
+                    f"  원본 오류: {e}"
+                )
+            except subprocess.TimeoutExpired:
+                raise RuntimeError(
+                    f"OeMeR 실행 타임아웃 (600초 초과)\n"
+                    f"  입력 파일: {image_path}\n"
+                    f"  첫 실행 시 딥러닝 모델 다운로드가 필요할 수 있습니다.\n"
+                    f"  `oemer <image>` 를 직접 실행해서 모델을 먼저 다운로드하세요."
+                )
+
+            xml_path = _find_any_musicxml(tmp_dir, Path(image_path).stem)
+            if xml_path is None:
+                stdout_tail = proc.stdout[-400:] if proc.stdout else "(없음)"
+                stderr_tail = proc.stderr[-400:] if proc.stderr else "(없음)"
+                raise RuntimeError(
+                    f"OeMeR 출력에서 MusicXML 파일을 찾을 수 없습니다.\n"
+                    f"  출력 디렉토리: {tmp_dir}\n"
+                    f"  returncode: {proc.returncode}\n"
+                    f"  STDOUT:\n{stdout_tail}\n"
+                    f"  STDERR:\n{stderr_tail}"
+                )
+
+            if debug_dir:
+                dest = Path(debug_dir) / Path(xml_path).name
+                shutil.copy2(xml_path, str(dest))
+
+            xml_string = _read_musicxml(xml_path)
+            return {
+                "format": "musicxml",
+                "data": xml_string,
+                "source_path": image_path,
+                "metadata": {
+                    "musicxml_path": xml_path,
+                    "oemer_stdout_tail": proc.stdout[-300:] if proc.stdout else "",
+                    "oemer_stderr_tail": proc.stderr[-300:] if proc.stderr else "",
+                    "oemer_returncode": proc.returncode,
+                },
+            }
+        finally:
+            shutil.rmtree(tmp_dir, ignore_errors=True)
+
+    def is_available(self) -> bool:
+        if self.cmd:
+            return shutil.which(self.cmd) is not None or Path(self.cmd).exists()
+        return False
+
+
+# ---------------------------------------------------------------------------
+# 팩토리
+# ---------------------------------------------------------------------------
+
+def get_adapter(mock_mode: bool = True) -> OMRAdapter:
+    """
+    옵션에 따라 적절한 OMR 어댑터를 반환.
+
+    mock_mode=True  → MockOMRAdapter (환경변수 불필요)
+    mock_mode=False → AudiverisOMRAdapter
+                      AUDIVERIS_BIN 또는 AUDIVERIS_JAR 환경변수 필요
+    """
+    if mock_mode:
+        return MockOMRAdapter()
+
+    bin_path = os.environ.get("AUDIVERIS_BIN", "")
+    jar_path = os.environ.get("AUDIVERIS_JAR", "")
+
+    if not bin_path and not jar_path:
+        raise RuntimeError(
+            "Audiveris 환경변수가 설정되지 않았습니다.\n"
+            "다음 중 하나를 설정하고 다시 실행하세요:\n\n"
+            "  [직접 실행 방식]\n"
+            "  set AUDIVERIS_BIN=C:\\path\\to\\Audiveris.exe    (Windows)\n"
+            "  export AUDIVERIS_BIN=/path/to/audiveris         (Linux/Mac)\n\n"
+            "  [JAR 방식 (java 필요)]\n"
+            "  set AUDIVERIS_JAR=C:\\path\\to\\Audiveris.jar     (Windows)\n"
+            "  export AUDIVERIS_JAR=/path/to/Audiveris.jar     (Linux/Mac)"
+        )
+
+    adapter = AudiverisOMRAdapter(jar_path=jar_path, bin_path=bin_path)
+
+    if not adapter.is_available():
+        if bin_path:
+            hint = f"AUDIVERIS_BIN='{bin_path}' 파일이 존재하는지 확인하세요."
+        else:
+            hint = (
+                f"AUDIVERIS_JAR='{jar_path}' 파일이 존재하는지,\n"
+                f"  java가 PATH에 있는지 확인하세요. (java -version 으로 테스트)"
+            )
+        raise RuntimeError(f"Audiveris를 실행할 수 없습니다.\n  {hint}")
+
+    return adapter
+
+
+def get_engine_adapter(engine_name: str) -> OMRAdapter:
+    """
+    엔진 이름으로 어댑터를 반환.
+
+    compare_omr_engines()에서 멀티 엔진 실행 시 사용.
+    엔진이 설치되지 않은 경우 RuntimeError 발생 (caller에서 처리).
+
+    지원 엔진:
+      "mock"      → MockOMRAdapter
+      "audiveris" → AudiverisOMRAdapter (AUDIVERIS_BIN 또는 AUDIVERIS_JAR 필요)
+      "homr"      → HOMROMRAdapter (pip install homr 또는 HOMR_CMD 필요)
+      "oemer"     → OeMeROMRAdapter (pip install oemer 또는 OEMER_CMD 필요)
+      "clarity"   → ClarityOMRAdapter (CLARITY_OMR_DIR 필요, GPU 자동 감지)
+    """
+    name = engine_name.lower().strip()
+
+    if name == "mock":
+        return MockOMRAdapter()
+
+    if name == "audiveris":
+        return get_adapter(mock_mode=False)
+
+    if name == "homr":
+        adapter = HOMROMRAdapter()
+        if not adapter.is_available():
+            raise RuntimeError(
+                "HOMR를 실행할 수 없습니다.\n"
+                "  설치: pip install homr\n"
+                "  또는 HOMR_CMD 환경변수를 설정하세요."
+            )
+        return adapter
+
+    if name == "oemer":
+        adapter = OeMeROMRAdapter()
+        if not adapter.is_available():
+            raise RuntimeError(
+                "OeMeR를 실행할 수 없습니다.\n"
+                "  설치: pip install oemer\n"
+                "  또는 OEMER_CMD 환경변수를 설정하세요."
+            )
+        return adapter
+
+    if name == "clarity":
+        adapter = ClarityOMRAdapter()
+        if not adapter.is_available():
+            raise RuntimeError(
+                "Clarity-OMR를 실행할 수 없습니다.\n"
+                "  1. git clone https://github.com/clquwu/Clarity-OMR\n"
+                "  2. pip install -r Clarity-OMR/requirements.txt\n"
+                "  3. set CLARITY_OMR_DIR=C:\\path\\to\\Clarity-OMR\n"
+                "  GPU 사용: pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121"
+            )
+        return adapter
+
+    raise RuntimeError(
+        f"알 수 없는 엔진 이름: '{engine_name}'\n"
+        f"  지원 엔진: mock, audiveris, homr, oemer, clarity"
+    )

core/part_splitter.py

@@ -0,0 +1,151 @@
+"""
+core/part_splitter.py
+
+NoteEvent 리스트를 N개 파트로 분배.
+
+현재 전략: Greedy 피치 범위 기반 분배
+  - Part 1: 가장 높은 피치 그룹 (주 멜로디)
+  - Part 2: 중간 피치 그룹 (화음/반주)
+  - Part 3: 가장 낮은 피치 그룹 (베이스)
+
+교체 가능성: 이 함수의 시그니처를 유지하면서
+  더 정교한 알고리즘(staff/voice 기반, 음역대 분석 등)으로 교체 가능.
+"""
+
+from __future__ import annotations
+
+from .models import NoteEvent
+
+
+def _count_max_simultaneous(notes: list[NoteEvent]) -> int:
+    """최대 동시 발음 수 계산 (part_count 자동 감지용)."""
+    if not notes:
+        return 1
+    events: list[tuple[float, int]] = []
+    for n in notes:
+        events.append((n.start, 1))
+        events.append((n.start + n.duration, -1))
+    events.sort()
+    max_count = current = 0
+    for _, delta in events:
+        current += delta
+        max_count = max(max_count, current)
+    return max(1, max_count)
+
+
+def split_parts(
+    notes: list[NoteEvent],
+    part_count: int = 0,
+) -> list[list[NoteEvent]]:
+    """
+    NoteEvent 리스트를 part_count개 파트로 분배.
+
+    Args:
+        notes: 전체 NoteEvent 리스트
+        part_count: 분배할 파트 수 (기본 3)
+
+    Returns:
+        파트별 NoteEvent 리스트의 리스트.
+        길이는 항상 part_count이며, 비어있는 파트는 빈 리스트.
+    """
+    if part_count <= 0:
+        part_count = _count_max_simultaneous(notes)
+
+    if not notes:
+        return [[] for _ in range(part_count)]
+
+    # part_hint가 지정된 경우 우선 사용
+    if any(n.part_hint is not None for n in notes):
+        return _split_by_hint(notes, part_count)
+
+    staffs = {n.staff for n in notes}
+    voices = {n.voice for n in notes}
+
+    # staff도 1개이고 voice도 1개면 단선율 → Part 1에 전부
+    if len(staffs) == 1 and len(voices) == 1:
+        parts = [[] for _ in range(part_count)]
+        parts[0].extend(sorted(notes, key=lambda n: n.start))
+        return parts
+
+    # staff 또는 voice가 여러 개면 staff+voice 기반 분배
+    return _split_by_staff_and_voice(notes, part_count)
+
+    # fallback: 피치 범위 기반 greedy 분배
+    return _split_by_pitch_range(notes, part_count)
+
+
+def _split_by_hint(notes: list[NoteEvent], part_count: int) -> list[list[NoteEvent]]:
+    """part_hint 값에 따라 분배."""
+    parts: list[list[NoteEvent]] = [[] for _ in range(part_count)]
+    for note in notes:
+        hint = note.part_hint
+        if hint is not None and 1 <= hint <= part_count:
+            parts[hint - 1].append(note)
+        else:
+            parts[0].append(note)  # 미지정은 Part 1으로
+    return parts
+
+
+def _split_by_staff_and_voice(notes: list[NoteEvent], part_count: int) -> list[list[NoteEvent]]:
+    """
+    staff + voice 조합으로 파트 분배.
+
+    조합 순서 (높은 피치 우선): staff1/voice1, staff1/voice2, staff2/voice1, ...
+    """
+    # (staff, voice) 조합을 평균 피치 기준으로 정렬 (높은 것이 Part 1)
+    combos: dict[tuple[int, int], list[NoteEvent]] = {}
+    for note in notes:
+        key = (note.staff, note.voice)
+        combos.setdefault(key, []).append(note)
+
+    def avg_pitch(note_list: list[NoteEvent]) -> float:
+        pitched = [n.pitch for n in note_list if n.pitch > 0]
+        return sum(pitched) / len(pitched) if pitched else 0.0
+
+    sorted_combos = sorted(combos.values(), key=avg_pitch, reverse=True)
+
+    parts: list[list[NoteEvent]] = [[] for _ in range(part_count)]
+    for i, group in enumerate(sorted_combos):
+        idx = min(i, part_count - 1)
+        parts[idx].extend(group)
+
+    # 파트 내 start 기준 재정렬
+    for part in parts:
+        part.sort(key=lambda n: n.start)
+
+    return parts
+
+
+def _split_by_pitch_range(notes: list[NoteEvent], part_count: int) -> list[list[NoteEvent]]:
+    """
+    피치 범위 기준 greedy 분배.
+
+    전체 피치를 part_count 구간으로 나누어 분배.
+    """
+    pitched = [n for n in notes if n.pitch > 0]
+    rests = [n for n in notes if n.pitch == 0]
+
+    if not pitched:
+        parts: list[list[NoteEvent]] = [[] for _ in range(part_count)]
+        parts[part_count - 1].extend(rests)
+        return parts
+
+    min_pitch = min(n.pitch for n in pitched)
+    max_pitch = max(n.pitch for n in pitched)
+    pitch_span = max_pitch - min_pitch or 1
+
+    parts = [[] for _ in range(part_count)]
+    for note in pitched:
+        ratio = (note.pitch - min_pitch) / pitch_span
+        # 높은 피치 = 낮은 인덱스 (Part 1)
+        idx = part_count - 1 - int(ratio * (part_count - 0.01))
+        idx = max(0, min(idx, part_count - 1))
+        parts[idx].append(note)
+
+    # 쉼표는 Part 1에 배치
+    parts[0].extend(rests)
+
+    for part in parts:
+        part.sort(key=lambda n: n.start)
+
+    return parts

core/pdf_converter.py

@@ -0,0 +1,106 @@
+"""
+core/pdf_converter.py
+
+PDF 파일을 페이지별 이미지로 변환하는 모듈.
+
+사용 라이브러리: pymupdf (fitz)
+  - 설치: pip install pymupdf
+  - 외부 바이너리(Poppler 등) 불필요, Windows에서 바로 동작
+
+이 모듈의 역할:
+  - PDF 파일을 받아 각 페이지를 PNG 이미지로 렌더링
+  - 렌더링된 이미지 경로 리스트를 반환
+  - 이후 처리는 기존 이미지 파이프라인에 그대로 위임
+
+사이드이펙트:
+  - output_dir에 page_001.png, page_002.png ... 파일을 생성
+  - 임시 디렉토리 정리는 호출 측(pipeline.py)에서 담당
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class PDFConvertError(Exception):
+    """PDF 변환 오류."""
+    pass
+
+
+def convert_pdf_to_images(
+    pdf_path: str,
+    output_dir: str,
+    dpi: int = 150,
+) -> list[str]:
+    """
+    PDF 파일의 각 페이지를 PNG 이미지로 변환.
+
+    Args:
+        pdf_path:   입력 PDF 파일 경로
+        output_dir: 이미지를 저장할 디렉토리 경로 (없으면 생성)
+        dpi:        렌더링 해상도 (기본 150dpi, OMR 정밀도에 따라 300dpi 권장)
+
+    Returns:
+        페이지 순서대로 정렬된 이미지 파일 경로 리스트
+
+    Raises:
+        PDFConvertError: pymupdf 미설치, 파일 없음, 렌더링 실패 시
+    """
+    try:
+        import fitz  # pymupdf
+    except ImportError:
+        raise PDFConvertError(
+            "pymupdf가 설치되지 않았습니다. 설치 명령: pip install pymupdf"
+        )
+
+    pdf = Path(pdf_path)
+    if not pdf.exists():
+        raise PDFConvertError(f"PDF 파일을 찾을 수 없습니다: {pdf_path}")
+
+    out_dir = Path(output_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        doc = fitz.open(str(pdf))
+    except Exception as e:
+        raise PDFConvertError(f"PDF 열기 실패: {e}")
+
+    if doc.page_count == 0:
+        doc.close()
+        raise PDFConvertError(f"PDF에 페이지가 없습니다: {pdf_path}")
+
+    # 72dpi가 fitz 기본 단위 → dpi/72 배율
+    matrix = fitz.Matrix(dpi / 72, dpi / 72)
+    image_paths: list[str] = []
+
+    try:
+        for page_idx in range(doc.page_count):
+            page = doc[page_idx]
+            pixmap = page.get_pixmap(matrix=matrix)
+            img_path = out_dir / f"page_{page_idx + 1:03d}.png"
+            pixmap.save(str(img_path))
+            image_paths.append(str(img_path))
+    except Exception as e:
+        raise PDFConvertError(f"페이지 렌더링 실패 (page {page_idx + 1}): {e}")
+    finally:
+        doc.close()
+
+    return image_paths
+
+
+def get_pdf_page_count(pdf_path: str) -> int:
+    """PDF 파일의 페이지 수를 반환."""
+    try:
+        import fitz
+    except ImportError:
+        raise PDFConvertError(
+            "pymupdf가 설치되지 않았습니다. 설치 명령: pip install pymupdf"
+        )
+
+    try:
+        doc = fitz.open(pdf_path)
+        count = doc.page_count
+        doc.close()
+        return count
+    except Exception as e:
+        raise PDFConvertError(f"PDF 페이지 수 확인 실패: {e}")

core/pipeline.py

@@ -0,0 +1,1117 @@
+"""
+core/pipeline.py
+
+전체 변환 파이프라인의 단일 진입점.
+
+CLI와 Web API 모두 convert_score_to_mml()만 호출해야 한다.
+사이드이펙트(파일 저장, 콘솔 출력)는 이 함수에서 수행하지 않는다.
+
+파이프라인 흐름 — 이미지 입력:
+  입력 경로
+    → preprocess.preprocess_image()          파일 검증
+    → [preprocess.apply_preprocessing()]     OpenCV 전처리 (audiveris 모드 + enabled 시)
+    → omr_adapter.run()
+    → music_parser.parse_omr_result()
+    → part_splitter.split_parts()
+    → mml_converter.convert_parts_to_mml()
+    → ConvertResult
+
+파이프라인 흐름 — PDF 입력:
+  입력 경로
+    → pdf_converter.convert_pdf_to_images()  페이지별 PNG 생성
+    → 각 페이지에 대해:
+        [preprocess.apply_preprocessing()]   OpenCV 전처리 (audiveris 모드 + enabled 시)
+        → omr_adapter.run()
+        → music_parser.parse_omr_result()
+    → NoteEvent 시간축 이어붙이기 (page offset 누적)
+    → 전체 NoteEvent 병합
+    → part_splitter.split_parts()
+    → mml_converter.convert_parts_to_mml()
+    → ConvertResult  (임시 디렉토리 정리)
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+from .models import ConvertOptions, ConvertResult, NoteEvent, EngineRunResult, ComparisonReport
+from .preprocess import preprocess_image, apply_preprocessing, PreprocessError
+from .omr_adapter import get_adapter, get_engine_adapter, OMRAdapter
+from .music_parser import parse_omr_result, ParseError
+from .part_splitter import split_parts
+from .mml_converter import convert_parts_to_mml
+
+
+def _get_adapter_for_options(options: ConvertOptions) -> OMRAdapter:
+    """ConvertOptions의 engine/mock_mode 설정에 따라 적절한 어댑터를 반환."""
+    if options.engine:
+        return get_engine_adapter(options.engine)
+    return get_adapter(mock_mode=options.mock_mode)
+
+
+def convert_score_to_mml(
+    input_path: str,
+    options: Optional[ConvertOptions] = None,
+) -> ConvertResult:
+    """
+    이미지 또는 PDF 악보를 MML로 변환하는 메인 파이프라인 함수.
+
+    Args:
+        input_path: 입력 파일 경로 (PNG, JPG, PDF 등)
+        options:    변환 옵션. None이면 기본값 사용.
+
+    Returns:
+        ConvertResult: 성공 여부, 3파트 MML, 경고 목록, 디버그 정보
+    """
+    if options is None:
+        options = ConvertOptions()
+
+    debug_info: dict = {"input_path": input_path, "options": vars(options)}
+
+    ext = Path(input_path).suffix.lower()
+    if ext == ".pdf":
+        # Clarity-OMR은 PDF를 직접 처리 — 페이지 분할 불필요
+        if options.engine == "clarity":
+            return _process_pdf_direct(input_path, options, debug_info)
+        return _process_pdf(input_path, options, debug_info)
+    else:
+        return _process_image(input_path, options, debug_info)
+
+
+# ---------------------------------------------------------------------------
+# 내부 헬퍼
+# ---------------------------------------------------------------------------
+
+def _process_image(
+    input_path: str,
+    options: ConvertOptions,
+    debug_info: dict,
+) -> ConvertResult:
+    """단일 이미지 파일에 대한 변환 파이프라인."""
+    warnings: list[str] = []
+    debug_info["input_type"] = "image"
+
+    # debug_dir 준비 (options.debug_dir가 설정된 경우 실행별 하위 폴더 생성)
+    run_debug_dir = _prepare_run_debug_dir(input_path, options.debug_dir)
+    if run_debug_dir:
+        debug_info["debug_output_dir"] = run_debug_dir
+        shutil.copy2(input_path, str(Path(run_debug_dir) / ("00_original" + Path(input_path).suffix)))
+
+    # 1. 파일 검증
+    try:
+        image_info = preprocess_image(input_path)
+        debug_info["image_info"] = image_info
+    except PreprocessError as e:
+        return ConvertResult(success=False, warnings=[str(e)], debug_info=debug_info)
+
+    omr_input = image_info["preprocessed_path"]
+    preprocess_tmpdir = None
+
+    try:
+        # 2. OpenCV 전처리 (audiveris 모드 + preprocess_enabled 시)
+        if not options.mock_mode and options.preprocess_enabled:
+            preprocess_tmpdir = tempfile.mkdtemp(prefix="score_to_mml_pre_")
+            omr_input, pre_info, pre_warnings = _run_preprocess_step(
+                omr_input, preprocess_tmpdir, Path(input_path).stem, options,
+                debug_dir=run_debug_dir,
+            )
+            # 전처리 최종 결과 이미지를 debug_dir에 복사
+            if run_debug_dir and Path(omr_input).exists():
+                shutil.copy2(omr_input, str(Path(run_debug_dir) / "01_preprocessed_final.png"))
+            debug_info["preprocess_info"] = pre_info
+            warnings.extend(pre_warnings)
+        else:
+            debug_info["preprocess_info"] = {
+                "applied": False,
+                "reason": "mock mode" if options.mock_mode else "preprocess_enabled=False",
+            }
+
+        # 3~4. OMR + 파싱
+        try:
+            adapter = _get_adapter_for_options(options)
+        except RuntimeError as e:
+            return ConvertResult(success=False, warnings=[f"OMR 어댑터 초기화 실패: {e}"], debug_info=debug_info)
+        notes, omr_warnings, omr_debug, _ = _run_omr_and_parse(
+            omr_input, adapter, debug_dir=run_debug_dir
+        )
+        debug_info.update(omr_debug)
+        warnings.extend(omr_warnings)
+
+        if notes is None:
+            _save_debug_log(run_debug_dir, debug_info, warnings, result=None)
+            return ConvertResult(success=False, warnings=warnings, debug_info=debug_info)
+
+        result = _build_result(notes, options, warnings, debug_info)
+        _save_debug_log(run_debug_dir, debug_info, warnings, result=result)
+        return result
+
+    finally:
+        if preprocess_tmpdir:
+            shutil.rmtree(preprocess_tmpdir, ignore_errors=True)
+
+
+def _process_pdf_direct(
+    input_path: str,
+    options: ConvertOptions,
+    debug_info: dict,
+) -> ConvertResult:
+    """
+    PDF를 페이지 분할 없이 OMR 엔진에 직접 전달하는 경로.
+
+    Clarity-OMR처럼 PDF를 통째로 받는 엔진에 사용.
+    PDF → adapter.run(pdf) → MusicXML → NoteEvent → MML
+    """
+    warnings: list[str] = []
+    debug_info["input_type"] = "pdf_direct"
+
+    try:
+        adapter = _get_adapter_for_options(options)
+    except RuntimeError as e:
+        return ConvertResult(success=False, warnings=[f"OMR 어댑터 초기화 실패: {e}"], debug_info=debug_info)
+
+    notes, omr_warnings, omr_debug, _ = _run_omr_and_parse(input_path, adapter)
+    debug_info.update(omr_debug)
+    warnings.extend(omr_warnings)
+
+    if notes is None:
+        return ConvertResult(success=False, warnings=warnings, debug_info=debug_info)
+
+    return _build_result(notes, options, warnings, debug_info)
+
+
+def _process_pdf(
+    input_path: str,
+    options: ConvertOptions,
+    debug_info: dict,
+) -> ConvertResult:
+    """
+    PDF 입력 처리.
+
+    PDF → 페이지별 이미지 변환 → 각 페이지 OMR + 파싱 → NoteEvent 병합
+    """
+    from .pdf_converter import convert_pdf_to_images, PDFConvertError
+
+    warnings: list[str] = []
+    debug_info["input_type"] = "pdf"
+
+    # PDF → 페이지 이미지
+    tmp_dir = tempfile.mkdtemp(prefix="score_to_mml_pdf_")
+    try:
+        try:
+            page_image_paths = convert_pdf_to_images(
+                input_path, tmp_dir, dpi=options.pdf_dpi
+            )
+        except PDFConvertError as e:
+            return ConvertResult(
+                success=False,
+                warnings=[f"PDF 변환 실패: {e}"],
+                debug_info=debug_info,
+            )
+
+        debug_info["pdf_page_count"] = len(page_image_paths)
+
+        adapter = _get_adapter_for_options(options)
+        all_notes: list[NoteEvent] = []
+        processed_pages: list[int] = []
+        page_offset: float = 0.0
+
+        for page_num, page_path in enumerate(page_image_paths, start=1):
+            omr_page_input = page_path
+            page_pre_info: dict = {"applied": False, "reason": "mock mode" if options.mock_mode else "preprocess_enabled=False"}
+
+            if not options.mock_mode and options.preprocess_enabled:
+                stem = Path(page_path).stem
+                omr_page_input, page_pre_info, page_pre_warns = _run_preprocess_step(
+                    page_path, tmp_dir, stem, options
+                )
+                for w in page_pre_warns:
+                    warnings.append(f"[page {page_num}] {w}")
+
+            page_notes, page_warnings, page_debug, _ = _run_omr_and_parse(
+                omr_page_input, adapter
+            )
+            page_debug["preprocess_info"] = page_pre_info
+            debug_info[f"page_{page_num}"] = page_debug
+
+            for w in page_warnings:
+                warnings.append(f"[page {page_num}] {w}")
+
+            # 정책: 어떤 페이지라도 OMR/파싱에 실패하면 전체 실패.
+            # 이유: 부분 결과로 만들어진 MML은 원곡과 다를 수 있어 오해를 유발함.
+            if page_notes is None:
+                debug_info["processed_pages"] = processed_pages
+                debug_info["failed_page"] = page_num
+                debug_info["note_count"] = len(all_notes)
+                return ConvertResult(
+                    success=False,
+                    warnings=warnings + [
+                        f"페이지 {page_num}/{len(page_image_paths)} 처리 실패로 전체 중단됨. "
+                        f"(실패 이유는 위 warnings 참조)"
+                    ],
+                    debug_info=debug_info,
+                )
+
+            # 시간축 이어붙이기
+            shifted = _shift_notes(page_notes, page_offset)
+            all_notes.extend(shifted)
+
+            if shifted:
+                page_offset = max(n.start + n.duration for n in shifted)
+            else:
+                page_offset += 4.0  # 음표 없는 페이지: 1마디(4박) 여백
+
+            processed_pages.append(page_num)
+
+        debug_info["processed_pages"] = processed_pages
+        debug_info["failed_page"] = None
+        debug_info["note_count"] = len(all_notes)
+
+        return _build_result(all_notes, options, warnings, debug_info)
+
+    finally:
+        # 임시 이미지 파일 정리
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+
+
+def _run_preprocess_step(
+    input_path: str,
+    output_dir: str,
+    stem: str,
+    options: ConvertOptions,
+    debug_dir: str = "",
+) -> tuple:
+    """
+    OpenCV 전처리를 실행하고 (omr_input_path, pre_info, warnings)를 반환.
+
+    전처리 실패 시: 원본 경로 + 경고 반환 (pipeline 중단하지 않음).
+    """
+    out_path = str(Path(output_dir) / f"{stem}_pre.png")
+    try:
+        pre_info = apply_preprocessing(input_path, out_path, options, debug_dir=debug_dir)
+        return out_path, pre_info, []
+    except PreprocessError as e:
+        warn = f"전처리 실패, 원본 이미지 사용: {e}"
+        fallback_info = {"applied": False, "reason": str(e)}
+        return input_path, fallback_info, [warn]
+
+
+def _run_omr_and_parse(
+    image_path: str,
+    adapter: OMRAdapter,
+    debug_dir: str = "",
+) -> tuple[Optional[list[NoteEvent]], list[str], dict, Optional[str]]:
+    """
+    단일 이미지에 대해 OMR 실행 + NoteEvent 파싱.
+
+    Returns:
+        (notes, warnings, debug_info, raw_xml)
+        notes가 None이면 실패.
+        raw_xml: musicxml 형식일 때 XML 문자열, 아니면 None.
+    """
+    warnings: list[str] = []
+    debug: dict = {}
+
+    try:
+        omr_result = adapter.run(image_path, debug_dir=debug_dir)
+        debug["omr_format"] = omr_result.get("format")
+        debug["omr_metadata"] = omr_result.get("metadata", {})
+    except (RuntimeError, NotImplementedError) as e:
+        return None, [f"OMR 실패: {e}"], debug, None
+
+    raw_xml: Optional[str] = None
+    if omr_result.get("format") == "musicxml":
+        raw_xml = omr_result.get("data")
+
+    try:
+        notes, parse_meta = parse_omr_result(omr_result)
+        debug["note_count"] = len(notes)
+        debug["tempo"] = parse_meta.get("tempo", 0)
+    except ParseError as e:
+        return None, [f"파싱 실패: {e}"], debug, None
+
+    if not notes:
+        warnings.append("음표를 찾지 못했습니다. 입력 이미지를 확인하세요.")
+
+    return notes, warnings, debug, raw_xml
+
+
+def _assign_chord_parts(notes: list[NoteEvent], max_parts: int = 3) -> list[NoteEvent]:
+    """
+    동시에 시작하는 모든 음표를 피치 순위 기반으로 파트에 배분.
+
+    같은 시작 시간의 음표들을 피치 내림차순 정렬 후:
+      - 1위(최고음) → part_hint=1
+      - 2위(중간음) → part_hint=2
+      - 3위(최저음) → part_hint=3
+      - 4위 이하    → 제거
+
+    staff/voice 구분 없이 전체 시간축 기준으로 처리하므로
+    왼손/오른손 구분 대신 '동시에 울리는 음' 기준으로 파트가 나뉜다.
+    """
+    from dataclasses import replace as dc_replace
+
+    # start time 0.01박 단위로 그룹화
+    groups: dict[int, list[NoteEvent]] = {}
+    for n in notes:
+        key = round(n.start * 100)
+        groups.setdefault(key, []).append(n)
+
+    result: list[NoteEvent] = []
+    for group in groups.values():
+        rests  = [n for n in group if n.pitch == 0]
+        pitches = sorted(
+            [n for n in group if n.pitch != 0],
+            key=lambda n: n.pitch,
+            reverse=True,  # 높은 음 먼저
+        )
+        for i, note in enumerate(pitches[:max_parts]):
+            result.append(dc_replace(note, part_hint=i + 1))
+        result.extend(rests)
+
+    return result
+
+
+def _shift_notes(notes: list[NoteEvent], offset: float) -> list[NoteEvent]:
+    """
+    NoteEvent 리스트의 start 시각에 offset을 더한 새 리스트를 반환.
+    원본 객체는 변경하지 않는다.
+    """
+    if offset == 0.0:
+        return list(notes)
+    from dataclasses import replace
+    return [replace(n, start=n.start + offset) for n in notes]
+
+
+def _build_result(
+    notes: list[NoteEvent],
+    options: ConvertOptions,
+    warnings: list[str],
+    debug_info: dict,
+) -> ConvertResult:
+    """파트 분배 → MML 변환 → ConvertResult 생성."""
+    notes = _assign_chord_parts(notes, max_parts=3)
+    parts = split_parts(notes, part_count=options.part_count)
+    debug_info["part_note_counts"] = [len(p) for p in parts]
+
+    tempo = debug_info.get("tempo", 0)
+    mml, part_mmls, mml_warnings = convert_parts_to_mml(
+        parts, prefer_sharps=options.prefer_sharps, tempo=tempo
+    )
+    warnings.extend(mml_warnings)
+
+    if options.strict_mode and warnings:
+        return ConvertResult(success=False, warnings=warnings, debug_info=debug_info)
+
+    while len(part_mmls) < 3:
+        part_mmls.append("MML@r1;")
+
+    return ConvertResult(
+        success=True,
+        mml=mml,
+        part1=part_mmls[0],
+        part2=part_mmls[1],
+        part3=part_mmls[2],
+        warnings=warnings,
+        debug_info=debug_info,
+    )
+
+
+# ---------------------------------------------------------------------------
+# 멀티 이미지 → MML 파이프라인 (mxl_mml_converter 경로)
+# ---------------------------------------------------------------------------
+
+def convert_images_to_mml_parts(
+    image_paths: list[str],
+    options: Optional[ConvertOptions] = None,
+    progress_callback=None,
+    mxl_save_dir: str = "",
+) -> tuple[list[str], list[str]]:
+    """
+    여러 이미지(PNG 등)를 순서대로 MML 파트 리스트로 변환.
+
+    각 이미지를 Audiveris OMR로 처리 → MusicXML 수집
+    → mxl_mml_converter.convert_xml_pages_to_mml_parts()로 합본 변환.
+
+    Args:
+        image_paths:       입력 이미지 경로 목록 (페이지 순서)
+        options:           변환 옵션. None이면 audiveris/no-preprocess 기본값 사용.
+        progress_callback: (page_idx, total, message) 형태의 진행 콜백 (선택)
+
+    Returns:
+        (mml_parts, warnings)
+        mml_parts: ["MML@...;", "MML@...;", ...]
+    """
+    from .mxl_mml_converter import convert_xml_pages_to_mml_parts
+
+    if options is None:
+        options = ConvertOptions(mock_mode=False, preprocess_enabled=False, engine="audiveris")
+
+    warnings: list[str] = []
+    xml_strings: list[str] = []
+    total = len(image_paths)
+
+    try:
+        adapter = _get_adapter_for_options(options)
+    except RuntimeError as e:
+        return ["MML@r1;"], [f"OMR 어댑터 초기화 실패: {e}"]
+
+    pre_tmp = None
+    if not options.mock_mode and options.preprocess_enabled:
+        pre_tmp = tempfile.mkdtemp(prefix="score_to_mml_pre_")
+
+    try:
+        for i, image_path in enumerate(image_paths, start=1):
+            if progress_callback:
+                progress_callback(i, total, f"페이지 {i}/{total} OMR 처리 중: {Path(image_path).name}")
+
+            omr_input = image_path
+            if pre_tmp:
+                stem = Path(image_path).stem
+                try:
+                    omr_input, _, pre_warns = _run_preprocess_step(image_path, pre_tmp, stem, options)
+                    for w in pre_warns:
+                        warnings.append(f"[페이지 {i}] {w}")
+                except Exception as e:
+                    warnings.append(f"[페이지 {i}] 전처리 실패, 원본 사용: {e}")
+
+            try:
+                omr_result = adapter.run(omr_input)
+            except (RuntimeError, NotImplementedError) as e:
+                return ["MML@r1;"], warnings + [f"페이지 {i} OMR 실패: {e}"]
+
+            if omr_result.get("format") != "musicxml":
+                return ["MML@r1;"], warnings + [
+                    f"페이지 {i}: musicxml 형식이 아닌 결과 ({omr_result.get('format')})"
+                ]
+
+            xml_data = omr_result["data"]
+            xml_strings.append(xml_data)
+
+            if mxl_save_dir:
+                save_dir = Path(mxl_save_dir)
+                save_dir.mkdir(parents=True, exist_ok=True)
+                stem = Path(image_path).stem
+                mxl_path = save_dir / f"{stem}.mxl"
+                mxl_path.write_text(xml_data, encoding="utf-8")
+
+        if progress_callback:
+            progress_callback(total, total, "MML 변환 중...")
+
+        mml_parts, conv_warnings = convert_xml_pages_to_mml_parts(xml_strings)
+        warnings.extend(conv_warnings)
+        return mml_parts, warnings
+
+    finally:
+        if pre_tmp:
+            shutil.rmtree(pre_tmp, ignore_errors=True)
+
+
+# ---------------------------------------------------------------------------
+# 멀티 엔진 비교 파이프라인
+# ---------------------------------------------------------------------------
+
+def compare_omr_engines(
+    input_path: Union[str, list[str]],
+    engine_names: list,
+    options: Optional[ConvertOptions] = None,
+    save_dir: str = "",
+) -> ComparisonReport:
+    """
+    같은 입력 파일을 여러 OMR 엔진으로 순차 실행하고 결과를 비교 리포트로 반환.
+
+    Args:
+        input_path:    입력 악보 파일 경로 (이미지, PDF, 또는 여러 이미지 경로 list)
+        engine_names:  실행할 엔진 이름 목록 (예: ["audiveris", "homr", "oemer"])
+        options:       변환 옵션. None이면 기본값 사용.
+        save_dir:      결과 저장 디렉토리. 지정 시 각 엔진별 하위 폴더에 산출물 저장.
+
+    Returns:
+        ComparisonReport: 엔진별 EngineRunResult 포함 비교 결과
+
+    중요:
+        comparison_summary와 heuristic_summary는 참고 지표입니다.
+        최종 품질 판단은 사용자가 직접 결과를 확인해야 합니다.
+    """
+    if options is None:
+        options = ConvertOptions()
+
+    ts = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+    input_label = " + ".join(input_path) if isinstance(input_path, list) else input_path
+    report = ComparisonReport(
+        input_file=input_label,
+        timestamp=ts,
+        user_review_priority=True,
+    )
+
+    # 저장 디렉토리 준비
+    if save_dir:
+        Path(save_dir).mkdir(parents=True, exist_ok=True)
+
+    for engine_name in engine_names:
+        engine_save_dir = ""
+        if save_dir:
+            engine_save_dir = str(Path(save_dir) / engine_name)
+            Path(engine_save_dir).mkdir(parents=True, exist_ok=True)
+
+        run_result = _run_single_engine(
+            input_path=input_path,
+            engine_name=engine_name,
+            options=options,
+            save_dir=engine_save_dir,
+        )
+        report.runs.append(run_result)
+
+    # 비교 요약 생성
+    report.comparison_summary = _build_comparison_summary(report)
+    report.notes_for_manual_review = _collect_manual_review_notes(report)
+    report.suggested_engine = _suggest_engine(report)  # 참고용만
+
+    # 리포트 저장
+    if save_dir:
+        _save_comparison_report(save_dir, report)
+
+    return report
+
+
+def _run_single_engine(
+    input_path: Union[str, list[str]],
+    engine_name: str,
+    options: ConvertOptions,
+    save_dir: str,
+) -> EngineRunResult:
+    """
+    단일 엔진으로 전체 파이프라인을 실행하고 EngineRunResult를 반환.
+
+    input_path가 list[str]이면 여러 이미지를 순서대로 이어붙임.
+    실패 시에도 구조화된 EngineRunResult를 반환한다 (예외를 밖으로 전파하지 않음).
+    """
+    result = EngineRunResult(engine_name=engine_name, success=False)
+
+    # 어댑터 초기화
+    try:
+        adapter = get_engine_adapter(engine_name)
+    except RuntimeError as e:
+        result.stage = "init"
+        result.error_message = str(e)
+        return result
+
+    # 전처리 + OMR + 파싱 + MML 변환
+    warnings: list[str] = []
+    notes: Optional[list[NoteEvent]] = None
+
+    is_mock = (engine_name == "mock")
+
+    preprocess_tmpdir = None
+    try:
+        # 입력 타입별 image_paths 결정
+        if isinstance(input_path, list):
+            image_paths = input_path
+            debug_info: dict = {"input_path": image_paths, "engine": engine_name, "input_type": "multi_image"}
+        elif Path(input_path).suffix.lower() == ".pdf":
+            debug_info = {"input_path": input_path, "engine": engine_name}
+            image_paths, pdf_warn = _convert_pdf_for_engine(input_path, options)
+            warnings.extend(pdf_warn)
+            debug_info["input_type"] = "pdf"
+            debug_info["pdf_page_count"] = len(image_paths)
+            if not image_paths:
+                result.stage = "preprocess"
+                result.error_message = "PDF를 이미지로 변환하지 못했습니다."
+                result.warnings = warnings
+                return result
+            # 페이지 필터 적용 (pdf_pages가 지정된 경우)
+            if options.pdf_pages:
+                total = len(image_paths)
+                page_specs = options.pdf_pages
+                # 음수값은 "해당 페이지 제외" 의미 (--skip-pages only)
+                if all(p < 0 for p in page_specs):
+                    skip = {-p for p in page_specs}
+                    filtered = [img for i, img in enumerate(image_paths, 1) if i not in skip]
+                else:
+                    filtered = []
+                    for p in page_specs:
+                        if 1 <= p <= total:
+                            filtered.append(image_paths[p - 1])
+                        else:
+                            warnings.append(f"페이지 {p}는 범위를 벗어납니다 (전체 {total}페이지). 건너뜀.")
+                if not filtered:
+                    result.stage = "preprocess"
+                    result.error_message = f"지정한 페이지가 모두 범위를 벗어납니다 (전체 {total}페이지)."
+                    result.warnings = warnings
+                    return result
+                debug_info["pdf_selected_pages"] = options.pdf_pages
+                image_paths = filtered
+        else:
+            image_paths = [input_path]
+            debug_info = {"input_path": input_path, "engine": engine_name, "input_type": "image"}
+
+        all_notes: list[NoteEvent] = []
+        all_xml_strings: list[str] = []   # musicxml 형식일 때 페이지별 XML 수집
+        page_offset = 0.0
+
+        for page_idx, img_path in enumerate(image_paths):
+            page_num = page_idx + 1
+            omr_input = img_path
+
+            # 전처리 (mock 아닌 경우 + enabled)
+            if not is_mock and options.preprocess_enabled:
+                preprocess_tmpdir = preprocess_tmpdir or tempfile.mkdtemp(prefix="score_to_mml_cmp_pre_")
+                stem = Path(img_path).stem
+                omr_input, pre_info, pre_warns = _run_preprocess_step(
+                    img_path, preprocess_tmpdir, stem, options,
+                    debug_dir=save_dir,
+                )
+                for w in pre_warns:
+                    warnings.append(f"[page {page_num}] {w}")
+                debug_info[f"page_{page_num}_preprocess"] = pre_info
+            else:
+                debug_info[f"page_{page_num}_preprocess"] = {
+                    "applied": False,
+                    "reason": "mock mode" if is_mock else "preprocess_enabled=False",
+                }
+
+            # OMR + 파싱
+            page_notes, omr_warns, omr_debug, raw_xml = _run_omr_and_parse(
+                omr_input, adapter, debug_dir=save_dir
+            )
+            for w in omr_warns:
+                warnings.append(f"[page {page_num}] {w}")
+            debug_info[f"page_{page_num}_omr"] = omr_debug
+
+            if page_notes is None:
+                result.stage = "omr"
+                result.error_message = f"페이지 {page_num} OMR/파싱 실패: " + "; ".join(omr_warns)
+                result.warnings = warnings
+                result.debug_info = debug_info
+                return result
+
+            if raw_xml:
+                all_xml_strings.append(raw_xml)
+
+            shifted = _shift_notes(page_notes, page_offset)
+            all_notes.extend(shifted)
+            if shifted:
+                page_offset = max(n.start + n.duration for n in shifted)
+            else:
+                page_offset += 4.0
+
+        notes = all_notes
+        debug_info["note_count"] = len(notes)
+
+        # MML 변환
+        # musicxml 형식이면 tick 기반 정수 변환기 사용, 아니면 기존 float 변환기 fallback
+        try:
+            if all_xml_strings and len(all_xml_strings) == len(image_paths):
+                from .mxl_mml_converter import convert_xml_pages_to_mml_parts
+                mml_list, mml_warns = convert_xml_pages_to_mml_parts(all_xml_strings)
+                warnings.extend(mml_warns)
+                # part_note_counts는 NoteEvent 기준으로 근사 표시
+                parts_approx = split_parts(notes, part_count=len(mml_list))
+                debug_info["part_note_counts"] = [len(p) for p in parts_approx]
+                debug_info["mml_converter"] = "mxl_mml_converter (tick-based)"
+            else:
+                parts = split_parts(notes, part_count=options.part_count)
+                _combined_mml, mml_list, mml_warns = convert_parts_to_mml(parts, prefer_sharps=options.prefer_sharps)
+                warnings.extend(mml_warns)
+                debug_info["part_note_counts"] = [len(p) for p in parts]
+                debug_info["mml_converter"] = "mml_converter (float-based, fallback)"
+            while len(mml_list) < 3:
+                mml_list.append("MML@r1;")
+        except Exception as e:
+            result.stage = "convert"
+            result.error_message = f"MML 변환 실패: {e}"
+            result.warnings = warnings
+            result.debug_info = debug_info
+            return result
+
+        # EngineRunResult 채우기
+        notes_dump = _build_notes_dump(notes)
+        chord_count = _count_chords(notes)
+        heuristic = _compute_heuristics(notes, mml_list, warnings, chord_count)
+
+        result.success = True
+        result.warnings = warnings
+        result.warning_count = len(warnings)
+        result.note_count = len(notes)
+        result.chord_count = chord_count
+        result.part_note_counts = [len(p) for p in parts]
+        result.mml_parts = mml_list
+        result.notes_dump = notes_dump
+        result.debug_info = debug_info
+        result.heuristic_summary = heuristic
+
+        # 산출물 저장
+        if save_dir:
+            _save_engine_artifacts(save_dir, result, notes, mml_list)
+
+        return result
+
+    except Exception as e:
+        result.stage = result.stage or "unknown"
+        result.error_message = f"예상치 못한 오류: {type(e).__name__}: {e}"
+        result.warnings = warnings
+        result.debug_info = debug_info
+        return result
+
+    finally:
+        if preprocess_tmpdir:
+            shutil.rmtree(preprocess_tmpdir, ignore_errors=True)
+
+
+def _convert_pdf_for_engine(
+    input_path: str,
+    options: ConvertOptions,
+) -> tuple:
+    """PDF → 이미지 리스트 변환. 임시 디렉토리는 caller가 관리."""
+    from .pdf_converter import convert_pdf_to_images, PDFConvertError
+    try:
+        tmp_dir = tempfile.mkdtemp(prefix="score_to_mml_cmp_pdf_")
+        pages = convert_pdf_to_images(input_path, tmp_dir, dpi=options.pdf_dpi)
+        return pages, []
+    except PDFConvertError as e:
+        return [], [f"PDF 변환 실패: {e}"]
+
+
+# ---------------------------------------------------------------------------
+# Note dump / 휴리스틱 헬퍼
+# ---------------------------------------------------------------------------
+
+_NOTE_NAMES_SHARP = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]
+_NOTE_NAMES_FLAT  = ["C", "Db", "D", "Eb", "E", "F", "Gb", "G", "Ab", "A", "Bb", "B"]
+
+
+def _midi_to_pitch_name(pitch: int, prefer_sharps: bool = True) -> str:
+    """MIDI 번호를 C4 형식 음이름으로 변환."""
+    if pitch <= 0:
+        return "rest"
+    octave = (pitch // 12) - 1
+    names = _NOTE_NAMES_SHARP if prefer_sharps else _NOTE_NAMES_FLAT
+    return f"{names[pitch % 12]}{octave}"
+
+
+def _build_notes_dump(notes: list[NoteEvent], prefer_sharps: bool = True) -> list[dict]:
+    """
+    NoteEvent 리스트를 사람이 검토하기 좋은 dict 리스트로 변환.
+
+    각 dict에는 start, duration, pitch, pitch_name, is_rest,
+    staff, voice, part_hint, is_chord_note 가 포함된다.
+    """
+    if not notes:
+        return []
+
+    # 동시 발음 노트 감지: 같은 start 위치에 여러 노트가 있으면 chord_note
+    from collections import defaultdict
+    start_groups: dict[float, list[int]] = defaultdict(list)
+    for i, n in enumerate(notes):
+        start_groups[round(n.start, 6)].append(i)
+    chord_indices = {i for idxs in start_groups.values() if len(idxs) > 1 for i in idxs}
+
+    dump = []
+    for i, n in enumerate(notes):
+        dump.append({
+            "index": i + 1,
+            "start": n.start,
+            "duration": n.duration,
+            "pitch": n.pitch,
+            "pitch_name": _midi_to_pitch_name(n.pitch, prefer_sharps),
+            "is_rest": (n.pitch == 0),
+            "is_chord_note": (i in chord_indices),
+            "staff": n.staff,
+            "voice": n.voice,
+            "part_hint": n.part_hint,
+        })
+    return dump
+
+
+def _count_chords(notes: list[NoteEvent]) -> int:
+    """동시 발음 노트 그룹(화음) 수를 반환."""
+    from collections import defaultdict
+    start_groups: dict[float, list] = defaultdict(list)
+    for n in notes:
+        start_groups[round(n.start, 6)].append(n)
+    return sum(1 for g in start_groups.values() if len(g) > 1)
+
+
+def _compute_heuristics(
+    notes: list[NoteEvent],
+    mml_list: list[str],
+    warnings: list[str],
+    chord_count: int,
+) -> dict:
+    """
+    가벼운 참고 지표를 계산.
+
+    중요: 이 지표는 최종 품질 판정에 사용하지 않는다.
+    사용자의 직접 청취/확인이 최우선이다.
+    """
+    if not notes:
+        return {
+            "note_count": 0,
+            "chord_count": 0,
+            "mml_empty": True,
+            "warning_count": len(warnings),
+            "note": "지표는 참고용. 최종 판정은 사용자 직접 확인.",
+        }
+
+    pitches = [n.pitch for n in notes if n.pitch > 0]
+    jumps = 0
+    for i in range(1, len(pitches)):
+        if abs(pitches[i] - pitches[i - 1]) > 12:
+            jumps += 1
+
+    mml_empty = all(m.strip() in ("MML@;", "") for m in mml_list)
+
+    return {
+        "note_count": len(notes),
+        "chord_count": chord_count,
+        "rest_count": sum(1 for n in notes if n.pitch == 0),
+        "pitch_jump_over_octave": jumps,
+        "warning_count": len(warnings),
+        "mml_empty": mml_empty,
+        "note": "지표는 참고용. 최종 판정은 사용자 직접 확인.",
+    }
+
+
+# ---------------------------------------------------------------------------
+# 산출물 저장 헬퍼
+# ---------------------------------------------------------------------------
+
+def _save_engine_artifacts(
+    engine_save_dir: str,
+    result: EngineRunResult,
+    notes: list[NoteEvent],
+    mml_list: list[str],
+) -> None:
+    """
+    엔진별 산출물을 engine_save_dir에 저장.
+
+    저장 파일:
+      result.txt    - MML 파트 텍스트
+      notes.json    - 노트 덤프 (machine-readable)
+      notes.txt     - 노트 덤프 (human-readable)
+      debug.json    - debug_info + heuristic_summary
+    """
+    d = Path(engine_save_dir)
+
+    # result.txt
+    try:
+        lines = []
+        for i, mml in enumerate(mml_list, start=1):
+            lines.append(f"Part {i}")
+            lines.append(mml if mml else "MML@;")
+            lines.append("")
+        if result.warnings:
+            lines.append("--- Warnings ---")
+            for w in result.warnings:
+                lines.append(f"  [WARN] {w}")
+        mml_path = d / "result.txt"
+        mml_path.write_text("\n".join(lines).strip(), encoding="utf-8")
+        result.output_mml_path = str(mml_path)
+    except Exception:
+        pass
+
+    # notes.json
+    try:
+        notes_dump = result.notes_dump or _build_notes_dump(notes)
+        notes_json_path = d / "notes.json"
+        notes_json_path.write_text(
+            json.dumps(notes_dump, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+        result.output_notes_json_path = str(notes_json_path)
+    except Exception:
+        pass
+
+    # notes.txt (human-readable)
+    try:
+        notes_txt_path = d / "notes.txt"
+        lines = [
+            "# Note Dump (사람이 읽기 쉬운 형식)",
+            "# 주의: 자동 지표는 참고용. 최종 품질은 사용자가 직접 확인하세요.",
+            f"# 엔진: {result.engine_name}",
+            f"# 총 노트 수: {result.note_count}  화음 그룹: {result.chord_count}",
+            "#",
+            "# idx   start    dur    pitch  name    rest  chord  staff  voice",
+            "#" + "-" * 65,
+        ]
+        for n in result.notes_dump:
+            chord_mark = "C" if n.get("is_chord_note") else " "
+            rest_mark  = "R" if n.get("is_rest") else " "
+            lines.append(
+                f"  {n['index']:04d}  "
+                f"{n['start']:7.3f}  "
+                f"{n['duration']:5.3f}  "
+                f"{n['pitch']:5d}  "
+                f"{n['pitch_name']:<7s}  "
+                f"{rest_mark}     "
+                f"{chord_mark}      "
+                f"{n['staff']}      "
+                f"{n['voice']}"
+            )
+        notes_txt_path.write_text("\n".join(lines), encoding="utf-8")
+        result.output_notes_txt_path = str(notes_txt_path)
+    except Exception:
+        pass
+
+    # debug.json
+    try:
+        debug_data = {
+            "engine_name": result.engine_name,
+            "success": result.success,
+            "stage": result.stage,
+            "error_message": result.error_message,
+            "warnings": result.warnings,
+            "heuristic_summary": result.heuristic_summary,
+            "debug_info": result.debug_info,
+        }
+        debug_path = d / "debug.json"
+        debug_path.write_text(
+            json.dumps(debug_data, ensure_ascii=False, indent=2, default=str),
+            encoding="utf-8",
+        )
+        result.output_debug_path = str(debug_path)
+    except Exception:
+        pass
+
+
+def _build_comparison_summary(report: ComparisonReport) -> str:
+    """사람이 읽기 쉬운 비교 요약 텍스트를 생성."""
+    lines = [
+        "=" * 60,
+        "OMR 엔진 비교 결과",
+        "=" * 60,
+        f"입력 파일: {report.input_file}",
+        f"실행 시간: {report.timestamp}",
+        "",
+        "[중요] 아래 지표는 참고용입니다.",
+        "       최종 품질 평가는 사용자가 직접 결과를 확인하세요.",
+        "",
+        "엔진별 결과:",
+    ]
+
+    for run in report.runs:
+        if run.success:
+            status = "성공"
+            detail = f"노트 {run.note_count}개  화음 {run.chord_count}개  경고 {run.warning_count}개"
+        else:
+            status = "실패"
+            detail = f"단계: {run.stage}  오류: {run.error_message[:80]}"
+        lines.append(f"  {run.engine_name:<12s}: {status}  {detail}")
+
+    if report.suggested_engine:
+        lines.append("")
+        lines.append(f"[자동 참고 추천] {report.suggested_engine}")
+        lines.append("  * 이 추천은 노트 수 기준이며 최종 판정이 아닙니다.")
+        lines.append("    반드시 각 엔진 result.txt와 notes.txt를 직접 확인하세요.")
+
+    lines.append("=" * 60)
+    return "\n".join(lines)
+
+
+def _collect_manual_review_notes(report: ComparisonReport) -> list:
+    """수동 검토 시 참고할 사항을 수집."""
+    notes = [
+        "아래 항목을 직접 확인하세요:",
+        "  1. 각 엔진의 result.txt (MML)를 재생해서 음악적 품질을 들어보세요.",
+        "  2. notes.txt에서 이상한 피치(극단적 점프, 예상치 못한 음)를 확인하세요.",
+        "  3. 화음 노트가 의도한 대로 추출되었는지 확인하세요.",
+        "  4. 쉼표 위치와 길이가 맞는지 확인하세요.",
+    ]
+    for run in report.runs:
+        if not run.success:
+            notes.append(f"  [주의] {run.engine_name}: 실패 ({run.stage} 단계) — {run.error_message[:60]}")
+        elif run.heuristic_summary.get("pitch_jump_over_octave", 0) > 5:
+            cnt = run.heuristic_summary["pitch_jump_over_octave"]
+            notes.append(f"  [주의] {run.engine_name}: 1옥타브 초과 피치 점프 {cnt}회 (음이탈 의심)")
+    return notes
+
+
+def _suggest_engine(report: ComparisonReport) -> str:
+    """
+    노트 수 기준 단순 참고 추천. 최종 판정이 아님.
+    실패한 엔진은 제외.
+    """
+    successful = [r for r in report.runs if r.success and r.note_count > 0]
+    if not successful:
+        return ""
+    best = max(successful, key=lambda r: r.note_count)
+    return best.engine_name
+
+
+def _save_comparison_report(save_dir: str, report: ComparisonReport) -> None:
+    """comparison_report.json 과 comparison_summary.txt 를 save_dir에 저장."""
+    d = Path(save_dir)
+
+    # comparison_report.json
+    try:
+        from dataclasses import asdict
+        report_dict = asdict(report)
+        (d / "comparison_report.json").write_text(
+            json.dumps(report_dict, ensure_ascii=False, indent=2, default=str),
+            encoding="utf-8",
+        )
+    except Exception:
+        pass
+
+    # comparison_summary.txt
+    try:
+        (d / "comparison_summary.txt").write_text(
+            report.comparison_summary, encoding="utf-8"
+        )
+    except Exception:
+        pass
+
+
+# ---------------------------------------------------------------------------
+# 디버그 저장 헬퍼
+# ---------------------------------------------------------------------------
+
+def _prepare_run_debug_dir(input_path: str, base_debug_dir: str) -> str:
+    """
+    base_debug_dir 아래에 실행별 하위 폴더를 생성하고 경로를 반환.
+    base_debug_dir가 비어있으면 빈 문자열 반환.
+    폴더명: {input_stem}_{YYYYMMDD_HHMMSS}
+    """
+    if not base_debug_dir:
+        return ""
+    stem = Path(input_path).stem
+    ts = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+    run_dir = Path(base_debug_dir) / f"{stem}_{ts}"
+    run_dir.mkdir(parents=True, exist_ok=True)
+    return str(run_dir)
+
+
+def _save_debug_log(
+    run_debug_dir: str,
+    debug_info: dict,
+    warnings: list,
+    result: Optional[ConvertResult],
+) -> None:
+    """debug_dir에 debug_log.txt와 result.txt를 저장."""
+    if not run_debug_dir:
+        return
+    d = Path(run_debug_dir)
+
+    # debug_log.txt
+    try:
+        log_lines = ["=== debug_info ==="]
+        for k, v in debug_info.items():
+            log_lines.append(f"{k}: {json.dumps(v, ensure_ascii=False, default=str)}")
+        if warnings:
+            log_lines.append("\n=== warnings ===")
+            for w in warnings:
+                log_lines.append(f"  [WARN] {w}")
+        (d / "debug_log.txt").write_text("\n".join(log_lines), encoding="utf-8")
+    except Exception:
+        pass
+
+    # result.txt (MML 결과)
+    if result is not None:
+        try:
+            (d / "result.txt").write_text(result.format_output(), encoding="utf-8")
+        except Exception:
+            pass

core/preprocess.py

@@ -0,0 +1,269 @@
+"""
+core/preprocess.py
+
+이미지 전처리 계층.
+
+역할:
+  - 파일 유효성 검사 (경로, 확장자, 읽기 가능 여부)
+  - OpenCV 기반 이미지 품질 개선 (Audiveris OMR 정확도 향상 목적)
+
+전처리 파이프라인 (apply_preprocessing):
+  1. 이미지 로드 및 검증 (cv2.imread)
+  2. Grayscale 변환
+  3. 가벼운 노이즈 제거 (GaussianBlur 3x3)
+  4. 이진화 (Otsu 또는 Adaptive Threshold)
+  5. [선택적] Deskew — 기울기 보정 (실험적, deskew_enabled=True 시)
+
+주의:
+  - apply_preprocessing은 opencv-python 필요 (pip install opencv-python)
+  - opencv 미설치 시 PreprocessError 발생 → pipeline에서 fallback 처리
+  - mock 모드에서는 pipeline이 이 함수를 호출하지 않음
+
+한계:
+  - deskew는 ±10도 범위에서만 동작. 과도하게 기울어진 이미지는 보정 불가
+  - 손글씨, 그림자, 저해상도 이미지는 이진화 후 오히려 품질 저하 가능
+  - 연필 필기 악보는 Adaptive Threshold가 더 적합할 수 있음
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .models import ConvertOptions
+
+SUPPORTED_EXTENSIONS = {".png", ".jpg", ".jpeg", ".tiff", ".tif", ".bmp", ".pdf"}
+
+
+class PreprocessError(Exception):
+    """전처리 단계 오류."""
+    pass
+
+
+# ---------------------------------------------------------------------------
+# 파일 검증 (opencv 불필요, 항상 동작)
+# ---------------------------------------------------------------------------
+
+def validate_image_path(input_path: str) -> Path:
+    """
+    입력 파일 경로를 검증하고 Path 객체를 반환.
+
+    Raises:
+        PreprocessError: 파일이 없거나 지원되지 않는 형식인 경우
+    """
+    path = Path(input_path)
+
+    if not path.exists():
+        raise PreprocessError(f"파일을 찾을 수 없습니다: {input_path}")
+    if not path.is_file():
+        raise PreprocessError(f"파일이 아닙니다: {input_path}")
+
+    ext = path.suffix.lower()
+    if ext not in SUPPORTED_EXTENSIONS:
+        raise PreprocessError(
+            f"지원하지 않는 파일 형식: {ext}. "
+            f"지원 형식: {', '.join(sorted(SUPPORTED_EXTENSIONS))}"
+        )
+    return path
+
+
+def get_file_info(path: Path) -> dict:
+    """파일 기본 정보를 반환."""
+    stat = path.stat()
+    return {
+        "filename": path.name,
+        "extension": path.suffix.lower(),
+        "size_bytes": stat.st_size,
+        "absolute_path": str(path.resolve()),
+    }
+
+
+def preprocess_image(input_path: str) -> dict:
+    """
+    파일 유효성 검사만 수행. 전처리 없이 원본 경로를 반환.
+
+    pipeline에서 먼저 호출하여 파일을 검증한 뒤,
+    Audiveris 모드라면 apply_preprocessing()을 추가 호출한다.
+    """
+    path = validate_image_path(input_path)
+    info = get_file_info(path)
+    info["preprocessed_path"] = str(path.resolve())
+    info["preprocessing_applied"] = []
+    return info
+
+
+# ---------------------------------------------------------------------------
+# OpenCV 전처리 (opencv-python 필요)
+# ---------------------------------------------------------------------------
+
+def apply_preprocessing(
+    input_path: str,
+    output_path: str,
+    options: ConvertOptions,
+    debug_dir: str = "",
+) -> dict:
+    """
+    OpenCV 기반 이미지 전처리를 적용하고 결과를 output_path에 저장.
+
+    Args:
+        input_path:  원본 이미지 경로
+        output_path: 전처리 결과 저장 경로 (.png 권장)
+        options:     ConvertOptions (binarize_method, deskew_enabled 사용)
+
+    Returns:
+        dict: 전처리 결과 정보
+          - applied: True
+          - steps: 적용된 단계 목록
+          - input_size: (w, h)
+          - output_path: 결과 파일 경로
+
+    Raises:
+        PreprocessError: opencv 미설치, 이미지 읽기 실패, 저장 실패 시
+    """
+    try:
+        import cv2
+        import numpy as np
+    except ImportError:
+        raise PreprocessError(
+            "opencv-python이 설치되지 않았습니다.\n"
+            "설치 명령: pip install opencv-python"
+        )
+
+    img = cv2.imread(input_path, cv2.IMREAD_COLOR)
+    if img is None:
+        raise PreprocessError(
+            f"이미지를 읽을 수 없습니다: {input_path}\n"
+            f"파일이 손상되었거나 지원하지 않는 형식일 수 있습니다."
+        )
+
+    h, w = img.shape[:2]
+    applied: list[str] = []
+
+    def _save_step(name: str, img_data) -> None:
+        if debug_dir:
+            cv2.imwrite(str(Path(debug_dir) / name), img_data)
+
+    # 1. Grayscale
+    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    applied.append("grayscale")
+    _save_step("step_01_grayscale.png", gray)
+
+    # 2. 노이즈 제거 (가벼운 Gaussian blur, 선택적)
+    if options.blur_enabled:
+        denoised = cv2.GaussianBlur(gray, (3, 3), 0)
+        applied.append("gaussian_blur_3x3")
+        _save_step("step_02_gaussian_blur.png", denoised)
+    else:
+        denoised = gray
+
+    # 3. 이진화 (선택적 — 기본 off, Audiveris 자체 이진화 신뢰)
+    processed = denoised
+    if options.binarize_enabled:
+        processed = _binarize(denoised, options.binarize_method)
+        applied.append(f"binarize:{options.binarize_method}")
+        _save_step(f"step_03_binarized_{options.binarize_method}.png", processed)
+
+    # 4. Deskew (선택적)
+    if options.deskew_enabled:
+        processed, angle = _deskew(processed)
+        if abs(angle) > 0.01:
+            applied.append(f"deskew:{angle:.2f}deg")
+            _save_step(f"step_04_deskew_{angle:.2f}deg.png", processed)
+        else:
+            applied.append("deskew:skipped(angle<0.5)")
+
+    # 저장
+    ok = cv2.imwrite(output_path, processed)
+    if not ok:
+        raise PreprocessError(
+            f"전처리 이미지 저장 실패: {output_path}\n"
+            f"출력 디렉토리가 존재하는지 확인하세요."
+        )
+
+    return {
+        "applied": True,
+        "steps": applied,
+        "input_path": input_path,
+        "output_path": output_path,
+        "input_size": (w, h),
+    }
+
+
+def _binarize(gray_img, method: str):
+    """
+    Grayscale 이미지를 이진화.
+
+    method:
+      "otsu"     : 전역 Otsu 임계값. 명암 대비가 분명한 스캔 악보에 적합.
+      "adaptive" : 지역 Adaptive Threshold. 조명 불균일 / 연필 필기 악보에 적합.
+    """
+    try:
+        import cv2
+    except ImportError:
+        raise PreprocessError("opencv-python이 필요합니다.")
+
+    if method == "adaptive":
+        return cv2.adaptiveThreshold(
+            gray_img, 255,
+            cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
+            cv2.THRESH_BINARY,
+            blockSize=15, C=8,
+        )
+    # default: otsu
+    _, binary = cv2.threshold(
+        gray_img, 0, 255,
+        cv2.THRESH_BINARY + cv2.THRESH_OTSU,
+    )
+    return binary
+
+
+def _deskew(binary_img):
+    """
+    이진화된 이미지의 기울기를 보정.
+
+    Returns:
+        (corrected_img, angle_degrees)
+
+    한계:
+      - ±10도 이내의 기울기만 보정. 범위 초과 시 원본 반환.
+      - 악보 전체가 기울어진 경우에만 유효. 개별 보표 기울기는 미처리.
+      - 어두운 픽셀이 너무 적으면 각도 추정 불가 → 원본 반환.
+    """
+    try:
+        import cv2
+        import numpy as np
+    except ImportError:
+        return binary_img, 0.0
+
+    # 어두운 픽셀 좌표 추출 (이진화된 이미지: 악보 선/음표 = 0)
+    dark_coords = np.column_stack(np.where(binary_img < 128))
+    if len(dark_coords) < 200:
+        return binary_img, 0.0
+
+    # (row, col) → (x=col, y=row) 변환 후 minAreaRect
+    points = dark_coords[:, ::-1].astype(np.float32)
+    rect = cv2.minAreaRect(points)
+    angle = rect[2]  # range: (-90, 0]
+
+    # (-90, -45] → 세로 방향 박스 → +90 보정
+    if angle < -45:
+        angle = 90.0 + angle
+    # 이제 angle ∈ (-45, 45)
+
+    # 너무 크면 보정 불가 (옆으로 찍힌 이미지 등)
+    if abs(angle) > 10.0:
+        return binary_img, 0.0
+    # 너무 작으면 의미 없음
+    if abs(angle) < 0.5:
+        return binary_img, 0.0
+
+    h, w = binary_img.shape
+    center = (w // 2, h // 2)
+    M = cv2.getRotationMatrix2D(center, angle, 1.0)
+    corrected = cv2.warpAffine(
+        binary_img, M, (w, h),
+        flags=cv2.INTER_LINEAR,
+        borderMode=cv2.BORDER_REPLICATE,
+    )
+    return corrected, angle

core/score_primitives.py

@@ -0,0 +1,193 @@
+"""
+score_primitives.py — CV 기반 악보 요소 검출
+현재: notehead 검출만 구현
+"""
+
+import cv2
+import numpy as np
+from dataclasses import dataclass
+from typing import List
+
+
+@dataclass
+class NoteHead:
+    x: int        # center x
+    y: int        # center y
+    w: int        # bounding box width
+    h: int        # bounding box height
+    filled: bool  # True=검은 음표(4분/8분), False=흰 음표(2분/온음표)
+
+
+def _remove_staff_lines(binary: np.ndarray) -> np.ndarray:
+    """수평 모폴로지로 5선을 제거한 이미지 반환 (흰=배경, 검=음표)."""
+    # 이미지 너비의 1/5 이상 이어진 수평선 = 오선
+    kernel_w = max(30, binary.shape[1] // 5)
+    horiz_kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (kernel_w, 1))
+    detected_lines = cv2.morphologyEx(binary, cv2.MORPH_OPEN, horiz_kernel)
+    return cv2.subtract(binary, detected_lines)
+
+
+def detect_noteheads(img_path: str) -> List[NoteHead]:
+    """
+    악보 이미지에서 notehead를 검출해 리스트로 반환.
+    img_path: PNG/JPG 경로
+    """
+    img = cv2.imread(img_path, cv2.IMREAD_GRAYSCALE)
+    if img is None:
+        raise FileNotFoundError(f"이미지를 열 수 없음: {img_path}")
+
+    h_img, w_img = img.shape
+
+    # --- 이진화 (흰=배경, 검=음표) ---
+    _, binary = cv2.threshold(img, 180, 255, cv2.THRESH_BINARY_INV)
+
+    # --- 5선 제거 ---
+    no_lines = _remove_staff_lines(binary)
+
+    # --- connected components ---
+    n, labels, stats, centroids = cv2.connectedComponentsWithStats(no_lines, connectivity=8)
+
+    # --- notehead 크기 임계값: 이미지 크기 기반 자동 스케일 ---
+    # 기준: 527px 너비 이미지에서 notehead ≈ w8~70, h6~55, area 60~4000
+    scale = w_img / 527.0
+    min_area = int(60   * scale ** 2)
+    max_area = int(4000 * scale ** 2)
+    min_w = int(8  * scale)
+    max_w = int(70 * scale)
+    min_h = int(6  * scale)
+    max_h = int(55 * scale)
+
+    noteheads = []
+    for i in range(1, n):
+        bx, by, bw, bh, area = stats[i]
+
+        # 크기 필터
+        if area < min_area or area > max_area:
+            continue
+        if bw < min_w or bw > max_w:
+            continue
+        if bh < min_h or bh > max_h:
+            continue
+
+        # 종횡비 필터 (notehead는 대략 타원형: 0.5~2.0)
+        aspect = bw / bh
+        if aspect < 0.45 or aspect > 2.2:
+            continue
+
+        cx = int(centroids[i][0])
+        cy = int(centroids[i][1])
+
+        # filled vs open: 바운딩박스 대비 채움 비율
+        fill_ratio = area / (bw * bh)
+        filled = fill_ratio > 0.42
+
+        noteheads.append(NoteHead(cx, cy, bw, bh, filled))
+
+    # x, y 순으로 정렬 (위→아래, 좌→우)
+    row_bin = int(30 * scale)
+    noteheads.sort(key=lambda n: (n.y // row_bin, n.x))
+
+    return noteheads
+
+
+def detect_noteheads_from_array(arr: np.ndarray) -> List[NoteHead]:
+    """
+    numpy array에서 notehead를 검출해 리스트로 반환.
+    detect_noteheads()와 동일하나 파일 경로 대신 배열을 받음.
+    arr: BGR 또는 GRAY numpy array.
+    """
+    if arr.ndim == 3:
+        img = cv2.cvtColor(arr, cv2.COLOR_BGR2GRAY)
+    else:
+        img = arr.copy()
+
+    h_img, w_img = img.shape
+
+    _, binary = cv2.threshold(img, 180, 255, cv2.THRESH_BINARY_INV)
+    no_lines = _remove_staff_lines(binary)
+
+    n, labels, stats, centroids = cv2.connectedComponentsWithStats(no_lines, connectivity=8)
+
+    scale = w_img / 527.0
+    min_area = int(60   * scale ** 2)
+    max_area = int(4000 * scale ** 2)
+    min_w = int(8  * scale)
+    max_w = int(70 * scale)
+    min_h = int(6  * scale)
+    max_h = int(55 * scale)
+
+    noteheads = []
+    for i in range(1, n):
+        bx, by, bw, bh, area = stats[i]
+        if area < min_area or area > max_area:
+            continue
+        if bw < min_w or bw > max_w:
+            continue
+        if bh < min_h or bh > max_h:
+            continue
+        aspect = bw / bh
+        if aspect < 0.45 or aspect > 2.2:
+            continue
+        cx = int(centroids[i][0])
+        cy = int(centroids[i][1])
+        fill_ratio = area / (bw * bh)
+        filled = fill_ratio > 0.42
+        noteheads.append(NoteHead(cx, cy, bw, bh, filled))
+
+    row_bin = int(30 * scale)
+    noteheads.sort(key=lambda nh: (nh.y // row_bin, nh.x))
+    return noteheads
+
+
+def detect_staff_spacing(arr: np.ndarray) -> float:
+    """
+    수평 투영으로 5선 간격(픽셀)을 반환.
+    arr: BGR 또는 GRAY numpy array.
+    검출 실패 시 이미지 높이 / 8 반환.
+    """
+    if arr.ndim == 3:
+        img = cv2.cvtColor(arr, cv2.COLOR_BGR2GRAY)
+    else:
+        img = arr.copy()
+
+    h, w = img.shape
+    _, binary = cv2.threshold(img, 180, 255, cv2.THRESH_BINARY_INV)
+
+    proj = binary.sum(axis=1).astype(float)
+    threshold = w * 255 * 0.3  # 행 너비의 30% 이상 픽셀 = 오선
+
+    in_line = False
+    line_centers: List[int] = []
+    start = 0
+    for y in range(h):
+        if proj[y] >= threshold:
+            if not in_line:
+                start = y
+                in_line = True
+        else:
+            if in_line:
+                line_centers.append((start + y) // 2)
+                in_line = False
+    if in_line:
+        line_centers.append((start + h) // 2)
+
+    if len(line_centers) < 2:
+        return float(h) / 8.0
+
+    spacings = [line_centers[i + 1] - line_centers[i]
+                for i in range(min(4, len(line_centers) - 1))]
+    return float(np.median(spacings))
+
+
+def save_overlay(img_path: str, noteheads: List[NoteHead], out_path: str) -> None:
+    """검출된 notehead를 원본 이미지에 overlay해 저장."""
+    img = cv2.imread(img_path)
+    for nh in noteheads:
+        color = (0, 0, 255) if nh.filled else (255, 0, 0)  # 빨강=filled, 파랑=open
+        cv2.rectangle(img,
+                      (nh.x - nh.w // 2, nh.y - nh.h // 2),
+                      (nh.x + nh.w // 2, nh.y + nh.h // 2),
+                      color, 1)
+        cv2.circle(img, (nh.x, nh.y), 2, color, -1)
+    cv2.imwrite(out_path, img)
+    print(f"overlay 저장: {out_path}")

core/xml_corrector.py

@@ -0,0 +1,1681 @@
+"""
+core/xml_corrector.py
+
+MXL/XML 자동 교정 파이프라인.
+Verovio 렌더링 + OpenCV 마디 분할 + SSIM 비교로
+Audiveris OMR 오류를 탐지·교정한다.
+
+의존성:
+    pip install verovio scikit-image lxml cairosvg
+
+흐름:
+    MXL → Verovio 렌더 → 마디 분할
+    원본 PNG → 마디 분할
+    SSIM 비교 → 의심 마디 추출
+    XML 수정 후보 생성 → 재렌더 → SSIM 재비교 → 채택
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import tempfile
+import zipfile
+from copy import deepcopy
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterator, Optional
+
+import cv2
+import numpy as np
+
+# ── Cairo DLL 선행 로드 (cairosvg 의존) ────────────────────────────────────
+_CAIRO_DIR = r"C:\Program Files\Unity Hub\resources\app.asar.unpacked\node_modules\canvas\build\Release"
+_CAIRO_DLLS = [
+    "libgcc_s_seh-1.dll", "libwinpthread-1.dll", "libglib-2.0-0.dll",
+    "libpixman-1-0.dll", "libpng16-16.dll", "libfreetype-6.dll",
+    "libfontconfig-1.dll", "libcairo-2.dll",
+]
+if os.path.isdir(_CAIRO_DIR):
+    for _dll in _CAIRO_DLLS:
+        _p = os.path.join(_CAIRO_DIR, _dll)
+        if os.path.exists(_p):
+            try:
+                ctypes.CDLL(_p)
+            except OSError:
+                pass
+
+# ── lazy import ────────────────────────────────────────────────────────────
+try:
+    import cairosvg as _cairosvg
+    _CAIRO_OK = True
+except Exception:
+    _CAIRO_OK = False
+
+try:
+    import verovio as _verovio_mod
+    _VEROVIO_OK = True
+except Exception:
+    _VEROVIO_OK = False
+
+try:
+    from lxml import etree as _etree
+    _LXML_OK = True
+except Exception:
+    import xml.etree.ElementTree as _etree  # type: ignore
+    _LXML_OK = False
+
+try:
+    from skimage.metrics import structural_similarity as _ssim
+    _SSIM_OK = True
+except Exception:
+    _SSIM_OK = False
+
+
+# ── 데이터클래스 ────────────────────────────────────────────────────────────
+
+@dataclass
+class SystemRegion:
+    y1: int
+    y2: int
+    x1: int
+    x2: int
+
+
+@dataclass
+class CandidateEdit:
+    measure_number: int
+    note_index: int
+    edit_type: str
+    description: str = ""
+
+
+@dataclass
+class CorrectionResult:
+    xml_path: str
+    measures_checked: int = 0
+    measures_corrected: int = 0
+    measures_fallback: int = 0
+    warnings: list[str] = field(default_factory=list)
+
+
+@dataclass
+class StaffBand:
+    y1: int
+    y2: int
+    spacing_px: float  # 5선 한 칸 간격
+
+
+# ── 헬퍼 함수 ──────────────────────────────────────────────────────────────
+
+def _check_deps() -> None:
+    missing = []
+    if not _VEROVIO_OK:
+        missing.append("verovio")
+    if not _CAIRO_OK:
+        missing.append("cairosvg (또는 Cairo 라이브러리)")
+    if not _SSIM_OK:
+        missing.append("scikit-image")
+    if missing:
+        raise ImportError(f"XML 교정에 필요한 패키지 없음: {', '.join(missing)}")
+
+
+def _extract_xml_from_mxl(mxl_path: str) -> str:
+    """MXL(zip) 또는 XML 파일에서 MusicXML 문자열 반환."""
+    path = Path(mxl_path)
+    if path.suffix.lower() == ".mxl":
+        with zipfile.ZipFile(mxl_path) as zf:
+            names = zf.namelist()
+            xml_name = next(
+                (n for n in names
+                 if n.lower().endswith((".xml", ".musicxml"))
+                 and "container" not in n.lower()),
+                None,
+            )
+            if xml_name is None:
+                raise RuntimeError(f"MXL 내부에 XML 없음: {mxl_path}")
+            return zf.read(xml_name).decode("utf-8", errors="replace")
+    else:
+        return path.read_text(encoding="utf-8", errors="replace")
+
+
+def _strip_ns(root) -> None:
+    """lxml Element의 네임스페이스 제거 (in-place)."""
+    for elem in root.iter():
+        if hasattr(elem, "tag") and isinstance(elem.tag, str) and "{" in elem.tag:
+            elem.tag = elem.tag.split("}", 1)[1]
+        # attrib 네임스페이스도 제거
+        new_attrib = {}
+        for k, v in elem.attrib.items():
+            if "{" in k:
+                k = k.split("}", 1)[1]
+            new_attrib[k] = v
+        elem.attrib.clear()
+        elem.attrib.update(new_attrib)
+
+
+# ── 디버그 이미지 헬퍼 ─────────────────────────────────────────────────────────
+
+def _save_debug_pair(
+    debug_dir: str, sys_idx: int, m_idx: int,
+    xml_num: int, score: float,
+    r_crop: np.ndarray, o_crop: np.ndarray,
+    proc_r: "np.ndarray | None" = None,
+    proc_o: "np.ndarray | None" = None,
+    best_cand: "np.ndarray | None" = None,
+) -> None:
+    h, w = 150, 200
+
+    def rsz(x: np.ndarray) -> np.ndarray:
+        if x is None or x.size == 0:
+            return np.ones((h, w, 3), np.uint8) * 200
+        out = cv2.resize(x, (w, h))
+        if out.ndim == 2:
+            out = cv2.cvtColor(out, cv2.COLOR_GRAY2BGR)
+        return out
+
+    name = f"r{sys_idx+1}_m{m_idx+1}_xml{xml_num}_score{score:.3f}"
+    cv2.imwrite(str(Path(debug_dir) / f"raw_{name}.png"),
+                np.hstack([rsz(r_crop), rsz(o_crop)]))
+    if proc_r is not None and proc_o is not None:
+        cv2.imwrite(str(Path(debug_dir) / f"proc_{name}.png"),
+                    np.hstack([rsz(proc_r), rsz(proc_o)]))
+    if best_cand is not None:
+        cv2.imwrite(str(Path(debug_dir) / f"cand_{name}.png"), rsz(best_cand))
+
+
+# pitch shift 헬퍼
+_STEP_SEMITONES = {"C": 0, "D": 2, "E": 4, "F": 5, "G": 7, "A": 9, "B": 11}
+_SEMITONE_TO_STEP = {
+    0: ("C", 0), 1: ("C", 1), 2: ("D", 0), 3: ("D", 1), 4: ("E", 0),
+    5: ("F", 0), 6: ("F", 1), 7: ("G", 0), 8: ("G", 1), 9: ("A", 0),
+    10: ("A", 1), 11: ("B", 0),
+}
+_TYPE_ORDER = ["64th", "32nd", "16th", "eighth", "quarter", "half", "whole"]
+
+
+def _shift_pitch(step: str, alter: int, octave: int, delta: int):
+    semi = _STEP_SEMITONES.get(step, 0) + alter + octave * 12
+    new_semi = semi + delta
+    new_oct, rem = divmod(new_semi, 12)
+    ns, na = _SEMITONE_TO_STEP[rem]
+    return ns, na, new_oct
+
+
+# ── MXLRenderer ─────────────────────────────────────────────────────────────
+
+class MXLRenderer:
+    """Verovio + cairosvg로 MXL/XML → BGR numpy 이미지 렌더링."""
+
+    def __init__(
+        self,
+        scale: int = 40,
+        seg_fill_ratio: float = 0.25,
+        seg_bar_ratio: float = 0.60,
+        seg_gap_factor: float = 5.0,
+    ):
+        _check_deps()
+        self._tk = _verovio_mod.toolkit()
+        self._tk.setOptions({
+            "scale": scale,
+            "adjustPageHeight": True,
+            "adjustPageWidth": True,
+            "svgBoundingBoxes": True,
+        })
+        self._loaded: Optional[str] = None
+        # ImageSegmenter 파라미터 보관 (get_measure_data_by_system 에서 사용)
+        self._seg_fill = seg_fill_ratio
+        self._seg_bar  = seg_bar_ratio
+        self._seg_gap  = seg_gap_factor
+
+    def load(self, mxl_path: str) -> None:
+        if self._loaded == mxl_path:
+            return
+        xml_str = _extract_xml_from_mxl(mxl_path)
+        ok = self._tk.loadData(xml_str)
+        if not ok:
+            raise RuntimeError(f"Verovio loadData 실패: {mxl_path}")
+        self._loaded = mxl_path
+
+    def load_xml_string(self, xml_str: str) -> None:
+        """XML 문자열 직접 로드 (후보 재렌더용)."""
+        self._tk.loadData(xml_str)
+        self._loaded = None
+
+    def render_candidate_measures(
+        self, xml_str: str, page_num: int = 1
+    ) -> Optional[list[list[dict]]]:
+        """
+        후보 XML을 **새로운 toolkit 인스턴스**로 렌더링 (크래시 격리).
+        실패 시 None 반환.
+        """
+        try:
+            tk = _verovio_mod.toolkit()
+            tk.setOptions({
+                "scale": self._tk.getOptions().get("scale", 40),
+                "adjustPageHeight": True,
+                "adjustPageWidth": True,
+                "svgBoundingBoxes": True,
+            })
+            tk.loadData(xml_str)
+            svg = tk.renderToSVG(page_num)
+            png_bytes = _cairosvg.svg2png(bytestring=svg.encode())
+            img = self._png_bytes_to_bgr(png_bytes)
+            img_h, img_w = img.shape[:2]
+
+            # SVG 파싱 (기존 get_measure_data_by_system과 동일)
+            if _LXML_OK:
+                root = _etree.fromstring(svg.encode())
+            else:
+                root = _etree.fromstring(svg)
+            tag    = root.tag
+            svg_ns = tag.split("}")[0].lstrip("{") if "}" in tag else ""
+            g_tag  = f"{{{svg_ns}}}g"  if svg_ns else "g"
+            r_tag  = f"{{{svg_ns}}}rect" if svg_ns else "rect"
+            svg_tag_name = f"{{{svg_ns}}}svg" if svg_ns else "svg"
+
+            vb_w, vb_h = float(img_w), float(img_h)
+            for inner in root.iter(svg_tag_name):
+                if "definition-scale" in inner.get("class", ""):
+                    vb = (inner.get("viewBox") or "").split()
+                    if len(vb) >= 4:
+                        try:
+                            vb_w = float(vb[2])
+                            vb_h = float(vb[3])
+                        except ValueError:
+                            pass
+                    break
+            scale_y = img_h / vb_h if vb_h > 0 else 1.0
+
+            _MARGIN = 12
+            sys_entries = []
+            counter = [0]
+            for sys_elem in root.iter(g_tag):
+                if sys_elem.get("class", "") != "system":
+                    continue
+                nums = []
+                for child in sys_elem.iter(g_tag):
+                    if child.get("class", "") != "measure":
+                        continue
+                    try:
+                        n = int(child.get("data-n") or 0)
+                    except ValueError:
+                        n = 0
+                    if n == 0:
+                        counter[0] += 1
+                        n = counter[0]
+                    nums.append(n)
+                if not nums:
+                    continue
+                y1_px = y2_px = None
+                for child in sys_elem:
+                    child_cls = child.get("class", "") if hasattr(child, "get") else ""
+                    if "bounding-box" in child_cls:
+                        for r in child.iter(r_tag):
+                            try:
+                                y_sv = float(r.get("y", 0))
+                                h_sv = float(r.get("height", 0))
+                                if h_sv > 0:
+                                    y1_px = max(0, int(y_sv * scale_y) - _MARGIN)
+                                    y2_px = min(img_h, int((y_sv + h_sv) * scale_y) + _MARGIN)
+                            except (ValueError, TypeError):
+                                pass
+                            break
+                        break
+                if y1_px is None:
+                    continue
+                sys_entries.append((y1_px, y2_px, nums))
+
+            if not sys_entries:
+                return None
+
+            segmenter = ImageSegmenter(
+                staff_fill_ratio=self._seg_fill,
+                barline_fill_ratio=self._seg_bar,
+                system_gap_factor=self._seg_gap,
+            )
+            gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+            _, binary = cv2.threshold(gray, 200, 255, cv2.THRESH_BINARY)
+            inv = cv2.bitwise_not(binary)
+
+            result = []
+            for y1_px, y2_px, xml_nums in sys_entries:
+                sys_region = SystemRegion(y1_px, y2_px, 0, img_w)
+                xs    = segmenter._detect_barlines(inv, sys_region)
+                crops = segmenter._crop_measures(img, sys_region, xs)
+                n_m   = min(len(xml_nums), len(crops))
+                sl = [{"xml_number": xml_nums[m_idx], "crop": crops[m_idx]}
+                      for m_idx in range(n_m)]
+                if sl:
+                    result.append(sl)
+            return result if result else None
+        except Exception:
+            return None
+
+    def get_page_count(self) -> int:
+        return self._tk.getPageCount()
+
+    @staticmethod
+    def _png_bytes_to_bgr(png_bytes: bytes) -> np.ndarray:
+        """PNG 바이트 → BGR ndarray. RGBA인 경우 흰 배경 위에 합성."""
+        arr = np.frombuffer(png_bytes, dtype=np.uint8)
+        img = cv2.imdecode(arr, cv2.IMREAD_UNCHANGED)
+        if img is None:
+            raise RuntimeError("PNG 디코드 실패")
+        if img.ndim == 2:
+            img = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
+        elif img.shape[2] == 4:
+            # BGRA → 흰 배경 합성
+            alpha = img[:, :, 3:4].astype(np.float32) / 255.0
+            bgr   = img[:, :, :3].astype(np.float32)
+            white = np.full_like(bgr, 255.0)
+            img   = (bgr * alpha + white * (1.0 - alpha)).astype(np.uint8)
+        return img
+
+    def render_page(self, page_num: int = 1) -> np.ndarray:
+        """페이지를 BGR numpy 배열로 렌더링."""
+        svg = self._tk.renderToSVG(page_num)
+        png_bytes = _cairosvg.svg2png(bytestring=svg.encode())
+        img = self._png_bytes_to_bgr(png_bytes)
+        if img is None:
+            raise RuntimeError("Verovio 렌더링 실패 (빈 이미지)")
+        return img
+
+    def get_measure_data_by_system(self, page_num: int = 1) -> list[list[dict]]:
+        """
+        SVG에서 시스템 bbox(y 범위)와 마디 xml_number를 추출하고,
+        마디 분할은 각 시스템 y 범위 내에서 ImageSegmenter(barline)로 수행.
+
+        SVG 내부 좌표계(viewBox)를 픽셀로 변환해 정확한 시스템 y 범위를 결정.
+
+        Returns: list[system] of list[{'xml_number': int, 'crop': ndarray}]
+        """
+        svg = self._tk.renderToSVG(page_num)
+        png_bytes = _cairosvg.svg2png(bytestring=svg.encode())
+        img = self._png_bytes_to_bgr(png_bytes)
+        if img is None:
+            raise RuntimeError("Verovio 렌더링 실패")
+        img_h, img_w = img.shape[:2]
+
+        # ── SVG 파싱 준비 ─────────────────────────────────────────
+        if _LXML_OK:
+            root = _etree.fromstring(svg.encode())
+        else:
+            root = _etree.fromstring(svg)
+
+        tag    = root.tag
+        svg_ns = tag.split("}")[0].lstrip("{") if "}" in tag else ""
+        g_tag  = f"{{{svg_ns}}}g"  if svg_ns else "g"
+        r_tag  = f"{{{svg_ns}}}rect" if svg_ns else "rect"
+        svg_tag = f"{{{svg_ns}}}svg" if svg_ns else "svg"
+
+        # ── definition-scale viewBox → 좌표 변환 비율 ────────────
+        vb_w, vb_h = float(img_w), float(img_h)
+        for inner in root.iter(svg_tag):
+            if "definition-scale" in inner.get("class", ""):
+                vb = (inner.get("viewBox") or "").split()
+                if len(vb) >= 4:
+                    try:
+                        vb_w = float(vb[2])
+                        vb_h = float(vb[3])
+                    except ValueError:
+                        pass
+                break
+        scale_x = img_w / vb_w if vb_w > 0 else 1.0
+        scale_y = img_h / vb_h if vb_h > 0 else 1.0
+
+        # ── SVG 파싱: system bbox + xml_number 목록 ──────────────
+        _MARGIN = 12  # 시스템 bbox에 추가할 여백(px)
+        sys_entries: list[tuple[int, int, list[int]]] = []  # (y1_px, y2_px, xml_nums)
+        counter = [0]
+
+        for sys_elem in root.iter(g_tag):
+            if sys_elem.get("class", "") != "system":
+                continue
+
+            # xml_numbers
+            nums: list[int] = []
+            for child in sys_elem.iter(g_tag):
+                if child.get("class", "") != "measure":
+                    continue
+                try:
+                    n = int(child.get("data-n") or 0)
+                except ValueError:
+                    n = 0
+                if n == 0:
+                    counter[0] += 1
+                    n = counter[0]
+                nums.append(n)
+            if not nums:
+                continue
+
+            # system bounding-box rect → y 범위
+            y1_px = y2_px = None
+            for child in sys_elem:
+                child_cls = child.get("class", "") if hasattr(child, "get") else ""
+                if "bounding-box" in child_cls:
+                    for r in child.iter(r_tag):
+                        try:
+                            y_sv  = float(r.get("y", 0))
+                            h_sv  = float(r.get("height", 0))
+                            if h_sv > 0:
+                                y1_px = max(0, int(y_sv * scale_y) - _MARGIN)
+                                y2_px = min(img_h, int((y_sv + h_sv) * scale_y) + _MARGIN)
+                        except (ValueError, TypeError):
+                            pass
+                        break
+                    break
+
+            if y1_px is None:
+                continue  # bbox 없으면 건너뜀
+
+            sys_entries.append((y1_px, y2_px, nums))
+
+        # ── SVG bbox 파싱 실패 시 ImageSegmenter fallback ────────
+        if not sys_entries:
+            segmenter = ImageSegmenter(
+                staff_fill_ratio=self._seg_fill,
+                barline_fill_ratio=self._seg_bar,
+                system_gap_factor=self._seg_gap,
+            )
+            crops_by_sys = segmenter.get_measures_by_system(img)
+            result: list[list[dict]] = []
+            for s_idx, crops in enumerate(crops_by_sys):
+                if s_idx < len(sys_entries):
+                    nums_f = sys_entries[s_idx][2]
+                elif not sys_entries:
+                    nums_f = list(range(1, len(crops) + 1))
+                else:
+                    break
+                sl = [{"xml_number": nums_f[m_idx], "crop": crops[m_idx]}
+                      for m_idx in range(min(len(nums_f), len(crops)))]
+                if sl:
+                    result.append(sl)
+            return result
+
+        # ── 각 시스템 y 범위 내에서 barline 기반 마디 분할 ───────
+        segmenter = ImageSegmenter(
+            staff_fill_ratio=self._seg_fill,
+            barline_fill_ratio=self._seg_bar,
+            system_gap_factor=self._seg_gap,
+        )
+        gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+        _, binary = cv2.threshold(gray, 200, 255, cv2.THRESH_BINARY)
+        inv = cv2.bitwise_not(binary)
+
+        result = []
+        for y1_px, y2_px, xml_nums in sys_entries:
+            sys_region = SystemRegion(y1_px, y2_px, 0, img_w)
+            xs    = segmenter._detect_barlines(inv, sys_region)
+            crops = segmenter._crop_measures(img, sys_region, xs)
+            n_m   = min(len(xml_nums), len(crops))
+            sl = [{"xml_number": xml_nums[m_idx], "crop": crops[m_idx]}
+                  for m_idx in range(n_m)]
+            if sl:
+                result.append(sl)
+        return result
+
+
+# ── ImageSegmenter ──────────────────────────────────────────────────────────
+
+class ImageSegmenter:
+    """
+    악보 PNG에서 OpenCV 기반으로 마디별 crop 이미지를 추출.
+    보표선 검출 → 시스템 분리 → 마디선 검출 → 마디 crop.
+    """
+
+    def __init__(
+        self,
+        staff_fill_ratio: float = 0.25,
+        barline_fill_ratio: float = 0.05,
+        system_gap_factor: float = 5.0,
+        margin_px: int = 10,
+    ):
+        self.staff_fill_ratio = staff_fill_ratio
+        self.barline_fill_ratio = barline_fill_ratio
+        self.system_gap_factor = system_gap_factor
+        self.margin_px = margin_px
+
+    def get_all_measures(self, png_path: str) -> list[np.ndarray]:
+        """이미지 전체에서 마디별 crop 목록 반환 (페이지 순서)."""
+        # cv2.imread는 Windows에서 한글 경로를 지원하지 않으므로 imdecode 사용
+        buf = np.fromfile(png_path, dtype=np.uint8)
+        img = cv2.imdecode(buf, cv2.IMREAD_COLOR)
+        if img is None:
+            raise RuntimeError(f"이미지 읽기 실패: {png_path}")
+        return self._segment(img)
+
+    def get_all_measures_from_array(self, img: np.ndarray) -> list[np.ndarray]:
+        """numpy 배열에서 마디별 crop 목록 반환 (렌더링 이미지용)."""
+        return self._segment(img)
+
+    def get_measures_by_system(
+        self, source, n_systems: Optional[int] = None
+    ) -> list[list[np.ndarray]]:
+        """
+        마디 crop을 시스템별로 그룹화해서 반환.
+        source: 파일 경로(str/Path) 또는 BGR ndarray
+        n_systems: 강제 시스템 수 (SVG 파싱 결과 전달 시 정확도 향상)
+        Returns: list[system] of list[crop ndarray]
+        """
+        if isinstance(source, np.ndarray):
+            img = source
+        else:
+            buf = np.fromfile(str(source), dtype=np.uint8)
+            img = cv2.imdecode(buf, cv2.IMREAD_COLOR)
+            if img is None:
+                raise RuntimeError(f"이미지 읽기 실패: {source}")
+
+        gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+        _, binary = cv2.threshold(gray, 200, 255, cv2.THRESH_BINARY)
+        inv = cv2.bitwise_not(binary)
+
+        result: list[list[np.ndarray]] = []
+        for sys in self._detect_systems(inv, n_systems=n_systems):
+            xs    = self._detect_barlines(inv, sys)
+            crops = self._crop_measures(img, sys, xs)
+            if crops:
+                result.append(crops)
+        return result
+
+    def _segment(self, img: np.ndarray) -> list[np.ndarray]:
+        gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+        _, binary = cv2.threshold(gray, 200, 255, cv2.THRESH_BINARY)
+        inv = cv2.bitwise_not(binary)  # 잉크=255
+
+        systems = self._detect_systems(inv)
+        if not systems:
+            return []
+
+        all_crops: list[np.ndarray] = []
+        for sys in systems:
+            xs = self._detect_barlines(inv, sys)
+            crops = self._crop_measures(img, sys, xs)
+            all_crops.extend(crops)
+        return all_crops
+
+    def _detect_systems(
+        self, inv: np.ndarray, n_systems: Optional[int] = None
+    ) -> list[SystemRegion]:
+        h, w = inv.shape
+        horiz = np.sum(inv // 255, axis=1)  # 행별 검은 픽셀 수
+        min_fill = int(w * self.staff_fill_ratio)
+        staff_rows = np.where(horiz > min_fill)[0]
+        if len(staff_rows) == 0:
+            return []
+
+        # 연속 행 그룹화
+        groups: list[tuple[int, int]] = []
+        start = staff_rows[0]
+        prev = staff_rows[0]
+        for r in staff_rows[1:]:
+            if r - prev > 5:
+                groups.append((start, prev))
+                start = r
+            prev = r
+        groups.append((start, prev))
+
+        if len(groups) < 2:
+            y1 = max(0, groups[0][0] - self.margin_px)
+            y2 = min(h, groups[0][1] + self.margin_px)
+            return [SystemRegion(y1, y2, 0, w)]
+
+        line_ys = [(g[0] + g[1]) // 2 for g in groups]
+        gaps = [line_ys[i + 1] - line_ys[i] for i in range(len(line_ys) - 1)]
+
+        # n_systems 지정 시: 가장 큰 (n_systems-1)개 gap을 시스템 경계로 사용
+        if n_systems is not None and n_systems >= 1:
+            n_splits = n_systems - 1
+            if n_splits <= 0:
+                # 단일 시스템
+                y1 = max(0, groups[0][0] - self.margin_px)
+                y2 = min(h, groups[-1][1] + self.margin_px)
+                return [SystemRegion(y1, y2, 0, w)]
+            sorted_gap_indices = sorted(range(len(gaps)), key=lambda i: gaps[i], reverse=True)
+            split_indices = sorted(sorted_gap_indices[:n_splits])
+            systems: list[SystemRegion] = []
+            sys_start = 0
+            for i in split_indices:
+                y1 = max(0, groups[sys_start][0] - self.margin_px)
+                y2 = min(h, groups[i][1] + self.margin_px)
+                systems.append(SystemRegion(y1, y2, 0, w))
+                sys_start = i + 1
+            y1 = max(0, groups[sys_start][0] - self.margin_px)
+            y2 = min(h, groups[-1][1] + self.margin_px)
+            systems.append(SystemRegion(y1, y2, 0, w))
+            return systems
+
+        # n_systems 미지정: factor 기반 자동 검출
+        median_gap = float(np.median(gaps))
+        thresh = median_gap * self.system_gap_factor
+
+        systems = []
+        sys_start = 0
+        for i, gap in enumerate(gaps):
+            if gap > thresh:
+                y1 = max(0, groups[sys_start][0] - self.margin_px)
+                y2 = min(h, groups[i][1] + self.margin_px)
+                systems.append(SystemRegion(y1, y2, 0, w))
+                sys_start = i + 1
+        y1 = max(0, groups[sys_start][0] - self.margin_px)
+        y2 = min(h, groups[-1][1] + self.margin_px)
+        systems.append(SystemRegion(y1, y2, 0, w))
+        return systems
+
+    def _detect_barlines(self, inv: np.ndarray, sys: SystemRegion) -> list[int]:
+        h_sys = sys.y2 - sys.y1
+        if h_sys <= 0:
+            return []
+        roi = inv[sys.y1:sys.y2, sys.x1:sys.x2]
+        vert = np.sum(roi // 255, axis=0)
+        min_fill = int(h_sys * self.barline_fill_ratio)
+        cols = np.where(vert > min_fill)[0]
+        if len(cols) == 0:
+            return []
+
+        # 연속 열 그룹화 → 중심 X
+        xs: list[int] = []
+        grp = [cols[0]]
+        for c in cols[1:]:
+            if c - grp[-1] <= 4:
+                grp.append(c)
+            else:
+                xs.append(int(np.mean(grp)) + sys.x1)
+                grp = [c]
+        xs.append(int(np.mean(grp)) + sys.x1)
+
+        # 시스템 양끝 2% 이내 제거
+        w_sys = sys.x2 - sys.x1
+        margin = max(int(w_sys * 0.02), 5)
+        xs = [x for x in xs if sys.x1 + margin < x < sys.x2 - margin]
+        return sorted(xs)
+
+    def _crop_measures(
+        self, img: np.ndarray, sys: SystemRegion, barline_xs: list[int]
+    ) -> list[np.ndarray]:
+        if not barline_xs:
+            crop = img[sys.y1:sys.y2, sys.x1:sys.x2]
+            return [crop] if crop.size > 0 else []
+
+        borders = [sys.x1] + barline_xs + [sys.x2]
+        crops = []
+        for i in range(len(borders) - 1):
+            x1, x2 = borders[i], borders[i + 1]
+            if x2 - x1 < 20:
+                continue
+            crop = img[sys.y1:sys.y2, x1:x2]
+            if crop.size > 0:
+                crops.append(crop)
+        return crops
+
+
+# ── CandidateGenerator ──────────────────────────────────────────────────────
+
+class CandidateGenerator:
+    """
+    MusicXML의 특정 마디에 제한된 편집 후보를 생성.
+    lxml 기반 XML 파싱 + 음악 이론 제약 검증.
+    """
+
+    MAX_CANDIDATES = 20
+
+    def __init__(self, xml_path: str):
+        if _LXML_OK:
+            self._tree = _etree.parse(xml_path)
+            self._root = self._tree.getroot()
+        else:
+            self._tree = _etree.parse(xml_path)
+            self._root = self._tree.getroot()
+        _strip_ns(self._root)
+        self._divisions_cache: dict[int, int] = {}
+
+    # ── 퍼블릭 API ────────────────────────────────────────────────
+
+    def generate_candidates(
+        self, measure_number: int
+    ) -> Iterator[tuple[CandidateEdit, str]]:
+        """
+        마디 내 음표 하나씩 수정한 후보를 yield.
+        Yields: (CandidateEdit, xml_string)
+        """
+        measure = self._find_measure(self._root, measure_number)
+        if measure is None:
+            return
+        notes = self._get_notes(measure)
+        count = 0
+
+        for idx, note in enumerate(notes):
+            if count >= self.MAX_CANDIDATES:
+                break
+            is_rest = note.find("rest") is not None
+            is_chord_member = note.find("chord") is not None
+
+            if not is_rest:
+                # 음높이 ±1 반음
+                for delta, etype in [(+1, "pitch_up1"), (-1, "pitch_down1")]:
+                    cand_xml = self._apply_pitch_shift(measure_number, idx, delta)
+                    if cand_xml:
+                        edit = CandidateEdit(measure_number, idx, etype,
+                                            f"note[{idx}] pitch {'+' if delta>0 else ''}{delta}")
+                        yield edit, cand_xml
+                        count += 1
+                        if count >= self.MAX_CANDIDATES:
+                            return
+
+                # 음표 → 쉼표
+                # chord member 또는 chord head(다음 note에 <chord>가 있음)는 제외
+                # — MusicXML 구조 파괴로 Verovio 크래시
+                next_is_chord = (
+                    idx + 1 < len(notes)
+                    and notes[idx + 1].find("chord") is not None
+                )
+                if not is_chord_member and not next_is_chord:
+                    cand_xml = self._apply_to_rest(measure_number, idx)
+                    if cand_xml:
+                        yield CandidateEdit(measure_number, idx, "to_rest",
+                                           f"note[{idx}] → rest"), cand_xml
+                        count += 1
+                        if count >= self.MAX_CANDIDATES:
+                            return
+
+            # 길이 변경
+            for edit, cand_xml in self._duration_candidates(measure_number, idx, note):
+                yield edit, cand_xml
+                count += 1
+                if count >= self.MAX_CANDIDATES:
+                    return
+
+    def apply_edit(self, edit: CandidateEdit) -> None:
+        """채택된 편집을 내부 root에 영구 적용."""
+        if edit.edit_type in ("pitch_up1", "pitch_down1"):
+            delta = +1 if edit.edit_type == "pitch_up1" else -1
+            self._apply_pitch_shift_inplace(
+                self._root, edit.measure_number, edit.note_index, delta
+            )
+        elif edit.edit_type == "to_rest":
+            self._apply_to_rest_inplace(
+                self._root, edit.measure_number, edit.note_index
+            )
+        elif edit.edit_type in ("dur_x2", "dur_half", "dot_add", "dot_remove"):
+            self._apply_duration_inplace(
+                self._root, edit.measure_number, edit.note_index, edit.edit_type
+            )
+
+    def to_xml_string(self) -> str:
+        """현재 XML을 문자열로 반환."""
+        if _LXML_OK:
+            return _etree.tostring(
+                self._root, encoding="unicode", xml_declaration=False
+            )
+        else:
+            return _etree.tostring(self._root, encoding="unicode")
+
+    def save(self, out_path: str) -> None:
+        """현재 XML을 파일로 저장."""
+        xml_str = self.to_xml_string()
+        Path(out_path).write_text(xml_str, encoding="utf-8")
+
+    # ── 내부 헬퍼 ────────────────────────────────────────────────
+
+    def _find_measure(self, root, number: int):
+        """주어진 번호의 마디 중 음표(non-rest note)가 가장 많은 파트의 마디 반환.
+        다성부 악보에서 첫 파트가 쉼표만 있을 때 후보가 생성되지 않는 문제 방지."""
+        candidates = []
+        for m in root.iter("measure"):
+            try:
+                if int(m.get("number", 0)) == number:
+                    note_count = sum(
+                        1 for n in m.iter("note")
+                        if n.find("rest") is None
+                    )
+                    candidates.append((note_count, m))
+            except (ValueError, TypeError):
+                pass
+        if candidates:
+            candidates.sort(key=lambda x: x[0], reverse=True)
+            return candidates[0][1]
+        # fallback: 순서 기반
+        measures = list(root.iter("measure"))
+        if 1 <= number <= len(measures):
+            return measures[number - 1]
+        return None
+
+    def _get_notes(self, measure) -> list:
+        return list(measure.iter("note"))
+
+    def _get_divisions(self, measure_number: int) -> int:
+        if measure_number in self._divisions_cache:
+            return self._divisions_cache[measure_number]
+        for m in self._root.iter("measure"):
+            try:
+                n = int(m.get("number", 0))
+            except (ValueError, TypeError):
+                n = 0
+            div_el = m.find(".//divisions")
+            if div_el is not None and div_el.text:
+                try:
+                    d = int(div_el.text)
+                    self._divisions_cache[n] = d
+                except ValueError:
+                    pass
+        return self._divisions_cache.get(measure_number, 1)
+
+    def _expected_duration(self, measure_number: int) -> Optional[int]:
+        """박자표 기반 예상 마디 총 duration (divisions 단위)."""
+        divisions = self._get_divisions(measure_number)
+        # 박자표 탐색
+        beats, beat_type = 4, 4
+        for m in self._root.iter("measure"):
+            try:
+                n = int(m.get("number", 0))
+            except (ValueError, TypeError):
+                n = 0
+            ts = m.find(".//time")
+            if ts is not None:
+                b = ts.find("beats")
+                bt = ts.find("beat-type")
+                if b is not None and bt is not None:
+                    try:
+                        beats = int(b.text)
+                        beat_type = int(bt.text)
+                    except (ValueError, TypeError):
+                        pass
+            if n >= measure_number:
+                break
+        # 4분음표 1박 = divisions 단위
+        quarter_dur = divisions
+        beat_dur = quarter_dur * 4 // beat_type
+        return beats * beat_dur
+
+    def _measure_actual_duration(self, measure) -> int:
+        total = 0
+        for note in measure.iter("note"):
+            if note.find("chord") is not None:
+                continue
+            dur_el = note.find("duration")
+            if dur_el is not None and dur_el.text:
+                try:
+                    total += int(dur_el.text)
+                except ValueError:
+                    pass
+        return total
+
+    def _validate_measure(self, root, measure_number: int) -> bool:
+        """수정 후 마디 길이가 박자표와 맞는지 검증."""
+        m = self._find_measure(root, measure_number)
+        if m is None:
+            return False
+        expected = self._expected_duration(measure_number)
+        if expected is None:
+            return True
+        actual = self._measure_actual_duration(m)
+        return actual == expected
+
+    # ── 편집 생성 (deepcopy → xml string) ───────────────────────
+
+    def _apply_pitch_shift(
+        self, measure_number: int, note_idx: int, delta: int
+    ) -> Optional[str]:
+        new_root = deepcopy(self._root)
+        if not self._apply_pitch_shift_inplace(new_root, measure_number, note_idx, delta):
+            return None
+        if _LXML_OK:
+            return _etree.tostring(new_root, encoding="unicode")
+        return _etree.tostring(new_root, encoding="unicode")
+
+    def _apply_pitch_shift_inplace(self, root, measure_number, note_idx, delta) -> bool:
+        m = self._find_measure(root, measure_number)
+        if m is None:
+            return False
+        notes = self._get_notes(m)
+        if note_idx >= len(notes):
+            return False
+        note = notes[note_idx]
+        pitch = note.find("pitch")
+        if pitch is None:
+            return False
+        step_el = pitch.find("step")
+        alter_el = pitch.find("alter")
+        octave_el = pitch.find("octave")
+        if step_el is None or octave_el is None:
+            return False
+        step = step_el.text or "C"
+        alter = int(float(alter_el.text)) if alter_el is not None and alter_el.text else 0
+        octave = int(octave_el.text or "4")
+        ns, na, no = _shift_pitch(step, alter, octave, delta)
+        step_el.text = ns
+        octave_el.text = str(no)
+        if alter_el is not None:
+            alter_el.text = str(na)
+        elif na != 0:
+            alter_el_new = _etree.SubElement(pitch, "alter")
+            alter_el_new.text = str(na)
+        return True
+
+    def _apply_to_rest(self, measure_number: int, note_idx: int) -> Optional[str]:
+        new_root = deepcopy(self._root)
+        m = self._find_measure(new_root, measure_number)
+        if m is None:
+            return None
+        notes = self._get_notes(m)
+        if note_idx >= len(notes):
+            return None
+        note = notes[note_idx]
+        pitch = note.find("pitch")
+        if pitch is not None:
+            note.remove(pitch)
+        if note.find("rest") is None:
+            rest_el = _etree.SubElement(note, "rest")
+            # rest를 pitch 위치에 삽입 (첫 번째 자식으로)
+            note.remove(rest_el)
+            note.insert(0, rest_el)
+        # tie 제거
+        for tie in note.findall("tie"):
+            note.remove(tie)
+        if _LXML_OK:
+            return _etree.tostring(new_root, encoding="unicode")
+        return _etree.tostring(new_root, encoding="unicode")
+
+    def _apply_to_rest_inplace(self, root, measure_number, note_idx) -> None:
+        m = self._find_measure(root, measure_number)
+        if m is None:
+            return
+        notes = self._get_notes(m)
+        if note_idx >= len(notes):
+            return
+        note = notes[note_idx]
+        pitch = note.find("pitch")
+        if pitch is not None:
+            note.remove(pitch)
+        if note.find("rest") is None:
+            rest_el = _etree.SubElement(note, "rest")
+            note.remove(rest_el)
+            note.insert(0, rest_el)
+        for tie in note.findall("tie"):
+            note.remove(tie)
+
+    def _duration_candidates(
+        self, measure_number: int, note_idx: int, note
+    ) -> list[tuple[CandidateEdit, str]]:
+        results = []
+        type_el = note.find("type")
+        dur_el = note.find("duration")
+        dot_el = note.find("dot")
+        if type_el is None or dur_el is None:
+            return results
+        cur_type = type_el.text or "quarter"
+        try:
+            cur_dur = int(dur_el.text)
+        except (ValueError, TypeError):
+            return results
+
+        cur_idx = _TYPE_ORDER.index(cur_type) if cur_type in _TYPE_ORDER else -1
+
+        # dur_x2 (한 단계 올림)
+        if cur_idx >= 0 and cur_idx + 1 < len(_TYPE_ORDER):
+            cand = self._make_duration_candidate(
+                measure_number, note_idx, "dur_x2", cur_dur * 2,
+                _TYPE_ORDER[cur_idx + 1], remove_dot=True
+            )
+            if cand:
+                results.append((
+                    CandidateEdit(measure_number, note_idx, "dur_x2",
+                                 f"note[{note_idx}] {cur_type}→{_TYPE_ORDER[cur_idx+1]}"),
+                    cand
+                ))
+
+        # dur_half (한 단계 내림)
+        if cur_idx > 0 and cur_dur // 2 > 0:
+            cand = self._make_duration_candidate(
+                measure_number, note_idx, "dur_half", cur_dur // 2,
+                _TYPE_ORDER[cur_idx - 1], remove_dot=True
+            )
+            if cand:
+                results.append((
+                    CandidateEdit(measure_number, note_idx, "dur_half",
+                                 f"note[{note_idx}] {cur_type}→{_TYPE_ORDER[cur_idx-1]}"),
+                    cand
+                ))
+
+        # dot_add (점음표 추가, 현재 dot 없을 때)
+        if dot_el is None:
+            new_dur = int(cur_dur * 1.5)
+            cand = self._make_duration_candidate(
+                measure_number, note_idx, "dot_add", new_dur, cur_type, add_dot=True
+            )
+            if cand:
+                results.append((
+                    CandidateEdit(measure_number, note_idx, "dot_add",
+                                 f"note[{note_idx}] +dot"),
+                    cand
+                ))
+
+        # dot_remove (점음표 제거, 현재 dot 있을 때)
+        if dot_el is not None:
+            new_dur = int(cur_dur / 1.5)
+            cand = self._make_duration_candidate(
+                measure_number, note_idx, "dot_remove", new_dur, cur_type, remove_dot=True
+            )
+            if cand:
+                results.append((
+                    CandidateEdit(measure_number, note_idx, "dot_remove",
+                                 f"note[{note_idx}] -dot"),
+                    cand
+                ))
+
+        return results
+
+    def _make_duration_candidate(
+        self,
+        measure_number: int,
+        note_idx: int,
+        edit_type: str,
+        new_dur: int,
+        new_type: str,
+        add_dot: bool = False,
+        remove_dot: bool = False,
+    ) -> Optional[str]:
+        new_root = deepcopy(self._root)
+        self._apply_duration_inplace(
+            new_root, measure_number, note_idx, edit_type,
+            new_dur=new_dur, new_type=new_type,
+            add_dot=add_dot, remove_dot=remove_dot
+        )
+        if not self._validate_measure(new_root, measure_number):
+            return None
+        if _LXML_OK:
+            return _etree.tostring(new_root, encoding="unicode")
+        return _etree.tostring(new_root, encoding="unicode")
+
+    def _apply_duration_inplace(
+        self, root, measure_number, note_idx, edit_type,
+        new_dur=None, new_type=None, add_dot=False, remove_dot=False
+    ) -> None:
+        m = self._find_measure(root, measure_number)
+        if m is None:
+            return
+        notes = self._get_notes(m)
+        if note_idx >= len(notes):
+            return
+        note = notes[note_idx]
+        dur_el = note.find("duration")
+        type_el = note.find("type")
+        dot_el = note.find("dot")
+
+        if dur_el is None or type_el is None:
+            return
+
+        cur_type = type_el.text or "quarter"
+        try:
+            cur_dur = int(dur_el.text)
+        except (ValueError, TypeError):
+            return
+
+        cur_idx = _TYPE_ORDER.index(cur_type) if cur_type in _TYPE_ORDER else -1
+
+        if edit_type == "dur_x2" and new_dur is None:
+            if cur_idx + 1 < len(_TYPE_ORDER):
+                new_dur = cur_dur * 2
+                new_type = _TYPE_ORDER[cur_idx + 1]
+            else:
+                return
+        elif edit_type == "dur_half" and new_dur is None:
+            if cur_idx > 0 and cur_dur // 2 > 0:
+                new_dur = cur_dur // 2
+                new_type = _TYPE_ORDER[cur_idx - 1]
+            else:
+                return
+        elif edit_type == "dot_add" and new_dur is None:
+            new_dur = int(cur_dur * 1.5)
+            new_type = cur_type
+            add_dot = True
+        elif edit_type == "dot_remove" and new_dur is None:
+            new_dur = int(cur_dur / 1.5)
+            new_type = cur_type
+            remove_dot = True
+
+        if new_dur is not None:
+            dur_el.text = str(new_dur)
+        if new_type is not None:
+            type_el.text = new_type
+        if add_dot and dot_el is None:
+            _etree.SubElement(note, "dot")
+        if remove_dot and dot_el is not None:
+            note.remove(dot_el)
+
+
+# ── XMLCorrector ─────────────────────────────────────────────────────────────
+
+class XMLCorrector:
+    """
+    단일 MXL 파일에 대한 전체 교정 루프.
+    """
+
+    SSIM_SUSPECT  = 0.75
+    SSIM_IMPROVE  = 0.02
+    MIN_CROP_SIZE = 32  # SSIM 계산 최소 크기
+
+    def __init__(
+        self,
+        ssim_threshold: float = SSIM_SUSPECT,
+        ssim_min_improvement: float = SSIM_IMPROVE,
+        render_scale: int = 70,
+    ):
+        _check_deps()
+        self.ssim_threshold = ssim_threshold
+        self.ssim_min_improvement = ssim_min_improvement
+        self._renderer = MXLRenderer(scale=render_scale)
+        # 원본 스캔 이미지용 segmenter:
+        # barline_fill_ratio=0.85 — 피아노 대보의 실제 마디선만 검출 (클레프/브레이스 제외)
+        # system_gap_factor=9.0  — 대보 내부 treble/bass 간격 vs 시스템 간격 구분
+        self._segmenter = ImageSegmenter(
+            barline_fill_ratio=0.85,
+            system_gap_factor=9.0,
+        )
+
+    def correct(
+        self,
+        mxl_path: str,
+        orig_png_path: str,
+        out_xml_path: str,
+        debug_dir: Optional[str] = None,
+    ) -> CorrectionResult:
+        """
+        mxl_path:      Audiveris 출력 MXL
+        orig_png_path: 원본 악보 PNG (전처리 이전)
+        out_xml_path:  교정된 XML 저장 경로
+        debug_dir:     지정 시 마디별 비교 이미지(좌=렌더, 우=원본) 저장
+        """
+        result = CorrectionResult(xml_path=out_xml_path)
+
+        # ── 1. 렌더링: SVG bbox 기반으로 시스템별 마디 추출 ───
+        self._renderer.load(mxl_path)
+        try:
+            rendered_by_sys = self._renderer.get_measure_data_by_system(1)
+        except Exception as e:
+            result.warnings.append(f"렌더링 마디 추출 실패: {e}")
+            Path(out_xml_path).write_text(_extract_xml_from_mxl(mxl_path), encoding="utf-8")
+            return result
+
+        # ── 2. 원본 PNG: OpenCV 시스템별 마디 추출 ───────────
+        # n_systems 없이 factor 자동 검출 — 원본 스캔의 실제 시스템 수를 검출
+        try:
+            orig_by_sys = self._segmenter.get_measures_by_system(orig_png_path)
+        except Exception as e:
+            result.warnings.append(f"원본 PNG 마디 추출 실패: {e}")
+            Path(out_xml_path).write_text(_extract_xml_from_mxl(mxl_path), encoding="utf-8")
+            return result
+
+        if not rendered_by_sys or not orig_by_sys:
+            result.warnings.append("마디 분할 실패 — 교정 생략")
+            Path(out_xml_path).write_text(_extract_xml_from_mxl(mxl_path), encoding="utf-8")
+            return result
+
+        if debug_dir:
+            Path(debug_dir).mkdir(parents=True, exist_ok=True)
+
+        # ── 3. XML 로드 ────────────────────────────────────────
+        with tempfile.NamedTemporaryFile(
+            suffix=".xml", delete=False, mode="w", encoding="utf-8"
+        ) as tf:
+            tf.write(_extract_xml_from_mxl(mxl_path))
+            tmp_xml = tf.name
+
+        generator = CandidateGenerator(tmp_xml)
+
+        # ── 4. Flatten: xml_number 순서 × 원본 문서 순서 1:1 매칭 ──
+        # 렌더링 레이아웃과 원본 스캔 레이아웃이 달라도 각자의 순서가 같으면 맞음.
+        # rendered_flat: xml_number 오름차순 정렬 (SVG 구조 보장)
+        # orig_flat    : 시스템 순서 → 마디 순서 (top-left → bottom-right)
+        def _flatten_rendered(by_sys):
+            flat = []
+            for sys_list in by_sys:
+                flat.extend(sys_list)
+            flat.sort(key=lambda m: m["xml_number"])
+            return flat
+
+        orig_flat: list[np.ndarray] = []
+        for sys_list in orig_by_sys:
+            orig_flat.extend(sys_list)
+
+        if not orig_flat:
+            result.warnings.append("비교할 마디 없음")
+            generator.save(out_xml_path)
+            try:
+                os.unlink(tmp_xml)
+            except OSError:
+                pass
+            return result
+
+        result.warnings.append(
+            f"orig 마디 수: {len(orig_flat)}"
+        )
+
+        # ── 5. DP alignment 기반 라운드 루프 ────────────────────
+        MAX_ROUNDS = 3
+        for _round in range(MAX_ROUNDS):
+            rendered_by_sys = self._renderer.get_measure_data_by_system(1)
+            rendered_flat   = _flatten_rendered(rendered_by_sys)
+
+            result.warnings.append(
+                f"[round {_round+1}] rendered={len(rendered_flat)}, "
+                f"orig={len(orig_flat)}"
+            )
+
+            pairs = self._align_flat(rendered_flat, orig_flat)
+            if not pairs:
+                break
+
+            edits_this_round = 0
+
+            for r_idx, o_idx in pairs:
+                r_entry    = rendered_flat[r_idx]
+                o_crop     = orig_flat[o_idx]
+                xml_number = r_entry["xml_number"]
+                r_crop     = r_entry["crop"]
+
+                split_log: list[str] = []
+                base_score, proc_r, proc_o = self._measure_score(
+                    r_crop, o_crop, warnings_out=split_log)
+
+                result.warnings.append(
+                    f"  r{r_idx+1}↔o{o_idx+1} xml#{xml_number} "
+                    f"r={r_crop.shape[:2]} o={o_crop.shape[:2]} "
+                    f"score={base_score:.3f}"
+                    + (f" [{'; '.join(s.strip() for s in split_log)}]" if split_log else "")
+                )
+                if debug_dir:
+                    _save_debug_pair(debug_dir, _round, r_idx,
+                                     xml_number, base_score,
+                                     r_crop, o_crop, proc_r, proc_o)
+
+                if base_score >= self.ssim_threshold:
+                    continue
+
+                result.measures_checked += 1
+                best_score = base_score
+                best_edit: Optional[CandidateEdit] = None
+                best_cand_crop: Optional[np.ndarray] = None
+
+                cand_scores: list[str] = []
+                for edit, cand_xml_str in generator.generate_candidates(xml_number):
+                    cand_by_sys = self._renderer.render_candidate_measures(
+                        cand_xml_str, 1)
+                    if cand_by_sys is None:
+                        result.warnings.append(
+                            f"    xml#{xml_number} 후보 렌더 실패"
+                        )
+                        continue
+                    cand_flat = _flatten_rendered(cand_by_sys)
+                    if r_idx >= len(cand_flat):
+                        result.warnings.append(
+                            f"    xml#{xml_number} 후보 r_idx={r_idx} "
+                            f"범위 초과 (cand_flat={len(cand_flat)})"
+                        )
+                        continue
+                    cand_crop = cand_flat[r_idx]["crop"]
+                    score, _, _ = self._measure_score(cand_crop, o_crop)
+                    cand_scores.append(f"{edit.edit_type}={score:.3f}")
+
+                    improvement = score - base_score
+                    relative    = improvement / max(1e-6, 1.0 - base_score)
+                    if improvement >= 0.005 and relative >= 0.015:
+                        if score > best_score:
+                            best_score     = score
+                            best_edit      = edit
+                            best_cand_crop = cand_crop
+                result.warnings.append(
+                    f"    xml#{xml_number} 후보점수: "
+                    + (", ".join(cand_scores) if cand_scores else "후보없음")
+                )
+
+                if best_edit is not None:
+                    generator.apply_edit(best_edit)
+                    result.measures_corrected += 1
+                    edits_this_round += 1
+                    current_xml_str = generator.to_xml_string()
+                    self._renderer.load_xml_string(current_xml_str)
+                    # 이번 라운드 남은 마디는 갱신된 렌더 기준으로 평가
+                    rendered_by_sys = self._renderer.get_measure_data_by_system(1)
+                    rendered_flat   = _flatten_rendered(rendered_by_sys)
+                    if debug_dir and best_cand_crop is not None:
+                        _save_debug_pair(debug_dir, _round, r_idx,
+                                         xml_number, best_score,
+                                         best_cand_crop, o_crop,
+                                         best_cand=best_cand_crop)
+                else:
+                    result.warnings.append(
+                        f"    xml#{xml_number}: score={base_score:.3f}, "
+                        f"교정 후보 없음"
+                    )
+                    result.measures_fallback += 1
+
+            if edits_this_round == 0:
+                break   # 더 개선 없음 → 조기 종료
+
+        # ── 5. 교정된 XML 저장 ─────────────────────────────────
+        generator.save(out_xml_path)
+
+        try:
+            os.unlink(tmp_xml)
+        except OSError:
+            pass
+
+        return result
+
+    # ── 비교 엔진 ────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _prepare_compare_image(img: np.ndarray) -> np.ndarray:
+        """BGR 이미지 → 음표 골격만 남긴 binary (검=음표).
+        워터마크·가사·얼룩을 줄이고 threshold 200으로 이진화."""
+        gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) if img.ndim == 3 else img
+        gray = cv2.GaussianBlur(gray, (3, 3), 0)
+        _, binary = cv2.threshold(gray, 200, 255, cv2.THRESH_BINARY)
+        inv = cv2.bitwise_not(binary)          # 검=음표
+        # 작은 노이즈 제거 (area < 20 px)
+        num_labels, labels, stats, _ = cv2.connectedComponentsWithStats(inv, 8)
+        cleaned = np.zeros_like(inv)
+        for i in range(1, num_labels):
+            if stats[i, cv2.CC_STAT_AREA] >= 20:
+                cleaned[labels == i] = 255
+        return cleaned
+
+    def _score_pair(self, proc_a: np.ndarray, proc_b: np.ndarray) -> float:
+        """전처리된 binary 이미지 두 장의 복합 유사도 [0, 1].
+        masked SSIM 35% + x-투영 25% + y-투영 25% + barline IoU 10% + 여유 5%."""
+        try:
+            h = max(self.MIN_CROP_SIZE, min(proc_a.shape[0], proc_b.shape[0]))
+            w = max(self.MIN_CROP_SIZE, min(proc_a.shape[1], proc_b.shape[1]))
+            a = cv2.resize(proc_a, (w, h)).astype(np.float32) / 255.0
+            b = cv2.resize(proc_b, (w, h)).astype(np.float32) / 255.0
+
+            # A. masked SSIM (binary 이미지)
+            a8 = (a * 255).astype(np.uint8)
+            b8 = (b * 255).astype(np.uint8)
+            masked_ssim = float(_ssim(a8, b8))
+
+            # B. x-투영 상관 (음표 군집 수평 위치)
+            xp_a = a.sum(axis=0); xp_b = b.sum(axis=0)
+            xp_a /= (xp_a.max() + 1e-6); xp_b /= (xp_b.max() + 1e-6)
+            x_score = float(np.nan_to_num(np.corrcoef(xp_a, xp_b)[0, 1]))
+            x_score = (x_score + 1.0) / 2.0   # [-1,1] → [0,1]
+
+            # C. y-투영 상관 (음높이 대역)
+            yp_a = a.sum(axis=1); yp_b = b.sum(axis=1)
+            yp_a /= (yp_a.max() + 1e-6); yp_b /= (yp_b.max() + 1e-6)
+            y_score = float(np.nan_to_num(np.corrcoef(yp_a, yp_b)[0, 1]))
+            y_score = (y_score + 1.0) / 2.0
+
+            # D. barline 위치 정렬 (IoU)
+            bars_a = set(np.where(a.sum(axis=0) / (h + 1e-6) > 0.5)[0])
+            bars_b = set(np.where(b.sum(axis=0) / (h + 1e-6) > 0.5)[0])
+            if bars_a or bars_b:
+                bar_score = len(bars_a & bars_b) / len(bars_a | bars_b)
+            else:
+                bar_score = 1.0
+
+            return (0.35 * masked_ssim
+                    + 0.25 * x_score
+                    + 0.25 * y_score
+                    + 0.10 * bar_score
+                    + 0.05 * masked_ssim)   # 합계 1.0 (SSIM 비중 보정)
+        except Exception:
+            return 0.0
+
+    def _split_staff_bands(
+        self, proc: np.ndarray
+    ) -> "tuple[np.ndarray, np.ndarray] | None":
+        """binary (검=음표) 이미지에서 상·하 보표 사이 수평 공백을 찾아 분리.
+        피아노 대보 전용 휴리스틱. 반환: (upper_proc, lower_proc) 또는 None."""
+        h = proc.shape[0]
+        lo, hi = int(h * 0.3), int(h * 0.7)
+        row_fill = proc[lo:hi].sum(axis=1) / (proc.shape[1] * 255.0 + 1e-6)
+        gap_mask = (row_fill < 0.04).tolist()
+
+        # run-length → 가장 긴 연속 True 구간
+        best_start, best_len = 0, 0
+        cur_start, cur_len   = 0, 0
+        for k, val in enumerate(gap_mask):
+            if val:
+                if cur_len == 0:
+                    cur_start = k
+                cur_len += 1
+                if cur_len > best_len:
+                    best_len  = cur_len
+                    best_start = cur_start
+            else:
+                cur_len = 0
+
+        if best_len < 3:    # 3행 이상 공백이어야 보표 구분
+            return None
+        split_y = lo + best_start + best_len // 2
+        return proc[:split_y], proc[split_y:]
+
+    @staticmethod
+    def _detect_staff_lines(
+        proc: np.ndarray,
+        diag: "list[str] | None" = None,
+    ) -> "list[StaffBand]":
+        """binary (검=음표) crop에서 5선 그룹을 검출.
+        반환: list of StaffBand(y1, y2, spacing_px). 검출 실패 시 [].
+        diag: 디버그 문자열 수집용 (None 이면 생략)."""
+        from scipy.signal import find_peaks
+        h, w = proc.shape[:2]
+        row_sums = proc.sum(axis=1).astype(np.float32)
+        threshold = w * 255 * 0.15  # 너비의 15% 이상 채워진 행
+        peaks, _ = find_peaks(row_sums, height=threshold, distance=2)
+        if diag is not None:
+            diag.append(f"peaks={len(peaks)} thr={threshold:.0f} img={h}x{w}")
+        if len(peaks) < 5:
+            return []
+
+        gaps = np.diff(peaks)
+        median_gap = float(np.median(gaps))
+        if diag is not None:
+            diag.append(f"median_gap={median_gap:.1f}")
+        if median_gap < 1.0:
+            return []
+
+        bands: list[StaffBand] = []
+        i = 0
+        while i <= len(peaks) - 5:
+            group = peaks[i:i + 5]
+            g = np.diff(group)
+            if g.max() < median_gap * 1.5 and g.min() > median_gap * 0.5:
+                sp = float(np.mean(g))
+                y1 = max(0, int(group[0] - sp * 0.8))
+                y2 = min(h, int(group[-1] + sp * 0.8))
+                bands.append(StaffBand(y1=y1, y2=y2, spacing_px=sp))
+                i += 5
+            else:
+                i += 1
+        if diag is not None:
+            diag.append(f"bands={len(bands)}")
+        return bands
+
+    @staticmethod
+    def _detect_staff_lines_from_raw(
+        img: np.ndarray,
+        diag: "list[str] | None" = None,
+    ) -> "list[StaffBand]":
+        """CC 필터 없이 raw BGR 이미지에서 5선을 검출.
+        원본 스캔에 사용 — CC 필터가 끊어진 5선 조각을 제거하는 문제 우회."""
+        from scipy.signal import find_peaks
+        gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) if img.ndim == 3 else img
+        gray = cv2.GaussianBlur(gray, (3, 3), 0)
+        _, binary = cv2.threshold(gray, 200, 255, cv2.THRESH_BINARY)
+        proc = cv2.bitwise_not(binary)  # 검=전경
+        h, w = proc.shape[:2]
+        row_sums = proc.sum(axis=1).astype(np.float32)
+        # 높은 임계값(60%) — 5선처럼 거의 꽉 찬 행만 검출, 음표 peak 제거
+        threshold = w * 255 * 0.60
+        peaks, _ = find_peaks(row_sums, height=threshold, distance=2)
+        if diag is not None:
+            diag.append(
+                f"raw_peaks={len(peaks)} thr={threshold:.0f} img={h}x{w}"
+                f" max_row={row_sums.max():.0f}")
+        if len(peaks) < 5:
+            return []
+        gaps = np.diff(peaks)
+        median_gap = float(np.median(gaps))
+        if diag is not None:
+            diag.append(f"median_gap={median_gap:.1f}")
+        if median_gap < 1.0:
+            return []
+        bands: list[StaffBand] = []
+        i = 0
+        while i <= len(peaks) - 5:
+            group = peaks[i:i + 5]
+            g = np.diff(group)
+            if g.max() < median_gap * 1.5 and g.min() > median_gap * 0.5:
+                sp = float(np.mean(g))
+                y1 = max(0, int(group[0] - sp * 0.8))
+                y2 = min(h, int(group[-1] + sp * 0.8))
+                bands.append(StaffBand(y1=y1, y2=y2, spacing_px=sp))
+                i += 5
+            else:
+                i += 1
+        if diag is not None:
+            diag.append(f"bands={len(bands)}")
+        return bands
+
+    @staticmethod
+    def _normalize_to_staff_scale(
+        proc_r: np.ndarray,
+        proc_o: np.ndarray,
+        bands_r: "list[StaffBand]",
+        bands_o: "list[StaffBand]",
+    ) -> "tuple[np.ndarray, float]":
+        """렌더 crop을 원본의 5선 간격에 맞게 upscale.
+        반환: (proc_r_scaled, scale_factor)."""
+        if not bands_r or not bands_o:
+            return proc_r, 1.0
+        sp_r = float(np.median([b.spacing_px for b in bands_r]))
+        sp_o = float(np.median([b.spacing_px for b in bands_o]))
+        if sp_r < 1.0:
+            return proc_r, 1.0
+        scale = min(sp_o / sp_r, 5.0)
+        if scale < 1.0:
+            # 원본 spacing이 렌더보다 작음 — 다운스케일 불필요, fallback
+            return proc_r, 1.0
+        if abs(scale - 1.0) < 0.1:
+            return proc_r, scale
+        new_h = int(proc_r.shape[0] * scale)
+        new_w = int(proc_r.shape[1] * scale)
+        scaled = cv2.resize(proc_r, (new_w, new_h),
+                            interpolation=cv2.INTER_LINEAR)
+        return scaled, scale
+
+    def _measure_score(
+        self, r_crop: np.ndarray, o_crop: np.ndarray,
+        warnings_out: "list[str] | None" = None,
+    ) -> "tuple[float, np.ndarray, np.ndarray]":
+        """마디 두 장의 최종 유사도 점수 + 전처리 이미지 반환.
+        반환: (score, proc_r, proc_o)"""
+        proc_r = self._prepare_compare_image(r_crop)
+        proc_o = self._prepare_compare_image(o_crop)
+
+        diag_r: list[str] = []
+        diag_o: list[str] = []
+        bands_r = self._detect_staff_lines(proc_r, diag_r)
+        bands_o = self._detect_staff_lines_from_raw(o_crop, diag_o)
+
+        # 해상도 정규화: 렌더를 원본 5선 간격에 맞게 upscale
+        proc_r_norm, scale = self._normalize_to_staff_scale(
+            proc_r, proc_o, bands_r, bands_o)
+        if warnings_out is not None and abs(scale - 1.0) > 0.1:
+            warnings_out.append(
+                f"  scale={scale:.2f}x "
+                f"(render {proc_r.shape[1]}px → {proc_r_norm.shape[1]}px)")
+
+        # per-staff 비교 (양쪽 모두 검출 성공 시, 공통 개수 비교)
+        if bands_r and bands_o:
+            scaled_bands_r = [
+                StaffBand(int(b.y1 * scale), int(b.y2 * scale),
+                          b.spacing_px * scale)
+                for b in bands_r]
+            n = min(len(scaled_bands_r), len(bands_o))
+            scores = []
+            for i in range(n):
+                br = scaled_bands_r[i]
+                bo = bands_o[i]
+                cr = proc_r_norm[br.y1:br.y2]
+                co = proc_o[bo.y1:bo.y2]
+                if cr.size > 0 and co.size > 0:
+                    scores.append(self._score_pair(cr, co))
+            if scores:
+                if warnings_out is not None:
+                    warnings_out.append(
+                        f"  per-staff scores({len(scores)}): "
+                        f"{[f'{s:.3f}' for s in scores]}")
+                return float(np.mean(scores)), proc_r, proc_o
+
+        # fallback: 기존 방식
+        if warnings_out is not None:
+            warnings_out.append(
+                f"  staff detection 실패 → fallback"
+                f" [r:{' '.join(diag_r)} | o:{' '.join(diag_o)}]")
+        return self._score_pair(proc_r_norm, proc_o), proc_r, proc_o
+
+    def _align_flat(
+        self,
+        rendered_flat: "list[dict]",
+        orig_flat: "list[np.ndarray]",
+    ) -> "list[tuple[int, int]]":
+        """DP sequence alignment으로 최적 (r_idx, o_idx) 쌍 반환.
+        30마디 초과 시 단순 1:1 fallback."""
+        n, m = len(rendered_flat), len(orig_flat)
+        if n > 30 or m > 30:
+            return list(zip(range(min(n, m)), range(min(n, m))))
+
+        S = np.zeros((n, m), dtype=np.float32)
+        for i in range(n):
+            for j in range(m):
+                score, _, _ = self._measure_score(
+                    rendered_flat[i]["crop"], orig_flat[j])
+                S[i][j] = score
+
+        GAP = -0.1
+        dp = np.full((n + 1, m + 1), -np.inf, dtype=np.float32)
+        dp[0, 0] = 0.0
+        for i in range(n + 1):
+            for j in range(m + 1):
+                if i == 0 and j == 0:
+                    continue
+                best = -np.inf
+                if i > 0 and j > 0:
+                    best = max(best, dp[i-1, j-1] + S[i-1, j-1])
+                if i > 0:
+                    best = max(best, dp[i-1, j] + GAP)
+                if j > 0:
+                    best = max(best, dp[i, j-1] + GAP)
+                dp[i, j] = best
+
+        # 역추적 (float equality → abs 비교)
+        pairs: list[tuple[int, int]] = []
+        i, j = n, m
+        while i > 0 and j > 0:
+            if abs(dp[i, j] - (dp[i-1, j-1] + S[i-1, j-1])) < 1e-5:
+                pairs.append((i-1, j-1))
+                i -= 1; j -= 1
+            elif i > 0 and dp[i-1, j] >= dp[i, j-1]:
+                i -= 1
+            else:
+                j -= 1
+        pairs.reverse()
+        return pairs
+
+    def _ssim(self, img_a: np.ndarray, img_b: np.ndarray) -> float:
+        """두 이미지의 SSIM 점수 계산. 실패 시 0.0 반환. (하위 호환용)"""
+        try:
+            h = max(self.MIN_CROP_SIZE, min(img_a.shape[0], img_b.shape[0]))
+            w = max(self.MIN_CROP_SIZE, min(img_a.shape[1], img_b.shape[1]))
+            a = cv2.resize(img_a, (w, h))
+            b = cv2.resize(img_b, (w, h))
+            a_g = cv2.cvtColor(a, cv2.COLOR_BGR2GRAY)
+            b_g = cv2.cvtColor(b, cv2.COLOR_BGR2GRAY)
+            score, _ = _ssim(a_g, b_g, full=True)
+            return float(score)
+        except Exception:
+            return 0.0

requirements-server.txt

@@ -0,0 +1,4 @@
+# Server dependencies for Hugging Face Spaces deployment
+gradio>=4.0.0
+pymupdf>=1.23.0
+opencv-python-headless>=4.9.0