Skip to main content

SpeechMgr (CPIK Libraries)

Contents
Overview
Description A class containing static methods regarding speech, languages, and voices.
Supported in Android Since Version 9.6.0.821
Supported in iOS Since Version 10.9
Type Class
Package com.alk.cpik.speech

Methods

Method Name Return Type Description
playSpeechSample(int delay)
void
It will play the test phrase in whichever language and voice is currently selected.
playTTSMessage(String message, int delay. Boolean currMsgOverride, Boolean muteOverride)
void
Will play the entered string of text using the Text To Speech function of CoPilot, after waiting the given delay period. The operation can stop a message that is currently playing and then play the TTS message.
cancelVoiceMessage()
void
This will stop the currently playing voice message, regardless of it being TTS or not.
getLanguages()
List<Locale>
A list of locale describing CoPilot’s supported languages.
getCurrentLanguage()
Locale
Describing CoPilot’s current language.
getCurrentVoice()
VoiceInfo
CoPilot’s currently set VoiceInfo.
getLanguageInfo(Locale locale)
LanguageInfo
Returns a LanguageInfo for the provided Locale.
setLanguageAndVoice(Locale locale, String voiceName)
void
Sets CoPilot’s current language and voice.
setVolume(double gain)
void
Sets the hardware volume used by CoPilot’s audio stream.
getVolume()
double
Gets the volume of CoPilot’s current audio stream.
setMuteState(Boolean bMute)
void
Sets the mute state of CoPilot’s audio. Does nothing if CoPilot has not yet been started.
isMuted()
boolean
Returns the current mute state of CoPilot’s audio.
setAudioStream(AudioStream audioStream)
void
Sets CoPilot’s audio stream. If this is not called, the default is STREAM_MUSIC. Does nothing if CoPilot has not yet been started.

SpeechMgr.setLanguageAndVoice

Overview
Description Sets CoPilot’s current language and voice. Please note that this API is intended for making changes after CoPilot’s first start has been completed. For selecting the language on initial startup, please use SpeechListener.selectCopilotLanguage instead.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.speech

Syntax

void setLanguageAndVoice(java.util.Locale, java.lang.String)
+(void)setLanguageAndVoice:(NSLocale*)

Parameters

locale - The Locale for which to set CoPilot.

voiceName - The voice name for which to set CoPilot.

Return Value

void

Sample Code

// Set CoPilot's language to English and the voice to John
String strVoicePerson = "John";
SpeechMgr.setLanguageAndVoice(Locale.ENGLISH, "John", strVoicePerson);
System.out.println("Completed.");
NSArray* languages = [SpeechMgr getLanguages];
NSLocale* locale = (NSLocale*) languages[0];
LanguageInfo* info = [SpeechMgr getLanguageInfo:locale];
VoiceInfo* voice = (SpeechVoiceInfo*) [info voices][0];
[SpeechMgr setLanguageAndVoice:locale withVoice:[voice voiceName]];

SpeechMgr.getLanguages

Overview
Description Returns a list of all languages currently supported by CoPilot, including those that are not yet installed.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.speech

Syntax

List<Locale> getLanguages()
+(NSArray) getLanguages

Parameters

None.

Return Value

List; A list of all java Locales supported by CoPilot

Sample Code

// Get a list of all languages supported by CoPilot
List<Locale> supportedLanguages = SpeechMgr.getLanguages();
System.out.println("Supporting languages are as follow");
for (Locale locale : supportedLanguages) {
  System.out.println(locale.getDefault().toString());
}
NSArray * ret = [SpeechMgr getLanguages];

SpeechMgr.getCurrentLanguage

Overview
Description Returns the currently set language of CoPilot.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version Android, Linux
Type Method
Package com.alk.cpik.speech

Syntax

Locale getCurrentLanguage()
+(NSLocale*) getCurrentLanguage

Return Value

Locale - a Java locale object

Sample Code

// Get CoPilot's current language
Locale currentLanguage = SpeechMgr.getCurrentLanguage();
System.out.println(currentLanguage.getDefault().toString());
NSLocale * locale = [SpeechMgr getCurrentLanguage];

Related APIs

