dasp_rs/
lib.rs

1//! # DASP-RS: Digital Audio Signal Processing in Rust
2//!
3//! DASP-RS provides a collection of tools and utilities for audio signal processing,
4//! analysis, and generation. It includes functionality for handling audio input/output,
5//! performing signal transformations, generating synthetic signals, extracting audio features,
6//! working with magnitude spectra, and pitch-related operations. The library is designed
7//! to be modular and extensible, leveraging Rust's performance and safety features.
8//!
9//! ## Key Features
10//! - Audio I/O: Loading and saving audio files with flexible options.
11//! - Signal Processing: Time-frequency transforms (e.g., STFT, CQT) and filtering.
12//! - Signal Generation: Creating synthetic waveforms and noise.
13//! - Feature Extraction: Computing audio features like tempo, pitch, and spectral properties.
14//! - Magnitude Operations: Manipulating and analyzing magnitude spectra.
15//! - Pitch Utilities: Converting between frequency, MIDI, and musical notations.
16//! - Utilities: General-purpose functions for audio analysis and conversion.
17//!
18//! ## Usage
19//! To use this library, add it to your `Cargo.toml` and import the desired modules:
20//!
21//! ```toml
22//! [dependencies]
23//! dasp-rs = "0.2.0"
24//! ```
25//!
26//! ```rust
27//! // Option 1: Use prelude for convenience
28//! use dasp_rs::prelude::*;
29//! 
30//! let audio = Decoder::from("example.wav")
31//!     .sample_rate(22050)
32//!     .mono()
33//!     .load()?;
34//! 
35//! let duration = get_duration(&audio);
36//! println!("Duration: {} seconds", duration);
37//! ```
38//!
39//! ```rust
40//! // Option 2: Explicit imports for clarity
41//! use dasp_rs::{types::AudioData, io::{Decoder, export}, util::get_duration};
42//! 
43//! let audio = Decoder::from("example.wav")
44//!     .sample_rate(22050)
45//!     .mono()
46//!     .load()?;
47//! 
48//! let duration = get_duration(&audio);
49//! println!("Duration: {} seconds", duration);
50//! ```
51//!
52//! ## API Structure
53//! The API is organized by concern for clarity and discoverability:
54//! - `prelude` - Convenient imports for common use cases
55//! - `types` - Core audio data types (AudioData, AudioError)
56//! - `io` - Audio input/output operations
57//! - `proc` - Signal processing algorithms
58//! - `feat` - Audio feature extraction
59//! - `util` - Utility functions
60//! - `pitch` - Pitch detection and conversion
61//! - `mag` - Magnitude spectrum operations
62//! - `generate` - Signal generation
63
64#![warn(clippy::all, clippy::pedantic, clippy::nursery)]
65
66// Internal modules
67mod core;
68mod signal_processing;
69mod signal_generation;
70mod features;
71mod magnitude;
72mod utils;
73mod pitch_core;
74
75/// Core audio data types
76pub mod types {
77    pub use crate::core::{AudioData, AudioError};
78}
79
80/// Audio input/output operations
81pub mod io {
82    pub use crate::core::io::{load, export, stream, stream_lazy, Decoder};
83}
84
85/// Signal processing algorithms
86pub mod proc {
87    pub use crate::signal_processing::{
88        mono::*,
89        amplitude::*,
90        mixing::*,
91        panning::*,
92        resampling::*,
93        time_frequency::*,
94        time_domain::*,
95    };
96}
97
98/// Audio feature extraction
99pub mod feat {
100    pub use crate::features::{
101        harmonics::*,
102        rhythm::*,
103        manipulation::*,
104        phase_recovery::*,
105        inverse::*,
106    };
107    // Import spectral module items directly
108    pub use crate::features::spectral::*;
109}
110
111/// Magnitude spectrum operations
112pub mod mag {
113    pub use crate::magnitude::scaling::*;
114}
115
116/// Pitch detection and conversion
117pub mod pitch {
118    pub use crate::pitch_core::*;
119}
120
121/// Utility functions
122pub mod util {
123    pub use crate::utils::{
124        time::*,
125        frequency::*,
126        notation::*,
127    };
128}
129
130/// Signal generation
131pub mod generate {
132    pub use crate::signal_generation::*;
133}
134
135/// Prelude module for convenient imports.
136///
137/// This module re-exports the most commonly used types and functions
138/// to make it easier to use the library without verbose imports.
139///
140/// # Example
141/// ```rust
142/// use dasp_rs::prelude::*;
143/// 
144/// // Now you can use common items directly
145/// let audio = Decoder::from("file.wav").mono().load()?;
146/// let duration = get_duration(&audio);
147/// ```
148pub mod prelude {
149    // Core types
150    pub use crate::core::{AudioData, AudioError};
151    
152    // I/O operations
153    pub use crate::core::io::{Decoder, export};
154    
155    // Utility functions
156    pub use crate::utils::time::get_duration;
157    pub use crate::utils::frequency::{hz_to_midi, midi_to_hz};
158    
159    // Common signal processing
160    pub use crate::signal_processing::{
161        mono::to_mono,
162        resampling::resample,
163        time_frequency::stft,
164    };
165    
166    // Common features
167    pub use crate::features::{
168        harmonics::salience,
169        rhythm::tempo,
170    };
171    pub use crate::features::spectral::spectral_centroid;
172    
173    // Pitch operations
174    pub use crate::pitch_core::*;
175}
dasp_rs/lib.rs

dasp_rs/
lib.rs
