` with valid JSON is required — the renderer reads BPM and duration from it
- `duration` is **literal seconds only** — `"16s"` not `"16n"` (see Gotchas)
- `async function main()` must start with `await Tone.start()`
- Schedule all notes at absolute times in seconds (or convert with `Tone.Time('2n').toSeconds()`)
---
## Skill Gallery
Install the full skill pack with: `npx skills add shepherd217/tuneframes`
Each skill ships with a BPM range, characteristic chord progressions, drum patterns, and a verified example composition.
| Genre | BPM Range |
|-------|-----------|
| ambient | 50–70 |
| boss-battle | 150–185 |
| chillwave | 90–110 |
| cinematic | 60–90 |
| classical | 80–140 |
| dnb | 165–180 |
| downtempo | 70–90 |
| folk | 80–110 |
| funk | 95–115 |
| future-bass | 140–160 |
| hip-hop | 80–95 |
| house | 120–128 |
| indie-pop | 115–140 |
| jazz | 60–240 |
| lofi | 70–90 |
| minimal | 128–135 |
| orchestral | 60–120 |
| r-and-b | 70–95 |
| techno | 130–145 |
| trap | 130–160 |
---
## Critical Gotchas
Four things that silently break agent-generated compositions:
**1. Duration is literal seconds, not note values.**
`"duration":"4n"` in the metadata block is not 4 beats. In Tone.js, `4n` means "quarter note fraction" — at 120 BPM that's 0.5 seconds. Always write `"duration":"16s"`.
**2. Reverb, Freeverb, BitCrusher, and Chebyshev are stubbed.**
These effects use AudioWorklet, which fails in headless Chromium. The renderer replaces them with passthrough `Gain` nodes automatically — sound plays through dry, wet effect is silently dropped. Use `FeedbackDelay` or `Chorus` instead.
**3. Schedule notes chronologically per instrument.**
Tone.js's `StateTimeline` requires that `triggerAttackRelease` calls on the same instrument are in non-decreasing time order. Scheduling `t=1.5` after `t=2.0` on the same synth throws:
```
Error: The time must be greater than or equal to the last scheduled time
```
Collect all hit times in an array, sort ascending, then schedule.
**4. CDN samples require the TUNEFRAMES_READY pattern.**
The renderer awaits `window.TUNEFRAMES_READY` before calling `Tone.Offline()`. When using `Tone.Sampler` with CDN URLs, set this to a Promise that resolves once samples are buffered:
```javascript
window.TUNEFRAMES_READY = (async () => {
// pre-fetch and decode samples into window._myBuffers
// then wrap with new Tone.ToneAudioBuffer(audioBuffer) inside Offline
})();
```
Do not use `await Tone.loaded()` inside `Tone.Offline()` — it checks a list that may be empty at call time, causing a race condition that silently drops samples.
---
## CLI Reference
```
tuneframes render
Render composition to MP3
tuneframes init Initialize a new project with a lofi starter composition
tuneframes preview Open in browser for live preview
tuneframes validate Headless test render — confirms audio output > 5 KB
tuneframes lint Static HTML analysis — no render needed
tuneframes instruments List all 128 GM instruments available via the gleitz CDN
tuneframes install Show setup guide for drum/piano/bass sample packs
```
**render options:**
```bash
tuneframes render track.html --output track.mp3
tuneframes render track.html --output track.wav --format wav
tuneframes render track.html --timeout 120 # seconds (default: 60)
```
---
## Requirements
- Node.js 18+
- FFmpeg — `brew install ffmpeg` or `apt install ffmpeg`
Playwright Chromium is bundled — no separate browser install needed.
---
## Contributing
To add a new genre skill:
1. Create `skills/audio-/SKILL.md` with BPM range, characteristic progressions, and instrument config
2. Create `skills/audio-/example.html` — a complete, renderable composition
3. Validate it: `tuneframes validate skills/audio-/example.html`
4. Submit a PR
The `example.html` must pass validate (render to > 5 KB) before the PR can merge. That's the only gate.
---
## See Also
- [Hyperframes](https://github.com/Shepherd217/Hyperframes) — the video counterpart: write HTML with GSAP/Three.js, render to MP4
---
## License
Apache 2.0