AI Audio Routing

TSAIContext.audioRouting provides read-only route discovery, active-route snapshots, and change observation. Business configurations request a route through audioRouteConfiguration; AIKit resolves it and owns its lifecycle.

Route configuration

TSAIAudioRouteConfiguration *route =
    [TSAIAudioRouteConfiguration configurationWithInputChannel:TSAIAudioInputChannelBuiltInMic
                                                   outputChannel:TSAIAudioOutputChannelBuiltInSpeaker
                                          routeUnavailablePolicy:TSAIAudioRouteUnavailablePolicyFail];

TSAIInterpreterConfig *config = [TSAIInterpreterConfig defaultConfig];
config.audioRouteConfiguration = route;

defaultConfiguration creates Automatic / Automatic / UseAutomaticRoute, matching the compatibility behavior when no route is set. A route is a complete input/output pair; AIKit does not replace only one side of an unavailable explicit pair.

TSAIAudioInputChannel	Description
TSAIAudioInputChannelUnknown	Unknown and invalid for starting
TSAIAudioInputChannelAutomatic	Resolved by AIKit
TSAIAudioInputChannelBuiltInMic	Phone built-in microphone PCM
TSAIAudioInputChannelSCO	Bluetooth HFP/SCO microphone
TSAIAudioInputChannelOpus	PCM decoded from device Opus data

TSAIAudioOutputChannel	Description
TSAIAudioOutputChannelUnknown	Unknown and invalid for starting
TSAIAudioOutputChannelNone	Do not synthesize or play audio
TSAIAudioOutputChannelAutomatic	Resolved by AIKit
TSAIAudioOutputChannelBuiltInSpeaker	Phone built-in speaker
TSAIAudioOutputChannelSCO	Bluetooth HFP/SCO output
TSAIAudioOutputChannelA2DP	Bluetooth A2DP output
TSAIAudioOutputChannelOpus	PCM sent through the device data channel

TSAIAudioRouteUnavailablePolicyFail fails unless the original pair is fully available. TSAIAudioRouteUnavailablePolicyUseAutomaticRoute lets AIKit resolve another complete route.

Query complete routes

id<TSAIAudioRoutingInterface> routing = context.audioRouting;
NSArray<TSAIAudioRouteCapability *> *routes =
    [routing audioRouteCapabilitiesForFeature:TSAIFeatureInterpretation];

for (TSAIAudioRouteCapability *route in routes) {
    TSLog(@"input=%ld output=%ld available=%@",
          (long)route.inputChannel,
          (long)route.outputChannel,
          route.isAvailable ? @"YES" : @"NO");
}

- (NSArray<TSAIAudioRouteCapability *> *)audioRouteCapabilitiesForFeature:
    (TSAIFeatureOptions)feature;

Pass exactly one feature. The stable ordered results expose inputChannel, outputChannel, supportedFeatures, isAvailable, supportsFullDuplex, echoCancellationMode, and optional unavailableReason.

TSAIAudioEchoCancellationMode defines TSAIAudioEchoCancellationModeUnknown, TSAIAudioEchoCancellationModeNone, TSAIAudioEchoCancellationModeSystem, and TSAIAudioEchoCancellationModeDevice.

Query an active route

TSAIAudioRouteSnapshot *snapshot =
    [routing activeAudioRouteForFeature:TSAIFeatureInterpretation];

- (nullable TSAIAudioRouteSnapshot *)activeAudioRouteForFeature:
    (TSAIFeatureOptions)feature;

The result is nil while idle. A snapshot exposes feature, requestedRoute, effectiveRoute, and state, so UI can distinguish the requested and selected routes.

TSAIAudioRouteState	Description
TSAIAudioRouteStateUnknown	Unknown
TSAIAudioRouteStateResolving	Resolving
TSAIAudioRouteStateActivating	Activating
TSAIAudioRouteStateActive	Active
TSAIAudioRouteStateStopping	Stopping
TSAIAudioRouteStateInterrupted	Interrupted
TSAIAudioRouteStateFailed	Activation or runtime failure

Observe changes

[routing registerAudioRouteCapabilitiesDidChange:^(TSAIFeatureOptions features) {
    TSLog(@"Route capabilities changed: %lu", (unsigned long)features);
}];

[routing registerActiveAudioRouteDidChange:^(TSAIAudioRouteSnapshot *snapshot) {
    TSLog(@"Effective output: %ld", (long)snapshot.effectiveRoute.outputChannel);
}];

- (void)registerAudioRouteCapabilitiesDidChange:
    (nullable TSAIAudioRouteCapabilitiesDidChangeBlock)block;
- (void)registerActiveAudioRouteDidChange:
    (nullable TSAIAudioRouteDidChangeBlock)block;

Both callbacks run on the main thread. Pass nil to unregister.

Model constructors

Provider or platform-bridge implementations can create a TSAIAudioRouteCapability with capabilityWithInputChannel:outputChannel:supportedFeatures:isAvailable:supportsFullDuplex:echoCancellationMode:unavailableReason: and a TSAIAudioRouteSnapshot with snapshotWithFeature:requestedRoute:effectiveRoute:state:. Apps normally consume Context-owned instances.

Errors

• TSAIErrorCodeAudioRouteUnavailable: no complete route satisfies the request or fallback policy.
• TSAIErrorCodeAudioRouteMismatch: the use case, device scene, or reserved route does not match the request.

Important notes

1. audioRouting can be nil; make sure the Context is active and the provider supports discovery.
2. Capabilities are point-in-time snapshots. Query again after Bluetooth, audio-session, or device changes.
3. Business APIs copy and freeze route configurations when starting; do not rely on later mutations.
4. Unregister both observers before screen teardown or Context switching.