ringkernel_audio_fft/
lib.rs

1//! # RingKernel Audio FFT
2//!
3//! GPU-accelerated audio FFT processing with direct/ambience signal separation
4//! using the RingKernel persistent actor model.
5//!
6//! ## Architecture
7//!
8//! This crate implements a novel approach to audio processing where each FFT frequency
9//! bin is represented as an independent GPU actor. These actors communicate with their
10//! neighbors via K2K (kernel-to-kernel) messaging to perform coherence analysis and
11//! separate direct sound from room ambience.
12//!
13//! ```text
14//! Audio Input -> FFT -> [Bin Actors with K2K] -> Separation -> Mixer -> IFFT -> Output
15//!                            |   |   |
16//!                          neighbor links
17//! ```
18//!
19//! ## Signal Separation Algorithm
20//!
21//! The separation is based on inter-bin coherence analysis:
22//! - **Direct signal**: High phase coherence between neighboring bins (transient, localized)
23//! - **Ambience**: Low phase coherence, diffuse energy distribution
24//!
25//! Each bin actor:
26//! 1. Receives its FFT data (magnitude + phase)
27//! 2. Exchanges data with left/right neighbors via K2K
28//! 3. Computes coherence metrics
29//! 4. Separates into direct and ambient components
30//!
31//! ## Example
32//!
33//! ```ignore
34//! use ringkernel_audio_fft::prelude::*;
35//!
36//! #[tokio::main]
37//! async fn main() -> Result<()> {
38//!     // Create the audio FFT processor
39//!     let processor = AudioFftProcessor::builder()
40//!         .fft_size(2048)
41//!         .hop_size(512)
42//!         .sample_rate(44100)
43//!         .build()
44//!         .await?;
45//!
46//!     // Load audio file
47//!     let input = AudioInput::from_file("input.wav")?;
48//!
49//!     // Process with dry/wet control
50//!     let output = processor
51//!         .process(input)
52//!         .dry_wet(0.5)       // 50% wet (ambience)
53//!         .gain_boost(1.2)    // 20% gain boost
54//!         .run()
55//!         .await?;
56//!
57//!     // Write output
58//!     output.direct.write_to_file("direct.wav")?;
59//!     output.ambience.write_to_file("ambience.wav")?;
60//!
61//!     Ok(())
62//! }
63//! ```
64
65#![warn(missing_docs)]
66#![warn(clippy::all)]
67
68pub mod audio_input;
69pub mod bin_actor;
70pub mod error;
71pub mod fft;
72pub mod messages;
73pub mod mixer;
74pub mod processor;
75pub mod separation;
76
77/// Prelude module for convenient imports.
78pub mod prelude {
79    pub use crate::audio_input::{AudioInput, AudioOutput, AudioSource, DeviceStream, FileSource};
80    pub use crate::bin_actor::{BinActor, BinActorHandle, BinNetwork};
81    pub use crate::error::{AudioFftError, Result};
82    pub use crate::fft::{FftProcessor, IfftProcessor, WindowFunction};
83    pub use crate::messages::*;
84    pub use crate::mixer::{DryWetMixer, MixerConfig};
85    pub use crate::processor::{AudioFftProcessor, AudioFftProcessorBuilder, ProcessingOutput};
86    pub use crate::separation::{CoherenceAnalyzer, SeparationConfig, SignalSeparator};
87}
88
89// Re-exports
90pub use error::{AudioFftError, Result};
91pub use processor::{AudioFftProcessor, AudioFftProcessorBuilder, ProcessingOutput};
ringkernel_audio_fft/lib.rs

ringkernel_audio_fft/
lib.rs
