HERE Android SDK Developer's Guide

Nlp

The class Nlp is a member of com.here.android.mpa.nlp .

Class Summary

public final class Nlp

extends java.lang.Object

This is the Natural Language Processor interface.

[For complete information, see the section Class Details]

Nested Class Summary

Table 1. Nested Classes in Nlp
Nested Classes

public static abstract interface Nlp.ListenerBase

Base event listener interface

public static abstract interface Nlp.OnBatteryLevelListener

The remaining battery level event listener interface

public static abstract interface Nlp.OnClearListener

Listener interface for clearing objects from the map.

public static abstract interface Nlp.OnCurrentAddressListener

Address at the current geo location is ready event listener interface.

public static abstract interface Nlp.OnCurrentTimeListener

The current time event listener interface

public static abstract interface Nlp.OnInitializationListener

Represents a listener to provide notification of the Nlp status upon completion of initialization.

public static abstract interface Nlp.OnIntentListener

Intention is ready event listener interface.

public static abstract interface Nlp.OnMapSchemeChangedListener

Map.Scheme of the Map object has been changed event listener interface.

public static abstract interface Nlp.OnNavigationListener

Navigation listener interface

public static abstract interface Nlp.OnParameterListener

Parameter event listener interface

public static abstract interface Nlp.OnPlaceFocusChangedListener

Listener for a client focus change to another place

public static abstract interface Nlp.OnRemoveFromRouteListener

Listener interface to notify user that a stopover is removed from the route

public static abstract interface Nlp.OnResetListener

Listener interface to notify that user wants to do the reset.

public static abstract interface Nlp.OnRouteListener

Route object is available event interface.

public static abstract interface Nlp.OnSearchListener

Search listener interface.

public static abstract interface Nlp.OnSendLocationListener

The send location event listener interface

public static abstract interface Nlp.OnSpeechListener

Listener interface for speech started/ended events.

public static abstract interface Nlp.OnSpeedListener

The speed value event listener interface

public static abstract interface Nlp.OnSpeedWarningSwitchListener

The speed warning mode during navigation event listener interface

public static abstract interface Nlp.OnTrafficModeListener

The traffic mode changed event listener interface

public static abstract interface Nlp.OnTravelDistanceListener

The travel distance to specified location event listener interface

public static abstract interface Nlp.OnTravelTimeListener

The travel time to specified location event listener interface

public static final enumeration Nlp.Reply

Client's responses on the events triggered by NLP

Method Summary

Table 2. Methods in Nlp
Methods

public void addListener (ListenerBase listener)

Adds an event listener to Nlp Nlp.OnBatteryLevelListener Nlp.OnCurrentAddressListener Nlp.OnCurrentTimeListener Nlp.OnIntentListener Nlp.OnMapSchemeChangedListener Nlp.OnNavigationListener Nlp.OnPlaceFocusChangedListener Nlp.OnRouteListener Nlp.OnSearchListener Nlp.OnSendLocationListener Nlp.OnSpeedListener Nlp.OnSpeedWarningSwitchListener Nlp.OnTrafficModeListener Nlp.OnTravelDistanceListener Nlp.OnTravelTimeListener Nlp.OnSpeechListener Nlp.OnClearListener Nlp.OnRemoveFromRouteListener Nlp.OnParameterListener Nlp.OnResetListener

public static Nlp getInstance ()

Returns the Nlp singleton: creates it or returns the already created one.

public java.util.List <Place> getRoutePlaces (Route route)

Get the Places of the Route.

public int getSpeechVolume ()

Get the current speech volume percentage.

public void init (Context context, MapFragment mapFragment, CollectionProvider collectionProvider, OnInitializationListener listener)

Asynchronously initialize Nlp .

public void init (Context context, Map map, MapGesture mapGesture, CollectionProvider collectionProvider, OnInitializationListener listener)

Asynchronously initialize Nlp .

public static boolean isInitialized ()

Gets the initialization state of Nlp .

public boolean isLocationTrackingEnabled ()

Check if automatic location tracking is enabled.

public boolean isMetricSystemEnabled ()

Check if metric measurement system is enabled.

public boolean isOnlineDeductionEnabled ()

Check if online deduction is enabled

public boolean isRepeatAfterMeEnabled ()

Check if repeat-after-me is enabled

public boolean isTalkBackEnabled ()

Check if talk-back is enabled

