npm - tuneframes - Versions diffs - 0.1.0 → 0.2.0 - Mend

tuneframes 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (78) hide show

package/LICENSE +167 -199
package/README.md +150 -97
package/examples/example-ai-dj-chill.html +167 -0
package/examples/example-ai-dj-dark.html +167 -0
package/examples/example-ai-dj-energetic.html +167 -0
package/examples/example-ai-dj-happy.html +167 -0
package/examples/example-ai-dj.html +167 -0
package/examples/example-ambient.html +63 -63
package/examples/example-ambient.mp3 +0 -0
package/examples/example-bass.html +48 -0
package/examples/example-lofi.html +45 -45
package/examples/example-lofi.mp3 +0 -0
package/examples/example-minimal.html +21 -19
package/examples/example-minimal.mp3 +0 -0
package/examples/example-orchestral.html +67 -67
package/examples/example-orchestral.mp3 +0 -0
package/examples/example-piano.html +53 -0
package/examples/example-piano.mp3 +0 -0
package/examples/example-techno.html +69 -69
package/examples/example-techno.mp3 +0 -0
package/package.json +42 -24
package/registry/presets/bass-electric.html +67 -0
package/registry/presets/bass-saw.html +22 -0
package/registry/presets/chord-progression.html +22 -0
package/registry/presets/drums-808.html +85 -0
package/registry/presets/drums-lofi.html +35 -0
package/registry/presets/lead-piano.html +26 -0
package/registry/presets/piano-salamander.html +69 -0
package/registry/presets/reverb-warm.html +11 -0
package/registry/samples.json +226 -0
package/skills/audio-ambient/SKILL.md +141 -0
package/skills/audio-ambient/example.html +113 -0
package/skills/audio-boss-battle/SKILL.md +157 -0
package/skills/audio-boss-battle/example.html +185 -0
package/skills/audio-boss-battle/example.mp3 +0 -0
package/skills/audio-chillwave/SKILL.md +142 -0
package/skills/audio-chillwave/example.html +144 -0
package/skills/audio-cinematic/SKILL.md +147 -0
package/skills/audio-cinematic/example.html +123 -0
package/skills/audio-classical/SKILL.md +138 -0
package/skills/audio-classical/example.html +145 -0
package/skills/audio-dnb/SKILL.md +142 -0
package/skills/audio-dnb/example.html +124 -0
package/skills/audio-downtempo/SKILL.md +152 -0
package/skills/audio-downtempo/example.html +164 -0
package/skills/audio-folk/SKILL.md +139 -0
package/skills/audio-folk/example.html +132 -0
package/skills/audio-funk/SKILL.md +149 -0
package/skills/audio-funk/example.html +144 -0
package/skills/audio-future-bass/SKILL.md +163 -0
package/skills/audio-future-bass/example.html +164 -0
package/skills/audio-hip-hop/SKILL.md +133 -0
package/skills/audio-hip-hop/example.html +129 -0
package/skills/audio-house/SKILL.md +147 -0
package/skills/audio-house/example.html +128 -0
package/skills/audio-indie-pop/SKILL.md +150 -0
package/skills/audio-indie-pop/example.html +121 -0
package/skills/audio-jazz/SKILL.md +141 -0
package/skills/audio-jazz/example.html +146 -0
package/skills/audio-lofi/SKILL.md +140 -0
package/skills/audio-lofi/example.html +135 -0
package/skills/audio-minimal/SKILL.md +155 -0
package/skills/audio-minimal/example.html +118 -0
package/skills/audio-orchestral/SKILL.md +156 -0
package/skills/audio-orchestral/example.html +140 -0
package/skills/audio-r-and-b/SKILL.md +134 -0
package/skills/audio-r-and-b/example.html +154 -0
package/skills/audio-r-and-b/example.mp3 +0 -0
package/skills/audio-techno/SKILL.md +140 -0
package/skills/audio-techno/example.html +125 -0
package/skills/audio-trap/SKILL.md +123 -0
package/skills/audio-trap/example.html +119 -0
package/skills/render-retest/example.html +115 -0
package/skills/tuneframes/SKILL.md +221 -0
package/skills/tuneframes-cli/SKILL.md +46 -0
package/skills/verify/example.html +104 -0
package/src/cli.js +261 -89
package/src/render.js +134 -7

package/skills/audio-trap/example.html ADDED Viewed

