Crate kira 

Kira

Kira is a backend-agnostic library to create expressive audio for games. It provides tweens for smoothly adjusting properties of sounds, a flexible mixer for applying effects to audio, a clock system for precisely timing audio events, and spatial audio support.

To get started, create an AudioManager and use it to play a StaticSoundData or StreamingSoundData.

Examples

Playing a sound multiple times simultaneously:

use kira::{
	AudioManager, AudioManagerSettings, DefaultBackend,
	sound::static_sound::{StaticSoundData, StaticSoundSettings},
};

// Create an audio manager. This plays sounds and manages resources.
let mut manager = AudioManager::<DefaultBackend>::new(AudioManagerSettings::default())?;
let sound_data = StaticSoundData::from_file("sound.ogg")?;
manager.play(sound_data.clone())?;
// After a couple seconds...
manager.play(sound_data.clone())?;
// Cloning the sound data will not use any extra memory.

Gradually speeding up a sound over time:

use std::time::Duration;

use kira::{
	AudioManager, AudioManagerSettings, DefaultBackend,
	sound::static_sound::{StaticSoundData, StaticSoundSettings},
	Tween,
};

let mut manager = AudioManager::<DefaultBackend>::new(AudioManagerSettings::default())?;
let sound_data = StaticSoundData::from_file("sound.ogg")?;
let mut sound = manager.play(sound_data)?;
// Start smoothly adjusting the playback rate parameter.
sound.set_playback_rate(
	2.0,
	Tween {
		duration: Duration::from_secs(3),
		..Default::default()
	},
);

Playing a sound with a low-pass filter applied (this makes the audio sound muffled):

use kira::{
	AudioManager, AudioManagerSettings, DefaultBackend,
	sound::static_sound::{StaticSoundData, StaticSoundSettings},
	track::TrackBuilder,
	effect::filter::FilterBuilder,
};

let mut manager = AudioManager::<DefaultBackend>::new(AudioManagerSettings::default())?;
// Create a mixer sub-track with a filter.
let mut track = manager.add_sub_track({
	let mut builder = TrackBuilder::new();
	builder.add_effect(FilterBuilder::new().cutoff(1000.0));
	builder
})?;
// Play the sound on the track.
let sound_data = StaticSoundData::from_file("sound.ogg")?;
track.play(sound_data)?;

Playing sounds in time with a musical beat:

use kira::{
	AudioManager, AudioManagerSettings, DefaultBackend,
	sound::static_sound::{StaticSoundData, StaticSoundSettings},
	clock::ClockSpeed,
};

const TEMPO: f64 = 120.0;

let mut manager = AudioManager::<DefaultBackend>::new(AudioManagerSettings::default())?;
// Create a clock that ticks 120 times per second. In this case,
// each tick is one musical beat. We can use a tick to represent any
// arbitrary amount of time.
let mut clock = manager.add_clock(ClockSpeed::TicksPerMinute(TEMPO))?;
// Play a sound 2 ticks (beats) from now.
let sound_data_1 = StaticSoundData::from_file("sound1.ogg")?
	.start_time(clock.time() + 2);
manager.play(sound_data_1)?;
// Play a different sound 4 ticks (beats) from now.
let sound_data_2 = StaticSoundData::from_file("sound2.ogg")?
	.start_time(clock.time() + 4);
manager.play(sound_data_2)?;
// Start the clock.
clock.start();

Features

The Kira crate has the following feature flags:

• cpal (enabled by default) - enables the cpal backend and makes it the default for audio managers. This allows Kira to talk to the operating system to output audio. Most users should leave this enabled.
• symphonia (enabled by default) - allows loading and streaming audio from common audio formats, like MP3 and WAV.
  • Audio formats: aiff, caf, isomp4, mkv, ogg, wav - these correspond to the Symphonia features of the same name
  • Audio codecs: aac, adpcm, alac, he-aac, he-aac-v2, flac, mp1, mp2, mp3, mpa, opus', pcm, vorbis, wavpack` - these correspond to the Symphonia features of the same name
  • mp3, ogg, vorbis, flac, wav, and pcm are enabled by default.
  • See Symphonia’s documentation for more information about these flags.
