rsgp/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Svelte + TypeScript audio synthesis application that generates and manipulates sounds using various synthesis recipes (modes). Each recipe is a different flavour of audio synthesis, generating random audio samples that musicians can use in their compositions. Users can generate random sounds, mutate existing ones, visualize waveforms, and export audio as WAV files.

Build System

• Package manager: pnpm (not npm or yarn)
• Bundler: Vite (using rolldown-vite fork)
• Development: pnpm dev
• Build: pnpm build
• Preview: pnpm preview
• Type checking: pnpm check (runs svelte-check and tsc)

Architecture

Audio Pipeline

The audio system follows a layered architecture:

1. SynthEngine interface (src/lib/audio/engines/SynthEngine.ts): Abstract interface for synthesis engines

   • Defines generate(), randomParams(), and mutateParams() methods
   • All engines must generate stereo output: [Float32Array, Float32Array]
   • Time-based parameters (envelopes, LFOs) stored as ratios (0-1) and scaled by duration during generation

2. Engines

3. AudioService (src/lib/audio/services/AudioService.ts): Web Audio API wrapper

   • Manages AudioContext, gain node, and playback
   • Provides playback position tracking via animation frames
   • Fixed sample rate: 44100 Hz

4. WAVEncoder (src/lib/audio/utils/WAVEncoder.ts): Audio export functionality

State Management

• No external state library - uses Svelte 5's reactivity
• Settings persistence via localStorage (src/lib/utils/settings.ts)
• Volume and duration preferences saved/loaded automatically

UI Components

• App.svelte: Main application container and control logic
• WaveformDisplay.svelte: Visual waveform rendering with playback position indicator
• VUMeter.svelte: Real-time level meter
• Color generation: Random colors for each sound (src/lib/utils/colors.ts)

Key Patterns

Adding New Synthesis Engines

CRITICAL: Each engine must be completely self-contained in a single file. Do not create separate utility files, helper classes, or subdirectories for engine components. All DSP code, envelopes, oscillators, and algorithm logic should be private methods within the engine class.

1. Implement the SynthEngine interface in a single file under src/lib/audio/engines/
2. Implement getName() to return the engine's display name
3. Implement getDescription() to return a brief description of the engine
4. Ensure generate() returns stereo output: [Float32Array, Float32Array]
5. Time-based parameters should be ratios (0-1) scaled by duration
6. Provide randomParams() and mutateParams() implementations
7. Keep all helper functions, enums, and types in the same file
8. Register the engine by adding it to the engines array in src/lib/audio/engines/registry.ts
9. The mode buttons in the UI will automatically update to include your new engine

Duration Handling

Duration is user-adjustable. All time-based synthesis parameters (attack, decay, release, LFO rates) must scale with duration. Store envelope timings as ratios of total duration, not absolute seconds.