Maui Speech To Text

Speech-to-Text — Gotchas & Best Practices

For full service implementation, types, and UI integration patterns, see references/speech-to-text-api.md.

Critical: Permission Handling

Always request permissions before starting speech recognition. Both microphone and speech permissions are required.

// ❌ Starting recognition without checking permissions
var result = await _speechService.StartListeningAsync();

// ✅ Always check permissions first
if (!await _speechService.RequestPermissionsAsync())
    return; // Gracefully handle denial
var result = await _speechService.StartListeningAsync(cancellationToken);

⚠️ iOS Requires Both Permission Descriptions

Missing either NSSpeechRecognitionUsageDescription or NSMicrophoneUsageDescription in Info.plist will cause a runtime crash — not a graceful failure.

⚠️ Android: Permission Re-prompt

On Android, if the user denies the RECORD_AUDIO permission twice, the OS stops showing the prompt. You must guide users to Settings manually.

Common Mistakes

❌ No Timeout — Indefinite Listening

Always set a timeout to prevent indefinite listening sessions that drain battery:

// ❌ No timeout — listens forever if no speech detected
await _speechToText.StartListenAsync(options, CancellationToken.None);

// ✅ Use a combined timeout + user cancellation token
using var timeoutCts = new CancellationTokenSource(TimeSpan.FromSeconds(60));
using var combinedCts = CancellationTokenSource.CreateLinkedTokenSource(
    userCancellationToken, timeoutCts.Token);
await _speechToText.StartListenAsync(options, combinedCts.Token);

❌ Not Unsubscribing Event Handlers

Leaking event subscriptions causes duplicate processing and memory leaks:

// ❌ Subscribe without unsubscribe
_speechToText.RecognitionResultUpdated += OnRecognitionResultUpdated;

// ✅ Always unsubscribe in finally block
try
{
    _speechToText.RecognitionResultUpdated += OnRecognitionResultUpdated;
    // ... listen ...
}
finally
{
    _speechToText.RecognitionResultUpdated -= OnRecognitionResultUpdated;
}

❌ Not Disposing CancellationTokenSource

// ❌ Leaked CTS
_currentCts = new CancellationTokenSource();

// ✅ Dispose in finally
try { /* ... */ }
finally
{
    _currentCts?.Dispose();
    _currentCts = null;
}

Platform Pitfalls

Architecture Tips

1. Wrap `ISpeechToText` in a service — Don't use SpeechToText.Default directly in ViewModels. Wrap in ISpeechRecognitionService for testability and state management.

2. Use partial results for UX — Subscribe to PartialResultReceived for live transcription feedback. Users expect to see words appear as they speak.

3. Continuous listening = loop with delay — Loop StartListeningAsync with small delays (Task.Delay(100)) for conversation mode.

4. Guard against double-start — Check state before starting:

   if (State == SpeechRecognitionState.Listening)
       return new SpeechRecognitionResultDto { Success = false, ErrorMessage = "Already listening" };

5. Natural language output — CommunityToolkit.Maui returns normalized, punctuated text — not raw phonemes. No post-processing needed for basic use cases.

6. UI-agnostic service — The ISpeechRecognitionService pattern works identically with XAML/MVVM, C# Markup, and MauiReactor. See references/speech-to-text-api.md for all three patterns.

Checklist

• [ ] CommunityToolkit.Maui NuGet installed (look up current version)
• [ ] UseMauiCommunityToolkit() called in MauiProgram.cs
• [ ] ISpeechToText registered as singleton via DI
• [ ] iOS: Both NSSpeechRecognitionUsageDescription and NSMicrophoneUsageDescription in Info.plist
• [ ] Android: RECORD_AUDIO permission in AndroidManifest.xml
• [ ] Permissions checked before every StartListeningAsync call
• [ ] Timeout configured (recommend 60 seconds max)
• [ ] Event handlers unsubscribed in finally blocks
• [ ] CancellationTokenSource disposed after use

