Skip to content
Skills Library
Programming · Building & coding

audio-implementation

/audio-implementation

Use when implementing audio features, adding new instruments, or modifying Tone.js synthesis - ensures proper resource management, prevents memory leaks, and maintains consistent audio quality

Licence
MIT
Last repository change
21.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when implementing audio features, adding new instruments, or modifying Tone.js synthesis - ensures proper resource management, prevents memory leaks, and maintains consistent audio quality

Original author description

Use when implementing audio features, adding new instruments, or modifying Tone.js synthesis - ensures proper resource management, prevents memory leaks, and maintains consistent audio quality

How it works

  1. Overview
  2. When to Use
  3. Audio Architecture
  4. Playing Notes
  5. Instrument Profiles
  6. Common Patterns
  7. Anti-Patterns
  8. Debugging Audio Issues
  9. Testing Audio
  10. Multiple Audio Sources (Tone.js + alphaTab)
Original SKILL.md headings · 323 lines, 1,010 words
SKILL.md preview
---
name: audio-implementation
description: Use when implementing audio features, adding new instruments, or modifying Tone.js synthesis - ensures proper resource management, prevents memory leaks, and maintains consistent audio quality
---

# Audio Implementation with Tone.js

## Overview

Audio in this project uses Tone.js for synthesis. Improper handling causes memory leaks, audio glitches, and browser crashes.

**Core principle:** Initialize once, reuse always, dispose completely.

## When to Use

- Adding audio playback features
- Creating new instrument sounds
- Modifying audio effects chains
- Fixing audio-related bugs
- Adding new play modes (arpeggios, chords, etc.)

## Audio Architecture

### Current Instruments

**Bass Guitar** (FretboardComponent):
```
FMSynth → EQ3 → Compressor → Reverb → Volume → Destination
```

**Piano** (KeyboardComponent):
```
PolySynth(Synth) → Reverb → Volume → Destination
```

### Initialization Pattern

```typescript
private synth: Tone.PolySynth | null = null;
private reverb: Tone.Reverb | null = null;
private volume: Tone.Volume | null = null;

async initAudio(): Promise<void> {
  // Start audio context (REQUIRED - needs user gesture)
  await Tone.start();

  // Create effects chain (end to start)
  this.volume = new Tone.Volume(-6).toDestination();
  this.reverb = new Tone.Reverb({ decay: 2.5 }).connect(this.volume);

  // Wait for reverb to generate IR
  await this.reverb.ready;

  // Create synth and connect
  this.synth = new Tone.PolySynth(Tone.Synth).connect(this.reverb);

  // Configure synth
  this.synth.set({
    oscillator: { type: 'sine' },
    envelope: {
      attack: 0.005,
      decay: 0.3,
      sustain: 0.2,
      release: 1.5
    }
  });
}
```

### Disposal Pattern (CRITICAL)

```typescript
ngOnDestroy(): void {
  // Dispose in reverse order of creation
  this.synth?.dispose();
  this.reverb?.dispose();
  this.volume?.dispose();

  // Null out references
  this.synth = null;
  this.reverb = null;
  this.volume = null;
}
```

## Playing Notes

### Single Note
```typescript
playNote(noteName: string, duration: string = '8n'): void {
  if (!this.synth) return;

  // triggerAttackRelease handles timing automatically
  this.synth.triggerAttackRelease(noteName, duration);
}
```

### Note with Octave
```typescript
// Convert note value (0-11) and octave to Tone.js format
const noteName = `${CHROMATIC_SHARPS[noteValue]}${octave}`;  // e.g., "C4", "F#3"
this.synth.triggerAttackRelease(noteName, '8n');
```

### Sequence of Notes (Arpeggio)
```typescript
playScale(notes: string[], tempo: number = 120): void {
  const now = Tone.now();
  const noteDuration = 60 / tempo;  // seconds per beat

  notes.forEach((note, index) => {
    this.synth?.triggerAttackRelease(
      note,
      '8n',
      now + (index * noteDuration)
    );
  });
}
```

### Chord (Simultaneous Notes)
```typescript
playChord(notes: string[], duration: string = '2n'): void {
  if (!this.synth) return;

  // PolySynth handles multiple simultaneous notes
  this.synth.triggerAttackRelease(notes, duration);
}
```

## Instrument Profiles

### Bass Sound
```typescript
const bassSynth = new Tone.FMSynth({
  harmonicity: 0.25,
  modulationIndex: 8,
  oscillator: { type: 'sine' },
  envelope: {
    attack: 0.01,
    decay: 0.2,
    sustain: 0.8,
    release: 0.5
  },
  modulation: { type: 'sine' },
  modulationEnvelope: {
    attack: 0.01,
    decay: 0.2,
    sustain: 0.5,
    release: 0.5
  }
});

const bassEQ = new Tone.EQ3({
  low: 8,      // Boost bass frequencies
  mid: -2,     // Slight mid cut
  high: -8     // Cut highs for warmth
});

const bassCompressor = new Tone.Compressor({
  ratio: 8,
  threshold: -24,
  attack: 0.003,
  release: 0.25
});
```

### Piano Sound
```typescript
const pianoSynth = new Tone.PolySynth(Tone.Synth, {
  oscillator: { type: 'sine' },
  envelope: {
    attack: 0.005,
    decay: 0.3,
    sustain: 0.2,
    release: 1.5
  }
});

const pianoReverb = new Tone.Reverb({
  decay: 2.5,
  wet: 0.3
});
```

### Guitar Sound (if adding)
```typescript
const guitarSynth = new Tone.PluckSynth({
  attackNoise: 1.5,
  dampening: 4000,
  resonance: 0.95,
  release: 1.2
});
```

