calvyn-code 0.14.0

package/skills/creative/ascii-video/README.md

@@ -0,0 +1,290 @@
+# ☤ ASCII Video
+
+Renders any content as colored ASCII character video. Audio, video, images, text, or pure math in, MP4/GIF/PNG sequence out. Full RGB color per character cell, 1080p 24fps default. No GPU.
+
+Built for [Hermes Agent](https://github.com/NousResearch/hermes-agent). Usable in any coding agent. Canonical source lives here; synced to [`NousResearch/hermes-agent/skills/creative/ascii-video`](https://github.com/NousResearch/hermes-agent/tree/main/skills/creative/ascii-video) via PR.
+
+## What this is
+
+A skill that teaches an agent how to build single-file Python renderers for ASCII video from scratch. The agent gets the full pipeline: grid system, font rasterization, effect library, shader chain, audio analysis, parallel encoding. It writes the renderer, runs it, gets video.
+
+The output is actual video. Not terminal escape codes. Frames are computed as grids of colored characters, composited onto pixel canvases with pre-rasterized font bitmaps, post-processed through shaders, piped to ffmpeg.
+
+## Modes
+
+| Mode | Input | Output |
+|------|-------|--------|
+| Video-to-ASCII | A video file | ASCII recreation of the footage |
+| Audio-reactive | An audio file | Visuals driven by frequency bands, beats, energy |
+| Generative | Nothing | Procedural animation from math |
+| Hybrid | Video + audio | ASCII video with audio-reactive overlays |
+| Lyrics/text | Audio + timed text (SRT) | Karaoke-style text with effects |
+| TTS narration | Text quotes + API key | Narrated video with typewriter text and generated speech |
+
+## Pipeline
+
+Every mode follows the same 6-stage path:
+
+```
+INPUT --> ANALYZE --> SCENE_FN --> TONEMAP --> SHADE --> ENCODE
+```
+
+1. **Input** loads source material (or nothing for generative).
+2. **Analyze** extracts per-frame features. Audio gets 6-band FFT, RMS, spectral centroid, flatness, flux, beat detection with exponential decay. Video gets luminance, edges, motion.
+3. **Scene function** returns a pixel canvas directly. Composes multiple character grids at different densities, value/hue fields, pixel blend modes. This is where the visuals happen.
+4. **Tonemap** does adaptive percentile-based brightness normalization with per-scene gamma. ASCII on black is inherently dark. Linear multipliers don't work. This does.
+5. **Shade** runs a `ShaderChain` (38 composable shaders) plus a `FeedbackBuffer` for temporal recursion with spatial transforms.
+6. **Encode** pipes raw RGB frames to ffmpeg for H.264 encoding. Segments concatenated, audio muxed.
+
+## Grid system
+
+Characters render on fixed-size grids. Layer multiple densities for depth.
+
+| Size | Font | Grid at 1080p | Use |
+|------|------|---------------|-----|
+| xs | 8px | 400x108 | Ultra-dense data fields |
+| sm | 10px | 320x83 | Rain, starfields |
+| md | 16px | 192x56 | Default balanced |
+| lg | 20px | 160x45 | Readable text |
+| xl | 24px | 137x37 | Large titles |
+| xxl | 40px | 80x22 | Giant minimal |
+
+Rendering the same scene on `sm` and `lg` then screen-blending them creates natural texture interference. Fine detail shows through gaps in coarse characters. Most scenes use two or three grids.
+
+## Character palettes (24)
+
+Each sorted dark-to-bright, each a different visual texture. Validated against the font at init so broken glyphs get dropped silently.
+
+| Family | Examples | Feel |
+|--------|----------|------|
+| Density ramps | ` .:-=+#@█` | Classic ASCII art gradient |
+| Block elements | ` ░▒▓█▄▀▐▌` | Chunky, digital |
+| Braille | ` ⠁⠂⠃...⠿` | Fine-grained pointillism |
+| Dots | ` ⋅∘∙●◉◎` | Smooth, organic |
+| Stars | ` ·✧✦✩✨★✶` | Sparkle, celestial |
+| Half-fills | ` ◔◑◕◐◒◓◖◗◙` | Directional fill progression |
+| Crosshatch | ` ▣▤▥▦▧▨▩` | Hatched density ramp |
+| Math | ` ·∘∙•°±×÷≈≠≡∞∫∑Ω` | Scientific, abstract |
+| Box drawing | ` ─│┌┐└┘├┤┬┴┼` | Structural, circuit-like |
+| Katakana | ` ·ｦｧｨｩｪｫｬｭ...` | Matrix rain |
+| Greek | ` αβγδεζηθ...ω` | Classical, academic |
+| Runes | ` ᚠᚢᚦᚱᚷᛁᛇᛒᛖᛚᛞᛟ` | Mystical, ancient |
+| Alchemical | ` ☉☽♀♂♃♄♅♆♇` | Esoteric |
+| Arrows | ` ←↑→↓↔↕↖↗↘↙` | Directional, kinetic |
+| Music | ` ♪♫♬♩♭♮♯○●` | Musical |
+| Project-specific | ` .·~=≈∞⚡☿✦★⊕◊◆▲▼●■` | Themed per project |
+
+Custom palettes are built per project to match the content.
+
+## Color strategies
+
+| Strategy | How it maps hue | Good for |
+|----------|----------------|----------|
+| Angle-mapped | Position angle from center | Rainbow radial effects |
+| Distance-mapped | Distance from center | Depth, tunnels |
+| Frequency-mapped | Audio spectral centroid | Timbral shifting |
+| Value-mapped | Brightness level | Heat maps, fire |
+| Time-cycled | Slow rotation over time | Ambient, chill |
+| Source-sampled | Original video pixel colors | Video-to-ASCII |
+| Palette-indexed | Discrete lookup table | Retro, flat graphic |
+| Temperature | Warm-to-cool blend | Emotional tone |
+| Complementary | Hue + opposite | Bold, dramatic |
+| Triadic | Three equidistant hues | Psychedelic, vibrant |
+| Analogous | Neighboring hues | Harmonious, subtle |
+| Monochrome | Fixed hue, vary S/V | Noir, focused |
+
+Plus 10 discrete RGB palettes (neon, pastel, cyberpunk, vaporwave, earth, ice, blood, forest, mono-green, mono-amber).
+
+Full OKLAB/OKLCH color system: sRGB↔linear↔OKLAB conversion pipeline, perceptually uniform gradient interpolation, and color harmony generation (complementary, triadic, analogous, split-complementary, tetradic).
+
+## Value field generators (21)
+
+Value fields are the core visual building blocks. Each produces a 2D float array in [0, 1] mapping every grid cell to a brightness value.
+
+### Trigonometric (12)
+
+| Field | Description |
+|-------|-------------|
+| Sine field | Layered multi-sine interference, general-purpose background |
+| Smooth noise | Multi-octave sine approximation of Perlin noise |
+| Rings | Concentric rings, bass-driven count and wobble |
+| Spiral | Logarithmic spiral arms, configurable arm count/tightness |
+| Tunnel | Infinite depth perspective (inverse distance) |
+| Vortex | Twisting radial pattern, distance modulates angle |
+| Interference | N overlapping sine waves creating moire |
+| Aurora | Horizontal flowing bands |
+| Ripple | Concentric waves from configurable source points |
+| Plasma | Sum of sines at multiple orientations/speeds |
+| Diamond | Diamond/checkerboard pattern |
+| Noise/static | Random per-cell per-frame flicker |
+
+### Noise-based (4)
+
+| Field | Description |
+|-------|-------------|
+| Value noise | Smooth organic noise, no axis-alignment artifacts |
+| fBM | Fractal Brownian Motion — octaved noise for clouds, terrain, smoke |
+| Domain warp | Inigo Quilez technique — fBM-driven coordinate distortion for flowing organic forms |
+| Voronoi | Moving seed points with distance, edge, and cell-ID output modes |
+
+### Simulation-based (4)
+
+| Field | Description |
+|-------|-------------|
+| Reaction-diffusion | Gray-Scott with 7 presets: coral, spots, worms, labyrinths, mitosis, pulsating, chaos |
+| Cellular automata | Game of Life + 4 rule variants with analog fade trails |
+| Strange attractors | Clifford, De Jong, Bedhead — iterated point systems binned to density fields |
+| Temporal noise | 3D noise that morphs in-place without directional drift |
+
+### SDF-based
+
+7 signed distance field primitives (circle, box, ring, line, triangle, star, heart) with smooth boolean combinators (union, intersection, subtraction, smooth union/subtraction) and infinite tiling. Render as solid fills or glowing outlines.
+
+## Hue field generators (9)
+
+Determine per-cell color independent of brightness: fixed hue, angle-mapped rainbow, distance gradient, time-cycled rotation, audio spectral centroid, horizontal/vertical gradients, plasma variation, perceptually uniform OKLCH rainbow.
+
+## Coordinate transforms (11)
+
+UV-space transforms applied before effect evaluation: rotate, scale, skew, tile (with mirror seaming), polar, inverse-polar, twist (rotation increasing with distance), fisheye, wave displacement, Möbius conformal transformation. `make_tgrid()` wraps transformed coordinates into a grid object.
+
+## Particle systems (9)
+
+| Type | Behavior |
+|------|----------|
+| Explosion | Beat-triggered radial burst with gravity and life decay |
+| Embers | Rising from bottom with horizontal drift |
+| Dissolving cloud | Spreading outward with accelerating fade |
+| Starfield | 3D projected, Z-depth stars approaching with streak trails |
+| Orbit | Circular/elliptical paths around center |
+| Gravity well | Attracted toward configurable point sources |
+| Boid flocking | Separation/alignment/cohesion with spatial hash for O(n) neighbors |
+| Flow-field | Steered by gradient of any value field |
+| Trail particles | Fading lines between current and previous positions |
+
+14 themed particle character sets (energy, spark, leaf, snow, rain, bubble, data, hex, binary, rune, zodiac, dot, dash).
+
+## Temporal coherence
+
+10 easing functions (linear, quad, cubic, expo, elastic, bounce — in/out/in-out). Keyframe interpolation with eased transitions. Value field morphing (smooth crossfade between fields). Value field sequencing (cycle through fields with crossfade). Temporal noise (3D noise evolving smoothly in-place).
+
+## Shader pipeline
+
+38 composable shaders, applied to the pixel canvas after character rendering. Configurable per section.
+
+| Category | Shaders |
+|----------|---------|
+| Geometry | CRT barrel, pixelate, wave distort, displacement map, kaleidoscope, mirror (h/v/quad/diag) |
+| Channel | Chromatic aberration (beat-reactive), channel shift, channel swap, RGB split radial |
+| Color | Invert, posterize, threshold, solarize, hue rotate, saturation, color grade, color wobble, color ramp |
+| Glow/Blur | Bloom, edge glow, soft focus, radial blur |
+| Noise | Film grain (beat-reactive), static noise |
+| Lines/Patterns | Scanlines, halftone |
+| Tone | Vignette, contrast, gamma, levels, brightness |
+| Glitch/Data | Glitch bands (beat-reactive), block glitch, pixel sort, data bend |
+
+12 color tint presets: warm, cool, matrix green, amber, sepia, neon pink, ice, blood, forest, void, sunset, neutral.
+
+7 mood presets for common shader combos:
+
+| Mood | Shaders |
+|------|---------|
+| Retro terminal | CRT + scanlines + grain + amber/green tint |
+| Clean modern | Light bloom + subtle vignette |
+| Glitch art | Heavy chromatic + glitch bands + color wobble |
+| Cinematic | Bloom + vignette + grain + color grade |
+| Dreamy | Heavy bloom + soft focus + color wobble |
+| Harsh/industrial | High contrast + grain + scanlines, no bloom |
+| Psychedelic | Color wobble + chromatic + kaleidoscope mirror |
+
+## Blend modes and composition
+
+20 pixel blend modes for layering canvases: normal, add, subtract, multiply, screen, overlay, softlight, hardlight, difference, exclusion, colordodge, colorburn, linearlight, vividlight, pin_light, hard_mix, lighten, darken, grain_extract, grain_merge. Both sRGB and linear-light blending supported.
+
+**Feedback buffer.** Temporal recursion — each frame blends with a transformed version of the previous frame. 7 spatial transforms: zoom, shrink, rotate CW/CCW, shift up/down, mirror. Optional per-frame hue shift for rainbow trails. Configurable decay, blend mode, and opacity per scene.
+
+**Masking.** 16 mask types for spatial compositing: shape masks (circle, rect, ring, gradients), procedural masks (any value field as a mask, text stencils), animated masks (iris open/close, wipe, dissolve), boolean operations (union, intersection, subtraction, invert).
+
+**Transitions.** Crossfade, directional wipe, radial wipe, dissolve, glitch cut.
+
+## Scene design patterns
+
+Compositional patterns for making scenes that look intentional rather than random.
+
+**Layer hierarchy.** Background (dim atmosphere, dense grid), content (main visual, standard grid), accent (sparse highlights, coarse grid). Three distinct roles, not three competing layers.
+
+**Directional parameter arcs.** The defining parameter of each scene ramps, accelerates, or builds over its duration. Progress-based formulas (linear, ease-out, step reveal) replace aimless `sin(t)` oscillation.
+
+**Scene concepts.** Scenes built around visual metaphors (emergence, descent, collision, entropy) with motivated layer/palette/feedback choices. Not named after their effects.
+
+**Compositional techniques.** Counter-rotating dual systems, wave collision, progressive fragmentation (voronoi cells multiplying over time), entropy (geometry consumed by reaction-diffusion), staggered layer entry (crescendo buildup).
+
+## Hardware adaptation
+
+Auto-detects CPU count, RAM, platform, ffmpeg. Adapts worker count, resolution, FPS.
+
+| Profile | Resolution | FPS | When |
+|---------|-----------|-----|------|
+| `draft` | 960x540 | 12 | Check timing/layout |
+| `preview` | 1280x720 | 15 | Review effects |
+| `production` | 1920x1080 | 24 | Final output |
+| `max` | 3840x2160 | 30 | Ultra-high |
+| `auto` | Detected | 24 | Adapts to hardware + duration |
+
+`auto` estimates render time and downgrades if it would take over an hour. Low-memory systems drop to 720p automatically.
+
+### Render times (1080p 24fps, ~180ms/frame/worker)
+
+| Duration | 4 workers | 8 workers | 16 workers |
+|----------|-----------|-----------|------------|
+| 30s | ~3 min | ~2 min | ~1 min |
+| 2 min | ~13 min | ~7 min | ~4 min |
+| 5 min | ~33 min | ~17 min | ~9 min |
+| 10 min | ~65 min | ~33 min | ~17 min |
+
+720p roughly halves these. 4K roughly quadruples them.
+
+## Known pitfalls
+
+**Brightness.** ASCII characters are small bright dots on black. Most frame pixels are background. Linear `* N` multipliers clip highlights and wash out. Use `tonemap()` with per-scene gamma instead. Default gamma 0.75, solarize scenes 0.55, posterize 0.50.
+
+**Render bottleneck.** The per-cell Python loop compositing font bitmaps runs at ~100-150ms/frame. Unavoidable without Cython/C. Everything else must be vectorized numpy. Python for-loops over rows/cols in effect functions will tank performance.
+
+**ffmpeg deadlock.** Never `stderr=subprocess.PIPE` on long-running encodes. Buffer fills at ~64KB, process hangs. Redirect stderr to a file.
+
+**Font cell height.** Pillow's `textbbox()` returns wrong height on macOS. Use `font.getmetrics()` for `ascent + descent`.
+
+**Font compatibility.** Not all Unicode renders in all fonts. Palettes validated at init, blank glyphs silently removed.
+
+## Requirements
+
+◆ Python 3.10+
+◆ NumPy, Pillow, SciPy (audio modes)
+◆ ffmpeg on PATH
+◆ A monospace font (Menlo, Courier, Monaco, auto-detected)
+◆ Optional: OpenCV, ElevenLabs API key (TTS mode)
+
+## File structure
+
+```
+├── SKILL.md                 # Modes, workflow, creative direction
+├── README.md                # This file
+└── references/
+    ├── architecture.md      # Grid system, fonts, palettes, color, _render_vf()
+    ├── effects.md           # Value fields, hue fields, backgrounds, particles
+    ├── shaders.md           # 38 shaders, ShaderChain, tint presets, transitions
+    ├── composition.md       # Blend modes, multi-grid, tonemap, FeedbackBuffer
+    ├── scenes.md            # Scene protocol, SCENES table, render_clip(), examples
+    ├── design-patterns.md   # Layer hierarchy, directional arcs, scene concepts
+    ├── inputs.md            # Audio analysis, video sampling, text, TTS
+    ├── optimization.md      # Hardware detection, vectorized patterns, parallelism
+    └── troubleshooting.md   # Broadcasting traps, blend pitfalls, diagnostics
+```
+
+## Projects built with this
+
+✦ 85-second highlight reel. 15 scenes (14×5s + 15s crescendo finale), randomized order, directional parameter arcs, layer hierarchy composition. Showcases the full effect vocabulary: fBM, voronoi fragmentation, reaction-diffusion, cellular automata, dual counter-rotating spirals, wave collision, domain warping, tunnel descent, kaleidoscope symmetry, boid flocking, fire simulation, glitch corruption, and a 7-layer crescendo buildup.
+
+✦ Audio-reactive music visualizer. 3.5 min, 8 sections with distinct effects, beat-triggered particles and glitch, cycling palettes.
+
+✦ TTS narrated testimonial video. 23 quotes, per-quote ElevenLabs voices, background music at 15% wide stereo, per-clip re-rendering for iterative editing.

package/skills/creative/ascii-video/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: ascii-video
+description: "ASCII video: convert video/audio to colored ASCII MP4/GIF."
+platforms: [linux, macos, windows]
+---
+
+# ASCII Video Production Pipeline
+
+## When to use
+
+Use when users request: ASCII video, text art video, terminal-style video, character art animation, retro text visualization, audio visualizer in ASCII, converting video to ASCII art, matrix-style effects, or any animated ASCII output.
+
+## What's inside
+
+Production pipeline for ASCII art video — any format. Converts video/audio/images/generative input into colored ASCII character video output (MP4, GIF, image sequence). Covers: video-to-ASCII conversion, audio-reactive music visualizers, generative ASCII art animations, hybrid video+audio reactive, text/lyrics overlays, real-time terminal rendering.
+
+## Creative Standard
+
+This is visual art. ASCII characters are the medium; cinema is the standard.
+
+**Before writing a single line of code**, articulate the creative concept. What is the mood? What visual story does this tell? What makes THIS project different from every other ASCII video? The user's prompt is a starting point — interpret it with creative ambition, not literal transcription.
+
+**First-render excellence is non-negotiable.** The output must be visually striking without requiring revision rounds. If something looks generic, flat, or like "AI-generated ASCII art," it is wrong — rethink the creative concept before shipping.
+
+**Go beyond the reference vocabulary.** The effect catalogs, shader presets, and palette libraries in the references are a starting vocabulary. For every project, combine, modify, and invent new patterns. The catalog is a palette of paints — you write the painting.
+
+**Be proactively creative.** Extend the skill's vocabulary when the project calls for it. If the references don't have what the vision demands, build it. Include at least one visual moment the user didn't ask for but will appreciate — a transition, an effect, a color choice that elevates the whole piece.
+
+**Cohesive aesthetic over technical correctness.** All scenes in a video must feel connected by a unifying visual language — shared color temperature, related character palettes, consistent motion vocabulary. A technically correct video where every scene uses a random different effect is an aesthetic failure.
+
+**Dense, layered, considered.** Every frame should reward viewing. Never flat black backgrounds. Always multi-grid composition. Always per-scene variation. Always intentional color.
+
+## Modes
+
+| Mode | Input | Output | Reference |
+|------|-------|--------|-----------|
+| **Video-to-ASCII** | Video file | ASCII recreation of source footage | `references/inputs.md` § Video Sampling |
+| **Audio-reactive** | Audio file | Generative visuals driven by audio features | `references/inputs.md` § Audio Analysis |
+| **Generative** | None (or seed params) | Procedural ASCII animation | `references/effects.md` |
+| **Hybrid** | Video + audio | ASCII video with audio-reactive overlays | Both input refs |
+| **Lyrics/text** | Audio + text/SRT | Timed text with visual effects | `references/inputs.md` § Text/Lyrics |
+| **TTS narration** | Text quotes + TTS API | Narrated testimonial/quote video with typed text | `references/inputs.md` § TTS Integration |
+
+## Stack
+
+Single self-contained Python script per project. No GPU required.
+
+| Layer | Tool | Purpose |
+|-------|------|---------|
+| Core | Python 3.10+, NumPy | Math, array ops, vectorized effects |
+| Signal | SciPy | FFT, peak detection (audio modes) |
+| Imaging | Pillow (PIL) | Font rasterization, frame decoding, image I/O |
+| Video I/O | ffmpeg (CLI) | Decode input, encode output, mux audio |
+| Parallel | concurrent.futures | N workers for batch/clip rendering |
+| TTS | ElevenLabs API (optional) | Generate narration clips |
+| Optional | OpenCV | Video frame sampling, edge detection |
+
+## Pipeline Architecture
+
+Every mode follows the same 6-stage pipeline:
+
+```
+INPUT → ANALYZE → SCENE_FN → TONEMAP → SHADE → ENCODE
+```
+
+1. **INPUT** — Load/decode source material (video frames, audio samples, images, or nothing)
+2. **ANALYZE** — Extract per-frame features (audio bands, video luminance/edges, motion vectors)
+3. **SCENE_FN** — Scene function renders to pixel canvas (`uint8 H,W,3`). Composes multiple character grids via `_render_vf()` + pixel blend modes. See `references/composition.md`
+4. **TONEMAP** — Percentile-based adaptive brightness normalization. See `references/composition.md` § Adaptive Tonemap
+5. **SHADE** — Post-processing via `ShaderChain` + `FeedbackBuffer`. See `references/shaders.md`
+6. **ENCODE** — Pipe raw RGB frames to ffmpeg for H.264/GIF encoding
+
+## Creative Direction
+
+### Aesthetic Dimensions
+
+| Dimension | Options | Reference |
+|-----------|---------|-----------|
+| **Character palette** | Density ramps, block elements, symbols, scripts (katakana, Greek, runes, braille), project-specific | `architecture.md` § Palettes |
+| **Color strategy** | HSV, OKLAB/OKLCH, discrete RGB palettes, auto-generated harmony, monochrome, temperature | `architecture.md` § Color System |
+| **Background texture** | Sine fields, fBM noise, domain warp, voronoi, reaction-diffusion, cellular automata, video | `effects.md` |
+| **Primary effects** | Rings, spirals, tunnel, vortex, waves, interference, aurora, fire, SDFs, strange attractors | `effects.md` |
+| **Particles** | Sparks, snow, rain, bubbles, runes, orbits, flocking boids, flow-field followers, trails | `effects.md` § Particles |
+| **Shader mood** | Retro CRT, clean modern, glitch art, cinematic, dreamy, industrial, psychedelic | `shaders.md` |
+| **Grid density** | xs(8px) through xxl(40px), mixed per layer | `architecture.md` § Grid System |
+| **Coordinate space** | Cartesian, polar, tiled, rotated, fisheye, Möbius, domain-warped | `effects.md` § Transforms |
+| **Feedback** | Zoom tunnel, rainbow trails, ghostly echo, rotating mandala, color evolution | `composition.md` § Feedback |
+| **Masking** | Circle, ring, gradient, text stencil, animated iris/wipe/dissolve | `composition.md` § Masking |
+| **Transitions** | Crossfade, wipe, dissolve, glitch cut, iris, mask-based reveal | `shaders.md` § Transitions |
+
+### Per-Section Variation
+
+Never use the same config for the entire video. For each section/scene:
+- **Different background effect** (or compose 2-3)
+- **Different character palette** (match the mood)
+- **Different color strategy** (or at minimum a different hue)
+- **Vary shader intensity** (more bloom during peaks, more grain during quiet)
+- **Different particle types** if particles are active
+
+### Project-Specific Invention
+
+For every project, invent at least one of:
+- A custom character palette matching the theme
+- A custom background effect (combine/modify existing building blocks)
+- A custom color palette (discrete RGB set matching the brand/mood)
+- A custom particle character set
+- A novel scene transition or visual moment
+
+Don't just pick from the catalog. The catalog is vocabulary — you write the poem.
+
+## Workflow
+
+### Step 1: Creative Vision
+
+Before any code, articulate the creative concept:
+
+- **Mood/atmosphere**: What should the viewer feel? Energetic, meditative, chaotic, elegant, ominous?
+- **Visual story**: What happens over the duration? Build tension? Transform? Dissolve?
+- **Color world**: Warm/cool? Monochrome? Neon? Earth tones? What's the dominant hue?
+- **Character texture**: Dense data? Sparse stars? Organic dots? Geometric blocks?
+- **What makes THIS different**: What's the one thing that makes this project unique?
+- **Emotional arc**: How do scenes progress? Open with energy, build to climax, resolve?
+
+Map the user's prompt to aesthetic choices. A "chill lo-fi visualizer" demands different everything from a "glitch cyberpunk data stream."
+
+### Step 2: Technical Design
+
+- **Mode** — which of the 6 modes above
+- **Resolution** — landscape 1920x1080 (default), portrait 1080x1920, square 1080x1080 @ 24fps
+- **Hardware detection** — auto-detect cores/RAM, set quality profile. See `references/optimization.md`
+- **Sections** — map timestamps to scene functions, each with its own effect/palette/color/shader config
+- **Output format** — MP4 (default), GIF (640x360 @ 15fps), PNG sequence
+
+### Step 3: Build the Script
+
+Single Python file. Components (with references):
+
+1. **Hardware detection + quality profile** — `references/optimization.md`
+2. **Input loader** — mode-dependent; `references/inputs.md`
+3. **Feature analyzer** — audio FFT, video luminance, or synthetic
+4. **Grid + renderer** — multi-density grids with bitmap cache; `references/architecture.md`
+5. **Character palettes** — multiple per project; `references/architecture.md` § Palettes
+6. **Color system** — HSV + discrete RGB + harmony generation; `references/architecture.md` § Color
+7. **Scene functions** — each returns `canvas (uint8 H,W,3)`; `references/scenes.md`
+8. **Tonemap** — adaptive brightness normalization; `references/composition.md`
+9. **Shader pipeline** — `ShaderChain` + `FeedbackBuffer`; `references/shaders.md`
+10. **Scene table + dispatcher** — time → scene function + config; `references/scenes.md`
+11. **Parallel encoder** — N-worker clip rendering with ffmpeg pipes
+12. **Main** — orchestrate full pipeline
+
+### Step 4: Quality Verification
+
+- **Test frames first**: render single frames at key timestamps before full render
+- **Brightness check**: `canvas.mean() > 8` for all ASCII content. If dark, lower gamma
+- **Visual coherence**: do all scenes feel like they belong to the same video?
+- **Creative vision check**: does the output match the concept from Step 1? If it looks generic, go back
+
+## Critical Implementation Notes
+
+### Brightness — Use `tonemap()`, Not Linear Multipliers
+
+This is the #1 visual issue. ASCII on black is inherently dark. **Never use `canvas * N` multipliers** — they clip highlights. Use adaptive tonemap:
+
+```python
+def tonemap(canvas, gamma=0.75):
+    f = canvas.astype(np.float32)
+    lo, hi = np.percentile(f[::4, ::4], [1, 99.5])
+    if hi - lo < 10: hi = lo + 10
+    f = np.clip((f - lo) / (hi - lo), 0, 1) ** gamma
+    return (f * 255).astype(np.uint8)
+```
+
+Pipeline: `scene_fn() → tonemap() → FeedbackBuffer → ShaderChain → ffmpeg`
+
+Per-scene gamma: default 0.75, solarize 0.55, posterize 0.50, bright scenes 0.85. Use `screen` blend (not `overlay`) for dark layers.
+
+### Font Cell Height
+
+macOS Pillow: `textbbox()` returns wrong height. Use `font.getmetrics()`: `cell_height = ascent + descent`. See `references/troubleshooting.md`.
+
+### ffmpeg Pipe Deadlock
+
+Never `stderr=subprocess.PIPE` with long-running ffmpeg — buffer fills at 64KB and deadlocks. Redirect to file. See `references/troubleshooting.md`.
+
+### Font Compatibility
+
+Not all Unicode chars render in all fonts. Validate palettes at init — render each char, check for blank output. See `references/troubleshooting.md`.
+
+### Per-Clip Architecture
+
+For segmented videos (quotes, scenes, chapters), render each as a separate clip file for parallel rendering and selective re-rendering. See `references/scenes.md`.
+
+## Performance Targets
+
+| Component | Budget |
+|-----------|--------|
+| Feature extraction | 1-5ms |
+| Effect function | 2-15ms |
+| Character render | 80-150ms (bottleneck) |
+| Shader pipeline | 5-25ms |
+| **Total** | ~100-200ms/frame |
+
+## References
+
+| File | Contents |
+|------|----------|
+| `references/architecture.md` | Grid system, resolution presets, font selection, character palettes (20+), color system (HSV + OKLAB + discrete RGB + harmony generation), `_render_vf()` helper, GridLayer class |
+| `references/composition.md` | Pixel blend modes (20 modes), `blend_canvas()`, multi-grid composition, adaptive `tonemap()`, `FeedbackBuffer`, `PixelBlendStack`, masking/stencil system |
+| `references/effects.md` | Effect building blocks: value field generators, hue fields, noise/fBM/domain warp, voronoi, reaction-diffusion, cellular automata, SDFs, strange attractors, particle systems, coordinate transforms, temporal coherence |
+| `references/shaders.md` | `ShaderChain`, `_apply_shader_step()` dispatch, 38 shader catalog, audio-reactive scaling, transitions, tint presets, output format encoding, terminal rendering |
+| `references/scenes.md` | Scene protocol, `Renderer` class, `SCENES` table, `render_clip()`, beat-synced cutting, parallel rendering, design patterns (layer hierarchy, directional arcs, visual metaphors, compositional techniques), complete scene examples at every complexity level, scene design checklist |
+| `references/inputs.md` | Audio analysis (FFT, bands, beats), video sampling, image conversion, text/lyrics, TTS integration (ElevenLabs, voice assignment, audio mixing) |
+| `references/optimization.md` | Hardware detection, quality profiles, vectorized patterns, parallel rendering, memory management, performance budgets |
+| `references/troubleshooting.md` | NumPy broadcasting traps, blend mode pitfalls, multiprocessing/pickling, brightness diagnostics, ffmpeg issues, font problems, common mistakes |
+
+---
+
+## Creative Divergence (use only when user requests experimental/creative/unique output)
+
+If the user asks for creative, experimental, surprising, or unconventional output, select the strategy that best fits and reason through its steps BEFORE generating code.
+
+- **Forced Connections** — when the user wants cross-domain inspiration ("make it look organic," "industrial aesthetic")
+- **Conceptual Blending** — when the user names two things to combine ("ocean meets music," "space + calligraphy")
+- **Oblique Strategies** — when the user is maximally open ("surprise me," "something I've never seen")
+
+### Forced Connections
+1. Pick a domain unrelated to the visual goal (weather systems, microbiology, architecture, fluid dynamics, textile weaving)
+2. List its core visual/structural elements (erosion → gradual reveal; mitosis → splitting duplication; weaving → interlocking patterns)
+3. Map those elements onto ASCII characters and animation patterns
+4. Synthesize — what does "erosion" or "crystallization" look like in a character grid?
+
+### Conceptual Blending
+1. Name two distinct visual/conceptual spaces (e.g., ocean waves + sheet music)
+2. Map correspondences (crests = high notes, troughs = rests, foam = staccato)
+3. Blend selectively — keep the most interesting mappings, discard forced ones
+4. Develop emergent properties that exist only in the blend
+
+### Oblique Strategies
+1. Draw one: "Honor thy error as a hidden intention" / "Use an old idea" / "What would your closest friend do?" / "Emphasize the flaws" / "Turn it upside down" / "Only a part, not the whole" / "Reverse"
+2. Interpret the directive against the current ASCII animation challenge
+3. Apply the lateral insight to the visual design before writing code