naravisuals-libstd

A desktop-focused standard library for Rust, acting as a general-purpose source of truth. This library provides highly optimized, low-level utilities and high-level abstractions tailored for desktop applications, with a strong emphasis on high-performance audio processing.

🎵 Audio Engine Architecture

The audio subsystem is designed as a multi-layered pipeline, moving from low-level hardware interaction to high-level orchestration.

🏗 Layered Design

Layer 0: Hardware & Low-Level FFI

The foundation of the engine.

• Hardware I/O: Cross-platform audio stream management via cpal.
• High-Performance DSP: Optimized Fourier transforms via vendored kissfft.
• Direct Memory Manipulation: C-optimized buffer operations (e.g., Gain) via custom FFI.

Layer 1: Audio Primitives (The "Nouns")

The fundamental building blocks of sound.

• AudioSource (Planned): Generators like Oscillators and Samplers.
• AudioSink (Planned): Targets like Speakers and File Writers.
• WavWriter: High-level WAV file generation.

Layer 2: Audio Processing (The "Verbs")

Transformations applied to audio streams.

• AudioProcessor: The core trait for all DSP operations.
• Gain: Linear amplitude adjustment.
• Fft: Frequency domain analysis.
• Filters (Planned): Low-pass, High-pass, and Band-pass filters.

Layer 3: Orchestration & Management

Managing the lifecycle and flow of sound.

• AudioManager: Device discovery and enumeration.
• AudioPlayer: High-level playback management via rodio.
• AudioGraph (Planned): The orchestration layer to connect sources, processors, and sinks into a seamless pipeline.

📊 Implementation Status

Feature	Status	Implementation
Hardware I/O	✅ Complete	cpal
FFT DSP	✅ Complete	kissfft (FFI)
Gain Control	✅ Complete	Custom C-FFI
WAV I/O	✅ Complete	hound
Playback	✅ Complete	rodio
Oscillators	⏳ Planned	AudioSource Trait
Filtering	⏳ Planned	AudioProcessor Trait
Audio Graph	⏳ Planned	Graph Orchestrator
Resampling	⏳ Planned	libsamplerate

---

Module Reference

🛠 Core

• error: Unified error management.
• fs: File system helpers.
• config: Configuration management.
• sys: System information.
• utils: General purpose utilities.

🎵 Audio & DSP

• audio: High-level audio management, playback, and I/O.
  • AudioManager: Device enumeration.
  • AudioPlayer: Audio playback engine.
  • WavWriter: WAV file generation.
• dsp: Digital Signal Processing primitives.
  • AudioProcessor: Trait for audio manipulation.
  • Fft: Fast Fourier Transform.
  • Gain: Amplitude control.

🎨 Appearance

• appearance: System theme and visual state detection.

🔌 FFI & Low-Level

• ffi: Raw bindings and safe wrappers for C libraries.
• c_src: Custom C implementations for desktop operations.
• thirdparty: Vendored external C libraries.

Getting Started

Add this dependency to your Cargo.toml:

[dependencies]
naravisuals-libstd = { path = "../path/to/naravisuals-libstd" }

Example: FFT Processing

use naravisuals_libstd::{Fft, kissfft_ffi::kiss_fft_cpx};

fn main() {
    let nfft = 4;
    let fft = Fft::new(nfft).unwrap();
    
    let input = vec![
        kiss_fft_cpx { r: 1.0, i: 0.0 },
        kiss_fft_cpx { r: 1.0, i: 0.0 },
        kiss_fft_cpx { r: 1.0, i: 0.0 },
        kiss_fft_cpx { r: 1.0, i: 0.0 },
    ];
    
    let output = fft.forward(&input);
    println!("FFT Output: {:?}", output);
}

Third-Party Dependencies

This project leverages the robust Rust audio ecosystem alongside high-performance C libraries.

🦀 Rust Ecosystem Integration

We integrate several industry-standard Rust crates to provide reliable and high-level audio capabilities:

• cpal: Low-level cross-platform audio I/O.
• rodio: High-level audio playback and mixing.
• hound: WAV file reading and writing.
• serde: Serialization/deserialization for configuration.

🛠 Vendored C Libraries

For performance-critical DSP and low-level operations, we vendor optimized C libraries in the ./thirdparty directory:

• kissfft: A lightweight FFT library used for real-time DSP.
• libsamplerate (Planned): For high-quality sample rate conversion.
• libsndfile (Planned): For professional audio file I/O.

Note: The ./thirdparty directory is ignored by Git to keep the repository lightweight.