Getting Started
Contributing
Control CommandPost
Plugins
Internationalisation
CommandPost API
Bundled Plugins API
Hammerspoon API
audiodevice
Manipulate the system's audio devices
Submodules
API Overview
- Functions - API calls offered directly by the extension
- Methods - API calls which can only be made on an object returned by a constructor
API Documentation
Functions
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
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
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
Signature
hs.audiodevice.current([input]) -> tableType
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 { name = defaultOutputDevice():name(), uid = module.defaultOutputDevice():uid(), muted = defaultOutputDevice():muted(), volume = defaultOutputDevice():volume(), device = defaultOutputDevice(), }
Signature
hs.audiodevice.defaultEffectDevice() -> audio or nilType
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
Signature
hs.audiodevice.defaultInputDevice() -> audio or nilType
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
Signature
hs.audiodevice.defaultOutputDevice() -> audio or nilType
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
Signature
hs.audiodevice.findDeviceByName(name) -> device or nilType
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.audiodeviceobject or nil if the device could not be found
Signature
hs.audiodevice.findDeviceByUID(uid) -> device or nilType
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.audiodeviceobject or nil if the device could not be found
Signature
hs.audiodevice.findInputByName(name) -> device or nilType
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
Signature
hs.audiodevice.findInputByUID(uid) -> device or nilType
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
Signature
hs.audiodevice.findOutputByName(name) -> device or nilType
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
Signature
hs.audiodevice.findOutputByUID(uid) -> device or nilType
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
Methods
Signature
hs.audiodevice:allInputDataSources() -> hs.audiodevice.dataSource[] or nilType
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
Signature
hs.audiodevice:allOutputDataSources() -> hs.audiodevice.dataSource[] or nilType
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
Signature
hs.audiodevice:balance() -> number or nilType
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()
Signature
hs.audiodevice:currentInputDataSource() -> hs.audiodevice.dataSource object or nilType
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()
Signature
hs.audiodevice:currentOutputDataSource() -> hs.audiodevice.dataSource object or nilType
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()
Signature
hs.audiodevice:inputMuted() -> bool or nilType
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
Signature
hs.audiodevice:inputVolume() -> number or nilType
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
Signature
hs.audiodevice:isInputDevice() -> booleanType
Method
Description
Determins if an audio device is an input device
Parameters
- None
Returns
- A boolean, true if the device is an input device, false if not
Signature
hs.audiodevice:isOutputDevice() -> booleanType
Method
Description
Determins if an audio device is an output device
Parameters
- None
Returns
- A boolean, true if the device is an output device, false if not
Signature
hs.audiodevice:jackConnected() -> boolean or nilType
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
Signature
hs.audiodevice:muted() -> bool or nilType
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.
Signature
hs.audiodevice:name() -> string or nilType
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
Signature
hs.audiodevice:outputMuted() -> bool or nilType
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
Signature
hs.audiodevice:outputVolume() -> number or nilType
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
Signature
hs.audiodevice:setBalance(level) -> boolType
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()
Signature
hs.audiodevice:setDefaultEffectDevice() -> boolType
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.
Signature
hs.audiodevice:setDefaultInputDevice() -> boolType
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.
Signature
hs.audiodevice:setDefaultOutputDevice() -> boolType
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.
Signature
hs.audiodevice:setInputMuted(state) -> boolType
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
Signature
hs.audiodevice:setInputVolume(level) -> boolType
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
Signature
hs.audiodevice:setMuted(state) -> boolType
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
:inputSetMuted()and:outputSetMuted()for specific variants.
Signature
hs.audiodevice:setOutputMuted(state) -> boolType
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
Signature
hs.audiodevice:setOutputVolume(level) -> boolType
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
Signature
hs.audiodevice:setVolume(level) -> boolType
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()
Signature
hs.audiodevice:supportsInputDataSources() -> booleanType
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
Signature
hs.audiodevice:supportsOutputDataSources() -> booleanType
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
Signature
hs.audiodevice:transportType() -> stringType
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
Signature
hs.audiodevice:uid() -> string or nilType
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.
Signature
hs.audiodevice:volume() -> number or nilType
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 d