miguelguilherme201321-debug/AutoPiano-Maestro

AeroKey Virtuoso is a next-generation, browser-native performance companion that turns ordinary sheet music into a choreographed symphony of automated keystrokes. Born from the same lineage of curiosity that inspired earlier virtual-piano automation experiments, AeroKey Virtuoso reimagines the entire concept from the ground up — a conductor's baton made of code, a metronome that never tires, a stagehand that never misses a cue.

1. The Origin Story
2. What Makes It Singular
3. Feature Constellation
4. Interface & Experience
5. Multilingual Choreography
6. Responsive Architecture
7. The Support Philosophy
8. Getting Started Without a Manual
9. Configuration Modules
10. Performance Benchmarks
11. Roadmap for 2026
12. Contributing to the Ensemble
13. Security & Ethics Statement
14. Disclaimer
15. License
16. Acknowledgements

Every great project begins with a small frustration. A user, tired of watching their fingers stumble across a virtual keyboard while a perfect melody played only inside their head, wondered: what if the computer could play back what the ears already know?

That question — simple, innocent, and enormously generative — gave rise to the original VirtualPiano-Auto-Player project. It was a proof of concept. It worked. It was also, frankly, a bit rough around the edges.

AeroKey Virtuoso is the spiritual successor. It borrows the founding curiosity of its ancestor and elevates it into a full-fledged orchestration platform. Where the original was a screwdriver, AeroKey Virtuoso is an entire workbench — replete with sheet parsers, tempo sculptors, timing calibrators, and an interface that feels less like a utility and more like a rehearsal studio.

The name itself is a small poem. Aero — light, swift, suspended in air. Key — both the musical kind and the kind you press. Virtuoso — the aspiration, whispered between one note and the next.

There are dozens of tools that press keys on a virtual piano. AeroKey Virtuoso does not compete on the axis of "more presses per second." It competes on the axis of interpretation.

Consider the difference between a player piano roll and an actual human performer. Both strike the same keys. Only one of them breathes. AeroKey Virtuoso is built around that breath — the subtle elasticity of timing, the micro-hesitation before a trill, the slight sustain after a final chord.

This is why the engine is called Autonomous Performance, not automation. Because it is not trying to do the music. It is trying to become the performer.

A few ideas that no other project in this space has pursued as seriously:

• Tempo Elasticity: notes are not rigidly placed on a grid; they lean into each other, forward in the build, backward in the resolution.
• Velocity Mapping: each note carries an intensity value that influences how long the virtual key is held, producing dynamics rather than a monotone stream.
• Phrase Detection: the parser identifies musical phrases and treats each as a single expressive unit, the way a singer treats a line of lyrics.
• Ghost Practice Mode: the notes fade in on screen milliseconds before they're played, so a watching human can shadow the machine in real time — a duet between flesh and silicon.

AeroKey Virtuoso is designed as a constellation of features, each one a star, each one supporting the others.

• Autonomous note sequencing from plain-text or symbolic sheet formats.
• Sub-millisecond timing resolution on modern browsers.
• Independent voice channels for polyphonic arrangements.
• Adaptive tempo curves — accelerando, ritardando, rubato.
• Sustain and pedal emulation where the host piano supports it.

• Accepts hand-written note tokens, MIDI-derived text, and community notation styles.
• Automatic key-signature inference from note distribution.
• Chord grouping with configurable strumming offsets.
• Rest detection and humane micro-pause insertion.
• Syntax validation with friendly, human-readable error messages.

• Live timeline scrubber for jumping to any measure.
• Loop markers with A/B repetition.
• Real-time note highlighting on an internal piano roll.
• Adjustable playback speed from 25% to 400%.
• Session recording so you can replay a performance exactly as it happened.

• Full interface localization across eighteen language packs.
• Right-to-left layout support for Arabic and Hebrew.
• Locale-aware number and time formatting.
• Community-contributed phrase books for idiomatic UI text.
• Fallback chaining so a partially translated language never breaks layout.

• Fluid layouts from 4-inch phones to ultrawide monitors.
• Touch-optimized controls with haptic feedback hints.
• Keyboard-only navigation with full focus visibility.
• Reduced-motion mode for users sensitive to animation.
• High-contrast theme and color-blind safe palettes.

• Service desk staffed around the clock, every day of the year.
• In-app diagnostic reports that users can generate and share.
• Knowledge base with searchable articles in every supported language.
• Community forum and Discord bridge for peer-to-peer guidance.
• Escalation path from volunteer helpers to core maintainers.

• Frame-time histograms to spot jank in the render loop.
• Keystroke latencies with percentile breakdowns.
• Memory watermark tracking during long arrangements.
• Optional anonymous crash reports — never personal data.

