virtual-piano-player 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AxmadjonTeacher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# 🎹 Virtual Piano Player
+
+> Autonomous browser-controlled virtual piano player with 88 visible keys, sustain pedal resonance, and studio-grade Web Audio synthesis. Designed as both a standalone CLI and an AI agent skill for **Antigravity**.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node: >=18](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+[![Puppeteer](https://img.shields.io/badge/puppeteer--core-%5E25.0.0-orange.svg)](https://pptr.dev/)
+
+---
+
+## ✨ Features
+
+- 🎹 **Full 88-Key Keyboard Support**: Automatically expands layout to Full and sets visible keys to Max (88 keys).
+- 🔊 **Studio Direct Native Audio Bridge**: Bypasses OS keyboard input lag by connecting directly into the underlying Web Audio synthesis engine with visual key glow feedback.
+- 🎼 **Curated Song Library**: Includes masterpieces by Chopin, Yann Tiersen, Beethoven, Vivaldi, Nicholas Britell, and Dr. Dre.
+- ⚡ **Instant Execution**: Run immediately via `npx`, install globally via `npm`, or use as an AI agent skill in Antigravity.
+- 🛡️ **Auto-Healing & Recovery**: Pre-flight singleton lock cleanup and signal traps ensure smooth playback with zero orphaned browser processes.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Instant Run via NPX
+Play any song instantly without manual installation:
+
+```bash
+npx virtual-piano-player amelie
+# or
+npx virtual-piano-player nocturne
+```
+
+---
+
+### 2. Global CLI Installation
+Install globally to get access to the `piano` and `virtual-piano` commands:
+
+```bash
+npm install -g virtual-piano-player
+
+# View catalog
+piano
+
+# Play songs
+piano amelie
+piano nocturne
+piano succession
+piano still
+```
+
+---
+
+### 3. Install as an Antigravity AI Agent Skill
+To equip your Antigravity agent or assistant with piano playing capabilities:
+
+```bash
+# Clone directly into your global agents skills directory:
+git clone https://github.com/AxmadjonTeacher/virtual-piano.git ~/.agents/skills/virtual-piano-player
+cd ~/.agents/skills/virtual-piano-player
+npm install
+```
+
+---
+
+## 🎵 Song Catalog
+
+| Alias | Shortcut | Title | Composer / Artist | Key | Duration |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| `amelie` | `play-amelie` | Amélie (Comptine d'un autre été) | Yann Tiersen | E minor | ~122s |
+| `nocturne` | `play-nocturne` | Nocturne Op. 9 No. 2 (Andante) | Frédéric Chopin (Csabay Domonkos) | Eb major | ~248s |
+| `succession` | `play-succession` | Succession (Main Title Theme) | Nicholas Britell | C minor | ~89s |
+| `still` | `play-still` | Still D.R.E. (Polished Master) | Dr. Dre ft. Snoop Dogg | A minor | ~66s |
+| `paint` | `play-paint` | Paint It, Black | The Rolling Stones (Westworld) | E minor | ~50s |
+| `winter` | `play-winter` | Winter (L'Inverno - Allegro) | Antonio Vivaldi | F minor | ~45s |
+| `chopin` | `play-chopin` | Impromptu-Etude in C# minor | Frédéric Chopin style | C# minor | ~60s |
+| `elise` | `play-elise` | Für Elise (Bagatelle No. 25) | Ludwig van Beethoven | A minor | ~25s |
+
+---
+
+## 🛠️ CLI Usage & Options
+
+```text
+Virtual Piano Player CLI
+Usage: piano [options] [song_alias]
+
+Options:
+  --song, -s <name>   Preset song name or alias (e.g. "amelie", "nocturne", "still")
+  --list, -l          Display the interactive song catalog table
+  --file, -f <path>   Path to custom song JSON file
+  --tempo, -t <float> Tempo multiplier (default: 1.0; e.g. 1.2 for faster, 0.8 for slower)
+  --headless <bool>   Run in headless mode (default: false)
+  --sustain <bool>    Enable sustain pedal (default: true)
+  --help, -h          Show help message
+```
+
+### Examples:
+```bash
+# Play Chopin Nocturne at 1.15x tempo
+piano nocturne --tempo 1.15
+
+# Run in headless mode for automated audio rendering
+piano elise --headless true
+
+# Play a custom song file
+piano --file ./my_composition.json
+```
+
+---
+
+## 💻 Programmatic API (Node.js)
+
+You can also use Virtual Piano Player directly within your own Node.js scripts:
+
+```javascript
+const { play, listSongs, NOTE_MAP, noteToMidi } = require('virtual-piano-player');
+
+// Display catalog
+listSongs();
+
+// Play a song programmatically
+await play();
+```
+
+---
+
+## 📦 Local Development & Verification
+
+To contribute or test changes locally:
+
+```bash
+# Clone the repository
+git clone https://github.com/AxmadjonTeacher/virtual-piano.git
+cd virtual-piano
+
+# Install dependencies
+npm install
+
+# Symlink package binary locally
+npm link
+
+# Test CLI commands globally
+piano --list
+piano elise --headless true
+
+# Unlink when finished
+npm unlink -g virtual-piano-player
+```
+
+---
+
+## 📄 License
+
+Distributed under the [MIT License](LICENSE). Copyright (c) 2026 **AxmadjonTeacher**.

package/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: virtual-piano-player
+description: Controls the browser to navigate to OnlinePianist (https://www.onlinepianist.com/virtual-piano), configure the 88-key piano interface (set visible keys to Max), and play classical, pop, jazz, or custom piano solos, melodies, and chords using automated keyboard simulation and Web Audio.
+---
+
+# Virtual Piano Player Skill
+
+This skill automates the **[OnlinePianist Virtual Piano](https://www.onlinepianist.com/virtual-piano)** in the browser. It configures the keyboard to the full **88 visible keys**, activates the sustain pedal, and plays classical piano solos, chords, or custom compositions with expressive timing and visual glow effects on each key.
+
+---
+
+## When to Activate This Skill
+
+Activate this skill whenever the user:
+- Asks to play, compose, or perform a song, melody, or solo on the OnlinePianist virtual piano (`https://www.onlinepianist.com/virtual-piano`).
+- Mentions playing piano in the browser, controlling keyboard keys, or playing in the style of composers like Chopin, Beethoven, Mozart, Bach, Debussy, or modern artists.
+- Requests setting visible keys to max / full 88-key piano view and performing music.
+
+---
+
+## Directory Structure
+
+```text
+virtual-piano-player/
+├── SKILL.md                          # Main skill instructions and documentation
+├── package.json                      # Node dependencies (puppeteer-core)
+└── scripts/
+    ├── play.js                       # Master CLI runner for browser automation & playback
+    └── songs/
+        ├── chopin_nocturne.json      # Chopin's Nocturne Op. 9 No. 2 (Csabay Domonkos perf. ~248s)
+        ├── chopin_etude.json         # 60s Fast Chopin Impromptu-Etude in C# minor
+        ├── vivaldi_winter.json       # Vivaldi's Winter (L'Inverno - Allegro non molto)
+        ├── paint_it_black.json       # The Rolling Stones' Paint It, Black
+        ├── still_dre.json            # Dr. Dre & Snoop Dogg's Still D.R.E.
+        ├── succession.json           # Nicholas Britell's Succession (Main Title Theme)
+        ├── amelie.json               # Yann Tiersen's Comptine d'un autre été (Amélie)
+        └── fur_elise.json            # Beethoven's Für Elise theme
+```
+
+---
+
+## Quick Usage
+
+### View Available Songs Catalog:
+Run any of the following to see the catalog table with all titles, composers, durations, and keys:
+```bash
+piano                        # From anywhere (via zsh function)
+songs                        # Global alias
+./scripts/list.sh            # When inside virtual-piano-player directory
+node scripts/play.js --list  # Direct Node CLI
+```
+
+### Play Songs via Shell Shortcuts:
+```bash
+# Play with master "piano" command:
+piano nocturne               # Chopin - Nocturnes, Op. 9: No. 2 (Domonkos Csabay)
+piano amelie                 # Yann Tiersen - Comptine d'un autre été (Amélie)
+piano succession             # Nicholas Britell - Succession Main Title Theme
+piano still                  # Dr. Dre & Snoop Dogg - Still D.R.E.
+piano paint                  # The Rolling Stones - Paint It, Black
+piano winter                 # Vivaldi - Winter (L'Inverno)
+piano chopin                 # Chopin - Fast Impromptu-Etude
+piano elise                  # Beethoven - Für Elise
+
+# Or play with direct shortcut aliases:
+play-nocturne
+play-amelie
+play-succession
+play-still
+play-paint
+play-winter
+play-chopin
+play-elise
+
+# Play at custom tempo (e.g. 1.2x speed):
+piano chopin --tempo 1.2
+
+# Play a custom song JSON file:
+piano --file /path/to/my_song.json
+```
+
+---
+
+## 88-Key Keyboard Mapping Reference
+
+OnlinePianist maps 5 full octaves (C2 through C7) directly to standard computer keyboard characters in the **Full** layout:
+
+| Octave | Note | Keyboard Key | Shift? | Octave | Note | Keyboard Key | Shift? |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| **2** | C2 | `1` | No | **4** | G#4 / Ab4 | `O` | **Shift+O** |
+| **2** | C#2 / Db2 | `!` | **Shift+1** | **4** | A4 | `p` | No |
+| **2** | D2 | `2` | No | **4** | A#4 / Bb4 | `P` | **Shift+P** |
+| **2** | D#2 / Eb2 | `@` | **Shift+2** | **4** | B4 | `a` | No |
+| **2** | E2 | `3` | No | **5** | C5 | `s` | No |
+| **2** | F2 | `4` | No | **5** | C#5 / Db5 | `S` | **Shift+S** |
+| **2** | F#2 / Gb2 | `$` | **Shift+4** | **5** | D5 | `d` | No |
+| **2** | G2 | `5` | No | **5** | D#5 / Eb5 | `D` | **Shift+D** |
+| **2** | G#2 / Ab2 | `%` | **Shift+5** | **5** | E5 | `f` | No |
+| **2** | A2 | `6` | No | **5** | F5 | `g` | No |
+| **2** | A#2 / Bb2 | `^` | **Shift+6** | **5** | F#5 / Gb5 | `G` | **Shift+G** |
+| **2** | B2 | `7` | No | **5** | G5 | `h` | No |
+| **3** | C3 | `8` | No | **5** | G#5 / Ab5 | `H` | **Shift+H** |
+| **3** | C#3 / Db3 | `*` | **Shift+8** | **5** | A5 | `j` | No |
+| **3** | D3 | `9` | No | **5** | A#5 / Bb5 | `J` | **Shift+J** |
+| **3** | D#3 / Eb3 | `(` | **Shift+9** | **5** | B5 | `k` | No |
+| **3** | E3 | `0` | No | **6** | C6 | `l` | No |
+| **3** | F3 | `q` | No | **6** | C#6 / Db6 | `L` | **Shift+L** |
+| **3** | F#3 / Gb3 | `Q` | **Shift+Q** | **6** | D6 | `z` | No |
+| **3** | G3 | `w` | No | **6** | D#6 / Eb6 | `Z` | **Shift+Z** |
+| **3** | G#3 / Ab3 | `W` | **Shift+W** | **6** | E6 | `x` | No |
+| **3** | A3 | `e` | No | **6** | F6 | `c` | No |
+| **3** | A#3 / Bb3 | `E` | **Shift+E** | **6** | F#6 / Gb6 | `C` | **Shift+C** |
+| **3** | B3 | `r` | No | **6** | G6 | `v` | No |
+| **4** | C4 (Middle C) | `t` | No | **6** | G#6 / Ab6 | `V` | **Shift+V** |
+| **4** | C#4 / Db4 | `T` | **Shift+T** | **6** | A6 | `b` | No |
+| **4** | D4 | `y` | No | **6** | A#6 / Bb6 | `B` | **Shift+B** |
+| **4** | D#4 / Eb4 | `Y` | **Shift+Y** | **6** | B6 | `n` | No |
+| **4** | E4 | `u` | No | **7** | C7 | `m` | No |
+| **4** | F4 | `i` | No | | | | |
+| **4** | F#4 / Gb4 | `I` | **Shift+I** | | | | |
+| **4** | G4 | `o` | No | | | | |
+
+---
+
+## How to Compose New Songs
+
+Songs are JSON objects with an array of sequential `events`. Each event contains:
+- `keys`: An array of note strings (e.g. `["C4"]` or `["C4", "E4", "G4"]` for a chord), or direct key letters (e.g. `["t", "u", "o"]`).
+- `dur`: Note hold duration in milliseconds (e.g. `80` for staccato / 16th-note, `400` for quarter note).
+- `wait`: Pause before the next event in milliseconds (e.g. `20` for continuous legato, `200` for rests).
+
+### Example Song JSON
+
+```json
+{
+  "title": "Moonlight Sonata (Opening Theme)",
+  "composer": "Ludwig van Beethoven",
+  "key": "C# minor",
+  "events": [
+    { "keys": ["Cs2", "Cs3"], "dur": 600, "wait": 100 },
+    { "keys": ["Gs3"], "dur": 180, "wait": 40 },
+    { "keys": ["Cs4"], "dur": 180, "wait": 40 },
+    { "keys": ["E4"], "dur": 180, "wait": 40 },
+    { "keys": ["Gs3"], "dur": 180, "wait": 40 },
+    { "keys": ["Cs4"], "dur": 180, "wait": 40 },
+    { "keys": ["E4"], "dur": 180, "wait": 40 }
+  ]
+}
+```
+
+---
+
+## Procedural Automation Checklist
+
+When automating OnlinePianist:
+1. **Launch Google Chrome**: Use `puppeteer-core` pointing to `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`.
+2. **Bring Window to Front**: Execute `osascript -e 'tell application "Google Chrome" to activate'` so visual animations and audio playback are front and center.
+3. **Wait for Sound Engine**: Poll until `!document.body.innerText.includes('WARMING UP PIANO')` so Web Audio fonts are fully initialized before playing.
+4. **Remove Ad Overlays**: Remove `#layoutDesign` and `.vp-btf-container` from the DOM to avoid pointer interception.
+5. **Set Visible Keys to Max**:
+   - Click `.synth-btn--settings`.
+   - Find the button with text `Max` under `VISIBLE KEYS` and click it.
+   - Close the settings menu by clicking `.synth-btn--settings` again.
+6. **Verify 88 Keys**: Ensure `document.querySelectorAll('.piano-key-white, .piano-key-black').length === 88`.
+7. **Ensure Sustain Pedal**: Verify `.synth-btn--sustain` has class `synth-btn--on`.
+8. **Native Audio Bridge**: Connects directly to OnlinePianist's Web Audio synthesis engine (`te.playNote(midi)`), eliminating OS keyboard modifier drops and ensuring 100% pitch fidelity for all black and white keys with simultaneous visual key glow.
+9. **Dual Playback Formats**:
+   - `notes`: High-precision client-side timeline arrays with exact millisecond timestamps (`startMs`, `durMs`, `midi`), ideal for official transcribed multi-track scores.
+   - `events`: Sequential step-by-step note events (`keys`, `dur`, `wait`), ideal for custom solos and arrangements.

package/bin/cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+/**
+ * Virtual Piano CLI
+ * Entry point for global binary execution (piano, virtual-piano) and npx runner.
+ */
+
+const { main } = require('../scripts/play.js');
+
+main().catch((err) => {
+  console.error('Fatal execution error:', err);
+  process.exit(1);
+});

package/index.js

@@ -0,0 +1,14 @@
+/**
+ * Virtual Piano Player Programmatic Module
+ * Exports core audio mapping, catalog metadata, and playback engine.
+ */
+
+const { NOTE_MAP, noteToMidi, loadSong, listSongs, main } = require('./scripts/play.js');
+
+module.exports = {
+  NOTE_MAP,
+  noteToMidi,
+  loadSong,
+  listSongs,
+  play: main
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "virtual-piano-player",
+  "version": "1.0.0",
+  "description": "Autonomous browser-controlled virtual piano player with 88 visible keys, sustain pedal, and studio-grade Web Audio synthesis.",
+  "main": "index.js",
+  "bin": {
+    "piano": "bin/cli.js",
+    "virtual-piano": "bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js",
+    "list": "node bin/cli.js --list",
+    "songs": "node bin/cli.js --list",
+    "test": "node bin/cli.js --list"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AxmadjonTeacher/virtual-piano.git"
+  },
+  "keywords": [
+    "piano",
+    "virtual-piano",
+    "music",
+    "audio",
+    "midi",
+    "onlinepianist",
+    "puppeteer",
+    "antigravity-skill"
+  ],
+  "author": "AxmadjonTeacher",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/AxmadjonTeacher/virtual-piano/issues"
+  },
+  "homepage": "https://github.com/AxmadjonTeacher/virtual-piano#readme",
+  "type": "commonjs",
+  "files": [
+    "bin",
+    "scripts",
+    "index.js",
+    "SKILL.md",
+    "skill.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "puppeteer-core": "^25.11.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/scripts/list.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+node "$SCRIPT_DIR/play.js" --list