hyperframes 0.2.2-alpha.4 → 0.2.3-alpha.1

package/dist/skills/gsap/references/plugins.md

@@ -0,0 +1,194 @@
+# GSAP Plugins
+
+Register each plugin once before use:
+
+```javascript
+import gsap from "gsap";
+import { ScrollToPlugin } from "gsap/ScrollToPlugin";
+import { Flip } from "gsap/Flip";
+gsap.registerPlugin(ScrollToPlugin, Flip);
+```
+
+## Table of Contents
+
+- [ScrollToPlugin](#scrolltoplugin)
+- [ScrollSmoother](#scrollsmoother)
+- [Flip](#flip)
+- [Draggable + Inertia](#draggable)
+- [Observer](#observer)
+- [SplitText](#splittext)
+- [ScrambleText](#scrambletext)
+- [DrawSVG](#drawsvg)
+- [MorphSVG](#morphsvg)
+- [MotionPath](#motionpath)
+- [CustomEase / EasePack](#customeaseeasepak)
+- [Physics2D / PhysicsProps](#physics)
+- [GSDevTools](#gsdevtools)
+- [PixiPlugin](#pixiplugin)
+
+---
+
+## ScrollToPlugin
+
+Animate scroll position (window or scrollable element).
+
+```javascript
+gsap.to(window, { scrollTo: { y: "#section", offsetY: 50 }, duration: 1 });
+gsap.to(scrollContainer, { scrollTo: { x: "max" }, duration: 1 });
+```
+
+## ScrollSmoother
+
+Smooth scroll wrapper. Requires ScrollTrigger + specific DOM structure (`#smooth-wrapper` > `#smooth-content`).
+
+## Flip
+
+FLIP layout transitions: capture state, change DOM, animate from old to new.
+
+```javascript
+const state = Flip.getState(".item");
+// change DOM (reorder, add/remove, change classes)
+Flip.from(state, { duration: 0.5, ease: "power2.inOut" });
+```
+
+Options: `absolute`, `nested`, `scale`, `simple`, `duration`, `ease`.
+
+## Draggable
+
+Makes elements draggable/spinnable/throwable.
+
+```javascript
+gsap.registerPlugin(Draggable, InertiaPlugin);
+Draggable.create(".box", { type: "x,y", bounds: "#container", inertia: true });
+Draggable.create(".knob", { type: "rotation" });
+```
+
+Types: `"x"`, `"y"`, `"x,y"`, `"rotation"`, `"scroll"`. Options: `bounds`, `inertia`, `edgeResistance`, `cursor`, drag callbacks.
+
+### Inertia (InertiaPlugin)
+
+Momentum after release with Draggable, or track velocity of any property:
+
+```javascript
+InertiaPlugin.track(".box", "x");
+gsap.to(obj, { inertia: { x: "auto" } });
+```
+
+## Observer
+
+Normalized pointer/scroll input across devices. Use for swipe/gesture detection.
+
+```javascript
+Observer.create({
+  target: "#area",
+  onUp: () => {},
+  onDown: () => {},
+  tolerance: 10,
+});
+```
+
+## SplitText
+
+Split text into chars, words, lines for per-unit animation.
+
+```javascript
+const split = SplitText.create(".heading", { type: "words, chars" });
+gsap.from(split.chars, { opacity: 0, y: 20, stagger: 0.03 });
+// later: split.revert()
+```
+
+Key options: `type` (comma-separated: chars/words/lines), `charsClass`/`wordsClass`/`linesClass`, `aria` ("auto"/"hidden"/"none"), `autoSplit` + `onSplit(self)` for font-safe re-splitting, `mask` (lines/words/chars for reveal effects), `tag`, `ignore`, `smartWrap`, `propIndex`.
+
+Tips: Split only what's animated. For custom fonts, use `autoSplit: true` with `onSplit()`. Avoid `text-wrap: balance`.
+
+## ScrambleText
+
+Scramble/glitch text effect.
+
+```javascript
+gsap.to(".text", { scrambleText: { text: "New message", chars: "01", revealDelay: 0.5 } });
+```
+
+## DrawSVG
+
+Animate SVG stroke reveal (stroke-dashoffset/dasharray). Element must have `stroke` and `stroke-width`.
+
+```javascript
+gsap.from("#path", { drawSVG: 0, duration: 1 }); // nothing to full stroke
+gsap.to("#path", { drawSVG: "20% 80%", duration: 1 }); // partial segment
+```
+
+`drawSVG` value = visible segment: `"start end"` in % or length. Single value (e.g. `0`) means start is 0.
+
+## MorphSVG
+
+Morph one SVG shape into another. Handles different point counts.
+
+```javascript
+MorphSVGPlugin.convertToPath("circle, rect, ellipse, line");
+gsap.to("#diamond", { morphSVG: "#lightning", duration: 1 });
+// object form: { shape, type: "rotational", shapeIndex, smooth, curveMode }
+```
+
+Use `shapeIndex: "log"` to find optimal value. `type: "rotational"` avoids kinks.
+
+## MotionPath
+
+Animate along an SVG path.
+
+```javascript
+gsap.to(".dot", {
+  motionPath: { path: "#path", align: "#path", alignOrigin: [0.5, 0.5], autoRotate: true },
+});
+```
+
+## CustomEase/EasePack
+
+Custom curves beyond built-in eases:
+
+```javascript
+const ease = CustomEase.create("name", ".17,.67,.83,.67");
+// or SVG path data for complex curves
+const hop = CustomEase.create("hop", "M0,0 C0,0 0.056,0.442 ...");
+```
+
+EasePack adds SlowMo, RoughEase, ExpoScaleEase. CustomWiggle for oscillation. CustomBounce for configurable bounces.
+
+## Physics
+
+### Physics2D
+
+```javascript
+gsap.to(".ball", { physics2D: { velocity: 250, angle: 80, gravity: 500 }, duration: 2 });
+```
+
+### PhysicsProps
+
+```javascript
+gsap.to(".obj", {
+  physicsProps: { x: { velocity: 100, end: 300 }, y: { velocity: -50, acceleration: 200 } },
+  duration: 2,
+});
+```
+
+## GSDevTools
+
+Timeline scrubbing UI for development. **Do not ship to production.**
+
+```javascript
+GSDevTools.create({ animation: tl });
+```
+
+## PixiPlugin
+
+Integrates GSAP with PixiJS display objects.
+
+```javascript
+gsap.to(sprite, { pixi: { x: 200, scale: 1.5 }, duration: 1 });
+```
+
+## Do Not
+
+- Use a plugin without registering it first.
+- Ship GSDevTools to production.
+- Forget to revert SplitText instances on unmount.

package/dist/skills/gsap/references/react.md

@@ -0,0 +1,80 @@
+# GSAP with React
+
+## Installation
+
+```bash
+npm install gsap @gsap/react
+```
+
+## useGSAP() Hook (Preferred)
+
+```javascript
+import { useGSAP } from "@gsap/react";
+gsap.registerPlugin(useGSAP);
+
+const containerRef = useRef(null);
+useGSAP(
+  () => {
+    gsap.to(".box", { x: 100 });
+  },
+  { scope: containerRef },
+);
+```
+
+- Pass **scope** (ref) so selectors are scoped to the component.
+- Cleanup runs automatically on unmount.
+- Use **contextSafe** for callbacks created after useGSAP executes:
+
+```javascript
+useGSAP(
+  (context, contextSafe) => {
+    const onClick = contextSafe(() => {
+      gsap.to(ref.current, { rotation: 180 });
+    });
+    ref.current.addEventListener("click", onClick);
+    return () => ref.current.removeEventListener("click", onClick);
+  },
+  { scope: container },
+);
+```
+
+## Dependency Array and revertOnUpdate
+
+```javascript
+useGSAP(
+  () => {
+    /* gsap code */
+  },
+  {
+    dependencies: [endX],
+    scope: container,
+    revertOnUpdate: true, // reverts + re-runs on dependency change
+  },
+);
+```
+
+## gsap.context() in useEffect (Fallback)
+
+When @gsap/react isn't available:
+
+```javascript
+useEffect(() => {
+  const ctx = gsap.context(() => {
+    gsap.to(".box", { x: 100 });
+  }, containerRef);
+  return () => ctx.revert();
+}, []);
+```
+
+Always return `ctx.revert()` in cleanup.
+
+## SSR (Next.js)
+
+GSAP runs in the browser. Keep all GSAP code inside useGSAP or useEffect.
+
+## Do Not
+
+- Target by selector without a scope — always pass scope.
+- Skip cleanup — always revert context or kill tweens on unmount.
+- Run GSAP during SSR.
+- Register plugins inside components that re-render — register once at app level.

package/dist/skills/gsap/references/scrolltrigger.md

@@ -0,0 +1,147 @@
+# ScrollTrigger
+
+## Registering
+
+```javascript
+gsap.registerPlugin(ScrollTrigger);
+```
+
+## Basic Trigger
+
+```javascript
+gsap.to(".box", {
+  x: 500,
+  scrollTrigger: {
+    trigger: ".box",
+    start: "top center",
+    end: "bottom center",
+    toggleActions: "play reverse play reverse",
+  },
+});
+```
+
+**start/end** format: `"triggerPosition viewportPosition"`. Examples: `"top top"`, `"center center"`, `"bottom 80%"`, numeric px `500`, relative `"+=300"`, `"+=100%"` (scroller height), `"max"`. Wrap in `clamp()` (v3.12+): `"clamp(top bottom)"`. Can be a function returning string/number.
+
+## Key Config Options
+
+| Property                                        | Type                                  | Description                                                                                                                                               |
+| ----------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **trigger**                                     | String/Element                        | Element whose position defines start. Required.                                                                                                           |
+| **start**                                       | String/Number/Function                | When active. Default `"top bottom"` (or `"top top"` if pinned).                                                                                           |
+| **end**                                         | String/Number/Function                | When ends. Default `"bottom top"`.                                                                                                                        |
+| **endTrigger**                                  | String/Element                        | Different element for end calculation.                                                                                                                    |
+| **scrub**                                       | Boolean/Number                        | Link progress to scroll. `true` = direct; number = catch-up seconds.                                                                                      |
+| **toggleActions**                               | String                                | Four actions: onEnter, onLeave, onEnterBack, onLeaveBack. Values: play/pause/resume/reset/restart/complete/reverse/none. Default `"play none none none"`. |
+| **pin**                                         | Boolean/String/Element                | Pin element while active. `true` = pin trigger. Animate children, not the pinned element.                                                                 |
+| **pinSpacing**                                  | Boolean/String                        | Default `true` (adds spacer). `false` or `"margin"`.                                                                                                      |
+| **horizontal**                                  | Boolean                               | For horizontal scrolling.                                                                                                                                 |
+| **scroller**                                    | String/Element                        | Scroll container (default: viewport).                                                                                                                     |
+| **markers**                                     | Boolean/Object                        | Dev markers. Remove in production.                                                                                                                        |
+| **once**                                        | Boolean                               | Kill after end reached once.                                                                                                                              |
+| **snap**                                        | Number/Array/Function/"labels"/Object | Snap to progress values.                                                                                                                                  |
+| **containerAnimation**                          | Tween/Timeline                        | For fake horizontal scroll (see below).                                                                                                                   |
+| **toggleClass**                                 | String/Object                         | Add/remove class when active.                                                                                                                             |
+| **onEnter/onLeave/onEnterBack/onLeaveBack**     | Function                              | Callbacks; receive ScrollTrigger instance.                                                                                                                |
+| **onUpdate/onToggle/onRefresh/onScrubComplete** | Function                              | Progress/state callbacks.                                                                                                                                 |
+
+**Standalone** (no linked tween): `ScrollTrigger.create({...})` with callbacks.
+
+## Scrub
+
+```javascript
+scrollTrigger: { trigger: ".box", start: "top center", end: "bottom center", scrub: true }
+```
+
+`scrub: true` = direct link; number (e.g. `1`) = smooth lag.
+
+## Pinning
+
+```javascript
+scrollTrigger: {
+  trigger: ".section", start: "top top", end: "+=1000", pin: true, scrub: 1
+}
+```
+
+## Timeline + ScrollTrigger
+
+```javascript
+const tl = gsap.timeline({
+  scrollTrigger: { trigger: ".container", start: "top top", end: "+=2000", scrub: 1, pin: true },
+});
+tl.to(".a", { x: 100 }).to(".b", { y: 50 });
+```
+
+## ScrollTrigger.batch()
+
+Creates one ScrollTrigger per target, batches callbacks within a short interval. Good for staggered reveal of many elements.
+
+```javascript
+ScrollTrigger.batch(".box", {
+  onEnter: (elements) => gsap.to(elements, { opacity: 1, y: 0, stagger: 0.15 }),
+  start: "top 80%",
+});
+```
+
+Options: `interval` (batch window), `batchMax` (max per batch). Callbacks receive `(targets, scrollTriggers)`.
+
+## Horizontal Scroll (containerAnimation)
+
+Pin a section, animate inner content's `x`/`xPercent` horizontally on vertical scroll:
+
+1. Pin the section
+2. Animate inner content with **ease: "none"** (required)
+3. Attach ScrollTrigger with pin + scrub
+4. Use `containerAnimation` on nested triggers
+
+```javascript
+const scrollTween = gsap.to(scrollingEl, {
+  xPercent: () => Math.max(0, window.innerWidth - scrollingEl.offsetWidth),
+  ease: "none",
+  scrollTrigger: {
+    trigger: scrollingEl,
+    pin: scrollingEl.parentNode,
+    start: "top top",
+    end: "+=1000",
+  },
+});
+
+gsap.to(".nested", {
+  y: 100,
+  scrollTrigger: { containerAnimation: scrollTween, trigger: ".wrapper", start: "left center" },
+});
+```
+
+Pinning and snapping unavailable on containerAnimation-based ScrollTriggers.
+
+## ScrollTrigger.scrollerProxy()
+
+Override scroll position reading for third-party smooth-scroll libraries. Call `ScrollTrigger.update` when the scroller updates.
+
+```javascript
+ScrollTrigger.scrollerProxy(document.body, {
+  scrollTop(value) {
+    if (arguments.length) scrollbar.scrollTop = value;
+    return scrollbar.scrollTop;
+  },
+  getBoundingClientRect() {
+    return { top: 0, left: 0, width: window.innerWidth, height: window.innerHeight };
+  },
+});
+scrollbar.addListener(ScrollTrigger.update);
+```
+
+## Refresh and Cleanup
+
+- `ScrollTrigger.refresh()` — recalculate after DOM/layout changes. Auto on resize (200ms debounce).
+- Create ScrollTriggers top-to-bottom or set `refreshPriority`.
+- Kill instances when removing elements: `ScrollTrigger.getAll().forEach(t => t.kill())` or `ScrollTrigger.getById("id")?.kill()`.
+
+## Do Not
+
+- Put ScrollTrigger on child tweens inside a timeline — put on the timeline.
+- Nest ScrollTriggered animations inside a parent timeline.
+- Use scrub and toggleActions together (scrub wins).
+- Use an ease other than "none" on the horizontal animation with containerAnimation.
+- Leave markers in production.
+- Create triggers in random order without refreshPriority.
+- Forget refresh() after layout changes.

package/dist/skills/gsap/references/utils.md

@@ -0,0 +1,91 @@
+# gsap.utils
+
+Pure helpers on `gsap.utils`. No registration needed.
+
+**Function form:** Most utils accept the value as the last argument. Omit it to get a reusable function: `gsap.utils.clamp(0, 100)(150)`. Exception: `random()` — pass `true` as the last argument for a reusable function.
+
+## Clamping and Ranges
+
+### clamp(min, max, value?)
+
+```javascript
+gsap.utils.clamp(0, 100, 150); // 100
+let c = gsap.utils.clamp(0, 100);
+c(150); // 100
+```
+
+### mapRange(inMin, inMax, outMin, outMax, value?)
+
+```javascript
+gsap.utils.mapRange(0, 1, 0, 360, 0.5); // 180
+let m = gsap.utils.mapRange(0, 100, 0, 500);
+m(50); // 250
+```
+
+### normalize(min, max, value?)
+
+Returns 0-1 for the range.
+
+```javascript
+gsap.utils.normalize(0, 100, 50); // 0.5
+```
+
+### interpolate(start, end, progress?)
+
+Numbers, colors, or objects with matching keys.
+
+```javascript
+gsap.utils.interpolate(0, 100, 0.5); // 50
+gsap.utils.interpolate("#ff0000", "#0000ff", 0.5); // mid color
+```
+
+## Random and Snap
+
+### random(min, max[, snap, returnFunction]) / random(array[, returnFunction])
+
+```javascript
+gsap.utils.random(-100, 100);
+gsap.utils.random(0, 500, 5); // snapped to 5
+let fn = gsap.utils.random(-200, 500, 10, true);
+fn(); // reusable
+gsap.utils.random(["red", "blue"]); // pick one
+```
+
+**String form in tweens:** `x: "random(-100, 100, 5)"`.
+
+### snap(snapTo, value?)
+
+```javascript
+gsap.utils.snap(10, 23); // 20
+gsap.utils.snap([0, 100, 200], 150); // nearest
+```
+
+### shuffle(array)
+
+Returns shuffled copy.
+
+### distribute(config)
+
+Returns a function assigning values by position. Config: `base`, `amount`/`each`, `from`, `grid`, `axis`, `ease`.
+
+```javascript
+gsap.to(".class", { scale: gsap.utils.distribute({ base: 0.5, amount: 2.5, from: "center" }) });
+```
+
+## Units and Parsing
+
+- **getUnit(value)** — `gsap.utils.getUnit("100px")` → `"px"`
+- **unitize(value, unit)** — `gsap.utils.unitize(100, "px")` → `"100px"`
+- **splitColor(color, returnHSL?)** — `gsap.utils.splitColor("red")` → `[255, 0, 0]`. Pass `true` for HSL.
+
+## Arrays and Collections
+
+- **selector(scope)** — scoped selector: `gsap.utils.selector(ref)(".box")`
+- **toArray(value, scope?)** — convert selector/NodeList/element to array
+- **pipe(...fns)** — compose: `pipe(f1, f2)(value)` = `f2(f1(value))`
+- **wrap(min, max, value?)** — cyclic wrap: `wrap(0, 360, 370)` → `10`
+- **wrapYoyo(min, max, value?)** — bounce wrap: `wrapYoyo(0, 100, 150)` → `50`
+
+## Do Not
+
+- Assume mapRange/normalize handle units — they work on numbers. Use getUnit/unitize.

package/dist/skills/gsap/scripts/extract-audio-data.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""
+Extract per-frame audio visualization data from an audio or video file.
+
+Outputs JSON with RMS amplitude and frequency band data at the target FPS,
+ready to embed in a HyperFrames composition.
+
+Usage:
+    python extract-audio-data.py input.mp3 -o audio-data.json
+    python extract-audio-data.py input.mp4 --fps 30 --bands 16 -o audio-data.json
+
+Requirements:
+    - Python 3.9+
+    - ffmpeg (for decoding audio)
+    - numpy (pip install numpy)
+"""
+
+import argparse
+import json
+import subprocess
+import sys
+
+import numpy as np
+
+# ---------------------------------------------------------------------------
+# FFT parameters
+#
+# A 4096-sample window gives ~10.8 Hz per bin at 44100Hz — enough to resolve
+# low-frequency bands cleanly. The per-frame audio slice (44100/30 = 1470
+# samples at 30fps) is too small and causes low bands to map to the same bins.
+#
+# Frequency range 30Hz–16kHz covers the useful range for music. Below 30Hz is
+# sub-bass most speakers can't reproduce; above 16kHz is noise/harmonics that
+# don't contribute to perceived rhythm or melody.
+# ---------------------------------------------------------------------------
+
+SAMPLE_RATE = 44100
+FFT_SIZE = 4096
+MIN_FREQ = 30.0
+MAX_FREQ = 16000.0
+
+
+def decode_audio(path: str) -> np.ndarray:
+    """Decode audio to mono float32 samples via ffmpeg."""
+    cmd = [
+        "ffmpeg", "-i", path,
+        "-vn", "-ac", "1", "-ar", str(SAMPLE_RATE),
+        "-f", "s16le", "-acodec", "pcm_s16le",
+        "-loglevel", "error",
+        "pipe:1",
+    ]
+    result = subprocess.run(cmd, capture_output=True)
+    if result.returncode != 0:
+        print(f"ffmpeg error: {result.stderr.decode()}", file=sys.stderr)
+        sys.exit(1)
+    return np.frombuffer(result.stdout, dtype=np.int16).astype(np.float32) / 32768.0
+
+
+def compute_band_edges(n_bands: int) -> np.ndarray:
+    """Logarithmically-spaced frequency band edges from MIN_FREQ to MAX_FREQ."""
+    return np.array([
+        MIN_FREQ * (MAX_FREQ / MIN_FREQ) ** (i / n_bands)
+        for i in range(n_bands + 1)
+    ])
+
+
+def compute_fft_bands(
+    windowed: np.ndarray, freq_per_bin: float, n_bins: int,
+    band_edges: np.ndarray, n_bands: int,
+) -> np.ndarray:
+    """Compute peak magnitude in logarithmically-spaced frequency bands."""
+    magnitudes = np.abs(np.fft.rfft(windowed))
+
+    bands = np.zeros(n_bands)
+    for b in range(n_bands):
+        low_bin = max(0, int(band_edges[b] / freq_per_bin))
+        high_bin = min(n_bins, int(band_edges[b + 1] / freq_per_bin))
+        if high_bin <= low_bin:
+            high_bin = low_bin + 1
+        # Clamp to valid range to avoid empty slices
+        low_bin = min(low_bin, n_bins - 1)
+        high_bin = min(high_bin, n_bins)
+        bands[b] = np.max(magnitudes[low_bin:high_bin])
+
+    return bands
+
+
+def extract(path: str, fps: int, n_bands: int) -> dict:
+    """Extract per-frame audio data."""
+    print(f"Decoding audio from {path}...", file=sys.stderr)
+    samples = decode_audio(path)
+    duration = len(samples) / SAMPLE_RATE
+    frame_step = SAMPLE_RATE // fps
+    total_frames = int(duration * fps)
+
+    print(f"Duration: {duration:.1f}s, {total_frames} frames at {fps}fps", file=sys.stderr)
+    print(f"FFT window: {FFT_SIZE} samples ({SAMPLE_RATE / FFT_SIZE:.1f} Hz/bin)", file=sys.stderr)
+    print(f"Frequency range: {MIN_FREQ:.0f}-{MAX_FREQ:.0f} Hz, {n_bands} bands", file=sys.stderr)
+
+    # Precompute constants
+    hann = np.hanning(FFT_SIZE)
+    band_edges = compute_band_edges(n_bands)
+    freq_per_bin = SAMPLE_RATE / FFT_SIZE
+    n_bins = FFT_SIZE // 2 + 1
+    half_fft = FFT_SIZE // 2
+
+    # Pass 1: extract raw values
+    rms_values = np.zeros(total_frames)
+    band_values = np.zeros((total_frames, n_bands))
+
+    for f in range(total_frames):
+        # RMS from the frame's audio slice
+        rms_start = f * frame_step
+        rms_end = rms_start + frame_step
+        frame_slice = samples[rms_start:min(rms_end, len(samples))]
+        if len(frame_slice) > 0:
+            rms_values[f] = np.sqrt(np.mean(frame_slice ** 2))
+
+        # FFT from a centered 4096-sample window
+        center = rms_start + frame_step // 2
+        win_start = center - half_fft
+        win_end = center + half_fft
+
+        if win_start >= 0 and win_end <= len(samples):
+            window = samples[win_start:win_end] * hann
+        else:
+            # Zero-pad at edges
+            padded = np.zeros(FFT_SIZE)
+            src_start = max(0, win_start)
+            src_end = min(len(samples), win_end)
+            dst_start = src_start - win_start
+            dst_end = dst_start + (src_end - src_start)
+            padded[dst_start:dst_end] = samples[src_start:src_end]
+            window = padded * hann
+
+        band_values[f] = compute_fft_bands(window, freq_per_bin, n_bins, band_edges, n_bands)
+
+    # Pass 2: normalize
+    peak_rms = rms_values.max() if total_frames > 0 else 1.0
+    if peak_rms > 0:
+        rms_values /= peak_rms
+
+    # Per-band normalization so treble is visible alongside louder bass
+    band_peaks = band_values.max(axis=0)
+    band_peaks[band_peaks == 0] = 1.0
+    band_values /= band_peaks
+
+    # Build output
+    frames = []
+    for f in range(total_frames):
+        frames.append({
+            "time": round(f / fps, 4),
+            "rms": round(float(rms_values[f]), 4),
+            "bands": [round(float(b), 4) for b in band_values[f]],
+        })
+
+    return {
+        "duration": round(duration, 4),
+        "fps": fps,
+        "bands": n_bands,
+        "totalFrames": total_frames,
+        "frames": frames,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Extract per-frame audio visualization data")
+    parser.add_argument("input", help="Audio or video file")
+    parser.add_argument("-o", "--output", default="audio-data.json", help="Output JSON path")
+    parser.add_argument("--fps", type=int, default=30, help="Frames per second (default: 30)")
+    parser.add_argument("--bands", type=int, default=16, help="Number of frequency bands (default: 16)")
+    args = parser.parse_args()
+
+    if args.fps < 1:
+        parser.error("--fps must be at least 1")
+    if args.bands < 1:
+        parser.error("--bands must be at least 1")
+
+    data = extract(args.input, args.fps, args.bands)
+
+    with open(args.output, "w") as f:
+        json.dump(data, f)
+
+    print(f"Wrote {args.output} ({data['totalFrames']} frames, {data['bands']} bands)", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()