pyclef 1.0.8

Desktop OMR tool for turning sheet music into annotations, audio, MIDI, and synchronized video.

PyClef

Desktop Optical Music Recognition for annotations, MIDI, MP3, and synchronized video.

Website | PyPI | Repository

---

PyClef is a desktop Optical Music Recognition (OMR) tool for converting sheet music into annotated score pages, MIDI, MP3 audio, and synchronized video.

It combines neural symbol detection with staff-aware post-processing to make score recognition easier to inspect, hear, and review.

Features

• PDF, PNG, JPG, and JPEG score input
• Annotated score image output
• MIDI export
• MP3 audio rendering
• Optional SoundFont piano rendering through FluidSynth
• Synchronized MP4 video preview
• Desktop interface with English and Portuguese support
• Automatic model download on first use

Installation

Install PyClef from PyPI:

pip install pyclef

Then launch the desktop app:

pyclef

Or start it from Python:

from pyclef import Pyclef

Pyclef()

External Requirements

PyClef depends on a few external tools for full functionality.

Poppler

PDF input is handled through pdf2image, which requires Poppler.

On Windows, install Poppler and make sure the Poppler bin directory is available. The default path used by PyClef is:

C:\poppler\Library\bin

You can adjust this path in pyclef_app/config.py if needed.

FFmpeg

MP3 and video generation use audio/video processing libraries that may require FFmpeg.

Make sure FFmpeg is installed and available in your system PATH.

FluidSynth

PyClef includes an internal audio synthesizer by default. For a more realistic piano sound, the desktop app also provides a SoundFont piano option.

That option requires FluidSynth. Install FluidSynth and make sure the executable is available in your system PATH, or set:

PYCLEF_FLUIDSYNTH_PATH=/path/to/fluidsynth

On Windows PowerShell:

$env:PYCLEF_FLUIDSYNTH_PATH="C:\tools\fluidsynth\bin\fluidsynth.exe"
pyclef

Model File

The YOLO model is not bundled inside the PyPI package because the file is large.

When PyClef starts processing a score, it looks for the model in this order:

1. PYCLEF_MODEL_PATH, if set.
2. The user cache folder at ~/.pyclef/models/best.pt.
3. Automatic download from PYCLEF_MODEL_URL.

By default, PYCLEF_MODEL_URL points to:

https://github.com/viniciusfs14/PyClef/releases/download/model-v1.0.0/best.pt.zip

If automatic download is available, PyClef will download and extract the model on first use.

For manual setup, place the model here:

~/.pyclef/models/best.pt

Or set the environment variable:

PYCLEF_MODEL_PATH=/path/to/best.pt

On Windows PowerShell:

$env:PYCLEF_MODEL_PATH="C:\path\to\best.pt"
pyclef

SoundFont Audio

The SoundFont file is not bundled inside the PyPI package. When SoundFont piano is selected, PyClef looks for the SoundFont in this order:

1. PYCLEF_SOUNDFONT_PATH, if set.
2. The user cache folder at ~/.pyclef/soundfonts/GeneralUser-GS.sf2.
3. Automatic download from PYCLEF_SOUNDFONT_URL.

By default, PYCLEF_SOUNDFONT_URL points to the GeneralUser GS SoundFont:

https://raw.githubusercontent.com/mrbumpy409/GeneralUser-GS/main/GeneralUser-GS.sf2

For manual setup, place a .sf2 file anywhere and set:

PYCLEF_SOUNDFONT_PATH=/path/to/piano.sf2

On Windows PowerShell:

$env:PYCLEF_SOUNDFONT_PATH="C:\path\to\piano.sf2"
pyclef

Basic Workflow

1. Open PyClef.
2. Select a PDF or image score.
3. Choose the outputs you want to generate.
4. Set the BPM.
5. Run processing.
6. Open the generated result folder.

Each run creates a result folder named after the input file:

results_score-name/
  score-name_annotated_p1.jpg
  score-name.mp3
  score-name.mid
  score-name.mp4

The generated files depend on the output options selected in the interface.

Programmatic Usage

PyClef can also be called from Python:

from pyclef import process_score_files

result = process_score_files(
    file_list=["score.pdf"],
    bpm=90,
    output_options={
        "annotations": True,
        "audio": True,
        "midi": True,
        "video": False,
        "timbre": "soundfont_piano",
        "language": "en",
    },
)

print(result)

Example return value:

{
    "annotations": ["results_score/score_annotated_p1.jpg"],
    "audio": "results_score/score.mp3",
    "midi": "results_score/score.mid"
}

Research Context

PyClef is part of an Optical Music Recognition research workflow focused on turning object detection results into usable musical output.

The project uses MIRP, a staff-referenced musical inference method, to reconstruct pitch from detected symbols using staff geometry and clef context.

Project website:

https://viniciusfs14.github.io/PyClef/

Current Status

PyClef is under active development.

The current version is suitable for experimentation, demonstrations, and research-oriented score processing. Recognition quality can vary depending on scan quality, notation density, and symbol detection performance.

License

See the repository license for usage terms.