@@ -0,0 +1,119 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>TuneFrames — Trap</title>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/tone/14.8.49/Tone.js"></script>
+</head>
+<body>
+  <!-- TuneFrames Metadata -->
+  <div id="tuneframes" style="display:none">{"bpm":140,"duration":"12s"}</div>
+  <script>
+    async function main() {
+      await Tone.start();
+      Tone.Transport.bpm.value = 140;
+      // --- MASTER BUS ---
+      const masterLimiter = new Tone.Limiter(-1).toDestination();
+      const masterGain = new Tone.Gain(0.85).connect(masterLimiter);
+      // --- 808 SUB — MembraneSynth with long pitchDecay for the signature glide ---
+      const subSaturate = new Tone.Distortion({ distortion: 0.12, wet: 0.25 }).connect(masterGain);
+      const subGain = new Tone.Gain(1.1).connect(subSaturate);
+      const sub = new Tone.MembraneSynth({
+        pitchDecay: 0.48,   // the 808 "fall" — longer = more dramatic
+        octaves: 3,          // pitch range of the glide
+        envelope: { attack: 0.001, decay: 1.1, sustain: 0, release: 0.5 }
+      }).connect(subGain);
+      // --- SNARE — punchy white noise, dry ---
+      const snareVerb = new Tone.Reverb({ decay: 0.7, wet: 0.18 }).connect(masterGain);
+      const snareGain = new Tone.Gain(0.7).connect(snareVerb);
+      const snare = new Tone.NoiseSynth({
+        noise: { type: "white" },
+        envelope: { attack: 0.001, decay: 0.16, sustain: 0, release: 0.05 }
+      }).connect(snareGain);
+      // --- HI-HAT — very tight, high frequency ---
+      const hatGain = new Tone.Gain(0.42).connect(masterGain);
+      const hat = new Tone.MetalSynth({
+        frequency: 820,
+        envelope: { attack: 0.001, decay: 0.028, release: 0.008 },
+        harmonicity: 5.1,
+        modulationIndex: 32,
+        resonance: 5200,
+        octaves: 2
+      }).connect(hatGain);
+      // --- STRINGS — atmospheric PolySynth, heavy reverb ---
+      const stringsVerb = new Tone.Reverb({ decay: 4.5, wet: 0.65 }).connect(masterGain);
+      const stringsGain = new Tone.Gain(0.5).connect(stringsVerb);
+      const strings = new Tone.PolySynth(Tone.Synth, {
+        oscillator: { type: "sawtooth4" },
+        envelope: { attack: 0.5, decay: 1.2, sustain: 0.65, release: 2.0 },
+        volume: -2
+      }).connect(stringsGain);
+      // --- 808 PATTERN — half-time feel, beat 1 of every bar ---
+      // Pattern: hit on beat 1, ghost on beat 3.5
+      const subPattern = new Tone.Sequence((time, note) => {
+        if (note === "C2") {
+          sub.triggerAttackRelease("C2", "2n", time);
+        } else if (note === "G1") {
+          sub.triggerAttackRelease("G1", "4n", time);
+        }
+      }, ["C2", null, null, null, null, null, "G1", null,
+          "C2", null, null, null, null, null, null, null], "16n");
+      subPattern.start(0);
+      // --- SNARE PATTERN — half-time: beat 3 of the bar (step 8 of 16) ---
+      const snareSeq = new Tone.Sequence((time, val) => {
+        if (val) snare.triggerAttackRelease("16n", time);
+      }, [null, null, null, null, null, null, null, null,
+          1, null, null, null, null, null, null, null], "16n");
+      snareSeq.start(0);
+      // --- HI-HAT ROLLS — the trap signature ---
+      // 32nd-note grid: velocity variation creates rolls and accents
+      // Pattern evolves every bar: starts sparse, builds to dense rolls
+      let hatStep = 0;
+      // Bar 1-2 velocity map: sparse 16th pattern (every 2 32nds)
+      const hatBar1 = [
+        0.8, 0,   0.4, 0,   0.8, 0,   0.4, 0,
+        0.8, 0,   0.4, 0,   0.8, 0.3, 0.9, 0.3
+      ];
+      // Bar 3-4: 16th rolls with triplet accent flurry
+      const hatBar2 = [
+        0.8, 0.3, 0.6, 0.2, 0.8, 0.3, 0.5, 0.2,
+        0.7, 0.3, 0.6, 0.2, 0.9, 0.5, 0.8, 0.5
+      ];
+      // Bar 5-6: dense 32nd roll building to drop
+      const hatBar3 = [
+        0.6, 0.3, 0.7, 0.3, 0.6, 0.4, 0.8, 0.3,
+        0.6, 0.4, 0.7, 0.5, 0.8, 0.6, 0.9, 0.7
+      ];
+      // Merge all bars into one 96-step (6-bar) loop for 32nds at 140bpm
+      const fullHatPattern = [...hatBar1, ...hatBar1, ...hatBar2, ...hatBar2, ...hatBar3, ...hatBar3];
+      const hatSeq = new Tone.Sequence((time, vel) => {
+        if (vel > 0) hat.triggerAttackRelease("32n", time, vel);
+      }, fullHatPattern, "32n");
+      hatSeq.start(0);
+      // --- STRINGS — atmospheric minor chord, enters at bar 3 ---
+      // Cm: C3-Eb3-G3 + high B4 tension note
+      const stringNotes = ["C3", "Eb3", "G3", "Bb3"];
+      strings.triggerAttackRelease(stringNotes, "2m", "2m");
+      // Resolution chord at bar 5
+      strings.triggerAttackRelease(["Ab2", "C3", "Eb3", "G3"], "2m", "4m");
+      strings.triggerAttackRelease(["C3", "Eb3", "G3", "Bb3"], "2m", "6m");
+    }
+    main();
+  </script>
+</body>
+</html>

