Trait awedio::Sound

source · 
pub trait Sound: Send {

Show 18 methods    // Required methods
    fn channel_count(&self) -> u16;
    fn sample_rate(&self) -> u32;
    fn next_sample(&mut self) -> Result<NextSample, Error>;
    fn on_start_of_batch(&mut self);

    // Provided methods
    fn next_frame(&mut self) -> Result<Vec<i16>, Result<NextSample, Error>> { ... }
    fn append_next_frame_to(
        &mut self,
        samples: &mut Vec<i16>
    ) -> Result<(), Result<NextSample, Error>> { ... }
    fn into_memory_sound(self) -> Result<MemorySound, Error>
       where Self: Sized { ... }
    fn loop_from_memory(self) -> Result<MemorySound, Error>
       where Self: Sized { ... }
    fn controllable(self) -> (Controllable<Self>, Controller<Self>)
       where Self: Sized { ... }
    fn with_async_completion_notifier(
        self
    ) -> (AsyncCompletionNotifier<Self>, Receiver<()>)
       where Self: Sized { ... }
    fn with_completion_notifier(
        self
    ) -> (CompletionNotifier<Self>, Receiver<()>)
       where Self: Sized { ... }
    fn with_adjustable_volume(self) -> AdjustableVolume<Self>
       where Self: Sized { ... }
    fn with_adjustable_volume_of(
        self,
        volume_adjustment: f32
    ) -> AdjustableVolume<Self>
       where Self: Sized { ... }
    fn with_adjustable_speed(self) -> AdjustableSpeed<Self>
       where Self: Sized { ... }
    fn with_adjustable_speed_of(
        self,
        speed_adjustment: f32
    ) -> AdjustableSpeed<Self>
       where Self: Sized { ... }
    fn pausable(self) -> Pausable<Self>
       where Self: Sized { ... }
    fn paused(self) -> Pausable<Self>
       where Self: Sized { ... }
    fn finish_after(self, duration: Duration) -> FinishAfter<Self>
       where Self: Sized { ... }

}
Expand description

A provider of audio samples.

This is the foundational trait of this crate. A Box<dyn Sound> can be played on a Manager. Sounds can be wrapped to modify the inner sound, often by using helper functions of this trait (e.g. pausable).

Required Methods§

source

fn channel_count(&self) -> u16

Returns the number of channels.

source

fn sample_rate(&self) -> u32

Returns the number of samples per second for each channel for this sound (e.g. 44,100).

source

fn next_sample(&mut self) -> Result<NextSample, Error>

Retrieve the next sample or notification if something has changed. The first sample is for the first channel and the second is the for second and so on until channel_count and then wraps back to the first channel. If any NextSample variant besides Sample is returned then the following NextSample::Sample is for the first channel. If a Sound has returned Paused it is expected that the consumer will call next_sample again in the future. If a Sound has returned Finished it is not expected for the consumer to call next_sample again but if called Finished will normally be returned again. After Finished has been returned, channel_count() and sample_rate() may return different values without MetadataChanged being returned.

If an error is returned it is not specified what will happen if next_sample is called again. Individual implementations can specify which errors are recoverable if any. Most consumers will either pass the error up or log the error and stop playing the sound (e.g. SoundMixer and SoundList).

source

fn on_start_of_batch(&mut self)

Called whenever a new batch of audio samples is requested by the backend.

This is a good place to put code that needs to run fairly frequently, but not for every single audio sample.

Provided Methods§

source

fn next_frame(&mut self) -> Result<Vec<i16>, Result<NextSample, Error>>

Returns the next sample for all channels.

It is the callers responsibility to ensure this function is only called at the start of a frame (i.e. the first channel is the next to be returned from next_sample).

If an Error, Paused, Finished, or MetadataChanged are encountered while collecting samples, an Err(Ok(NextSample)) of that variant will be returned and any previously collected samples are lost. Err(Ok(NextSample::Sample)) will never be returned. If an error is encountered Err(Err(error::Error)) is returned.

source

fn append_next_frame_to( &mut self, samples: &mut Vec<i16> ) -> Result<(), Result<NextSample, Error>>

Same as next_frame but samples are appended into an existing Vec.

Any existing data is left unmodified.

source

fn into_memory_sound(self) -> Result<MemorySound, Error>
where Self: Sized,

Read the entire sound into memory. MemorySound can be cloned for efficient reuse. See MemorySound::from_sound.

source

fn loop_from_memory(self) -> Result<MemorySound, Error>
where Self: Sized,

Read the entire sound into memory and loop indefinitely.

If you do not want to read the entire sound into memory see SoundsFromFn as an alternative.

source

fn controllable(self) -> (Controllable<Self>, Controller<Self>)
where Self: Sized,

Allow this sound to be controlled after it has started playing with a Controller.

What can be controlled depends on the Sound type (e.g. set_volume).

source

fn with_async_completion_notifier( self ) -> (AsyncCompletionNotifier<Self>, Receiver<()>)
where Self: Sized,

Get notified via a tokio::sync::oneshot::Receiver when this sound has Finished.

source

fn with_completion_notifier(self) -> (CompletionNotifier<Self>, Receiver<()>)
where Self: Sized,

Get notified via a std::sync::mpsc::Receiver when this sound has Finished.

