hs.audiodevice
ModuleModule for discovering and controlling audio devices.
Finding devices
const all = hs.audiodevice.all();
const out = hs.audiodevice.defaultOutputDevice();
const mic = hs.audiodevice.defaultInputDevice();
Selecting a device
const usb = hs.audiodevice.findDeviceByName("USB Audio CODEC");
if (usb) usb.setDefaultOutputDevice();
Watching for system-level changes
Available events: "dOut" (default output changed), "dIn" (default input changed),
"dSErr" (default alert sound device changed), "dev+" (a device was added), "dev-"
(a device was removed).
var fn = function() { console.log("Default output changed") };
hs.audiodevice.on("dOut", fn);
// later…
hs.audiodevice.off("dOut", fn);
Types
This module provides the following types:
Properties
This module has no properties.
Methods
hs.audiodevice.all() -> HSAudioDevice[]
All audio devices attached to the system.
Declaration
hs.audiodevice.all() -> HSAudioDevice[]Returns
HSAudioDevice[]
An array of HSAudioDevice objects
Example
const devs = hs.audiodevice.all()
devs.forEach(d => console.log(d.name))hs.audiodevice.allOutputDevices() -> HSAudioDevice[]
All audio devices that have at least one output stream.
Declaration
hs.audiodevice.allOutputDevices() -> HSAudioDevice[]Returns
HSAudioDevice[]
An array of HSAudioDevice objects
Example
const outputs = hs.audiodevice.allOutputDevices()hs.audiodevice.allInputDevices() -> HSAudioDevice[]
All audio devices that have at least one input stream.
Declaration
hs.audiodevice.allInputDevices() -> HSAudioDevice[]Returns
HSAudioDevice[]
An array of HSAudioDevice objects
Example
const inputs = hs.audiodevice.allInputDevices()hs.audiodevice.defaultOutputDevice() -> HSAudioDevice
The current system default output device.
Declaration
hs.audiodevice.defaultOutputDevice() -> HSAudioDeviceReturns
HSAudioDevice
An HSAudioDevice, or null if none is set
Example
const out = hs.audiodevice.defaultOutputDevice()
console.log(out && out.name)hs.audiodevice.defaultInputDevice() -> HSAudioDevice
The current system default input device.
Declaration
hs.audiodevice.defaultInputDevice() -> HSAudioDeviceReturns
HSAudioDevice
An HSAudioDevice, or null if none is set
Example
const mic = hs.audiodevice.defaultInputDevice()hs.audiodevice.defaultEffectDevice() -> HSAudioDevice
The current system alert sound device.
Declaration
hs.audiodevice.defaultEffectDevice() -> HSAudioDeviceReturns
HSAudioDevice
An HSAudioDevice, or null if none is set
Example
const effect = hs.audiodevice.defaultEffectDevice()hs.audiodevice.findDeviceByName(name) -> HSAudioDevice
Find the first audio device whose name matches the given string.
Declaration
hs.audiodevice.findDeviceByName(name) -> HSAudioDeviceParameters
| Name | Type | Description |
|---|---|---|
| name | string | The device name to search for |
Returns
HSAudioDevice
An HSAudioDevice if found, null otherwise
Example
const usb = hs.audiodevice.findDeviceByName("USB Audio CODEC")hs.audiodevice.findDeviceByUID(uid) -> HSAudioDevice
Find the audio device with the given unique identifier.
Declaration
hs.audiodevice.findDeviceByUID(uid) -> HSAudioDeviceParameters
| Name | Type | Description |
|---|---|---|
| uid | string | The device UID to search for |
Returns
HSAudioDevice
An HSAudioDevice if found, null otherwise
Example
const dev = hs.audiodevice.findDeviceByUID("BuiltInSpeakerDevice")hs.audiodevice.on(event, listener) -> None
Register a listener for a named system-level audio configuration event.
Declaration
hs.audiodevice.on(event, listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| event | any | The event to listen for |
| listener | any | Called when the event occurs |
Returns
None
Throws
Throws an Error on failure; wrap calls in try/catch to handle it.
Example
try {
hs.audiodevice.on('dOut', () => console.log("Default output changed"))
hs.audiodevice.on('dev+', () => console.log("A device was added"))
} catch (err) {
console.error(err.message)
}hs.audiodevice.off(event, listener) -> None
Remove a previously registered system-level audio event listener.
Declaration
hs.audiodevice.off(event, listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| event | any | The event the listener was registered for |
| listener | any | The function originally passed to `on` |
Returns
None
Example
const onDefaultOutChange = () => console.log("changed")
hs.audiodevice.on('dOut', onDefaultOutChange)
// later…
hs.audiodevice.off('dOut', onDefaultOutChange)hs.audiodevice.once(event, listener) -> None
Register a listener that fires at most once for a system-level audio configuration event.
Declaration
hs.audiodevice.once(event, listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| event | any | The event to listen for |
| listener | any | Called the next time a matching event occurs, then automatically removed |
Returns
None
Throws
Throws an Error on failure; wrap calls in try/catch to handle it.
Example
try {
hs.audiodevice.once('dev+', () => console.log("First device-added event seen"))
} catch (err) {
console.error(err.message)
}