com.ibm.watson.developer_cloud.speech_to_text.v1

Class SpeechToText

java.lang.Object

com.ibm.watson.developer_cloud.service.WatsonService

com.ibm.watson.developer_cloud.speech_to_text.v1.SpeechToText

public class SpeechToText
extends WatsonService

The Speech to Text service uses IBM's speech recognition capabilities to convert English speech into text. The transcription of incoming audio is continuously sent back to the client with minimal delay, and it is corrected as more speech is heard.

Version:

v1

See Also:

Speech to Text

Field Summary

Fields inherited from class com.ibm.watson.developer_cloud.service.WatsonService

defaultHeaders, MESSAGE_CODE, MESSAGE_ERROR, skipAuthentication, VERSION

Constructor Summary

Constructors

Constructor and Description
SpeechToText() Instantiates a new Speech to Text service.
SpeechToText(String username, String password) Instantiates a new Speech to Text service by username and password.

Method Summary

Modifier and Type	Method and Description
ServiceCall<Void>	addTextToCustomizationCorpus(String customizationId, String corpusName, Boolean allowOverride, File trainingData) Adds a single corpus text file of new training data to the custom language model.
ServiceCall<Void>	addWord(String customizationId, Word word) Add/Updates a custom word to a custom language model.
ServiceCall<Void>	addWords(String customizationId, Word... words) Adds one or more custom words to a custom language model.
ServiceCall<Customization>	createCustomization(String name, SpeechModel baseModel, String description) Creates the customization.
ServiceCall<RecognitionJob>	createRecognitionJob(File audio, RecognizeOptions recognizeOptions, RecognitionJobOptions recognitionJobOptions) Creates an asynchronous recognition request.
ServiceCall<SpeechSession>	createSession() Creates a session to lock an engine to the session.
ServiceCall<SpeechSession>	createSession(SpeechModel model) Creates a session to lock an engine to the session.
ServiceCall<SpeechSession>	createSession(String model) Creates a session to lock an engine to the session.
ServiceCall<Void>	deleteCorpus(String customizationId, String corpusName) Delete customization corpus.
ServiceCall<Void>	deleteCustomization(String customizationId) Delete customization.
ServiceCall<Void>	deleteRecognitionJob(String id) Delete recognition.
ServiceCall<Void>	deleteSession(SpeechSession session) Deletes a SpeechSession.
ServiceCall<Void>	deleteWord(String customizationId, String wordName) Deletes a custom word from a custom language model.
ServiceCall<List<Corpus>>	getCorpora(String customizationId) Gets the customization corpus list.
ServiceCall<Customization>	getCustomization(String customizationId) Gets the customization information.
ServiceCall<List<Customization>>	getCustomizations(String language) Gets all the customizations belonging to the user.
ServiceCall<SpeechModel>	getModel(String modelName) Gets the speech model based on a given name.
ServiceCall<List<SpeechModel>>	getModels() Gets the models.
ServiceCall<RecognitionJob>	getRecognitionJob(String id) Gets the recognition.
ServiceCall<List<RecognitionJob>>	getRecognitionJobs() Returns the status and id of all outstanding jobs.
ServiceCall<SpeechSessionStatus>	getRecognizeStatus(SpeechSession session) Gets the session status.
ServiceCall<WordData>	getWord(String customizationId, String wordName) Gets information about a word from a custom language model.
ServiceCall<List<WordData>>	getWords(String customizationId, Word.Type type) Gets information about all the words from a custom language model.
ServiceCall<SpeechResults>	recognize(File audio) Recognizes an audio file and returns SpeechResults.
ServiceCall<SpeechResults>	recognize(File audio, RecognizeOptions options) Recognizes an audio file and returns SpeechResults. Here is an example of how to recognize an audio file:
void	recognizeUsingWebSocket(InputStream audio, RecognizeOptions options, RecognizeCallback callback) Recognizes an audio InputStream using a WebSocket. The RecognizeCallback instance will be called every time the service sends SpeechResults. Here is an example of how to recognize an audio file using WebSockets and get interim results:
ServiceCall<RecognitionCallback>	registerCallback(String callbackUrl, String secret) Registers a callback URL with the service for use with subsequent asynchronous recognition requests.
ServiceCall<Void>	resetCustomization(String customizationId) Resets a custom language model by removing all corpora and words from the model.
ServiceCall<Void>	trainCustomization(String customizationId, Customization.WordTypeToAdd wordTypeToAdd) Initiates the training of a custom language model with new corpora, words, or both.

