SyMuPe/PianoFlow-base

1---2library_name: symupe3license: cc-by-nc-sa-4.04datasets:5- SyMuPe/PERiScoPe6tags:7- music8- piano9- midi10- expressive-performance11- transformer12- flow-matching13---14 15# SyMuPe: PianoFlow16 17**PianoFlow-base** is the flagship generative model of the SyMuPe framework. It utilizes **Conditional Flow Matching (CFM)** to render high-fidelity symbolic expressive piano performances from musical scores.18 19Introduced in the paper: [**SyMuPe: Affective and Controllable Symbolic Music Performance**](https://arxiv.org/abs/2511.03425).20 21- **GitHub:** https://github.com/ilya16/SyMuPe22- **Website:** https://ilya16.github.io/SyMuPe23- **Dataset:** https://huggingface.co/datasets/SyMuPe/PERiScoPe24 25## Architecture26 27- **Type:** Transformer Encoder28- **Objective:** Conditional Flow Matching (CFM)29- **Inputs:** 30  - **Score features (y):** `Pitch`, `Position`, `PositionShift`, `Duration`31  - **Performance features (x):** `Velocity`, `TimeShift`, `TimeDuration`, `TimeDurationSustain`32  - **Conditioning (c_s):** `Velocity` and `Tempo` score tokens for tempo and dynamics.33- **Outputs:** Probablity flow for performance feature values.34- **Training:** Trained for 300,000 iterations on the [PERiScoPe v1.0](https://huggingface.co/datasets/SyMuPe/PERiScoPe) dataset as described in the paper.35 36## Quick Start37 38Before using this model, ensure you have the `symupe` library installed:39```shell40pip install -U symupe41```42 43Use the following code to render performances:44 45```python46import torch47from symupe import AutoGenerator48 49device = torch.device("cuda" if torch.cuda.is_available() else "cpu")50 51# Build Generator by loading the model and tokenizer directly from the Hub52generator = AutoGenerator.from_pretrained("SyMuPe/PianoFlow-base", device=device)53# model, tokenizer = generator.model, generator.tokenizer54 55# Perform score MIDI (tokenization is handled inside)56gen_results = generator.perform_score(57    "score.mid",58    use_score_context=True,59    num_samples=8,60    seed=23,61)62# gen_results[i] is PerformanceRenderingResult(...) containing:63# - score_midi, score_seq, gen_seq, perf_seq, perf_midi, perf_midi_sus64 65# Save performed MIDI files66generator.save_performances(gen_results, out_dir="samples/pianoflow")67```68 69## License70 71The model weights are distributed under the [CC-BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/deed.en) license.72 73 74## Citation75 76If you use the dataset, please cite the paper:77 78```bibtex79@inproceedings{borovik2025symupe,80  title = {{SyMuPe: Affective and Controllable Symbolic Music Performance}},81  author = {Borovik, Ilya and Gavrilev, Dmitrii and Viro, Vladimir},82  year = {2025},83  booktitle = {Proceedings of the 33rd ACM International Conference on Multimedia},84  pages = {10699--10708},85  doi = {10.1145/3746027.3755871}86}87```