Speech-to-Text API Reference

Package Installation

Look up the current version of CommunityToolkit.Maui on NuGet before adding:

<PackageReference Include="CommunityToolkit.Maui" Version="[CURRENT_VERSION]" />

MauiProgram.cs Configuration

using CommunityToolkit.Maui;
using CommunityToolkit.Maui.Media;

builder.UseMauiCommunityToolkit();

// Register services
builder.Services.AddSingleton<ISpeechToText>(SpeechToText.Default);
builder.Services.AddSingleton<ISpeechRecognitionService, SpeechRecognitionService>();

Platform Permissions

iOS (Info.plist):

<key>NSSpeechRecognitionUsageDescription</key>
<string>App uses speech recognition for hands-free input.</string>
<key>NSMicrophoneUsageDescription</key>
<string>App needs microphone access to hear your voice.</string>

Android (AndroidManifest.xml):

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

---

Service Interface

public interface ISpeechRecognitionService
{
    SpeechRecognitionState State { get; }
    event EventHandler<SpeechRecognitionState>? StateChanged;
    event EventHandler<string>? PartialResultReceived;
    Task<bool> IsAvailableAsync();
    Task<bool> RequestPermissionsAsync();
    Task<SpeechRecognitionResultDto> StartListeningAsync(CancellationToken cancellationToken = default);
    Task StopListeningAsync();
}

Supporting Types

public enum SpeechRecognitionState
{
    Idle = 0,
    Listening = 1,
    Processing = 2,
    Error = 3
}

public record SpeechRecognitionResultDto
{
    public bool Success { get; init; }
    public string? Transcript { get; init; }
    public double Confidence { get; init; }
    public string? ErrorMessage { get; init; }
}

---

Full Service Implementation

using CommunityToolkit.Maui.Media;
using Microsoft.Extensions.Logging;
using System.Globalization;

public class SpeechRecognitionService : ISpeechRecognitionService
{
    private readonly ISpeechToText _speechToText;
    private readonly ILogger<SpeechRecognitionService> _logger;
    private SpeechRecognitionState _state = SpeechRecognitionState.Idle;
    private CancellationTokenSource? _currentCts;
    private TaskCompletionSource<SpeechRecognitionResultDto>? _recognitionTcs;

    public SpeechRecognitionState State
    {
        get => _state;
        private set
        {
            if (_state != value)
            {
                _state = value;
                StateChanged?.Invoke(this, value);
            }
        }
    }

    public event EventHandler<SpeechRecognitionState>? StateChanged;
    public event EventHandler<string>? PartialResultReceived;

    public SpeechRecognitionService(ISpeechToText speechToText, ILogger<SpeechRecognitionService> logger)
    {
        _speechToText = speechToText;
        _logger = logger;
        _speechToText.RecognitionResultCompleted += OnRecognitionResultCompleted;
    }

    public Task<bool> IsAvailableAsync() => Task.FromResult(true);

    public async Task<bool> RequestPermissionsAsync()
    {
        try
        {
            var micStatus = await Permissions.CheckStatusAsync<Permissions.Microphone>();
            var speechStatus = await Permissions.CheckStatusAsync<Permissions.Speech>();

            if (micStatus != PermissionStatus.Granted)
                micStatus = await Permissions.RequestAsync<Permissions.Microphone>();
            
            if (speechStatus != PermissionStatus.Granted)
                speechStatus = await Permissions.RequestAsync<Permissions.Speech>();

            return micStatus == PermissionStatus.Granted && speechStatus == PermissionStatus.Granted;
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error requesting speech recognition permissions");
            return false;
        }
    }

