pub trait Sound: Send {
Show 19 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 { ... }
fn skip(&mut self, duration: Duration) -> Result<bool, Error> { ... }
}
Expand description
Required Methods§
sourcefn channel_count(&self) -> u16
fn channel_count(&self) -> u16
Returns the number of channels.
sourcefn sample_rate(&self) -> u32
fn sample_rate(&self) -> u32
Returns the number of samples per second for each channel for this sound (e.g. 44,100).
sourcefn next_sample(&mut self) -> Result<NextSample, Error>
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
).
sourcefn on_start_of_batch(&mut self)
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§
sourcefn next_frame(&mut self) -> Result<Vec<i16>, Result<NextSample, Error>>
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.
sourcefn append_next_frame_to(
&mut self,
samples: &mut Vec<i16>,
) -> Result<(), Result<NextSample, Error>>
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.
sourcefn into_memory_sound(self) -> Result<MemorySound, Error>where
Self: Sized,
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.
sourcefn loop_from_memory(self) -> Result<MemorySound, Error>where
Self: Sized,
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.
sourcefn controllable(self) -> (Controllable<Self>, Controller<Self>)where
Self: Sized,
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).
sourcefn with_async_completion_notifier(
self,
) -> (AsyncCompletionNotifier<Self>, Receiver<()>)where
Self: Sized,
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.
sourcefn with_completion_notifier(self) -> (CompletionNotifier<Self>, Receiver<()>)where
Self: Sized,
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?
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(())
}
sourcefn with_adjustable_volume(self) -> AdjustableVolume<Self>where
Self: Sized,
fn with_adjustable_volume(self) -> AdjustableVolume<Self>where
Self: Sized,
Allow the volume of the sound to be adjustable with set_volume
.
sourcefn with_adjustable_volume_of(
self,
volume_adjustment: f32,
) -> AdjustableVolume<Self>where
Self: Sized,
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.
sourcefn with_adjustable_speed(self) -> AdjustableSpeed<Self>where
Self: Sized,
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.
sourcefn with_adjustable_speed_of(
self,
speed_adjustment: f32,
) -> AdjustableSpeed<Self>where
Self: Sized,
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.
sourcefn pausable(self) -> Pausable<Self>where
Self: Sized,
fn pausable(self) -> Pausable<Self>where
Self: Sized,
Allow for the sound to be pausable with set_paused
. Starts unpaused.
sourcefn paused(self) -> Pausable<Self>where
Self: Sized,
fn paused(self) -> Pausable<Self>where
Self: Sized,
Allow for the sound to be pausable with set_paused
. Starts paused.
sourcefn finish_after(self, duration: Duration) -> FinishAfter<Self>where
Self: Sized,
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.
sourcefn skip(&mut self, duration: Duration) -> Result<bool, Error>
fn skip(&mut self, duration: Duration) -> Result<bool, Error>
Skip the next duration
of samples.
This is done by calling next_sample repeatedly.
Returns true if all samples were successfully skipped, false if a Paused or Finished were encountered first. MetadataChanged events are handled correctly but are not returned.
Trait Implementations§
source§impl Sound for Box<dyn Sound>
impl Sound for Box<dyn Sound>
source§fn on_start_of_batch(&mut self)
fn on_start_of_batch(&mut self)
source§fn channel_count(&self) -> u16
fn channel_count(&self) -> u16
source§fn sample_rate(&self) -> u32
fn sample_rate(&self) -> u32
source§fn next_sample(&mut self) -> Result<NextSample, Error>
fn next_sample(&mut self) -> Result<NextSample, Error>
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 moresource§fn next_frame(&mut self) -> Result<Vec<i16>, Result<NextSample, Error>>
fn next_frame(&mut self) -> Result<Vec<i16>, Result<NextSample, Error>>
source§fn append_next_frame_to(
&mut self,
samples: &mut Vec<i16>,
) -> Result<(), Result<NextSample, Error>>
fn append_next_frame_to( &mut self, samples: &mut Vec<i16>, ) -> Result<(), Result<NextSample, Error>>
next_frame
but samples are appended into an existing Vec. Read moresource§fn into_memory_sound(self) -> Result<MemorySound, Error>where
Self: Sized,
fn into_memory_sound(self) -> Result<MemorySound, Error>where
Self: Sized,
source§fn loop_from_memory(self) -> Result<MemorySound, Error>where
Self: Sized,
fn loop_from_memory(self) -> Result<MemorySound, Error>where
Self: Sized,
source§fn controllable(self) -> (Controllable<Self>, Controller<Self>)where
Self: Sized,
fn controllable(self) -> (Controllable<Self>, Controller<Self>)where
Self: Sized,
Controller
. Read moresource§fn with_async_completion_notifier(
self,
) -> (AsyncCompletionNotifier<Self>, Receiver<()>)where
Self: Sized,
fn with_async_completion_notifier(
self,
) -> (AsyncCompletionNotifier<Self>, Receiver<()>)where
Self: Sized,
source§fn with_completion_notifier(self) -> (CompletionNotifier<Self>, Receiver<()>)where
Self: Sized,
fn with_completion_notifier(self) -> (CompletionNotifier<Self>, Receiver<()>)where
Self: Sized,
source§fn with_adjustable_volume(self) -> AdjustableVolume<Self>where
Self: Sized,
fn with_adjustable_volume(self) -> AdjustableVolume<Self>where
Self: Sized,
set_volume
.source§fn with_adjustable_volume_of(
self,
volume_adjustment: f32,
) -> AdjustableVolume<Self>where
Self: Sized,
fn with_adjustable_volume_of(
self,
volume_adjustment: f32,
) -> AdjustableVolume<Self>where
Self: Sized,
set_volume
and set
the initial volume adjustment.source§fn with_adjustable_speed(self) -> AdjustableSpeed<Self>where
Self: Sized,
fn with_adjustable_speed(self) -> AdjustableSpeed<Self>where
Self: Sized,
set_speed
. Read moresource§fn with_adjustable_speed_of(
self,
speed_adjustment: f32,
) -> AdjustableSpeed<Self>where
Self: Sized,
fn with_adjustable_speed_of(
self,
speed_adjustment: f32,
) -> AdjustableSpeed<Self>where
Self: Sized,
set_speed
and set
the initial speed adjustment. Read moresource§fn pausable(self) -> Pausable<Self>where
Self: Sized,
fn pausable(self) -> Pausable<Self>where
Self: Sized,
set_paused
. Starts unpaused.source§fn paused(self) -> Pausable<Self>where
Self: Sized,
fn paused(self) -> Pausable<Self>where
Self: Sized,
set_paused
. Starts paused.source§fn finish_after(self, duration: Duration) -> FinishAfter<Self>where
Self: Sized,
fn finish_after(self, duration: Duration) -> FinishAfter<Self>where
Self: Sized,
duration
of the sound, then finish even if samples
remain. Read more