Sound topic

Use this module to manage audio playback, text‑to‑speech (TTS), and sound preferences inside apps that use the Magic Lane Maps SDK for Flutter. The sound APIs provide a high‑level service for playing voice guidance and alert sounds, a listener to observe playback lifecycle and interruptions, and a set of preference and session types for fine‑grained control of audio focus, routing and volumes.

  • SoundPlayingService: The central static service for playing TTS and sound resources. Use it to trigger synthesized speech or play sound assets and to configure global playback routing, volumes and session preferences.
  • SoundPlayingPreferences: Typed model that holds per‑severity playback settings. Use it to store volume, maximum play time, audio stream selection and focus delays for informational vs. warning alerts.
  • SoundSessionRequestPreferences: Model for audio session request behaviour. Use it to define audio category, desired output, focus delay and exclusivity when requesting platform audio focus.
  • SoundPlayingListener: Event listener singleton that reports playback lifecycle and interruption events. Use it to register callbacks for start/stop events, volume key changes, and system audio interruptions.

The sound APIs enable reliable voice guidance and alert playback by centralizing audio control, preferences, and lifecycle events. Together they let apps play TTS and sounds consistently across platforms, respect system interruptions, and tune behavior per alert severity to provide a robust, user-friendly audio experience.

Prefer SoundPlayingService for all app-level playback actions so routing, focus and preference handling remain consistent. Configure SoundPlayingPreferences for different alert severities and persist changes through the service. Register SoundPlayingListener early to respond to start/stop events and to gracefully handle system interruptions; use SoundSessionRequestPreferences when you need precise control over audio focus and exclusive sessions. Keep volume changes and focus requests minimal on foreground UI threads and avoid long-running synchronous audio operations.

Learn more about sound and voice guidance: https://developer.magiclane.com/docs/flutter/guides/navigation/voice-guidance

Classes

SoundPlayingListener Sound
Listener for events related to sound playback and text-to-speech.
SoundPlayingPreferences Sound
Preferences controlling how the SDK plays sounds and TTS.
SoundPlayingService Sound
High-level static API for playing sounds and TTS through the SDK.
SoundSessionRequestPreferences Sound
Preferences used when requesting an audio session from the platform.

Enums

AlertSeverity Sound
Alert severity levels used for sound-related settings.
AudioCategory Sound
Audio category type used when requesting an audio session.
AudioOutput Sound
Audio output type.
AudioStreamType Sound
Audio stream type used for playback.
SoundPlayType Sound
Specifies the type of media the sound engine is currently playing. Provides the currently active media type used by the SDK sound engine. Use SoundPlayingListener.soundPlayType to read the current value.