package/skills/render-retest/example.html ADDED Viewed

@@ -0,0 +1,115 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>TuneFrames — Render Retest</title>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/tone/14.8.49/Tone.js"></script>
+</head>
+<body>
+  <!-- TuneFrames Metadata -->
+  <div id="tuneframes" style="display:none">{"bpm":120,"duration":"10s"}</div>
+  <script>
+    async function main() {
+      await Tone.start();
+      // 120 BPM: quarter note = 0.5s, bar = 2.0s, 10s = 5 bars exactly.
+      // All note times are absolute seconds from 0. No Tone.now(), no Transport.start().
+      const beat = 0.5;
+      const bar  = 2.0;
+      // --- MASTER BUS ---
+      const limiter    = new Tone.Limiter(-1).toDestination();
+      const masterGain = new Tone.Gain(0.82).connect(limiter);
+      // --- REVERB connected to master ---
+      const reverb = new Tone.Reverb({ decay: 2.5, wet: 0.30 }).connect(masterGain);
+      // --- DELAY connected to master (parallel with reverb, not chained) ---
+      const delay = new Tone.FeedbackDelay(beat * 0.5, 0.25).connect(masterGain);
+      // --- KICK (MembraneSynth) ---
+      const kickGain = new Tone.Gain(0.88).connect(masterGain);
+      const kick = new Tone.MembraneSynth({
+        pitchDecay: 0.06,
+        octaves: 9,
+        envelope: { attack: 0.001, decay: 0.34, sustain: 0, release: 0.1 }
+      }).connect(kickGain);
+      // --- HI-HAT (MetalSynth) ---
+      // MetalSynth.triggerAttackRelease(duration, time, velocity) -- no pitch arg
+      const hatGain = new Tone.Gain(0.36).connect(masterGain);
+      const hat = new Tone.MetalSynth({
+        frequency: 440,
+        envelope: { attack: 0.001, decay: 0.05, release: 0.01 },
+        harmonicity: 5.1,
+        modulationIndex: 32,
+        resonance: 4000,
+        octaves: 1.5
+      }).connect(hatGain);
+      // --- CHORDS (PolySynth) through reverb ---
+      const padGain = new Tone.Gain(0.60).connect(reverb);
+      const pad = new Tone.PolySynth(Tone.Synth, {
+        oscillator: { type: "sine" },
+        envelope: { attack: 0.40, decay: 0.5, sustain: 0.60, release: 1.8 },
+        volume: -8
+      }).connect(padGain);
+      // --- MELODY (Synth) through delay + reverb ---
+      const melGain = new Tone.Gain(0.72).connect(delay);
+      melGain.connect(reverb);
+      const mel = new Tone.Synth({
+        oscillator: { type: "triangle" },
+        envelope: { attack: 0.012, decay: 0.20, sustain: 0.45, release: 0.65 },
+        volume: -5
+      }).connect(melGain);
+      // --- KICK: 4-on-the-floor, every 0.5s, 20 hits, last at 9.5s ---
+      for (let i = 0; i < 20; i++) {
+        kick.triggerAttackRelease("C1", "8n", i * beat);
+      }
+      // --- HI-HAT: 8th notes every 0.25s, on-beat louder, 40 hits, last at 9.75s ---
+      for (let i = 0; i < 40; i++) {
+        const vel = (i % 2 === 0) ? 0.60 : 0.35;
+        hat.triggerAttackRelease("16n", i * (beat * 0.5), vel);
+      }
+      // --- CHORDS: Dm -> Bb -> F -> C, one bar each, enter at bar 2 (2s) ---
+      // "1n" = whole note = 2.0s at 120 BPM = exactly one bar
+      const progression = [
+        { notes: ["D2","F2","A2"], time: bar       },  // Dm @ 2s
+        { notes: ["Bb2","D3","F3"], time: bar * 2  },  // Bb @ 4s
+        { notes: ["F2","A2","C3"], time: bar * 3   },  // F  @ 6s
+        { notes: ["C3","E3","G3"], time: bar * 4   },  // C  @ 8s
+      ];
+      progression.forEach(({ notes, time }) => {
+        pad.triggerAttackRelease(notes, "1n", time);
+      });
+      // --- MELODY: D minor pentatonic, enters at bar 3 (4s), last note at 9.0s ---
+      const melody = [
+        { note: "F4", dur: "4n", t: 4.0 },
+        { note: "E4", dur: "8n", t: 4.5 },
+        { note: "D4", dur: "4n", t: 5.0 },
+        { note: "A4", dur: "4n", t: 5.5 },
+        { note: "G4", dur: "2n", t: 6.0 },
+        { note: "F4", dur: "4n", t: 7.0 },
+        { note: "E4", dur: "8n", t: 7.5 },
+        { note: "D4", dur: "4n", t: 8.0 },
+        { note: "F4", dur: "8n", t: 8.5 },
+        { note: "A4", dur: "4n", t: 9.0 },
+      ];
+      melody.forEach(({ note, dur, t }) => {
+        mel.triggerAttackRelease(note, dur, t);
+      });
+      // NOTE: do NOT call Tone.Transport.start() here.
+      // Tone.Offline manages the transport internally.
+    }
+    main();
+  </script>
+</body>
+</html>

