# Speaking Piano

A browser piano that turns agent replies into fixed-pitch piano key strikes through WebMCP. Speech synthesis runs locally as an unplayed analysis intermediate; the speakers play piano samples only.

## Run locally

Serve this directory with a static HTTP server, for example:

```sh
python -m http.server 8000
```

Open `http://localhost:8000`, select **Enable piano**, then click keys or use a WebMCP-compatible agent. No build, account, API key, microphone, or external speech service is required.

## Agent tools

- `piano_play`: play melodies and chords directly, without speech synthesis. Supply `notes` with `pitch` (such as `C4`, `F#4`, `Bb3`, or MIDI 21–108), `start` and `duration` in beats, and optional `velocity` (1–127). Notes at the same start form chords. Set `bpm` (30–300, default 120), an optional `title`, `request_id`, and `interrupt`. Maximum 512 notes and 120 seconds. Repeated pitches need a 27.5 ms release gap and at least 50 ms between attacks.
- `piano_speak`: queue up to 500 characters of English text. Use a unique `request_id` to prevent duplicate messages. Set `interrupt: true` to cancel earlier replies.
- `piano_get_status`: inspect readiness, queue state, and playback results.
- `piano_stop`: stop playback and clear queued replies.
- `piano_configure`: change rate, key density, mapping, volume, speech pace, and captions.

For quick exchanges, send a reply and return when it is accepted. Check completion when needed. A queue receipt does not mean playback has finished, and completed playback does not establish intelligibility.

## Source layout

- `agent-piano.js`: audio loading, local synthesis, queue, playback, and controls.
- `solenoid-engine.js`: spectral mapping, strike timing validation, and MIDI encoding.
- `piano3d.js`: piano scene, actuator animation, and key interaction.
- `webmcp.js`: page-scoped tool registration.
- `assets/`: 88 piano note samples.
- `solenoid/dictionary.json`: piano spectral dictionary for compensated mapping.
- `vendor/`: bundled rendering and speech dependencies with licenses and upstream speech source.

Settings are saved in this browser's local storage. Reply text and recent jobs remain in memory for the page session. Third-party reference links are listed in `CREDITS.md`.

## Limitations

Speech intelligibility is experimental. The simulated action is not calibrated to physical hardware. Rates above 20 strikes per key per second are software experiments. At high rates, audio is rendered ahead and the display cannot show every motion. Backgrounding the page stops playback.

## License

Application JavaScript: GPL-3.0-or-later. Bundled dependencies and samples retain their own licenses. See `LICENSE.txt` and `CREDITS.md`.