[−][src]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:
- 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. - Choose an output with the
devices
ordefault_output_device
functions. - Call
play_raw(output, source)
.
The play_raw
function expects the source to produce f32
s, which may not be the case. If you
get a compilation error, try calling .convert_samples()
on the source to fix it.
For example, here is how you would play an audio file:
use std::fs::File; use std::io::BufReader; use rodio::Source; let device = rodio::default_output_device().unwrap(); let file = File::open("sound.ogg").unwrap(); let source = rodio::Decoder::new(BufReader::new(file)).unwrap(); rodio::play_raw(&device, source.convert_samples());
Sink
In order to make it easier to control the playback, the rodio library also provides a type
named Sink
which represents an audio track.
Instead of playing the sound with play_raw
, you can add it to a
Sink
instead.
use rodio::Sink; let device = rodio::default_output_device().unwrap(); let sink = Sink::new(&device); // Add a dummy source of the sake of the example. let source = rodio::source::SineWave::new(440); sink.append(source);
The append
method will add the sound at the end of the
sink. It will be played when all the previous sounds have been played. If you want multiple
sounds to play simultaneously, you should create multiple Sink
s.
The Sink
type also provides utilities such as playing/pausing or
controlling the volume.
Filters
The Source
trait provides various filters, similarly 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();
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 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 decoder::Decoder; |
pub use source::Source; |
Modules
buffer | A simple source of samples coming from a buffer. |
decoder | Decodes samples from an audio file. |
dynamic_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. |
static_buffer | A simple source of samples coming from a static buffer. |
Structs
Device | The Device implementation associated with the platform's dynamically dispatched Host type. |
Devices | The Devices iterator associated with the platform's dynamically dispatched Host type. |
Format | The format of an input or output audio stream. |
Sink | Handle to an device that outputs sounds. |
SpatialSink |
Enums
DevicesError | An error that might occur while attempting to enumerate the available devices on a system. |
Traits
DeviceTrait | A device that is capable of audio input and/or output. |
Sample | Represents a value of a single sample. |
Functions
default_input_device | The default input audio device on the system. |
default_output_device | The default output audio device on the system. |
devices | An iterator yielding all |
input_devices | An iterator yielding all |
output_devices | An iterator yielding all |
play_once | Plays a sound once. Returns a |
play_raw | Plays a source with a device until it ends. |
Type Definitions
InputDevices | A host's device iterator yielding only input devices. |
OutputDevices | A host's device iterator yielding only output devices. |