SpeechMgr.setLanguageAndVoice()

SpeechMgr.getLanguages()

SpeechMgr.getCurrentVoice()

SpeechMgr.getLanguageInfo()


SpeechMgr.getCurrentVoice

Overview
Description Returns CoPilot’s currently set voice as a VoiceInfo object.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version Android, Linux
Type Method
Package com.alk.cpik.speech

Syntax

VoiceInfo getCurrentVoice()
+(SpeechVoiceInfo*) getCurrentVoice

Return Value

VoiceInfo; contains various info about a CoPilot-supported voice

Sample Code

// Get CoPilot's current voice
VoiceInfo currentVoice = SpeechMgr.getCurrentVoice();
System.out.println("Voice Name " + currentVoice.getVoiceName());
System.out.println("Voice storage: " + currentVoice.getVoiceStorage());
System.out.println("Voice : " + (currentVoice.getIsTTSVoice() ? "TTS": " not TTS"));
//to print all information in one shot
System.out.println("Voice info: " + currentVoice.toString());
[SpeechMgr getCurrentVoice];

Related APIs

SpeechMgr.setLanguageAndVoice() SpeechMgr.getLanguages() SpeechMgr.getCurrentLanguage() SpeechMgr.getLanguageInfo()


SpeechMgr.getLanguageInfo

Overview
Description Returns information about the CoPilot language for a particular Locale.
Supported Since Version 9.6.0.821
Platforms Supported Android, Linux
Type Method
Package com.alk.cpik.speech

Syntax

LanguageInfo getLanguageInfo(java.util.Locale)
+(SpeechLanguageInfo*) getLanguageInfo:(NSLocale*)

Parameters

locale– a locale object of the language query.

Return Value

LanguageInfo; contains info about a CoPilot language

Sample Code

// Get information about the CoPilot language for the US English Locale
Locale enUsLocale = new Locale("en_US");
LanguageInfo enUsLanguageInfo = SpeechMgr.getLanguageInfo(enUsLocale);
LanguageInfo * info = [SpeechMgr getLanguageInfo:[SpeechMgr getCurrentLanguage]];

Related APIs

SpeechMgr.setLanguageAndVoice() SpeechMgr.getLanguages() SpeechMgr.getCurrentLanguage() SpeechMgr.getCurrentVoice()


LanguageInfo

Overview
Description An object containing information about a CoPilot language.
Supported on Android Since Version 9.6.0.821
Type Object
Package com.alk.cpik.speech

Methods

Method Name Return Type Description
getLocale()
Locale
Returns the Locale of this language.
getVoices() List<VoiceInfo> Returns a list of VoiceInfo CoPilot supports for this language.
getLanguageDisplayName()
String
Returns a string representation of this language’s display name.

VoiceInfo

Overview
Description An object containing information about a CoPilot voice.
Supported on Android Since Version 9.6.0.821
Type Object
Package com.alk.cpik.speech

Methods

Method Name Return Type Description
getVoiceName()
String
Returns a string representation of the voice’s name.
getIsTTSVoice()
boolean
Returns whether or not this voice supports text to speech functionality.
getVoiceStorage()
VoiceStorage
Returns the voice’s installation status.

VoiceStorage

Overview
Description An enum that describes the voice’s current installation state.
Supported on Android Since Version 9.6.0.821
Type Enum
Package com.alk.cpik.speech

Values

Value Description
DOWNLOADING The voice is currently downloading.
NEED_DOWNLOADING Not installed, must be downloaded.
ON_DEVICE The voice is on the device.

SpeechMgr.playSpeechSample

Overview
Description Performs the action of pressing the “Test” button from the voice selection screen. It will play the test phrase in whichever language and voice is currently selected. The phrase will be played after the given time delay.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.speech

Syntax

void playSpeechSample(int delay)
+(void) playSpeechSample:(int)

Parameters

delay - The delay in milliseconds to wait before playing the sample

Sample Code

int milliSecDelay = 1000;
// Play a speech sample after 1 second
SpeechMgr.playSpeechSample(milliSecDelay);
System.out.println("Speech will play after " + milliSecDelay);
[SpeechMgr playSpeechSample:1];

