#hs.audiodevice

Manipulate the system's audio devices

This module is based primarily on code from the previous incarnation of Mjolnir by Steven Degutis.

#Submodules

#API Overview

Functions - API calls offered directly by the extension

allDevices
allInputDevices
allOutputDevices
current
defaultEffectDevice
defaultInputDevice
defaultOutputDevice
findDeviceByName
findDeviceByUID
findInputByName
findInputByUID
findOutputByName
findOutputByUID

Methods - API calls which can only be made on an object returned by a constructor

allInputDataSources
allOutputDataSources
balance
currentInputDataSource
currentOutputDataSource
inputMuted
inputVolume
inUse
isInputDevice
isOutputDevice
jackConnected
muted
name
outputMuted
outputVolume
setBalance
setDefaultEffectDevice
setDefaultInputDevice
setDefaultOutputDevice
setInputMuted
setInputVolume
setMuted
setOutputMuted
setOutputVolume
setVolume
supportsInputDataSources
supportsOutputDataSources
transportType
uid
volume
watcherCallback
watcherIsRunning
watcherStart
watcherStop

#API Documentation

#Functions

#allDevices


Signature	`hs.audiodevice.allDevices() -> hs.audiodevice[]`
Type	Function
Description	Returns a list of all connected devices
Parameters	None
Returns	A table of zero or more audio devices connected to the system
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 173

#allInputDevices


Signature	`hs.audiodevice.allInputDevices() -> audio[]`
Type	Function
Description	Returns a list of all connected input devices.
Parameters	None
Returns	A table of zero or more audio input devices connected to the system
Notes	None
Examples	None
Source	extensions/audiodevice/audiodevice.lua line 141

#allOutputDevices


Signature	`hs.audiodevice.allOutputDevices() -> hs.audiodevice[]`
Type	Function
Description	Returns a list of all connected output devices
Parameters	None
Returns	A table of zero or more audio output devices connected to the system
Notes	None
Examples	None
Source	extensions/audiodevice/audiodevice.lua line 128

#current


Signature	`hs.audiodevice.current([input]) -> table`
Type	Function
Description	Fetch various metadata about the current default audio devices
Parameters	output - An optional boolean, true to fetch information about the default input device, false for output device. Defaults to false
Returns	A table with the following contents: `lua</li><li> {</li><li> name = defaultOutputDevice():name(),</li><li> uid = module.defaultOutputDevice():uid(),</li><li> muted = defaultOutputDevice():muted(),</li><li> volume = defaultOutputDevice():volume(),</li><li> device = defaultOutputDevice(),</li><li> }</li><li>`
Notes	None
Examples	None
Source	extensions/audiodevice/audiodevice.lua line 15

#defaultEffectDevice


Signature	`hs.audiodevice.defaultEffectDevice() -> audio or nil`
Type	Function
Description	Get the currently selected sound effect device
Parameters	None
Returns	An hs.audiodevice object, or nil if no suitable device could be found
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 315

#defaultInputDevice


Signature	`hs.audiodevice.defaultInputDevice() -> audio or nil`
Type	Function
Description	Get the currently selected audio input device
Parameters	None
Returns	An hs.audiodevice object, or nil if no suitable device could be found
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 284

#defaultOutputDevice


Signature	`hs.audiodevice.defaultOutputDevice() -> audio or nil`
Type	Function
Description	Get the currently selected audio output device
Parameters	None
Returns	An hs.audiodevice object, or nil if no suitable device could be found
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 253

#findDeviceByName


Signature	`hs.audiodevice.findDeviceByName(name) -> device or nil`
Type	Function
Description	Find an audio device by name
Parameters	name - A string containing the name of an audio device to search for
Returns	An `hs.audiodevice` object or nil if the device could not be found
Notes	None
Examples	None
Source	extensions/audiodevice/audiodevice.lua line 50

#findDeviceByUID


Signature	`hs.audiodevice.findDeviceByUID(uid) -> device or nil`
Type	Function
Description	Find an audio device by UID
Parameters	uid - A string containing the UID of an audio device to search for
Returns	An `hs.audiodevice` object or nil if the device could not be found
Notes	None
Examples	None
Source	extensions/audiodevice/audiodevice.lua line 63

#findInputByName


Signature	`hs.audiodevice.findInputByName(name) -> device or nil`
Type	Function
Description	Find an audio input device by name
Parameters	name - A string containing the name of an audio input device to search for
Returns	An hs.audiodevice object or nil if the device could not be found
Notes	None
Examples	None
Source	extensions/audiodevice/audiodevice.lua line 89

