# CLAUDE.md

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

## Development Commands

### Build Commands

- `cargo build` - Build with core features only
- `cargo build --features full` - Build with all features enabled
- `cargo build --features "fft plotting"` - Build with specific features
- `cargo check` - Fast syntax/type checking
- `cargo clippy` - Comprehensive linting
- `cargo fmt` - Code formatting

### Testing

- `cargo test` - Run core tests
- `cargo test --features full` - Run all tests with all features
- `cargo test <test_name>` - Run specific test
- `cargo test --lib` - Run library unit tests only
- `cargo test --doc` - Run documentation tests

### Running Examples

- `cargo run --example iterators_demo` - Basic iteration patterns
- `cargo run --example processing_builder_demo --features full` - Processing pipeline demo
- `cargo run --example beat_tracking_with_progress --features full` - Advanced analysis with progress tracking

## Architecture Overview

### Core Design Philosophy
This is a modular audio processing library built around trait-based operations on `AudioSamples<T>` containers. The library follows a zero-allocation approach where possible, using views for efficient data access.

### Key Components

#### `AudioSamples<T>` - Main Container

- Central data structure wrapping `AudioData<T>` enum
- Supports borrowed and owned data through lifetime parameter `'a`
- Channels as rows, samples as columns in multi-channel case
- Supports multiple sample types: `i16`, `I24`, `i32`, `f32`, `f64`
- Sample rate stored alongside data

#### Data Storage System

- `AudioData<'a, T>` - Enum with `Mono(MonoData<'a, T>)` and `Multi(MultiData<'a, T>)` variants
- `MonoData<'a, T>` - Wraps `Array1<T>` for single-channel audio
- `MultiData<'a, T>` - Wraps `Array2<T>` for multi-channel audio
- Each data type supports both borrowed (`ArrayView`) and owned (`Array`) representations

#### Trait Organization
Operations are organized into focused traits in `src/operations/traits.rs`:

**Core Traits:**

- `AudioStatistics` - Peak, RMS, variance, zero-crossings, spectral analysis
- `AudioProcessing` - Normalize, scale, clip, DC removal, gain operations
- `AudioChannelOps` - Mono/stereo conversion, channel manipulation
- `AudioEditing` - Trim, pad, reverse, fade, mix, concatenation

**Advanced Traits (feature-gated):**

- `AudioTransforms` - FFT, STFT, spectral analysis (requires `fft`)
- `AudioPitchAnalysis` - Fundamental frequency analysis (requires `spectral-analysis`)
- `AudioPlottingUtils` - Visualization (requires `plotting`)
- `AudioIirFiltering` - IIR filters, biquads
- `AudioParametricEq` - Multi-band equalizer
- `AudioDynamicRange` - Compression, limiting, expansion

**Utility Traits:**

- `AudioOperationApply` - Apply functions to samples
- `AudioRealtimeOps` - Real-time processing operations
- `AudioSamplesOperations` - Umbrella trait combining all operations

### Type System

#### Sample Types and Conversions

- **`ConvertTo<T>`** - Audio-aware conversions with proper scaling (i16 → f32 normalizes to -1.0..1.0)
- **`CastFrom<T>/CastInto<T>`** - Raw numeric casting without audio scaling
- All sample types implement `AudioSample` trait for common operations

#### Error Handling

- Simple operations return values directly (e.g., `peak()` returns `T`)
- Complex operations return `Result<T, AudioError>`
- Chainable result pattern available for functional composition

### Feature System
The library uses cargo features for modular dependencies:

- `default` - Includes `full` (all features enabled by default)
- `core-ops` - Basic operations
- `fft` - Spectral analysis via RustFFT/RealFFT
- `plotting` - Visualization via Plotly
- `resampling` - Quality resampling via Rubato
- `parallel-processing` - Multi-threading via Rayon
- `simd` - SIMD acceleration
- `beat-detection` - Tempo analysis (requires `fft`)
- `spectral-analysis` - Advanced spectral operations (requires `fft`)
- `static-plots` - Static plot generation
- `mkl` - Intel MKL backend for FFT
- `progress-tracking` - Progress reporting for long operations
- `full` - All features enabled

### Module Structure

- `src/repr.rs` - Core data structures (`AudioSamples`, `AudioData`, etc.)
- `src/operations/traits.rs` - All trait definitions
- `src/operations/` - Trait implementations organized by functionality:
  - `statistics.rs` - Statistical operations
  - `processing.rs` - Signal processing + ProcessingBuilder
  - `transforms.rs` - FFT and spectral analysis
  - `editing.rs` - Time-domain editing
  - `channels.rs` - Channel operations
  - `iir_filtering.rs` - IIR filter implementations
  - `parametric_eq.rs` - Equalizer operations
  - `dynamic_range.rs` - Compression/limiting
  - `pitch_analysis.rs` - Pitch detection
  - `plotting/` - Visualization components
  - `beats.rs` - Beat detection and tracking
- `src/utils/` - Utility functions (generation, detection, comparison)
- `src/iterators.rs` - Iterator patterns (frames, channels, windows)
- `src/realtime.rs` - Real-time processing utilities
- `src/conversions.rs` - Type conversion implementations
- `src/traits.rs` - Core type system traits

## Code Conventions

### Error Handling

- Use `AudioSampleError` for audio-specific errors
- Simple getters return values directly, complex operations return `Result`
- Prefer `?` operator over `.unwrap()` or `.expect()`

### Performance

- Use views for zero-allocation access patterns
- Prefer in-place operations when possible
- SIMD acceleration available via `simd` feature
- Parallel processing available via `parallel-processing` feature

### Type Safety

- Leverage the type system for sample format safety
- Use appropriate conversion traits (`ConvertTo` vs `CastInto`)
- Maintain sample rate information with audio data

## Builder Pattern Usage

The library provides a fluent ProcessingBuilder API:

```rust
audio.processing()
    .normalize(-1.0, 1.0, NormalizationMethod::Peak)
    .scale(0.8)
    .clip(-0.5, 0.5)
    .remove_dc_offset()
    .apply()?;
```

## Iterator Patterns

The library supports several iteration patterns:

- `audio.frames()` - Iterate by frames (one sample from each channel)
- `audio.channels()` - Iterate by complete channels
- `audio.windows(size, hop)` - Windowed iteration with overlap
- Support for different padding modes: Zero, None, Skip

## Important Implementation Details

1. **Lifetime Management**: `AudioSamples<'a, T>` uses lifetime parameter to support both borrowed and owned data
2. **Memory Layout**: Mono audio uses 1D arrays, multi-channel uses 2D arrays with channels as rows
3. **Feature Gates**: Many operations are feature-gated to keep dependencies minimal
4. **Type Conversions**: Two conversion systems - `ConvertTo` for audio-aware scaling, `CastFrom/Into` for raw numeric casting
5. **Error Propagation**: Complex operations return `Result` types and support chainable error handling