alsa-rs

The alsa crate provides thin, safe Rust wrappers for the ALSA (Advanced Linux Sound Architecture) library. While the library is still evolving, it currently supports the following core audio functionalities:

• Audio Playback: Managed via the pcm module.
• Audio Recording
• Mixer controls
• HCtl API: Includes JACK detection (see hctl module docs).
• Raw MIDI and UMP
• MIDI sequencer
• Ctl API
• Device name hints: Managed via the device_name module.
• Enumerations: Iterators for cards, devices, and other entities.
• Polling/Waiting: Support for non-blocking operations across most APIs.

The MilliBel struct is a wrapper around an i64 used to represent millibels (1/100th of a decibel). This is the unit ALSA uses for its dB-related functions.

• MilliBel::from_db(f32): Converts a standard decibel value to MilliBel.
• MilliBel::to_db(): Converts the value to a f32 decibel representation.
• It implements standard arithmetic operators (Add, Sub, etc.) for easy calculation.

let db_val = MilliBel::from_db(-6.0);
let raw_val = db_val.0; // Access the underlying i64
println!("Decibels: {}", db_val.to_db());

To read events from the sequencer, you must first obtain an Input object by calling seq.input().

Important Constraints:

• Only one Input instance may exist at a time for a given Seq instance. The Seq object tracks this and will panic if you attempt to create a second Input while the first is still in scope.
• The Input object provides access to event_input, event_input_pending, and set_input_buffer_size.
• While an Event obtained via event_input is alive, you must not call any methods on Input that modify the internal input buffer (as the event might hold a reference to it, such as for Sysex messages).

let seq = Seq::open(None, None, false)?;
{
    let mut input = seq.input();
    if input.event_input_pending(false)? > 0 {
        let mut event = input.event_input()?;
        // Process event...
    }
}

The Direction enum is used to specify whether an operation involves audio output or input. It provides helper methods to map common terminology to the ALSA concepts of Playback and Capture.

• Direction::Playback: Audio output.
• Direction::Capture: Audio input.

Use Direction::output() to get Playback and Direction::input() to get Capture.

use alsa::Direction;

let output = Direction::output(); // Returns Direction::Playback
let input = Direction::input();   // Returns Direction::Capture

The EvQueueControl<T> struct is a generic wrapper for sending control messages to an ALSA sequencer queue. The type T depends on the specific EventType being used:

• EvQueueControl<()>: Used for Start, Continue, Stop, Clock, and QueueSkew.
• EvQueueControl<i32>: Used for Tempo (where value is the tempo).
• EvQueueControl<u32>: Used for SyncPos, Tick, and SetposTick (where value is the position).
• EvQueueControl<time::Duration>: Used for SetposTime (where value is the time duration).

The Round enum is used in certain mixer-related calls to specify how values should be rounded.

• Round::Floor: Round down (towards negative infinity).
• Round::Ceil: Round up (towards positive infinity).

When submitting values for hardware parameters, ValueOr defines the strategy to use if the exact requested value is unavailable. It determines in which direction the system should search for the nearest available value.

• ValueOr::Less: The value set is the submitted value, or less.
• ValueOr::Nearest: The value set is the submitted value, or the nearest.
• ValueOr::Greater: The value set is the submitted value, or greater.

Events are created using two different methods depending on whether they carry variable-length data.

1. Event::new<D: EventData>(t: EventType, data: &D): Use this for fixed-length events (like EvNote or EvCtrl).
2. Event::new_ext<D: Into<Cow<'a, [u8]>>>(t: EventType, data: D): Use this for variable-length events such as Sysex, Bounce, or UsrVar types. This method requires a lifetime 'a because the event may reference an external buffer.

To decouple an event from its original buffer (e.g., to move it to a 'static lifetime), call .into_owned().

// Fixed length event
let note_event = Event::new(EventType::NoteOn, &note_data);

// Variable length event (Sysex)
let sysex_data = vec![0x00, 0x01, 0x02];
let sysex_event = Event::new_ext(EventType::Sysex, sysex_data);

The Params struct allows you to inspect and modify the current configuration of a Rawmidi device. You can manage settings such as the minimum available buffer size, active sensing, read modes, and clock types.

let mut params = midi.params_current()?;

// Get current settings
let mode = params.get_read_mode()?;
let clock = params.get_clock_type()?;

// Set new settings
params.set_read_mode(ReadMode::Timestamp)?;
params.set_clock_type(Clock::Monotonic)?;

// Apply parameters back to the device
midi.params(&params)?;