Installation

Add the package, give the app microphone access on Android and iOS, raise the iOS deployment target, and register the package:

1. Add the packages

   flutter pub add carp_core carp_mobile_sensing carp_audio_package

   The package runs on top of CARP Mobile Sensing (CAMS), so complete the CAMS setup in Installation first. The steps below add only what the audio measures need.

2. Configure Android

   Add the microphone permission to android/app/src/main/AndroidManifest.xml, above the <application> element:

   <uses-permission android:name="android.permission.RECORD_AUDIO"/>

   NOISE and AUDIO both need it: CAMS asks the participant for Permission.microphone, which is RECORD_AUDIO on Android. The package does not use the camera, so declare CAMERA only if your app captures images or videos itself.

   The package needs minSdk 24 or later, because flutter_sound and audio_streamer do. If android/app/build.gradle.kts sets a lower value, raise it to 24.

3. Configure iOS

   audio_streamer requires iOS 16.0 or later, which is higher than the CAMS minimum. In Xcode, select Runner → General and set Minimum Deployments to 16.0. If ios/Podfile has a platform line, set it to the same version:

   platform :ios, '16.0'

   Add the microphone usage description and the audio background mode to ios/Runner/Info.plist. If the file already has UIBackgroundModes, add audio to its array:

   <key>NSMicrophoneUsageDescription</key>
   <string>This app uses the microphone to measure noise levels and record sound for a research study.</string>
   <key>UIBackgroundModes</key>
   <array>
       <string>audio</string>
   </array>

   Noise sampling and recordings need the audio background mode to continue when the app moves to the background. Add NSCameraUsageDescription only if your app captures images or videos itself.

   AUDIO checks the microphone permission through permission_handler and records nothing until the check passes. How you enable microphone access in permission_handler depends on how Flutter builds the iOS plugins:

   Swift Package ManagerCocoaPods

   No change is needed: permission_handler_apple enables microphone access when it finds NSMicrophoneUsageDescription in Info.plist.

   flutter_sound is available through CocoaPods only, so CocoaPods must stay installed for the iOS build.

   Enable microphone access in the post_install block of the Podfile. If the block already sets GCC_PREPROCESSOR_DEFINITIONS, add the macro to that list:

   post_install do |installer|
     installer.pods_project.targets.each do |target|
       flutter_additional_ios_build_settings(target)
       target.build_configurations.each do |config|
         config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
           '$(inherited)',
           'PERMISSION_MICROPHONE=1',
         ]
       end
     end
   end

4. Register the sampling package

   Register the package in main(), before you configure the client:

   import 'package:carp_mobile_sensing/carp_mobile_sensing.dart';
   import 'package:carp_audio_package/media.dart';
   
   void main() async {
     CarpMobileSensing.ensureInitialized();
     SamplingPackageRegistry().register(MediaSamplingPackage());
   
     await SmartPhoneClientManager().configure();
     // ... the rest of your app
   }

   Call CarpMobileSensing.ensureInitialized() before register(): registering a sampling package before CAMS is initialized throws a null check error.

   Registering the package makes its four measure types known to CAMS and registers the JSON types of their data. configure() restores the studies saved on the phone and resumes their sampling, which needs the package's measure types.

Troubleshooting

No audio recordings on iOS

Enable microphone access in permission_handler: add NSMicrophoneUsageDescription to Info.plist with Swift Package Manager, or the PERMISSION_MICROPHONE=1 macro to the Podfile with CocoaPods. AUDIO records nothing while permission_handler reports the microphone permission as denied.

The iOS build fails on the deployment target

Set Minimum Deployments to 16.0 in Xcode and platform :ios, '16.0' in the Podfile, then run pod install in the ios/ folder again. audio_streamer 5.0.0 does not build for earlier iOS versions.

Next step