Trait bevy::audio::Source

pub trait Source: Iterator
where
    Self::Item: Sample,
{
    // 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 as Iterator>::Item>,
             S: Source,
             <S as Iterator>::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>(
        self,
        other: S,
        duration: Duration
    ) -> Mix<TakeDuration<Self>, FadeIn<TakeDuration<S>>>
       where S: Source,
             Self: Sized,
             Self::Item: FromSample<<S as Iterator>::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> { ... }
}

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

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.

fn channels(&self) -> u16

Returns the number of channels. Channels are always interleaved.

fn sample_rate(&self) -> u32

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

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

fn buffered(self) -> Buffered<Self>

where Self: Sized,

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

fn mix<S>(self, other: S) -> Mix<Self, S>

where Self: Sized, Self::Item: FromSample<<S as Iterator>::Item>, S: Source, <S as Iterator>::Item: Sample,

Mixes this source with another one.

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.

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

where Self: Sized,

Takes a certain duration of this source and then stops.

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.

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.

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

where Self: Sized,

Amplifies the sound by the given value.

fn take_crossfade_with<S>( self, other: S, duration: Duration ) -> Mix<TakeDuration<Self>, FadeIn<TakeDuration<S>>>

where S: Source, Self: Sized, Self::Item: FromSample<<S as Iterator>::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.

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

where Self: Sized,

Fades in the sound.

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), ...)

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.

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);

fn convert_samples<D>(self) -> SamplesConverter<Self, D>

where Self: Sized, D: Sample,

Converts the samples of this source to another type.

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

where Self: Sized,

Makes the sound pausable.

fn stoppable(self) -> Stoppable<Self>

where Self: Sized,

Makes the sound stoppable.

fn skippable(self) -> Skippable<Self>

where Self: Sized,

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.

fn high_pass(self, freq: u32) -> BltFilter<Self>

where Self: Sized + Source<Item = f32>,

Applies a high-pass filter to the 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.

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

impl<S> Source for Box<dyn Source<Item = S>>

where S: Sample,

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.

fn channels(&self) -> u16

Returns the number of channels. Channels are always interleaved.

fn sample_rate(&self) -> u32

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

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

Returns the total duration of this source, if known.

fn buffered(self) -> Buffered<Self>

where Self: Sized,

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

fn mix<S>(self, other: S) -> Mix<Self, S>

where Self: Sized, Self::Item: FromSample<<S as Iterator>::Item>, S: Source, <S as Iterator>::Item: Sample,

Mixes this source with another one.

fn repeat_infinite(self) -> Repeat<Self>

where Self: Sized,

Repeats this source forever.

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

where Self: Sized,

Takes a certain duration of this source and then stops.

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

where Self: Sized,

Delays the sound by a certain duration.

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

where Self: Sized,

Immediately skips a certain duration of this source.

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

where Self: Sized,

Amplifies the sound by the given value.

fn take_crossfade_with<S>( self, other: S, duration: Duration ) -> Mix<TakeDuration<Self>, FadeIn<TakeDuration<S>>>

where S: Source, Self: Sized, Self::Item: FromSample<<S as Iterator>::Item>, <S as Iterator>::Item: Sample,

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

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

where Self: Sized,

Fades in the sound.

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.

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.

fn convert_samples<D>(self) -> SamplesConverter<Self, D>

where Self: Sized, D: Sample,

Converts the samples of this source to another type.

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

where Self: Sized,

Makes the sound pausable.

fn stoppable(self) -> Stoppable<Self>

where Self: Sized,

Makes the sound stoppable.

fn skippable(self) -> Skippable<Self>

where Self: Sized,

impl<S> Source for Box<dyn Source<Item = S> + Send>

where S: Sample,

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.

fn channels(&self) -> u16

Returns the number of channels. Channels are always interleaved.

fn sample_rate(&self) -> u32

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

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

Returns the total duration of this source, if known.

fn buffered(self) -> Buffered<Self>

where Self: Sized,

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

fn mix<S>(self, other: S) -> Mix<Self, S>

where Self: Sized, Self::Item: FromSample<<S as Iterator>::Item>, S: Source, <S as Iterator>::Item: Sample,

Mixes this source with another one.

fn repeat_infinite(self) -> Repeat<Self>

where Self: Sized,

Repeats this source forever.

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

where Self: Sized,

Takes a certain duration of this source and then stops.

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

where Self: Sized,

Delays the sound by a certain duration.

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

where Self: Sized,

Immediately skips a certain duration of this source.

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

where Self: Sized,

Amplifies the sound by the given value.

fn take_crossfade_with<S>( self, other: S, duration: Duration ) -> Mix<TakeDuration<Self>, FadeIn<TakeDuration<S>>>

where S: Source, Self: Sized, Self::Item: FromSample<<S as Iterator>::Item>, <S as Iterator>::Item: Sample,

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

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

where Self: Sized,

Fades in the sound.

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.

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.

fn convert_samples<D>(self) -> SamplesConverter<Self, D>

where Self: Sized, D: Sample,

