Struct riddle_audio::ClipPlayer

pub struct ClipPlayer { /* fields omitted */ }

Handles playback of a Clip with support for pausing, resuming, volume adjustment.

Instances can be built using a ClipPlayerBuilder.

Example

let bytes = include_bytes!("../../example_assets/boop.wav");
let clip = Clip::new(&bytes[..])?;

// Play the clip
let mut player = ClipPlayerBuilder::new(&audio_system).play(&clip)?;
player.set_volume(0.5);

Implementations

impl ClipPlayer

pub fn fade_volume(&mut self, volume: f32, duration: Duration)

Fade the volume from the current volume to the targat volume over time.

Once the volume has been changed the nominal volume will be immediately set to the new goal volume, as that is the volume that the player will be set to if it gets paused and resumed.

The observed volume will change over time as the AudioSubsystem progresses the fade.

If another volume fade is started while one is in progress the existing one is replaced by the new one, starting from whatever the current volume is.

Since ClipPlayer::set_volume, ClipPlayer::stop, ClipPlayer::pause and ClipPlayer::resume calls also trigger a fade to avoid popping, calling any of those methods will also replace any current fade.

Example

// The player starts with all volumes at 1.0
let mut player = ClipPlayerBuilder::new(&audio_system).play(&clip)?;
assert_eq!(1.0, player.get_nominal_volume());
assert_eq!(1.0, player.get_observed_volume());

// The nominal volume changes immediately, the observed volume hasn't changed
player.fade_volume(0.0, std::time::Duration::from_secs(1));
assert_eq!(0.0, player.get_nominal_volume());
assert_eq!(1.0, player.get_observed_volume());

// A few seconds later
// The fade has completed and the nominal and observed volumes agree again
assert_eq!(0.0, player.get_nominal_volume());
assert_eq!(0.0, player.get_observed_volume());

pub fn set_volume(&mut self, volume: f32)

Set the volume of playback immediately.

This performs a very quick fade to the destination volume, to avoid popping audio artefacts.

See the example in ClipPlayer::fade_volume for more details of how volume changes over time.

pub fn get_nominal_volume(&self) -> f32

Get the nominal volume of the player, which may not match the volume the player is currently playing at this second.

This is the volume last set via ClipPlayer::set_volume or ClipPlayer::fade_volume. This is the volume the player will be at if it is paused and resumed.

See the example in ClipPlayer::fade_volume for more details of how volume changes over time.

pub fn get_observed_volume(&self) -> f32

Get the observed volume of the player, which is always equal to exactly the volume of playback.

This is the volume of playback at this moment in time, which could be either equal to the nominal volume, or another volume if there is a fade running or if the player has been paused (which causes an observed fade to 0 volume).

See the example in ClipPlayer::fade_volume for more details of how volume changes over time.

pub fn pause(&mut self)

Pauses playback of the clip.

This performs a very quick fade to zero volume, to avoid popping audio artefacts, and then pauses playback.

The nominal volume of the player won't change, but the observed volume will drop to zero.

Example

// The player starts with all volumes at 1.0
let mut player = ClipPlayerBuilder::new(&audio_system).play(&clip)?;
assert_eq!(1.0, player.get_nominal_volume());
assert_eq!(1.0, player.get_observed_volume());

// Pausing doesn't change the nominal volume
player.pause();
assert_eq!(1.0, player.get_nominal_volume());
assert_eq!(1.0, player.get_observed_volume());

// A short moment later
// The pause has completed and the observed volume is now 0.0
assert_eq!(1.0, player.get_nominal_volume());
assert_eq!(0.0, player.get_observed_volume());

pub fn resume(&mut self)

Example

// The paused player starts with an observed volume of 0.0
let mut player = ClipPlayerBuilder::new(&audio_system).paused(&clip)?;
assert_eq!(1.0, player.get_nominal_volume());
assert_eq!(0.0, player.get_observed_volume());

// Resuming doesn't change the nominal volume
player.resume();
assert_eq!(1.0, player.get_nominal_volume());
assert_eq!(0.0, player.get_observed_volume());

// A short moment later
// The resume has completed and the observed volume is now 1.0
assert_eq!(1.0, player.get_nominal_volume());
assert_eq!(1.0, player.get_observed_volume());

pub fn stop(self)

Stops playback.

This is equivalent to calling ClipPlayer::pause and then dropping the player after the fade is complete