Audio devices

Output #

An audioDevice item shows the default output device name, such as Studio Display Speakers, with a speaker icon. Set audioDevice.device to input to show the default input device, such as USB Microphone, with a microphone icon. Omitting the audioDevice block is equivalent to audioDevice: {}.

A missing device shows No output or No input. Failed reads show Output unavailable or Input unavailable. Blank names fall back to Unnamed device.

Configuration #

Use the item-level text template to customise or hide the label.

Set these options inside audioDevice.

States and labels #

tints accepts these state keys; the default labels are shown alongside them:

A device is disconnected when macOS reports no default device or reports that the device is no longer alive. A failed read or notification subscription produces unavailable. A failed input device read does not suppress a readable output device, and vice versa.

Accessibility retains the device name and direction, such as Input: USB Microphone, even with a custom label or text: "". Missing and unavailable states retain their default accessibility labels.

Appearance #

Omitted state symbols use the built-in defaults.

Symbols accept SF Symbol names or font glyph objects. Use symbolFontWeight to set SF Symbol weight independently of text.

An item-level symbol overrides the state icon. showSymbol: false hides all symbols, including this override. State tints override the normal item/theme tint.

To change audioDevice, edit the configuration file. sbar set cannot change this block.

Shared item options cover styling, symbols, actions, priority, and enabled state.

Text templates #

The item-level text setting supports id, value, symbol, name, status, available. See text templates for shared fields and syntax. Fields follow the selected input or output endpoint.

name contains the reported device name, or an empty string when none is available. value contains the formatted label. The provider collapses whitespace in names, uses Unnamed device for a blank name, and supplies the missing-device or read-error label. available is true only for a readable device. The status values match the device states above.

Use a state condition to add a prefix while preserving device names and error labels:

{
  "id": "microphone",
  "type": "audioDevice",
  "audioDevice": { "device": "input" },
  "text": "{{#status=available}}Mic: {{value}}{{/status}}{{^status=available}}{{value}}{{/status}}"
}

This displays Mic: USB Microphone for that device, Mic: Unnamed device for a blank name, and No input or Input unavailable for the other states. Use {{name}} when you need the reported name without the formatting or fallback. Provider hide rules still apply to custom text.

Updates #

Items and displays share one native event monitor. Monitoring starts when an audio device item becomes active and reads both default devices immediately. Core Audio notifications track default device changes, renames, device removal, and audio service restarts. Unavailable reads retry every two seconds.

Event items follow changes to their selected device. Interval and manual items hold a snapshot until refreshed or triggered. Snapshots retain input and output device state, text, icon, tint, and visibility together. Triggers capture the latest shared state. See refresh policies.

Current limits #

The provider follows the macOS default input and normal output. Applications can choose different devices, and macOS has a separate output for alerts. There is no device list, selector for a named device, or built-in switching control.

Reading device names does not record audio or change audio settings. Use the Volume provider for output volume and mute state.

Example #

Use two items to show the default output and input together:

{
  "schemaVersion": 1,
  "bar": {},
  "items": {
    "right": [
      { "id": "speakers", "type": "audioDevice" },
      {
        "id": "microphone",
        "type": "audioDevice",
        "audioDevice": {
          "device": "input",
          "hideWhenDisconnected": true,
          "tints": { "unavailable": "#ED8796" }
        }
      }
    ]
  }
}

The microphone item hides when there is no default input device. Read errors remain visible, with the configured colour. The output item uses the default settings.