HSAudioDevice
TypeAn audio device attached to the system.
Obtain instances via hs.audiodevice module methods — do not instantiate directly.
Getting and setting volume
const dev = hs.audiodevice.defaultOutputDevice();
if (dev) {
console.log(dev.volume); // 0.0 – 1.0, or null
dev.volume = 0.5;
}
Watching for changes
const dev = hs.audiodevice.defaultOutputDevice();
if (dev) {
var fn = function(event) { console.log("Device event:", event); };
dev.addWatcher(fn);
// later…
dev.removeWatcher(fn);
}
Properties
transportType
string
The transport mechanism: `"built-in"`, `"usb"`, `"bluetooth"`, `"bluetooth-le"`,
`"hdmi"`, `"display-port"`, `"firewire"`, `"airplay"`, `"avb"`,
`"thunderbolt"`, `"virtual"`, `"aggregate"`, `"pci"`, or `"unknown"`.
volume
NSNumber
Output volume scalar in the range `0.0`–`1.0`, or `null` if the device has
no controllable output volume. Setting `null` is a no-op.
balance
NSNumber
Output stereo balance in the range `0.0` (full left)–`1.0` (full right),
or `null` if balance control is not available.
inputVolume
NSNumber
Input (microphone) volume scalar in the range `0.0`–`1.0`, or `null` if
the device has no controllable input volume.
availableSampleRates
NSNumber[]
All sample rates (in Hz) that this device supports.
For devices that support a range, both the minimum and maximum are included.
Methods
currentOutputDataSource() -> NSDictionary
The current output data source as `{ id, name }`, or `null` if unavailable.
Declaration
currentOutputDataSource() -> NSDictionaryReturns
NSDictionary
A dictionary containing the id and name of the current output data source
Example
const dev = hs.audiodevice.defaultOutputDevice()
console.log(dev.currentOutputDataSource())currentInputDataSource() -> NSDictionary
The current input data source as `{ id, name }`, or `null` if unavailable.
Declaration
currentInputDataSource() -> NSDictionaryReturns
NSDictionary
A dictionary containing the id and name of the current input data source
Example
const mic = hs.audiodevice.defaultInputDevice()
console.log(mic.currentInputDataSource())outputDataSources() -> NSDictionary[]
All available output data sources as an array of `{ id, name }` objects.
Declaration
outputDataSources() -> NSDictionary[]Returns
NSDictionary[]
A dictionary containing the ids and names of all available output data sources
Example
const dev = hs.audiodevice.defaultOutputDevice()
console.log(dev.outputDataSources())inputDataSources() -> NSDictionary[]
All available input data sources as an array of `{ id, name }` objects.
Declaration
inputDataSources() -> NSDictionary[]Returns
NSDictionary[]
A dictionary containing the ids and names of all available input data sources
Example
const mic = hs.audiodevice.defaultInputDevice()
console.log(mic.inputDataSources())setCurrentOutputDataSource(sourceID) -> boolean
Select an output data source by its numeric ID.
Declaration
setCurrentOutputDataSource(sourceID) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| sourceID | number | The `id` value from ``outputDataSources()`` |
Returns
boolean
`true` on success
Example
const dev = hs.audiodevice.defaultOutputDevice()
const sources = dev.outputDataSources()
dev.setCurrentOutputDataSource(sources[0].id)setCurrentInputDataSource(sourceID) -> boolean
Select an input data source by its numeric ID.
Declaration
setCurrentInputDataSource(sourceID) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| sourceID | number | The `id` value from ``inputDataSources()`` |
Returns
boolean
`true` on success
Example
const mic = hs.audiodevice.defaultInputDevice()
const sources = mic.inputDataSources()
mic.setCurrentInputDataSource(sources[0].id)setDefaultOutputDevice() -> boolean
Make this device the system default output device.
Declaration
setDefaultOutputDevice() -> booleanReturns
boolean
`true` on success
Example
const usb = hs.audiodevice.findDeviceByName("USB Audio CODEC")
usb.setDefaultOutputDevice()setDefaultInputDevice() -> boolean
Make this device the system default input device.
Declaration
setDefaultInputDevice() -> booleanReturns
boolean
`true` on success
Example
const mic = hs.audiodevice.findDeviceByName("External Mic")
mic.setDefaultInputDevice()setDefaultEffectDevice() -> boolean
Make this device the system alert sound (effect) device.
Declaration
setDefaultEffectDevice() -> booleanReturns
boolean
`true` on success
Example
const dev = hs.audiodevice.defaultOutputDevice()
dev.setDefaultEffectDevice()addWatcher(listener) -> None
Register a listener for a per-device property-change event.
Declaration
addWatcher(listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| listener | JSValue | A JavaScript function that receives an event name string |
Returns
None
Example
const dev = hs.audiodevice.defaultOutputDevice()
dev.addWatcher((event) => console.log("Event:", event))removeWatcher(listener) -> None
Remove a previously registered per-device listener.
Declaration
removeWatcher(listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| listener | JSValue | The JavaScript function that was passed to ``addWatcher(_:)`` |
Returns
None
Example
const dev = hs.audiodevice.defaultOutputDevice()
dev.removeWatcher(myHandler)