#findInputByUID


Signature	`hs.audiodevice.findInputByUID(uid) -> device or nil`
Type	Function
Description	Find an audio input device by UID
Parameters	name - A string containing the UID of an audio input device to search for
Returns	An hs.audiodevice object or nil if the device could not be found
Notes	None
Examples	None
Source	extensions/audiodevice/audiodevice.lua line 115

#findOutputByName


Signature	`hs.audiodevice.findOutputByName(name) -> device or nil`
Type	Function
Description	Find an audio output device by name
Parameters	name - A string containing the name of an audio output device to search for
Returns	An hs.audiodevice object or nil if the device could not be found
Notes	None
Examples	None
Source	extensions/audiodevice/audiodevice.lua line 76

#findOutputByUID


Signature	`hs.audiodevice.findOutputByUID(uid) -> device or nil`
Type	Function
Description	Find an audio output device by UID
Parameters	name - A string containing the UID of an audio output device to search for
Returns	An hs.audiodevice object or nil if the device could not be found
Notes	None
Examples	None
Source	extensions/audiodevice/audiodevice.lua line 102

#Methods

#allInputDataSources


Signature	`hs.audiodevice:allInputDataSources() -> hs.audiodevice.dataSource[] or nil`
Type	Method
Description	Gets all of the input data sources of an audio device
Parameters	None
Returns	A list of hs.audiodevice.dataSource objects, or nil if an error occurred
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 1499

#allOutputDataSources


Signature	`hs.audiodevice:allOutputDataSources() -> hs.audiodevice.dataSource[] or nil`
Type	Method
Description	Gets all of the output data sources of an audio device
Parameters	None
Returns	A list of hs.audiodevice.dataSource objects, or nil if an error occurred
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 1446

#balance


Signature	`hs.audiodevice:balance() -> number or nil`
Type	Method
Description	Get the current left/right balance of this audio device
Parameters	None
Returns	A number between 0.0 and 1.0, representing the balance (0.0 for full left, 1.0 for full right, 0.5 for center), or nil if the audio device does not support balance
Notes	The return value will be a floating point number This method will inspect the device to determine if it is an input or output device, and return the appropriate volume. For devices that are both input and output devices, see `:inputVolume()` and `:outputVolume()`
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 1067

#currentInputDataSource


Signature	`hs.audiodevice:currentInputDataSource() -> hs.audiodevice.dataSource object or nil`
Type	Method
Description	Gets the current input data source of an audio device
Parameters	None
Returns	An hs.audiodevice.dataSource object, or nil if an error occurred
Notes	Before calling this method, you should check the result of hs.audiodevice:supportsInputDataSources()
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 1372

#currentOutputDataSource


Signature	`hs.audiodevice:currentOutputDataSource() -> hs.audiodevice.dataSource object or nil`
Type	Method
Description	Gets the current output data source of an audio device
Parameters	None
Returns	An hs.audiodevice.dataSource object, or nil if an error occurred
Notes	Before calling this method, you should check the result of hs.audiodevice:supportsOutputDataSources()
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 1409

#inputMuted


Signature	`hs.audiodevice:inputMuted() -> bool or nil`
Type	Method
Description	Get the Input mutedness state of the audio device
Parameters	None
Returns	True if the audio device's Input is muted. False if it's not muted, nil if it does not support muting
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 563

#inputVolume


Signature	`hs.audiodevice:inputVolume() -> number or nil`
Type	Method
Description	Get the current input volume of this audio device
Parameters	None
Returns	A number between 0 and 100, representing the input volume percentage, or nil if the audio device does not support input volume levels
Notes	The return value will be a floating point number
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 794

#inUse


Signature	`hs.audiodevice:inUse() -> bool or nil`
Type	Method
Description	Check if the audio device is in use
Parameters	None
Returns	True if the audio device is in use, False if not. nil if an error occurred.
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 521

#isInputDevice


Signature	`hs.audiodevice:isInputDevice() -> boolean`
Type	Method
Description	Determines if an audio device is an input device
Parameters	None
Returns	A boolean, true if the device is an input device, false if not
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 1185

#isOutputDevice


Signature	`hs.audiodevice:isOutputDevice() -> boolean`
Type	Method
Description	Determines if an audio device is an output device
Parameters	None
Returns	A boolean, true if the device is an output device, false if not
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 1165

#jackConnected


