# Piano Keys — `piano-keys@1.0.0`

A two-octave piano playing a repeating tune: keys press down and glowing notes and colour rings rise from them. Loops perfectly.

A keyboard playing itself. A two-octave piano of ivory and ebony keys plays a little tune that repeats every loop: each note presses its key down on its hinge, and as it sounds a glowing note rises from the key on a lazy sway, followed by rings of colour that spread as they climb and fade, hue by pitch. Choose the tune (arpeggio, scale or chords), the colours of the rising sound (rainbow, aurora, ember or mono), how high the sound climbs, the finish of the piano (ivory, rose or midnight), the backdrop colour and whether the camera sways.

- Kind: object; status: published; digest sha256:c69fb8a50445390ac2c447fbe99c61026fcfe786792301e79f312b81b7ef1a07
- Role: Object (3D, three.js): a musical showpiece that plays itself, for music, learning and creative content.
- Implementation: three; entry `src/piano-keys.js`
- Files: https://aipixelwizard.com/registry/piano-keys/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/piano-keys.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/piano-keys/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/piano-keys/1.0.0/index.html (open over http; it imports sibling packages by relative path)
- Dependencies (exact): `three@0.185.1` (source) — Renderer, geometry and shader materials.; `chrome-material@1.1.0` (demo) — Studio environment light, backdrop and contact shadow.; `apw-runtime@1.0.0` (demo) — Demo harness.

## Exports
- `createPiano({ tune?, palette?, rise?, body? }) => { group, setProgress(progress), dispose() }` — The keyboard with its casing and rising notes and rings, about 14 wide, resting on y = 0; needs an environment map.
- `TUNES: { arpeggio, scale, chords }` — Lists of [step, white key] notes on 32 steps per loop.
- `PALETTES: { rainbow, aurora, ember, mono }` — Colours of the rising sound by pitch.

## Parameters
- `tune` (select one of arpeggio | scale | chords, default "arpeggio") — Tune
- `palette` (select one of rainbow | aurora | ember | mono, default "rainbow") — Sound colours
- `rise` (number 0.5–1.6, default 1) — Rise
- `body` (select one of ivory | rose | midnight, default "ivory") — Piano
- `background` (color, default "#11131c") — Backdrop
- `orbit` (boolean, default true) — Camera sway

## Composition
- Inputs: Time within the loop; the tune, sound colours, rise, piano finish, backdrop and camera sway.
- Outputs: A full frame rendered in 3D with a studio environment.
- Coordinates: Fourteen white keys 1 wide and 5 long run along x from −6.5 to 6.5, hinged at z = −2.5; the casing stands behind them; sound rises from y ≈ 1 to y ≈ 8.
- Lighting: A warm key light with a shadow map, a shadow-catching floor and the studio environment; the rising sound is self-lit and additive.
- Timing: setProgress(progress) presses each struck key and places each note and ring; frames render in any order.
- Works with: chrome-material, orbit-camera, kinetic-title, number-reveal
- Black keys are present but not struck by the built-in tunes.

## Output and loop
- 1080×1080, 30 fps, 16 s, procedural
- Seamless loop: yes — The tune is a fixed list of notes on 32 steps per loop; each key's press and each rising note and ring is a function of the time since its note was struck, wrapping round the loop, and the camera sway is a sine of the loop, so the last frame meets the first.
- Verified 2026-10-06 in Chrome 154.0.8037.97 headless on Linux 7.0.0-38-generic (x64), Node 22.14.0 (WebGL 2 via SwiftShader (software)); deterministic: yes; loop check: Frame 0 vs end state (progress 1): mean |Δ| 0.0000, max |Δ| 0 of 255.

## Use it
New project: Create a WebGLRenderer with a studio environment and a shadow-casting light, add createPiano().group and call piano.setProgress(progress) each frame; export TUNES to write your own.

Existing project: Copy src/piano-keys.js; add the group to your scene with an environment map.

Reuse ideas:
- Music lesson: Arpeggio, rainbow.
- Calm: Chords, aurora.
- Warm: Scale, ember.

## Limitations
- There is no audio: the notes are visual only.
- The built-in tunes strike white keys only.

## License
MIT. Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.

Provenance: Adapted from the owner's threejs-sketches/objects-scenes/piano-keys (MIT) and rebuilt for AI Pixel Wizard in October 2026 as an original studio object: a hinged two-octave keyboard playing a fixed note list with glowing notes and expanding rings by the time since each strike, on an exact loop.