SDK for Android Developer's Guide

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.

Note: Voice instructions are only supported in Navigation Mode for driving. Users of pedestrian Navigation Mode receive audio beep and vibration alerts at the change of each maneuver.

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.

Note: A set of sample voice skins is packaged with SDK for Android in {SDK for Android}.zip/misc directory. To deploy these voice skins into your test device, extract 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:

  1. Get a NavigationManager by calling NavigationManager.getInstance()
    
    // Declare the navigationManager member variable
    private NavigationManager navigationManager = null;
    ...
    ...
    // Get the NavigationManager
    navigationManager = NavigationManager.getInstance();
    
  2. Get a calculated Route from CoreRouter. Refer to the code samples in Routing section.
  3. Declare NewInstructionEventListener and PositionListener 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();
      }
    };
    
  4. 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));
  5. 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
        }
      }
    });
  6. 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 using isLanguageAvailable(Locale) method in android.speech.tts.TextToSpeech.
  7. 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
            }
          }
        });
    }
    
  8. 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));
    
  9. If the user decides to abort navigation, call stop().
    // abort navigation
    navigationManager.stop();