# songhaotian694-oss/pdf-to-musescore architecture

> Architecture diagram of the GitHub repository songhaotian694-oss/pdf-to-musescore, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/songhaotian694-oss/pdf-to-musescore
- Repository: https://github.com/songhaotian694-oss/pdf-to-musescore

## Overview

This is a local skill for converting printed-score PDFs into editable MuseScore projects. The principal workflow is: review and group every source page, run Audiveris recognition, import/export through MuseScore, then validate and deliver a draft or validated MSCZ. Further documented branches handle evidence-linked correction, playback, layout, reference-score comparison, and optional MIDI. The README documents orchestration, but the main conversion script was not sampled, so some internal call wiring is shown only where the documented workflow supports it.

Main entry points: [`scripts/convert-score.ps1`](https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/convert-score.ps1) (Conversion orchestrator), [`scripts/verify-output.ps1`](https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/verify-output.ps1) (Output verification), [`scripts/score-playback.py`](https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/score-playback.py) (Playback mapping), [`scripts/score-correction.py`](https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/score-correction.py) (Correction worklist)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_review["Page review"]
  node_preflight["Preflight and groups<br/>[score-structure.py]"]
  node_plan["Reviewed page plan<br/>[page-selection.md]"]
end

subgraph group_conversion["Recognition conversion"]
  node_convert["Conversion orchestrator<br/>[convert-score.ps1]"]
  node_raster["Grayscale fallback"]
  node_musicxml["MusicXML / MXL<br/>[convert-score.ps1]"]
end

subgraph group_validation["Validation correction"]
  node_structure["Structure and rest checks<br/>[score-structure.py]"]
  node_reference["Reference timeline<br/>[reference-mscz.md]"]
  node_worklist["Correction worklist"]
  node_verify["Output verification<br/>[verify-output.ps1]"]
end

subgraph group_finishing["Score finishing"]
  node_layout["Layout policy<br/>[score-layout.py]"]
  node_playback["Playback mapping<br/>[score-playback.py]"]
  node_midi["Optional MIDI<br/>[score-playback.py]"]
  node_result["MSCZ and reports<br/>[convert-score.ps1]"]
end

node_user(("User / reviewer"))
node_pdf["Source PDF"]
node_audiveris["Audiveris OMR"]
node_musescore["MuseScore Studio"]

node_user -->|"starts conversion"| node_convert
node_pdf -->|"provides source"| node_convert
node_convert -->|"prepares pages"| node_preflight
node_preflight -->|"presents review"| node_user
node_user -->|"reviews all pages"| node_plan
node_plan -->|"selects page group"| node_convert
node_convert -->|"runs recognition"| node_audiveris
node_convert -->|"prepares fallback"| node_raster
node_raster -->|"supplies fallback PDF"| node_audiveris
node_audiveris -->|"returns recognition project"| node_convert
node_convert -->|"imports and exports"| node_musescore
node_musescore -->|"exports score data"| node_musicxml
node_convert -->|"checks candidate"| node_structure
node_convert -.->|"compares reference"| node_reference
node_convert -->|"applies break policy"| node_layout
node_convert -->|"assigns instruments"| node_playback
node_playback -->|"uses score copy"| node_musescore
node_musescore -.->|"optionally exports"| node_midi
node_playback -.->|"verifies events"| node_midi
node_convert -->|"runs acceptance checks"| node_verify
node_structure -->|"provides findings"| node_worklist
node_verify -->|"provides failures"| node_worklist
node_worklist -->|"guides correction"| node_user
node_convert -->|"writes deliverables"| node_result
node_verify -->|"reports status"| node_result

click node_convert "https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/convert-score.ps1"
click node_preflight "https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/score-structure.py"
click node_plan "https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/references/page-selection.md"
click node_raster "https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/prepare-omr-input.py"
click node_musicxml "https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/convert-score.ps1"
click node_structure "https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/score-structure.py"
click node_reference "https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/references/reference-mscz.md"
click node_worklist "https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/score-correction.py"
click node_layout "https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/score-layout.py"
click node_playback "https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/score-playback.py"
click node_midi "https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/score-playback.py"
click node_verify "https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/verify-output.ps1"
click node_result "https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/convert-score.ps1"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_preflight,node_plan,node_user toneBlue
class node_convert,node_raster,node_musicxml toneAmber
class node_structure,node_reference,node_worklist,node_verify toneMint
class node_layout,node_playback,node_midi,node_result toneRose
class node_pdf,node_audiveris,node_musescore toneIndigo
```

## Components

### Page review

- [Preflight and groups](https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/score-structure.py): `scripts/score-structure.py`
- [Reviewed page plan](https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/references/page-selection.md): `references/page-selection.md`

### Recognition conversion

- [Conversion orchestrator](https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/convert-score.ps1): `scripts/convert-score.ps1`
- [Grayscale fallback](https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/prepare-omr-input.py): `scripts/prepare-omr-input.py`
- [MusicXML / MXL](https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/convert-score.ps1): `scripts/convert-score.ps1`

### Validation correction

- [Structure and rest checks](https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/score-structure.py): `scripts/score-structure.py`
- [Reference timeline](https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/references/reference-mscz.md): `references/reference-mscz.md`
- [Correction worklist](https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/score-correction.py): `scripts/score-correction.py`
- [Output verification](https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/verify-output.ps1): `scripts/verify-output.ps1`

### Score finishing

- [Layout policy](https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/score-layout.py): `scripts/score-layout.py`
- [Playback mapping](https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/score-playback.py): `scripts/score-playback.py`
- [Optional MIDI](https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/score-playback.py): `scripts/score-playback.py`
- [MSCZ and reports](https://github.com/songhaotian694-oss/pdf-to-musescore/blob/main/scripts/convert-score.ps1): `scripts/convert-score.ps1`

### Other components

- **User / reviewer**
- **Source PDF**
- **Audiveris OMR**
- **MuseScore Studio**

## Connections

- User / reviewer → Conversion orchestrator: starts conversion
- Source PDF → Conversion orchestrator: provides source
- Conversion orchestrator → Preflight and groups: prepares pages
- Preflight and groups → User / reviewer: presents review
- User / reviewer → Reviewed page plan: reviews all pages
- Reviewed page plan → Conversion orchestrator: selects page group
- Conversion orchestrator → Audiveris OMR: runs recognition
- Conversion orchestrator → Grayscale fallback: prepares fallback
- Grayscale fallback → Audiveris OMR: supplies fallback PDF
- Audiveris OMR → Conversion orchestrator: returns recognition project
- Conversion orchestrator → MuseScore Studio: imports and exports
- MuseScore Studio → MusicXML / MXL: exports score data
- Conversion orchestrator → Structure and rest checks: checks candidate
- Conversion orchestrator → Reference timeline: compares reference
- Conversion orchestrator → Layout policy: applies break policy
- Conversion orchestrator → Playback mapping: assigns instruments
- Playback mapping → MuseScore Studio: uses score copy
- MuseScore Studio → Optional MIDI: optionally exports
- Playback mapping → Optional MIDI: verifies events
- Conversion orchestrator → Output verification: runs acceptance checks
- Structure and rest checks → Correction worklist: provides findings
- Output verification → Correction worklist: provides failures
- Correction worklist → User / reviewer: guides correction
- Conversion orchestrator → MSCZ and reports: writes deliverables
- Output verification → MSCZ and reports: reports status