Tesselode Kira Versions Save

• Fix crackling on Mac OS when multiple applications are playing audio
• Update cpal to 0.15.1

• Update cpal to 0.14.1
• Update ringbuf to 0.3.1
• Implement PartialEq for StaticSoundData, DistortionKind, DistortionBuilder, FilterMode, FilterBuilder, PanningControlBuilder, ReverbBuilder, VolumeControlBuilder, and TrackRoutes
• Implement Debug for StaticSoundData and TrackRoutes
• Implement Clone for TrackRoutes

This is a bugfix release, but unfortunately one of the bugfixes did require a breaking change. Fortunately, this breaking change only affects people who have created their own Sound or Effect implementations, which is not the most common use case.

Fixes:

• Fix a panic when starting a StaticSound with a start position later than the end of the sound
• Fix negative start positions getting rounded up to 0.0. Now sounds played with negative start positions will output silence until the position reaches 0.0, at which point normal playback will resume. This is the behavior from versions 0.5.x and prior, and it was not meant to change in 0.6.x.
• Streaming sounds will no longer stop after they encounter an error, allowing them to recover from non-fatal errors and continue playback
• Fix a bug where if a sound was played with the start time set to a clock time, and the clock time had already passed by the time the sound was played, it would not start until the next tick of that clock

Breaking changes (only for Sound and Effect implementations):

• Removed the on_clock_tick callback from Sound, Effect, and Tweener
• Instead, Sound::process, Effect::process, and Tweener::update receive a &ClockInfoProvider argument. ClockInfoProvider can report the current state of any active clock.

• Added ClockHandle::fractional_position
• Added StaticSoundData::with_settings and StaticSoundData::with_modified_settings
• Changed the following functions to take &self arguments instead of &mut self (thanks @nobbele!):
  • ClockHandle::set_speed
  • ClockHandle::start
  • ClockHandle::pause
  • ClockHandle::stop
  • AudioManager::pause
  • AudioManager::resume
  • TrackHandle::set_volume
  • TrackHandle::set_route

Kira v0.6 is a complete rewrite of Kira with the following goals:

• Make the API more elegant
• Make the library leaner by removing features that weren't pulling their weight
• Provide a solid technical foundation for future feature development

Of course, the overall goals of Kira are the same: provide a library that fills missing niches in most audio libraries and enables people to be creative with their game audio.

Streaming sounds

Kira now supports streaming sounds! Unlike static sounds, which keep all audio data in memory, streaming sounds decode audio from the filesystem in realtime. This has a much leaner memory footprint at the cost of higher CPU usage.

The Sound trait

Static and streaming sounds are both implementors of the new Sound trait. Sounds produce arbitrary streams of audio, so they can be used for both finite sounds or infinite sounds, like voice chat audio. In this sense, they're similar to AudioStreams from previous versions of Kira, but they can be automatically unloaded when they're finished, and they can receive clock events (see below). They're better integrated with the rest of Kira, making them first class citizens instead of escape hatches.

Kira no longer has any concept of "instances". If you want to play a static sound multiple times, you can clone it each time you want to pass it to AudioManager::play. (Static sounds share their samples via an Arc, so cloning is cheap.) Streaming sounds cannot be cloned since each one opens up a new file handle.

Clocks

Metronomes and sequences from previous versions of Kira were useful for complex audio scripting, but most games don't need such a complex system. In Kira v0.6, they're both replaced by clocks, which are simple timing sources.

Static and streaming sounds can be set to start playing at a certain clock time. Additionally, tweens can be set to start at a clock time. This means anything involving a tween, such as fading out a sound or changing its playback rate, can be synced to a clock.

If you need a more complex system, you should be able to build it in gameplay code using clocks as a building block.

More flexible mixer routing

The mixer no longer makes a distinction between sub-tracks and send tracks. Any sub-track can be routed to any number of other sub-tracks.

Modular backends

Previous versions of Kira were hardcoded to use cpal to talk to the operation system's audio drivers. Kira v0.6.0 has a Backend trait, so you can implement your own backends.

More permissive licensing

Kira is now available under the MIT or Apache-2.0 license. (Previous versions were only available under MIT.)

Feature removals

Parameters

