https://github.com/tsukamotoshio/sumisoraomr
An OMR to Jianpu (numbered musical notation) converter/一个五线谱转简谱工具
https://github.com/tsukamotoshio/sumisoraomr
jianpu midi music-notation musicxml omr python
Last synced: about 1 month ago
JSON representation
An OMR to Jianpu (numbered musical notation) converter/一个五线谱转简谱工具
- Host: GitHub
- URL: https://github.com/tsukamotoshio/sumisoraomr
- Owner: Tsukamotoshio
- License: agpl-3.0
- Created: 2026-04-02T10:17:09.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-28T10:05:42.000Z (about 1 month ago)
- Last Synced: 2026-04-28T10:34:36.603Z (about 1 month ago)
- Topics: jianpu, midi, music-notation, musicxml, omr, python
- Language: Python
- Homepage:
- Size: 2.38 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# SumisoraOMR
> Batch-convert Western staff notation (PDF / PNG / JPG) to Jianpu (numbered musical notation) PDFs, with optional MIDI output.
[](LICENSE)
[]()
[]()
**[中文说明 →](README.zh.md)**
---
## Features
- Batch-processes files from the `Input` folder; results land in `Output`
- Skips already-converted files automatically (hash-based deduplication)
- Optional MIDI generation alongside each Jianpu PDF
- Handles Chinese, Japanese, and other non-ASCII filenames
- Optional super-resolution upscaling to improve recognition on low-quality scans
---
## Engines
### OMR (Optical Music Recognition)
| Engine | Best for | Notes |
|--------|----------|-------|
| **Audiveris** | Digital PDFs | Reads PDFs exported from notation software (MuseScore, Sibelius, Finale, etc.). Fast and accurate on clean vector files — no GPU needed. |
| **Homr** | Scans & photos | AI-powered engine for PNG/JPG images of printed or photographed sheet music. Handles noise and real-world imperfections; GPU-accelerated (CUDA / DirectML). |
> Auto mode picks **Audiveris** for PDF files and **Homr** for images (PNG/JPG) automatically.
### Super-Resolution (optional pre-processing)
| Engine | Notes |
|--------|-------|
| **Real-ESRGAN** | Default SR engine; higher-fidelity upscaling; anime-optimized models; Vulkan GPU-accelerated |
| **waifu2x-ncnn-vulkan** | Alternative SR engine; Vulkan GPU-accelerated |
---
## Usage
### Conversion
1. Drop your staff notation files (`.pdf`, `.png`, `.jpg`) into the `Input`
folder, or drag them directly into the file sidebar.
2. Launch the app — double-click the **SumisoraOMR** shortcut or run
`SumisoraOMR.exe`.
3. In the file sidebar, check the files you want to convert.
4. Choose an OMR engine (or leave it on **Auto**), then click **Start Conversion**.
5. Confirm options in the dialog (MIDI generation, skip duplicates) and
click **Start Conversion**.
6. Converted Jianpu PDFs appear in the `Output` folder.
### Jianpu Preview
After conversion, switch to the **Jianpu Preview** tab to browse all
generated PDFs. Check files using the checkboxes, then click the export
button in the sidebar header to copy them to a folder of your choice.
Click **Edit Jianpu** in the top bar to open the currently previewed file
in the editor.
### Jianpu Editor
The editor lets you inspect and manually correct `.jianpu.txt` source files.
The left pane shows the original score image for reference; the right pane
contains editable Jianpu text. After editing, click **Regenerate PDF** to
rebuild the output.
### Transposer
The transposer reads a MusicXML score from `xml-scores/` and renders it in
a different key. Three modes are available:
- **By semitone** — enter an exact semitone offset.
- **By interval** — choose a named interval (perfect 4th, major 3rd, etc.)
and direction.
- **Diatonic** — shift notes by scale degree within the current key.
Settings auto-preview on any change. The result can be exported as a Jianpu
PDF or a staff-notation PDF.
---
## Running from Source
**Prerequisites**
- Python 3.10+
- JDK 17+ on `PATH` (required only for PDF recognition via Audiveris)
- The following runtime directories alongside the repo root:
| Directory | Purpose |
|-----------|---------|
| `omr_engine/audiveris/` | Audiveris OMR engine — used for PDF inputs |
| `lilypond-2.24.4/` | LilyPond engraving engine |
| `jdk/` | Java runtime for Audiveris |
| `omr_engine/homr/` | Homr deep-learning OMR engine — used for PNG/JPG inputs |
| `waifu2x-ncnn-vulkan/` *(optional)* | waifu2x SR binary |
| `realesrgan-runtime/` *(optional)* | Real-ESRGAN binary and models |
**Install dependencies**
```bash
pip install -r requirements.txt
```
**Run**
```bash
python app.py
```
For hot-reload during development:
```bash
flet run app.py
```
---
## Directory Layout
```
Input/ # Drop source files here
Output/ # Converted Jianpu PDFs and MIDIs
editor-workspace/ # Intermediate .jianpu.txt files for manual editing
xml-scores/ # MusicXML archives (used by the transposer)
logs/ # Runtime logs
THIRD_PARTY_NOTICES.md # Third-party component licenses
```
---
## Known Limitations
- **Recognition accuracy** depends heavily on scan quality. Blurry or complex scores may produce wrong or missing notes.
- **Polyphony** — scores with many voices or dense chords may retain only the main melody.
- **No lyrics** — only note data is exported.
- **Processing speed** — Homr processes images in seconds; Audiveris startup is slow and multi-page PDFs can take several minutes.
- **Edge cases** — uncommon time signatures or mid-piece key changes may yield inaccurate results.
---
## Attribution
Integration, scripting, feature development, and packaging by **Tsukamotoshio**.
When redistributing, please retain this notice and `THIRD_PARTY_NOTICES.md` to distinguish:
- **Integration & packaging**: Tsukamotoshio
- **Third-party component copyrights & licenses**: remain with their respective authors (see `THIRD_PARTY_NOTICES.md`)
---
## License
This project is licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)** — see the [`LICENSE`](LICENSE) file for details.
This tool bundles third-party components (Audiveris, LilyPond, music21, waifu2x-ncnn-vulkan, Real-ESRGAN, and others). Their respective licenses are listed in [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).