Class: SpeechToTextV1

SpeechToTextV1

new SpeechToTextV1(options)

Speech Recognition API Wrapper

Parameters:
Name Type Description
options Object
Source:

Methods

addCorpus(params, callback)

Add a corpus to a custom model.

Parameters:
Name Type Attributes Default Description
params Object

The parameters

Properties
Name Type Description
customization_id String

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.

name String

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.

parms.allow_overwrite Boolean <optional>
false

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.

params.corpus String | Buffer | ReadStream <optional>

the text of the corpus - may be provided as a String, a Buffer, or a ReadableStream. A ReadableStream is recommended when reading a file from disk.

callback function
Source:

addWord(params, callback)

Add a single custom word.

Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Attributes Description
customization_id String

The GUID of the custom language model

word String

The custom word that is to be added to the custom model. Do not include spaces in the word. Use a - (dash) or _ (underscore) to connect the tokens of compound words.

sounds_like Array.<String>

An array of sounds-like pronunciations for the custom word.

display_as String <optional>

An alternative spelling for the custom word when it appears in a transcript.

callback function
Source:

addWords(params, callback)

Add multiple custom words.

Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Description
customization_id String

The GUID of the custom language model

words Array.<Word>

Array of objects: [{word: String, sounds_like: [String, ...], display_as: String}, ...]

callback function
Source:

createCustomization(params, callback)

Creates a new empty custom voice model

Response looks like:

{
  "customization_id": "abc996ea-86ca-482e-b7ec-0f31c34e5ee9"
}
Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Attributes Description
base_model_name String

The base language model, for example, en-US_BroadbandModel

name String

The customization name

description String <optional>

The customization description

callback function
Source:

createRecognitionJob(params, callback) → {ReadableStream|undefined}

Creates a job for a new asynchronous recognition request. The job is owned by the user whose service credentials are used to create it. How you learn the status and results of a job depends on the parameters you include with the job creation request.

Parameters:
Name Type Description
params object

The parameters

Properties
Name Type Attributes Description
audio Stream

Audio to be recognized

content_type string

The Content-type e.g. audio/l16; rate=48000

callback_url string

A URL to which callback notifications are to be sent

events string | Array.<string> <optional>

Events to trigger the callback for. Valid options are recognitions.started, recognitions.completed, recognitions.failed, recognitions.completed_with_results

user_token string <optional>

The token allows the user to maintain an internal mapping between jobs and notification events

results_ttl number <optional>

time to alive of the job result

* * <optional>

all params that .recognize() accepts may also be passed to createRecognitionJob()

callback function
Source:
Returns:
Type
ReadableStream | undefined

createRecognizeStream(params) → {RecognizeStream}

Replaces recognizeLive & friends with a single 2-way stream over websockets

Parameters:
Name Type Description
params Object

The parameters

Source:
Returns:
Type
RecognizeStream

createSession(params, callback)

Create a session Set-cookie header is returned with a cookie that must be used for each request using this session.

Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Description
model string

The model to use during the session

callback function
Source:

deleteCorpus(params, callback)

Delete a corpus.

Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Description
customization_id String

The GUID of the custom language model

name String

The name of the corpus.

callback function
Source:

deleteCustomization(params, callback)

Delete a custom model.

Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Description
customization_id String

The GUID of the custom language model

callback function
Source:

deleteRecognitionJob(params, callback) → {ReadableStream|undefined}

Deletes the specified job. You cannot delete a job that the service is actively processing.

Parameters:
Name Type Description
params

The parameters

Properties
Name Type Description
id

id of the Job

callback
Source:
Returns:
Type
ReadableStream | undefined

deleteSession(params, callback)

Deletes the specified session.

Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Description
session_id String

Session id.

callback function
Source:

deleteWord(params, callback)

Delete a custom word

Removing a custom word does not affect the custom model until you train the model with the Train a custom model method.

Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Description
customization_id String

The GUID of the custom language model

word String

The custom word that is to be deleted.

callback function
Source:

getCorpora(params, callback)

List corpora

Lists information about all corpora that have been added to the specified custom language model. The information includes the total number of words and out-of-vocabulary (OOV) words, name, and status of each corpus.

Example Result:

 {
     "corpora": [{
         "out_of_vocabulary_words": 1,
         "total_words": 233,
         "name": "corpus-1",
         "status": "analyzed"
     }, {
         "out_of_vocabulary_words": 3,
         "total_words": 20,
         "name": "corpus-2",
         "status": "being_processed"
     }]
 }
Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Description
customization_id String

