Trait rodio::source::Source

source ·
pub trait Source: Iterator
where Self::Item: Sample,
{
Show 24 methods // Required methods fn current_frame_len(&self) -> Option<usize>; fn channels(&self) -> u16; fn sample_rate(&self) -> u32; fn total_duration(&self) -> Option<Duration>; // Provided methods fn buffered(self) -> Buffered<Self> where Self: Sized { ... } fn mix<S>(self, other: S) -> Mix<Self, S> where Self: Sized, Self::Item: FromSample<S::Item>, S: Source, S::Item: Sample { ... } fn repeat_infinite(self) -> Repeat<Self> where Self: Sized { ... } fn take_duration(self, duration: Duration) -> TakeDuration<Self> where Self: Sized { ... } fn delay(self, duration: Duration) -> Delay<Self> where Self: Sized { ... } fn skip_duration(self, duration: Duration) -> SkipDuration<Self> where Self: Sized { ... } fn amplify(self, value: f32) -> Amplify<Self> where Self: Sized { ... } fn take_crossfade_with<S: Source>( self, other: S, duration: Duration ) -> Crossfade<Self, S> where Self: Sized, Self::Item: FromSample<S::Item>, <S as Iterator>::Item: Sample { ... } fn fade_in(self, duration: Duration) -> FadeIn<Self> where Self: Sized { ... } fn periodic_access<F>( self, period: Duration, access: F ) -> PeriodicAccess<Self, F> where Self: Sized, F: FnMut(&mut Self) { ... } fn speed(self, ratio: f32) -> Speed<Self> where Self: Sized { ... } fn reverb( self, duration: Duration, amplitude: f32 ) -> Mix<Self, Delay<Amplify<Self>>> where Self: Sized + Clone { ... } fn convert_samples<D>(self) -> SamplesConverter<Self, D> where Self: Sized, D: Sample { ... } fn pausable(self, initially_paused: bool) -> Pausable<Self> where Self: Sized { ... } fn stoppable(self) -> Stoppable<Self> where Self: Sized { ... } fn skippable(self) -> Skippable<Self> where Self: Sized { ... } fn low_pass(self, freq: u32) -> BltFilter<Self> where Self: Sized + Source<Item = f32> { ... } fn high_pass(self, freq: u32) -> BltFilter<Self> where Self: Sized + Source<Item = f32> { ... } fn low_pass_with_q(self, freq: u32, q: f32) -> BltFilter<Self> where Self: Sized + Source<Item = f32> { ... } fn high_pass_with_q(self, freq: u32, q: f32) -> BltFilter<Self> where Self: Sized + Source<Item = f32> { ... }
}
Expand description

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 retrieved with channels.
  • The frequency can be retrieved with sample_rate.
  • The list of values can be retrieved 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 channels() and sample_rate too frequently.

In order to properly handle this situation, the 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.

Required Methods§

source

fn current_frame_len(&self) -> Option<usize>

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 channels() and/or sample_rate() have changed.

source

fn channels(&self) -> u16

Returns the number of channels. Channels are always interleaved.

source

fn sample_rate(&self) -> u32

Returns the rate at which the source should be played. In number of samples per second.

source

fn total_duration(&self) -> Option<Duration>

Returns the total duration of this source, if known.

None indicates at the same time “infinite” or “unknown”.

Provided Methods§

source

fn buffered(self) -> Buffered<Self>
where Self: Sized,

Stores the source in a buffer in addition to returning it. This iterator can be cloned.

source

fn mix<S>(self, other: S) -> Mix<Self, S>
where Self: Sized, Self::Item: FromSample<S::Item>, S: Source, S::Item: Sample,

Mixes this source with another one.

source

fn repeat_infinite(self) -> Repeat<Self>
where Self: Sized,

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.

source

fn take_duration(self, duration: Duration) -> TakeDuration<Self>
where Self: Sized,

Takes a certain duration of this source and then stops.

source

fn delay(self, duration: Duration) -> Delay<Self>
where Self: Sized,

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.

source

fn skip_duration(self, duration: Duration) -> SkipDuration<Self>
where Self: Sized,

Immediately skips a certain duration of this source.

If the specified duration is longer than the source itself, skip_duration will skip to the end of the source.

source

fn amplify(self, value: f32) -> Amplify<Self>
where Self: Sized,

Amplifies the sound by the given value.

source

fn take_crossfade_with<S: Source>( self, other: S, duration: Duration ) -> Crossfade<Self, S>
where Self: Sized, Self::Item: FromSample<S::Item>, <S as Iterator>::Item: Sample,

Mixes this sound fading out with another sound fading in for the given duration.

Only the crossfaded portion (beginning of self, beginning of other) is returned.

