98 lines
5.2 KiB
Markdown
98 lines
5.2 KiB
Markdown
# 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.
|