Signature	`hs.audiodevice:jackConnected() -> boolean or nil`
Type	Method
Description	Determines whether an audio jack (e.g. headphones) is connected to an audio device
Parameters	None
Returns	A boolean, true if a jack is connected, false if not, or nil if the device does not support jack sense
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 1284

#muted


Signature	`hs.audiodevice:muted() -> bool or nil`
Type	Method
Description	Get the mutedness state of the audio device
Parameters	None
Returns	True if the audio device is muted, False if it is not muted, nil if it does not support muting
Notes	If a device is capable of both input and output, this method will prefer the output. See `:inputMuted()` and `:outputMuted()` for specific variants.
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 635

#name


Signature	`hs.audiodevice:name() -> string or nil`
Type	Method
Description	Get the name of the audio device
Parameters	None
Returns	A string containing the name of the audio device, or nil if it has no name
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 448

#outputMuted


Signature	`hs.audiodevice:outputMuted() -> bool or nil`
Type	Method
Description	Get the Output mutedness state of the audio device
Parameters	None
Returns	True if the audio device's Output is muted. False if it's not muted, nil if it does not support muting
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 599

#outputVolume


Signature	`hs.audiodevice:outputVolume() -> number or nil`
Type	Method
Description	Get the current output volume of this audio device
Parameters	None
Returns	A number between 0 and 100, representing the output volume percentage, or nil if the audio device does not support output volume levels
Notes	The return value will be a floating point number
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 835

#setBalance


Signature	`hs.audiodevice:setBalance(level) -> bool`
Type	Method
Description	Set the balance of this audio device
Parameters	level - A number between 0.0 and 1.0, representing the balance (0.0 for full left, 1.0 for full right, 0.5 for center)
Returns	True if the balance was set, false if the audio device does not support setting a balance.
Notes	This method will inspect the device to determine if it is an input or output device, and set the appropriate volume. For devices that are both input and output devices, see `:setInputVolume()` and `:setOutputVolume()`
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 1112

#setDefaultEffectDevice


Signature	`hs.audiodevice:setDefaultEffectDevice() -> bool`
Type	Method
Description	Selects this device as the audio output device for system sound effects
Parameters	None
Returns	True if the audio device was successfully selected, otherwise false.
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 382

#setDefaultInputDevice


Signature	`hs.audiodevice:setDefaultInputDevice() -> bool`
Type	Method
Description	Selects this device as the system's audio input device
Parameters	None
Returns	True if the audio device was successfully selected, otherwise false.
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 415

#setDefaultOutputDevice


Signature	`hs.audiodevice:setDefaultOutputDevice() -> bool`
Type	Method
Description	Selects this device as the system's audio output device
Parameters	None
Returns	True if the audio device was successfully selected, otherwise false.
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 349

#setInputMuted


Signature	`hs.audiodevice:setInputMuted(state) -> bool`
Type	Method
Description	Set the mutedness state of the Input of the audio device
Parameters	state - A boolean value. True to mute the device, False to unmute it
Returns	True if the device's Input mutedness state was set, or False if it does not support muting
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 678

#setInputVolume


Signature	`hs.audiodevice:setInputVolume(level) -> bool`
Type	Method
Description	Set the input volume of this audio device
Parameters	level - A number between 0 and 100, representing the input volume as a percentage
Returns	True if the volume was set, false if the audio device does not support setting an input volume level
Notes	The volume level is a floating point number. Depending on your audio hardware, it may not be possible to increase volume in single digit increments
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 921

#setMuted


Signature	`hs.audiodevice:setMuted(state) -> bool`
Type	Method
Description	Set the mutedness state of the audio device
Parameters	state - A boolean value. True to mute the device, False to unmute it
Returns	True if the device's mutedness state was set, or False if it does not support muting
Notes	If a device is capable of both input and output, this method will prefer the output. See `:setInputMuted()` and `:setOutputMuted()` for specific variants.
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 751

#setOutputMuted


Signature	`hs.audiodevice:setOutputMuted(state) -> bool`
Type	Method
Description	Set the mutedness state of the Output of the audio device
Parameters	state - A boolean value. True to mute the device, False to unmute it
Returns	True if the device's Output mutedness state was set, or False if it does not support muting
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 714

#setOutputVolume


Signature	`hs.audiodevice:setOutputVolume(level) -> bool`
Type	Method
Description	Set the output volume of this audio device
Parameters	level - A number between 0 and 100, representing the output volume as a percentage
Returns	True if the volume was set, false if the audio device does not support setting an output volume level
Notes	The volume level is a floating point number. Depending on your audio hardware, it may not be possible to increase volume in single digit increments
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 967

