1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154
//! Thin but safe wrappers for [ALSA](http://http://alsa-project.org). //! //! [Github repo](https://github.com/diwic/alsa-rs) //! //! [Crates.io](https://crates.io/crates/alsa) //! //! This ALSA API wrapper/binding is WIP - the ALSA API is huge, and new //! functions and structs might be added as requested. //! //! Most functions map 1-to-1 to alsa-lib functions, e g, `ctl::CardInfo::get_id()` is a wrapper around //! `snd_ctl_card_info_get_id` and the [alsa-lib documentation](http://www.alsa-project.org/alsa-doc/alsa-lib/) //! can be consulted for additional information. //! //! Enjoy! extern crate alsa_sys as alsa; extern crate libc; #[macro_use] extern crate bitflags; #[macro_use] extern crate nix; macro_rules! alsa_enum { ($(#[$attr:meta])+ $name:ident, $static_name:ident [$count:expr], $( $a:ident = $b:ident),* ,) => { #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] $(#[$attr])* pub enum $name { $( $a = alsa::$b as isize, )* } static $static_name: [$name; $count] = [ $( $name::$a, )* ]; impl $name { /// Returns a slice of all possible values; useful for iteration pub fn all() -> &'static [$name] { &$static_name[..] } #[allow(dead_code)] fn from_c_int(c: ::libc::c_int, s: &'static str) -> Result<$name> { Self::all().iter().find(|&&x| c == x as ::libc::c_int).map(|&x| x) .ok_or_else(|| Error::unsupported(s)) } } } } /// Replaces constants ending with PLAYBACK/CAPTURE as well as /// INPUT/OUTPUT #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)] pub enum Direction { Playback, Capture } impl Direction { #[inline] pub fn input() -> Direction { Direction::Capture } #[inline] pub fn output() -> Direction { Direction::Playback } } /// Used to restrict hw parameters. In case the submitted /// value is unavailable, in which direction should one search /// for available values? #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)] pub enum ValueOr { /// The value set is the submitted value, or less Less = -1, /// The value set is the submitted value, or the nearest Nearest = 0, /// The value set is the submitted value, or greater Greater = 1, } /// Rounding mode (used in some mixer related calls) #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)] pub enum Round { /// Round down (towards negative infinity) Floor = 0, /// Round up (towards positive infinity) Ceil = 1, } mod error; pub use crate::error::{Error, Result}; pub mod card; pub use crate::card::Card as Card; mod ctl_int; pub mod ctl { //! Control device API pub use super::ctl_int::{Ctl, CardInfo, ElemIface, ElemId, ElemType, ElemValue, ElemInfo}; } pub use crate::ctl::Ctl as Ctl; pub mod hctl; pub use crate::hctl::HCtl as HCtl; pub mod pcm; pub use crate::pcm::PCM as PCM; pub mod rawmidi; pub use crate::rawmidi::Rawmidi as Rawmidi; pub mod device_name; pub mod poll; pub use crate::poll::Descriptors as PollDescriptors; pub mod mixer; pub use crate::mixer::Mixer as Mixer; pub mod seq; pub use crate::seq::Seq as Seq; mod io; pub use crate::io::Output; // Reexported inside PCM module mod chmap; mod pcm_direct; /// Functions that bypass alsa-lib and talk directly to the kernel. pub mod direct { /// This module bypasses alsa-lib and directly read and write into memory mapped kernel memory. /// /// In case of the sample memory, this is in many cases the DMA buffers that is transferred to the sound card. /// /// The reasons for doing this are: /// /// * Minimum overhead where it matters most: let alsa-lib do the code heavy setup - /// then steal its file descriptor and deal with sample streaming from Rust. /// * RT-safety to the maximum extent possible. Creating/dropping any of these structs causes syscalls, /// but function calls on these are just read and write from memory. No syscalls, no memory allocations, /// not even loops (with the exception of `MmapPlayback::write` that loops over samples to write). /// * Possibility to allow Send + Sync for structs /// * It's a fun experiment and an interesting deep dive into how alsa-lib does things. /// /// Note: Not all sound card drivers support this direct method of communication; although almost all /// modern/common ones do. It only works with hardware devices though (such as "hw:xxx" device strings), /// don't expect it to work with, e g, the PulseAudio plugin or so. /// /// For an example of how to use this mode, look in the "synth-example" directory. pub mod pcm { pub use crate::pcm_direct::{SyncPtrStatus, Status, Control, MmapCapture, MmapPlayback, MmapIO, RawSamples}; } }