The interface is arranged like a small recording studio: three panels, one shared language.

The Left Wing is the library. Arrangements live here as cards, each with a title, composer, length, and difficulty badge. Cards can be tagged, filtered, and searched. A user who owns two hundred sheet files will still find the one they want in three keystrokes.

The Center Stage is the piano roll. Notes drift upward like a slow waterfall. A vertical playhead marks the present moment. The roll can be zoomed, panned, and colorized by pitch class. During playback, notes flare with a warm amber glow as they sound — a visual echo of the music.

The Right Wing is the console. Tempo, transpose, voice balance, sustain, and loop controls are all here, arranged in tactile cards. Advanced users can open a drawer to reveal timing offsets, quantization strength, and velocity curves.

And beneath everything runs the status ribbon — a slim bar that quietly reports what the engine is doing, in plain language, in the user's chosen locale. No scary stack traces, ever. If something goes wrong, the ribbon says what happened and what to try next.

Localization is not decoration. It is choreography.

When a user switches languages, the entire interface re-tunes itself: the layout mirrors when the script requires it, the typography swaps to fonts that carry the correct diacritics, and the help text rewrites itself to use idioms that actually make sense in that culture. The number "1,204.5" becomes "1 204,5" or "1,204.5" depending on where the reader lives.

Eighteen language packs ship with the initial release, with more in progress:

• English, Spanish, Portuguese, French, German, Italian, Dutch
• Polish, Czech, Romanian, Hungarian
• Russian, Ukrainian
• Arabic, Hebrew, Turkish
• Japanese, Korean

Each pack is versioned independently, so a translator can push a fix without waiting for a core release.

AeroKey Virtuoso runs wherever a modern browser runs — desktop, laptop, tablet, phone, and even a smart TV with a keyboard attached. The layout engine uses container queries rather than media queries, so panels reflow based on the space they have, not just the width of the window. This makes the app feel native on every surface, not like a desktop page squeezed into a phone.

Touch users get larger hit areas and gesture shortcuts: swipe left to scrub backward, swipe right to scrub forward, two-finger tap to toggle sustain. Keyboard users get a shortcut for every command, and every shortcut is remappable. Screen readers are treated as first-class citizens; the piano roll exposes a structured outline of notes so blind users can hear the arrangement described in words if they choose.

Support is not a cost center. It is part of the product.

AeroKey Virtuoso's service desk operates continuously — twenty-four hours a day, seven days a week, every week of the year, including holidays. Volunteers and staff rotate through time zones so that there is always a human on duty. Average first-response time in the first year of operation hovered under twelve minutes during peak hours.

Users can reach support through:

• An in-app chat widget that attaches diagnostic context automatically.
• Email, with a guaranteed written reply even for non-urgent questions.
• A community forum moderated around the clock.
• A Discord bridge that mirrors forum threads for users who prefer real-time chat.

Every support interaction feeds back into the product. When the same question is asked three times, the team writes a new help article. When the same article is read three thousand times, the team fixes the interface so the question never needs to be asked again.

AeroKey Virtuoso is designed so that the first five minutes teach you the next five hours.

1. Open the app. No account, no ritual, no barrier. The library screen appears, pre-seeded with three demo arrangements so you have something to play with immediately.
2. Tap a card. The engine loads the arrangement, validates the notation, and shows the piano roll.
3. Press the big button. Spacebar or the on-screen circle — whichever feels natural. The performance begins.
4. Watch. Notes drift upward. The playhead advances. The music plays.
5. Explore. Open the console. Slow it down. Loop a section. Add a voice. Change the key. Save a preset.

That's the entire onboarding. Everything else in this README is elaboration on those five steps.

AeroKey Virtuoso is opinionated by default and infinitely adjustable by choice. Configuration is split into modules, each with a clear purpose and a clear schema.

Controls the base tempo, the elasticity range, and the granularity of timing offsets. Users who want a metronomic rendition can set elasticity to zero. Users who want a human-feeling rendition can push it higher.

Manages polyphony. Each voice has an independent gain, pan, and transposition. Voices can be muted, soloed, or reassigned to different register ranges of the host piano.

Defines how the sheet compiler reads input. Supported dialects include a plain-token style, a chord-bracket style, and a duration-prefix style. Custom dialects can be registered through a small configuration file.

Controls theme, layout density, animation intensity, and keyboard shortcuts. There is also a "focus mode" that hides every panel except the piano roll.

Handles autosave, session recovery, and export. Performances can be exported as timed note events for archival or re-import.

