SDK for iOS Developer's Guide

Audio Management

This section outlines how you can control and manage audio from HERE SDK. With the information from this section you can

Control when audio clips are played
Pass your application audio to NMAAudioManager by using its audio queue
Disable automatic NMAAudioManager playback
Receive audio playback events

The section also contains information about audio routing, e.g. how to use HERE SDK audio with a Bluetooth device.

NMAAudioManager and the Audio Queue

NMAAudioManager is the central class that is used by SDK for iOS to modify the application AVAudioSession and play audio. It is the interface that the NMANavigationManager uses to play audio feedback such as voice instructions. You can also use NMAAudioManager to change whether hardware keys directly control HERE SDK volume, and also use it to set volume as a factor relative to the user's device volume.

The NMAAudioManager contains a queue of audio output objects. You can add to this queue by calling playOutput: with NMAAudioFileOutput, NMATTSAudioOutput, or your own NMAAudioOutput implementation. You can also use NMAAudioManager methods such as clearQueue, skipCurrentOutput, and stopOutputAndClearQueue to manage audio output in this queue.

Audio Output Types

By default HERE SDK provides two NMAAudioOutput subtypes: NMAAudioFileOutput and NMATTSAudioOutput. You can play or enqueue these (or your own custom NMAAudioOutput subtype) by calling playOutput: method with NMAAudioManager.

NMAAudioFileOutput represents a collection of audio files that are compatible with the iOS AVAudioPlayer. You can get an instance by calling NMAAudioFileOutput audioOutputWithFiles: with an array of compatible files. All files in an NMAAudioFileOutput instance are together considered as a single output segment when it is played by the NMAAudioManager.

NMATTSAudioOutput represents a text-to-speech audio output segment. It contains a text string to be spoken and an AVSpeechSynthesisVoice. You can get an instance of this class by calling NMATTSAudioOutput audioOutputWithText: with the text to be converted to a speech sample. By default the text-to-speech (speech synthesis) engine selects the voice dialect based on the current device locale.

Delaying Audio Playback

You can use audioRouteLatencyCompensation property in NMAAudioManager to introduce some silence before audio playback. This is useful if you need to compensate for Bluetooth connection or audio ducking, and to prevent clipping guidance audio.

Disabling Automatic Playback

In case you would like more control over the application AVAudioSession, you can use managesAudioSession property to manage automatic playback.

When managesAudioSession property is YES, the NMAAudioManager automatically configures, activates, and deactivates the AVAudioSession as needed to play HERE SDK or application audio. If managesAudioSession is NO, the application AVAudioSession is not touched, and it is up to the application to configure the audio session for both its own and HERE SDK audio.

When managesAudioSession property is set to NO, NMAAudioManager continues to attempt to play audio output. However, the AVAudioSession is not modified. Instead, you should configure AVAudioSession to meet your own audio playback requirements. If you want to reconfigure AVAudioSession for NMAAudioManager events, implement NMAAudioManagerDelegate protocol methods.

Overriding Default Audio Playback Using NMAAudioManagerDelegate

Whether or not the NMAAudioManager is set to automatically manage your application HERE SDK audio session, you can choose to implement NMAAudioManagerDelegate to listen for relevant audio output events and perform custom logic before using the audio output for playback.

NMAAudioManagerDelegate contains the following methods:

audioManager:shouldPlayOutput: - This method is called when the audio manager has output to play. If you implement this method, you must return NO to prevent audio playback, or return YES and then call playOutput: method. You can use this to customize audio playback to some degree. For example, you can choose to configure AVAudioSession before playback, if you opted to manage the AVAudioSession yourself.
audioManagerWillPlayOutput: - Callback that occurs just before the output is played by NMAAudioManager.
audioManagerDidPlayOutput: - Callback that occurs after the output is played by NMAAudioManager.

Audio Routing

With iOS 8 or above devices you can route NMAAudioManager audio playback to the device speaker or Bluetooth peripherals, such as a headset or a car stereo, by using setAudioRoute: method before playOutput: is called.

setAudioRoute: accepts the following NMAAudioRoute values. The default audio route is NMAAudioRouteDefault.

NMAAudioRouteDefault - Uses the default audio route as determined by the operating system. This audio route may represent connected wired headphones, connected A2DP Bluetooth devices, or the device speaker.
NMAAudioRouteDeviceSpeaker - Plays audio over the device speaker even if headphones or other peripherals are connected.
NMAAudioRouteBluetoothHFP - Plays audio using Bluetooth the Hands-Free Profile (HFP).

If you set the audio route to NMAAudioRouteBluetoothHFP, HERE SDK attempts to play audio over the connected Bluetooth HFP device. If no device is connected, NMAAudioManager automatically sets the audio route back to NMAAudioRouteDefault. You can receive a notification for this fallback event by observing NMAAudioRouteDidChangeNotification using NSNotificationCenter.

You can retrieve the current audio route from NMAAudioManager by using audioRoute property.