/audioaccessorykit

name: audioaccessorykit
description: "Support automatic audio switching for paired third-party Bluetooth headphones or earbuds with AudioAccessoryKit. Use when a companion app registers an audio accessory, an app extension reports worn/removed placement or connected source-device changes, or AccessoryControlDevice capabilities and errors need handling. Do not use for general AVAudioSession routing, Bluetooth transport, or initial accessory pairing."

AudioAccessoryKit

Automatic audio switching support and intelligent audio routing inputs for third-party audio accessories. Enables companion apps to register audio accessory configuration with the system, and app extensions to report placement and connected source changes that help the system switch audio output. Available iOS 26.4+ / iPadOS 26.4+.

> **Beta-sensitive.** AudioAccessoryKit is new in iOS 26.4. Re-check current > Apple documentation before relying on specific API details.

AudioAccessoryKit builds on top of AccessorySetupKit. The accessory must first be paired via AccessorySetupKit before it can be registered for audio features. The central type is `AccessoryControlDevice`, which registers a `Configuration` from the container app and applies ongoing configuration updates from the app extension.

Contents

• [Setup](#setup)
• [Session Management](#session-management)
• [Audio Switching](#audio-switching)
• [Device Placement](#device-placement)
• [Connected Audio Sources](#connected-audio-sources)
• [Feature Discovery](#feature-discovery)
• [Error Handling](#error-handling)
• [Common Mistakes](#common-mistakes)
• [Review Checklist](#review-checklist)
• [References](#references)

Setup

Prerequisites

1. Pair the accessory over Bluetooth using AccessorySetupKit. This yields an `ASAccessory` object. 2. Import the frameworks where needed in the container app and extension:

import AccessorySetupKit
import AudioAccessoryKit

Framework Availability

| Platform | Minimum Version | |---|---| | iOS | 26.4+ | | iPadOS | 26.4+ |

In the current Xcode 26.6 toolchain, AudioAccessoryKit is present in the device SDK but not the iPhone Simulator 26.5 SDK. Use a physical-device destination for this target. If the rest of the app must build for Simulator, isolate target membership or guard the import and implementation with `#if canImport(AudioAccessoryKit)` and provide a simulator stub.

Session Management

Registering an Accessory

After pairing via AccessorySetupKit, register the accessory from the container app by passing an `AccessoryControlDevice.Configuration` that describes the capabilities and any initial state the accessory supports:

let accessory: ASAccessory  // Obtained from AccessorySetupKit pairing

let configuration = AccessoryControlDevice.Configuration(
    devicePlacement: .offHead,
    deviceCapabilities: [.audioSwitching, .placement]
)

try await AccessoryControlDevice.register(accessory, configuration)

Registration activates the specified capabilities and gives the system the configuration it needs to participate in audio routing decisions.

Retrieving the Current Configuration

In the app extension, access the device's current configuration using the static `current(for:)` method:

let device = try AccessoryControlDevice.current(for: accessory)
let currentConfig = device.configuration

This returns the `AccessoryControlDevice` instance associated with the paired `ASAccessory`. The device exposes both the `accessory` reference and the current `configuration`. Apple marks `current(for:)` as app-extension-only.

Updating Configuration

In the app extension, push configuration changes to the system with `update(_:)`. Only update fields for capabilities that were declared during registration:

let device = try AccessoryControlDevice.current(for: accessory)
var config = device.configuration

config.devicePlacement = .onHead
try await device.update(config)

Treat this as a gated write workflow: confirm registration declared the capability, copy and mutate `device.configuration`, then `try await update(_:)`. The method returns no configuration value; update an app-side mirror only after the call succeeds. On failure, use the disposition in [Error Handling](#error-handling). Apple marks `update(_:)` as app-extension-only.

Audio Switching

Automatic audio switching lets the system intelligently route audio output to the correct device based on placement and connected sources.

Enabling Audio Switching

Declare `.audioSwitching` during the canonical registration flow above. Include `.placement` and an initial placement only when the accessory can report ongoing placement changes.

Capabilities

Automatic switching commonly uses these `AccessoryControlDevice.Capabilities`:

| Capability | Purpose | |---|---| | `.audioSwitching` | Device supports automatic audio switching | | `.placement` | Device can report its physical placement |

Combine capabilities as needed. Do not declare `.placement` unless the accessory can keep the system updated with real placement state.

Device Placement

Report the physical position of the accessory from the app extension to help the system make routing decisions. Update placement whenever the accessory detects a position change.

Placement Values

`AccessoryControlDevice.Placement` defines four cases:

| Placement | Meaning | |---|---| | `.inEar` | Accessory is seated in the ear (e.g., earbuds) | | `.onHead` | Accessory is on the head (e.g., headband headphones) | | `.overTheEar` | Accessory is over the ear (e.g., over-ear headphones) | | `.offHead` | Accessory is not being worn |

Updating Placement

config.devicePlacement = .inEar

Apply this mutation within the canonical current→copy→update sequence above.

Common transitions:

• `.offHead` to `.onHead` or `.inEar` when the user puts on the accessory
• `.onHead` or `.inEar` to `.offHead` when removed
• Update promptly o