HERE iOS SDK Developer's Guide

Audio Management

This section outlines how you can control and manage audio from the HERE SDK. With the information from this section, you can
  • Control when audio clips are played
  • Pass your application's audio to NMAAudioManager by using its audio queue
  • Disable automatic NMAAudioManager playback
  • Receive audio playback events

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

NMAAudioManager and the Audio Queue

NMAAudioManager is the central class that is used by the HERE iOS SDK to modify the application's 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, the HERE SDK provides two NMAAudioOutput subtypes: NMAAudioFileOutput and NMATTSAudioOutput. You can play or enqueue these (or your own custom NMAAudioOutput subtype) by calling the playOutput: method with NMAAudioManager.

The 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.

The 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 the 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 the case where you would like more control over the application's AVAudioSession, you can use the managesAudioSession property to manage automatic playback.

When the 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 the HERE SDK audio.

When the 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's 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 the 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 the 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, the 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 the audioRoute property.

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.