timbre 0.3.0

A library for audio processing with composable effects.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

use crate::{
    core::{AudioBuffer, AudioSource, SharedAudioSource},
    ReadResult,
};

use slotmap::{DefaultKey, DenseSlotMap};

use tracing::instrument;

/// A mixer that combines multiple [`AudioSource`](crate::AudioSource)s.
///
/// This simple mixer adds the samples from the given sources together,
/// and optionally multiplies by a coefficient to give some headroom.
///
/// # Examples
/// ```
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// # use timbre::{generators::SineWave, effects::BasicMixer, IntoShared};
/// let sin1 = SineWave::new(0.5, 440.0);
/// let sin2 = SineWave::new(0.5, 220.0);
///
/// let mut mixer = BasicMixer::new();
/// let sin1 = mixer.add_source(sin1.into_shared());
/// mixer.add_source(sin2.into_shared());
/// mixer.remove_source(sin1);
/// # Ok(())
/// # }
/// ```
#[derive(Default)]
pub struct BasicMixer {
    buffer: Vec<f32>,
    coefficient: Option<f32>,
    sources: DenseSlotMap<DefaultKey, SharedAudioSource>,
}

/// A key used to remove sources that have been added to [`BasicMixer`](crate::effects::BasicMixer).
pub struct BasicMixerSource {
    key: DefaultKey,
}

impl BasicMixer {
    /// Construct a `BasicMixer` that simply adds samples and doesn't multiply by anything.
    pub fn new() -> Self {
        BasicMixer {
            coefficient: None,
            sources: DenseSlotMap::new(),
            buffer: Vec::new(),
        }
    }

    /// Construct a `BasicMixer` that adds samples together, then multiplies by the given
    /// coefficient to reduce the chance of clipping.
    ///
    /// # Arguments
    ///
    /// * `coefficient` -- A number to multiply the final resulting samples by.
    pub fn with_coefficient(coefficient: f32) -> Self {
        BasicMixer {
            buffer: Vec::new(),
            coefficient: Some(coefficient),
            sources: DenseSlotMap::new(),
        }
    }

    /// Add a source to this mixer.
    ///
    /// # Arguments
    ///
    /// * `source` -- The audio source to add to this mixer.
    ///
    /// # Returns
    ///
    /// A key to be used in [`remove_source`](method.remove_source) to remove this source.
    pub fn add_source(&mut self, source: SharedAudioSource) -> BasicMixerSource {
        BasicMixerSource {
            key: self.sources.insert(source),
        }
    }

    /// Removes the source indicated by `source`, if present.
    ///
    /// # Examples
    /// ```
    /// # use timbre::{effects::BasicMixer, generators::SineWave, IntoShared};
    /// let sin = SineWave::new(1.0, 440.0);
    /// let mut mixer = BasicMixer::new();
    /// let sin = mixer.add_source(sin.into_shared());
    /// mixer.remove_source(sin);
    /// ```
    pub fn remove_source(&mut self, source: BasicMixerSource) {
        self.sources.remove(source.key);
    }
}

impl AudioSource for BasicMixer {
    #[instrument(name = "BasicMixer::read", skip(self, buffer))]
    fn read(&mut self, buffer: &mut AudioBuffer) -> ReadResult {
        if self.sources.is_empty() {
            buffer.samples.iter_mut().for_each(|sample| *sample = 0.0);
            return ReadResult::good(buffer.samples.len());
        }

        let mut iter = self.sources.iter_mut();
        let (_, first) = iter.next().unwrap();
        let ReadResult {
            mut read,
            state: _state,
        } = first.lock().unwrap().read(buffer);

        for (_, source) in iter {
            self.buffer.resize(buffer.samples.len(), 0.0);

            {
                let mut buffer = AudioBuffer {
                    format: buffer.format,
                    samples: &mut self.buffer[..],
                };

                let result = source.lock().unwrap().read(&mut buffer);
                read = std::cmp::max(read, result.read);
            }

            buffer
                .samples
                .iter_mut()
                .zip(self.buffer.iter())
                .for_each(|(a, b)| *a += *b);
        }

        if let Some(coef) = self.coefficient {
            buffer.samples.iter_mut().for_each(|sample| *sample *= coef);
        }

        if read < buffer.samples.len() {
            ReadResult::underrun(read)
        } else {
            ReadResult::good(buffer.samples.len())
        }
    }
}