PIANO PERFORMANCE ASSESSMENT SYSTEM
Wanyi Deng | English Desktop Application | Version 1.1

ABOUT THIS PROGRAM

This program contains a MIDI-based piano performance assessment module developed by Wanyi Deng within a collaborative acoustic-piano retrofit project. The original project report explains the wider team system and the individual MIDI assessment contribution.

The module compares reference MIDI notes with a recorded MIDI performance and presents note alignment, pitch accuracy, timing differences, and MIDI note-on velocity differences. The desktop interface provides live feedback, Pitch, Rhythm, Dynamics, and Overall assessment controls, a staff view, and JSON report export. Version 1.1 uses English score summaries, logs, live statistics, and audio status text.

WHAT IS INCLUDED

PianoAssessment.app
    Standalone English application for supported Apple Silicon Macs.
Sample_Data/
    Reference MIDI, reconstructed performance MIDI, original event report,
    English live-event CSV, and recomputed numerical results.
Source_Code/
    Updated source, dependencies, build specification, Data/, and the
    case-study recomputation script. See BUILD.txt for build details.
Validation/
    validation.json: checks performed on the packaged application.
    sample-export.json: a report exported during functional verification.
ThirdPartyLicenses/
    License texts for included third-party components.
README_EN.txt
    This guide.

The original project PDF, team demonstration video, and listening-example audio files are NOT included in this program bundle. They should be supplied separately if this program is submitted as part of an application portfolio.

COMPATIBILITY

The supplied .app is an Apple Silicon (M1 and later M-series) Mac build. Its declared minimum system version is macOS 14; it was tested on macOS 26.6.2, arm64. Other macOS releases have not been tested on separate machines.

The .app includes its Python runtime and dependencies. It does not require VS Code, a separate Python installation, or an Internet connection for assessment and playback. Windows and Intel Mac executables are not included; those platforms require a separate compatible build and testing. This is not a universal executable for every computer.

The application uses the existing pygame synthesized tone. It does not bundle FluidSynth or a SoundFont piano library. It is ad hoc signed for local execution and has not received Apple Developer ID signing or notarization. macOS may restrict an application received from another computer.

TRY THE APPLICATION

1. Extract the ZIP, then open PianoAssessment.app.
2. Click Import Reference MIDI. The file chooser opens the bundled sample-data directory; choose Twinkle_Twinkle_Little_Star.mid.
3. Click Play Reference MIDI to hear it. Stop All Audio stops playback. No MIDI keyboard is needed for this step.
4. To record a new performance, connect a MIDI keyboard, click Refresh Ports, and select its input under MIDI Input.
5. Adjust the metronome if required, then click Start Recording (Live Feedback). Play the piece and click Stop Recording.
6. Select Pitch, Rhythm, Dynamics, or Overall to assess the performance.
7. Use View Staff & Error Notes to inspect notes, or Export JSON Report to save a report in a chosen location.

The graphical application does not import a saved JSON performance for reassessment. Without a connected keyboard, reviewers can play the reference MIDI, inspect the provided results, or reproduce the case study from source as described below. User-selected filenames and device names retain their original text. The English interface preserves the original internal JSON field names, including Chinese keys, for data compatibility.

REPRODUCE THE SAVED CASE STUDY

This optional step requires a desktop Python installation with Tk support. In a virtual environment, open Source_Code and run:

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

A MIDI keyboard is not needed. The script reads the original saved events and recomputes the assessment. Compare its output with Data/Recomputed_Metrics_EN.json.

Expected example results:
    Reference notes: 42
    Performed notes: 43
    Correct / wrong / extra / missed notes: 40 / 2 / 1 / 0
    Pitch accuracy: 95.2381%
    Mean absolute inter-onset-interval error: 51.8320 ms
    Mean absolute MIDI note-on velocity difference: 11.8095 units
    Overall score: 90.5 / 100

Timing assessment uses differences between consecutive note onsets. The live onset offsets include the wait before the first note. Dynamics are reported separately from the overall score. Performance_Report_Original.json had an empty final-metrics field; the recomputed results and validation export are separate evidence, not edits to that original recording.

VALIDATION SCOPE

See Validation/validation.json for the actual checks and results. Verification covers application initialization, the real audio mixer, reference MIDI playback, a temporary virtual CoreMIDI recording path, scoring, JSON export, staff view, metronome, and shutdown. Virtual MIDI verification does not establish physical-keyboard compatibility. No physical MIDI keyboard was used for this packaging validation; audio-device and mixer checks do not replace human listening.

RECOMMENDED ADDITIONS FOR A SCHOOL PORTFOLIO

Provide the following alongside this program, subject to the school's rules:

- The original project PDF: explain the problem, method, results, and which work was individual versus collaborative.
- The original team demonstration video: label it clearly as the team-system demonstration.
- A new English-interface screencast, approximately 1–3 minutes if the portal allows: show importing reference MIDI, recording or a clearly identified saved demonstration, live feedback, assessment results, and export. This is a recommendation; a new screencast is not included here.
- The original reference and recorded-performance audio examples, with clear filenames and a short listening note.
- A concise start-here note giving the review order and identifying this Mac application as optional supporting material.

Reviewers should be able to understand the project from the PDF and media without installing software or owning a MIDI keyboard. The original team video should not be described as a new walkthrough of the updated English interface. The original listening examples are separate files and do not establish that the application's built-in tone has the same timbre.

The receiving school determines the permitted file types, sizes, durations, and supplementary links. If executables or ZIP archives are not accepted, submit the allowed report and media in the required fields; include source or application access only where supplementary materials are permitted.
