skyler
/
Lightningbeam
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Lightningbeam/docs/AUDIO_SYSTEM.md

1093 lines
32 KiB
Markdown
Raw Blame History

# Audio System Architecture
This document describes the architecture of Lightningbeam's audio engine (`daw-backend`), including real-time constraints, lock-free design patterns, and how to extend the system with new effects and features.
## Table of Contents
- [Overview](#overview)
- [Architecture](#architecture)
- [Real-Time Constraints](#real-time-constraints)
- [Lock-Free Communication](#lock-free-communication)
- [Audio Processing Pipeline](#audio-processing-pipeline)
- [Adding Effects](#adding-effects)
- [Adding Synthesizers](#adding-synthesizers)
- [MIDI System](#midi-system)
- [Performance Optimization](#performance-optimization)
- [Debugging Audio Issues](#debugging-audio-issues)
## Overview
The `daw-backend` crate is a standalone real-time audio engine designed for:
- **Multi-track audio playback and recording**
- **Real-time audio effects processing**
- **MIDI input/output and sequencing**
- **Modular audio routing** (node graph system)
- **Audio export** (WAV, MP3, AAC)
### Key Features
- Lock-free design for real-time safety
- Cross-platform audio I/O via cpal
- Audio decoding via symphonia (MP3, FLAC, WAV, Ogg, AAC)
- Node-based audio graph processing
- Comprehensive effects library
- Multiple synthesizer types
- Zero-allocation audio thread
## Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ UI Thread │
│ (lightningbeam-editor or other application) │
├─────────────────────────────────────────────────────────────┤
│ │
│ AudioSystem::new() ─────> Creates audio stream │
│ │ │
│ ├─> command_sender (rtrb::Producer) │
│ └─> state_receiver (rtrb::Consumer) │
│ │
│ Commands sent: │
│ - Play / Stop / Seek │
│ - Add / Remove tracks │
│ - Load audio files │
│ - Add / Remove effects │
│ - Update parameters │
│ │
└──────────────────────┬──────────────────────────────────────┘
│
│ Lock-free queues (rtrb)
│
┌──────────────────────▼──────────────────────────────────────┐
│ Audio Thread (Real-Time) │
├─────────────────────────────────────────────────────────────┤
│ │
│ Engine::process(output_buffer) │
│ │ │
│ ├─> Receive commands from queue │
│ ├─> Update playhead position │
│ ├─> For each track: │
│ │ ├─> Read audio samples at playhead │
│ │ ├─> Apply effects chain │
│ │ └─> Mix to output │
│ ├─> Apply master effects │
│ └─> Write samples to output_buffer │
│ │
│ Send state updates back to UI thread │
│ - Playhead position │
│ - Meter levels │
│ - Overrun warnings │
│ │
└──────────────────────┬──────────────────────────────────────┘
│
▼
┌───────────┐
│ cpal │
│ (Audio │
│ I/O) │
└───────────┘
│
▼
┌──────────────┐
│ Audio Output │
│ (Speakers) │
└──────────────┘
```
### Core Components
#### AudioSystem (`src/lib.rs`)
- Entry point for the audio engine
- Creates the audio stream
- Sets up lock-free communication channels
- Manages audio device configuration
#### Engine (`src/audio/engine.rs`)
- The main audio callback
- Runs on the real-time audio thread
- Processes commands, mixes tracks, applies effects
- Must complete in ~5ms (at 44.1kHz, 256 frame buffer)
#### Project (`src/audio/project.rs`)
- Top-level audio state
- Contains tracks, tempo, time signature
- Manages global settings
#### Track (`src/audio/track.rs`)
- Individual audio track
- Contains audio clips and effects chain
- Handles track-specific state (volume, pan, mute, solo)
## Real-Time Constraints
### The Golden Rule
**The audio thread must NEVER block.**
Audio callbacks run with strict timing deadlines:
- **Buffer size**: 256 frames (default) = ~5.8ms at 44.1kHz
- **ALSA on Linux**: May provide smaller buffers (64-75 frames = ~1.5ms)
- **Deadline**: Audio callback must complete before next buffer is needed
If the audio callback takes too long:
- **Audio dropout**: Audible glitch/pop in output
- **Buffer underrun**: Missing samples
- **System instability**: Priority inversion, thread starvation
### Forbidden Operations in Audio Thread
❌ **Never do these in the audio callback:**
- **Locking**: `Mutex`, `RwLock`, or any blocking synchronization
- **Allocation**: `Vec::push()`, `Box::new()`, `String` operations
- **I/O**: File operations, network, print statements
- **System calls**: Most OS operations
- **Unbounded loops**: Must have guaranteed completion time
✅ **Safe operations:**
- Reading/writing lock-free queues (rtrb)
- Fixed-size array operations
- Arithmetic and DSP calculations
- Pre-allocated buffer operations
### Optimized Debug Builds
To meet real-time deadlines, audio code is compiled with optimizations even in debug builds:
```toml
# In lightningbeam-ui/Cargo.toml
[profile.dev.package.daw-backend]
opt-level = 2
[profile.dev.package.symphonia]
opt-level = 2
# ... other audio libraries
```
This allows fast iteration while maintaining audio performance.
## Lock-Free Communication
### Command Queue (UI → Audio)
The UI thread sends commands to the audio thread via a lock-free ringbuffer:
```rust
// UI Thread
let command = AudioCommand::Play;
command_sender.push(command).ok();
// Audio Thread (in Engine::process)
while let Ok(command) = command_receiver.pop() {
match command {
AudioCommand::Play => self.playing = true,
AudioCommand::Stop => self.playing = false,
AudioCommand::Seek(time) => self.playhead = time,
// ... handle other commands
}
}
```
### State Updates (Audio → UI)
The audio thread sends state updates back to the UI:
```rust
// Audio Thread
let state = AudioState {
playhead: self.playhead,
is_playing: self.playing,
meter_levels: self.compute_meters(),
};
state_sender.push(state).ok();
// UI Thread
if let Ok(state) = state_receiver.pop() {
// Update UI with new state
}
```
### Design Pattern: Command-Response
1. **UI initiates action**: Send command to audio thread
2. **Audio thread executes**: In `Engine::process()`, between buffer fills
3. **Audio thread confirms**: Send state update back to UI
4. **UI updates**: Reflect new state in user interface
This pattern ensures:
- No blocking on either side
- UI remains responsive
- Audio thread never waits
## Audio Processing Pipeline
### Per-Buffer Processing
Every audio buffer (typically 256 frames), the `Engine::process()` callback:
```rust
pub fn process(&mut self, output: &mut [f32]) -> Result<(), AudioError> {
// 1. Process commands from UI thread
self.process_commands();
// 2. Update playhead
if self.playing {
self.playhead += buffer_duration;
}
// 3. Clear output buffer
output.fill(0.0);
// 4. Process each track
for track in &mut self.tracks {
if track.muted {
continue;
}
// Read audio samples at playhead position
let samples = track.read_samples(self.playhead, output.len());
// Apply track effects chain
let mut processed = samples;
for effect in &mut track.effects {
processed = effect.process(processed);
}
// Mix to output with volume/pan
mix_to_output(output, &processed, track.volume, track.pan);
}
// 5. Apply master effects
for effect in &mut self.master_effects {
effect.process_in_place(output);
}
// 6. Send state updates to UI
self.send_state_update();
Ok(())
}
```
### Sample Rate and Buffer Size
- **Sample rate**: 44.1kHz (default) or 48kHz
- **Buffer size**: 256 frames (configurable)
- **Channels**: Stereo (2 channels)
Buffer is interleaved: `[L, R, L, R, L, R, ...]`
### Time Representation
- **Playhead position**: Stored as `f64` seconds
- **Sample index**: `(playhead * sample_rate) as usize`
- **Frame index**: `sample_index / channels`
## Node Graph System
### Overview
Tracks use a node graph architecture powered by `dasp_graph` for flexible audio routing. Unlike simple serial effect chains, the node graph allows:
- **Parallel processing**: Multiple effects processing the same input
- **Complex routing**: Effects feeding into each other in arbitrary configurations
- **Modular synthesis**: Build synthesizers from oscillators, filters, and modulators
- **Send/return chains**: Shared effects (reverb, delay) fed by multiple tracks
- **Sidechain processing**: One signal controlling another (compression, vocoding)
### Node Graph Architecture
```
┌─────────────────────────────────────────────────────────┐
│ Track Node Graph │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ │
│ │ Input │ (Audio clip or synthesizer) │
│ └────┬────┘ │
│ │ │
│ ├──────┬──────────────┬─────────────┐ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌─────────┐ │
│ │Filter │ │Distort │ │ EQ │ │ Reverb │ │
│ │(Node 1)│ │(Node 2)│ │(Node 3)│ │(Node 4) │ │
│ └───┬────┘ └───┬────┘ └───┬────┘ └────┬────┘ │
│ │ │ │ │ │
│ └────┬─────┴──────┬───┘ │ │
│ │ │ │ │
│ ▼ ▼ │ │
│ ┌─────────┐ ┌─────────┐ │ │
│ │ Mixer │ │Compress │ │ │
│ │(Node 5) │ │(Node 6) │◄──────────┘ │
│ └────┬────┘ └────┬────┘ (sidechain) │
│ │ │ │
│ └─────┬──────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ Output │ │
│ └──────────┘ │
│ │
└────────────────────────────────────────────────────────┘
```
### Node Types
#### Input Nodes
- **Audio Clip Reader**: Reads samples from audio file
- **Oscillator**: Generates waveforms (sine, saw, square, triangle)
- **Noise Generator**: White/pink noise
- **External Input**: Microphone or line-in
#### Processing Nodes
- **Effects**: Any audio effect (see [Adding Effects](#adding-effects))
- **Filters**: Low-pass, high-pass, band-pass, notch
- **Mixers**: Combine multiple inputs with gain control
- **Splitters**: Duplicate signal to multiple outputs
#### Output Nodes
- **Track Output**: Sends to mixer or master bus
- **Send Output**: Feeds auxiliary effects
### Building a Node Graph
```rust
use dasp_graph::{Node, NodeData, Input, BoxedNode};
use petgraph::graph::NodeIndex;
pub struct TrackGraph {
graph: dasp_graph::Graph,
input_node: NodeIndex,
output_node: NodeIndex,
}
impl TrackGraph {
pub fn new() -> Self {
let mut graph = dasp_graph::Graph::new();
// Create input and output nodes
let input_node = graph.add_node(NodeData::new1(
Input::default(),
PassThrough, // Simple input node
));
let output_node = graph.add_node(NodeData::new1(
Input::default(),
PassThrough, // Simple output node
));
Self {
graph,
input_node,
output_node,
}
}
pub fn add_effect(&mut self, effect: BoxedNode) -> NodeIndex {
// Add effect node between input and output
let effect_node = self.graph.add_node(NodeData::new1(
Input::default(),
effect,
));
// Connect: input -> effect -> output
self.graph.add_edge(self.input_node, effect_node, ());
self.graph.add_edge(effect_node, self.output_node, ());
effect_node
}
pub fn connect(&mut self, from: NodeIndex, to: NodeIndex) {
self.graph.add_edge(from, to, ());
}
pub fn process(&mut self, input: &[f32], output: &mut [f32]) {
// Set input samples
self.graph.set_input(self.input_node, input);
// Process entire graph
self.graph.process();
// Read output samples
self.graph.get_output(self.output_node, output);
}
}
```
### Example: Serial Effect Chain
Simple effects chain (the most common case):
```rust
// Input -> Distortion -> EQ -> Reverb -> Output
let mut graph = TrackGraph::new();
let distortion = graph.add_effect(Box::new(Distortion::new(0.5)));
let eq = graph.add_effect(Box::new(EQ::new()));
let reverb = graph.add_effect(Box::new(Reverb::new()));
// Connect in series
graph.connect(graph.input_node, distortion);
graph.connect(distortion, eq);
graph.connect(eq, reverb);
graph.connect(reverb, graph.output_node);
```
### Example: Parallel Processing
Split signal into parallel paths:
```rust
// Input -> Split -> [Distortion + Clean] -> Mix -> Output
let mut graph = TrackGraph::new();
// Create parallel paths
let distortion = graph.add_effect(Box::new(Distortion::new(0.7)));
let clean = graph.add_effect(Box::new(Gain::new(1.0)));
let mixer = graph.add_effect(Box::new(Mixer::new(2))); // 2 inputs
// Connect parallel paths
graph.connect(graph.input_node, distortion);
graph.connect(graph.input_node, clean);
graph.connect(distortion, mixer);
graph.connect(clean, mixer);
graph.connect(mixer, graph.output_node);
```
### Example: Modular Synthesizer
Build a synthesizer from basic components:
```rust
// ┌─ LFO ────┐ (modulation)
// │ ▼
// Oscillator -> Filter -> Envelope -> Output
let mut graph = TrackGraph::new();
// Sound source
let oscillator = graph.add_effect(Box::new(Oscillator::new(440.0)));
// Modulation source
let lfo = graph.add_effect(Box::new(LFO::new(5.0))); // 5 Hz
// Filter with LFO modulation
let filter = graph.add_effect(Box::new(Filter::new_modulated()));
// Envelope
let envelope = graph.add_effect(Box::new(ADSREnvelope::new()));
// Connect sound path
graph.connect(oscillator, filter);
graph.connect(filter, envelope);
graph.connect(envelope, graph.output_node);
// Connect modulation path
graph.connect(lfo, filter); // LFO modulates filter cutoff
```
### Example: Sidechain Compression
One signal controls another:
```rust
// Input (bass) ──────────────────┐
// ▼
// Kick drum ────> Compressor (sidechain) -> Output
let mut graph = TrackGraph::new();
// Main signal input (bass)
let bass_input = graph.add_effect(Box::new(PassThrough));
// Sidechain signal input (kick drum)
let kick_input = graph.add_effect(Box::new(PassThrough));
// Compressor with sidechain
let compressor = graph.add_effect(Box::new(SidechainCompressor::new()));
// Connect main signal
graph.connect(bass_input, compressor);
// Connect sidechain signal (port 1 = main, port 2 = sidechain)
graph.connect_to_port(kick_input, compressor, 1);
graph.connect(compressor, graph.output_node);
```
### Node Interface
All nodes implement the `dasp_graph::Node` trait:
```rust
pub trait Node {
/// Process audio for this node
fn process(&mut self, inputs: &[Input], output: &mut [f32]);
/// Number of input ports
fn num_inputs(&self) -> usize;
/// Number of output ports
fn num_outputs(&self) -> usize;
/// Reset internal state
fn reset(&mut self);
}
```
### Multi-Channel Processing
Nodes can have multiple input/output channels:
```rust
pub struct StereoEffect {
left_processor: Processor,
right_processor: Processor,
}
impl Node for StereoEffect {
fn process(&mut self, inputs: &[Input], output: &mut [f32]) {
// Split stereo input
let (left_in, right_in) = inputs[0].as_stereo();
// Process each channel
let left_out = self.left_processor.process(left_in);
let right_out = self.right_processor.process(right_in);
// Interleave output
for i in 0..left_out.len() {
output[i * 2] = left_out[i];
output[i * 2 + 1] = right_out[i];
}
}
fn num_inputs(&self) -> usize { 1 } // One stereo input
fn num_outputs(&self) -> usize { 1 } // One stereo output
fn reset(&mut self) {
self.left_processor.reset();
self.right_processor.reset();
}
}
```
### Parameter Modulation
Nodes can expose parameters for automation or modulation:
```rust
pub struct ModulatableFilter {
filter: Filter,
cutoff: f32,
resonance: f32,
}
impl Node for ModulatableFilter {
fn process(&mut self, inputs: &[Input], output: &mut [f32]) {
let audio_in = &inputs[0]; // Port 0: audio input
// Port 1 (optional): cutoff modulation
if inputs.len() > 1 {
let mod_signal = &inputs[1];
// Modulate cutoff: base + modulation
self.filter.set_cutoff(self.cutoff + mod_signal[0] * 1000.0);
}
// Process audio
self.filter.process(audio_in, output);
}
fn num_inputs(&self) -> usize { 2 } // Audio + modulation
fn num_outputs(&self) -> usize { 1 }
fn reset(&mut self) {
self.filter.reset();
}
}
```
### Graph Execution Order
`dasp_graph` automatically determines execution order using topological sort:
1. Nodes with no dependencies execute first (inputs, oscillators)
2. Nodes execute when all inputs are ready
3. Cycles are detected and prevented
4. Output nodes execute last
This ensures:
- No node processes before its inputs are ready
- Efficient CPU cache usage
- Deterministic execution
### Performance Considerations
#### Graph Overhead
Node graphs have small overhead:
- **Topological sort**: Done once when graph changes, not per-buffer
- **Buffer copying**: Minimized by reusing buffers
- **Indirection**: Virtual function calls (unavoidable with trait objects)
For simple serial chains, the overhead is negligible (<1% CPU).
#### When to Use Node Graphs vs Simple Chains
**Use node graphs when:**
- Complex routing (parallel, feedback, modulation)
- Building synthesizers from components
- User-configurable effect routing
- Sidechain processing
**Use simple chains when:**
- Just a few effects in series
- Performance is critical
- Graph structure never changes
**Note**: In Lightningbeam, audio layers always use node graphs to provide maximum flexibility for users. This allows any track to have complex routing, modular synthesis, or effect configurations without requiring different track types.
```rust
// Simple chain (no graph overhead)
pub struct SimpleChain {
effects: Vec<Box<dyn AudioEffect>>,
}
impl SimpleChain {
fn process(&mut self, buffer: &mut [f32]) {
for effect in &mut self.effects {
effect.process_in_place(buffer);
}
}
}
```
### Debugging Node Graphs
Enable graph visualization:
```rust
// Print graph structure
println!("{:?}", graph);
// Export to DOT format for visualization
let dot = graph.to_dot();
std::fs::write("graph.dot", dot)?;
// Then: dot -Tpng graph.dot -o graph.png
```
Trace signal flow:
```rust
// Add probe nodes to inspect signals
let probe = graph.add_effect(Box::new(SignalProbe::new("After Filter")));
graph.connect(filter, probe);
graph.connect(probe, output);
// Probe prints min/max/RMS of signal
```
## Adding Effects
### Effect Trait
All effects implement the `AudioEffect` trait:
```rust
pub trait AudioEffect: Send {
fn process(&mut self, input: &[f32], output: &mut [f32]);
fn process_in_place(&mut self, buffer: &mut [f32]);
fn reset(&mut self);
}
```
### Example: Simple Gain Effect
```rust
pub struct Gain {
gain: f32,
}
impl Gain {
pub fn new(gain: f32) -> Self {
Self { gain }
}
}
impl AudioEffect for Gain {
fn process(&mut self, input: &[f32], output: &mut [f32]) {
for (i, &sample) in input.iter().enumerate() {
output[i] = sample * self.gain;
}
}
fn process_in_place(&mut self, buffer: &mut [f32]) {
for sample in buffer.iter_mut() {
*sample *= self.gain;
}
}
fn reset(&mut self) {
// No state to reset for gain
}
}
```
### Example: Delay Effect (with state)
```rust
pub struct Delay {
buffer: Vec<f32>,
write_pos: usize,
delay_samples: usize,
feedback: f32,
mix: f32,
}
impl Delay {
pub fn new(sample_rate: f32, delay_time: f32, feedback: f32, mix: f32) -> Self {
let delay_samples = (delay_time * sample_rate) as usize;
let buffer_size = delay_samples.next_power_of_two();
Self {
buffer: vec![0.0; buffer_size],
write_pos: 0,
delay_samples,
feedback,
mix,
}
}
}
impl AudioEffect for Delay {
fn process_in_place(&mut self, buffer: &mut [f32]) {
for sample in buffer.iter_mut() {
// Read delayed sample
let read_pos = (self.write_pos + self.buffer.len() - self.delay_samples)
% self.buffer.len();
let delayed = self.buffer[read_pos];
// Write new sample with feedback
self.buffer[self.write_pos] = *sample + delayed * self.feedback;
self.write_pos = (self.write_pos + 1) % self.buffer.len();
// Mix dry and wet signals
*sample = *sample * (1.0 - self.mix) + delayed * self.mix;
}
}
fn reset(&mut self) {
self.buffer.fill(0.0);
self.write_pos = 0;
}
}
```
### Adding Effects to Tracks
```rust
// UI Thread
let command = AudioCommand::AddEffect {
track_id: track_id,
effect: Box::new(Delay::new(44100.0, 0.5, 0.3, 0.5)),
};
command_sender.push(command).ok();
```
### Built-In Effects
Located in `daw-backend/src/effects/`:
- **reverb.rs**: Reverb
- **delay.rs**: Delay
- **eq.rs**: Equalizer
- **compressor.rs**: Dynamic range compressor
- **distortion.rs**: Distortion/overdrive
- **chorus.rs**: Chorus
- **flanger.rs**: Flanger
- **phaser.rs**: Phaser
- **limiter.rs**: Brick-wall limiter
## Adding Synthesizers
### Synthesizer Trait
```rust
pub trait Synthesizer: Send {
fn process(&mut self, output: &mut [f32], sample_rate: f32);
fn note_on(&mut self, note: u8, velocity: u8);
fn note_off(&mut self, note: u8);
fn reset(&mut self);
}
```
### Example: Simple Oscillator
```rust
pub struct Oscillator {
phase: f32,
frequency: f32,
amplitude: f32,
sample_rate: f32,
}
impl Oscillator {
pub fn new(sample_rate: f32) -> Self {
Self {
phase: 0.0,
frequency: 440.0,
amplitude: 0.0,
sample_rate,
}
}
}
impl Synthesizer for Oscillator {
fn process(&mut self, output: &mut [f32], _sample_rate: f32) {
for sample in output.iter_mut() {
// Generate sine wave
*sample = (self.phase * 2.0 * std::f32::consts::PI).sin() * self.amplitude;
// Advance phase
self.phase += self.frequency / self.sample_rate;
if self.phase >= 1.0 {
self.phase -= 1.0;
}
}
}
fn note_on(&mut self, note: u8, velocity: u8) {
// Convert MIDI note to frequency
self.frequency = 440.0 * 2.0_f32.powf((note as f32 - 69.0) / 12.0);
self.amplitude = velocity as f32 / 127.0;
}
fn note_off(&mut self, _note: u8) {
self.amplitude = 0.0;
}
fn reset(&mut self) {
self.phase = 0.0;
self.amplitude = 0.0;
}
}
```
### Built-In Synthesizers
Located in `daw-backend/src/synth/`:
- **oscillator.rs**: Basic waveform generator (sine, saw, square, triangle)
- **fm_synth.rs**: FM synthesis
- **wavetable.rs**: Wavetable synthesis
- **sampler.rs**: Sample-based synthesis
## MIDI System
### MIDI Input
```rust
// Setup MIDI input (UI thread)
let midi_input = midir::MidiInput::new("Lightningbeam")?;
let port = midi_input.ports()[0];
midi_input.connect(&port, "input", move |_timestamp, message, _| {
// Parse MIDI message
match message[0] & 0xF0 {
0x90 => {
// Note On
let note = message[1];
let velocity = message[2];
command_sender.push(AudioCommand::NoteOn { note, velocity }).ok();
}
0x80 => {
// Note Off
let note = message[1];
command_sender.push(AudioCommand::NoteOff { note }).ok();
}
_ => {}
}
}, ())?;
```
### MIDI File Parsing
```rust
use midly::{Smf, TrackEventKind};
let smf = Smf::parse(&midi_data)?;
for track in smf.tracks {
for event in track {
match event.kind {
TrackEventKind::Midi { channel, message } => {
// Process MIDI message
}
_ => {}
}
}
}
```
## Performance Optimization
### Pre-Allocation
Allocate all buffers before audio thread starts:
```rust
// Good: Pre-allocated
pub struct Track {
buffer: Vec<f32>, // Allocated once in constructor
// ...
}
// Bad: Allocates in audio thread
fn process(&mut self) {
let mut temp = Vec::new(); // ❌ Allocates!
// ...
}
```
### Memory-Mapped Audio Files
Large audio files use memory-mapped I/O for zero-copy access:
```rust
use memmap2::Mmap;
let file = File::open(path)?;
let mmap = unsafe { Mmap::map(&file)? };
// Audio samples can be read directly from mmap
```
### SIMD Optimization
For portable SIMD operations, use the `fearless_simd` crate:
```rust
use fearless_simd::*;
fn process_simd(samples: &mut [f32], gain: f32) {
// Automatically uses best available SIMD instructions
// (SSE, AVX, NEON, etc.) without unsafe code
for chunk in samples.chunks_exact_mut(f32x8::LEN) {
let simd_samples = f32x8::from_slice(chunk);
let simd_gain = f32x8::splat(gain);
let result = simd_samples * simd_gain;
result.write_to_slice(chunk);
}
// Handle remainder
let remainder = samples.chunks_exact_mut(f32x8::LEN).into_remainder();
for sample in remainder {
*sample *= gain;
}
}
```
This approach is:
- **Portable**: Works across x86, ARM, and other architectures
- **Safe**: No unsafe code required
- **Automatic**: Uses best available SIMD instructions for the target
- **Fallback**: Gracefully degrades on platforms without SIMD
### Avoid Branching in Inner Loops
```rust
// Bad: Branch in inner loop
for sample in samples.iter_mut() {
if self.gain > 0.5 {
*sample *= 2.0;
}
}
// Good: Branch outside loop
let multiplier = if self.gain > 0.5 { 2.0 } else { 1.0 };
for sample in samples.iter_mut() {
*sample *= multiplier;
}
```
## Debugging Audio Issues
### Enable Debug Logging
```bash
DAW_AUDIO_DEBUG=1 cargo run
```
Output includes:
```
[AUDIO] Buffer size: 256 frames (5.8ms at 44100 Hz)
[AUDIO] Processing time: avg=0.8ms, worst=2.1ms
[AUDIO] Playhead: 1.234s
[AUDIO] WARNING: Audio overrun detected!
```
### Common Issues
#### Audio Dropouts
**Symptoms**: Clicks, pops, glitches in audio output
**Causes**:
- Audio callback taking too long
- Blocking operation in audio thread
- Insufficient CPU resources
**Solutions**:
- Increase buffer size (reduces CPU pressure, increases latency)
- Optimize audio processing code
- Remove debug prints from audio thread
- Check `DAW_AUDIO_DEBUG=1` output for timing info
#### Crackling/Distortion
**Symptoms**: Harsh, noisy audio
**Causes**:
- Samples exceeding [-1.0, 1.0] range (clipping)
- Incorrect sample rate conversion
- Denormal numbers in filters
**Solutions**:
- Add limiter to master output
- Use hard clipping: `sample.clamp(-1.0, 1.0)`
- Enable flush-to-zero for denormals
#### No Audio Output
**Symptoms**: Silence, but no errors
**Causes**:
- Audio device not found
- Wrong device selected
- All tracks muted
- Volume set to zero
**Solutions**:
- Check `cpal` device enumeration
- Verify track volumes and mute states
- Check master volume
- Test with simple sine wave
### Profiling Audio Performance
```bash
# Use perf on Linux
perf record --call-graph dwarf cargo run --release
perf report
# Look for hot spots in Engine::process()
```
## Related Documentation
- [ARCHITECTURE.md](../ARCHITECTURE.md) - Overall system architecture
- [docs/UI_SYSTEM.md](UI_SYSTEM.md) - UI integration with audio system
- [docs/BUILDING.md](BUILDING.md) - Build troubleshooting
Reference in New Issue View Git Blame Copy Permalink