Metadata-Version: 2.4
Name: pyclef
Version: 1.0.8
Summary: Desktop OMR tool for turning sheet music into annotations, audio, MIDI, and synchronized video.
Author: Vinicius Fernandes
Project-URL: Homepage, https://viniciusfs14.github.io/PyClef/
Project-URL: Repository, https://github.com/viniciusfs14/PyClef
Keywords: omr,sheet-music,music,midi,computer-vision
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Win32 (MS Windows)
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: PySide6>=6.6
Requires-Dist: numpy>=1.24
Requires-Dist: opencv-python>=4.8
Requires-Dist: Pillow>=10
Requires-Dist: pydub>=0.25
Requires-Dist: pdf2image>=1.17
Requires-Dist: mido>=1.3
Requires-Dist: moviepy>=1.0
Requires-Dist: ultralytics>=8.3

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="pyclef_app/ui/logo_black.png">
    <source media="(prefers-color-scheme: light)" srcset="pyclef_app/ui/logo.png">
    <img src="pyclef_app/ui/logo.png" alt="PyClef logo" width="260">
  </picture>
</p>

<h1 align="center">PyClef</h1>

<p align="center">
  <strong>Desktop Optical Music Recognition for annotations, MIDI, MP3, and synchronized video.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/pyclef/">
    <img alt="PyPI" src="https://img.shields.io/pypi/v/pyclef?color=40d6ff&label=PyPI">
  </a>
  <img alt="Python" src="https://img.shields.io/badge/python-3.10%2B-40d6ff">
  <img alt="Platform" src="https://img.shields.io/badge/platform-Windows-40d6ff">
  <img alt="Status" src="https://img.shields.io/badge/status-alpha-101827">
  <a href="https://pypi.org/project/pyclef/">
    <img alt="Downloads" src="https://img.shields.io/pypi/dm/pyclef?color=40d6ff">
  </a>
</p>

<p align="center">
  <a href="https://viniciusfs14.github.io/PyClef/">Website</a>
  |
  <a href="https://pypi.org/project/pyclef/">PyPI</a>
  |
  <a href="https://github.com/viniciusfs14/PyClef">Repository</a>
</p>

---

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:

```bash
pip install pyclef
```

Then launch the desktop app:

```bash
pyclef
```

Or start it from Python:

```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:

```text
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:

```bash
PYCLEF_FLUIDSYNTH_PATH=/path/to/fluidsynth
```

On Windows PowerShell:

```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:

```text
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:

```text
~/.pyclef/models/best.pt
```

Or set the environment variable:

```bash
PYCLEF_MODEL_PATH=/path/to/best.pt
```

On Windows PowerShell:

```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:

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

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

```bash
PYCLEF_SOUNDFONT_PATH=/path/to/piano.sf2
```

On Windows PowerShell:

```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:

```text
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:

```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:

```python
{
    "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:

```text
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.