SpeechMgr.playTTSMessage

Overview
Description Will play the entered string of text using the Text To Speech (TTS) function of CoPilot, after waiting for the given delay period. The operation can stop a message that is currently playing and then play the TTS message. Furthermore, the message can override the mute function and play regardless of the mute state of CoPilot. If CoPilot is muted and the mute override function is used, callbacks will not be received for this or any message.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.speech

Syntax

void playTTSMessage(java.lang.String, int, boolean, boolean)
+(void) playTTSMessage:(NSString*) (int) (bool) (bool)

Parameters

message - The message to be played via the TTS player.

delay - The amount of time, in milliseconds, to wait before playing the message.

currMsgOverride - If true, the current message will stop, and this message will play.

muteOverride - If true, this message will play regardless of whether or not CoPilot is in a muted state.

Sample Code

// Play a test TTS message after 1 second
// Overriding the current message
// But not overriding the mute state
String messageStr = "Hello. Test message";
int milliSecDelay = 1000;
boolean currMsgOverride = true;
boolean muteOverride = false;
SpeechMgr.playTTSMessage(messageStr, milliSecDelay, currMsgOverride, muteOverride);
[SpeechMgr playTTSMessage:@"Welcome To Copilot" withDelay:0 currMessageOverride:true muteOverride:true];

SpeechMgr.cancelVoiceMessage

Overview
Description This will stop the currently playing voice message, regardless of it being Text to Speech or not. It will also cancel all messages that are not yet queued for playback.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.speech

Syntax

void cancelVoiceMessage()
+(void) cancelVoiceMessage

Sample Code

// Cancel the currently playing voice message
SpeechMgr.cancelVoiceMessage();
System.out.println("Voice Message is canceled.");
[SpeechMgr cancelVoiceMessage];

SpeechMgr.setVolume

Overview
Description Sets the hardware volume that CoPilot will use for audio instructions. If CoPilot has not been started, this will not have any effect on the volume settings.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.speech

Syntax

void setVolume(double gain)
+(void)setVolume:(double)

Parameters

gain - The percentage of the maximum volume to be set to. (0 to 1).

Sample Code

double gain = .50;
// Set CoPilot's volume to 50%
SpeechMgr.setVolume(gain);
System.out.println("Volume is increased by " + gain * 100 + "%");
[SpeechMgr setVolume:.5];

SpeechMgr.getVolume

Overview
Description Gets the volume of CoPilot’s current audio stream (default is music).
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.speech

Syntax

getVolume()
+(double) getVolume

Return Value

Returns the current volume, given as a percentage of the CoPilot Media Stream’s maximum volume (0 to 1).

If CoPilot has not been started, returns -1.

Sample Code

// Print CoPilot's current volume level
double volumeLevel = SpeechMgr.getVolume();
System.out.println("Current volume level: " +
String.valueOf(volumeLevel));
NSLog([NSString stringWithFormat:@"Current Volume: %f", [SpeechMgr getVolume]]);

Related APIs

SpeechMgr.setVolume() SpeechMgr.isMuted() SpeechMgr.setMuteState()


SpeechMgr.isMuted

Overview
Description Gets whether or not CoPilot is audible.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version Android, Linux
Type Method
Package com.alk.cpik.speech

Syntax

boolean isMuted()
+(bool) isMuted

Return Value

Boolean representing whether or not CoPilot is muted.

Sample Code

// Print whether or not CoPilot is muted
boolean isCopilotMuted = SpeechMgr.isMuted();
if (isCopilotMuted)
  System.out.println("CoPilot is muted");
else
  System.out.println("CoPilot is NOT muted");
NSLog([NSString stringWithFormat:@"Is Muted: %@", ([SpeechMgr isMuted]) ? @"Muted" : @"Not Muted"]);

Related APIs

SpeechMgr.setVolume() SpeechMgr.getVolume() SpeechMgr.setMuteState()


SpeechMgr.setMuteState

Overview
Description Sets the mute state of CoPilot’s audio. Does nothing if CoPilot has not yet been started.
Supported Since Version 9.6.0.821
Platforms Supported Android, Linux
Type Method
Package com.alk.cpik.speech

