From 2ce6744f6fdaefe67fbde89644c87d87c0d8be3d Mon Sep 17 00:00:00 2001 From: mitchmindtree Date: Wed, 11 Nov 2015 13:17:40 +1100 Subject: [PATCH 1/3] Convert time stamp flags and mpeg4objectid to bitflags --- Cargo.toml | 1 + src/audio_unit/audio_format.rs | 119 ++++++++++++++++----------------- src/lib.rs | 1 + 3 files changed, 61 insertions(+), 60 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 0a964c689..5d1429bae 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -15,5 +15,6 @@ homepage = "https://github.com/RustAudio/coreaudio-rs" num = "0.1.27" [dependencies] +bitflags = "0.3.2" coreaudio-sys = "0.1.1" libc = "0.1.10" diff --git a/src/audio_unit/audio_format.rs b/src/audio_unit/audio_format.rs index 6d0050cfa..a779be790 100644 --- a/src/audio_unit/audio_format.rs +++ b/src/audio_unit/audio_format.rs @@ -14,10 +14,10 @@ pub enum AudioFormat { AC3, // = 1633889587, F60958AC3(Option), // = 1667326771, AppleIMA4, // = 1768775988, - MPEG4AAC(Option), // = 1633772320, - MPEG4CELP(Option), // = 1667591280, - MPEG4HVXC(Option), // = 1752594531, - MPEG4TwinVQ(Option), // = 1953986161, + MPEG4AAC(Option), // = 1633772320, + MPEG4CELP(Option), // = 1667591280, + MPEG4HVXC(Option), // = 1752594531, + MPEG4TwinVQ(Option), // = 1953986161, MACE3, // = 1296122675, MACE6, // = 1296122678, ULaw, // = 1970037111, @@ -57,10 +57,10 @@ impl AudioFormat { (1633889587, _) => Some(AudioFormat::AC3), (1667326771, Some(i)) => Some(AudioFormat::F60958AC3(StandardFlag::from_u32(i))), (1768775988, _) => Some(AudioFormat::AppleIMA4), - (1633772320, Some(i)) => Some(AudioFormat::MPEG4AAC(Mpeg4Object::from_u32(i))), - (1667591280, Some(i)) => Some(AudioFormat::MPEG4CELP(Mpeg4Object::from_u32(i))), - (1752594531, Some(i)) => Some(AudioFormat::MPEG4HVXC(Mpeg4Object::from_u32(i))), - (1953986161, Some(i)) => Some(AudioFormat::MPEG4TwinVQ(Mpeg4Object::from_u32(i))), + (1633772320, Some(i)) => Some(AudioFormat::MPEG4AAC(Mpeg4ObjectId::from_bits(i as isize))), + (1667591280, Some(i)) => Some(AudioFormat::MPEG4CELP(Mpeg4ObjectId::from_bits(i as isize))), + (1752594531, Some(i)) => Some(AudioFormat::MPEG4HVXC(Mpeg4ObjectId::from_bits(i as isize))), + (1953986161, Some(i)) => Some(AudioFormat::MPEG4TwinVQ(Mpeg4ObjectId::from_bits(i as isize))), (1296122675, _) => Some(AudioFormat::MACE3), (1296122678, _) => Some(AudioFormat::MACE6), (1970037111, _) => Some(AudioFormat::ULaw), @@ -71,7 +71,7 @@ impl AudioFormat { (778924081, _) => Some(AudioFormat::MPEGLayer1), (778924082, _) => Some(AudioFormat::MPEGLayer2), (778924083, _) => Some(AudioFormat::MPEGLayer3), - (1953066341, Some(i)) => Some(AudioFormat::TimeCode(AudioTimeStampFlag::from_u32(i))), + (1953066341, Some(i)) => Some(AudioFormat::TimeCode(AudioTimeStampFlag::from_bits(i))), (1835623529, _) => Some(AudioFormat::MIDIStream), (1634760307, _) => Some(AudioFormat::ParameterValueStream), (1634492771, _) => Some(AudioFormat::AppleLossless), @@ -100,10 +100,10 @@ impl AudioFormat { AudioFormat::AC3 => (1633889587, None), AudioFormat::F60958AC3(flag) => (1667326771, flag.map(|flag| flag as u32)), AudioFormat::AppleIMA4 => (1768775988, None), - AudioFormat::MPEG4AAC(flag) => (1633772320, flag.map(|flag| flag as u32)), - AudioFormat::MPEG4CELP(flag) => (1667591280, flag.map(|flag| flag as u32)), - AudioFormat::MPEG4HVXC(flag) => (1752594531, flag.map(|flag| flag as u32)), - AudioFormat::MPEG4TwinVQ(flag) => (1953986161, flag.map(|flag| flag as u32)), + AudioFormat::MPEG4AAC(flag) => (1633772320, flag.map(|flag| flag.bits() as u32)), + AudioFormat::MPEG4CELP(flag) => (1667591280, flag.map(|flag| flag.bits() as u32)), + AudioFormat::MPEG4HVXC(flag) => (1752594531, flag.map(|flag| flag.bits() as u32)), + AudioFormat::MPEG4TwinVQ(flag) => (1953986161, flag.map(|flag| flag.bits() as u32)), AudioFormat::MACE3 => (1296122675, None), AudioFormat::MACE6 => (1296122678, None), AudioFormat::ULaw => (1970037111, None), @@ -114,7 +114,7 @@ impl AudioFormat { AudioFormat::MPEGLayer1 => (778924081, None), AudioFormat::MPEGLayer2 => (778924082, None), AudioFormat::MPEGLayer3 => (778924083, None), - AudioFormat::TimeCode(flag) => (1953066341, flag.map(|flag| flag as u32)), + AudioFormat::TimeCode(flag) => (1953066341, flag.map(|flag| flag.bits())), AudioFormat::MIDIStream => (1835623529, None), AudioFormat::ParameterValueStream => (1634760307, None), AudioFormat::AppleLossless => (1634492771, None), @@ -213,57 +213,56 @@ impl AppleLosslessFlag { } } -#[derive(Copy, Clone, Debug)] -#[allow(non_camel_case_types)] -pub enum Mpeg4Object { - AAC_Main = 1, - AAC_LC = 2, - AAC_SSR = 3, - AAC_LTP = 4, - AAC_SBR = 5, - AAC_Scalable = 6, - TwinVQ = 7, - CELP = 8, - HVXC = 9, -} -impl Mpeg4Object { - pub fn from_u32(i: u32) -> Option { - match i { - 1 => Some(Mpeg4Object::AAC_Main), - 2 => Some(Mpeg4Object::AAC_LC), - 3 => Some(Mpeg4Object::AAC_SSR), - 4 => Some(Mpeg4Object::AAC_LTP), - 5 => Some(Mpeg4Object::AAC_SBR), - 6 => Some(Mpeg4Object::AAC_Scalable), - 7 => Some(Mpeg4Object::TwinVQ), - 8 => Some(Mpeg4Object::CELP), - 9 => Some(Mpeg4Object::HVXC), - _ => None, - } +bitflags! { + /// "Used in the `mFormatFlags` field of an `AudioStreamBasicDescription` structure that + /// describes an MPEG-4 audio stream to specify the type of MPEG-4 audio data. + /// + /// **Available** in OSX v10.3 and later. + /// + /// **Deprecated** in OSX v10.5. + flags Mpeg4ObjectId: isize { + /// Advanced audio coding; the baisc MPEG-4 technology. + const AAC_MAIN = 1, + /// Lossless coding; provides compression with no loss of quality. + const AAC_LC = 2, + /// Scalable sampling rate; provides different sampling frequencies for different targets. + const AAC_SSR = 3, + /// Long term prediction; reduces redundancy in a coded signal. + const AAC_LTP = 4, + /// Spectral band replication; reconstructs high-frequency content from lower frequencies + /// and side information. + const AAC_SBR = 5, + /// Scalable lossless coding. + const AAC_SCALABLE = 6, + /// Transform-domain weighted interleaved vector quantization; an audio codec optimised for + /// audio coding at ultra low bit rates around 8kbit/s. + const TWIN_VQ = 7, + /// Code Excited Linear Prdiction; a narrow-band/wide-band speech codec. + const CELP = 8, + /// Harmonic Vector Excitation Coding; a very-low bit-rate parametric speech codec. + const HVXC = 9, } } -#[derive(Copy, Clone, Debug)] -#[allow(non_camel_case_types)] -pub enum AudioTimeStampFlag { - SampleTimeValid = 1, - HostTimeValid = 2, - RateScalarValid = 4, - WordClockTimeValid = 8, - SMPTETimeValid = 16, -} -impl AudioTimeStampFlag { - pub fn from_u32(i: u32) -> Option { - match i { - 1 => Some(AudioTimeStampFlag::SampleTimeValid), - 2 => Some(AudioTimeStampFlag::HostTimeValid), - 4 => Some(AudioTimeStampFlag::RateScalarValid), - 8 => Some(AudioTimeStampFlag::WordClockTimeValid), - 16 => Some(AudioTimeStampFlag::SMPTETimeValid), - _ => None - } +bitflags! { + /// "These flags indicate the valuid fields in an AudioTimeStamp structure." + /// + /// Original Documentation [here](https://developer.apple.com/library/mac/documentation/MusicAudio/Reference/CoreAudioDataTypesRef/#//apple_ref/doc/constant_group/Audio_Time_Stamp_Flags). + /// + /// Available in OSX v10.0 and later. + flags AudioTimeStampFlag: u32 { + /// The sample frame time is valid. + const SAMPLE_TIME_VALID = 1, + /// The host time is valid. + const HOST_TIME_VALID = 2, + /// The rate scalar is valid. + const RATE_SCALAR_VALID = 4, + /// The world clock time is valid. + const WORLD_CLOCK_TIME_VALID = 8, + /// The SMPTE time is valid. + const SMPTE_TIME_VALID = 16, } } diff --git a/src/lib.rs b/src/lib.rs index d5da3d762..300266f02 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -8,6 +8,7 @@ //! Currently, work has only been started on the [audio_unit](./audio_unit/index.html) module, but //! eventually we'd like to cover at least the majority of the C API. +#[macro_use] extern crate bitflags; extern crate coreaudio_sys; pub use coreaudio_sys as bindings; From 996482f5e3c83faff6e41c3d503051dd569688c4 Mon Sep 17 00:00:00 2001 From: mitchmindtree Date: Wed, 11 Nov 2015 14:48:42 +1100 Subject: [PATCH 2/3] Completed enum conversions to bitflags. Improved documentation. --- src/audio_unit/audio_format.rs | 484 ++++++++++++++++++++++++--------- 1 file changed, 360 insertions(+), 124 deletions(-) diff --git a/src/audio_unit/audio_format.rs b/src/audio_unit/audio_format.rs index a779be790..7a8cde315 100644 --- a/src/audio_unit/audio_format.rs +++ b/src/audio_unit/audio_format.rs @@ -6,61 +6,191 @@ use libc; -/// Represents the kAudioFormat types in the form of an enum. +pub use self::standard_flags::StandardFlags; +pub use self::linear_pcm_flags::LinearPCMFlags; +pub use self::apple_lossless_flags::AppleLosslessFlags; +pub use self::audio_time_stamp_flags::AudioTimeStampFlags; + + +/// A type-safe representation of both the `AudioFormatId` and their associated flags. #[derive(Copy, Clone, Debug)] #[allow(non_camel_case_types)] pub enum AudioFormat { - LinearPCM(Option), // = 1819304813, + /// Linear PCM; a non-compressed audio data format with one frame per packet. + /// + /// **Available** in OS X v10.0 and later. + LinearPCM(Option), // = 1819304813, + /// An AC-3 codec. + /// + /// **Available** in OS X v10.2 and later. AC3, // = 1633889587, - F60958AC3(Option), // = 1667326771, + /// AC-3 codec that provides data packaged for transport over an IEC 60958 compliant digital + /// audio interface. + /// + /// **Available** in OS X v10.2 and later. + F60958AC3(Option), // = 1667326771, + /// Apple's implementation of the IMA 4:1 ADPCM codec. + /// + /// **Available** in OS X v10.2 and later. AppleIMA4, // = 1768775988, + /// MPEG-4 AAC codec. + /// + /// **Available** in OS X v10.2 and later. MPEG4AAC(Option), // = 1633772320, + /// MPEG-4 CELP codec. + /// + /// **Available** in OS X v10.2 and later. MPEG4CELP(Option), // = 1667591280, + /// MPEG-4 HVXC codec. + /// + /// **Available** in OS X v10.2 and later. MPEG4HVXC(Option), // = 1752594531, + /// MPEG-4 TwinVQ codec. + /// + /// **Available** in OS X v10.2 and later. MPEG4TwinVQ(Option), // = 1953986161, + /// MACE 3:1. + /// + /// **Available** in OS X v10.3 and later. MACE3, // = 1296122675, + /// MACE 6:1. + /// + /// **Available** in OS X v10.3 and later. MACE6, // = 1296122678, + /// μLaw 2:1. + /// + /// **Available** in OS X v10.3 and later. ULaw, // = 1970037111, + /// aLaw 2:1. + /// + /// **Available** in OS X v10.3 and later. ALaw, // = 1634492791, + /// QDesign Music. + /// + /// **Available** in OS X v10.3 and later. QDesign, // = 1363430723, + /// QDesign2 Music. + /// + /// **Available** in OS X v10.3 and later. QDesign2, // = 1363430706, + /// QUALCOMM PureVoice. + /// + /// **Available** in OS X v10.3 and later. QUALCOMM, // = 1365470320, + /// MPEG-1/2, Layer 1 audio. + /// + /// **Available** in OS X v10.3 and later. MPEGLayer1, // = 778924081, + /// MPEG-1/2, Layer 2 audio. + /// + /// **Available** in OS X v10.3 and later. MPEGLayer2, // = 778924082, + /// MPEG-1/2, Layer 3 audio. + /// + /// **Available** in OS X v10.3 and later. MPEGLayer3, // = 778924083, - TimeCode(Option), // = 1953066341, + /// A stream of IOAudioTimeStamp structures. + /// + /// **Available** in OS X v10.2 and later. + TimeCode(Option), // = 1953066341, + /// A stream of MIDIPAcketList structures where the time stamps in the MIDIPacket structures + /// are sample offsets in the stream. The `sample_rate` field in the **StreamFormat** structure + /// is used to describe how time is passed in this kind of stream. + /// + /// An audio unit that receives or generates this stream can use this sample rate together with + /// the number of frames it is rendering. + /// + /// The sample offsets within the MIDIPacketList can be used to define the time for any MIDI + /// event within the list. + /// + /// **Available** in OS X v10.2 and later. + /// + /// TODO: Review whether or not this audio format should indicate some fundamental change + /// within the **StreamFormat**. MIDIStream, // = 1835623529, + /// A "side-chain" of f32 data that can be fed or generated by an audio unit and that is used + /// to send a high density of parameter value control information. + /// + /// An audio unit typically runs a parameter value stream at either the sample rate of the + /// audio unit's audio data, or some integer quotient of this (i.e. a half or a third of the + /// sample rate of the audio). + /// + /// The `sample_rate` field in the **StreamFormat** type describes this relationship. + /// + /// **Available** in OS X v10.2 and later. ParameterValueStream, // = 1634760307, + /// Apple Lossless format. + /// + /// **Available** in OS X v10.3 and later. AppleLossless, // = 1634492771, + /// MPEG-4 High Efficiency AAC audio object. + /// + /// **Available** in OS X v10.5 and later. MPEG4AAC_HE, // = 1633772392, + /// MPEG-4 AAC Low Delay audio object. + /// + /// **Available** in OS X v10.5 and later. MPEG4AAC_LD, // = 1633772396, + /// MPEG-4 AAC Enhanced Low Delay audio object. + /// + /// **Available** in OS X v10.7 and later. MPEG4AAC_ELD, // = 1633772389, + /// MPEG-4 AAC Enhanced Low Delay audio object with SBR (spectral band replication) extension + /// layer. + /// + /// **Available** in OS X v10.7 and later. MPEG4AAC_ELD_SBR, // = 1633772390, MPEG4AAC_ELD_V2, // = 1633772391, + /// MPEG-4 High Efficiency AAC Version 2 audio object. + /// + /// **Available** in OS X v10.5 and later. MPEG4AAC_HE_V2, // = 1633772400, + /// MPEG-4 Apatial Audio audio object. + /// + /// **Available** in OS X v10.5 and later. MPEG4AAC_Spatial, // = 1633772403, + /// The AMR (adaptive Multi-Rate) narrow band speech codec. + /// + /// **Available** in OS X v10.5 and later. AMR, // = 1935764850, AMR_WB, // = 1935767394, + /// The codec used for Audible, Inc. audio books. + /// + /// **Available** in OS X v10.6 and later. Audible, // = 1096107074, + /// The iLBC (internet Low Bitrate Codec) narrow band cpeech codec. + /// + /// **Available** in OS X v10.6 and later. iLBC, // = 1768710755, + /// DVI/Intel IMA ADPCM - ACM code 17. + /// + /// **Available** in OS X v10.6 and later. DVIIntelIMA, // = 1836253201, + /// Microsoft GSM 6.10 - ACM code 49. + /// + /// **Available** in OS X v10.6 and later. MicrosoftGSM, // = 1836253233, + /// The format defined by the AES3-2003 standard. + /// + /// Adopted into MXF and MPEG-2 containers and SDTI transport streams with SMPTE specs + /// 203M-2002 and 331M-2000. AES3, // = 1634038579, } + impl AudioFormat { - /// Convert from C format and flag to Rust enum. + /// Convert from the FFI C format and flags to a typesafe Rust enum representation. pub fn from_format_and_flag(format: libc::c_uint, flag: Option) -> Option { match (format, flag) { - (1819304813, Some(i)) => Some(AudioFormat::LinearPCM(LinearPCMFlag::from_u32(i))), + (1819304813, Some(i)) => Some(AudioFormat::LinearPCM(LinearPCMFlags::from_bits(i))), (1633889587, _) => Some(AudioFormat::AC3), - (1667326771, Some(i)) => Some(AudioFormat::F60958AC3(StandardFlag::from_u32(i))), + (1667326771, Some(i)) => Some(AudioFormat::F60958AC3(StandardFlags::from_bits(i))), (1768775988, _) => Some(AudioFormat::AppleIMA4), - (1633772320, Some(i)) => Some(AudioFormat::MPEG4AAC(Mpeg4ObjectId::from_bits(i as isize))), - (1667591280, Some(i)) => Some(AudioFormat::MPEG4CELP(Mpeg4ObjectId::from_bits(i as isize))), - (1752594531, Some(i)) => Some(AudioFormat::MPEG4HVXC(Mpeg4ObjectId::from_bits(i as isize))), - (1953986161, Some(i)) => Some(AudioFormat::MPEG4TwinVQ(Mpeg4ObjectId::from_bits(i as isize))), + (1633772320, Some(i)) => Some(AudioFormat::MPEG4AAC(Mpeg4ObjectId::from_u32(i))), + (1667591280, Some(i)) => Some(AudioFormat::MPEG4CELP(Mpeg4ObjectId::from_u32(i))), + (1752594531, Some(i)) => Some(AudioFormat::MPEG4HVXC(Mpeg4ObjectId::from_u32(i))), + (1953986161, Some(i)) => Some(AudioFormat::MPEG4TwinVQ(Mpeg4ObjectId::from_u32(i))), (1296122675, _) => Some(AudioFormat::MACE3), (1296122678, _) => Some(AudioFormat::MACE6), (1970037111, _) => Some(AudioFormat::ULaw), @@ -71,7 +201,7 @@ impl AudioFormat { (778924081, _) => Some(AudioFormat::MPEGLayer1), (778924082, _) => Some(AudioFormat::MPEGLayer2), (778924083, _) => Some(AudioFormat::MPEGLayer3), - (1953066341, Some(i)) => Some(AudioFormat::TimeCode(AudioTimeStampFlag::from_bits(i))), + (1953066341, Some(i)) => Some(AudioFormat::TimeCode(AudioTimeStampFlags::from_bits(i))), (1835623529, _) => Some(AudioFormat::MIDIStream), (1634760307, _) => Some(AudioFormat::ParameterValueStream), (1634492771, _) => Some(AudioFormat::AppleLossless), @@ -96,14 +226,14 @@ impl AudioFormat { /// Convert from the Rust enum to the C format and flag. pub fn to_format_and_flag(&self) -> (libc::c_uint, Option) { match *self { - AudioFormat::LinearPCM(flag) => (1819304813, flag.map(|flag| flag as u32)), + AudioFormat::LinearPCM(flag) => (1819304813, flag.map(|flag| flag.bits())), AudioFormat::AC3 => (1633889587, None), - AudioFormat::F60958AC3(flag) => (1667326771, flag.map(|flag| flag as u32)), + AudioFormat::F60958AC3(flag) => (1667326771, flag.map(|flag| flag.bits())), AudioFormat::AppleIMA4 => (1768775988, None), - AudioFormat::MPEG4AAC(flag) => (1633772320, flag.map(|flag| flag.bits() as u32)), - AudioFormat::MPEG4CELP(flag) => (1667591280, flag.map(|flag| flag.bits() as u32)), - AudioFormat::MPEG4HVXC(flag) => (1752594531, flag.map(|flag| flag.bits() as u32)), - AudioFormat::MPEG4TwinVQ(flag) => (1953986161, flag.map(|flag| flag.bits() as u32)), + AudioFormat::MPEG4AAC(flag) => (1633772320, flag.map(|flag| flag as u32)), + AudioFormat::MPEG4CELP(flag) => (1667591280, flag.map(|flag| flag as u32)), + AudioFormat::MPEG4HVXC(flag) => (1752594531, flag.map(|flag| flag as u32)), + AudioFormat::MPEG4TwinVQ(flag) => (1953986161, flag.map(|flag| flag as u32)), AudioFormat::MACE3 => (1296122675, None), AudioFormat::MACE6 => (1296122678, None), AudioFormat::ULaw => (1970037111, None), @@ -137,132 +267,238 @@ impl AudioFormat { } -#[derive(Copy, Clone, Debug)] -pub enum LinearPCMFlag { - IsFloat = 1, - IsBigEndian = 2, - IsSignedInteger = 4, - IsPacked = 8, - IsAlignedHigh = 16, - IsNonInterleaved = 32, - IsNonMixable = 64, - FlagsSampleFractionShift = 7, - FlagsSampleFractionMask = 8064, -} -impl LinearPCMFlag { - pub fn from_u32(i: u32) -> Option { - match i { - 1 => Some(LinearPCMFlag::IsFloat), - 2 => Some(LinearPCMFlag::IsBigEndian), - 4 => Some(LinearPCMFlag::IsSignedInteger), - 8 => Some(LinearPCMFlag::IsPacked), - 16 => Some(LinearPCMFlag::IsAlignedHigh), - 32 => Some(LinearPCMFlag::IsNonInterleaved), - 64 => Some(LinearPCMFlag::IsNonMixable), - 7 => Some(LinearPCMFlag::FlagsSampleFractionShift), - 8064 => Some(LinearPCMFlag::FlagsSampleFractionMask), - _ => None, +/// A wrapper around the const **StandardFlags**. +pub mod standard_flags { + bitflags! { + /// Standard flags for use in the **F60958AC3** **AudioFormat** variant. + /// + /// Note: In the original Core Audio API these are consolidated with what we have named the + /// **StandardFlags** and **AppleLosslessFlag** types under the `AudioFormatFlag` type. We have + /// chosen to separate these for greater type safety and clearer compatibility with the + /// **AudioFormat** type. + /// + /// Original documentation [here](https://developer.apple.com/library/mac/documentation/MusicAudio/Reference/CoreAudioDataTypesRef/#//apple_ref/doc/constant_group/AudioStreamBasicDescription_Flags). + flags StandardFlags: u32 { + /// Set for floating point, clear for integer. + /// + /// **Available** in OS X v10.2 and later. + const IS_FLOAT = 1, + /// Set for big endian, clear for little endian. + /// + /// **Available** in OS X v10.2 and later. + const IS_BIG_ENDIAN = 2, + /// Set for signed integer, clear for unsigned integer. + /// + /// Note: This is only valid if `IS_FLOAT` is clear. + /// + /// **Available** in OS X v10.2 and later. + const IS_SIGNED_INTEGER = 4, + /// Set if the sample bits occupy the entire available bits for the channel, clear if they + /// are high- or low-aligned within the channel. + /// + /// **Available** in OS X v10.2 and later. + const IS_PACKED = 8, + /// Set if the sample bits are placed into the high bits of the channel, clear for low bit + /// placement. + /// + /// Note: This is only valid if `IS_PACKED` is clear. + /// + /// **Available** in OS X v10.2 and later. + const IS_ALIGNED_HIGH = 16, + /// Set if the sample for each channel are located contiguously and the channels are laid + /// out end to end. + /// + /// Clear if the samples for each frame are laid out contiguously and the frames laid out + /// end to end. + /// + /// In the original API, this flag affects the use of AudioStreamBasicDescription and + /// AudioBufferList structures, however in this Rust implementation we aim to make this + /// behaviour type safe so that you need not worry about this. + /// + /// **Available** in OS X v10.2 and later. + const IS_NON_INTERLEAVED = 32, + /// Set to indicate when a format is nonmixable. + /// + /// Note: that this flag is only used when interacting with the HAL's stream format + /// information. It is **not** valid for any other use. + /// + /// **Available** in OS X v10.3 and later. + const IS_NON_MIXABLE = 64, } } } -#[derive(Copy, Clone, Debug)] -pub enum StandardFlag { - IsFloat = 1, - IsBigEndian = 2, - IsSignedInteger = 4, - IsPacked = 8, - IsAlignedHigh = 16, - IsNonInterleaved = 32, - IsNonMixable = 64, -} -impl StandardFlag { - pub fn from_u32(i: u32) -> Option { - match i { - 1 => Some(StandardFlag::IsFloat), - 2 => Some(StandardFlag::IsBigEndian), - 4 => Some(StandardFlag::IsSignedInteger), - 8 => Some(StandardFlag::IsPacked), - 16 => Some(StandardFlag::IsAlignedHigh), - 32 => Some(StandardFlag::IsNonInterleaved), - 64 => Some(StandardFlag::IsNonMixable), - _ => None, +/// A wrapper around the const **LinearPCMFlags**. +pub mod linear_pcm_flags { + bitflags! { + /// Flags for use within the **LinearPCM** **AudioFormat**. + /// + /// Note: In the original Core Audio API these are consolidated with what we have named the + /// **StandardFlags** and **AppleLosslessFlag** types under the `AudioFormatFlag` type. We have + /// chosen to separate these for greater type safety and clearer compatibility with the + /// **AudioFormat** type. + /// + /// Original documentation [here](https://developer.apple.com/library/mac/documentation/MusicAudio/Reference/CoreAudioDataTypesRef/#//apple_ref/doc/constant_group/AudioStreamBasicDescription_Flags). + flags LinearPCMFlags: u32 { + /// Synonmyn for the **IS_FLOAT** **StandardFlags**. + /// + /// **Available** in OS X v10.0 and later. + const IS_FLOAT = 1, + /// Synonmyn for the **IS_BIG_ENDIAN** **StandardFlags**. + /// + /// **Available** in OS X v10.0 and later. + const IS_BIG_ENDIAN = 2, + /// Synonmyn for the **IS_SIGNED_INTEGER** **StandardFlags**. + /// + /// **Available** in OS X v10.0 and later. + const IS_SIGNED_INTEGER = 4, + /// Synonmyn for the **IS_PACKED** **StandardFlags**. + /// + /// **Available** in OS X v10.0 and later. + const IS_PACKED = 8, + /// Synonmyn for the **IS_ALIGNED_HIGH** **StandardFlags**. + /// + /// **Available** in OS X v10.0 and later. + const IS_ALIGNED_HIGH = 16, + /// Synonmyn for the **IS_NON_INTERLEAVED** **StandardFlags**. + /// + /// **Available** in OS X v10.2 and later. + const IS_NON_INTERLEAVED = 32, + /// Synonmyn for the **IS_NON_MIXABLE** **StandardFlags**. + /// + /// **Available** in OS X v10.3 and later. + const IS_NON_MIXABLE = 64, + /// The linear PCM flags contain a 6-bit bitfield indicating that an integer format is to + /// be interpreted as fixed point. + /// + /// The value indicates the number of bits are used to represent the fractional portion of + /// each sample value. + /// + /// This constant indicates the bit position (counting from the right) of the bitfield in + /// `mFormatFlags` field. + /// + /// TODO: Review whether or not this flag indicates that we need to treat LinearPCM format + /// uniquely in some way. + /// + /// **Available** in OS X v10.6 and later. + const FLAGS_SAMPLE_FRACTION_SHIFT = 7, + /// The number of fractional bits. + /// + /// `== ( & FLAGS_SAMPLE_FRACTION_MASK) >> FLAGS_SAMPLE_FRACTION_SHIFT` + /// + /// **Available** in OS X v10.6 and later. + const FLAGS_SAMPLE_FRACTION_MASK = 8064, } } } -#[derive(Copy, Clone, Debug)] -pub enum AppleLosslessFlag { - Bit16SourceData = 1, - Bit20SourceData = 2, - Bit24SourceData = 3, - Bit32SourceData = 4, -} -impl AppleLosslessFlag { - pub fn from_u32(i: u32) -> Option { - match i { - 1 => Some(AppleLosslessFlag::Bit16SourceData), - 2 => Some(AppleLosslessFlag::Bit20SourceData), - 3 => Some(AppleLosslessFlag::Bit24SourceData), - 4 => Some(AppleLosslessFlag::Bit32SourceData), - _ => None +/// A wrapper around the const **AppleLosslessFlags**. +pub mod apple_lossless_flags { + bitflags! { + /// Flags set for Apple Lossless data. + /// + /// **Available** in OS X v10.3 and later. + /// + /// Note: In the original Core Audio API these are consolidated with what we have named the + /// **StandardFlags** and **AppleLosslessFlag** types under the `AudioFormatFlag` type. We have + /// chosen to separate these for greater type safety and clearer compatibility with the + /// **AudioFormat** type. + /// + /// Original documentation [here](https://developer.apple.com/library/mac/documentation/MusicAudio/Reference/CoreAudioDataTypesRef/#//apple_ref/doc/constant_group/AudioStreamBasicDescription_Flags). + flags AppleLosslessFlags: u32 { + /// Sourced from 16 bit native endian signed integer data. + const BIT_16_SOURCE_DATA = 1, + /// Sourced from 20 bit native endian signed integer data aligned high in 24 bits. + const BIT_20_SOURCE_DATA = 2, + /// Sourced from 24 bit native endian signed integer data. + const BIT_24_SOURCE_DATA = 3, + /// Sourced from 32 bit native endian signed integer data. + const BIT_32_SOURCE_DATA = 4, } } } -bitflags! { - /// "Used in the `mFormatFlags` field of an `AudioStreamBasicDescription` structure that - /// describes an MPEG-4 audio stream to specify the type of MPEG-4 audio data. - /// - /// **Available** in OSX v10.3 and later. - /// - /// **Deprecated** in OSX v10.5. - flags Mpeg4ObjectId: isize { - /// Advanced audio coding; the baisc MPEG-4 technology. - const AAC_MAIN = 1, - /// Lossless coding; provides compression with no loss of quality. - const AAC_LC = 2, - /// Scalable sampling rate; provides different sampling frequencies for different targets. - const AAC_SSR = 3, - /// Long term prediction; reduces redundancy in a coded signal. - const AAC_LTP = 4, - /// Spectral band replication; reconstructs high-frequency content from lower frequencies - /// and side information. - const AAC_SBR = 5, - /// Scalable lossless coding. - const AAC_SCALABLE = 6, - /// Transform-domain weighted interleaved vector quantization; an audio codec optimised for - /// audio coding at ultra low bit rates around 8kbit/s. - const TWIN_VQ = 7, - /// Code Excited Linear Prdiction; a narrow-band/wide-band speech codec. - const CELP = 8, - /// Harmonic Vector Excitation Coding; a very-low bit-rate parametric speech codec. - const HVXC = 9, +/// "Used in the `mFormatFlags` field of an `AudioStreamBasicDescription` structure that +/// describes an MPEG-4 audio stream to specify the type of MPEG-4 audio data. +/// +/// **Available** in OS X v10.3 and later. +/// +/// **Deprecated** in OS X v10.5. +/// +/// Note: This type was originally represented using a bitflag field in the original API, however +/// there is only ever one flag set at a time. Thus, we use an enum as a more accurate, +/// user-friendly, type-safe representation. +/// +/// Original documenation +/// [here](https://developer.apple.com/library/mac/documentation/MusicAudio/Reference/CoreAudioDataTypesRef/#//apple_ref/doc/constant_group/MPEG_4_Audio_Object_Type_Constants). +#[derive(Copy, Clone, Debug, PartialEq)] +#[allow(non_camel_case_types)] +pub enum Mpeg4ObjectId { + /// Advanced audio coding; the baisc MPEG-4 technology. + AAC_Main = 1, + /// Lossless coding; provides compression with no loss of quality. + AAC_LC = 2, + /// Scalable sampling rate; provides different sampling frequencies for different targets. + AAC_SSR = 3, + /// Long term prediction; reduces redundancy in a coded signal. + AAC_LTP = 4, + /// Spectral band replication; reconstructs high-frequency content from lower frequencies + /// and side information. + AAC_SBR = 5, + /// Scalable lossless coding. + AAC_Scalable = 6, + /// Transform-domain weighted interleaved vector quantization; an audio codec optimised for + /// audio coding at ultra low bit rates around 8kbit/s. + TwinVQ = 7, + /// Code Excited Linear Prdiction; a narrow-band/wide-band speech codec. + CELP = 8, + /// Harmonic Vector Excitation Coding; a very-low bit-rate parametric speech codec. + HVXC = 9, +} + +impl Mpeg4ObjectId { + /// Create an Mpeg4ObjectId from a u32. + pub fn from_u32(u: u32) -> Option { + match u { + 1 => Some(Mpeg4ObjectId::AAC_Main), + 2 => Some(Mpeg4ObjectId::AAC_LC), + 3 => Some(Mpeg4ObjectId::AAC_SSR), + 4 => Some(Mpeg4ObjectId::AAC_LTP), + 5 => Some(Mpeg4ObjectId::AAC_SBR), + 6 => Some(Mpeg4ObjectId::AAC_Scalable), + 7 => Some(Mpeg4ObjectId::TwinVQ), + 8 => Some(Mpeg4ObjectId::CELP), + 9 => Some(Mpeg4ObjectId::HVXC), + _ => None, + } } } -bitflags! { - /// "These flags indicate the valuid fields in an AudioTimeStamp structure." - /// - /// Original Documentation [here](https://developer.apple.com/library/mac/documentation/MusicAudio/Reference/CoreAudioDataTypesRef/#//apple_ref/doc/constant_group/Audio_Time_Stamp_Flags). - /// - /// Available in OSX v10.0 and later. - flags AudioTimeStampFlag: u32 { - /// The sample frame time is valid. - const SAMPLE_TIME_VALID = 1, - /// The host time is valid. - const HOST_TIME_VALID = 2, - /// The rate scalar is valid. - const RATE_SCALAR_VALID = 4, - /// The world clock time is valid. - const WORLD_CLOCK_TIME_VALID = 8, - /// The SMPTE time is valid. - const SMPTE_TIME_VALID = 16, +/// A wrapper around the const **AudioTimeStampFlags**. +pub mod audio_time_stamp_flags { + bitflags! { + /// "These flags indicate the valuid fields in an AudioTimeStamp structure." + /// + /// **Available** in OS X v10.0 and later. + /// + /// Original Documentation [here](https://developer.apple.com/library/mac/documentation/MusicAudio/Reference/CoreAudioDataTypesRef/#//apple_ref/doc/constant_group/Audio_Time_Stamp_Flags). + flags AudioTimeStampFlags: u32 { + /// The sample frame time is valid. + const SAMPLE_TIME_VALID = 1, + /// The host time is valid. + const HOST_TIME_VALID = 2, + /// The rate scalar is valid. + const RATE_SCALAR_VALID = 4, + /// The world clock time is valid. + const WORLD_CLOCK_TIME_VALID = 8, + /// The SMPTE time is valid. + const SMPTE_TIME_VALID = 16, + } } } From 895806f0232d19e231717695dbe18d90105c6fa4 Mon Sep 17 00:00:00 2001 From: mitchmindtree Date: Wed, 11 Nov 2015 15:21:22 +1100 Subject: [PATCH 3/3] Fix typos --- src/audio_unit/audio_format.rs | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/audio_unit/audio_format.rs b/src/audio_unit/audio_format.rs index 7a8cde315..4a097d607 100644 --- a/src/audio_unit/audio_format.rs +++ b/src/audio_unit/audio_format.rs @@ -93,7 +93,7 @@ pub enum AudioFormat { /// /// **Available** in OS X v10.2 and later. TimeCode(Option), // = 1953066341, - /// A stream of MIDIPAcketList structures where the time stamps in the MIDIPacket structures + /// A stream of MIDIPacketList structures where the time stamps in the MIDIPacket structures /// are sample offsets in the stream. The `sample_rate` field in the **StreamFormat** structure /// is used to describe how time is passed in this kind of stream. /// @@ -274,9 +274,9 @@ pub mod standard_flags { /// Standard flags for use in the **F60958AC3** **AudioFormat** variant. /// /// Note: In the original Core Audio API these are consolidated with what we have named the - /// **StandardFlags** and **AppleLosslessFlag** types under the `AudioFormatFlag` type. We have - /// chosen to separate these for greater type safety and clearer compatibility with the - /// **AudioFormat** type. + /// **StandardFlags** and **AppleLosslessFlags** types under the `AudioFormatFlag` type. We + /// have chosen to separate these for greater type safety and clearer compatibility with + /// the **AudioFormat** type. /// /// Original documentation [here](https://developer.apple.com/library/mac/documentation/MusicAudio/Reference/CoreAudioDataTypesRef/#//apple_ref/doc/constant_group/AudioStreamBasicDescription_Flags). flags StandardFlags: u32 { @@ -336,9 +336,9 @@ pub mod linear_pcm_flags { /// Flags for use within the **LinearPCM** **AudioFormat**. /// /// Note: In the original Core Audio API these are consolidated with what we have named the - /// **StandardFlags** and **AppleLosslessFlag** types under the `AudioFormatFlag` type. We have - /// chosen to separate these for greater type safety and clearer compatibility with the - /// **AudioFormat** type. + /// **StandardFlags** and **AppleLosslessFlags** types under the `AudioFormatFlag` type. We + /// have chosen to separate these for greater type safety and clearer compatibility with + /// the **AudioFormat** type. /// /// Original documentation [here](https://developer.apple.com/library/mac/documentation/MusicAudio/Reference/CoreAudioDataTypesRef/#//apple_ref/doc/constant_group/AudioStreamBasicDescription_Flags). flags LinearPCMFlags: u32 { @@ -403,9 +403,9 @@ pub mod apple_lossless_flags { /// **Available** in OS X v10.3 and later. /// /// Note: In the original Core Audio API these are consolidated with what we have named the - /// **StandardFlags** and **AppleLosslessFlag** types under the `AudioFormatFlag` type. We have - /// chosen to separate these for greater type safety and clearer compatibility with the - /// **AudioFormat** type. + /// **StandardFlags** and **AppleLosslessFlags** types under the `AudioFormatFlag` type. We + /// have chosen to separate these for greater type safety and clearer compatibility with + /// the **AudioFormat** type. /// /// Original documentation [here](https://developer.apple.com/library/mac/documentation/MusicAudio/Reference/CoreAudioDataTypesRef/#//apple_ref/doc/constant_group/AudioStreamBasicDescription_Flags). flags AppleLosslessFlags: u32 {