fix(expo-audio-studio): Resolve iOS HW Format Mismatch Crash and Enhance Logging (#218)

[deeeed]

Description

This pull request addresses a critical issue on iOS where the app crashes with a "Format mismatch" error (com.apple.coreaudio.avfaudio: input HW format is invalid) during recording preparation, as reported in issue #218. The root cause was identified as a mismatch between the audio tap format and the hardware's actual input format, particularly when switching devices or resuming recording. Additionally, this PR improves logging consistency across platforms and enhances the iOS playground app for better debugging and validation.

Purpose and Impact

• Fix iOS Crash ([BUG] com.apple.coreaudio.avfaudio: Input HW format is invalid #218): Resolves the format mismatch crash by ensuring the audio tap is installed using the hardware's actual input format (inputNode.inputFormat) rather than relying on potentially inconsistent session or node output formats. This fix ensures stable recording across device changes (e.g., Bluetooth headsets) and resume operations.
• Improved Logging: Standardizes logging tags across platforms by adopting the ExpoAudioStudio prefix, making it easier to filter and debug logs on both Android and iOS. Enhanced log messages provide better context for debugging recording, device management, and audio processing.
• Playground Enhancement for iOS: Adds the AudioDevPlayground app for testing and includes detailed logging instructions in the CONTRIBUTE.md file, enabling developers to validate recording behavior on iOS simulators and physical devices.

Key Implementation Details

• Hardware Format Detection (iOS):
  • Introduced a new installTapWithHardwareFormat method in AudioStreamManager.swift to query inputNode.inputFormat(forBus: 0) just before installing the audio tap, ensuring compatibility with the hardware's actual format.
  • Updated recording preparation, resume, and device fallback logic to reinstall the tap with the correct hardware format, preventing format mismatch crashes.
  • Added aggressive recovery mechanisms in the fallback handler to ensure data continuity after device disconnection, including forced emissions and engine restarts.
• Compression Format Handling:
  • Modified ExpoAudioStreamModule.swift to automatically fall back to AAC on iOS when Opus is requested, as Opus is not supported on iOS. This fallback is logged as a warning to inform developers.
  • Updated RecordingSettings.tsx to enforce AAC as the only compression format on iOS, with clear user feedback in the UI.
• Logging Improvements:
  • Standardized logging tags across platforms using the ExpoAudioStudio prefix (e.g., ExpoAudioStudio:AudioDeviceManager).
  • Enhanced iOS logging in Logger.swift to include class names for better context.
  • Updated CONTRIBUTE.md with detailed instructions for filtering logs on both Android and iOS, including commands for viewing logs from the AudioDevPlayground app.
• Documentation Updates:
  • Updated recording-config.md to clarify platform-specific compression support (e.g., Opus not supported on iOS, automatic fallback to AAC).
  • Added detailed root cause analysis and solution steps in ISSUE_IOS.md for future reference.
• Playground Enhancements:
  • Added the AudioDevPlayground app for iOS testing, with instructions in CONTRIBUTE.md for viewing logs on simulators and physical devices.
  • Improved recording preparation logic in record.tsx to track configuration changes and re-prepare when necessary, reducing the likelihood of crashes due to stale configurations.

Breaking Changes

• Compression Format on iOS: Opus compression is no longer supported on iOS and will automatically fall back to AAC. This may affect apps that explicitly rely on Opus for iOS recordings.
  • Migration Step: Update any recording configurations that specify Opus on iOS to use AAC instead. The library will handle the fallback automatically, but developers should ensure their app logic accounts for AAC output on iOS.

[sonarqubecloud]

Quality Gate passed

Issues
8 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[everuribe]

Nice catch on hardware format changes! I have a concern regarding the forced emissions in recovery...

The current fallback tap block implementation has redundant data emission:

• First calls processAudioBuffer which handles normal processing and emission
• Then directly emits the same buffer data again to the delegate

This causes duplicate data being sent to the delegate.

Can't we rely solely on processAudioBuffer to eventually bubble up the acculumutedData for continuity's sake?