zk-audio

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:

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

Or without native capture support:

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

Quick Start

Basic Voice Recording

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

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

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

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:

use zk_audio::{MicrophoneSimConfig, MicrophoneSimModel};

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

Supported Models

Delay Effects

Add vocal effects:

use zk_audio::{DelayEffectConfig, DelayEffectPreset};

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

Device Enumeration

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
• Pipeline Stages Details
• Evolution & Iterations
• Microphone Simulation

Platform Support

Dependencies

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

License

MIT