Syntax

void setMuteState(boolean)
+(void) setMuteState:(bool)

Parameters

bMute - Whether or not to mute CoPilot.

Sample Code

// Mute CoPilot
SpeechMgr.setMuteState(true);
// Un-Mute CoPilot
SpeechMgr.setMuteState(false);
[SpeechMgr setMuteState:true];

Related APIs

SpeechMgr.setVolume() SpeechMgr.getVolume() SpeechMgr.isMuted()


SpeechMgr.setAudioStream

Overview
Description Sets CoPilot’s audio stream. If this is not called, the default is STREAM_MUSIC.
Supported on Android Since Version 9.6.0.821
Type Method
Package com.alk.cpik.speech

Syntax

void setAudioStream(AudioStream)

Parameters

audioStream – Enum value for the new stream.

Sample Code

// Set CoPilot to music playback stream
SpeechMgr.setAudioStream(STREAM\_MUSIC);
System.out.println("AudioStream is set to STREAM_MUSIC");

SpeechMgr.setSpeechRate

Overview
Description Set CoPilot’s default speech rate for iOS’ TTS engine. To reset the rate back to CoPilot’s default pass in 0.0.
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.speech

Syntax

Void setSpeechRate:(double)

Parameters

Double - The speech rate multiplier desired

Sample Code

// Set iOS TTS engines speech rate
[SpeechMgr setSpeechRate:.5];

SpeechMgr.downloadVoice

Note: VoiceInfo can be used to validate the voice name as well as whether or not it is already available on the device.

Overview
Description This API will trigger the download of a voice for CoPilot to use. The callback onVoiceDownloadStatusUpdate will provide information relating to the status of the download if required.
Supported on Android Since Version 9.6.0.1704
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.speech

Tip: If using iOS this API is only available if map data has been downloaded over the air. If pre-installed data is present voices cannot be downloaded and should be pre-installed.

Syntax

VoiceDownloadResult downloadVoice(VoiceInfo voiceInfo)
+(enum VoiceDownloadResult)downloadVoice:(VoiceInfo*)voiceInfo

Parameters

VoiceInfo – The voice to download.

Return Value

VoiceDownloadResult – The result of the voice download request.

Sample Code

// Download any available voice that hasn't yet been downloaded
// Generate a list of all voices that need to be downloaded
List<Locale> supportedLanguages = SpeechMgr.getLanguages();
ArrayList<LanguageInfo> languageInfoList = new
ArrayList<LanguageInfo>();
for (Locale loc : supportedLanguages)
  languageInfoList.add(SpeechMgr.getLanguageInfo(loc));
ArrayList<VoiceInfo> voicesNeedingDownload = new ArrayList<VoiceInfo>();
for (LanguageInfo langInfo : languageInfoList){
  for (VoiceInfo voiceInfo : langInfo.getVoices())  {
    // If the voice storage is NEED_DOWNLOADING, we want to add it to the list
    if (voiceInfo.getVoiceStorage() == VoiceInfo.VoiceStorage.NEED_DOWNLOADING)
      voicesNeedingDownload.add(voiceInfo);
  }
}
// For each voice that needs downloading
for (VoiceInfo vi : voicesNeedingDownload){
  // Download the voice
  SpeechMgr.VoiceDownloadResult dlResult = SpeechMgr.downloadVoice(voiceNeedingDownload);
}
NSArray* languages = [SpeechMgr getLanguages];
for (id langElement in languages)
{
  LanguageInfo* info = [SpeechMgr getLanguageInfo:langElement ];
  for (id voiceElement in info.voices)
  {
    VoiceInfo* voice = voiceElement;
    if (!voice.isTTSVoice)
    {
    if (voice.voiceStorage == NOT_DOWNLOADED)
      {
        VoiceDownloadResult result = [SpeechMgr downloadVoice:voice]; // Should return VOICE_DOWNLOAD_QUEUED_SUCCESSFULLY
      }
    }
  }
}

Related APIs

SpeechMgr.VoiceDownloadStatus SpeechMgr.VoiceDownloadResult


VoiceDownloadStatus

