Macos Audio Devices

https://github.com/spotxyz/macos-audio-devices
Admin
A Node.js library and CLI tool to get, set, and configure audio devices on macOS, including managing...
Tokens:1,952
Snippets:22
Trust Score:5.1
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Node.js API Example: Get and Set Default Output Device

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Demonstrates how to use the Node.js API to retrieve output devices, get the current default output device, set a new default, and adjust device volume.

```javascript
const audioDevices = require('@spotxyz/macos-audio-devices');

const outputDevices = audioDevices.getOutputDevices.sync();
const targetDevice = outputDevices[0];

const defaultDevice = audioDevices.getDefaultOutputDevice.sync();

if (defaultDevice.id !== targetDevice.id) {
  setDefaultOutputDevice(targetDevice.id)
}

if (targetDevice.hasVolume) {
  setOutputDeviceVolume(targetDevice.id, 0.5); // 50%
}
```

--------------------------------

### Install macOS Audio Devices CLI Globally

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Install the macOS audio devices CLI tool globally using npm for direct command execution.

```shell
$ npm install -g @spotxyz/macos-audio-devices
$ audio-devices
```

--------------------------------

### Install macOS Audio Devices Node.js Module

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Install the `@spotxyz/macos-audio-devices` package as a dependency in your Node.js project.

```shell
$ npm install @spotxyz/macos-audio-devices
```

--------------------------------

### Run macOS Audio Devices CLI with npx

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Execute the macOS audio devices CLI tool directly using npx without global installation.

```shell
$ npx @spotxyz/macos-audio-devices
```

--------------------------------

### API Reference: getAllDevices()

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Retrieves a promise that resolves to an array of all available audio devices.

```APIDOC
getAllDevices(): Promise<Device[]>
  Get all the audio devices.
```

--------------------------------

### View macOS Audio Devices CLI Commands

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Display the available commands and options for the macOS audio devices CLI tool.

```shell
Usage: audio-devices <command> [options]

Groups:
  output          Get or set the default output device
  input           Get or set the default input device
  system          Get or set the default device for system sounds
  volume          Get or set the volume of an output device
  aggregate       Create or delete aggregate audio devices

Commands:
  list            List the available audio devices
  get             Get a device by its ID
  help            Prints help information
```

--------------------------------

### API Reference: getOutputDevices()

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Retrieves a promise that resolves to an array of all available output devices.

```APIDOC
getOutputDevices(): Promise<Device[]>
  Get all the output devices.
```

--------------------------------

### API Reference: getInputDevices()

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Retrieves a promise that resolves to an array of all available input devices.

```APIDOC
getInputDevices(): Promise<Device[]>
  Get all the input devices.
```

--------------------------------

### Node.js API: Synchronous Method Calls

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Illustrates how to use the `.sync` property on asynchronous methods to perform synchronous operations.

```javascript
getDevice(73).then(device => {…}); // async

const device = getDevice.sync(73); // sync
```

--------------------------------

### API Reference: Device Interface

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Defines the structure and properties of an audio `Device` object returned by the API.

```APIDOC
Device:
  id: number
    The unique ID of the device.
  uid: string
    The UID of the device for the AVCaptureDevice API.
  name: string
    The human readable name of the device.
  isOutput: bool
    Whether the device is an output device.
  isInput: bool
    Whether the device is an input device.
  volume: number
    A number between 0 and 1 representing the volume setting of the device. Only applicable on output devices that support it. It will be undefined otherwise.
  transportType: TransportType
    The value of this property represents the transport type of the device (USB, PCI, etc).
```

--------------------------------

### API Reference: getDefaultOutputDevice()

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Retrieves a promise that resolves to the current default output device.

```APIDOC
getDefaultOutputDevice(): Promise<Device>
  Get all the default output device.
```

--------------------------------

### API Reference: getDefaultSystemDevice()

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Retrieves a promise that resolves to the current default device for system sounds.

```APIDOC
getDefaultSystemDevice(): Promise<Device>
  Get all the default input device.
```

--------------------------------

