Voice Instructions

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.

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();