Previous versions of Kira had global "parameters" that you could link settings to, like metronome tempos and instance playback rates. The only way to smoothly tween a setting was to link it to a parameter and tween that parameter. It is useful to be able to link multiple settings to one parameter, but the more common use case was to create a parameter just to tween one setting, which isn't very ergonomic.

In Kira v0.6, parameters have been removed, and all settings can be tweened directly. In future versions, I'd like to bring back global parameters and allow users to either tween settings directly or link them to parameters, I just haven't figured out a good way to architect that.

Arrangements

The main purpose of arrangements was to make it easier to create looping music with intro sections. It served that purpose well, but it was overkill for that purpose, and it wouldn't work with streaming sounds.

Groups

Groups were meant to help with pausing, resuming, stopping, and unloading large categories of resources. It tried to cover different types of resources with different notions of pausing, resuming, and stopping. It mapped decently to instances and sequences, but I think it would have been likely that future versions of Kira would have a resource type that groups didn't make sense for, and the abstraction would become shakier over time. Furthermore, resource management can be done from gameplay code, so it's not even necessary for Kira to provide this feature.

Changes since v0.6.0 beta 6

• Added volume control and panning control effects
• Removed the built-in panning control from mixer tracks

• Moved the functionality from kira-cpal and kira-loaders into the main kira crate. kira-cpal and kira-loaders are now unneeded and deprecated.
  • CpalBackend from kira-cpal is now available as kira::manager::backend::cpal::CpalBackend
  • kira_loaders::load and kira_loaders::load_from_cursor are now StaticSoundData::from_file and StaticSoundData::from_cursor
  • kira_loaders::stream and kira_loaders::stream_from_cursor are now StreamingSoundData::from_file and StreamingSoundData::from_cursor
• Added Renderer::on_change_sample_rate, which the Backend should call if the audio sample rate changes
• Added Effect::on_change_sample_rate, which is called when the audio sample rate changes
• Changes to the Backend trait:
  • Added the associated type Backend::settings and the method Backend::setup, which is used for creating Backends (basically a new function, but required by the Backend trait)
  • Renamed Backend::init to Backend::start
  • Removed Backend::sample_rate
  • Removed UnusedResourceCollector from the public API. Backends are no longer responsible for dropping unused resources.
• Updated MockBackend to the new API
• Removed the backend argument to AudioManager::new
• Restructured AudioManagerSettings
• The cpal backend will now do its best to gracefully handle device disconnection and sample rate changes
• The cpal backend now works in wasm environments

• Fix static sounds not pausing/resuming/stopping immediately when playback is waiting for a clock tick
• Remove From<f64> implementation for ClockSpeed
• Change AudioManager::add_clock to take a ClockSpeed argument instead of an impl Into<ClockSpeed> argument

• Fix clocks not resetting their fractional position when stopped

• Fix clock tick 0 occurring one tick after the clock is started instead of immediately when the clock is started
• Fix static sound pause/resume/stop fades never starting when the start time is set to a clock time

• Remove Clock and Clocks from the public API
• Sounds and effects now have an on_clock_tick callback instead of having a &Clocks argument passed into process
• Remove parameters
• Settings that were previously Values can now be tweened directly without needing to link them to a parameter
• All functions that send commands to the renderer now use CommandError as their error type
• Effects now have a similar structure to sounds
  • EffectBuilder - trait for types that can be converted to an Effect and a handle
  • Effect - runs on the renderer
• TrackSettings is now TrackBuilder. Effects can be added by passing an EffectBuilder to TrackBuilder::add_effect.
• Changes to the built-in effects:
  • Removed Distortion from the public API, DistortionSettings is now DistortionBuilder, added DistortionHandle
  • Removed Delay from the public API, DelaySettings is now DelayBuilder, added DelayHandle
  • Removed Reverb from the public API, ReverbSettings is now ReverbBuilder, added ReverbHandle
  • Removed Filter from the public API, FilterSettings is now FilterBuilder, added FilterHandle
• Renamed Tweenable to Tweener
• Added a Tweenable trait for things that a Tweener can control. Tweener is now generic over the type of the Tweenable value
• Volume settings now use the Volume type instead of f64
• Playback rate settings now use the PlaybackRate type instead of f64
• Clock speed settings now use the ClockSpeed type instead of f64
• Fix audio artifacts when a static sound loops
• Slight performance improvement when sounds are center-panned
• Allow configuring the main mixer track using a TrackBuilder in AudioManagerSettings