Crate rodio 

Audio playback library.

The main concept of this library is the Source trait, which represents a sound (streaming or not). In order to play a sound, there are three steps:

• Get an OS-Sink handle to a physical device. For example, get a sink to the system’s default sound device with [DeviceSinkBuilder::open_default_stream()].
• Create an object that represents the streaming sound. It can be a sine wave, a buffer, a decoder, etc. or even your own type that implements the Source trait.
• Add the source to the OS-Sink using DeviceSink::mixer() on the OS-Sink handle.

Here is a complete example of how you would play an audio file:

use std::fs::File;
use rodio::{Decoder, MixerDeviceSink, source::Source};

// Get an OS-Sink handle to the default physical sound device.
// Note that the playback stops when the handle is dropped.//!
let handle = rodio::DeviceSinkBuilder::open_default_sink()
        .expect("open default audio stream");
let player = rodio::Player::connect_new(&handle.mixer());
// Load a sound from a file, using a path relative to Cargo.toml
let file = File::open("examples/music.ogg").unwrap();
// Decode that sound file into a source
let source = Decoder::try_from(file).unwrap();
// Play the sound directly on the device
handle.mixer().add(source);

// The sound plays in a separate audio thread,
// so we need to keep the main thread alive while it's playing.
std::thread::sleep(std::time::Duration::from_secs(5));

rodio::play() helps to simplify the above

use std::fs::File;
use std::io::BufReader;
use rodio::{Decoder, MixerDeviceSink, source::Source};

// Get an OS-Sink handle to the default physical sound device.
// Note that the playback stops when the sink_handle is dropped.
let sink_handle = rodio::DeviceSinkBuilder::open_default_sink()
        .expect("open default audio stream");

// Load a sound from a file, using a path relative to Cargo.toml
let file = BufReader::new(File::open("examples/music.ogg").unwrap());
// Note that the playback stops when the player is dropped
let player = rodio::play(&sink_handle.mixer(), file).unwrap();

// The sound plays in a separate audio thread,
// so we need to keep the main thread alive while it's playing.
std::thread::sleep(std::time::Duration::from_secs(5));

Player

In order to make it easier to control the playback, the rodio library also provides a type named Player which represents an audio track. Player plays its input sources sequentially, one after another. To play sounds in simultaneously in parallel, use mixer::Mixer instead.

To play a song Create a Player, connect it to the OS-Sink, and .append() your sound to it.

use std::time::Duration;
use rodio::{MixerDeviceSink, Player};
use rodio::source::{SineWave, Source};

// _stream must live as long as the sink
let handle = rodio::DeviceSinkBuilder::open_default_sink()
        .expect("open default audio stream");
let player = rodio::Player::connect_new(&handle.mixer());

// Add a dummy source of the sake of the example.
let source = SineWave::new(440.0).take_duration(Duration::from_secs_f32(0.25)).amplify(0.20);
player.append(source);

// The sound plays in a separate thread. This call will block the current thread until the
// player has finished playing all its queued sounds.
player.sleep_until_end();

The append method will add the sound at the end of the player. It will be played when all the previous sounds have been played. If you want multiple sounds to play simultaneously consider building your own Player from rodio parts.

The Player type also provides utilities such as playing/pausing or controlling the volume.

Note that playback through Player will end if the associated DeviceSink is dropped.

Filters

The Source trait provides various filters, similar to the standard Iterator trait.

Example:

use rodio::Source;
use std::time::Duration;

// Repeats the first five seconds of the sound forever.
let source = source.take_duration(Duration::from_secs(5)).repeat_infinite();

Decoder Backends

Symphonia is the default decoder library. Rodio supports enabling all of Symphonia’s codecs using the symphonia-all feature or enabling specific codecs using one of the symphonia-{codec name} features. By default, decoders for the most common file types (flac, mp3, mp4, vorbis, wav) are enabled.

Alternative Decoders

Alternative decoder libraries are available for some filetypes:

• claxon (flac)
• hound (wav)
• lewton (vorbis)
• minimp3 (mp3)

Symphonia is recommended for most usage. However, the alternative decoders are all licensed under either MIT or Apache 2.0 while Symphonia is licensed under MPL-2.0, so this may be a factor if you have strict licensing requirements.

If you enable one of these, you may want to set default-features = false to avoid adding extra crates to your binary. See the available feature flags for all options.

