virtual-piano-player 1.0.0 → 1.0.1

package/README.md

@@ -67,6 +67,16 @@ npm install
 | :--- | :--- | :--- | :--- | :--- | :--- |
 | `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 |
+| `golden` | `play-golden` | Golden Hour | JVKE | E major | ~207s |
+| `idea10` | `play-idea10` | Idea 10 | Gibran Alcocer | G minor | ~121s |
+| `solas` | `play-solas` | Solas | Jamie Duffy | E minor | ~122s |
+| `blue` | `play-blue` | Blue | Yung Kai | E major | ~105s |
+| `lovestory` | `play-lovestory` | Love Story | Indila | Bb minor | ~253s |
+| `luna` | `play-luna` | Hijo de la Luna | Mecano (José María Cano) | A minor | ~268s |
+| `baby` | `play-baby` | Pretty Little Baby | Connie Francis | Db major | ~94s |
+| `hotline` | `play-hotline` | Hotline (Edit) | Billie Eilish | A minor | ~94s |
+| `face` | `play-face` | I Thought I Saw Your Face Today | She & Him (Zooey Deschanel) | G major | ~86s |
+| `moment` | `play-moment` | Every Living Breathing Moment | Grant Steller | F major | ~101s |
 | `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 |

package/SKILL.md

@@ -1,11 +1,11 @@
 ---
 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.
+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 studio-grade Web Audio synthesis.
 ---
 
-# Virtual Piano Player Skill
+# Virtual Piano Player Skill & CLI
 