Methods inherited from class com.ibm.watson.developer_cloud.service.WatsonService

configureHttpClient, createServiceCall, getApiKey, getEndPoint, getName, getToken, processServiceCall, setApiKey, setAuthentication, setDefaultHeaders, setEndPoint, setSkipAuthentication, setUsernameAndPassword, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SpeechToText

public SpeechToText()

Instantiates a new Speech to Text service.

SpeechToText

public SpeechToText(String username,
                    String password)

Instantiates a new Speech to Text service by username and password.

Parameters:

username - the username

password - the password

Method Detail

addTextToCustomizationCorpus

public ServiceCall<Void> addTextToCustomizationCorpus(String customizationId,
                                                      String corpusName,
                                                      Boolean allowOverride,
                                                      File trainingData)

Adds a single corpus text file of new training data to the custom language model. Use multiple requests to submit multiple corpus text files. Only the owner of a custom model can use this method to add a corpus to the model. Submit a plain text file that contains sample sentences from the domain of interest to enable the service to extract words in context. The more sentences you add that represent the context in which speakers use words from the domain, the better the service's recognition accuracy. Adding a corpus does not affect the custom model until you train the model for the new data by using the POST /v1/customizations/{customization_id}/train method.

Parameters:

customizationId - The GUID of the custom language model to which a corpus is to be added. You must make the request with the service credentials of the model's owner.

corpusName - The name of the corpus that is to be added. The name cannot contain spaces and cannot be the string user, which is reserved by the service to denote custom words added or modified by the user.

allowOverride - Indicates whether the specified corpus is to overwrite an existing corpus with the same name. If a corpus with the same name already exists, the request fails unless allow_overwrite is set to true; by default, the parameter is false. The parameter has no effect if a corpus with the same name does not already exist. query.

trainingData - A plain text file that contains the training data for the corpus. Encode the file in UTF-8 if it contains non-ASCII characters; the service assumes UTF-8 encoding if it encounters non-ASCII characters.

Returns:

the service call

addWord

public ServiceCall<Void> addWord(String customizationId,
                                 Word word)

Add/Updates a custom word to a custom language model. The service automatically populates the words resource for a custom model with out-of-vocabulary (OOV) words found in each corpus added to the model. You can use this method to add additional words or to modify existing words in the words resource. Adding or modifying a custom word does not affect the custom model until you train the model for the new data by using SpeechToText#trainCustomization(String, Boolean).

Parameters:

customizationId - The GUID of the custom language model to which a word is to be added. You must make the request with the service credentials of the model's owner.

word - the word to add/update

Returns:

the service call

addWords

public ServiceCall<Void> addWords(String customizationId,
                                  Word... words)

Adds one or more custom words to a custom language model. The service automatically populates the words resource for a custom model with out-of-vocabulary (OOV) words found in each corpus added to the model. You can use this method to add additional words or to modify existing words in the words resource. Adding or modifying custom words does not affect the custom model until you train the model for the new data by using SpeechToText#trainCustomization(String, Boolean).

Parameters:

customizationId - The GUID of the custom language model to which words are to be added. You must make the request with the service credentials of the model's owner.

words - the list of words to be added.

Returns:

the service call

createCustomization

public ServiceCall<Customization> createCustomization(String name,
                                                      SpeechModel baseModel,
                                                      String description)

Creates the customization.

Parameters:

name - The customization name

baseModel - The name of the language model that is to be customized by the new model. e.g: 'en-US_BroadbandModel'.

description - the customization description

Returns:

the service call with the GUID which identifies the created custom model.

createRecognitionJob

public ServiceCall<RecognitionJob> createRecognitionJob(File audio,
                                                        RecognizeOptions recognizeOptions,
                                                        RecognitionJobOptions recognitionJobOptions)

Creates an asynchronous recognition request.

Parameters:

audio - the audio

recognizeOptions - the recognize options

recognitionJobOptions - the recognition job options

Returns:

the service call

createSession

public ServiceCall<SpeechSession> createSession()

Creates a session to lock an engine to the session. You can use the session for multiple recognition requests, so that each request is processed with the same speech-to-text engine. Use the cookie that is returned from this operation in the Set-Cookie header for each request that uses this session. The session expires after 15 minutes of inactivity.

Returns:

the SpeechSession

createSession

public ServiceCall<SpeechSession> createSession(SpeechModel model)