Examples found in repository?
examples/play.rs (line 10)
3
4
5
6
7
8
9
10
11
12
13
14
15
16

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let Some(file_path) = args() else {
        eprintln!("usage: FILE_PATH");
        std::process::exit(2);
    };

    let (mut manager, _backend) = awedio::start()?;
    let (sound, notifier) = awedio::sounds::open_file(file_path)?.with_completion_notifier();

    manager.play(Box::new(sound));
    let _ = notifier.recv();

    Ok(())
}
source

fn with_adjustable_volume(self) -> AdjustableVolume<Self>
where Self: Sized,

Allow the volume of the sound to be adjustable with set_volume.

source

fn with_adjustable_volume_of( self, volume_adjustment: f32 ) -> AdjustableVolume<Self>
where Self: Sized,

Allow the volume of the sound to be adjustable with set_volume and set the initial volume adjustment.

source

fn with_adjustable_speed(self) -> AdjustableSpeed<Self>
where Self: Sized,

Allow the speed of the sound to be adjustable with set_speed.

This adjusts both speed and pitch.

source

fn with_adjustable_speed_of( self, speed_adjustment: f32 ) -> AdjustableSpeed<Self>
where Self: Sized,

Allow the speed of the sound to be adjustable with set_speed and set the initial speed adjustment.

This adjusts both speed and pitch.

source

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

Allow for the sound to be pausable with set_paused. Starts unpaused.

source

fn paused(self) -> Pausable<Self>
where Self: Sized,

Allow for the sound to be pausable with set_paused. Starts paused.

source

fn finish_after(self, duration: Duration) -> FinishAfter<Self>
where Self: Sized,

Play the first duration of the sound, then finish even if samples remain.

See FinishAfter.

Trait Implementations§

source§

impl Sound for Box<dyn Sound>

source§

fn on_start_of_batch(&mut self)

Called whenever a new batch of audio samples is requested by the backend. Read more
source§

fn channel_count(&self) -> u16

Returns the number of channels.
source§

fn sample_rate(&self) -> u32

Returns the number of samples per second for each channel for this sound (e.g. 44,100).
source§

fn next_sample(&mut self) -> Result<NextSample, Error>

Retrieve the next sample or notification if something has changed. The first sample is for the first channel and the second is the for second and so on until channel_count and then wraps back to the first channel. If any NextSample variant besides Sample is returned then the following NextSample::Sample is for the first channel. If a Sound has returned Paused it is expected that the consumer will call next_sample again in the future. If a Sound has returned Finished it is not expected for the consumer to call next_sample again but if called Finished will normally be returned again. After Finished has been returned, channel_count() and sample_rate() may return different values without MetadataChanged being returned. Read more
source§

fn next_frame(&mut self) -> Result<Vec<i16>, Result<NextSample, Error>>

Returns the next sample for all channels. Read more
source§

fn append_next_frame_to( &mut self, samples: &mut Vec<i16> ) -> Result<(), Result<NextSample, Error>>

Same as next_frame but samples are appended into an existing Vec. Read more
source§

fn into_memory_sound(self) -> Result<MemorySound, Error>
where Self: Sized,

Read the entire sound into memory. MemorySound can be cloned for efficient reuse. See MemorySound::from_sound.
source§

fn loop_from_memory(self) -> Result<MemorySound, Error>
where Self: Sized,

Read the entire sound into memory and loop indefinitely. Read more
source§

fn controllable(self) -> (Controllable<Self>, Controller<Self>)
where Self: Sized,

Allow this sound to be controlled after it has started playing with a Controller. Read more
source§

fn with_async_completion_notifier( self ) -> (AsyncCompletionNotifier<Self>, Receiver<()>)
where Self: Sized,

Get notified via a tokio::sync::oneshot::Receiver when this sound has Finished.
source§

fn with_completion_notifier(self) -> (CompletionNotifier<Self>, Receiver<()>)
where Self: Sized,

Get notified via a std::sync::mpsc::Receiver when this sound has Finished.
source§

fn with_adjustable_volume(self) -> AdjustableVolume<Self>
where Self: Sized,

Allow the volume of the sound to be adjustable with set_volume.
source§

fn with_adjustable_volume_of( self, volume_adjustment: f32 ) -> AdjustableVolume<Self>
where Self: Sized,

Allow the volume of the sound to be adjustable with set_volume and set the initial volume adjustment.
source§

fn with_adjustable_speed(self) -> AdjustableSpeed<Self>
where Self: Sized,

Allow the speed of the sound to be adjustable with set_speed. Read more
source§

fn with_adjustable_speed_of( self, speed_adjustment: f32 ) -> AdjustableSpeed<Self>
where Self: Sized,

Allow the speed of the sound to be adjustable with set_speed and set the initial speed adjustment. Read more
source§

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

Allow for the sound to be pausable with set_paused. Starts unpaused.
source§

fn paused(self) -> Pausable<Self>
where Self: Sized,

Allow for the sound to be pausable with set_paused. Starts paused.
source§

fn finish_after(self, duration: Duration) -> FinishAfter<Self>
where Self: Sized,

Play the first duration of the sound, then finish even if samples remain. Read more

Implementations on Foreign Types§

source§

impl Sound for Box<dyn Sound>

source§

fn on_start_of_batch(&mut self)

source§

fn channel_count(&self) -> u16

source§

fn sample_rate(&self) -> u32

source§

fn next_sample(&mut self) -> Result<NextSample, Error>

Implementors§