tonejs

Files (1)

• SKILL.md

SKILL.md (first lines)

# Tone.js

## When to Use This Skill

Apply when any of the following are needed:

- Playing audio files (SFX, VO, music) alongside GSAP animations
- Beat-synchronized or BPM-locked animation (e.g. scene cuts on the beat)
- Audio-reactive visuals: DOM/SVG elements animated by waveform or frequency data
- Programmatic sound generation (synths, oscillators, UI sounds)
- Adding audio effects (reverb, delay, distortion) to any source

**Related skills:** For timeline sequencing use **gsap-timeline**, for performance use **gsap-performance**, and for scroll-sync use **gsap-scrolltrigger**.

> ⚠️ **Browser Autoplay Policy**: `Tone.start()` MUST be called inside a user-gesture handler (click, keydown, etc.). Audio context will not resume otherwise. Always gate initialization behind an interaction.

---

## Setup

**CDN (vanilla HTML projects):**
```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/tone/14.8.49/Tone.js"></script>
```

**npm / bun:**
```bash
bun add tone
```
```js
import * as Tone from 'tone';
```

**Required initialization (always wrap in user gesture):**
```js
document.getElementById('start-btn').addEventListener('click', async () => {
  await Tone.start();           // Resume AudioContext
  Tone.getTransport().start();  // Start master clock
}, { once: true });
```

---

## Core Architecture

```
Tone.js signal graph
  Source  →  Effect(s)  →  Destination
  Synth       Reverb        toDestination()
  Player      Delay
  Analyser    Distortion
```

All nodes connect via `.connect()` or `.toDestination()` shorthand.

---

## Quick Reference

| Task | API |
|---|---|
| Play a tone | `new Tone.Synth().toDestination().triggerAttackRelease("C4", "8n")` |
| Load + play file | `new Tone.Player(url).toDestination(); player.start()` |
| Add reverb | `const rev = new Tone.Reverb(2).toDestination(); synth.connect(rev)` |
| Schedule on beat | `Tone.getTransport().scheduleRepeat(cb, "4n")` |
| Read waveform | `new Tone.Analyser("waveform", 64).getValue()` |
| Read frequency | `new Tone.Analyser("fft", 32).getValue()` |
| Set BPM | `Tone.getTransport().bpm.value = 120` |
| Sync visual to audio | `Tone.getDraw().schedule(() => { /* gsap here */ }, time)` |
| Stop everything | `Tone.getTransport().stop(); Tone.getTransport().cancel()` |

---

## GSAP Sync: The Right Way

**Problem:** Tone callbacks run on the audio thread. Calling `gsap.to()` directly inside them causes jitter.

**Solution:** Always use `Tone.getDraw().schedule()` to bridge audio events to the visual frame.

```js
// Correct: no jitter
Tone.getTransport().scheduleRepeat((time) => {
  Tone.getDraw().schedule(() => {
    gsap.fromTo('#element', { scale: 1 }, { scale: 1.2, duration: 0.1 });
  }, time);
}, '4n');

// Wrong: triggers on audio thread, causes jitter
Tone.getTransport().scheduleRepeat((time) => {
  gsap.to('#element', { scale: 1.2 }); // DO NOT do this
}, '4n');
```

---

## Audio-Reactive Animation

Wire a `Tone.Analyser` into the GSAP ticker to drive DOM elements in real time:

```js
const analyser = new Tone.Analyser('waveform', 64);
const synth    = new Tone.Synth().connect(analyser).toDestination();

// Pull audio data every animation frame via GSAP ticker
gsap.ticker.add(() => {
  const waveform = analyser.getValue(); // Float32Array, values in [-1, 1]
  const bars = document.querySelectorAll('.bar');

  bars.forEach((bar, i) => {
    const amp = Math.abs(waveform[i] ?? 0);
    gsap.set(bar, { scaleY: 1 + amp * 15 }); // gsap.set: no tween overhead
  });
});

synth.triggerAttackRelease('C3', '1n');
```

> Use `gsap.set()` (not `gsap.to()`) inside `ticker.add()` because creating new tweens every frame is expensive.

From imMamdouhaboammar/motion-graphics-skills, MIT.

More from imMamdouhaboammar/motion-graphics-skills