Piano Performance Assessment System
Technical Notes | Wanyi Deng

Reproduce the case study

Use a desktop Python installation with Tk support. In a virtual environment, open the 03_Prototype folder and run the following commands.

    python -m pip install -r requirements.txt
    python recompute_take.py

The script reads the saved reference and performance events and calls the original assessment function. It runs without a connected keyboard. Compare the output with Data/Recomputed_Metrics_EN.json. The recorded take contains 42 reference notes and 43 performed notes. Across the 40 eligible inter-onset intervals (IOIs), the mean absolute timing error is 51.83 ms. Across the 42 aligned note pairs, the mean absolute difference in MIDI note-on velocity is 11.81 units. The overall score is 90.5 out of 100.

Record a new performance

    python MIDI_Beginner_Assessment_Full_English_UI.py

Connect a MIDI keyboard, import Data/Twinkle_Twinkle_Little_Star.mid, refresh the MIDI ports, and select the keyboard input. Start recording, play the melody, and stop recording. Select Pitch, Rhythm, Dynamics, or Overall to run assessment before exporting a JSON report. Playback supports pygame and an optional FluidSynth installation with a compatible SoundFont.

Data and figures

Twinkle_Twinkle_Little_Star.mid contains the reference performance.
Performance_Report_Original.json preserves the original export, including its original field names, captured note events, and live classifications. The final-metrics field was empty when the file was saved.
Live_Events_EN.csv presents the live classifications in English. Onset offsets include the wait before the first note. Rhythm assessment uses differences between consecutive onsets.
Twinkle_Performance_From_Report.mid reconstructs the recorded take from its 43 performed notes, preserving channel, pitch, note-on velocity, and timing to MIDI tick precision.
Recomputed_Metrics_EN.json gives the offline results calculated from the original export. Dynamics are reported separately from the overall score.
Detail_Views/ contains enlargements of the velocity display and scoring code. Version 1.1 uses English display messages and includes desktop packaging fixes. The original scoring algorithm and export schema are retained.