-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.
+This skill and standalone CLI automates the **[OnlinePianist Virtual Piano](https://www.onlinepianist.com/virtual-piano)** in Google Chrome. It automatically expands the keyboard to the full **88 visible keys**, activates the sustain pedal, connects directly into the browser's Web Audio synthesis engine (**Studio Direct** audio bridge), and performs classical piano solos, chords, or custom compositions with expressive timing and visual glow effects on each key.
 
 ---
 
@@ -13,46 +13,94 @@ This skill automates the **[OnlinePianist Virtual Piano](https://www.onlinepiani
 
 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.
+- Mentions playing piano in the browser, controlling keyboard keys, or playing works by composers like Chopin, Yann Tiersen, Beethoven, Vivaldi, Nicholas Britell, or Dr. Dre.
 - Requests setting visible keys to max / full 88-key piano view and performing music.
+- Asks to manage, list, add, or publish songs to the virtual piano package or repository.
 
 ---
 
-## Directory Structure
+## Project & 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
+├── bin/
+│   └── cli.js                    # Executable CLI binary (piano, virtual-piano, npx runner)
+├── scripts/
+│   ├── play.js                   # Master playback engine, audio bridge & lock manager
+│   ├── list.sh                   # In-directory bash catalog runner
+│   └── songs/                    # Curated library of high-precision song JSONs
+│       ├── golden_hour.json      # JVKE's Golden Hour (unabridged cascading piano ~207s)
+│       ├── idea_10.json          # Gibran Alcocer's Idea 10 (3/4 waltz arpeggios ~121s)
+│       ├── solas.json            # Jamie Duffy's Solas (emotive Celtic piano solo ~122s)
+│       ├── blue.json             # Yung Kai's Blue (tender ballad ~105s)
+│       ├── love_story.json       # Indila's Love Story (Bb minor harp & piano ~253s)
+│       ├── hijo_de_la_luna.json  # Mecano's Hijo de la Luna (expressive A minor ~268s)
+│       ├── pretty_little_baby.json # Connie Francis' Pretty Little Baby (1962 pop swing ~94s)
+│       ├── hotline.json          # Billie Eilish's Hotline Edit (haunting ballad ~94s)
+│       ├── i_thought_i_saw_your_face_today.json # She & Him's 60s folk swing ~86s
+│       ├── every_living_breathing_moment.json # Grant Steller's cinematic theme ~101s
+│       ├── 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
+├── index.js                      # Programmatic Node.js exports (play, listSongs, loadSong)
+├── package.json                  # NPM manifest with bin mappings, files whitelist & dependencies
+├── package-lock.json             # Exact dependency lockfile (puppeteer-core)
+├── SKILL.md                      # Agent skill instructions & key mappings
+├── skill.json                    # Skill metadata for Antigravity & agent discovery
+├── README.md                     # Public documentation, quickstart & catalog table
+├── LICENSE                       # MIT License (AxmadjonTeacher)
+└── .gitignore                    # Ignores node_modules/, scratch/, /tmp profiles, logs
 ```
 
 ---
 
+## 🌐 Public Distribution & Releases
+
+- **NPM Package**: [`virtual-piano-player`](https://www.npmjs.com/package/virtual-piano-player) (v1.0.0 live)
+- **GitHub Repository**: [https://github.com/AxmadjonTeacher/virtual-piano](https://github.com/AxmadjonTeacher/virtual-piano)
+- **Global Binaries**: `piano`, `virtual-piano`
+
+### 📦 Summary of Future Releases
+
+Whenever you add new songs or tweak code, just run:
+
+  cd ~/.agents/skills/virtual-piano-player
+  npm version patch          # Increments 1.0.0 -> 1.0.1 and tags git
+  git push origin main --tags
+  npm publish
+
+---
+
 ## Quick Usage
 
-### View Available Songs Catalog:
-Run any of the following to see the catalog table with all titles, composers, durations, and keys:
+### 1. View Song Catalog:
+Run any of the following to see the interactive catalog table with all titles, composers, durations, and keys:
 ```bash
-piano                        # From anywhere (via zsh function)
-songs                        # Global alias
+piano                        # From anywhere (via zsh function & npm link)
+virtual-piano                # Direct npm binary
+songs                        # Shell shortcut
 ./scripts/list.sh            # When inside virtual-piano-player directory
 node scripts/play.js --list  # Direct Node CLI
 ```
 
-### Play Songs via Shell Shortcuts:
+### 2. Play Songs via Shell Shortcuts:
 ```bash
-# Play with master "piano" command:
+# Play with master "piano" or "virtual-piano" command:
+piano golden                 # JVKE - Golden Hour (unabridged cascading piano)
+piano idea10                 # Gibran Alcocer - Idea 10 (3/4 waltz arpeggios)
+piano solas                  # Jamie Duffy - Solas (emotive Celtic piano solo)
+piano blue                   # Yung Kai - Blue (tender ballad)
+piano lovestory              # Indila - Love Story (Bb minor harp & piano)
+piano luna                   # Mecano - Hijo de la Luna (expressive A minor)
+piano baby                   # Connie Francis - Pretty Little Baby (1962 pop swing)
+piano hotline                # Billie Eilish - Hotline Edit (haunting ballad)
+piano face                   # She & Him - I Thought I Saw Your Face Today
+piano moment                 # Grant Steller - Every Living Breathing Moment
 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
@@ -63,6 +111,16 @@ piano chopin                 # Chopin - Fast Impromptu-Etude
 piano elise                  # Beethoven - Für Elise
 
 # Or play with direct shortcut aliases:
+play-golden
+play-idea10
+play-solas
+play-blue
+play-lovestory
+play-luna
+play-baby
+play-hotline
+play-face
+play-moment
 play-nocturne
 play-amelie
 play-succession
@@ -72,13 +130,49 @@ play-winter
 play-chopin
 play-elise
 
-# Play at custom tempo (e.g. 1.2x speed):
-piano chopin --tempo 1.2
+# Play at custom tempo (e.g. 1.15x speed):
+piano golden --tempo 1.15
+
+# Play headlessly (for audio testing/CI):
+piano elise --headless true
 
 # Play a custom song JSON file:
 piano --file /path/to/my_song.json
 ```
 
+### 3. Instant Zero-Install Execution (NPX):
+```bash
+npx virtual-piano-player golden
+npx virtual-piano-player solas
+npx virtual-piano-player idea10
+npx virtual-piano-player amelie
+```
+
+---
+
+## 🎵 Song Catalog Reference
+
+| Alias | Shortcut | Title | Composer / Artist | Key | Duration | Notes |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| `amelie` | `play-amelie` | Amélie (Comptine d'un autre été) | Yann Tiersen | E minor | ~122s | 945 notes, client timeline |
+| `nocturne` | `play-nocturne` | Nocturne Op. 9 No. 2 (Andante) | Frédéric Chopin (Csabay Domonkos) | Eb major | ~248s | 1,242 notes, full unabridged |
+| `golden` | `play-golden` | Golden Hour | JVKE | E major | ~207s | 2,716 notes, sparkling arpeggios |
+| `idea10` | `play-idea10` | Idea 10 | Gibran Alcocer | G minor | ~121s | 1,076 notes, 3/4 waltz arpeggios |
+| `solas` | `play-solas` | Solas | Jamie Duffy | E minor | ~122s | 808 notes, emotive Celtic piano |
+| `blue` | `play-blue` | Blue | Yung Kai | E major | ~105s | 744 notes, warm tender chords |
+| `lovestory` | `play-lovestory` | Love Story | Indila | Bb minor | ~253s | 1,655 notes, concert harp & piano |
+| `luna` | `play-luna` | Hijo de la Luna | Mecano (José María Cano) | A minor | ~268s | 1,636 notes, expressive piano score |
+| `baby` | `play-baby` | Pretty Little Baby | Connie Francis | Db major | ~94s | 754 notes, 1962 pop swing |
+| `hotline` | `play-hotline` | Hotline (Edit) | Billie Eilish | A minor | ~94s | 329 notes, intimate acoustic ballad |
+| `face` | `play-face` | I Thought I Saw Your Face Today | She & Him (Zooey Deschanel) | G major | ~86s | 550 notes, 60s folk pop swing |
+| `moment` | `play-moment` | Every Living Breathing Moment | Grant Steller | F major | ~101s | 431 notes, cinematic film score |
+| `succession` | `play-succession` | Succession (Main Title Theme) | Nicholas Britell | C minor | ~89s | 390 notes, hip-hop/classical |
+| `still` | `play-still` | Still D.R.E. (Polished Master) | Dr. Dre ft. Snoop Dogg | A minor | ~66s | 374 notes, classic 8-beat loop |
+| `paint` | `play-paint` | Paint It, Black | The Rolling Stones (Westworld) | E minor | ~50s | 98 events, driving rock rhythm |
+| `winter` | `play-winter` | Winter (L'Inverno - Allegro) | Antonio Vivaldi | F minor | ~45s | 80 events, rapid violin runs |
+| `chopin` | `play-chopin` | Impromptu-Etude in C# minor | Frédéric Chopin style | C# minor | ~60s | 257 events, tempestuous arpeggios |
+| `elise` | `play-elise` | Für Elise (Bagatelle No. 25) | Ludwig van Beethoven | A minor | ~25s | 53 events, famous theme |
+
 ---
 
 ## 88-Key Keyboard Mapping Reference
@@ -122,48 +216,19 @@ OnlinePianist maps 5 full octaves (C2 through C7) directly to standard computer
 
 ---
 
-## 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.
+## Technical Architecture & Automation Checklist
+
+1. **Launch Google Chrome**: Uses `puppeteer-core` pointing to `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome` with `--start-maximized` and `--autoplay-policy=no-user-gesture-required`.
+2. **Pre-flight Lock Cleanup & Auto-Recovery**: Prior to launching, `play.js` terminates orphaned `chrome-piano-profile` processes (`pkill -9 -f "chrome-piano-profile"`) and removes stale `/tmp/chrome-piano-profile/Singleton*` lock symlinks, preventing browser startup errors.
+3. **Signal Trapping**: Intercepts `SIGINT` (Ctrl+C) and `SIGTERM` to close browser windows cleanly and release profile locks.
+4. **Bring Window to Front**: Executes `osascript -e 'tell application "Google Chrome" to activate'` so visual animations and audio playback are front and center.
+5. **Sound Engine Synchronization**: Polls until `!document.body.innerText.includes('WARMING UP PIANO')` so Web Audio samples are loaded before notes trigger.
+6. **Set Visible Keys to Max**:
+   - Clicks `.synth-btn--settings`.
+   - Clicks `Full` layout and `Max` visible keys (88 keys).
+   - Verifies 88 keys exist in DOM (`document.querySelectorAll('.piano-key-white, .piano-key-black').length === 88`).
+7. **Ensure Sustain Pedal**: Confirms `.synth-btn--sustain` has class `synth-btn--on`.
+8. **Studio Direct Audio Bridge**: Connects directly into OnlinePianist's Web Audio synthesis engine (`window.__playMidi`, `window.__releaseMidi`), bypassing 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.
+   - `notes`: High-precision client-side timeline arrays with exact millisecond timestamps (`startMs`, `durMs`, `midi`), used for complex multi-track classical scores (Amélie, Chopin Nocturne, Still D.R.E.).
+   - `events`: Sequential note events (`keys`, `dur`, `wait`), used for classic solo and chord transcriptions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "virtual-piano-player",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Autonomous browser-controlled virtual piano player with 88 visible keys, sustain pedal, and studio-grade Web Audio synthesis.",
   "main": "index.js",
   "bin": {

package/scripts/play.js

@@ -75,6 +75,16 @@ function listSongs() {
   const SONG_ORDER = [
     { file: 'amelie.json', alias: 'amelie', shortcut: 'play-amelie' },
     { file: 'chopin_nocturne.json', alias: 'nocturne', shortcut: 'play-nocturne' },
+    { file: 'golden_hour.json', alias: 'golden', shortcut: 'play-golden' },
+    { file: 'idea_10.json', alias: 'idea10', shortcut: 'play-idea10' },
+    { file: 'solas.json', alias: 'solas', shortcut: 'play-solas' },
+    { file: 'blue.json', alias: 'blue', shortcut: 'play-blue' },
+    { file: 'love_story.json', alias: 'lovestory', shortcut: 'play-lovestory' },
+    { file: 'hijo_de_la_luna.json', alias: 'luna', shortcut: 'play-luna' },
+    { file: 'pretty_little_baby.json', alias: 'baby', shortcut: 'play-baby' },
+    { file: 'hotline.json', alias: 'hotline', shortcut: 'play-hotline' },
+    { file: 'i_thought_i_saw_your_face_today.json', alias: 'face', shortcut: 'play-face' },
+    { file: 'every_living_breathing_moment.json', alias: 'moment', shortcut: 'play-moment' },
     { file: 'succession.json', alias: 'succession', shortcut: 'play-succession' },
     { file: 'still_dre.json', alias: 'still', shortcut: 'play-still' },
     { file: 'paint_it_black.json', alias: 'paint', shortcut: 'play-paint' },
@@ -227,6 +237,26 @@ function loadSong(options) {
       filePath = path.join(songsDir, 'succession.json');
     } else if (s === 'amelie' || s === 'comptine' || s === 'comptine_dun_autre_ete' || s === 'tiersen' || s === 'yann_tiersen') {
       filePath = path.join(songsDir, 'amelie.json');
+    } else if (s === 'golden' || s === 'golden_hour' || s === 'goldenhour' || s === 'jvke' || s === 'jvke_golden_hour') {
+      filePath = path.join(songsDir, 'golden_hour.json');
+    } else if (s === 'idea10' || s === 'idea_10' || s === 'idea' || s === 'gibran' || s === 'alcocer' || s === 'gibran_alcocer') {
+      filePath = path.join(songsDir, 'idea_10.json');
+    } else if (s === 'solas' || s === 'jamie' || s === 'duffy' || s === 'jamie_duffy') {
+      filePath = path.join(songsDir, 'solas.json');
+    } else if (s === 'blue' || s === 'yungkai' || s === 'yung_kai' || s === 'kai') {
+      filePath = path.join(songsDir, 'blue.json');
+    } else if (s === 'baby' || s === 'pretty_little_baby' || s === 'pretty' || s === 'connie' || s === 'francis' || s === 'connie_francis') {
+      filePath = path.join(songsDir, 'pretty_little_baby.json');
+    } else if (s === 'hotline' || s === 'hotline_edit' || s === 'billie' || s === 'eilish' || s === 'billie_eilish' || s === 'hotline_bling') {
+      filePath = path.join(songsDir, 'hotline.json');
+    } else if (s === 'face' || s === 'i_thought_i_saw_your_face_today' || s === 'she_and_him' || s === 'she&him' || s === 'sheandhim' || s === 'deschanel') {
+      filePath = path.join(songsDir, 'i_thought_i_saw_your_face_today.json');
+    } else if (s === 'luna' || s === 'hijo_de_la_luna' || s === 'hijo' || s === 'mecano' || s === 'cano') {
+      filePath = path.join(songsDir, 'hijo_de_la_luna.json');
+    } else if (s === 'lovestory' || s === 'love_story' || s === 'indila' || s === 'love') {
+      filePath = path.join(songsDir, 'love_story.json');
+    } else if (s === 'moment' || s === 'every_living_breathing_moment' || s === 'grant' || s === 'steller' || s === 'grant_steller' || s === 'breathing') {
+      filePath = path.join(songsDir, 'every_living_breathing_moment.json');
     } else {
       filePath = path.join(songsDir, `${s}.json`);
     }