Module kira::sequence

Scripts audio events with precise timing.

Creating and starting sequences

To create a sequence, use Sequence::new() and then add the actions you want to take in order:

let mut sequence = Sequence::<()>::new(SequenceSettings::default());
// play a sound
let instance_id = sequence.play(&sound_handle, InstanceSettings::default());
// wait 2 seconds
sequence.wait(Duration::Seconds(2.0));
// stop the sound
sequence.stop_instance(instance_id, StopInstanceSettings::default());

To start the sequence, use AudioManager::start_sequence():

audio_manager.start_sequence(sequence, SequenceInstanceSettings::default())?;

Timing events

Sequences provide two ways of timing events:

• waiting for specific amounts of time
• waiting for a certain metronome interval

This sequence will play a sound at the beginning of a measure (assuming a measure is 4 beats long):

sequence.wait_for_interval(4.0);
sequence.play(&sound_handle, InstanceSettings::default());

Note that the metronome has to be running for the interval to work.

Looping sequences

You can create looping sequences by setting the loop start point. The following example will wait for the start of a measure and then play a sound every beat:

sequence.wait_for_interval(4.0);
sequence.start_loop();
// when the sequence finishes, it will loop back to this step
sequence.play(&sound_handle, InstanceSettings::default());
sequence.wait(Duration::Beats(1.0));

Custom events

Sequences can emit custom events that you can receive on the main thread, which is useful for syncing gameplay events to music events:

#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
enum CustomEvent {
	Beat,
}

sequence.wait_for_interval(4.0);
sequence.start_loop();
sequence.emit(CustomEvent::Beat);
sequence.wait(Duration::Beats(1.0));

let mut sequence_instance_handle =
	audio_manager.start_sequence(sequence, SequenceInstanceSettings::default())?;

You can retrieve events that the sequence emits using the SequenceInstanceHandle.

while let Some(event) = sequence_instance_handle.pop_event()? {
	println!("{:?}", event);
}

Modules

error	Things that can go wrong with sequences.
handle	An interface for controlling sequence instances.

Structs

Sequence	A series of steps to execute at certain times.
SequenceInstanceId	A unique identifier for an instance of a Sequence.
SequenceInstanceSettings	Settings for an instance of a Sequence.
SequenceSettings	Settings for a Sequence.

Enums

SequenceInstanceState

The playback state of an instance of a sequence.