mkaudiolibrary

A Rust library for real-time audio signal processing, featuring analog modeling through numeric functions and circuit simulation via Modified Nodal Analysis (MNA).

Features

• Thread-safe buffers with RwLock-based concurrent access
• Analog modeling for tube/tape-style saturation with asymmetric parameters
• Circuit simulation with real-time transient analysis using MNA
• DSP primitives including convolution, compression, limiting, and delay
• Audio file I/O for WAV and AIFF formats with Buffer integration
• Plugin system via MKAU format for modular processing chains
• Zero-copy design with boxed slices for minimal allocation overhead

Installation

Add to your Cargo.toml:

[dependencies]
mkaudiolibrary = "1.0"

Quick Start

use mkaudiolibrary::audiofile::{AudioFile, FileFormat};
use mkaudiolibrary::dsp::Compression;
use mkaudiolibrary::buffer::Buffer;

// Load an audio file
let mut audio = AudioFile::default();
audio.load("input.wav");

println!("Loaded: {} channels, {} samples, {}Hz",
    audio.num_channel(),
    audio.num_sample(),
    audio.sample_rate()
);

// Convert to thread-safe buffers for processing
let buffers = audio.to_buffers();

// Apply compression to each channel
let mut comp = Compression::new(audio.sample_rate() as f64);
comp.threshold = -12.0;
comp.ratio = 4.0;

for buffer in &buffers {
    let output = Buffer::new(buffer.len());
    comp.run(buffer, &output);
    // ... copy processed output back
}

// Save result
audio.save("output.wav", FileFormat::Wav);

Modules

buffer

Thread-safe audio buffers designed for concurrent multi-threaded access:

All buffers use Arc<RwLock<...>> internally, allowing multiple concurrent readers or exclusive write access.

use mkaudiolibrary::buffer::Buffer;
use std::thread;

let buffer = Buffer::<f64>::new(1024);
let buffer_clone = buffer.clone();  // Shares underlying data

// Writer thread
let writer = thread::spawn(move || {
    let mut guard = buffer_clone.write();
    for i in 0..1024 {
        guard[i] = (i as f64 / 1024.0).sin();
    }
});

writer.join().unwrap();

// Reader thread
let guard = buffer.read();
println!("First sample: {}", guard[0]);

dsp

Audio processing components organized by category:

Utility Functions

use mkaudiolibrary::dsp::{ratio_to_db, db_to_ratio};

let db = ratio_to_db(2.0);      // ~6.02 dB
let ratio = db_to_ratio(-6.0);  // ~0.5

Saturation (Analog Modeling)

Asymmetric logarithmic saturation model for analog-style harmonic generation:

• Alpha parameters - Independent drive/knee control for positive and negative signals
• Beta parameters - Separate compression/gain characteristics per polarity
• Delta parameter - DC bias offset for curve positioning
• Gamma parameter - Boolean polarity inversion

use mkaudiolibrary::dsp::Saturation;
use mkaudiolibrary::buffer::Buffer;

let sat = Saturation::new(
    10.0, 10.0,   // alpha_plus, alpha_minus (drive)
    1.0, 1.0,     // beta_plus, beta_minus (compression)
    0.0,          // delta (bias)
    false         // flip polarity
);

// Process single sample
let output = sat.process(0.8);

// Process buffer
let input = Buffer::from_slice(&[0.0, 0.5, 1.0, -0.5, -1.0]);
let output = Buffer::new(5);
sat.run(&input, &output);

Circuit Simulation (Modified Nodal Analysis)

Sample-by-sample circuit analysis for real-time filtering:

• Component library - Resistors, capacitors, and inductors with companion model discretization
• Gaussian elimination solver with partial pivoting
• Single preprocessing step builds the static admittance matrix
• Per-sample updates for reactive element state

use mkaudiolibrary::dsp::{Circuit, Resistor, Capacitor, Inductor};

// Create an RC lowpass filter: fc = 1/(2πRC) ≈ 159Hz
let mut circuit = Circuit::new(44100.0, 2);
circuit.add_component(Box::new(Resistor::new(1, 2, 1000.0)));   // 1kΩ
circuit.add_component(Box::new(Capacitor::new(2, 0, 1e-6)));    // 1µF

// Build Y matrix (call once before processing)
circuit.preprocess(10.0);

// Process samples
for input_sample in audio_input {
    let output = circuit.process(input_sample, 2);  // Input voltage, probe node 2
}

Dynamics Processing

use mkaudiolibrary::dsp::{Compression, Limit};
use mkaudiolibrary::buffer::Buffer;

// Compressor with soft knee
let mut compressor = Compression::new(44100.0);
compressor.threshold = -20.0;  // dB
compressor.ratio = 4.0;        // 4:1
compressor.attack = 10.0;      // ms
compressor.release = 100.0;    // ms
compressor.makeup = 6.0;       // dB
compressor.knee = 6.0;         // dB (soft knee width)

// Brickwall limiter
let mut limiter = Limit::new(44100.0);
limiter.gain = 0.0;            // dB input gain
limiter.ceiling = -0.1;        // dB output ceiling
limiter.release = 100.0;       // ms