The GUID of the custom language model

callback function
Source:

getCorpus(params, callback)

Get corpus details

Example response:

 {
   "name": "corpus-1",
   "total_words": 100,
   "out_of_vocabulary_words": 5,
   "status": "analyzed"
 }
Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Description
customization_id String

The GUID of the custom language model

name String

The corpus name

callback function
Source:

getCustomization(params, callback)

Get customization details

Example response:

 { owner: '8a6f5bb1-5b2d-4a20-85a9-eaa421d25c88',
   base_model_name: 'en-US_BroadbandModel',
   customization_id: 'e695ad30-97c1-11e6-be92-bb627d4684b9',
   created: '2016-10-21T19:09:33.443Z',
   name: 'js-sdk-test-temporary',
   description: 'Temporary customization to test the JS SDK. Should be automatically deleted within a few minutes.',
   progress: 0,
   language: 'en-US',
   status: 'pending' }
Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Description
customization_id String

The GUID of the custom language model

callback function
Source:

getCustomizations(params, callback)

List all customizations

Example response:

 { customizations:
     [ { owner: '8a6f5bb1-5b2d-4a20-85a9-eaa421d25c88',
         base_model_name: 'en-US_BroadbandModel',
         customization_id: '6a7785a0-9665-11e6-a73a-0da9193a4475',
         created: '2016-10-20T01:35:00.346Z',
         name: 'IEEE-test',
         description: '',
         progress: 0,
         language: 'en-US',
         status: 'pending' },
       { owner: '8a6f5bb1-5b2d-4a20-85a9-eaa421d25c88',
         base_model_name: 'en-US_BroadbandModel',
         customization_id: '9e2f6bb0-9665-11e6-a73a-0da9193a4475',
         created: '2016-10-20T01:36:27.115Z',
         name: 'IEEE-test',
         description: '',
         progress: 0,
         language: 'en-US',
         status: 'ready' },
       { owner: '8a6f5bb1-5b2d-4a20-85a9-eaa421d25c88',
         base_model_name: 'en-US_BroadbandModel',
         customization_id: '6b194e70-9666-11e6-a73a-0da9193a4475',
         created: '2016-10-20T01:42:10.903Z',
         name: 'IEEE-test',
         description: '',
         progress: 100,
         language: 'en-US',
         status: 'available' } ] }
Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Attributes Description
language String <optional>

optional filter.

callback function
Source:

getModel(params, callback) → {ReadableStream|undefined}

Get information about a model based on the given model_id

Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Description
model_id String

The desired model

callback function
Source:
Returns:
Type
ReadableStream | undefined

getModels(params, callback) → {ReadableStream|undefined}

List of models available.

Parameters:
Name Type Description
params Object

The parameters

callback function
Source:
Returns:
Type
ReadableStream | undefined

getRecognitionJob(params, callback) → {ReadableStream|undefined}

Returns the status and ID of all outstanding jobs associated with the service credentials with which it is called.

Parameters:
Name Type Description
params
Properties
Name Type Description
id

id of the Job

callback
Source:
Returns:
Type
ReadableStream | undefined

getRecognitionJobs(paramsopt, callback) → {ReadableStream|undefined}

Returns the status and ID of all outstanding jobs associated with the service credentials with which it is called. The method also returns the creation and update times of each job, and, if a job was created with a callback URL and a user token, the user token for the job.

Parameters:
Name Type Attributes Description
params Object <optional>
callback function
Source:
Returns:
Type
ReadableStream | undefined

getRecognizeStatus(params, callback)

Get the state of the engine to check if recognize is available. This is the way to check if the session is ready to accept a new recognition task. The returned state has to be 'initialized' to be able to do recognize POST.

Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Attributes Description
session_id String <optional>

Session used in the recognition

callback function
Deprecated:
  • use createRecognizeStream instead
Source:

getWord(params, callback)

Get a custom word

Lists information about a custom word from a custom language model.

Example output:

 {
    "sounds_like": ["N. C. A. A.","N. C. double A."],
    "display_as": "NCAA",
    "source": ["corpus3","user"]
 }
Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Description
customization_id String

The GUID of the custom language model

word String

The custom word

callback function
Source:

getWords(params, callback)

List all custom words

Lists information about all custom words from a custom language model. You can list all words from the custom model's words resource, only custom words that were added or modified by the user, or only OOV words that were extracted from corpora.