Creates a session to lock an engine to the session. You can use the session for multiple recognition requests, so that each request is processed with the same speech-to-text engine. Use the cookie that is returned from this operation in the Set-Cookie header for each request that uses this session. The session expires after 15 minutes of inactivity.

Parameters:

model - the model

Returns:

the SpeechSession

createSession

public ServiceCall<SpeechSession> createSession(String model)

Creates a session to lock an engine to the session. You can use the session for multiple recognition requests, so that each request is processed with the same speech-to-text engine. Use the cookie that is returned from this operation in the Set-Cookie header for each request that uses this session. The session expires after 15 minutes of inactivity.

Parameters:

model - the model

Returns:

the SpeechSession

deleteCorpus

public ServiceCall<Void> deleteCorpus(String customizationId,
                                      String corpusName)

Delete customization corpus.

Parameters:

customizationId - The GUID of the custom language model from which the corpus is to be deleted. You must make the request with the service credentials of the model's owner.

corpusName - the corpus name

Returns:

the service call

deleteCustomization

public ServiceCall<Void> deleteCustomization(String customizationId)

Delete customization.

Parameters:

customizationId - The GUID of the custom language model being deleted. You must make the request with the service credentials of the model's owner.

Returns:

the service call

deleteRecognitionJob

public ServiceCall<Void> deleteRecognitionJob(String id)

Delete recognition.

Parameters:

id - the id

Returns:

the service call

deleteSession

public ServiceCall<Void> deleteSession(SpeechSession session)

Deletes a SpeechSession.

Parameters:

session - the speech session to delete

Returns:

the service call

deleteWord

public ServiceCall<Void> deleteWord(String customizationId,
                                    String wordName)

Deletes a custom word from a custom language model. You can remove any word that you added to the custom model's words resource via any means. However, if the word also exists in the service's base vocabulary, the service removes only the custom pronunciation for the word; the word remains in the base vocabulary.

Parameters:

customizationId - The GUID of the custom language model from which the word is being deleted. You must make the request with the service credentials of the model's owner.

wordName - the word name

Returns:

the service call

getCorpora

public ServiceCall<List<Corpus>> getCorpora(String customizationId)

Gets the customization corpus list.

Parameters:

customizationId - The GUID of the custom language model whose corpora is being queried. You must make the request with the service credentials of the model's owner.

Returns:

the list of customization corpora

getCustomization

public ServiceCall<Customization> getCustomization(String customizationId)

Gets the customization information.

Parameters:

customizationId - The GUID of the custom language model being queried. You must make the request with the service credentials of the model's owner.

Returns:

the customization

getCustomizations

public ServiceCall<List<Customization>> getCustomizations(String language)

Gets all the customizations belonging to the user.

Parameters:

language - The language for which custom models are to be returned.

Returns:

the customizations

getModel

public ServiceCall<SpeechModel> getModel(String modelName)

Gets the speech model based on a given name.

Parameters:

modelName - the model name

Returns:

the SpeechModel

getModels

public ServiceCall<List<SpeechModel>> getModels()

Gets the models.

Returns:

the SpeechModels

getRecognitionJob

public ServiceCall<RecognitionJob> getRecognitionJob(String id)

Gets the recognition.

Parameters:

id - the id

Returns:

the recognition

getRecognitionJobs

public ServiceCall<List<RecognitionJob>> getRecognitionJobs()

Returns the status and id of all outstanding jobs. If a job was created with a callback URL and a user token, the method also returns the user token for the job.

Returns:

the recognitions

getRecognizeStatus

public ServiceCall<SpeechSessionStatus> getRecognizeStatus(SpeechSession session)

Gets the session status. Concurrent recognition tasks during the same session are not allowed. This method offers a way to check whether the session can accept another recognition task. The returned state must be "initialized" to call recognize(File, RecognizeOptions) .

Parameters:

session - the speech session

Returns:

the model

getWord

public ServiceCall<WordData> getWord(String customizationId,
                                     String wordName)

Gets information about a word from a custom language model.

Parameters:

customizationId - The GUID of the custom language model containing the word being queried. You must make the request with the service credentials of the model's owner.

wordName - the word name

Returns:

the words

getWords

public ServiceCall<List<WordData>> getWords(String customizationId,
                                            Word.Type type)

Gets information about all the words from a custom language model.

Parameters:

customizationId - The GUID of the custom language model to which a corpus is to be added. You must make the request with the service credentials of the model's owner.

type - the word type. Possible values are: ALL, USER or CORPORA.