// Process buffers
let input = Buffer::new(1024);
let output = Buffer::new(1024);
compressor.run(&input, &output);

Time-Based Effects

use mkaudiolibrary::dsp::{Convolution, Delay};
use mkaudiolibrary::buffer::Buffer;

// Convolution with impulse response
let impulse_response = vec![1.0, 0.5, 0.25, 0.125];
let conv = Convolution::new(&impulse_response).unwrap();

let input = Buffer::new(1024);
let output = Buffer::new(1024);
conv.run(&input, &output);

// Feedback delay
let mut delay = Delay::new(250.0, 44100.0);  // 250ms delay
delay.feedback = 0.5;  // 50% feedback
delay.mix = 0.5;       // 50% wet

audiofile

Load and save audio files with automatic format detection:

use mkaudiolibrary::audiofile::{AudioFile, FileFormat};

// Load audio file (WAV or AIFF auto-detected)
let mut audio = AudioFile::default();
audio.load("song.wav");

// Inspect file properties
println!("Format: {:?}", audio.format());
println!("Channels: {}", audio.num_channel());
println!("Samples: {}", audio.num_sample());
println!("Sample rate: {} Hz", audio.sample_rate());
println!("Bit depth: {}", audio.bit_depth());
println!("Duration: {:.2} seconds", audio.length());

// Direct channel access
if let Some(left) = audio.channel(0) {
    let peak = left.iter().fold(0.0_f64, |max, &s| max.max(s.abs()));
    println!("Peak level: {:.4}", peak);
}

// Modify samples
if let Some(left) = audio.channel_mut(0) {
    for sample in left.iter_mut() {
        *sample *= 0.5;  // Apply -6dB gain
    }
}

// Save in different format
audio.set_bit_depth(24);
audio.save("output.aiff", FileFormat::Aiff);

Buffer Integration

Seamlessly integrate with thread-safe buffers for DSP processing:

use mkaudiolibrary::audiofile::AudioFile;
use mkaudiolibrary::buffer::Buffer;

let mut audio = AudioFile::default();
audio.load("input.wav");

// Convert to thread-safe buffers
let buffers = audio.to_buffers();

// Process each channel in parallel (example)
// ... parallel processing ...

// Copy results back
audio.from_buffers(&buffers);

processor

MKAU plugin format for modular audio processing chains:

use mkaudiolibrary::processor::{Processor, load};

// Load a plugin
let plugin = load("/path/to/plugins", "myplugin").expect("Failed to load");
println!("Loaded: {}", plugin.name());

// Prepare for playback
plugin.prepare_to_play(512, 44100);

// Process audio
let input: Vec<&[f64]> = vec![&left_in, &right_in];
let mut output: Vec<&mut [f64]> = vec![&mut left_out, &mut right_out];
plugin.run(&input, &[], &mut output, &mut []);

Creating Plugins

use mkaudiolibrary::processor::Processor;
use mkaudiolibrary::buffer::Buffer;

struct GainPlugin {
    gain: f64,
}

impl Processor for GainPlugin {
    fn init(&mut self) {}
    fn name(&self) -> String { String::from("Gain") }
    fn get_parameter(&self, _index: usize) -> f64 { self.gain }
    fn set_parameter(&mut self, _index: usize, value: f64) { self.gain = value; }
    fn get_parameter_name(&self, _index: usize) -> String { String::from("Gain") }
    fn open_window(&self) {}
    fn close_window(&self) {}
    fn prepare_to_play(&mut self, _buffer_size: usize, _sample_rate: usize) {}

    fn run(&self, input: &[&[f64]], _sidechain_in: &[&[f64]],
           output: &mut [&mut [f64]], _sidechain_out: &mut [&mut [f64]]) {
        for ch in 0..input.len() {
            for i in 0..input[ch].len() {
                output[ch][i] = input[ch][i] * self.gain;
            }
        }
    }
}

// Export as dynamic library
mkaudiolibrary::declare_plugin!(GainPlugin, GainPlugin::new);

Thread Safety

All buffer types implement Send + Sync and use interior mutability with RwLock:

Guards automatically release locks when dropped (RAII pattern).

Supported Audio Formats

Supported bit depths: 8, 16, 24, 32-bit

Changelog

1.0.0

• Major update with thread-safe buffers using RwLock
• New saturation model with asymmetric numeric modeling
• Circuit simulation with MNA solver
• Refined compression and limiting with proper envelope detection
• Enhanced audiofile module with Buffer integration
• Comprehensive documentation for all modules

0.3.0

• Reconstructed sized buffer, used slice instead of buffer for plugins

0.2.x

• Added audiofile module
• Lock/unlock mechanisms for data safety
• Updated processor loader and documentation

0.1.x

• Initial development versions
• Buffer implementations with reference counting
• Basic DSP components

License

This library is dual-licensed:

• GPL-3.0 for open source projects
• Commercial license available for closed source usage

For commercial licensing inquiries, contact: minjaekim@mkaudio.company