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, apply audio processors to transform sounds, 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: Engine → Processor → Output

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: Registered in src/lib/audio/engines/registry.ts

3. AudioProcessor interface (src/lib/audio/processors/AudioProcessor.ts): Abstract interface for audio processors

   • Defines process() method that transforms existing audio buffers
   • Takes stereo input and returns stereo output: [Float32Array, Float32Array]
   • Applied after engine generation, before final output

4. Processors: Registered in src/lib/audio/processors/registry.ts

5. 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

6. 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

Adding New Audio Processors

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

1. Implement the AudioProcessor interface in a single file under src/lib/audio/processors/
2. Implement getName() to return the processor's display name
3. Implement getDescription() to return a brief description of the processor
4. Ensure process() takes stereo input and returns stereo output: [Float32Array, Float32Array]
5. Processors operate on existing audio buffers and should not generate new sounds from scratch
6. Keep all helper functions, enums, and types in the same file
7. Register the processor by adding it to the processors array in src/lib/audio/processors/registry.ts
8. Processors are randomly selected when the user clicks "Process"

User Workflow

1. Generate: User clicks "Random" to generate a raw, unprocessed sound using the current engine
2. Refine: User can "Mutate" the sound (adjusting parameters) or generate a new random sound
3. Process: User clicks "Process" to apply a random audio processor to the sound
4. Iterate: After processing, "Mutate" disappears but "Process" remains available for multiple processing passes
5. Reset: Clicking "Random" generates a new raw sound and returns to the initial state

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.