viz — music visualizer engineering skill

A Claude Code plugin that makes Claude an expert advisor for building audio-reactive 2D and 3D visualizers across web (Three.js + Canvas 2D) and iOS (Metal fragment shaders).

Invoke with /viz:studiojoe inside Claude Code.

What this plugin gives you

A loaded reference library Claude can consult mid-conversation whenever you're working on music visualizers:

• Proven patterns — dual-time oscillating drift for organic ink/fluid motion, EMA smoothing time constants for audio channels, raw-vs-smoothed beat dispatch, ACES tone mapping + physicallyCorrectLights save/restore for Three.js r128, normDt = dt * 60 idiom for porting 60-fps integrators to vsync-aware iOS, center-subtract FBM noise, Inigo-Quilez smooth-min for metaballs.
• A new-viz recipe — step-by-step Phase 1 (standalone HTML prototype) → Phase 2 (web integration with a registry pattern) → Phase 3 (iOS Metal shader + Swift uniforms) → Phase 4 (parity check), with code skeletons for each phase.
• Stack contracts — a registry API skeleton for self-registering web visualizers, an AudioFrame schema, uniform-struct layout rules for matching Metal and Swift side-by-side.
• Web ↔ iOS parity rule — when to propagate a tuning change across platforms and what counts as tuning vs platform-specific code.
• Apple MetalSampleCode index — 48 Apple samples tiered HIGH / MEDIUM / LOW by relevance to music visualizers, with a one-line reason for each.
• PBR cheat sheet — Three.js r128 (MeshPhysicalMaterial, PMREM env map, ACES, UnrealBloomPass) matched to equivalent Metal patterns.
• Performance playbook — DPR clamping, raymarch step caps on mobile, triple-buffered uniforms, MetalFX upscaling, bloom cost management.
• External resources — curated links to shader-tutorial.dev, Inigo Quilez, The Book of Shaders, SebLague's procedural/sim projects, three.js/examples, WebGLFundamentals, plus the authoritative WebGL 1.0 and OpenGL ES specs.
• A 5-demo showcase — standalone HTML files you can open in a browser (no build, no server) demonstrating each technique: Fluid Ink (SDF + dual-time drift), Chrome Orb (disco-tile geometry + real-time CubeCamera reflections + procedural nebula skybox), Kaleidoscope Tunnel (6-fold polar fold shader), Particle Waves (Canvas 2D beat-reactive), Wire Terrain (vertex-shader displacement).

Installation

Via Claude Code plugin install (recommended)

/plugin install https://github.com/jayvee6/viz-plugin

Manual install (any environment)

# 1. Clone anywhere on disk
git clone https://github.com/jayvee6/viz-plugin ~/.claude-plugins/viz

# 2. Tell Claude Code about it (see your Claude Code plugin docs for the
#    current mechanism — usually adding to ~/.claude/settings.json or
#    running /plugin install <local-path>)

Usage

Inside Claude Code, run:

/viz:studiojoe

Or just start working on visualizer code and the skill will trigger automatically if your task matches its description — adding a new viz, tuning an existing one, raymarching / SDFs, PBR setup, Three.js r128 specifics, Metal fragment shaders for audio-reactive graphics, performance tuning for real-time GPU work, or porting visualizers between web and iOS.

Showcase demos

The skills/studiojoe/showcase/ directory contains five standalone HTML files. Open any of them in a browser — no build step, no server required — to see a working example of the patterns documented in references/. Each uses a sine-based fake audio frame so reactivity is visible without hooking up a microphone or music source.

open skills/studiojoe/showcase/index.html

Origin + acknowledgements

This plugin is distilled from two parallel music-visualizer projects:

• jayvee6/musicplayer-viz — browser music visualizer (vanilla JS + Three.js r128 UMD + Canvas 2D, Spotify + Apple Music full-track playback, self-registering visualizer modules)
• jayvee6/StudioJoeMusic — iOS music visualizer (SwiftUI + Metal fragment shaders, AVAudioEngine tap with vDSP for FFT + onset/BPM)

Those repos are the reference implementations for the patterns documented here. If you're building something similar, skimming them alongside this skill will show the patterns in situ. If you're building something different, the patterns still apply — metaballs, raymarched SDFs, PBR chrome, and beat-driven particles don't care what audio source feeds them.

Shader + technique credits are inline in skills/studiojoe/references/ (Inigo Quilez for smooth-min and noise; Sebastian Lague for procedural/simulation algorithms; the Book of Shaders and shader-tutorial.dev for foundations).

License

MIT — do what you want, but attribution is appreciated.