source

fn fade_in(self, duration: Duration) -> FadeIn<Self>
where Self: Sized,

Fades in the sound.

source

fn periodic_access<F>( self, period: Duration, access: F ) -> PeriodicAccess<Self, F>
where Self: Sized, F: FnMut(&mut Self),

Calls the access closure on Self the first time the source is iterated and every time period elapses.

Later changes in either sample_rate() or channels_count() won’t be reflected in the rate of access.

The rate is based on playback speed, so both the following will call access when the same samples are reached: periodic_access(Duration::from_secs(1), ...).speed(2.0) speed(2.0).periodic_access(Duration::from_secs(2), ...)

source

fn speed(self, ratio: f32) -> Speed<Self>
where Self: Sized,

Changes the play speed of the sound. Does not adjust the samples, only the play speed.

source

fn reverb( self, duration: Duration, amplitude: f32 ) -> Mix<Self, Delay<Amplify<Self>>>
where Self: Sized + Clone,

Adds a basic reverb effect.

This function requires the source to implement Clone. This can be done by using buffered().

Example
use std::time::Duration;

let source = source.buffered().reverb(Duration::from_millis(100), 0.7);
source

fn convert_samples<D>(self) -> SamplesConverter<Self, D>
where Self: Sized, D: Sample,

Converts the samples of this source to another type.

source

fn pausable(self, initially_paused: bool) -> Pausable<Self>
where Self: Sized,

Makes the sound pausable.

source

fn stoppable(self) -> Stoppable<Self>
where Self: Sized,

Makes the sound stoppable.

source

fn skippable(self) -> Skippable<Self>
where Self: Sized,

source

fn low_pass(self, freq: u32) -> BltFilter<Self>
where Self: Sized + Source<Item = f32>,

Applies a low-pass filter to the source. Warning: Probably buggy.

source

fn high_pass(self, freq: u32) -> BltFilter<Self>
where Self: Sized + Source<Item = f32>,

Applies a high-pass filter to the source.

source

fn low_pass_with_q(self, freq: u32, q: f32) -> BltFilter<Self>
where Self: Sized + Source<Item = f32>,

Applies a low-pass filter to the source while allowing the q (badnwidth) to be changed.

source

fn high_pass_with_q(self, freq: u32, q: f32) -> BltFilter<Self>
where Self: Sized + Source<Item = f32>,

Applies a high-pass filter to the source while allowing the q (badnwidth) to be changed.

Trait Implementations§

source§

impl<S> Source for Box<dyn Source<Item = S>>
where S: Sample,

source§

fn current_frame_len(&self) -> Option<usize>

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. Read more
source§

fn channels(&self) -> u16

Returns the number of channels. Channels are always interleaved.
source§

fn sample_rate(&self) -> u32

Returns the rate at which the source should be played. In number of samples per second.
source§

fn total_duration(&self) -> Option<Duration>

Returns the total duration of this source, if known. Read more
source§

fn buffered(self) -> Buffered<Self>
where Self: Sized,

Stores the source in a buffer in addition to returning it. This iterator can be cloned.
source§

fn mix<S>(self, other: S) -> Mix<Self, S>
where Self: Sized, Self::Item: FromSample<S::Item>, S: Source, S::Item: Sample,

Mixes this source with another one.
source§

fn repeat_infinite(self) -> Repeat<Self>
where Self: Sized,

Repeats this source forever. Read more
source§

fn take_duration(self, duration: Duration) -> TakeDuration<Self>
where Self: Sized,

Takes a certain duration of this source and then stops.
source§

fn delay(self, duration: Duration) -> Delay<Self>
where Self: Sized,

Delays the sound by a certain duration. Read more
source§

fn skip_duration(self, duration: Duration) -> SkipDuration<Self>
where Self: Sized,

Immediately skips a certain duration of this source. Read more
source§

fn amplify(self, value: f32) -> Amplify<Self>
where Self: Sized,

Amplifies the sound by the given value.
source§

fn take_crossfade_with<S: Source>( self, other: S, duration: Duration ) -> Crossfade<Self, S>
where Self: Sized, Self::Item: FromSample<S::Item>, <S as Iterator>::Item: Sample,

Mixes this sound fading out with another sound fading in for the given duration. Read more
source§

fn fade_in(self, duration: Duration) -> FadeIn<Self>
where Self: Sized,

Fades in the sound.
source§

fn periodic_access<F>( self, period: Duration, access: F ) -> PeriodicAccess<Self, F>
where Self: Sized, F: FnMut(&mut Self),

Calls the access closure on Self the first time the source is iterated and every time period elapses. Read more
source§

fn speed(self, ratio: f32) -> Speed<Self>
where Self: Sized,

