zk-audio 0.1.0

# zk-audio

[![zk-audio](https://img.shields.io/crates/v/zk-audio)](https://crates.io/crates/zk-audio)
[![Documentation](https://docs.rs/zk-audio/badge.svg)](https://docs.rs/zk-audio)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Rust library for real-time audio capture, voice enhancement, and microphone simulation.

## Features

- **Native Audio Capture** - CPAL-based cross-platform audio input
- **Voice Enhancement Pipeline** - 19 DSP processor stages for professional voice quality
- **Microphone Simulation** - Emulate classic microphones (Neumann U87, Shure SM7B, etc.)
- **Profile-Based Processing** - Pre-configured profiles for different environments
- **WAV Output** - Built-in WAV encoding with hound

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
zk-audio = { path = "../zk-audio" }
```

Or without native capture support:

```toml
[dependencies]
zk-audio = { path = "../zk-audio", default-features = false }
```

## Quick Start

### Basic Voice Recording

```rust
use zk_audio::{
    NativePipelineBuilder, PipelineBuildRequest,
    NativeCaptureConfig, AudioProfile, NativeCaptureBackend,
    CaptureBackend,
};
use std::path::PathBuf;

// Create capture configuration
let config = NativeCaptureConfig {
    output_path: PathBuf::from("recording.wav"),
    target_sample_rate: 44_100,
    target_channels: 1,
    preferred_input_device: None, // Use system default
    profile: AudioProfile::VoiceClean,
    input_gain_db: 0.0,
    limiter_threshold: 0.95,
    high_pass_hz: 80.0,
    noise_suppression_amount: 0.5,
    noise_calibration_ms: 350,
    delay_effect: None,
    stage_overrides: Default::default(),
    microphone_sim: Default::default(),
};

// Start recording
let backend = NativeCaptureBackend::new();
let mut recording = backend.start(config)?;

// Stop and finalize
let diagnostics = recording.stop()?;
println!("Recorded {} frames", diagnostics.frames_processed);
```

### Building a Processing Pipeline

```rust
use zk_audio::{
    NativePipelineBuilder, PipelineBuildRequest,
    AudioProfile, MicrophoneSimConfig, MicrophoneSimModel,
};

let builder = NativePipelineBuilder::new();
let pipeline = builder.build(PipelineBuildRequest {
    output_path: PathBuf::from("output.wav"),
    profile: AudioProfile::VoiceHvac,
    sample_rate: 44_100,
    device_channels: 1,
    device_name: Some("USB Microphone".to_string()),
    gain_db: 2.0,
    limiter_threshold: 0.92,
    high_pass_hz: 100.0,
    noise_suppression_amount: 0.7,
    noise_calibration_ms: 350,
    delay_effect: None,
    stage_overrides: Default::default(),
    microphone_sim: MicrophoneSimConfig {
        model: Some(MicrophoneSimModel::U87),
        ..Default::default()
    },
})?;
```

## Audio Profiles

| Profile | Description | Use Case |
|---------|-------------|----------|
| `Raw` | No processing | Reference recordings, debugging |
| `VoiceClean` | Light processing | Quiet environments, studio |
| `VoiceNoisyRoom` | Moderate noise reduction | Office spaces, cafes |
| `VoiceHvac` | Aggressive HVAC suppression | Air-conditioned rooms |

## Processor Stages

The pipeline applies processors in this order:

1. **Filtering**
   - `HighPass` - Remove low-frequency rumble
   - `LowShelfCut` - Reduce bass build-up
   - `LowPass` - Remove high-frequency noise

2. **Dynamics**
   - `Expander` - Gate out quiet noise
   - `NoiseSuppression` - Spectral noise reduction
   - `AdaptiveGain` - Speech-aware amplification
   - `Compressor` - Multi-band compression
   - `Agc` - Automatic gain control

3. **Tone Shaping**
   - `AdaptiveToneShaper` - Dynamic EQ
   - `MidResonanceSuppressor` - Reduce boxy sound
   - `HighBandCleanup` - Clean harsh frequencies
   - `PresenceBoost` - Enhance speech clarity
   - `DeEsser` - Reduce sibilance
   - `TailSuppression` - Reduce reverb tails
   - `Dehiss` - Remove hiss
   - `AirBandReducer` - HVAC-specific filtering

4. **Effects**
   - `DoublingDelay` - Voice thickening
   - `VoiceFinisher` - Final polish (glue, warmth, saturation)
   - `Limiter` - Prevent clipping

### Overriding Processor Stages

```rust
use zk_audio::{ProcessorOverrideMode, ProcessorStage};
use std::collections::BTreeMap;

let mut overrides = BTreeMap::new();
overrides.insert("presence_boost".to_string(), ProcessorOverrideMode::Disabled);
overrides.insert("deesser".to_string(), ProcessorOverrideMode::Enabled);

let config = NativeCaptureConfig {
    stage_overrides: overrides,
    // ...
};
```

## Microphone Simulation

Add character of classic microphones to your recordings:

```rust
use zk_audio::{MicrophoneSimConfig, MicrophoneSimModel};

let mic_config = MicrophoneSimConfig {
    model: Some(MicrophoneSimModel::SM7B),
    drive: 0.5,
    mix: 0.8,
};
```

### Supported Models

| Model | Description |
|-------|-------------|
| `U87` | Neumann U87 - Warm, smooth condenser |
| `TLM103` | Neumann TLM103 - Clean, modern |
| `SM7B` | Shure SM7B - Broadcast standard |
| `RE20` | Electro-Voice RE20 - Announcer mic |
| `C414` | AKG C414 - Versatile condenser |
| `MD421` | Sennheiser MD421 - Dynamic |
| `M149` | Neumann M149 - Vintage tube |

## Delay Effects

Add vocal effects:

```rust
use zk_audio::{DelayEffectConfig, DelayEffectPreset};

let delay = DelayEffectConfig {
    preset: DelayEffectPreset::VoiceDoubler,
};
```

| Preset | Effect |
|--------|--------|
| `VoiceDoubler` | Subtle widening |
| `Thickener` | Dense doubling |
| `Slapback` | Short echo |
| `Bloom` - | Rich ambience |

## Device Enumeration

```rust
use zk_audio::{list_input_devices, set_default_input_device};

// List available input devices
let devices = list_input_devices()?;
for device in devices {
    println!("{}: {} (default: {})", device.id, device.name, device.is_default);
}

// Set preferred device
set_default_input_device("alsa_input.usb-device-id")?;
```

## Documentation

- [Audio Processing Architecture](docs/audio-processing/README.md)
- [Pipeline Stages Details](docs/audio-processing/pipeline-stages.md)
- [Evolution & Iterations](docs/audio-processing/evolution.md)
- [Microphone Simulation](docs/microphone-simulation/README.md)

## Platform Support

| Platform | Backend | Status |
|----------|---------|--------|
| Linux | PipeWire/PulseAudio | Supported |
| macOS | CoreAudio | Planned |
| Windows | WASAPI | Planned |

## Dependencies

- `cpal` - Cross-platform audio I/O (optional)
- `hound` - WAV encoding/decoding
- `biquad` - Biquad filter coefficients
- `realfft` - Real-valued FFT
- `serde` - Serialization

## License

MIT