Voice instructions are available in 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, HERE SDK sets the navigation voice language to US English, which is pre-packaged with HERE SDK.
Note: Voice instructions are only available in Navigation Mode for driving. Users of the pedestrian Navigation Mode receive audio beeps and vibration alerts at the change of each maneuver. Please note that HERE SDK temporarily lowers the volume of other audio when a beep or voice instruction occurs.
NMAVoicePackage class
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 NMAVoiceCatalog singleton instance. Multiple voice package can be loaded to the device but only one can be selected for navigation voice playback. An NMAVoicePackage can be added to NMANavigationManager through voicePackage property. Each NMAVoicePackage is represented by a unique ID in packageId property.
HERE SDK supports two types of voice packages: text-to-speech and pre-recorded. Pre-recorded voice skins provide basic maneuver instructions, such as "turn right in 300 metres", while text-to-speech voices also support spoken street names, such as "turn right in 300 metres onto Granville Street".
NMAVoiceCatalog class and NMAVoiceCatalogDelegate protocol
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
installedVoicePackages property, you can fetch a list of
NMAVoicePackage that are stored on the device. By default
HERE SDK includes a number of pre-installed voice packages. You can also use
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.
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 an NMAVoicePackage with the navigation manager:
- Get
NMAVoiceCatalog by retrieving the shared object instance. NMAVoiceCatalog* voiceCatalog = [NMAVoiceCatalog sharedVoiceCatalog];
- Implement and add an
NMAVoiceCatalogDelegate to NMAVoiceCatalog using delegate property. - Next, get the catalog of voice packages by calling
updateVoiceCatalog. When this operation is complete, a callback to voiceCatalog:didUpdateWithError: delegate method occurs. [voiceCatalog updateVoiceCatalog];
- 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 is complete, a callback to voiceCatalog:didInstallPackage:withError delegate method occurs. [voiceCatalog installVoicePackage:selectedPackage]
- Once the package is installed, set it to
NMANavigationManager. [NMANavigationManager sharedNavigationManager].voicePackage = selectedPackage;
- Get a calculated
NMARoute from NMACoreRouter. For more details on how to do this, please refer to the code samples in Routing section. - 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 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 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.
