Plugin.Maui.Audio

On iOS and macOS, the AVAudioSession is a shared resource. You can control how the session behaves when a player is disposed using the SessionLifetime property in AudioPlayerOptions:

Best Practice for short sounds (notifications, TTS): Use EndSessionAndNotifyOthers and dispose the player when playback finishes to avoid interrupting other apps.

var player = audioManager.CreatePlayer(
    await FileSystem.OpenAppPackageFileAsync("notification.mp3"),
    new AudioPlayerOptions
    {
#if IOS || MACCATALYST
        SessionLifetime = SessionLifetime.EndSessionAndNotifyOthers
#endif
    });

void OnPlaybackEnded(object? sender, EventArgs e)
{
    player.PlaybackEnded -= OnPlaybackEnded;
    player.Dispose();
}

player.PlaybackEnded += OnPlaybackEnded;
player.Play();

The library uses a hierarchical pipeline to process audio data for analysis and manipulation. The flow is as follows:

AudioStreamer (provides raw PCM) $\rightarrow$ PcmAudioHandler (converts raw PCM to ordered samples) $\rightarrow$ AudioListeners (listens to and analyzes samples) $\rightarrow$ PcmAudioHelpers (provides utility methods for analysis).

Important Implementation Note

Audio listeners do not receive data from AudioRecorder. To perform analysis, you must:

1. Keep a reference to an AudioStreamer.
2. Subscribe to its OnAudioCaptured event.
3. Call StartAsync() on the streamer to supply PCM data.

Warning: Avoid running AudioRecorder and AudioStreamer simultaneously, especially on Android, as they compete for microphone capture sessions. If you need both recording and analysis, manually save the PCM data provided by the AudioStreamer.

// Create and retain AudioStreamer
audioStreamer = audioManager.CreateStreamer();

// Create PcmAudioHandler
pcmAudioHandler = new PcmAudioHandler(44100, ChannelType.Mono, BitDepth.Pcm16bit);

// Create listener
silenceListener = new SilenceListener
{
   MinimalSilenceTimescanInMilliseconds = 200,
   SilenceThresholdInDb = -40
};
silenceListener.IsSilentChanged += (sender, args) =>
{
   dispatcher.Dispatch(() =>
   {
      IsSilent = args.IsSilent;
   });
};

// Subscribe the SilenceListener to PcmAudioHandler
pcmAudioHandler.Subscribe(silenceListener);

// Connect PcmAudioHandler to AudioStreamer for incoming audio
audioStreamer.OnAudioCaptured += (sender, args) =>
{
   pcmAudioHandler.HandlePcmAudio(args.Audio);
};

// Start supplying PCM data to the listeners
await audioStreamer.StartAsync();

Each platform requires specific configuration to allow microphone access and audio streaming.

Android

Add the following to your AndroidManifest.xml inside the <manifest> tag:

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

iOS

Add the following to your Info.plist inside the <dict> tag:

<key>NSMicrophoneUsageDescription</key>
<string>The [app name] wants to use your microphone to record audio.</string>

Note: To stream in the background, add the UIBackgroundModes key with the audio string.

MacCatalyst

Add the following to your Info.plist inside the <dict> tag:

<key>NSMicrophoneUsageDescription</key>
<string>The [app name] wants to use your microphone to record audio.</string>

If distributing the app, you must also add an entitlement in Entitlements.plist:

<key>com.apple.security.device.audio-input</key>
<true/>

Windows

Add the following to your Package.appxmanifest inside the <Capabilities> tag:

<DeviceCapability Name="microphone"/>

To enable Bluetooth HFP (Hands-Free Profile) recording on iOS or macCatalyst, you must set CategoryOptions to AllowBluetooth in AudioRecorderOptions.

Note: Bluetooth HFP recording is limited to voice-quality audio (8–16 kHz, mono).

To select a specific Bluetooth device, you must first configure and activate a temporary AVAudioSession to discover available inputs, then pass the PreferredInput to the recorder.

#if IOS || MACCATALYST
using AVFoundation;

// 1. Configure session to discover inputs
var audioSession = AVAudioSession.SharedInstance();
audioSession.SetCategory(AVAudioSessionCategory.Record, 
    AVAudioSessionCategoryOptions.AllowBluetooth, out _);
audioSession.SetActive(true, out _);

// 2. Find the Bluetooth HFP input
var btInput = audioSession.AvailableInputs? 
    .FirstOrDefault(i => i.PortType == AVAudioSession.PortBluetoothHfp);

// 3. Create recorder with preferred input
var recorder = audioManager.CreateRecorder(
    new AudioRecorderOptions
    {
        CategoryOptions = AVAudioSessionCategoryOptions.AllowBluetooth,
        PreferredInput = btInput
    });
#endif

The AudioStreamer class allows you to stream raw audio data from a microphone via an event handler. Unlike AudioRecorder, which saves to a file, AudioStreamer provides raw linear PCM audio data (similar to a WAV file without a header) in real-time.

To use it, create an instance via IAudioManager.CreateStreamer() and subscribe to the OnAudioCaptured event to receive AudioStreamEventArgs. The args.Audio property contains the byte array of the captured data.

public class AudioStreamerViewModel
{
    readonly IAudioManager audioManager;
    readonly IAudioStreamer audioStreamer;

    public AudioStreamerViewModel(IAudioManager audioManager)
    {
        this.audioManager = audioManager;
        this.audioStreamer = audioManager.CreateStreamer();
        this.audioStreamer.OnAudioCaptured += OnAudioStreamerCapturedData;
    }

    public async Task StartStreamingAsync()
    {
        await audioStreamer.StartAsync();
    }

    public async Task StopStreamingAsync()
    {
        await audioStreamer.StopAsync();
    }

    private void OnAudioStreamerCapturedData(object sender, AudioStreamEventArgs args)
    {
        // args.Audio is a byte array with linear PCM audio data
    }
}

Recording audio requires specific permissions and configuration in platform-specific manifest files.

Android

Add these to AndroidManifest.xml:

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

Note: For Bluetooth device selection on Android 12+, also add android.permission.BLUETOOTH_CONNECT.

iOS / MacCatalyst

Add these to Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>The [app name] wants to use your microphone to record audio.</string>

To record in the background on iOS, add:

<key>UIBackgroundModes</key>
<array>
  <string>audio</string>
</array>

For MacCatalyst distribution, add the following to Entitlements.plist:

<key>com.apple.security.device.audio-input</key>
<true/>

Windows

Add this to Package.appxmanifest inside the Capabilities tag:

<DeviceCapability Name="microphone"/>