## Common Patterns

### User Gesture Requirement
```typescript
// Audio context starts suspended - MUST have user interaction
async handleFirstInteraction(): Promise<void> {
  if (Tone.context.state !== 'running') {
    await Tone.start();
  }
}

// Attach to click handler
<button (click)="handleFirstInteraction(); playNote('C4')">Play</button>
```

### Visual Feedback with Audio
```typescript
playNoteWithFeedback(noteIndex: number, noteName: string): void {
  // Visual highlight
  this.currentlyPlayingPosition = noteIndex;

  // Play audio
  this.synth?.triggerAttackRelease(noteName, '8n');

  // Clear highlight after duration
  setTimeout(() => {
    this.currentlyPlayingPosition = null;
  }, 300);
}
```

### Volume Control
```typescript
setVolume(db: number): void {
  if (this.volume) {
    this.volume.volume.value = db;  // -60 to 0, where 0 is max
  }
}

mute(): void {
  if (this.volume) {
    this.volume.mute = true;
  }
}
```

## Anti-Patterns

| Anti-Pattern | Problem | Correct Approach |
|--------------|---------|------------------|
| `new Tone.Synth()` per note | Memory leak, audio glitches | Initialize once, reuse |
| No disposal in ngOnDestroy | Memory never freed | Always dispose all nodes |
| Forgetting `await Tone.start()` | Silent playback | Call on first interaction |
| Not awaiting `reverb.ready` | Reverb may not work | Always await before connecting |
| Using `setTimeout` for timing | Timing drift | Use Tone.js Transport or `Tone.now()` |
| Connecting nodes out of order | No audio output | Connect from source to destination |

## Debugging Audio Issues

### No Sound
1. Check `Tone.context.state` - must be 'running'
2. Verify connections: synth → effects → destination
3. Check volume levels (not muted, not -Infinity)
4. Ensure note names are valid ('C4' not 'C' or 'c4')

### Clicks/Pops
1. Add attack/release envelope (not 0)
2. Don't stop notes abruptly - use `triggerRelease()`
3. Check for overlapping notes

### Memory Issues
1. Verify disposal in ngOnDestroy
2. Check for event listener cleanup
3. Use Chrome DevTools → Memory → Heap snapshot

## Testing Audio

```typescript
// Mock Tone.js for unit tests
beforeEach(() => {
  spyOn(Tone, 'start').and.returnValue(Promise.resolve());
  // Create mock synth
  mockSynth = jasmine.createSpyObj('PolySynth',
    ['triggerAttackRelease', 'dispose', 'connect', 'set']
  );
  spyOn(Tone, 'PolySynth').and.returnValue(mockSynth);
});

it('should play note', async () => {
  await component.initAudio();
  component.playNote('C4');
  expect(mockSynth.triggerAttackRelease).toHaveBeenCalledWith('C4', '8n');
});
```

## Multiple Audio Sources (Tone.js + alphaTab)

The app uses two audio systems:
- **Tone.js**: Fretboard/keyboard note playback
- **alphaTab**: Guitar Pro file playback (has its own audio context)

### Handling Audio Context Conflicts

alphaTab creates its own Web Audio context. When switching between pages:

```typescript
// The composer's score, which owns the alphaTab api (composer-score.component.ts)
export class ComposerScoreComponent implements AfterViewInit, OnDestroy {
  ngAfterViewInit(): void {
    // alphaTabService.initializeApi(...): alphaTab will create its own audio context
    // Tone.js context remains but is unused
  }

  ngOnDestroy(): void {
    // Dispose alphaTab resources
    this.alphaTabService.dispose();
    // Tone.js resumes automatically when fretboard initializes
  }
}
```

### Key Points

| Context | Managed By | Notes |
|---------|------------|-------|
| Tone.js AudioContext | Tone.js library | Auto-created on first `Tone.start()` |
| alphaTab AudioContext | alphaTab library | Created by `AlphaTabApi` initialization |

- Both contexts can coexist but only one should play at a time
- alphaTab disposes its context when `api.destroy()` is called
- Tone.js context persists across navigation (singleton)

Versions

The database has no other skills named audio-implementation.

Database snapshot: 13.11.2026 · package version 841f9c12791d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100adding-instruments
    Use when adding new musical instruments (ukulele, mandolin, etc.) to the app - covers data model setup, tuning definitions, rendering considerations, and audio synthesis configuration
  • 95audio-playback
    Audio playback using Tone.js including players, transport, scheduling, and loading audio. Use when implementing background music, sound effects, audio synchronization, or timed audio events. Essential for any audio-enabled web application.
  • 95implementation-phase
    Executes implementation tasks using Test-Driven Development, prevents code duplication through anti-duplication checks, and maintains quality through continuous testing. Use when implementing features from tasks.md, during the /implement phase, or when the user requests…
  • 100audio-analysis
    Audio analysis with Tone.js and Web Audio API including FFT, frequency data extraction, amplitude measurement, and waveform analysis. Use when extracting audio data for visualizations, beat detection, or any audio-reactive features.
  • 95web-audio-api-synthesis
    Design and implement low-latency browser audio synthesis, sound effects, audio node graphs, convolver reverbs, and custom AudioWorklet processors using the W3C Web Audio API. Trigger when building interactive web synthesizers, in-browser audio editors, sound engines for games,…
  • 100audio-and-sound
    Use this skill when adding audio or sound to a Phaser 4 game. Covers loading audio, playing sounds, music, volume, spatial audio, Web Audio API, and SoundManager. Triggers on: sound, audio, music, volume, mute.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.