Overview
Description Once a voice has been requested to be downloaded the status of the download can be checked via this API. A number of values will be returned and will inform the user on the status of the download.

This API should be used in combination with SpeechMgr.downloadVoice and SpeechMgr.VoiceDownloadStatus.

Supported on Android Since Version 9.6.0.1704
Type Enum
Package com.alk.cpik.speech

Values

Value Description
VOICE_DOWNLOAD_STATUS_SUCCESS The voice download successfully.
VOICE_DOWNLOAD_STATUS_CANCELED The voice download was canceled.
VOICE_DOWNLOAD_STATUS_FAILED The voice download failed.

VoiceDownloadResult

Overview
Description Once a request has been made to download a voice, a result will be provided via this API. Once the attempt has been made the user will be informed as to the result of the request.

This API should be used in combination with SpeechMgr.downloadVoice and SpeechMgr.VoiceDownloadStatus.

Supported Since Version 9.6.0.1704
Platforms Supported Android, Linux
Type Enum
Package com.alk.cpik.speech

Values

Value Description
VOICE_DOWNLOAD_QUEUED_SUCCESSFULLY The voice download was queued successfully.
VOICE_DOWNLOAD_FAILED_ALREADY_DOWNLOADING The voice download request failed because the voice is already downloading.
VOICE_DOWNLOAD_FAILED_ALREADY_DOWNLOADED The voice download request failed because the voice is already downloaded to the device.
VOICE_DOWNLOAD_FAILED_CELLULAR_DOWNLOADING_DISABLED The voice download request failed because cellular downloading of voices is disabled and there is no Wi-Fi connection.
VOICE_DOWNLOAD_FAILED_GENERIC_ERROR The voice download request failed.

SoundType

Overview
Description An enum of sounds.
Supported on Android Since Version 9.6.0.821
Type Enum
Package com.alk.cpik.speech

Values

Value Description
BUTTON_CLICK Button click sound.
SPEED_LIMIT_WARNING Speed limit warning sound.
AT_TURN_WARNING At turn warning sound.
RESTRICTED Restriction warning sound.
WARNING Warning sound.
CP_WELCOME CoPilot welcome sound.
CP_WELCOME_LIVE CoPilot welcome sound.
CP_WELCOME_PRO CoPilot Professional welcome sound.
CP_WELCOME_LIVE_PRO CoPilot Professional live welcome sound.
CP_WELCOME_TRUCK CoPilot Truck welcome sound.
CP_WELCOME_LIVE_TRUCK CoPilot Truck live welcome sound.
DETOUR Detour sound.
CANCEL_DETOUR Cancel Detour sound.
AVOID_ROAD Avoid road warning sound.
AVOID_CANCEL Avoid canceled warning sound.
NEW_MESSAGE New message received sound.
MESSAGE_SENT Message sent sound.
ARRIVED Arrived sound.
OFF_ROUTE Off route warning sound.
LONDON_CONGESTION London Congestion zone warning sound.
CONGESTION Congestion warning sound.
LOW_EMISSION Low Emission warning sound.
NO_SOUND No sound type.

AudioStream

Overview
Description An Android AudioStream enum. See android.media.AudioManager.
Supported on Android Since Version 9.6.0.821
Type Enum
Package com.alk.cpik.speech

Values

Value Description
STREAM_ALARM The audio stream for alarms.
STREAM_DTMF The audio stream for DTMF Tones.
STREAM_MUSIC The audio stream for music playback.
STREAM_NOTIFICATION The audio stream for notifications.
STREAM_RING The audio stream for the phone ring.
STREAM_SYSTEM The audio stream for system sounds.
STREAM_VOICE_CALL The audio stream for phone calls.

Hooks and Callbacks

Hooks and Callbacks related to Speech can be found below. For further details on these Hooks or Callbacks please refer to the Hooks and Callbacks section of this document.

SpeechListener
onReadToSpeakTurnInstruction
onSpeakTurnInstructionComplete
onReadyToSpeakUtterance
onSpeakUtteranceComplete
onSpeakTurnInstruction
beforeSoundHook
onAfterSoundPlayed
onVoiceDownloadStatusUpdate
Last updated April 25, 2024.