Voice Instructions
You can use voice instructions with turn-by-turn navigation. Voice instructions are offered in a variety of languages which are available through downloadable text-to-speech (TTS) and pre-recorded voice skins. 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, e.g. "turn right in 300 meters onto Granville Street".
You can check Navigation Voices for a list of the supported voices in HERE SDK.
Voice skins information and voice skins downloads can be managed through the voice catalog. The following section describes how you can use the voice catalog, download voice skins, and use a voice skin with turn-by-turn navigation.
VoiceCatalog Class
VoiceCatalog
class is used to access voice skin files from the local device. A VoiceCatalog
object instance can be retrieved by calling VoiceCatalog.getInstance()
. Then, using getLocalVoiceSkins()
method, you can fetch a list of VoiceSkin
files stored on the device.
Be sure to check if VoiceCatalog.getCatalogList()
is empty. Since the voice catalog is downloaded based on the current device language, changing the device language causes an empty list of downloadable voice skins. When this happens, the user needs to re-download the voice catalog.
voiceskins.tar.gz
file, then call the following ADB command from the parent folder of the voices
folder: adb push voices /sdcard/Android/data/{YourAppNamespace}/files/voices-download
VoicePackage Class
VoicePackage
class represents an entry within the voice catalog. Each voice package shares a common ID value with a downloadable voice skin. You can use this class to display information about the voice skin before launching a download.
A list of VoicePackage
can be accessed by using VoiceCatalog.getCatalogList()
method.
VoiceSkin Class
VoiceSkin
class encapsulates voice-generation scripts. The scripts are used to generate voice instructions for navigation. A voice skin is language-specific and can either support Text-to-Speech or voice audio files. Multiple voice skins can be loaded to the device but only one can be selected for navigation voice playback.
A list of loaded VoiceSkin
instances can be accessed by using the VoiceCatalog
singleton instance. Each VoiceSkin
can be fetched by getLocalVoiceSkins()
method. Voice skins can be passed to NavigationManager
by calling VoiceGuidanceOptions.setVoiceSkin(VoiceSkin)
.
Selecting a Voice Skin and Starting Navigation
The following is an example of how to start navigation using a calculated route and an English text-to-speech voice skin:
- Get a NavigationManager by calling
NavigationManager.getInstance()
// Declare the navigationManager member variable private NavigationManager navigationManager = null; ... ... // Get the NavigationManager navigationManager = NavigationManager.getInstance();
- Get a calculated
Route
fromCoreRouter
. Refer to the code samples in Routing section. - Declare
NewInstructionEventListener
andPositionListener
member variables// declare the listeners // add application specific logic in each of the callbacks. private NavigationManager.NewInstructionEventListener instructListener = new NavigationManager.NewInstructionEventListener() { @Override public void onNewInstructionEvent() { // Interpret and present the Maneuver object as it contains // turn by turn navigation instructions for the user. navigationManager.getNextManeuver(); } }; private NavigationManager.PositionListener positionListener = new NavigationManager.PositionListener() { @Override public void onPositionUpdated(GeoPosition loc) { // the position we get in this callback can be used // to reposition the map and change orientation. loc.getCoordinate(); loc.getHeading(); loc.getSpeed(); // also remaining time and distance can be // fetched from navigation manager navigationManager.getTta(TrafficPenaltyMode.DISABLED, true); navigationManager.getDestinationDistance(); } };
- Add the listeners to
NavigationManager
to listen for the callbacks// start listening for navigation events navigationManager.addNewInstructionEventListener( new WeakReference<NewInstructionEventListener>(instructListener));
// start listening for position events navigationManager.addPositionListener( new WeakReference<PositionListener>(positionListener));
- Retrieve the
VoiceCatalog
and download the latest updates.VoiceCatalog voiceCatalog = VoiceCatalog.getInstance(); voiceCatalog.downloadCatalog(new OnDownloadDoneListener() { @Override public void onDownloadDone(Error errorCode) { if (errorCode == Error.NONE) { // catalog download successful } } });
- Using the voice catalog, find the desired voice package. In this example choose "English TTS" from the voice catalog.
// Get the list of voice packages from the voice catalog list List<VoicePackage> voicePackages = VoiceCatalog.getInstance().getCatalogList(); long id = -1; // select for (VoicePackage vPackage : voicePackages) { if (vPackage.getMarcCode().compareToIgnoreCase("eng") == 0) { if (vPackage.isTts()) { id = vPackage.getId(); break; } } }
Note: Some voice packages in the voice catalog may not be supported by the installed TTS engine. You can check whether the language is supported by usingisLanguageAvailable(Locale)
method inandroid.speech.tts.TextToSpeech
. - If the ID of the voice package does not match an item in the list of installed voice skins, install it. When the installation operation completes, a callback to
onDownloadDone(Error)
method occurs.if (!voiceCatalog.isLocalVoiceSkin(id)) { voiceCatalog.downloadVoice(id, new OnDownloadDoneListener() { @Override public void onDownloadDone(Error errorCode) { if (errorCode == Error.NONE){ //voice skin download successful } } }); }
- Start navigation according to user selection. Navigation can be started in three different modes but only one of them can be started at a time:
// if user wants to start simulation, // submit calculated route and a simulation speed in meters per second error = navigationManager.simulate(route, 60); // obtain VoiceGuidanceOptions object VoiceGuidanceOptions voiceGuidanceOptions = navigationManager.getVoiceGuidanceOptions(); // set the voice skin for use by navigation manager voiceGuidanceOptions.setVoiceSkin(voiceCatalog.getLocalVoiceSkin(id));
- If the user decides to abort navigation, call
stop()
.// abort navigation navigationManager.stop();