    public async Task<SpeechRecognitionResultDto> StartListeningAsync(CancellationToken cancellationToken = default)
    {
        if (State == SpeechRecognitionState.Listening)
        {
            return new SpeechRecognitionResultDto { Success = false, ErrorMessage = "Already listening" };
        }

        _currentCts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
        _recognitionTcs = new TaskCompletionSource<SpeechRecognitionResultDto>();
        State = SpeechRecognitionState.Listening;

        using var timeoutCts = new CancellationTokenSource(TimeSpan.FromSeconds(60));
        using var combinedCts = CancellationTokenSource.CreateLinkedTokenSource(_currentCts.Token, timeoutCts.Token);

        try
        {
            _speechToText.RecognitionResultUpdated += OnRecognitionResultUpdated;

            var options = new SpeechToTextOptions
            {
                Culture = CultureInfo.CurrentCulture,
                ShouldReportPartialResults = true
            };

            await _speechToText.StartListenAsync(options, combinedCts.Token);

            var timeoutTask = Task.Delay(TimeSpan.FromSeconds(60), combinedCts.Token);
            var completedTask = await Task.WhenAny(_recognitionTcs.Task, timeoutTask);

            if (completedTask == timeoutTask)
            {
                await StopListeningAsync();
                return new SpeechRecognitionResultDto { Success = false, ErrorMessage = "Listening timed out." };
            }

            return await _recognitionTcs.Task;
        }
        catch (OperationCanceledException)
        {
            State = SpeechRecognitionState.Idle;
            return new SpeechRecognitionResultDto { Success = false, ErrorMessage = "Cancelled" };
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error during speech recognition");
            State = SpeechRecognitionState.Error;
            return new SpeechRecognitionResultDto { Success = false, ErrorMessage = ex.Message };
        }
        finally
        {
            _speechToText.RecognitionResultUpdated -= OnRecognitionResultUpdated;
            _currentCts?.Dispose();
            _currentCts = null;
        }
    }

    public async Task StopListeningAsync()
    {
        try { await _speechToText.StopListenAsync(CancellationToken.None); }
        catch (Exception ex) { _logger.LogWarning(ex, "Error stopping speech recognition"); }
        State = SpeechRecognitionState.Idle;
    }

    private void OnRecognitionResultUpdated(object? sender, SpeechToTextRecognitionResultUpdatedEventArgs args)
    {
        PartialResultReceived?.Invoke(this, args.RecognitionResult);
    }

    private void OnRecognitionResultCompleted(object? sender, SpeechToTextRecognitionResultCompletedEventArgs args)
    {
        State = SpeechRecognitionState.Processing;
        var result = args.RecognitionResult;

        if (result.IsSuccessful && !string.IsNullOrEmpty(result.Text))
        {
            State = SpeechRecognitionState.Idle;
            _recognitionTcs?.TrySetResult(new SpeechRecognitionResultDto
            {
                Success = true,
                Transcript = result.Text,
                Confidence = 1.0
            });
        }
        else
        {
            State = SpeechRecognitionState.Error;
            _recognitionTcs?.TrySetResult(new SpeechRecognitionResultDto
            {
                Success = false,
                ErrorMessage = result.Exception?.Message ?? "No speech recognized"
            });
        }
    }
}

---

UI Integration Patterns

The service works with any .NET MAUI UI approach. Below are patterns for each.

MVVM with XAML

ViewModel:

public partial class MyViewModel : ObservableObject
{
    private readonly ISpeechRecognitionService _speechService;
    private CancellationTokenSource? _voiceCts;

    [ObservableProperty] private bool _isRecording;
    [ObservableProperty] private string _voiceTranscript = "";
    [ObservableProperty] private SpeechRecognitionState _voiceState;

    public MyViewModel(ISpeechRecognitionService speechService)
    {
        _speechService = speechService;
    }

    [RelayCommand]
    private async Task ToggleRecordingAsync()
    {
        if (IsRecording)
            await StopRecordingAsync();
        else
            await StartRecordingAsync();
    }

    private async Task StartRecordingAsync()
    {
        if (!await _speechService.RequestPermissionsAsync())
            return;

        _voiceCts = new CancellationTokenSource();
        IsRecording = true;
        VoiceTranscript = "";
        VoiceState = SpeechRecognitionState.Listening;
        
        _speechService.PartialResultReceived += OnPartialResult;
        _ = ListenLoopAsync();
    }

