{
  "schemaVersion": 1,
  "id": "music-box",
  "version": "1.0.0",
  "status": "published",
  "kind": "object",
  "title": "Music Box",
  "summary": "The bare movement of a music box: a pinned brass barrel plucks a steel comb, tooth by tooth, as the gears turn. Loops perfectly.",
  "description": "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.",
  "role": "Hero object (Three.js 3D): a mechanical, nostalgic movement for music, memory and craft content.",
  "collections": [
    "satisfying",
    "hypnotic-loops",
    "chrome-glass"
  ],
  "tags": [
    "music box",
    "mechanism",
    "comb",
    "barrel",
    "gears",
    "brass",
    "lullaby",
    "nostalgia",
    "music",
    "clockwork",
    "loop",
    "3d"
  ],
  "synonyms": [
    "music box mechanism",
    "music box comb",
    "pinned cylinder",
    "clockwork music",
    "mechanical music",
    "lullaby box",
    "tinkling music box",
    "cylinder music box"
  ],
  "useCases": [
    "A nostalgic, tender or whimsical backdrop for music, memory and children's content",
    "A craft and engineering moment: how a music box makes its tune",
    "A visual to sync with a real music-box recording: the teeth move as the notes sound"
  ],
  "featured": null,
  "publishedAt": "2026-10-06",
  "implementation": {
    "target": "three",
    "runtime": "browser",
    "language": "javascript",
    "module": "esm",
    "entry": "src/music-box.js",
    "exports": [
      {
        "name": "createMusicBox",
        "signature": "createMusicBox({ tune?, finish?, turns?, exaggerate?, seed?, anisotropy? }) => { group, teeth, axisY, notes, steps, update(time, loopSeconds), dispose() }",
        "description": "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."
      },
      {
        "name": "TUNES",
        "signature": "TUNES: { lullaby, waltz, chimes }",
        "description": "The pin patterns: a number of steps round the barrel and the (step, tooth) of each pin."
      },
      {
        "name": "FINISHES",
        "signature": "FINISHES: { brass, gold, copper, silver }",
        "description": "Finishes for the barrel, plates and gears."
      }
    ],
    "reusable": [
      "src/music-box.js"
    ],
    "demo": "demo.js",
    "harness": "index.html"
  },
  "dependencies": [
    {
      "id": "three",
      "version": "0.185.1",
      "reason": "Renderer, geometry and physical metals."
    },
    {
      "id": "chrome-material",
      "version": "1.1.0",
      "scope": "demo",
      "reason": "Studio environment light, backdrop, floor and contact shadow."
    },
    {
      "id": "apw-runtime",
      "version": "1.0.0",
      "scope": "demo",
      "reason": "Demo harness."
    }
  ],
  "params": [
    {
      "key": "tune",
      "label": "Tune",
      "type": "select",
      "default": "lullaby",
      "options": [
        {
          "value": "lullaby",
          "label": "Lullaby"
        },
        {
          "value": "waltz",
          "label": "Waltz"
        },
        {
          "value": "chimes",
          "label": "Rising chimes"
        }
      ]
    },
    {
      "key": "finish",
      "label": "Metal",
      "type": "select",
      "default": "brass",
      "options": [
        {
          "value": "brass",
          "label": "Brass"
        },
        {
          "value": "gold",
          "label": "Gold"
        },
        {
          "value": "copper",
          "label": "Copper"
        },
        {
          "value": "silver",
          "label": "Silver"
        }
      ]
    },
    {
      "key": "turns",
      "label": "Plays per loop",
      "help": "Whole turns of the barrel in each loop.",
      "type": "integer",
      "min": 1,
      "max": 3,
      "step": 1,
      "default": 1
    },
    {
      "key": "swing",
      "label": "How far the teeth swing",
      "type": "number",
      "min": 0,
      "max": 1.6,
      "step": 0.1,
      "default": 1
    },
    {
      "key": "background",
      "label": "Room",
      "type": "color",
      "default": "#15110f"
    },
    {
      "key": "seed",
      "label": "Seed",
      "help": "Changes the wood grain.",
      "type": "integer",
      "min": 1,
      "max": 999,
      "step": 1,
      "default": 3
    }
  ],
  "presets": [
    {
      "id": "default",
      "label": "Lullaby, brass",
      "params": {}
    },
    {
      "id": "waltz",
      "label": "Waltz, gold",
      "params": {
        "tune": "waltz",
        "finish": "gold",
        "turns": 2,
        "background": "#120f14"
      }
    },
    {
      "id": "chimes",
      "label": "Chimes, silver",
      "params": {
        "tune": "chimes",
        "finish": "silver",
        "swing": 1.3,
        "background": "#0f131a",
        "seed": 6
      }
    },
    {
      "id": "copper",
      "label": "Lullaby, copper, slow",
      "params": {
        "finish": "copper",
        "swing": 0.7,
        "background": "#1a1210",
        "seed": 11
      }
    }
  ],
  "output": {
    "width": 1080,
    "height": 1080,
    "fps": 30,
    "durationSeconds": 12,
    "posterSeconds": 4,
    "alpha": false,
    "motion": "procedural",
    "loop": {
      "seamless": true,
      "cycleSeconds": 12,
      "method": "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."
    },
    "seed": {
      "param": "seed",
      "behavior": "Seed changes the wood grain of the base."
    }
  },
  "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.",
    "compatibleWith": [
      "chrome-material",
      "orbit-camera",
      "kinetic-title"
    ],
    "notes": [
      "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."
    ]
  },
  "reuse": [
    "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."
  ],
  "integration": {
    "newProject": "Set scene.environment (createStudioEnvironment from Chrome Material works), add createMusicBox().group and a shadow-casting light, and call update(time, loopSeconds) each frame.",
    "existingProject": "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."
  },
  "performance": {
    "notes": "About two hundred meshes built once and one instanced set of pins; only the barrel, the teeth, the gears and the key are reposed each frame. Smooth at 1080p on laptop GPUs.",
    "limits": "Software WebGL (no GPU) renders slowly."
  },
  "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": {
    "spdx": "MIT",
    "notice": "Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.",
    "thirdParty": [
      {
        "name": "three.js",
        "version": "0.185.1",
        "license": "MIT",
        "url": "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.",
  "changelog": [
    {
      "version": "1.0.0",
      "date": "2026-10-05",
      "notes": "Initial release."
    }
  ]
}