Skip to content

Latest commit

 

History

History
210 lines (159 loc) · 9.66 KB

README.md

File metadata and controls

210 lines (159 loc) · 9.66 KB

🔊 SimplyCoreAudio

Platform Swift support Swift Package Manager compatible GitHub tag License

SimplyCoreAudio (formerly known as AMCoreAudio) is a Swift framework that aims to make Core Audio use less tedious in macOS.

Features

  • Enumerating audio devices (see SimplyCoreAudio)
  • Getting/setting default input, output and system device (see SimplyCoreAudio)
  • Creating and destroying aggregate devices (see SimplyCoreAudio)
  • Querying audio device properties such as: name, manufacturer, UID, volume, mute, sample rate, clock source, etc. (see AudioDevice)
  • Managing (physical and virtual) audio streams associated to an audio device (see AudioStream)
  • Subscribing to audio hardware, audio device, and audio stream notifications (see Notification Extensions)

Resources

Requirements

  • Xcode 12+
  • Swift 4.0+
  • macOS 10.12+

Installation

To install the Swift Package, please follow the steps below:

  • Add https://github.com/rnine/SimplyCoreAudio.git as a Swift Package Manager dependency to your project.
  • When asked to Choose Package Options, use the default settings provided by Xcode.
  • When asked to Add Package, add SimplyCoreAudio to your desired target(s).

Usage

  1. Import SimplyCoreAudio

    import SimplyCoreAudio
  2. Instantiate SimplyCoreAudio

    let simplyCA = SimplyCoreAudio()
  3. Interact with SimplyCoreAudio

    // Get the default output device
    let device = simplyCA.defaultOutputDevice
    
    // Get all output devices
    simplyCA.allOutputDevices
    
    // You can also filter devices by the scope needed
    simplyCA.allDevices.filter { $0.channels(scope: .output) > 0 }
    
    // For example, list all devices that aren't aggregate ones that support input 
    simplyCA.allNonAggregateDevices.filter { $0.channels(scope: .input) > 0 }
    
    // After you've chosen a device you can set it as the default.
    // This will switch the selected device in the system
    device.isDefaultOutputDevice = true
    
    // Set the default input device to a new device
    device.isDefaultInputDevice = true
    
    // Get preferred output channels
    if let stereoPair = device.preferredChannelsForStereo(scope: .output) {
        let leftChannel = stereoPair.left
        let rightChannel = stereoPair.right
        // Use channels...
    }
    
    // Get device samplerate
    if let sampleRate = device.nominalSampleRate {
        // Use samplerate...
    }
    
    // Get device virtual main volume
    if let outVolume = device.virtualMainVolume(scope: .output) {
        // Use output volume...
    }
  4. Subscribe to hardware-related notifications

    // e.g., subscribing to `deviceListChanged` notification.
    var observer = NotificationCenter.default.addObserver(forName: .deviceListChanged,
                                                           object: nil,
                                                            queue: .main) { (notification) in
        // Get added devices.
        guard let addedDevices = notification.userInfo?["addedDevices"] as? [AudioDevice] else { return }
    
        // Get removed devices.
        guard let removedDevices = notification.userInfo?["removedDevices"] as? [AudioDevice] else { return }
    }
    
    // Once done observing, remove observer and nil it.
    NotificationCenter.default.removeObserver(observer)
    observer = nil
  5. Subscribe to notifications from a specific audio device

    // Get the default output device
    let device = simplyCA.defaultOutputDevice
    
    // e.g., subscribing to `deviceNominalSampleRateDidChange` notification.
    var observer = NotificationCenter.default.addObserver(forName: .deviceNominalSampleRateDidChange,
                                                           object: device,
                                                            queue: .main) { (notification) in
        // Handle notification.
    }
    
    // Once done observing, remove observer and nil it.
    NotificationCenter.default.removeObserver(observer)
    observer = nil
  6. Subscribe to notifications from a specific audio stream

    // Get the default output device
    let device = simplyCA.defaultOutputDevice
    
    // Get the first output stream
    guard let streams = device.streams(scope: .output) else { return }
    guard let stream0 = streams.first else { return }
    
    // e.g., subscribing to `streamPhysicalFormatDidChange` notification.
    var observer = NotificationCenter.default.addObserver(forName: .streamPhysicalFormatDidChange,
                                                           object: stream0,
                                                            queue: .main) { (notification) in
        // Handle notification.
    }
    
    // Once done observing, remove observer and nil it.
    NotificationCenter.default.removeObserver(observer)
    observer = nil

Supported Notifications

Audio Hardware Notifications

Name Purpose User Info
defaultInputDeviceChanged Called whenever the default input device changes. N/A
defaultOutputDeviceChanged Called whenever the default output device changes. N/A
defaultSystemOutputDeviceChanged Called whenever the default system output device changes. N/A
deviceListChanged Called whenever the list of hardware devices and device subdevices changes. addedDevices: [AudioDevice], removedDevices: [AudioDevice]

Audio Device Notifications

Name Purpose User Info
deviceNominalSampleRateDidChange Called whenever the audio device's sample rate changes. N/A
deviceAvailableNominalSampleRatesDidChange Called whenever the audio device's list of nominal sample rates changes. N/A
deviceClockSourceDidChange Called whenever the audio device's clock source changes. N/A
deviceNameDidChange Called whenever the audio device's name changes.
deviceOwnedObjectsDidChange Called whenever the list of owned audio devices on this audio device changes. N/A
deviceVolumeDidChange Called whenever the audio device's volume for a given channel and scope changes. channel: UInt32, scope: Scope
deviceMuteDidChange Called whenever the audio device's mute state for a given channel and scope changes. channel: UInt32, scope: Scope
deviceIsAliveDidChange Called whenever the audio device's list of nominal sample rates changes. N/A
deviceIsRunningDidChange Called whenever the audio device's is running property changes. N/A
deviceIsRunningSomewhereDidChange Called whenever the audio device's is running somewhere property changes. N/A
deviceIsJackConnectedDidChange Called whenever the audio device's is jack connected property changes. N/A
devicePreferredChannelsForStereoDidChange Called whenever the audio device's preferred channels for stereo property changes. N/A
deviceHogModeDidChange Called whenever the audio device's hog mode property changes. N/A

Audio Stream Notifications

Name Purpose User Info
streamIsActiveDidChange Called whenever the audio stream isActive flag changes state. N/A
streamPhysicalFormatDidChange Called whenever the audio stream physical format changes. N/A

Further Development & Patches

Do you want to contribute to the project? Please fork, patch, and then submit a pull request!

Running Tests

Please make sure to install NullAudio.driver before attempting to run tests:

Installing NullAudio.driver

  1. Download and build NullAudio.driver located at:
  1. Install into the system HAL Plug-Ins folder
    /Library/Audio/Plug-Ins/HAL
  2. Reload coreaudiod
    sudo launchctl kill KILL system/com.apple.audio.coreaudiod

Demo Project

  • SimplyCoreAudioDemo — a basic SwiftUI-based demo showcasing device enumeration and notifications.

License

SimplyCoreAudio was written by Ruben Nine (@rnine) in 2013-2014 (open-sourced in March 2014) and is licensed under the MIT license. See LICENSE.md.