SDK for iOS Developer's Guide

Voice Instructions

Voice instructions are available in the HERE SDK as voice packages. Voice packages are available in two forms: pre-packaged or downloadable through the voice catalog. You can set a voice package to be used for navigational instructions. However, if a package is not set, the HERE SDK sets the navigation voice language to US English, which is pre-packaged with the HERE SDK.

Note: Voice instructions are only available in Navigation Mode for driving. Users of the pedestrian Navigation Mode receive audio beeps and vibrations alerts at the change of each maneuver. Please note that the HERE SDK temporarily lowers the volume of other audio when a beep or voice instruction occurs.

The NMAVoicePackage class

The NMAVoicePackage class encapsulates spoken voices that can be used for navigation guidance. It contains information such as name, gender, and the spoken language. This information can be accessed through its class properties.

A list of loaded NMAVoicePackage instances can be accessed by using the NMAVoiceCatalog singleton instance. Multiple voice package can be loaded to the device, but only one can be selected for navigation voice playback. A NMAVoicePackage can be added to NMANavigationManager through the voicePackage property. Each NMAVoicePackage is represented by a unique ID in the packageId property.

The HERE SDK supports two types of voice packages: text-to-speech or pre-recorded. Pre-recorded voice skins provide basic maneuver instructions, such as "turn right in 300 meters", while text-to-speech voices also support spoken street names, such as "turn right in 300 meters onto Granville Street".

The NMAVoiceCatalog class and the NMAVoiceCatalogDelegate protocol

The NMAVoiceCatalog class is used to access voice package files from the local device. An NMAVoiceCatalog object instance can be retrieved by calling:
NMAVoiceCatalog* voiceCatalog = [NMAVoiceCatalog sharedVoiceCatalog];
Then, using the installedVoicePackages property, you can fetch a list of NMAVoicePackage that are stored on the device. By default, the HERE SDK includes a number of pre-installed voice packages. You can also use the voicePackages property to obtain a list of voice packages that are available for download from the voice packages server. To retrieve the latest list of packages from the server, call updateVoicePackages.

The NMAVoiceCatalogDelegate is used for receiving callbacks that are related to certain asynchronous NMAVoiceCatalog operations. Examples of these operations include updating the catalog and installing a voice package.

Selecting a Voice Package and Starting Navigation

The following is an example of how to use a NMAVoicePackage with the navigation manager:

  1. Get the NMAVoiceCatalog by retrieving the shared object instance.
    NMAVoiceCatalog* voiceCatalog = [NMAVoiceCatalog sharedVoiceCatalog];
  2. Implement and add an NMAVoiceCatalogDelegate to NMAVoiceCatalog using the delegate property.
  3. Next, get the catalog of voice packages by calling updateVoiceCatalog. When this operation completes, a callback to the voiceCatalog:didUpdateWithError: delegate method occurs.
    [voiceCatalog updateVoiceCatalog];
  4. Using the list of voicePackages, find the desired voice package. If the voice package is not already in the list of installed voice packages (installedVoicePackages), install it. When the installation operation completes, a callback to the voiceCatalog:didInstallPackage:withError delegate method occurs.
    [voiceCatalog installVoicePackage:selectedPackage]
  5. Once the package is installed, set it to the NMANavigationManager.
    [NMANavigationManager sharedNavigationManager].voicePackage = selectedPackage;
  6. Get a calculated NMARoute from NMACoreRouter. For more details on how to do this, please refer to the code samples in the Routing section.
  7. Start navigation according to user selection.
    NSError* error = [[NMANavigationManager sharedNavigationManager] startTurnByTurnNavigationWithRoute:calculatedRoute];

Controlling Audio Playback

Your application may require control over the timing of when HERE SDK navigation audio, such as a voice instruction, is played. For example, you may need to interrupt audio feedback to play another audio clip. To do this, use the cancelVoiceFeedback method in NMANavigationManager. When this method is called, the current voice feedback stops and any queued feedback is also cleared.

In other scenarios, you may need to suppress navigation audio for a period of time. To do this, implement the navigationManager:shouldPlayVoiceFeedbackWithText: callback in NMANavigationManagerDelegate and return NO. This event is triggered whenever audio feedback is ready to be played, and returning NO skips this feedback from being played.