Returns:

the words

recognize

public ServiceCall<SpeechResults> recognize(File audio)

Recognizes an audio file and returns SpeechResults. It will try to recognize the audio format based on the file extension.
Here is an example of how to recognize an audio file:

 SpeechToText service = new SpeechToText();
 service.setUsernameAndPassword("USERNAME", "PASSWORD");
 service.setEndPoint("SERVICE_URL");

 SpeechResults results = service.recognize(new File("sample1.wav")).execute();
 System.out.println(results);
 

Parameters:

audio - the audio file

Returns:

the SpeechResults

Throws:

IllegalArgumentException - if the file extension doesn't match a valid audio type

recognize

public ServiceCall<SpeechResults> recognize(File audio,
                                            RecognizeOptions options)

Recognizes an audio file and returns SpeechResults.

Here is an example of how to recognize an audio file:

 SpeechToText service = new SpeechToText();
 service.setUsernameAndPassword("USERNAME", "PASSWORD");
 service.setEndPoint("SERVICE_URL");

 RecognizeOptions options = new RecognizeOptions().maxAlternatives(3).continuous(true);

 File audio = new File("sample1.wav");

 SpeechResults results = service.recognize(audio, options).execute();
 System.out.println(results);
 

Parameters:

audio - the audio file

options - the recognize options

Returns:

the SpeechResults

recognizeUsingWebSocket

public void recognizeUsingWebSocket(InputStream audio,
                                    RecognizeOptions options,
                                    RecognizeCallback callback)

Recognizes an audio InputStream using a WebSocket.
The RecognizeCallback instance will be called every time the service sends SpeechResults.

Here is an example of how to recognize an audio file using WebSockets and get interim results:

 SpeechToText service = new SpeechToText();
 service.setUsernameAndPassword("USERNAME", "PASSWORD");
 service.setEndPoint("SERVICE_URL");

 RecognizeOptions options = new RecognizeOptions().maxAlternatives(2).continuous(true);

 FileInputStream audio = new FileInputStream("sample1.wav");

 service.recognizeUsingWebSocket(audio, options, new BaseRecognizeCallback() {
   @Override
   public void onTranscript(SpeechResults speechResults) {
     System.out.println(speechResults);
   }
 });
 

Parameters:

audio - the audio input stream

options - the recognize options

callback - the callback

registerCallback

public ServiceCall<RecognitionCallback> registerCallback(String callbackUrl,
                                                         String secret)

Registers a callback URL with the service for use with subsequent asynchronous recognition requests. The service attempts to register, or white-list, the callback URL. To be registered successfully, the callback URL must respond to a GET request from the service, after which the service responds with response code 201 to the original registration request.
If you specify a secret with the request, the service uses it as a key to calculate an HMAC-SHA1 signature of a random challenge string in its response to the request. The signature provides authentication and data integrity for HTTP communications.

Parameters:

callbackUrl - the callback url

secret - the secret

Returns:

the service call

resetCustomization

public ServiceCall<Void> resetCustomization(String customizationId)

Resets a custom language model by removing all corpora and words from the model. Resetting a custom model initializes the model to its state when it was first created. Metadata such as the name and language of the model are preserved.

Parameters:

customizationId - The GUID of the custom language model being reset. You must make the request with the service credentials of the model's owner.

Returns:

the service call

trainCustomization

public ServiceCall<Void> trainCustomization(String customizationId,
                                            Customization.WordTypeToAdd wordTypeToAdd)

Initiates the training of a custom language model with new corpora, words, or both. After adding training data to the custom model with the corpora or words methods, use this method to begin the actual training of the model on the new data. You can specify whether the custom model is to be trained with all words from its words resources or only with words that were added or modified by the user.

This method is asynchronous and can take on the order of minutes to complete depending on the amount of data on which the service is being trained and the current load on the service. You can monitor the status of the training by using the getCustomization(String) method to poll the model's status.

Training can fail to start for the following reasons:

• No training data (corpora or words) have been added to the custom model.
• Pre-processing of corpora to generate a list of out-of-vocabulary (OOV) words is not complete.
• Pre-processing of words to validate or auto-generate sounds-like pronunciations is not complete.
• One or more words that were added to the custom model have invalid sounds-like pronunciations that you must fix.

Parameters:

customizationId - The GUID of the custom language model being trained. You must make the request with the service credentials of the model's owner.

wordTypeToAdd - the word type to add

Returns:

the service call