    private async Task ListenLoopAsync()
    {
        try
        {
            while (IsRecording && !(_voiceCts?.IsCancellationRequested ?? true))
            {
                var result = await _speechService.StartListeningAsync(_voiceCts?.Token ?? default);
                if (result.Success && !string.IsNullOrWhiteSpace(result.Transcript))
                    await ProcessTranscriptAsync(result.Transcript);
                if (IsRecording) await Task.Delay(100);
            }
        }
        catch (OperationCanceledException) { }
        finally
        {
            _speechService.PartialResultReceived -= OnPartialResult;
            IsRecording = false;
            VoiceState = SpeechRecognitionState.Idle;
        }
    }

    private async Task StopRecordingAsync()
    {
        _voiceCts?.Cancel();
        await _speechService.StopListeningAsync();
        _speechService.PartialResultReceived -= OnPartialResult;
        IsRecording = false;
        VoiceState = SpeechRecognitionState.Idle;
    }

    private void OnPartialResult(object? sender, string text) => VoiceTranscript = text;
    private Task ProcessTranscriptAsync(string transcript) => Task.CompletedTask; // Your logic
}

XAML:

<Button Text="{Binding IsRecording, Converter={StaticResource BoolToRecordText}}"
        Command="{Binding ToggleRecordingCommand}" />
<Label Text="{Binding VoiceTranscript}" />

MVVM with C# Markup

public class MyPage : ContentPage
{
    public MyPage(MyViewModel vm)
    {
        BindingContext = vm;
        Content = new VerticalStackLayout
        {
            new Button()
                .Text("Record")
                .BindCommand(nameof(vm.ToggleRecordingCommand)),
            new Label()
                .Bind(Label.TextProperty, nameof(vm.VoiceTranscript))
        };
    }
}

MauiReactor

partial class MyPage : Component<MyPageState>
{
    [Inject] ISpeechRecognitionService _speechService;
    private CancellationTokenSource? _voiceCts;

    public override VisualNode Render() => ContentPage(
        VStack(
            Button(State.IsRecording ? "Stop" : "Record")
                .OnClicked(ToggleRecordingAsync),
            Label(State.VoiceTranscript)
        )
    );

    private async void ToggleRecordingAsync()
    {
        if (State.IsRecording) await StopRecordingAsync();
        else await StartRecordingAsync();
    }

    private async Task StartRecordingAsync()
    {
        if (!await _speechService.RequestPermissionsAsync()) return;
        _voiceCts = new CancellationTokenSource();
        SetState(s => { s.IsRecording = true; s.VoiceTranscript = ""; });
        _speechService.PartialResultReceived += OnPartialResult;
        _ = ListenLoopAsync();
    }

    private async Task ListenLoopAsync()
    {
        try
        {
            while (State.IsRecording && !(_voiceCts?.IsCancellationRequested ?? true))
            {
                var result = await _speechService.StartListeningAsync(_voiceCts?.Token ?? default);
                if (result.Success && !string.IsNullOrWhiteSpace(result.Transcript))
                    await ProcessTranscriptAsync(result.Transcript);
                if (State.IsRecording) await Task.Delay(100);
            }
        }
        catch (OperationCanceledException) { }
        finally
        {
            _speechService.PartialResultReceived -= OnPartialResult;
            SetState(s => s.IsRecording = false);
        }
    }

    private async Task StopRecordingAsync()
    {
        _voiceCts?.Cancel();
        await _speechService.StopListeningAsync();
        _speechService.PartialResultReceived -= OnPartialResult;
        SetState(s => s.IsRecording = false);
    }

    private void OnPartialResult(object? sender, string text) => SetState(s => s.VoiceTranscript = text);
    private Task ProcessTranscriptAsync(string transcript) => Task.CompletedTask;
}

class MyPageState { public bool IsRecording; public string VoiceTranscript = ""; }