• serde - adds Serialize and Deserialize implementations for the following types:
  • Capacities
  • ClockSpeed
  • DistortionKind
  • Easing
  • EndPosition
  • EqFilterKind
  • FilterMode
  • Frame
  • Mapping
  • PlaybackPosition
  • PlaybackRate
  • PlaybackState
  • Region
  • Decibels
  • Waveform
• assert_no_alloc - uses the assert_no_alloc crate to cause panics if memory is allocated or deallocated on the audio thread. This is mainly useful for people developing Kira itself.

Performance using the dev profile

By default, Rust programs run with the dev profile are not optimized. This can lead to poor performance of audio playback and long loading times for audio files. You can alleviate this by building Kira and its audio-related dependencies with a higher optimization level. Add the following to your Cargo.toml:

[profile.dev.package.kira]
opt-level = 3

[profile.dev.package.cpal]
opt-level = 3

[profile.dev.package.symphonia]
opt-level = 3

[profile.dev.package.symphonia-bundle-mp3]
opt-level = 3

[profile.dev.package.symphonia-format-ogg]
opt-level = 3

[profile.dev.package.symphonia-codec-vorbis]
opt-level = 3

[profile.dev.package.symphonia-bundle-flac]
opt-level = 3

[profile.dev.package.symphonia-format-wav]
opt-level = 3

[profile.dev.package.symphonia-codec-pcm]
opt-level = 3

You can also build all of your projects with a higher optimization level by using this snippet instead:

[profile.dev.package."*"]
opt-level = 3

Building dependencies with a higher optimization level does increase compile times, but only when compiling your project from scratch. If you only make changes to your crate, you’re not recompiling the dependencies, so you don’t suffer from the longer compilation step in that case. Building dependencies optimized and the main crate unoptimized can be a good balance of performance and compile times for games.

Re-exports

pub use backend::DefaultBackend;

pub use pastey;

Modules

backend

Communication between Kira and a low-level audio API.

clock

Precise timing for audio events.

command

Helpers for sending commands from the gameplay thread to the audio thread. You’ll only need to use this if you’re making your own implementation of Sound, Effect, or Modulator.

effect

Modifies audio signals.

info

Types for providing info about resources to trait implementors.

listener

Types related to spatial listeners.

modulator

Global values that parameters (like volume and playback rate) can be linked to.

sound

Sources of audio.

track

Organizes and applies effects to audio.

Macros

command_writers_and_readers

Creates a set of command writers and readers and a constructor for them. You’ll only need to use this if you’re making your own implementation of Sound, Effect, or Modulator.

Structs

AudioManager

Controls audio from gameplay code.

AudioManagerSettings

Settings for an AudioManager.

Capacities

Specifies how many of each resource type an audio context can have.

Decibels

Represents a change in volume.

Frame

A stereo audio sample.

Mapping

A transformation from a modulator’s value to a parameter value.

Mix

An amount to blend the “dry” and “wet” outputs from an effect.

Panning

The stereo positioning of a sound.

Parameter

Manages and updates a value that can be smoothly transitioned and linked to modulators.

PlaybackRate

How quickly a sound should be played, where 1.0 is the default playback rate.

ResourceLimitReached

An error that is returned when a resource cannot be added because the maximum capacity for that resource has been reached.

Semitones

A change in pitch in semitones.

Tween

Describes a smooth transition between values.

Enums

Easing

Curves the motion of a Tween.

PlaySoundError

Errors that can occur when playing a sound.

StartTime

Describes when an action should occur.

Value

A value that a parameter can be linked to.

Traits

Tweenable

A trait for types that can be smoothly interpolated.

Functions

interpolate_frame

Given a previous frame, a current frame, the two next frames, and a position x from 0.0 to 1.0 between the current frame and next frame, get an approximated frame.