package/skills/tuneframes/SKILL.md ADDED Viewed

@@ -0,0 +1,221 @@
+---
+name: tuneframes
+description: Write music compositions in HTML using Tone.js. Use when asked to create music, audio, sound effects, beats, or any audio generation task.
+---
+# TuneFrames
+Open-source music generation: write HTML with Tone.js, render to MP3 with one CLI command. Built for AI agents — no native audio code, no per-render fees, fully deterministic.
+## When to Use This Skill
+- User asks for music, a beat, soundtrack, sound effects, or audio
+- User describes a musical mood (lofi, ambient, techno, orchestral) and wants output
+- User wants audio for a video, game, or application
+- User wants to generate music programmatically in an automated pipeline
+## Core Authoring Pattern
+Every TuneFrames composition is a single HTML file:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/tone/14.8.49/Tone.js"></script>
+</head>
+<body>
+  <div id="tuneframes" style="display:none">{"bpm":120,"duration":"4s"}</div>
+  <script>
+    async function main() {
+      await Tone.start();
+      const synth = new Tone.Synth().toDestination();
+      synth.triggerAttackRelease('C4', '4n', 0);
+    }
+  </script>
+</body>
+</html>
+```
+## Metadata Block
+```html
+<div id="tuneframes" style="display:none">{"bpm":120,"duration":"4s"}</div>
+```
+- **bpm**: beats per minute (default: 120)
+- **duration**: render length in **seconds** — use `"4s"`, `"10s"`, etc. Do NOT use Tone.js note values like `"4n"` for duration (see warning below)
+## The `main()` Function Rules
+1. Must be `async function main()`
+2. Must start with `await Tone.start()`
+3. All notes are scheduled relative to transport time 0
+4. Tone.Offline renders deterministically — same HTML = identical MP3 every time
+## Instruments
+```js
+// Basic tone generation
+const synth = new Tone.Synth().toDestination();
+const mono = new Tone.MonoSynth().toDestination();
+const poly = new Tone.PolySynth(Tone.Synth).toDestination();
+// Drums
+const kick = new Tone.MembraneSynth().toDestination();     // Kick drum
+const noise = new Tone.NoiseSynth().toDestination();        // Hi-hats, snares
+// Effects
+const reverb = new Tone.Reverb({ decay: 2.5, wet: 0.3 }).toDestination();
+const delay = new Tone.FeedbackDelay('8n', 0.4).toDestination();
+const comp = new Tone.Compressor(-12, 2).toDestination();
+const chorus = new Tone.Chorus(4, 2.5, 0.5).toDestination();
+```
+## Common Patterns
+**Note timing:**
+```js
+const beat = Tone.Time('4n').toSeconds();
+synth.triggerAttackRelease('C4', '4n', 0);          // Beat 1
+synth.triggerAttackRelease('E4', '4n', beat);        // Beat 2
+synth.triggerAttackRelease('G4', '4n', beat * 2);   // Beat 3
+synth.triggerAttackRelease('C5', '4n', beat * 3);   // Beat 4
+```
+**Chord progression:**
+```js
+const pad = new Tone.PolySynth(Tone.Synth).toDestination();
+const chords = [
+  ['D3','F3','A3'],  // Dm
+  ['C3','E3','G3'],  // C
+  ['Bb2','D3','F3'], // Bb
+  ['A2','C3','E3'],  // Am
+];
+const measure = Tone.Time('1n').toSeconds();
+chords.forEach((chord, i) => {
+  pad.triggerAttackRelease(chord, '1n', i * measure);
+});
+```
+**Drum pattern:**
+```js
+const kick = new Tone.MembraneSynth().toDestination();
+const snare = new Tone.NoiseSynth().toDestination();
+const beat = Tone.Time('4n').toSeconds();
+for (let i = 0; i < 4; i++) {
+  kick.triggerAttackRelease('C1', '4n', i * beat);              // Kick on 1-4
+  snare.triggerAttackRelease('C3', '4n', (i + 0.5) * beat);   // Snare on 2,4
+}
+```
+**Lofi beat (full example):**
+```js
+const kick = new Tone.MembraneSynth().toDestination();
+const snare = new Tone.NoiseSynth().toDestination();
+const hihat = new Tone.NoiseSynth().toDestination();
+const piano = new Tone.PolySynth(Tone.Synth).toDestination();
+const reverb = new Tone.Reverb({ decay: 1.5, wet: 0.4 }).toDestination();
+const beat = Tone.Time('4n').toSeconds();
+const bar = beat * 4;
+// Kick: four on the floor
+for (let i = 0; i < 4; i++) kick.triggerAttackRelease('C1', '4n', i * beat);
+// Snare: 2 and 4
+[1, 3].forEach(i => snare.triggerAttackRelease('C3', '4n', i * beat));
+// Hi-hat: eighth notes, quiet
+hihat.volume.value = -12;
+for (let i = 0; i < 8; i++) hihat.triggerAttackRelease('16n', i * beat * 0.5);
+// Piano: chord progression
+const progression = [['D3','F3','A3'],['C3','E3','G3']];
+progression.forEach((chord, i) => {
+  piano.connect(reverb);
+  piano.triggerAttackRelease(chord, '2n', i * bar);
+});
+```
+## ⚠️ Duration Warning
+**Use literal seconds (`"4s"`, `"10s"`) for the metadata duration.**
+Tone.js note notation (`4n`, `2n`, `1n`) is a fraction of a whole note at the given BPM:
+- `1n` = 1 whole note = 4 beats → at 120 BPM, 1n = 2.0s
+- `2n` = 1/2 whole note = 2 beats → at 120 BPM, 2n = 1.0s
+- `4n` = 1/4 whole note = 1 beat → at 120 BPM, 4n = 0.5s
+- `8n` = 1/8 whole note = 1/2 beat → at 120 BPM, 8n = 0.25s
+This is a common source of clipped renders. Always use seconds in the metadata block.
+## CLI Reference
+```bash
+tuneframes render <file.html> [--output <out.mp3>]  # Render to MP3
+tuneframes render <file.html> --format wav [--output <out.wav>]
+tuneframes preview <file.html>   # Live preview in browser
+tuneframes init <name>          # Scaffold new project
+```
+---
+# TuneFrames — Sample Instruments
+Extends the core TuneFrames skill with real instrument samples via CDN.
+## Sample Pattern (Tone.Sampler + gleitz CDN)
+Every sample composition must:
+1. Create Tone.Sampler instances with CDN baseUrl
+2. Call `await Tone.loaded()` before scheduling any notes
+3. Then schedule all notes using the loaded sampler
+```js
+async function main() {
+  await Tone.start();
+  // Load piano from CDN
+  const piano = new Tone.Sampler({
+    urls: { A4: 'A4.mp3', C4: 'C4.mp3', 'F#4': 'Fs4.mp3', A5: 'A5.mp3' },
+    baseUrl: 'https://gleitz.github.io/midi-js-soundfonts/FluidR3_GM/acoustic_grand_piano-mp3/'
+  }).toDestination();
+  // CRITICAL: wait for samples to load before scheduling
+  await Tone.loaded();
+  // Now schedule notes
+  piano.triggerAttackRelease('C4', '4n', 0);
+  piano.triggerAttackRelease('E4', '4n', '4n');
+  piano.triggerAttackRelease('G4', '2n', '2n');
+}
+```
+## Available Instruments (gleitz FluidR3_GM)
+Full registry: `registry/samples.json` — includes all URL mappings and per-instrument notes.
+| Key | CDN path suffix | Category | Best range |
+|-----|----------------|----------|------------|
+| `acoustic_grand_piano` | `acoustic_grand_piano-mp3` | Piano | A0–C8 |
+| `acoustic_bass` | `acoustic_bass-mp3` | Bass | C1–C4 |
+| `string_ensemble_1` | `string_ensemble_1-mp3` | Strings | C2–C7 |
+| `brass_section` | `brass_section-mp3` | Brass | C2–C6 |
+| `acoustic_guitar_nylon` | `acoustic_guitar_nylon-mp3` | Guitar | Fs2–C6 |
+| `vibraphone` | `vibraphone-mp3` | Mallet | C3–C7 |
+| `flute` | `flute-mp3` | Woodwind | C4–A7 |
+| `choir_aahs` | `choir_aahs-mp3` | Choir | C3–G5 |
+CDN base: `https://gleitz.github.io/midi-js-soundfonts/FluidR3_GM/{instrument}-mp3/`
+Sharp notes use `s` suffix in filenames: F#4 → `Fs4.mp3`, D#3 → `Ds3.mp3`.
+## Presets
+Ready-to-render compositions in `registry/presets/`:
+- `piano-salamander.html` — Am–F–C–G chord progression, acoustic grand piano, 8s
+- `drums-808.html` — Trap 808 pattern, MembraneSynth + MetalSynth (no CDN), 7s
+- `bass-electric.html` — Walking bass line in C minor, acoustic bass, 6s