### API Reference: getDefaultInputDevice()

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Retrieves a promise that resolves to the current default input device.

```APIDOC
getDefaultInputDevice(): Promise<Device>
  Get all the default input device.
```

--------------------------------

### Create macOS Aggregate Audio Device

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Creates an aggregate audio device from multiple existing devices. Note that aggregate devices do not support volume control directly; volume must be adjusted on the constituent devices.

```APIDOC
createAggregateDevice(name: string, mainDeviceId: number, otherDeviceIds: number[], options: object): Promise<Device>
  name: string
    Human-readable name for the new device.
  mainDeviceId: number
    The unique ID of the main device.
  otherDeviceIds: number[]
    An array of unique IDs of the rest of the devices. Needs to have at least one.
  options: object
    options.multiOutput: boolean
      Whether or not to create a Multi-Output Device.
      If this is enabled, all the devices need to be output devices.
```

--------------------------------

### API Reference: getDevice(deviceId)

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Retrieves a promise that resolves to a specific audio device by its unique ID.

```APIDOC
getDevice(deviceId: number): Promise<Device>
  Get an audio device by its ID.
  Parameters:
    deviceId: number
      The unique ID of the device.
```

--------------------------------

### API Reference: getOutputDeviceVolume(deviceId)

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Retrieves a promise that resolves to the volume level of a specified output device, if supported. Throws an error if the device is not an output device or does not support volume control.

```APIDOC
getOutputDeviceVolume(deviceId: number): Promise<void>
  Get the volume level of an output device that supports it.
  Throws an error if the device is not an output device or if it doesn't support volume.
  Parameters:
    deviceId: number
      The unique ID of the supported output device.
```

--------------------------------

### API Reference: setDefaultSystemDevice(deviceId)

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Sets the default device for system sounds using its unique ID. This must be an output device.

```APIDOC
setDefaultSystemDevice(deviceId: number): Promise<void>
  Set the default input device. Can only be an output device.
  Parameters:
    deviceId: number
      The unique ID of an output device.
```

--------------------------------

### API Reference: setOutputDeviceVolume(deviceId, volume)

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Sets the volume level of a specified output device, if supported. Throws an error if the device is not an output device, does not support volume control, or if the volume value is out of range (0-1).

```APIDOC
setOutputDeviceVolume(deviceId: number, volume: number): Promise<void>
  Set the volume level of an output device that supports it.
  Throws an error if the device is not an output device or if it doesn't support volume.
  Parameters:
    deviceId: number
      The unique ID of the supported output device.
    volume: number
      The volume level to set the device to. Must be between 0 and 1, otherwise and error will be thrown.
```

--------------------------------

### API Reference: setDefaultOutputDevice(deviceId)

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Sets the default output device using its unique ID.

```APIDOC
setDefaultOutputDevice(deviceId: number): Promise<void>
  Set the default output device.
  Parameters:
    deviceId: number
      The unique ID of an output device.
```

--------------------------------

### API Reference: TransportType Enum

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Defines the possible string values for the `transportType` property of a `Device`.

```APIDOC
TransportType: string
  Can be one of:
  - avb
  - aggregate
  - airplay
  - autoaggregate
  - bluetooth
  - bluetoothle
  - builtin
  - displayport
  - firewire
  - hdmi
  - pci
  - thunderbolt
  - usb
  - virtual
  - unknown
```

--------------------------------

### API Reference: setDefaultInputDevice(deviceId)

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Sets the default input device using its unique ID.

```APIDOC
setDefaultInputDevice(deviceId: number): Promise<void>
  Set the default input device.
  Parameters:
    deviceId: number
      The unique ID of an input device.
```

--------------------------------

### Destroy macOS Aggregate Audio Device

Source: https://github.com/spotxyz/macos-audio-devices/blob/master/readme.md

Destroys an existing aggregate audio device using its unique ID.

```APIDOC
destroyAggregateDevice(deviceId: number): Promise<void>
  deviceId: number
    The unique ID of an aggregate device.
```
Tokens:
Raw