Converts the samples of this source to another type.

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

where Self: Sized,

Makes the sound pausable.

fn stoppable(self) -> Stoppable<Self>

where Self: Sized,

Makes the sound stoppable.

fn skippable(self) -> Skippable<Self>

where Self: Sized,

impl<S> Source for Box<dyn Source<Item = S> + Send + Sync>

where S: Sample,

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.

fn channels(&self) -> u16

Returns the number of channels. Channels are always interleaved.

fn sample_rate(&self) -> u32

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

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

Returns the total duration of this source, if known.

fn buffered(self) -> Buffered<Self>

where Self: Sized,

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

fn mix<S>(self, other: S) -> Mix<Self, S>

where Self: Sized, Self::Item: FromSample<<S as Iterator>::Item>, S: Source, <S as Iterator>::Item: Sample,

Mixes this source with another one.

fn repeat_infinite(self) -> Repeat<Self>

where Self: Sized,

Repeats this source forever.

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

where Self: Sized,

Takes a certain duration of this source and then stops.

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

where Self: Sized,

Delays the sound by a certain duration.

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

where Self: Sized,

Immediately skips a certain duration of this source.

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

where Self: Sized,

Amplifies the sound by the given value.

fn take_crossfade_with<S>( self, other: S, duration: Duration ) -> Mix<TakeDuration<Self>, FadeIn<TakeDuration<S>>>

where S: Source, Self: Sized, Self::Item: FromSample<<S as Iterator>::Item>, <S as Iterator>::Item: Sample,

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

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

where Self: Sized,

Fades in the sound.

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.

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.

fn convert_samples<D>(self) -> SamplesConverter<Self, D>

where Self: Sized, D: Sample,

Converts the samples of this source to another type.

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

where Self: Sized,

Makes the sound pausable.

fn stoppable(self) -> Stoppable<Self>

where Self: Sized,

Makes the sound stoppable.

fn skippable(self) -> Skippable<Self>

where Self: Sized,

Implementors

impl Source for SineWave

impl<I1, I2> Source for Mix<I1, I2>

where I1: Source, <I1 as Iterator>::Item: FromSample<<I2 as Iterator>::Item> + Sample, I2: Source, <I2 as Iterator>::Item: Sample,

impl<I> Source for Amplify<I>

where I: Source, <I as Iterator>::Item: Sample,

impl<I> Source for BltFilter<I>

where I: Source<Item = f32>,

impl<I> Source for Buffered<I>

where I: Source, <I as Iterator>::Item: Sample,

impl<I> Source for ChannelVolume<I>

where I: Source, <I as Iterator>::Item: Sample,

impl<I> Source for Delay<I>

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

impl<I> Source for Done<I>

where I: Source, <I as Iterator>::Item: Sample,

impl<I> Source for FadeIn<I>

where I: Source, <I as Iterator>::Item: Sample,

impl<I> Source for FromIter<I>

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

impl<I> Source for Pausable<I>

where I: Source, <I as Iterator>::Item: Sample,

impl<I> Source for Repeat<I>

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

impl<I> Source for SkipDuration<I>

where I: Source, <I as Iterator>::Item: Sample,

impl<I> Source for Skippable<I>

where I: Source, <I as Iterator>::Item: Sample,

impl<I> Source for Spatial<I>

where I: Source, <I as Iterator>::Item: Sample,

impl<I> Source for Speed<I>

where I: Source, <I as Iterator>::Item: Sample,

impl<I> Source for Stoppable<I>

where I: Source, <I as Iterator>::Item: Sample,

impl<I> Source for TakeDuration<I>

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

impl<I, D> Source for SamplesConverter<I, D>

where I: Source, <I as Iterator>::Item: Sample, D: FromSample<<I as Iterator>::Item> + Sample,

impl<I, D> Source for UniformSourceIterator<I, D>

where I: Iterator + Source, <I as Iterator>::Item: Sample, D: FromSample<<I as Iterator>::Item> + Sample,

impl<I, F> Source for PeriodicAccess<I, F>

where I: Source, <I as Iterator>::Item: Sample, F: FnMut(&mut I),

impl<R> Source for Decoder<R>

where R: Read + Seek,

impl<R> Source for LoopedDecoder<R>

where R: Read + Seek,

impl<S> Source for SamplesBuffer<S>

where S: Sample,

impl<S> Source for DynamicMixer<S>

where S: Sample + Send + 'static,

impl<S> Source for SourcesQueueOutput<S>

where S: Sample + Send + 'static,

impl<S> Source for Empty<S>

where S: Sample,

impl<S> Source for EmptyCallback<S>

where S: Sample,

impl<S> Source for Zero<S>

where S: Sample,

impl<S> Source for StaticSamplesBuffer<S>

where S: Sample,

impl<S> Source for Box<dyn Source<Item = S> + Send + Sync>

where S: Sample,

impl<S> Source for Box<dyn Source<Item = S> + Send>

where S: Sample,

impl<S> Source for Box<dyn Source<Item = S>>

where S: Sample,