🎠Monster Puppet Theater
An interactive gothic music box inside an antique miniature puppet theater.
Inspiration
What if Halloween monsters weren't just scary decorations, but members of an eccentric miniature orchestra? We wanted to build something immediately tactile, charming, and musically satisfying—moving away from generic AI sound generators toward a hands-on, toy-like experience reminiscent of an antique puppet theater and a faded picture book.
Instead of treating the Halloween theme as a superficial costume, we wanted the physical crafting of each puppet (carving a pumpkin, assembling skeletal bones, brewing a bubbling cauldron, dressing a cozy ghost) to directly shape the underlying mathematical synthesis of sound and groove.
What it does
Monster Puppet Theater is a zero-dependency, serverless interactive music toy featuring four monster puppets performing in a handcrafted wooden theater:
- 🎃 Jack-o'-Lantern (Lead Synth): Carving eyes, nose, and mouth alters the synth waveforms, rhythmic patterns, and articulation. It sings by opening and closing its mouth as its inner candle glows!
- 💀 Skeleton (Drums & Bone Marimba): Swapping the skull, ribs, and mallets changes percussion sounds and rhythmic grooves. It uses both arms to physically strike its own ribcage to play arpeggiated gothic chords!
- 🧪 Witch's Cauldron (Acid Bubble Bass): Mixing eerie ingredients and changing pots and flames creates rich, bubbling resonant bass lines, with magical bubbles bursting on every note.
- 👻 Ghost (Theremin Choir Pad): Wearing nightcaps or paper crowns, this ghost stretches and squashes while harmonizing haunting, detuned choir pads. If muted, it falls asleep with cozy "Zzz" bubbles.
🎪 Puppet Theater Mechanics & Surprises
- Curtain Call & Bow: Pressing "Play" draws the velvet curtains and lights the footlight candles. Pressing "Stop" triggers an adorable bow—where the Skeleton's skull accidentally rolls onto the stage with a clattering marimba sound effect before being hurriedly picked back up!
- Direct Poke on Stage: While the curtains are open, clicking or tapping any puppet directly triggers an individual note and animation. Even a muted puppet briefly wakes up, plays a note, and falls back asleep!
- Exporting the Magic: Generates a downloadable vintage Showbill Poster (.PNG) with dynamically generated monster band names, and exports a seamless 2-bar loop (.WAV) for game creators to use in their own projects.
How we built it
We leveraged Kiro's Spec-Driven Development (SDD) workflow to build the entire application from scratch without external dependencies:
.kiro/steering/: Defined strict architectural rules, restricting external asset fetching, locking the color palette to antique storybook tones (#1A1412,#4A3228,#6B1D2F,#F2E6D0), and requiring pure Web Audio synthesis..kiro/specs/: Structured our project with rigorous EARS notation (WHEN ... THE SYSTEM SHALL ...) acrossrequirements.md,design.md, andtasks.md.- Harmonic Architecture: Locked the entire ensemble into a unified 32-step C Harmonic Minor chord progression (Cm → Ab → Fm → G7), maintaining harmonic coherence regardless of how users combine the 36 distinct puppet parts.
- Unified Shuffle Groove: When either the Jack-o'-Lantern or Skeleton selects a shuffle groove, a synchronized swing delay of 0.32 × step duration is applied across all active tracks to prevent rhythmic misalignment.
Challenges we ran into
1. Seamless WAV Loop Export via 44,800 Hz Pre-Roll & Circular Resampling
At 112 BPM, a 2-bar (32-step) loop lasts approximately 4.2857 seconds and contains exactly 189,000 sample frames at 44,100 Hz. However, this is not a multiple of Web Audio's 128-frame render block, causing phase discrepancies between successive loops.
Kiro autonomously diagnosed this issue during integration testing and engineered a DSP solution:
- Rendered two complete loops (64 steps) in an
OfflineAudioContextat an intermediate sample rate of 44,800 Hz, where each loop contains exactly 192,000 sample frames, equivalent to 1,500 render blocks. - Extracted the second loop to preserve the accumulated feedback delay tails.
- Applied circular Kaiser-windowed sinc resampling to convert the audio to standard 44,100 Hz, 16-bit stereo PCM WAV while preserving its periodic structure.
The resulting export preserves natural delay tails while dramatically reducing waveform discontinuities at the loop boundary. Across 12 tested arrangements, the boundary jumps were substantially smaller than typical sample-to-sample changes within the music itself.
2. Audio-Visual Output Synchronization
Web applications can suffer from audio-visual misalignment when animations trigger on scheduler timers rather than actual audio output. Furthermore, frame-based dampening (energy *= 0.85) leads to inconsistent animation speeds across displays with different refresh rates.
We addressed this by reading audio output time via audioCtx.getOutputTimestamp().contextTime and driving visual motion through exponential time decay:
energy(t) = exp(-(outputTime - noteTime) / Ï„)
This allows the Jack-o'-Lantern's mouth, the Skeleton's rib strikes, the Cauldron's bubbles, and the Ghost's stretching motions to follow the audio timeline rather than depending on a fixed visual frame rate.
Accomplishments that we're proud of
- 100% Pure Client-Side: Zero external audio samples, zero external graphics assets, zero backend servers, and zero API keys. All artwork, animations, and sounds are generated programmatically.
- 531,441 Possible Ensembles: With four customizable puppets, each featuring three slots with three choices, players can discover hundreds of thousands of distinctive visual and musical combinations.
- Autonomous DSP Engineering: Kiro not only generated the frontend and audio graphs but independently identified audio boundary anomalies and implemented circular resampling.
- Incredible Efficiency: From initial specification to complete multi-track implementation, self-directed regression testing, and automated demo video production, the entire workflow consumed approximately 102 Kiro credits—less than 2.6% of our 4,000-credit allocation.
- Heart & Charm: Balancing technical audio-synthesis rigor with whimsical storybook theater animation to create a playful experience full of personality.
What we learned
Spec-driven AI development works best when humans provide musical and architectural guardrails while allowing the agent freedom to solve lower-level edge cases.
Kiro proved capable of acting not only as a software developer but also as a procedural artist, audio engineer, quality assurance tester, and even a video producer.
The combination of precise specifications and creative freedom allowed us to build an entire interactive musical experience in a single day.
What's next for Monster Puppet Theater
- Expanding the theater with swappable backdrops and seasonal monster guest stars.
- Adding a MIDI-export feature so game developers can take both the synthesized WAVs and MIDI note arrangements directly into their favorite DAWs.
- Bringing even more musical monsters and theatrical surprises to our little haunted stage.