Changes the play speed of the sound. Does not adjust the samples, only the play speed.
source§

fn convert_samples<D>(self) -> SamplesConverter<Self, D>
where Self: Sized, D: Sample,

Converts the samples of this source to another type.
source§

fn pausable(self, initially_paused: bool) -> Pausable<Self>
where Self: Sized,

Makes the sound pausable.
source§

fn stoppable(self) -> Stoppable<Self>
where Self: Sized,

Makes the sound stoppable.
source§

fn skippable(self) -> Skippable<Self>
where Self: Sized,

source§

impl<S> Source for Box<dyn Source<Item = S> + Send>
where S: Sample,

source§

fn current_frame_len(&self) -> Option<usize>

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. Read more
source§

fn channels(&self) -> u16

Returns the number of channels. Channels are always interleaved.
source§

fn sample_rate(&self) -> u32

Returns the rate at which the source should be played. In number of samples per second.
source§

fn total_duration(&self) -> Option<Duration>

Returns the total duration of this source, if known. Read more
source§

fn buffered(self) -> Buffered<Self>
where Self: Sized,

Stores the source in a buffer in addition to returning it. This iterator can be cloned.
source§

fn mix<S>(self, other: S) -> Mix<Self, S>
where Self: Sized, Self::Item: FromSample<S::Item>, S: Source, S::Item: Sample,

Mixes this source with another one.
source§

fn repeat_infinite(self) -> Repeat<Self>
where Self: Sized,

Repeats this source forever. Read more
source§

fn take_duration(self, duration: Duration) -> TakeDuration<Self>
where Self: Sized,

Takes a certain duration of this source and then stops.
source§

fn delay(self, duration: Duration) -> Delay<Self>
where Self: Sized,

Delays the sound by a certain duration. Read more
source§

fn skip_duration(self, duration: Duration) -> SkipDuration<Self>
where Self: Sized,

Immediately skips a certain duration of this source. Read more
source§

fn amplify(self, value: f32) -> Amplify<Self>
where Self: Sized,

Amplifies the sound by the given value.
source§

fn take_crossfade_with<S: Source>( self, other: S, duration: Duration ) -> Crossfade<Self, S>
where Self: Sized, Self::Item: FromSample<S::Item>, <S as Iterator>::Item: Sample,

Mixes this sound fading out with another sound fading in for the given duration. Read more
source§

fn fade_in(self, duration: Duration) -> FadeIn<Self>
where Self: Sized,

Fades in the sound.
source§

fn periodic_access<F>( self, period: Duration, access: F ) -> PeriodicAccess<Self, F>
where Self: Sized, F: FnMut(&mut Self),

Calls the access closure on Self the first time the source is iterated and every time period elapses. Read more
source§

fn speed(self, ratio: f32) -> Speed<Self>
where Self: Sized,

Changes the play speed of the sound. Does not adjust the samples, only the play speed.
source§

fn convert_samples<D>(self) -> SamplesConverter<Self, D>
where Self: Sized, D: Sample,

Converts the samples of this source to another type.
source§

fn pausable(self, initially_paused: bool) -> Pausable<Self>
where Self: Sized,

Makes the sound pausable.
source§

fn stoppable(self) -> Stoppable<Self>
where Self: Sized,

Makes the sound stoppable.
source§

fn skippable(self) -> Skippable<Self>
where Self: Sized,

source§

impl<S> Source for Box<dyn Source<Item = S> + Send + Sync>
where S: Sample,

source§

fn current_frame_len(&self) -> Option<usize>

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. Read more
source§

fn channels(&self) -> u16

Returns the number of channels. Channels are always interleaved.
source§

fn sample_rate(&self) -> u32

Returns the rate at which the source should be played. In number of samples per second.
source§

fn total_duration(&self) -> Option<Duration>

Returns the total duration of this source, if known. Read more
source§

fn buffered(self) -> Buffered<Self>
where Self: Sized,

Stores the source in a buffer in addition to returning it. This iterator can be cloned.
source§

fn mix<S>(self, other: S) -> Mix<Self, S>
where Self: Sized, Self::Item: FromSample<S::Item>, S: Source, S::Item: Sample,

Mixes this source with another one.
source§

fn repeat_infinite(self) -> Repeat<Self>
where Self: Sized,

Repeats this source forever. Read more
source§

fn take_duration(self, duration: Duration) -> TakeDuration<Self>
where Self: Sized,

Takes a certain duration of this source and then stops.
source§

fn delay(self, duration: Duration) -> Delay<Self>
where Self: Sized,

Delays the sound by a certain duration. Read more
source§

fn skip_duration(self, duration: Duration) -> SkipDuration<Self>
where Self: Sized,