Optional Features

Rodio provides several optional features that are guarded with feature gates.

Feature “tracing”

The “tracing” feature replaces the print to stderr when a stream error happens with a recording an error event with tracing.

Feature “noise”

The “noise” feature adds support for white and pink noise sources. This feature requires the “rand” crate.

Feature “playback”

The “playback” feature adds support for playing audio. This feature requires the “cpal” crate.

Feature “64bit”

The “64bit” feature enables 64-bit sample precision using f64 for audio samples and most internal calculations. By default, rodio uses 32-bit floats (f32), which offers better performance and is sufficient for most use cases. The 64-bit mode addresses precision drift when chaining many audio operations together and in long-running signal generators where phase errors compound over time.

How it works under the hood

Rodio spawns a background thread that is dedicated to reading from the sources and sending the output to the device. Whenever you give up ownership of a Source in order to play it, it is sent to this background thread where it will be read by rodio.

All the sounds are mixed together by rodio before being sent to the operating system or the hardware. Therefore, there is no restriction on the number of sounds that play simultaneously or on the number of sinks that can be created (except for the fact that creating too many will slow down your program).

Re-exports

pub use crate::decoder::Decoder;

pub use crate::fixed_source::FixedSource;experimental

pub use crate::source::Source;

pub use crate::stream::play;playback

pub use crate::stream::DeviceSinkBuilder;playback

pub use crate::stream::DeviceSinkError;playback

pub use crate::stream::MixerDeviceSink;playback

pub use crate::stream::PlayError;playback

pub use cpal;playback

Modules

buffer

A simple source of samples coming from a buffer.

conversions

This module contains functions that convert from one PCM format to another.

decoder

Decodes audio samples from various audio file formats.

fixed_sourceexperimental

Sources of sound and various filters which never change sample rate or channel count.

math

Math utilities for audio processing.

microphonerecording

Microphone input support for audio recording. A microphone Source

mixer

Mixer that plays multiple sounds at the same time.

queue

Queue that plays sounds one after the other.

source

Sources of sound and various filters.

speakersplayback and experimental

A speakers sink

static_buffer

A simple source of samples coming from a static buffer.

streamplayback

Output audio via the OS via mixers or play directly

Macros

nz

Utility macro for getting a NonZero from a literal. Especially useful for passing in ChannelCount and Samplerate. Equivalent to: const { core::num::NonZero::new($n).unwrap() }

Structs

Deviceplayback

The Device implementation associated with the platform’s dynamically dispatched Host type.

Devicesplayback

The Devices iterator associated with the platform’s dynamically dispatched Host type.

Player

Handle to a device that outputs sounds.

SpatialPlayer

A sink that allows changing the position of the source and the listeners ears while playing. The sources played are then transformed to give a simple spatial effect. See Spatial for details.

SupportedStreamConfigplayback

Describes a single supported stream configuration, retrieved via either a SupportedStreamConfigRange instance or one of the Device::default_input/output_config methods.

Enums

DevicesErrorplayback

An error that might occur while attempting to enumerate the available devices on a system.

Traits

DeviceTraitplayback

A device that is capable of audio input and/or output.

Functions

wav_to_filewav_output

Saves Source’s output into a wav file. The output samples format is 32-bit float. This function is intended primarily for testing and diagnostics. It can be used to see the output without opening OS-Sink to a real audio device.

wav_to_writerwav_output

Saves Source’s output into a writer. The output samples format is 32-bit float. This function is intended primarily for testing and diagnostics. It can be used to see the output without opening an OS-Sink to a real audio device.

Type Aliases

BitDepth

Number of bits per sample. Can never be zero.

ChannelCount

Number of channels in a stream. Can never be Zero

Float

Floating point type used for internal calculations. Can be configured to be either f32 (default) or f64 using the 64bit feature flag.

InputDevicesplayback

A host’s device iterator yielding only input devices.

OutputDevicesplayback

A host’s device iterator yielding only output devices.

Sample

Represents value of a single sample. Silence corresponds to the value 0.0. The expected amplitude range is -1.0…1.0. Values below and above this range are clipped in conversion to other sample types. Use conversion traits from dasp_sample crate or crate::conversions::SampleTypeConverter to convert between sample types if necessary.

SampleRate

Sample rate (a frame rate or samples per second per channel).