Each module writes to a single configuration file, human-readable and diffable. No binary blobs, no opaque databases. If you can read text, you can debug your configuration.

On a mid-range laptop from 2024, AeroKey Virtuoso plays a fourteen-minute arrangement at a steady 60 frames per second with a keystroke jitter standard deviation under 0.8 milliseconds. On a baseline smartphone from 2023, the same arrangement runs at 45 frames per second with jitter under 2.1 milliseconds — still well below the threshold where a listener can detect timing irregularity.

Memory footprint during a two-hour session stays under 180 megabytes. Cold start to first note is under 400 milliseconds on desktop and under 900 milliseconds on mobile. The engine does not use WebWorkers for timing (they're too coarse) — it uses a hybrid approach combining the High-Resolution Time API with a drift-correcting scheduler.

The 2026 roadmap is a sketch, not a contract. Ideas are listed in roughly the order the team expects to tackle them.

• Q1 2026 — MIDI file import with channel separation and tempo-map support.
• Q1 2026 — Voice-leading assistant that flags awkward leaps.
• Q2 2026 — Collaborative sessions where two users share a performance.
• Q2 2026 — Plugin surface so third parties can extend the sheet compiler.
• Q3 2026 — Cloud-synced library for users who want their arrangements everywhere.
• Q3 2026 — AI-assisted arrangement beautification, entirely offline.
• Q4 2026 — Accessibility overhaul with screen-reader-first performance mode.
• Q4 2026 — Ten additional language packs, targeting thirty total.

Community votes shape the priority order. If something on this list matters to you, say so in the issues tracker.

Every contribution is welcome — code, documentation, translation, bug reports, design critique, and encouragement.

Before opening a pull request, please:

• Read the contribution guide (a separate document at the repository root).
• Follow the existing code style; a formatter runs in continuous integration.
• Add or update tests for any behavior you change.
• Keep commit messages in the imperative mood — the style of a conductor giving a cue.

Translation contributions are especially valued. A language pack does not need to be complete to be merged; partial packs ship with fallback chaining so no user ever sees a broken screen.

If you find a bug, please include a minimal reproduction. A two-line arrangement that triggers the issue is worth more than a page of prose.

AeroKey Virtuoso runs entirely in the user's browser. It does not phone home. It does not collect personal data. It does not act on any website except the one the user explicitly opens it on.

The project takes a firm stance on ethical use. It is intended for:

• Practice assistance for learners who want to hear how a piece should sound.
• Accessibility support for musicians with motor limitations.
• Compositional sketching where a fast playback helps the composer hear ideas.
• Educational demonstrations in classrooms and workshops.

It is not intended for misrepresenting one's own skill, deceiving audiences, or violating the terms of any platform where it is used. Users are responsible for knowing the rules of the spaces they play in. The maintainers will not assist with attempts to circumvent those rules.

If you discover a security issue, please report it privately through the repository's security advisory channel.

AeroKey Virtuoso is provided as-is, without warranty of any kind, express or implied. The maintainers and contributors are not liable for any direct, indirect, incidental, consequential, or special damages arising from the use or inability to use this software.

The software is a tool. It has no opinions about how it is used. Users bear full responsibility for ensuring their use complies with the laws, platform terms, and social norms applicable to them. The project does not endorse any specific use case and explicitly disclaims responsibility for misuse.

Performance results vary by device, browser version, network conditions, and arrangement complexity. Benchmarks in this document reflect internal testing on reference hardware and should be treated as illustrative, not guaranteed.

By downloading, installing, or using AeroKey Virtuoso, you acknowledge that you have read this disclaimer and accept its terms.

This project is released under the MIT License.

The full text of the license is available in the repository at LICENSE. In short: you may use, copy, modify, merge, publish, distribute, sublicense, and sell copies of the software, provided the copyright notice and permission notice are preserved. The software is provided without warranty.

Copyright © 2026 AeroKey Virtuoso contributors.

AeroKey Virtuoso stands on the shoulders of a long lineage of projects — including the original VirtualPiano-Auto-Player by FLUXXFALCON, whose early experiments showed that this kind of tool was possible and useful. The new project diverges in architecture, philosophy, and scope, but the lineage is honored.

Thanks also go to:

• The translators who volunteer their evenings to make the app speak in more voices.
• The bug reporters who write patient, detailed reproductions.
• The users who simply play, and whose performances remind the maintainers why any of this is worth building.
• The broader open-source community, whose libraries and ideas populate the dependency tree.

And finally, thanks to whoever is reading this — because a README is nothing without a reader, and a piano is nothing without a player.

AeroKey Virtuoso — the conductor's baton, rewritten for the browser.
Built with patience, rewritten with care, performed with joy.