package/skills/tuneframes-cli/SKILL.md ADDED Viewed

@@ -0,0 +1,46 @@
+---
+name: tuneframes-cli
+description: CLI commands for TuneFrames — render, preview, init, validate. Load this skill when working with the tuneframes CLI.
+---
+# TuneFrames CLI
+## Commands
+```bash
+# Render composition to MP3
+tuneframes render <file.html> [--output <out.mp3>]
+# Render to WAV (no re-encoding)
+tuneframes render <file.html> --format wav [--output <out.wav>]
+# Preview in browser (live reload)
+tuneframes preview <file.html>
+# Scaffold a new project
+tuneframes init my-track
+# Validate a composition (headless render test)
+tuneframes validate <file.html>
+```
+## Rendering Pipeline
+```
+HTML + Tone.js → Chromium (headless, Tone.Offline)
+                → WAV (PCM 44.1kHz mono)
+                → FFmpeg
+                → MP3 192kbps
+```
+Tone.Offline renders without audio hardware. Same input HTML = identical output MP3. This is what makes TuneFrames safe for automated pipelines.
+## Requirements
+- Node.js >= 18
+- FFmpeg (install via: `apt install ffmpeg` or `brew install ffmpeg`)
+## Output Locations
+Default: input file's directory with same basename, `.mp3` extension.
+`--output` flag overrides: `tuneframes render in.html --output /tmp/out.mp3`

package/skills/verify/example.html ADDED Viewed

@@ -0,0 +1,104 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>TuneFrames — Verify</title>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/tone/14.8.49/Tone.js"></script>
+</head>
+<body>
+  <div id="tuneframes" style="display:none">{"bpm":120,"duration":"10s"}</div>
+  <script>
+// Verify — upbeat electronic, C major, I-vi-IV-V-I arc. "System checked out: PASS."
+//
+// Instrument choices follow confirmed-working pattern (techno/lofi examples):
+//   - Tone.Reverb without await  — generate() resolves before startRendering() inside Offline
+//   - Tone.MembraneSynth kick    — confirmed working in example-techno.html
+//   - Tone.NoiseSynth hi-hat     — confirmed working; MetalSynth fails inside Tone.Offline
+//     (MetalSynth's FM oscillators use sustain:0 early-stop scheduling which creates
+//      a state-timeline ordering conflict on re-trigger in the Offline context)
+//   - main() NOT called from HTML — render.js calls it inside Tone.Offline()
+async function main() {
+  await Tone.start();
+  const beat = Tone.Time('4n').toSeconds();  // 0.5s at 120 BPM
+  const bar  = beat * 4;                     // 2.0s
+  // Effects
+  const reverb = new Tone.Reverb({ decay: 2.2, wet: 0.28 }).toDestination();
+  const delay  = new Tone.FeedbackDelay({ delayTime: beat, feedback: 0.28, wet: 0.22 }).toDestination();
+  // Chord pad — PolySynth(Synth) → reverb
+  const pad = new Tone.PolySynth(Tone.Synth, {
+    oscillator: { type: 'triangle' },
+    envelope: { attack: 0.08, decay: 0.40, sustain: 0.60, release: 1.20 }
+  }).connect(reverb);
+  pad.volume.value = -10;
+  // Melody — Synth → delay
+  const mel = new Tone.Synth({
+    oscillator: { type: 'sawtooth' },
+    envelope: { attack: 0.01, decay: 0.15, sustain: 0.40, release: 0.30 }
+  }).connect(delay);
+  mel.volume.value = -9;
+  // Kick — MembraneSynth
+  const kick = new Tone.MembraneSynth({
+    pitchDecay: 0.05,
+    octaves: 6,
+    oscillator: { type: 'sine' },
+    envelope: { attack: 0.001, decay: 0.28, sustain: 0, release: 0.08 }
+  }).toDestination();
+  kick.volume.value = -5;
+  // Hi-hat — NoiseSynth (white noise burst, similar timbre to metallic hat)
+  // NoiseSynth works inside Tone.Offline; MetalSynth does not in v14.8.49
+  const hihat = new Tone.NoiseSynth({
+    noise: { type: 'white' },
+    envelope: { attack: 0.001, decay: 0.05, sustain: 0, release: 0.01 }
+  }).toDestination();
+  hihat.volume.value = -16;
+  // Kick: 4-on-the-floor, 20 hits across 10s
+  for (var i = 0; i < 20; i++) {
+    kick.triggerAttackRelease('C1', '8n', i * beat);
+  }
+  // Hi-hat: off-beat 8th notes, 19 hits
+  for (var j = 0; j < 19; j++) {
+    var vel = j % 2 === 0 ? 0.60 : 0.32;
+    hihat.triggerAttackRelease('16n', beat * 0.5 + j * beat, vel);
+  }
+  // Chords: I-vi-IV-V-I (C-Am-F-G-C), one per bar
+  [
+    { notes: ['C4', 'E4', 'G4'], t: bar * 0 },
+    { notes: ['A3', 'C4', 'E4'], t: bar * 1 },
+    { notes: ['F3', 'A3', 'C4'], t: bar * 2 },
+    { notes: ['G3', 'B3', 'D4'], t: bar * 3 },
+    { notes: ['C4', 'E4', 'G4'], t: bar * 4 },
+  ].forEach(function(c) {
+    pad.triggerAttackRelease(c.notes, '1n', c.t);
+  });
+  // Melody: question phrase (bars 2-3), answer resolves to tonic (bars 4-5)
+  var e = beat * 0.5;  // eighth-note duration
+  [
+    [bar + beat * 0, 'E5', e],
+    [bar + beat * 1, 'G5', e],
+    [bar + beat * 2, 'A5', beat],
+    [bar * 2 + beat * 0, 'G5', e],
+    [bar * 2 + beat * 1, 'F5', e],
+    [bar * 2 + beat * 2, 'E5', beat],
+    [bar * 3 + beat * 0, 'D5', e],
+    [bar * 3 + beat * 1, 'E5', e],
+    [bar * 3 + beat * 2, 'F5', e],
+    [bar * 3 + beat * 3, 'G5', e],
+    [bar * 4, 'C5', beat * 3],
+  ].forEach(function(n) {
+    mel.triggerAttackRelease(n[1], n[2], n[0]);
+  });
+}
+  </script>
+</body>
+</html>