public void pause ()

Pause NLP

public void removeListener (ListenerBase listener)

Removes an event listener from Nlp Nlp.OnBatteryLevelListener Nlp.OnCurrentAddressListener Nlp.OnCurrentTimeListener Nlp.OnIntentListener Nlp.OnMapSchemeChangedListener Nlp.OnNavigationListener Nlp.OnPlaceFocusChangedListener Nlp.OnRouteListener Nlp.OnSearchListener Nlp.OnSendLocationListener Nlp.OnSpeedListener Nlp.OnSpeedWarningSwitchListener Nlp.OnTrafficModeListener Nlp.OnTravelDistanceListener Nlp.OnTravelTimeListener Nlp.OnSpeechListener Nlp.OnClearListener Nlp.OnRemoveFromRouteListener Nlp.OnParameterListener Nlp.OnResetListener

public void reset ()

Resets Nlp cache (search results or route results.

public void resume (Context context)

Resume NLP

public void setEarcons (int earconStartResId, int earconStopResId, int earconErrorResId)

Install earcons.

public void setFocusToPlace (int index)

Client application to notify NLP that "it" would refer to the provided PlaceLink.

public void setFocusToPlace (PlaceLink place)

Client application to notify NLP that "it" would refer to the provided PlaceLink.

public void setFocusToPlace (String name, GeoCoordinate coordinate)

Client application tells NLP to focus on place specified by name and GeoCoordinate.

public void setLocationTrackingEnabled (boolean enabled)

Enable or disable automatic location tracking.

public void setMap (Map map)

Set Map to be associated with this NLP instance if it's changed since initialization.

public void setMapFragment (MapFragment mapFragment)

Set MapFragment to be associated with this NLP instance if it's changed since initialization.

public void setMapGesture (MapGesture mapGesture)

Sets the MapGesture to be associated with this NLP instance if it is instantiated through (Context, Map)

public void setMetricSystemEnabled (boolean enable)

Controls whether NLP should use metric measurement system or imperial.

public void setOnlineDeductionEnabled (boolean enable)

Controls whether NLP deduction happens on the back-end server or on the client side.

public void setPreferredRoute (Route route)

Client application tells NLP to use a preferred Route for navigation purposes.

public void setRepeatAfterMeEnabled (boolean enable)

Set repeat-after-me to true lets user to hear the results of voice recognition.

public void setRouteResult (Route route, List waypointNames)

Set the externally-generated Route result with an optional list of names and aliases of the waypoints in the route.

public void setSearchResults (CategoryFilter filter, java.util.ArrayList <PlaceLink> results)

Set the search results in NLP

public void setSearchResults (GeoCoordinate location, Address address)

Set the search results in NLP

public void setSearchResults (String searchSubject, java.util.ArrayList <PlaceLink> results)

Set the search results in NLP

public void setSpeechVolume (int percentage)

Set speech volume percentage.

public void setTalkBackEnabled (boolean enable)

Enable/disable talk-back on a spoken user request

public void speak (String text)

Speaks the text

public void startListening ()

Start listening for the voice input.

public void stopListening ()

Stop listening for the voice input.

public boolean understand (String utterance)

"Understand" the text and produce formalized Intention through onIntent(Intention).

Class Details

This is the Natural Language Processor interface. This controls voice operations for the SDK. Note: The application is responsible for downloading voice skins prior to using Navigation features otherwise no voice will be heard during navigation.

IMPORTANT: Natural language processor is a Beta feature. The related classes are subject to change without notice.

Method Details

public static Nlp getInstance ()

Returns the Nlp singleton: creates it or returns the already created one.

Once the Nlp instance is available, it must be initialized through one of the following methods before it can be used:

Returns:

Nlp instance

public java.util.List <Place> getRoutePlaces (Route route)

Get the Places of the Route.

Parameters:

Returns:

List of Places included into the route in the correct order. Will return null if Nlp has not yet been initialized.

public int getSpeechVolume ()

Get the current speech volume percentage.

Note this value may be subjected to rounding and may not reflect the original percentage set by setSpeechVolume(int)

Returns:

int representing the volume percentage ranging from 0 to 100. If speech volume has not yet been set using setSpeechVolume(int), current android.media.AudioManager#STREAM_MUSIC volume of the device will be returned. If Nlp has not yet been initialized, default volume percentage of 10 will be returned.

See also:

setSpeechVolume(int)

public void init (Context context, MapFragment mapFragment, CollectionProvider collectionProvider, OnInitializationListener listener)

Asynchronously initialize Nlp . Nlp cannot be used until it has been initialized successfully. Note: multiple calls to this API will only result on a callback saying initialization was successful. New parameters would be ignored.

Parameters:

  • context

    context to be used during initialization. Must not be null.

  • mapFragment

    MapFragment to be associated with this NLP instance. Must not be null.

  • collectionProvider

    CollectionProvider for collection handling. null if application does not support collections.

  • listener

    Nlp.OnInitializationListener to provide information when Nlp initialization completes. If null, completion callback will not be received.

public void init (Context context, Map map, MapGesture mapGesture, CollectionProvider collectionProvider, OnInitializationListener listener)

Asynchronously initialize Nlp . Nlp cannot be used until it has been initialized successfully. Note: multiple calls to this API will only result on a callback saying initialization was successful. New parameters would be ignored.

Parameters:

  • context

    context to be used during initialization. Must not be null.

  • map

    Map to be associated with this NLP instance. Must not be null.

  • mapGesture

    MapGesture Gesture handler for the Map, if available.

  • collectionProvider

    CollectionProvider for collection handling. Null if application does not support collections.

  • listener

    Nlp.OnInitializationListener to provide information when Nlp initialization completes. If null, completion callback will not be received.

public static boolean isInitialized ()

Gets the initialization state of Nlp .

Returns:

true if Nlp is initialized and ready for service.

public boolean isLocationTrackingEnabled ()

Check if automatic location tracking is enabled.

Returns:

true if enabled or if Nlp has not yet been initialized; false otherwise.

public boolean isMetricSystemEnabled ()

Check if metric measurement system is enabled.

Returns:

true if enabled or if Nlp has not yet been initialized; false otherwise.

public boolean isOnlineDeductionEnabled ()

Check if online deduction is enabled

Returns:

true if enabled or if Nlp has not yet been initialized; false otherwise.

public boolean isRepeatAfterMeEnabled ()

Check if repeat-after-me is enabled

Returns:

true if enabled, false otherwise or Nlp has not yet been initialized. Default value is false.

public boolean isTalkBackEnabled ()

Check if talk-back is enabled

Returns:

true if enabled, false if disabled or Nlp has not yet been initialized. Default value is false.

public void pause ()

Pause NLP

public void reset ()

Resets Nlp cache (search results or route results. It will also stop any ongoing navigation.

public void resume (Context context)

Resume NLP

Parameters:

  • context

    context to be used. This context may be different from the context passed during initialization.

public void setEarcons (int earconStartResId, int earconStopResId, int earconErrorResId)

Install earcons. Earcons are distinctive sounds that will be used to indicate the following speech recognition events: start, stop and error.

Parameters:

  • earconStartResId

    Resource Id of start audio file

  • earconStopResId

    Resource Id of stop audio file

  • earconErrorResId

    Resource Id of error audio file

public void setFocusToPlace (int index)

Client application to notify NLP that "it" would refer to the provided PlaceLink. User may browse among searched places using user interface and then say "Take me there". In order to accommodate this functionality NLP needs to know the place your should refer as "it" or "there".

Parameters:

  • index

    Index of the place in the last search results that should be referred as "it" or "there". Example: "Take me there"

Client application to notify NLP that "it" would refer to the provided PlaceLink. User may browse among searched places using user interface and then say "Take me there". In order to accommodate this functionality NLP needs to know the place your should refer as "it" or "there".

Parameters:

  • place

    Place that should be referred as "it" or "there". Example: "Take me there"

public void setFocusToPlace (String name, GeoCoordinate coordinate)

Client application tells NLP to focus on place specified by name and GeoCoordinate. User may refer to that place as "it" or "there".

Parameters:

public void setLocationTrackingEnabled (boolean enabled)

Enable or disable automatic location tracking.

Parameters:

  • enabled

    If true, the map will be automatically centered on the user's location. Default is true.

public void setMap (Map map)

Set Map to be associated with this NLP instance if it's changed since initialization. setMapGesture(MapGesture) should also be called after Map is changed.

Parameters:

  • map

    Map to be associated with this NLP instance.

See also:

init(Context, Map, MapGesture, CollectionProvider, OnInitializationListener)

setMapGesture(MapGesture)

public void setMapFragment (MapFragment mapFragment)

Set MapFragment to be associated with this NLP instance if it's changed since initialization.

Parameters:

  • mapFragment

    MapFragment to be associated with this NLP instance.

See also:

init(Context, MapFragment, CollectionProvider, OnInitializationListener)

public void setMapGesture (MapGesture mapGesture)

Sets the MapGesture to be associated with this NLP instance if it is instantiated through (Context, Map)

Parameters:

  • mapGesture

    Gesture handler for the Map.

public void setMetricSystemEnabled (boolean enable)

Controls whether NLP should use metric measurement system or imperial.

This may be set by user, please refer to the following for more information: onParameterChanged(Error, Intention.Field, Intention.Value)

Parameters:

  • enable

    When true, metric system will be used; when false, imperial system will be used. Default is true.

public void setOnlineDeductionEnabled (boolean enable)

Controls whether NLP deduction happens on the back-end server or on the client side. This may be set by user, please refer to the following for more information: onParameterChanged(Error, Intention.Field, Intention.Value)

Parameters:

  • enable

    When true, NLP deduction happens on the back-end server. When false, NLP deduction happens on the device. Default is true.

public void setPreferredRoute (Route route)

Client application tells NLP to use a preferred Route for navigation purposes. Only one Route can be chosen at a time. By default, the preferred route is the route returned in onComplete(Error, Route, List, String, List)

Parameters:

public void setRepeatAfterMeEnabled (boolean enable)

Set repeat-after-me to true lets user to hear the results of voice recognition. When talk-back is enabled, user will hear the voice statement back, before processing the request. See #setTalkBackEnabled.

Parameters:

  • enable

    If true, user will hear back the result of the voice recognition. If false, user spoken request will be processed immediately.

public void setRouteResult (Route route, List waypointNames)

Set the externally-generated Route result with an optional list of names and aliases of the waypoints in the route. If the waypoint name array does not match the waypoints in the route, the route place names are resolved internally by NLP, if possible.

After setting the Route, setPreferredRoute(Route) needs to be called to set it as the preferred route in NLP.

The waypoint name aliases allow the application to specify the alias in a voice query (e.g. instead of saying "remove stopover", voice query can be "remove Starbucks", if "Starbucks" is the alias)

Parameters:

  • route

    Route generated externally by the application

  • waypointNames

    A list of the names and aliases of the waypoints in the route, including the start

public void setSearchResults (CategoryFilter filter, java.util.ArrayList <PlaceLink> results)

Set the search results in NLP

Parameters:

  • filter

    Search category. See CategoryFilter

  • results

    List of discovered places generated externally by the application

public void setSearchResults (GeoCoordinate location, Address address)

Set the search results in NLP

Parameters:

  • location

    Search center GeoCoordinate

  • address

    Address of discovered place Address provided by the application

public void setSearchResults (String searchSubject, java.util.ArrayList <PlaceLink> results)

Set the search results in NLP

Parameters:

  • searchSubject

    Search subject name. Example: "hotels"

  • results

    List of discovered places generated externally by the application

public void setSpeechVolume (int percentage)

Set speech volume percentage.

Parameters:

  • percentage

    Volume percentage [0..100]. If less than 0, a default minimum volume percentage will be used instead. If greater than 100, it's clipped to 100.

public void setTalkBackEnabled (boolean enable)

Enable/disable talk-back on a spoken user request

Parameters:

  • enable

    If true, user will hear back all the responses on the spoken request. If false, the responses will be shown as toast messages.

public void speak (String text)

Speaks the text

Parameters:

  • text

    Text to speak

public void startListening ()

Start listening for the voice input.

public void stopListening ()

Stop listening for the voice input.

public boolean understand (String utterance)

"Understand" the text and produce formalized Intention through onIntent(Intention).

Typically, this is done automatically after startListening() is called; thereafter, user can speak and his/her speech is processed by automatic speech recognizer (ASR) and the output from ASR is fed into this function. Moreover, if application has a different source for the text, this API can be used to pass ASR. When deduction is complete, application will receive onIntent(Intention) callback and application can chose to handle the Intention by replying CONSUMED or instruct SDK to handle the Intention by replying PROCEED.

Parameters:

  • utterance

    input for deduction

Returns:

true if it can proceed with deduction; false otherwise or if Nlp has not yet been initialized.