[−][src]Crate soundio
soundio-rs
The soundio-rs crate is a wrapper for libsoundio.
The API closely follows the libsoundio so it is fairly low level but much safer. Most of the libsoundio API is exposed.
Some examples are included that are roughly equivalent to the examples in libsoundio.
Basic Usage
First you must create a new instance of the library using Context::new()
as follows.
let ctx = soundio::Context::new();
This will never fail except for out-of-memory situations in which case it panics (this is standard Rust behaviour).
Next you can connect to a backend. You can specify the backend explicitly, but the simplest thing is to leave it unspecified, in which case they are all tried in order. You can also set the name of the app if you like.
ctx.set_app_name("Player"); ctx.connect()?;
Assuming that worked ok, you can now find a device (or devices) to play or record from. However before you can open any devices you must flush events like this.
ctx.flush_events();
The simplest way to open a device is to just open the default input or output device as follows.
let dev = ctx.default_input_device().expect("No input device");
However please don't only use that option. Your users will hate you when they have to work out
how ALSA's undocumented and convoluted .asoundrc
config systems works just to have your app use
a different sound card.
To let the user select the output device you can make use of Context::input_devices()
and Context::output_devices()
.
Onces the device has been opened, you can query it for supported formats and sample rates.
if !dev.supports_layout(soundio::ChannelLayout::get_builtin(soundio::ChannelLayoutId::Stereo)) { return Err("Device doesn't support stereo".to_string()); } if !dev.supports_format(soundio::Format::S16LE) { return Err("Device doesn't support S16LE".to_string()); } if !dev.supports_sample_rate(44100) { return Err("Device doesn't 44.1 kHz".to_string()); }
If all is well we can open an input or output stream. You can only open an input stream on an input
device, and an output stream on an output device. If a physical device supports input and output it
is split into two Device
instances, with different Device::aim()
s but the same Device::id()
.
To open the stream you need to define some callbacks for reading/writing to it. The only required one is the read/write callback. You also need to specify the latency in seconds, which determines how often your callback is called.
let mut input_stream = dev.open_instream( 44100, soundio::Format::S16LE, soundio::ChannelLayout::get_builtin(soundio::ChannelLayoutId::Stereo), 2.0, read_callback, None::<fn()>, None::<fn(soundio::Error)>, )?;
read_callback
is a callback that takes an InStreamReader
or OutStreamWriter
, something like this.
fn read_callback(stream: &mut soundio::InStreamReader) { let frame_count_max = stream.frame_count_max(); if let Err(e) = stream.begin_read(frame_count_max) { println!("Error reading from stream: {}", e); return; } for f in 0..stream.frame_count() { for c in 0..stream.channel_count() { do_something_with(stream.sample::<i16>(c, f)); } } }
In memory samples are stored LRLRLRLR rather than LLLLRRRR so for optimisation purposes it is probably better to loop over frames and then channels, rather than the other way around (though I've not tested the actual effect this has).
Finally call InStream::start()
to start your stream.
input_stream.start()?;
There are some extra details regarding Context::wait_events()
and Context::wakeup()
, and you
will likely want to use scoped threads via the crossbeam
crate for those. The best way to learn
more is to see the examples.
Examples
list_devices
This example is very similar to libsoundio's list_devices example. It simply lists the devices on the system. It currently has no command line options.
recorder
This records audio to a wav file until you press enter. Note that it actually writes the wav file in the audio callback which is a bad idea because writing files can be slow. In a real program it might be better to have a separate thread for buffered file writing.
player
The opposite of recorder - it plays a wav file. This also has the flaw of reading the file in the audio callback. Also currently it does not exit when the file ends because I am still learning Rust.
sine
A very simple example that plays a sine wave.
Bugs, Credits, etc.
libsoundio was written by Andrew Kelley (legend). This wrapper was written by Tim Hutt. There is another wrapper available here if this one doesn't satisfy you for some reason. It is developed on github. Bugs, suggestions and praise are welcome!
Modules
native | This module provides some aliases for native endian formats, and foreign endian formats. |
Structs
ChannelLayout | A |
Context |
|
ContextUserData | |
Device | Device represents an input or output device. |
InStream | InStream represents an input stream for recording. |
InStreamReader |
|
InStreamUserData | The callbacks required for an instream are stored in this object. We also store a pointer
to the raw instream so that it can be passed to |
OutStream | OutStream represents an output stream for playback. |
OutStreamUserData | |
OutStreamWriter |
|
SampleRateRange | Devices report their supported sample rates as ranges. For non-range sample
rates |
SoftwareLatency | This is used for reporting software latency, that is the latency not including
latency due to hardware. It is returned by |
i24 | |
u24 |
Enums
Backend | Backend indicates one of the supported audio backends. |
ChannelId | ChannelId indicates the location or intent of a channel (left, right, LFE, etc.). |
ChannelLayoutId | Built-in channel layouts for convenience.
These can be used with |
DeviceAim | Used to identify devices as input or output. In this library
all devices are either input or output. If a physical device supports
both it is exposed as two devices with the same id, but with different
aims returned by |
Endian | This is a small helper type to find the endianness of a sample format. |
Error | Error is the error return type for many functions. These are
taken directly from libsoundio. It supports conversion to |
Format | Format defines the format of the samples. In 90% of cases you'll want |
Traits
Sample | The Sample trait defines functions to convert between the various sample formats. The full range
of the integer sample formats is always used, so |
Functions
endianness | Return the endianness of a sample format. |
have_backend | Return |
instream_error_callback | |
instream_overflow_callback | |
instream_read_callback | This is called when an instream has been read. The |
outstream_error_callback | |
outstream_underflow_callback | |
outstream_write_callback | This is called when an outstream needs to be written to. The |
version | Return the libsoundio version as a tuple, for exaample |
version_string | Return the libsoundio version string, for example |
Type Definitions
Result | Local typedef for results that soundio-rs returns. |