Module kira::arrangement

Combines individual sounds into larger pieces.

Arrangements are containers of SoundClips, which are portions of a sound that can be positioned in time, stretched, trimmed, and reversed. You can play instances of an arrangement just like you would play instances of a sound.

Arrangements are a lot like arrangement views in DAWs, like the playlist view in FL Studio. In fact, the playlist view in FL Studio will be used to illustrate the contents of Arrangements in the following examples.

This image represents an arrangement that plays the same sound four times: once normally, once trimmed, once stretched out, and once reversed.

Motivating example: seamless loops

Oftentimes, game composers need to write pieces that loop forever. These pieces may also have an intro section that plays once before the main part of the song loops forever. Instances allow you to set a loop start point so when the playback position reaches the end, it jumps back to an arbitrary point in the sound.

The problem is this doesn’t account for parts of the sound that bleed into the next section. For example, at the end of an orchestral piece, there may be a cymbal swell that transitions the song back to the beginning of the loop. To preserve the musical timing of the piece, the playback position needs to jump back to the start point as soon as the last measure of music ends, which would cut off the cymbal, creating a jarring sound. If the song has an intro section with trailing sound, then that sound will cut in when the song loops, which is also jarring.

There’s a couple possible solutions:

• Use a Sequence to play separate intro and loop sounds at the right time. This works, but you can’t reverse or change the playback rate of a sequence, which you may want in some circumstances.
• You can edit your intro and loop audio in a specific way to create a larger piece that will seamlessly loop. This is tedious, and you have to store a larger audio as part of the game’s assets.

Arrangements let you use the latter solution without having to store a larger audio file, and as you’ll see, they can do the work of setting up seamless loops for you.

Setting up a simple loop

Let’s say we have a short drum loop with a cymbal swell at the end that will act as a transition as we go back to the beginning of the loop.

We can set up a seamless loop by placing the same sound in an arrangement twice, once with the cymbal swell preserved and once with it cut off. The red region at the top shows the portion of the arrangement that will be looped.

When the playback position jumps back to the loop point, the trailing sound from the first sound clip will seamlessly connect to the trailing sound that was cut off from the second clip.

You can set up this arrangement manually:

let tempo = Tempo(140.0);
let mut arrangement = Arrangement::new(
	ArrangementSettings::new().default_loop_start(tempo.beats_to_seconds(16.0)),
);
arrangement
	.add_clip(SoundClip::new(&sound_handle, 0.0))
	.add_clip(
		SoundClip::new(&sound_handle, tempo.beats_to_seconds(16.0))
			.trim(tempo.beats_to_seconds(16.0)),
	);

Or you can just use Arrangement::new_loop, which will do the work for you:

let tempo = Tempo(140.0);
let sound_handle = audio_manager.add_sound(Sound::from_file(
	std::env::current_dir()?.join("assets/loop.wav"),
	SoundSettings {
		semantic_duration: Some(tempo.beats_to_seconds(16.0)),
		..Default::default()
	},
)?)?;
let arrangement = Arrangement::new_loop(&sound_handle, LoopArrangementSettings::default());

Loops with intros

Loops with intros can be set up in a similar way:

For brevity, we’ll just say you can use Arrangement::new_loop_with_intro to create these.

Modules

handle

An interface for controlling arrangements.

Structs

Arrangement	An arrangement of sound clips to play at specific times.
ArrangementId	A unique identifier for an Arrangement.
ArrangementSettings	Settings for an Arrangement.
LoopArrangementSettings	Settings for a looping Arrangement.
SoundClip	A segment of a sound in an arrangement.