Immediately skips a certain duration of this source. Read more
source§

fn amplify(self, value: f32) -> Amplify<Self>
where Self: Sized,

Amplifies the sound by the given value.
source§

fn take_crossfade_with<S: Source>( self, other: S, duration: Duration ) -> Crossfade<Self, S>
where Self: Sized, Self::Item: FromSample<S::Item>, <S as Iterator>::Item: Sample,

Mixes this sound fading out with another sound fading in for the given duration. Read more
source§

fn fade_in(self, duration: Duration) -> FadeIn<Self>
where Self: Sized,

Fades in the sound.
source§

fn periodic_access<F>( self, period: Duration, access: F ) -> PeriodicAccess<Self, F>
where Self: Sized, F: FnMut(&mut Self),

Calls the access closure on Self the first time the source is iterated and every time period elapses. Read more
source§

fn speed(self, ratio: f32) -> Speed<Self>
where Self: Sized,

Changes the play speed of the sound. Does not adjust the samples, only the play speed.
source§

fn convert_samples<D>(self) -> SamplesConverter<Self, D>
where Self: Sized, D: Sample,

Converts the samples of this source to another type.
source§

fn pausable(self, initially_paused: bool) -> Pausable<Self>
where Self: Sized,

Makes the sound pausable.
source§

fn stoppable(self) -> Stoppable<Self>
where Self: Sized,

Makes the sound stoppable.
source§

fn skippable(self) -> Skippable<Self>
where Self: Sized,

Implementations on Foreign Types§

source§

impl<S> Source for Box<dyn Source<Item = S> + Send + Sync>
where S: Sample,

source§

impl<S> Source for Box<dyn Source<Item = S> + Send>
where S: Sample,

source§

impl<S> Source for Box<dyn Source<Item = S>>
where S: Sample,

Implementors§

source§

impl Source for SineWave

source§

impl<I1, I2> Source for Mix<I1, I2>
where I1: Source, I1::Item: FromSample<I2::Item> + Sample, I2: Source, I2::Item: Sample,

source§

impl<I> Source for Amplify<I>
where I: Source, I::Item: Sample,

source§

impl<I> Source for BltFilter<I>
where I: Source<Item = f32>,

source§

impl<I> Source for Buffered<I>
where I: Source, I::Item: Sample,

source§

impl<I> Source for ChannelVolume<I>
where I: Source, I::Item: Sample,

source§

impl<I> Source for Delay<I>
where I: Iterator + Source, I::Item: Sample,

source§

impl<I> Source for Done<I>
where I: Source, I::Item: Sample,

source§

impl<I> Source for FadeIn<I>
where I: Source, I::Item: Sample,

source§

impl<I> Source for FromIter<I>
where I: Iterator, I::Item: Iterator + Source, <I::Item as Iterator>::Item: Sample,

source§

impl<I> Source for Pausable<I>
where I: Source, I::Item: Sample,

source§

impl<I> Source for Repeat<I>
where I: Iterator + Source, I::Item: Sample,

source§

impl<I> Source for SkipDuration<I>
where I: Source, I::Item: Sample,

source§

impl<I> Source for Skippable<I>
where I: Source, I::Item: Sample,

source§

impl<I> Source for Spatial<I>
where I: Source, I::Item: Sample,

source§

impl<I> Source for Speed<I>
where I: Source, I::Item: Sample,

source§

impl<I> Source for Stoppable<I>
where I: Source, I::Item: Sample,

source§

impl<I> Source for TakeDuration<I>
where I: Iterator + Source, I::Item: Sample,

source§

impl<I, D> Source for SamplesConverter<I, D>
where I: Source, I::Item: Sample, D: FromSample<I::Item> + Sample,

source§

impl<I, D> Source for UniformSourceIterator<I, D>
where I: Iterator + Source, I::Item: Sample, D: FromSample<I::Item> + Sample,

source§

impl<I, F> Source for PeriodicAccess<I, F>
where I: Source, I::Item: Sample, F: FnMut(&mut I),

source§

impl<R> Source for Decoder<R>
where R: Read + Seek,

source§

impl<R> Source for LoopedDecoder<R>
where R: Read + Seek,

source§

impl<S> Source for SamplesBuffer<S>
where S: Sample,

source§

impl<S> Source for DynamicMixer<S>
where S: Sample + Send + 'static,

source§

impl<S> Source for SourcesQueueOutput<S>
where S: Sample + Send + 'static,

source§

impl<S> Source for StaticSamplesBuffer<S>
where S: Sample,

source§

impl<S> Source for Empty<S>
where S: Sample,

source§

impl<S> Source for EmptyCallback<S>
where S: Sample,

source§

impl<S> Source for Zero<S>
where S: Sample,