Module kira::sequence

Provides an interface to script timed audio events.

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_id, 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_id, 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_id, 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 (id, mut event_receiver) = audio_manager.start_sequence(sequence, SequenceInstanceSettings::default())?;

When you start a sequence, an EventReceiver is returned that you can pop events from:

#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
enum CustomEvent {
	Beat,
}
while let Some(event) = event_receiver.pop() {
	println!("{:?}", event);
}

Structs

EventReceiver	Receives events from an instance of a Sequence.
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.