#setVolume


Signature	`hs.audiodevice:setVolume(level) -> bool`
Type	Method
Description	Set the volume of this audio device
Parameters	level - A number between 0 and 100, representing the volume as a percentage
Returns	True if the volume was set, false if the audio device does not support setting a volume level.
Notes	The volume level is a floating point number. Depending on your audio hardware, it may not be possible to increase volume in single digit increments. This method will inspect the device to determine if it is an input or output device, and set the appropriate volume. For devices that are both input and output devices, see `:setInputVolume()` and `:setOutputVolume()`
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 1013

#supportsInputDataSources


Signature	`hs.audiodevice:supportsInputDataSources() -> boolean`
Type	Method
Description	Determines whether an audio device supports input data sources
Parameters	None
Returns	A boolean, true if the device supports input data sources, false if not
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 1318

#supportsOutputDataSources


Signature	`hs.audiodevice:supportsOutputDataSources() -> boolean`
Type	Method
Description	Determines whether an audio device supports output data sources
Parameters	None
Returns	A boolean, true if the device supports output data sources, false if not
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 1345

#transportType


Signature	`hs.audiodevice:transportType() -> string`
Type	Method
Description	Gets the hardware transport type of an audio device
Parameters	None
Returns	A string containing the transport type, or nil if an error occurred
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 1205

#uid


Signature	`hs.audiodevice:uid() -> string or nil`
Type	Method
Description	Get the unique identifier of the audio device
Parameters	None
Returns	A string containing the UID of the audio device, or nil if it has no UID.
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 482

#volume


Signature	`hs.audiodevice:volume() -> number or nil`
Type	Method
Description	Get the current volume of this audio device
Parameters	None
Returns	A number between 0 and 100, representing the volume percentage, or nil if the audio device does not support volume levels
Notes	The return value will be a floating point number This method will inspect the device to determine if it is an input or output device, and return the appropriate volume. For devices that are both input and output devices, see `:inputVolume()` and `:outputVolume()`
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 876

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.audiodevice:watcherCallback(fn) -> hs.audiodevice | | Type | Method | | Description | Sets or removes a callback function for an audio device watcher | | Parameters |

fn - A callback function that will be called when properties of this audio device change, or nil to remove an existing callback. The function should accept four arguments: A string containing the UID of the audio device (see hs.audiodevice.findDeviceByUID()) A string containing the name of the event. Possible values are: vmvc - Volume changed mute - Mute state changed jack - Jack sense state changed (usually this means headphones were plugged/unplugged) span - Stereo pan changed diff - Device configuration changed (if you are caching audio device properties, this event indicates you should flush your cache) gone - The device's "in use" status changed (ie another app started using the device, or stopped using it) A string containing the scope of the event. Possible values are: glob - This is a global event pertaining to the whole device inpt - This is an event pertaining only to the input functions of the device outp - This is an event pertaining only to the output functions of the device A number containing the element of the event. Typical values are: 0 - Typically this means the Master channel 1 - Typically this means the Left channel 2 - Typically this means the Right channel

| | Returns |

The hs.audiodevice object

| | Notes |

You will receive many events to your callback, so filtering on the name/scope/element arguments is vital. For example, on a stereo device, it is not uncommon to receive a volm event for each audio channel when the volume changes, or multiple mute events for channels. Dragging a volume slider in the system Sound preferences will produce a large number of volm events. Plugging/unplugging headphones may trigger volm events in addition to jack ones, etc.
If you need to use the hs.audiodevice object in your callback, use hs.audiodevice.findDeviceByUID() to obtain it fro the first callback argument

#watcherIsRunning


Signature	`hs.audiodevice:watcherIsRunning() -> boolean`
Type	Method
Description	Gets the status of the `hs.audiodevice` object watcher
Parameters	None
Returns	A boolean, true if the watcher is running, false if not
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 1698

#watcherStart


Signature	`hs.audiodevice:watcherStart() -> hs.audiodevice or nil`
Type	Method
Description	Starts the watcher on an `hs.audiodevice` object
Parameters	None
Returns	The `hs.audiodevice` object, or nil if an error occurred
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 1608

#watcherStop


Signature	`hs.audiodevice:watcherStop() -> hs.audiodevice`
Type	Method
Description	Stops the watcher on an `hs.audiodevice` object
Parameters	None
Returns	The `hs.audiodevice` object
Notes	None
Examples	None
Source	extensions/audiodevice/libaudiodevice.m line 1676