Example response:

 {
     "words": [
        {
           "word": "hhonors",
           "sounds_like": ["hilton honors","h honors"],
           "display_as": "HHonors",
           "source": ["corpus1"]
        },
        {
           "word": "ieee",
           "sounds_like": ["i triple e"],
           "display_as": "IEEE",
           "source": ["corpus1","corpus2"]
        },
        {
           "word": "tomato",
           "sounds_like": ["tomatoh","tomayto"],
           "display_as": "",
           "source": ["user"]
        },
        {
           "word": "$75.00",
           "sounds_like": ["75 dollars"],
           "display_as": "",
           "source": ["user"],
           "error":" Numbers are not allowed in sounds-like"
        }
     ]
  }
Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Attributes Default Description
customization_id String

The GUID of the custom language model

sort String

+alphabetical|-alphabetical|+count|-count to order result in alphabetical oredering or count ordering.

word_type String <optional>
all

all|user|corpora - user shows only custom words that were added or modified by the user; corpora shows only OOV that were extracted from corpora.

callback function
Source:

observeResult(params, callback)

Result observer for upcoming or ongoing recognition task in the session. This request has to be started before POST on recognize finishes, otherwise it waits for the next recognition.

Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Attributes Description
session_id String <optional>

Session used in the recognition

interim_results boolean <optional>

If true, interim results will be returned. Default: false

callback function
Deprecated:
  • use createRecognizeStream instead
Source:

recognize(params, callback)

Speech recognition for given audio using default model.

Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Attributes Description
audio Stream

Audio to be recognized

content_type String

Content-type

continuous Boolean <optional>
max_alternatives Number <optional>
timestamps Boolean <optional>
word_confidence Boolean <optional>
inactivity_timeout Number <optional>
model String <optional>
interim_results Boolean <optional>
keywords Boolean <optional>
keywords_threshold Number <optional>
word_alternatives_threshold Number <optional>
profanity_filter Boolean <optional>
smart_formatting Boolean <optional>
customization_id String <optional>
speaker_labels Boolean <optional>
callback function
Source:

recognizeLive(params, callback)

Creates a HTTP/HTTPS request to /recognize and keep the connection open. Sets 'Transfer-Encoding': 'chunked' and prepare the connection to send chunk data.

Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Attributes Description
content_type String <optional>

The Content-type e.g. audio/l16; rate=48000

session_id String <optional>

The session id

callback function
Deprecated:
  • use createRecognizeStream instead
Source:

registerCallback(params, callback) → {ReadableStream|undefined}

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 if it is not already registered by sending a GET request to the callback URL.

Parameters:
Name Type Description
params object

The parameters

Properties
Name Type Attributes Description
callback_url string

A URL to which callback notifications are to be sent

user_secret string <optional>

A user-specified string that the service uses to generate the HMAC-SHA1 signature that it sends via the X-Callback-Signature header

callback function
Source:
Returns:
Type
ReadableStream | undefined

resetCustomization(params, callback)

Reset a custom model.

Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Description
customization_id String

The GUID of the custom language model

callback function
Source:

trainCustomization(params, callback)

Train a custom model.

Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Attributes Default Description
customization_id String

The GUID of the custom language model

word_type_to_add String <optional>
all

set to 'user' to train the model only on new words that were added or modified by the user; the model is not trained on new words extracted from corpora.

callback function
Source:

whenCorporaAnalyzed(params, callback)

Waits while corpora analysis status is 'being_processes', fires callback once the status is 'analyzed'

Note: the code will throw an error in case there in no corpus in the customization

Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Attributes Default Description
customization_id String

The GUID of the custom language model

interval Number <optional>
5000

(milliseconds) - how long to wait between status checks

times Number <optional>
30

maximum number of attempts

callback function
Source:

whenCustomizationReady(params, callback)

Waits while a customization status is 'pending' or 'training', fires callback once the status is 'ready' or 'available'.

Note: the customization will remain in 'pending' status until at least one word corpus is added.

See http://www.ibm.com/watson/developercloud/speech-to-text/api/v1/#list_models for status details.

Parameters:
Name Type Description
params Object

The parameters

Properties
Name Type Attributes Default Description
customization_id String

The GUID of the custom language model

interval Number <optional>
5000

(milliseconds) - how log to wait between status checks

times Number <optional>
30

maximum number of attempts

callback function
Source: