npm package: @funwayhq/sound-design
Description: Claude Code skill for expert sound design — synthesis theory, psychoacoustics, patch recipes, and runnable SuperCollider/Web Audio code generation
Author: Funway Interactive SRL
Latest version: 1.0.0

# Sound Design Skill for Claude Code

An expert sound designer skill that turns Claude into a synthesis specialist — reasoning from physics, psychoacoustics, and signal processing theory to produce detailed patch recipes and runnable code.

## What It Does

Give Claude a sound description and get back:

1. **Psychoacoustic analysis** — spectral, temporal, dynamic, and perceptual reasoning about the target sound
2. **Parameter sheet** — every synthesis parameter with a value *and* rationale grounded in acoustics
3. **SuperCollider code** — complete, runnable `SynthDef` ready to paste into SC IDE
4. **Web Audio code** — complete, runnable JavaScript ready to paste into a browser console

Claude reasons from first principles — not preset lookup. Every value has a "why."

## Quick Start

### As a Personal Skill

Copy the skill folder to your Claude Code skills directory:

```bash
# macOS / Linux
cp -r skills/sound-design ~/.claude/skills/sound-design

# Windows
xcopy /E /I skills\sound-design %USERPROFILE%\.claude\skills\sound-design
```

Then use it in Claude Code:

```
/sound-design warm analog pad
/sound-design metallic FM bell with long decay
/sound-design 808 kick with extra sub weight
```

It also auto-triggers on natural language like:
- "design me a bass sound"
- "how do I synthesize a bell?"
- "create a granular texture"

### As an NPM Plugin

```bash
npm install @funwayhq/sound-design
```

## Example Output

Ask for a "warm analog pad" and you'll get:

**Analysis**: Slow-attack sound with detuned sawtooths creating beating at ~3 Hz for warmth. Low-pass filter at ~1200 Hz passes first few harmonics. Slow LFO on filter cutoff adds organic timbral movement...

**Parameter Sheet**:

| Parameter | Value | Rationale |
|---|---|---|
| Osc 1 | Sawtooth | Full harmonic series — richest subtractive source |
| Osc 2 detune | +7 cents | ~3 Hz beating at A440 — warmth without pitch ambiguity |
| Filter cutoff | 1200 Hz | Passes ~3 harmonics at A220 — warm but not muffled |
| Attack | 600 ms | Slow fade-in defines pad character |
| ... | ... | ... |

**SuperCollider**: Complete `SynthDef(\warmPad, { ... }).add;` with test line

**Web Audio**: Complete `function playPad(freq, duration) { ... }` ready for browser console

## File Structure

```
skills/sound-design/
├── SKILL.md                        # Main orchestration (skill entry point)
├── reference/
│   ├── synthesis-types.md          # 8 synthesis methods with theory
│   ├── building-blocks.md          # Oscillators, filters, envelopes, LFOs
│   ├── sound-recipes.md            # Starting recipes by category
│   ├── psychoacoustics.md          # Timbre, harmonics, formants, masking
│   ├── effects-chain.md            # Reverb, delay, distortion, modulation FX
│   └── modulation-matrix.md        # Routing patterns and amount calibration
├── templates/
│   ├── supercollider.md            # SC SynthDef patterns + UGen reference
│   ├── webaudio.md                 # Web Audio API patterns + AudioParam scheduling
│   └── parameter-sheet.md          # Synth-agnostic parameter table format
└── examples/
    ├── sc-examples.scd             # 6 runnable SuperCollider SynthDefs
    └── wa-examples.js              # 6 runnable Web Audio patches
```

## Synthesis Methods Covered

| Method | Best For |
|---|---|
| **Subtractive** | Warm basses, analog leads, pads with filter sweeps |
| **FM** | Bells, electric pianos, metallic sounds, complex plucks |
| **Additive** | Organs, precise spectral control, vocal formants |
| **Wavetable** | Evolving pads, morphing timbres, digital textures |
| **Granular** | Atmospheric textures, soundscapes, time-stretching |
| **Physical Modeling** | Plucked strings, wind instruments, realistic percussion |
| **AM / Ring Mod** | Metallic timbres, tremolo, robotic effects |
| **Phase Distortion** | CZ-style digital sounds, unique waveform shapes |

## Sound Categories

The skill includes starting recipes for:

- **Bass**: sub, analog, Reese, FM, 808, wobble
- **Leads**: mono, sync, supersaw, acid (303-style)
- **Pads**: analog, digital/wavetable, granular, string
- **Keys**: electric piano (FM), organ (additive), clavinet
- **Plucks**: Karplus-Strong, filtered, FM
- **Drums**: kick, snare, hi-hat, clap, toms
- **FX/Textures**: risers, impacts, drones, atmospheres

## Working Examples

### SuperCollider (`examples/sc-examples.scd`)

Six complete, runnable SynthDefs:
1. **Subtractive bass** — detuned saws, resonant LP filter, filter envelope
2. **FM bell** — 1:1.41 ratio, decaying mod index, long ring
3. **Karplus-Strong pluck** — noise excitation, waveguide delay, LP damping
4. **Supersaw pad** — 7-voice unison, stereo spread, slow attack, reverb
5. **808 kick** — sine + pitch envelope, noise click, soft saturation
6. **Granular texture** — randomized grains, pitch scatter, reverb wash

### Web Audio (`examples/wa-examples.js`)

Six complete, browser-console-ready patches:
1. **Subtractive bass** — detuned saws, filter envelope, punchy amp
2. **FM bell** — irrational ratio, decaying index, percussive decay
3. **Acid lead** — single saw, high-Q filter, fast cutoff sweep
4. **Warm pad** — detuned saws, LFO filter mod, convolution reverb
5. **808 kick** — sine pitch drop, noise click, waveshaper saturation
6. **Karplus-Strong pluck** — noise burst, delay line feedback, LP damping

## Reference Knowledge

### Psychoacoustics
- Spectral centroid and brightness perception
- Harmonic series and even/odd harmonic character
- Vowel formant frequencies (full table)
- Critical bands and spectral masking
- Equal-loudness contours (Fletcher-Munson)
- Roughness, beating, and detuning perception

### Building Blocks
- Waveform spectra comparison table
- Filter types, slopes, and resonance ranges with perceptual meanings
- ADSR ranges with musical use cases
- LFO rate ranges and perceptual effects
- Modulation amount calibration guide

### Effects
- Signal chain ordering rationale
- Reverb types with decay ranges and use cases
- Delay types and feedback behavior
- Distortion types and harmonic character
- Modulation effects (chorus, flanger, phaser, tremolo)
- Creative EQ applications

## Quality Standards

Every output from this skill follows these rules:

1. Every parameter value has a rationale grounded in acoustics or psychoacoustics
2. All code is copy-paste runnable — no placeholders, no TODOs
3. Signal flow is explicit and traceable from oscillator to output
4. Frequencies in Hz, times in seconds — never ambiguous units
5. Modulation amounts explained perceptually
6. CPU awareness noted for expensive patches

## License

MIT