From bb73a94e2c91d5759075901f0363490b4021ed7f Mon Sep 17 00:00:00 2001 From: Edison Jwa Date: Sun, 7 Jun 2026 21:39:28 +0900 Subject: [PATCH] docs(audio): document parseBridgeAudioRoute case-sensitivity contract Adds a doc comment to parseBridgeAudioRoute clarifying that both iOS and Android producers (IOSAudioLifecycleController.classifyDevice and AndroidAudioLifecycleController.classifyDevice) emit exact PascalCase strings. Case variants (USB_HEADSET, usb_headset, UsbHeadphone) fall through to unknown by design. This is a silent failure mode worth documenting so future changes to either platform classifier are paired with a parser update. Per PR #28 review feedback. --- .../lib/services/audio_lifecycle_service.dart | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/apps/chanora_flutter/lib/services/audio_lifecycle_service.dart b/apps/chanora_flutter/lib/services/audio_lifecycle_service.dart index f141d73..99cf4a2 100644 --- a/apps/chanora_flutter/lib/services/audio_lifecycle_service.dart +++ b/apps/chanora_flutter/lib/services/audio_lifecycle_service.dart @@ -7,6 +7,20 @@ import '../src/rust/api.dart' as rust; const iosAudioLifecycleChannelName = 'chanora/ios_audio_lifecycle'; const androidAudioLifecycleChannelName = 'chanora/android_audio_lifecycle'; +/// Parses a platform-channel route string into a [rust.BridgeAudioRoute]. +/// +/// The producer contract is: +/// - iOS: `IOSAudioLifecycleController.classifyDevice` emits one of +/// `Earpiece`, `Speaker`, `WiredHeadset`, `BluetoothHfp`, `BluetoothA2dp`, +/// `Unknown`. +/// - Android: `AndroidAudioLifecycleController.classifyDevice` emits one of +/// `Earpiece`, `Speaker`, `WiredHeadset`, `UsbHeadset`, `BluetoothHfp`, +/// `BluetoothA2dp`, `Hdmi`, `Unknown`. +/// +/// Both producers emit exact PascalCase strings. Case variants (`USB_HEADSET`, +/// `usb_headset`, `UsbHeadphone`) are NOT handled and will fall through to +/// `unknown`. If either platform classifier changes its string contract, +/// update both producers and this parser together. rust.BridgeAudioRoute parseBridgeAudioRoute(String value) { switch (value) { case 'Earpiece':