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 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221
//! Sources of sound and various filters. use std::time::Duration; use Sample; pub use self::amplify::Amplify; pub use self::buffered::Buffered; pub use self::delay::Delay; pub use self::empty::Empty; pub use self::fadein::FadeIn; pub use self::mix::Mix; pub use self::pausable::Pausable; pub use self::repeat::Repeat; pub use self::samples_converter::SamplesConverter; pub use self::sine::SineWave; pub use self::speed::Speed; pub use self::stoppable::Stoppable; pub use self::take::TakeDuration; pub use self::uniform::UniformSourceIterator; pub use self::volume_filter::VolumeFilter; pub use self::zero::Zero; mod amplify; mod buffered; mod delay; mod empty; mod fadein; mod mix; mod pausable; mod repeat; mod samples_converter; mod sine; mod speed; mod stoppable; mod take; mod uniform; mod volume_filter; mod zero; /// A source of samples. /// /// # A quick lesson about sounds /// /// ## Sampling /// /// A sound is a vibration that propagates through air and reaches your ears. This vibration can /// be represented as an analog signal. /// /// In order to store this signal in the computer's memory or on the disk, we perform what is /// called *sampling*. The consists in choosing an interval of time (for example 20µs) and reading /// the amplitude of the signal at each interval (for example, if the interval is 20µs we read the /// amplitude every 20µs). By doing so we obtain a list of numerical values, each value being /// called a *sample*. /// /// Therefore a sound can be represented in memory by a frequency and a list of samples. The /// frequency is expressed in hertz and corresponds to the number of samples that have been /// read per second. For example if we read one sample every 20µs, the frequency would be /// 50000 Hz. In reality, common values for the frequency are 44100, 48000 and 96000. /// /// ## Channels /// /// But a frequency and a list of values only represent one signal. When you listen to a sound, /// your left and right ears don't receive exactly the same signal. In order to handle this, /// we usually record not one but two different signals: one for the left ear and one for the right /// ear. We say that such a sound has two *channels*. /// /// Sometimes sounds even have five or six channels, each corresponding to a location around the /// head of the listener. /// /// The standard in audio manipulation is to *interleave* the multiple channels. In other words, /// in a sound with two channels the list of samples contains the first sample of the first /// channel, then the first sample of the second channel, then the second sample of the first /// channel, then the second sample of the second channel, and so on. The same applies if you have /// more than two channels. The rodio library only supports this schema. /// /// Therefore in order to represent a sound in memory in fact we need three characteristics: the /// frequency, the number of channels, and the list of samples. /// /// ## The `Source` trait /// /// A Rust object that represents a sound should implement the `Source` trait. /// /// The three characteristics that describe a sound are provided through this trait: /// /// - The number of channels can be retreived with `get_channels`. /// - The frequency can be retreived with `get_samples_rate`. /// - The list of values can be retreived by iterating on the source. The `Source` trait requires /// that the `Iterator` trait be implemented as well. /// /// # Frames /// /// The samples rate and number of channels of some sound sources can change by itself from time /// to time. /// /// > **Note**: As a basic example, if you play two audio files one after the other and treat the /// > whole as a single source, then the channels and samples rate of that source may change at the /// > transition between the two files. /// /// However, for optimization purposes rodio supposes that the number of channels and the frequency /// stay the same for long periods of time and avoids calling `get_channels()` and /// `get_samples_rate` too frequently. /// /// In order to properly handle this situation, the `get_current_frame_len()` method should return /// the number of samples that remain in the iterator before the samples rate and number of /// channels can potentially change. /// pub trait Source: Iterator where Self::Item: Sample { /// Returns the number of samples before the current frame ends. `None` means "infinite" or /// "until the sound ends". /// Should never return 0 unless there's no more data. /// /// After the engine has finished reading the specified number of samples, it will check /// whether the value of `get_channels()` and/or `get_samples_rate()` have changed. fn get_current_frame_len(&self) -> Option<usize>; /// Returns the number of channels. Channels are always interleaved. fn get_channels(&self) -> u16; /// Returns the rate at which the source should be played. In number of samples per second. fn get_samples_rate(&self) -> u32; /// Returns the total duration of this source, if known. /// /// `None` indicates at the same time "infinite" or "unknown". fn get_total_duration(&self) -> Option<Duration>; /// Stores the source in a buffer in addition to returning it. This iterator can be cloned. #[inline] fn buffered(self) -> Buffered<Self> where Self: Sized { buffered::buffered(self) } /// Mixes this source with another one. #[inline] fn mix<S>(self, other: S) -> Mix<Self, S> where Self: Sized, S: Source, S::Item: Sample { mix::mix(self, other) } /// Repeats this source forever. /// /// Note that this works by storing the data in a buffer, so the amount of memory used is /// proportional to the size of the sound. #[inline] fn repeat_infinite(self) -> Repeat<Self> where Self: Sized { repeat::repeat(self) } /// Takes a certain duration of this source and then stops. #[inline] fn take_duration(self, duration: Duration) -> TakeDuration<Self> where Self: Sized { take::take_duration(self, duration) } /// Delays the sound by a certain duration. /// /// The rate and channels of the silence will use the same format as the first frame of the /// source. #[inline] fn delay(self, duration: Duration) -> Delay<Self> where Self: Sized { delay::delay(self, duration) } /// Amplifies the sound by the given value. #[inline] fn amplify(self, value: f32) -> Amplify<Self> where Self: Sized { amplify::amplify(self, value) } /// Fades in the sound. #[inline] fn fade_in(self, duration: Duration) -> FadeIn<Self> where Self: Sized { fadein::fadein(self, duration) } /// Changes the play speed of the sound. Does not adjust the samples, only the play speed. #[inline] fn speed(self, ratio: f32) -> Speed<Self> where Self: Sized { speed::speed(self, ratio) } /// Adds a basic reverb effect. /// /// This function requires the source to implement `Clone`. This can be done by using /// `buffered()`. /// /// # Example /// /// ```ignore /// use std::time::Duration; /// /// let source = source.buffered().reverb(Duration::from_millis(100), 0.7); /// ``` #[inline] fn reverb(self, duration: Duration, amplitude: f32) -> Mix<Self, Delay<Amplify<Self>>> where Self: Sized + Clone { let echo = self.clone().amplify(amplitude).delay(duration); self.mix(echo) } }