# Music Box — `music-box@1.0.0`

The bare movement of a music box: a pinned brass barrel plucks a steel comb, tooth by tooth, as the gears turn. Loops perfectly.

The heart of a music box laid bare on a walnut base: a brass barrel studded with pins turns slowly, and each pin that comes round lifts the tip of one tooth of a steel comb and lets it go, so the tooth swings and settles (a little exaggerated so the eye can follow it). The pins spell out a tune, repeated every turn. At the end of the barrel a toothed gear spins a pinion and a small fan, and a winding key turns on its own post. Choose the tune (a lullaby, a waltz or rising chimes), the metal of the barrel, plates and gears, how many times the tune plays per loop, and how far the teeth swing.

- Kind: object; status: published; digest sha256:3e8aa3a3373e60e296b9b0a36916e4481b3690a94e1146201a7834e11c9b29b6
- Role: Hero object (Three.js 3D): a mechanical, nostalgic movement for music, memory and craft content.
- Implementation: three; entry `src/music-box.js`
- Files: https://aipixelwizard.com/registry/music-box/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/music-box.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/music-box/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/music-box/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 physical metals.; `chrome-material@1.1.0` (demo) — Studio environment light, backdrop, floor and contact shadow.; `apw-runtime@1.0.0` (demo) — Demo harness.

## Exports
- `createMusicBox({ tune?, finish?, turns?, exaggerate?, seed?, anisotropy? }) => { group, teeth, axisY, notes, steps, update(time, loopSeconds), dispose() }` — The movement as a THREE.Group (1 unit = 10 cm, base on y = 0). update(time, loopSeconds) turns the barrel a whole number of times and swings each tooth when its pin comes round. notes lists every pin (step round the barrel, tooth) so a sound can be synced to it.
- `TUNES: { lullaby, waltz, chimes }` — The pin patterns: a number of steps round the barrel and the (step, tooth) of each pin.
- `FINISHES: { brass, gold, copper, silver }` — Finishes for the barrel, plates and gears.

## Parameters
- `tune` (select one of lullaby | waltz | chimes, default "lullaby") — Tune
- `finish` (select one of brass | gold | copper | silver, default "brass") — Metal
- `turns` (integer 1–3, default 1) — Plays per loop: Whole turns of the barrel in each loop.
- `swing` (number 0–1.6, default 1) — How far the teeth swing
- `background` (color, default "#15110f") — Room
- `seed` (integer 1–999, default 3) — Seed: Changes the wood grain.

## Composition
- Inputs: Time within the loop; the tune, metal, plays per loop and the swing of the teeth.
- Outputs: A THREE.Group: base, bedplate, barrel with pins, comb, gears, fan and key, standing on y = 0.
- Coordinates: 1 unit = 10 cm. The base is 9.2 × 7.4; the barrel (radius 1, length 5.4) lies along x at y = 2.1; the comb of 18 teeth lies in front of it towards +z.
- Lighting: Physical metals: needs scene.environment; a shadow-casting key light draws the teeth's and pins' shadows on the plate.
- Timing: update(time, loopSeconds) is a pure function of time; frames render in any order. The notes list gives the moment of every pluck for syncing sound.
- Works with: chrome-material, orbit-camera, kinetic-title
- A tooth's swing is exaggerated several times over so that it can be followed by eye; set swing to 0.3 for a subtle shimmer.
- The gears' teeth are not phase-matched to each other; they turn in the correct ratios.

## Output and loop
- 1080×1080, 30 fps, 12 s, procedural
- Seamless loop: yes — The barrel makes a whole number of turns per loop and each tooth's swing, started by its pin, is measured from the pluck with wrap-around, so the tune and the teeth repeat exactly; the gears turn whole multiples of the barrel and the key turns a whole number of times.
- 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: Set scene.environment (createStudioEnvironment from Chrome Material works), add createMusicBox().group and a shadow-casting light, and call update(time, loopSeconds) each frame.

Existing project: Copy src/music-box.js. Add the group to your scene, scale it, and call update(seconds, loopSeconds) every frame; use the notes array to sync sound.

Reuse ideas:
- Lullaby video: Lullaby, brass, with a soft title and a real recording of a music box.
- Craft explainer: Waltz, gold, camera drift on.
- Nostalgic scene: Lullaby, copper, slow, behind a photograph montage.

## Limitations
- The teeth swing as rigid levers rather than bending, and their frequencies are scaled for the eye, not for the ear.
- No sound is produced: the tune is only in the pins.

## License
MIT. Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.
- three.js 0.185.1: MIT (https://github.com/mrdoob/three.js)

Provenance: Adapted from the owner's threejs-sketches/objects-scenes/music-box-dancer (MIT), rebuilt for AI Pixel Wizard in October 2026 as the bare movement of a music box: a pinned barrel, a stepped steel comb whose teeth are plucked in time with the pins, a gear train with a fan, a winding key, a walnut base, studio light and shadows, an exact loop and the frame/time contract.