tuneframes 0.1.0

package/LICENSE

@@ -0,0 +1,199 @@
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,160 @@
+# TuneFrames — Agent-Native Music Generation
+
+**Write music compositions in HTML. Render them to MP3 with one CLI command.**
+
+TuneFrames brings the same portability model that Hyperframes (97K npm downloads/month) proved for video — to audio. Every AI agent, Claude Code session, and workflow tool can now compose music without a single line of native audio code.
+
+```bash
+npx tuneframes init my-track
+cd my-track && npx tuneframes render composition.html
+# Done. my-track/output.mp3 is ready.
+```
+
+---
+
+## How It Works
+
+1. **Write HTML** with Tone.js — same API every web developer already knows
+2. **Add a metadata block** so TuneFrames knows the tempo and duration
+3. **Run `tuneframes render`** — Chromium headless renders the composition offline, FFmpeg encodes to MP3/WAV
+
+```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":"4n"}</div>
+  <script>
+    async function main() {
+      await Tone.start();
+      const synth = new Tone.Synth().toDestination();
+      synth.triggerAttackRelease('C4', '4n', 0);
+      synth.triggerAttackRelease('E4', '4n', Tone.Time('4n').toSeconds());
+      synth.triggerAttackRelease('G4', '4n', Tone.Time('4n').toSeconds() * 2);
+    }
+  </script>
+</body>
+</html>
+```
+
+---
+
+## Examples
+
+| Example | Description | BPM | Duration |
+|---------|-------------|-----|----------|
+| `minimal` | Single synth melody — the simplest possible TuneFrames composition | 120 | 2s |
+| `lofi` | Chord progression, melody, kick and snare — complete lo-fi hip-hop beat | 80 | 10s |
+| `techno` | 4-on-the-floor kick, noise hihat, detuned bass, pad chords | 130 | 2s |
+| `ambient` | Lush reverb pads, crystalline arpeggios — textural ambient | 60 | 2.5s |
+| `orchestral` | Strings, brass, woodwinds in a layered orchestral arrangement | 72 | 2.5s |
+
+Run any example:
+
+```bash
+npx tuneframes render node_modules/tuneframes/examples/example-lofi.html
+```
+
+---
+
+## API Reference
+
+### Metadata Block
+
+Add a `<div id="tuneframes">` to the page body to tell TuneFrames how to render:
+
+```json
+{
+  "bpm": 120,       // Beats per minute (default: 120)
+  "duration": "4n"  // Render duration as Tone.js time (default: "4n")
+}
+```
+
+TuneFrames uses [Tone.js time notation](https://tonejs.github.io/docs/latest/modules/Core.html#Time) — `4n` (quarter note), `2n` (half note), `1n` (whole note), `8n` (eighth note), `16n` (sixteenth note), or any numeric value in seconds.
+
+### `main()` Function
+
+Define an async `main()` function in a `<script>` tag. TuneFrames waits for it to complete, then renders the offline audio buffer.
+
+```js
+async function main() {
+  await Tone.start();
+
+  const synth = new Tone.Synth().toDestination();
+  // Schedule all your notes, chords, and patterns here
+  synth.triggerAttackRelease('C4', '4n', 0);
+  // ...
+}
+```
+
+### Instruments
+
+Tone.js provides a complete instrument library:
+
+- **Synth / MonoSynth / PolySynth** — basic tone generation
+- **MembraneSynth** — kick drums, toms, bass drums
+- **NoiseSynth** — white/pink/brown noise for hi-hats, snares, textures
+- **MetalSynth** — metallic percussion (cymbals, shakers)
+- **Sampler** — load your own WAV/MP3 samples
+
+### Effects
+
+```js
+const reverb = new Tone.Reverb({ decay: 2.5, wet: 0.3 }).toDestination();
+const comp = new Tone.Compressor(-12, 2).toDestination();
+const delay = new Tone.FeedbackDelay('8n', 0.4).toDestination();
+```
+
+---
+
+## CLI
+
+```bash
+# Render a 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 (dev mode with live reload)
+tuneframes preview <file.html>
+
+# Scaffold a new project
+tuneframes init my-track
+```
+
+---
+
+## TuneFrames vs Hyperframes
+
+TuneFrames is the audio sibling of [Hyperframes](https://github.com/cusidoc/hyperframes) — the same portability model, the same agent-first philosophy, but for music instead of video.
+
+| | Hyperframes | TuneFrames |
+|---|---|---|
+| Output | MP4 video | MP3/WAV audio |
+| Framework | Remotion (React) | Tone.js |
+| Use case | Video generation, animation | Music composition, sound design |
+| Deterministic | Yes | Yes |
+
+---
+
+## Architecture
+
+```
+HTML + Tone.js → Chromium (headless, Tone.Offline)
+                → WAV ( PCM 44.1kHz mono )
+                → FFmpeg
+                → MP3 192kbps
+```
+
+**Tone.Offline** is the key: it renders audio without audio hardware or a browser audio context, producing bit-for-bit identical output every time. Same input HTML = same output MP3, guaranteed.
+
+---
+
+## License
+
+Apache 2.0 — use it in any project, commercial or open-source, no strings attached.
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

package/examples/example-ambient.html

@@ -0,0 +1,63 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>TuneFrames — Ambient</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":60,"duration":"1m"}</div>
+  <script>
+    async function main() {
+      await Tone.start();
+      
+      const verb = new Tone.Reverb({ decay: 8, wet: 0.8 }).toDestination();
+      const delay = new Tone.PingPongDelay('4n', 0.3).toDestination();
+      
+      // Warm pad
+      const pad = new Tone.PolySynth(Tone.Synth, {
+        oscillator: { type: 'sine' },
+        envelope: { attack: 3, decay: 1, sustain: 0.8, release: 4 }
+      }).connect(verb);
+      pad.volume.value = -8;
+
+      // Crystal high texture
+      const crystal = new Tone.PolySynth(Tone.Synth, {
+        oscillator: { type: 'sine' },
+        envelope: { attack: 4, decay: 0.5, sustain: 1, release: 3 }
+      }).connect(delay);
+      crystal.volume.value = -18;
+
+      // D minor progression — hypnotic and spacious
+      const chords = [
+        ['D3', 'F3', 'A3'],       // Dm
+        ['C3', 'E3', 'G3'],       // C
+        ['Bb2', 'D3', 'F3'],      // Bb
+        ['A2', 'C3', 'E3'],       // Am
+      ];
+      
+      const beat = Tone.Time('1n').toSeconds();
+      
+      chords.forEach((chord, i) => {
+        pad.triggerAttackRelease(chord, '1n', i * beat);
+        // Add crystal shimmer an octave up, delayed
+        crystal.triggerAttackRelease(
+          chord.map(n => {
+            const octave = parseInt(n.match(/\d/)[0]);
+            return n.replace(/\d/, octave + 1);
+          }),
+          '2n', i * beat + 0.05
+        );
+      });
+
+      // Slow bass drone
+      const drone = new Tone.MonoSynth({
+        oscillator: { type: 'sine' },
+        envelope: { attack: 2, decay: 0, sustain: 1, release: 3 }
+      }).toDestination();
+      drone.volume.value = -20;
+      drone.triggerAttackRelease('D1', '1n', 0);
+      drone.triggerAttackRelease('D1', '1n', beat * 2);
+    }
+  </script>
+</body>
+</html>

package/examples/example-lofi.html

@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>TuneFrames — Lofi Example</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":80,"duration":"1m"}</div>
+  <script>
+    async function main() {
+      await Tone.start();
+      
+      const reverb = new Tone.Reverb({ decay: 4, wet: 0.6 }).toDestination();
+      const pad = new Tone.PolySynth(Tone.Synth, {
+        oscillator: { type: 'triangle' },
+        envelope: { attack: 0.5, decay: 0.3, sustain: 0.8, release: 2 }
+      }).connect(reverb);
+      
+      // Am - F - C - G chord progression
+      const chords = [
+        ['A3', 'C4', 'E4'],
+        ['F3', 'A3', 'C4'],
+        ['C3', 'E3', 'G3'],
+        ['G3', 'B3', 'D4'],
+      ];
+      
+      // Play each chord for 2 beats at 80 BPM
+      for (let i = 0; i < chords.length; i++) {
+        pad.triggerAttackRelease(chords[i], '2n', i * Tone.Time('2n').toSeconds());
+      }
+      
+      // Simple melody
+      const melody = new Tone.Synth({
+        oscillator: { type: 'sine' },
+        envelope: { attack: 0.01, decay: 0.1, sustain: 0.3, release: 0.5 }
+      }).toDestination();
+      
+      melody.triggerAttackRelease('C5', '8n', Tone.Time('2n').toSeconds() * 0.5);
+      melody.triggerAttackRelease('E5', '8n', Tone.Time('2n').toSeconds() * 1.5);
+      melody.triggerAttackRelease('G5', '8n', Tone.Time('2n').toSeconds() * 2.5);
+      melody.triggerAttackRelease('C5', '4n', Tone.Time('2n').toSeconds() * 3.5);
+    }
+  </script>
+</body>
+</html>

package/examples/example-minimal.html

@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>TuneFrames — Minimal Test</title>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/tone/14.8.49/Tone.js"></script>
+</head>
+<body>
+  <script>
+    // This must be a named async function for the renderer to call
+    async function main() {
+      // BPM set in #tuneframes metadata
+      await Tone.start();
+      const synth = new Tone.Synth().toDestination();
+      // Explicitly schedule at transport time 0
+      synth.triggerAttackRelease('C4', '4n', 0);
+    }
+  </script>
+</body>
+</html>

package/examples/example-orchestral.html

@@ -0,0 +1,67 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>TuneFrames — Orchestral</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":72,"duration":"1m"}</div>
+  <script>
+    async function main() {
+      await Tone.start();
+      
+      const verb = new Tone.Reverb({ decay: 6, wet: 0.5 }).toDestination();
+      
+      // Strings section
+      const strings = new Tone.PolySynth(Tone.Synth, {
+        oscillator: { type: 'sawtooth' },
+        envelope: { attack: 1.5, decay: 0.3, sustain: 0.9, release: 3 }
+      }).connect(verb);
+      strings.volume.value = -12;
+
+      // Brass
+      const brass = new Tone.PolySynth(Tone.Synth, {
+        oscillator: { type: 'sawtooth' },
+        envelope: { attack: 0.3, decay: 0.2, sustain: 0.7, release: 1.5 }
+      }).connect(verb);
+      brass.volume.value = -10;
+
+      // Timpani
+      const timpani = new Tone.MembraneSynth({
+        pitchDecay: 0.05,
+        octaves: 4,
+        oscillator: { type: 'sine' },
+        envelope: { attack: 0.001, decay: 1, sustain: 0, release: 2 }
+      }).toDestination();
+      timpani.volume.value = -8;
+
+      const beat = Tone.Time('1n').toSeconds();
+
+      // Strings: swell on every bar
+      const stringChords = [
+        ['D3', 'F3', 'A3', 'C4'],  // Dm7
+        ['C3', 'E3', 'G3', 'B3'],  // Cmaj7
+        ['Bb2', 'D3', 'F3', 'A3'], // Bbmaj7
+        ['A2', 'C3', 'E3', 'G3'],  // Am7
+      ];
+      stringChords.forEach((chord, i) => {
+        strings.triggerAttackRelease(chord, '1n', i * beat);
+      });
+
+      // Brass: enters on bar 3 with fanfare
+      const fanfares = [
+        ['D4', 'F4', 'A4'],
+        ['C4', 'E4', 'G4'],
+      ];
+      fanfares.forEach((chord, i) => {
+        brass.triggerAttackRelease(chord, '2n', (i + 2) * beat);
+      });
+
+      // Timpani: tonic hits on bars 1 and 3
+      timpani.triggerAttackRelease('D2', '1n', 0);
+      timpani.triggerAttackRelease('D2', '1n', beat * 2);
+      timpani.triggerAttackRelease('A1', '2n', beat * 3.5);
+    }
+  </script>
+</body>
+</html>

package/examples/example-techno.html

@@ -0,0 +1,69 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>TuneFrames - Techno</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":130,"duration":"2n"}</div>
+  <script>
+    async function main() {
+      await Tone.start();
+      const beat = Tone.Time('4n').toSeconds();
+
+      const comp = new Tone.Compressor(-18, 5).toDestination();
+      const verb = new Tone.Reverb({ decay: 1, wet: 0.3 }).toDestination();
+
+      // Kick - 4-on-the-floor
+      const kick = new Tone.MembraneSynth({
+        pitchDecay: 0.05, octaves: 6,
+        oscillator: { type: 'sine' },
+        envelope: { attack: 0.001, decay: 0.3, sustain: 0, release: 0.1 }
+      }).connect(comp);
+
+      // Hi-hat: NoiseSynth (white noise + filter envelope)
+      const hihat = new Tone.NoiseSynth({
+        noise: { type: 'white' },
+        envelope: { attack: 0.001, decay: 0.03, sustain: 0, release: 0.01 }
+      }).toDestination();
+      hihat.volume.value = -10;
+
+      // Bass: detuned saws
+      const bass = new Tone.MonoSynth({
+        oscillator: { type: 'sawtooth' },
+        filter: { Q: 3, type: 'lowpass', rolloff: -24 },
+        envelope: { attack: 0.005, decay: 0.15, sustain: 0.5, release: 0.1 },
+        filterEnvelope: { attack: 0.001, decay: 0.1, sustain: 0.3, release: 0.2, baseFrequency: 80, octaves: 4 }
+      }).connect(comp);
+
+      // Pad: parallel saw chords
+      const pad = new Tone.PolySynth(Tone.Synth, {
+        oscillator: { type: 'sawtooth' },
+        envelope: { attack: 0.2, decay: 0.4, sustain: 0.7, release: 0.8 }
+      }).connect(verb);
+      pad.volume.value = -14;
+
+      // Kick: 4-on-the-floor every beat
+      for (let i = 0; i < 8; i++) {
+        kick.triggerAttackRelease('C1', '8n', i * beat);
+      }
+
+      // Hi-hat: offbeat 16ths (16 events)
+      for (let i = 0; i < 16; i++) {
+        hihat.triggerAttackRelease('16n', (i + 0.5) * beat * 0.5);
+      }
+
+      // Bass: syncopated
+      const bassPat = ['E1', 'E1', null, 'G1', 'A1', null, 'B1', 'A1', 'G1', null, 'E1', 'E1'];
+      bassPat.forEach((note, i) => {
+        if (note) bass.triggerAttackRelease(note, '8n', i * beat * 0.5);
+      });
+
+      // Pad: slow chord stabs
+      pad.triggerAttackRelease(['E2', 'G2', 'B2'], '2n', 0);
+      pad.triggerAttackRelease(['C2', 'E2', 'G2'], '2n', beat * 4);
+      pad.triggerAttackRelease(['D2', 'F2', 'A2'], '2n', beat * 6);
+    }
+  </script>
+</body>
+</html>

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "tuneframes",
+  "version": "0.1.0",
+  "description": "Write HTML with Tone.js. Render music to MP3/WAV with one CLI command. Built for AI agents.",
+  "repository": "github:cusidoc/tuneframes",
+  "homepage": "https://github.com/cusidoc/tuneframes#readme",
+  "author": "Nick Shepherd <nick@moltos.org>",
+  "main": "src/cli.js",
+  "bin": {
+    "tuneframes": "src/cli.js"
+  },
+  "scripts": {
+    "render": "node src/render.js",
+    "test": "node src/cli.js render examples/example-minimal.html"
+  },
+  "keywords": ["music", "tone.js", "agent", "hyperframes", "ai"],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "playwright": "^1.40.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cli.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * TuneFrames CLI
+ * 
+ * Commands:
+ *   tuneframes render <file.html> [--output track.mp3]
+ *   tuneframes init <project-name>
+ *   tuneframes preview <file.html>
+ */
+
+const { render } = require('./render');
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+async function main() {
+  const [,, cmd, ...args] = process.argv;
+
+  switch (cmd) {
+    case 'render': {
+      const inputFile = args[0];
+      const outputArg = args.find(a => a.startsWith('--output='));
+      const outputFile = outputArg 
+        ? outputArg.split('=')[1] 
+        : inputFile.replace(/\.html$/, '.mp3');
+
+      if (!inputFile) {
+        console.error('Usage: tuneframes render <file.html> [--output=track.mp3]');
+        process.exit(1);
+      }
+
+      if (!fs.existsSync(inputFile)) {
+        console.error(`File not found: ${inputFile}`);
+        process.exit(1);
+      }
+
+      console.log(`Rendering ${inputFile} → ${outputFile}`);
+      const result = await render(inputFile, outputFile);
+      console.log(`Done. Output: ${result.output}`);
+      break;
+    }
+
+    case 'init': {
+      const [projectName] = args;
+      if (!projectName) {
+        console.error('Usage: tuneframes init <project-name>');
+        process.exit(1);
+      }
+
+      const dir = path.join(process.cwd(), projectName);
+      fs.mkdirSync(dir, { recursive: true });
+      
+      const example = fs.readFileSync(
+        path.join(__dirname, '../examples/example-lofi.html'), 'utf8'
+      );
+      fs.writeFileSync(path.join(dir, 'composition.html'), example);
+      fs.writeFileSync(path.join(dir, 'README.md'), 
+        `# ${projectName}\n\nRun: tuneframes render composition.html\n`);
+      
+      console.log(`Initialized ${projectName}/`);
+      break;
+    }
+
+    case 'preview': {
+      const inputFile = args[0];
+      if (!inputFile) {
+        console.error('Usage: tuneframes preview <file.html>');
+        process.exit(1);
+      }
+      // Open in default browser (or just tell user where the file is)
+      const url = `file://${path.resolve(inputFile)}`;
+      console.log(`Preview: ${url}`);
+      if (process.platform === 'darwin') {
+        spawn('open', [url]);
+      } else if (process.platform === 'linux') {
+        spawn('xdg-open', [url]);
+      }
+      break;
+    }
+
+    default:
+      console.log(`TuneFrames CLI\n\nCommands:\n  tuneframes render <file.html>  Render composition to MP3\n  tuneframes init <name>         Initialize new project\n  tuneframes preview <file.html> Open in browser`);
+  }
+}
+
+main().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/src/render.js

@@ -0,0 +1,138 @@
+const { chromium } = require('playwright');
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const HELPER_SCRIPT = `
+(function() {
+  if (window._helpersInjected) return;
+  window._helpersInjected = true;
+
+  function audioBufferToWav(buffer) {
+    const nc = buffer.numberOfChannels, sr = buffer.sampleRate;
+    const bitDepth = 16, bps = bitDepth / 8, blockAlign = nc * bps;
+    const ns = buffer.length, dataSize = ns * blockAlign;
+    const total = 44 + dataSize;
+    const wav = new ArrayBuffer(total);
+    const view = new DataView(wav);
+    const ws = (v, o, s) => { for (let i = 0; i < s.length; i++) v.setUint8(o + i, s.charCodeAt(i)); };
+    ws(view, 0, 'RIFF'); view.setUint32(4, total - 8, true);
+    ws(view, 8, 'WAVE'); ws(view, 12, 'fmt ');
+    view.setUint32(16, 16, true); view.setUint16(20, 1, true);
+    view.setUint16(22, nc, true); view.setUint32(24, sr, true);
+    view.setUint32(28, sr * blockAlign, true);
+    view.setUint16(32, blockAlign, true); view.setUint16(34, bitDepth, true);
+    ws(view, 36, 'data'); view.setUint32(40, dataSize, true);
+    const ch = []; for (let c = 0; c < nc; c++) ch.push(buffer.getChannelData(c));
+    let off = 44;
+    for (let i = 0; i < ns; i++) {
+      for (let c = 0; c < nc; c++) {
+        const s = Math.max(-1, Math.min(1, ch[c][i]));
+        view.setInt16(off, s < 0 ? s * 0x8000 : s * 0x7fff, true);
+        off += 2;
+      }
+    }
+    return wav;
+  }
+
+  window.audioBufferToWav = audioBufferToWav;
+
+  window.renderComposition = async function(wavPath) {
+    // Wait for Tone.js to be ready
+    let attempts = 0;
+    while (typeof Tone === 'undefined' && attempts < 50) {
+      await new Promise(r => setTimeout(r, 100));
+      attempts++;
+    }
+    if (typeof Tone === 'undefined') throw new Error('Tone not loaded');
+    if (typeof window.audioBufferToWav !== 'function') throw new Error('audioBufferToWav not injected');
+
+    let bpm = 120, duration = '4n';
+    const metaEl = document.getElementById('tuneframes');
+    if (metaEl) {
+      try {
+        const meta = JSON.parse(metaEl.textContent);
+        bpm = meta.bpm || 120;
+        duration = meta.duration || '4n';
+      } catch(e) {}
+    }
+
+    const durationSec = Math.max(Tone.Time(duration).toSeconds() + 0.5, 2);
+    console.log('TuneFrames: rendering', durationSec, 's at BPM', bpm);
+
+    const audioBuffer = await Tone.Offline(async () => {
+      if (typeof main === 'function') await main();
+    }, durationSec, 1, 44100, bpm);
+
+    console.log('TuneFrames: buffer ready', audioBuffer.duration, audioBuffer.length);
+
+    const wavBuf = audioBufferToWav(audioBuffer);
+    console.log('TuneFrames: wav size', wavBuf.byteLength);
+
+    window.writeFile(wavPath, Array.from(new Uint8Array(wavBuf)));
+    console.log('TuneFrames: file written');
+    return wavBuf.byteLength;
+  };
+})();
+`;
+
+async function render(compositionPath, outputPath, format = 'mp3') {
+  const browser = await chromium.launch({ headless: true });
+  const page = await browser.newPage();
+
+  page.on('pageerror', err => console.error('BROWSER ERR:', err.message));
+  page.on('console', msg => console.log('BROWSER:', msg.type(), msg.text()));
+
+  // Inject writeFile bridge BEFORE page load
+  await page.exposeFunction('writeFile', (filePath, arrayBuffer) => {
+    fs.writeFileSync(filePath, Buffer.from(new Uint8Array(arrayBuffer)));
+    console.log('Node writeFile: wrote', arrayBuffer.length, 'bytes to', filePath);
+  });
+
+  // Inject helper scripts as an inline script tag before anything else loads
+  await page.addInitScript({ content: HELPER_SCRIPT });
+
+  await page.goto(`file://${path.resolve(compositionPath)}`, {
+    waitUntil: 'domcontentloaded', timeout: 30000
+  });
+
+  // Wait for Tone.js to actually be available
+  await page.waitForFunction(() => typeof Tone !== 'undefined', { timeout: 15000 });
+  
+  // Also wait for our renderComposition to be defined
+  await page.waitForFunction(() => typeof window.renderComposition === 'function', { timeout: 15000 });
+
+  const wavPath = path.resolve(outputPath.replace(/\.[^.]+$/, '.wav'));
+
+  console.log('Starting render...');
+  const wavSize = await page.evaluate(async (wavPath) => {
+    return await window.renderComposition(wavPath);
+  }, wavPath);
+
+  console.log('Render complete, WAV size:', wavSize);
+  await browser.close();
+
+  if (!fs.existsSync(wavPath)) throw new Error(`WAV not written: ${wavPath}`);
+  const stats = fs.statSync(wavPath);
+  if (stats.size < 1000) throw new Error(`WAV too small: ${stats.size} bytes`);
+  console.log(`WAV on disk: ${stats.size} bytes`);
+
+  if (format === 'mp3') {
+    await new Promise((resolve, reject) => {
+      const ff = spawn('ffmpeg', [
+        '-y', '-hide_banner', '-loglevel', 'error',
+        '-i', wavPath, '-codec:a', 'libmp3lame', '-qscale:a', '2', outputPath
+      ]);
+      ff.on('close', code => {
+        if (code === 0) { fs.unlinkSync(wavPath); resolve(); }
+        else reject(new Error(`FFmpeg exited ${code}`));
+      });
+      ff.on('error', reject);
+    });
+    console.log(`MP3: ${fs.statSync(outputPath).size} bytes`);
+  }
+
+  return { output: outputPath };
+}
+
+module.exports = { render };