Parameters of recognize method

• access_token

  Required*

  string

  Pass a valid access token to establish an authenticated connection with the service. You must establish the connection before the access token expires. You pass an access token only to establish an authenticated connection. After you establish a connection, you can keep it alive indefinitely. You remain authenticated for as long as you keep the connection open. You do not need to refresh the access token for an active connection that lasts beyond the token's expiration time. After a connection is established, it can remain active even after the token or its credentials are deleted.

  • IBM Cloud only. Pass an Identity and Access Management (IAM) access token to authenticate with the service. You pass an IAM access token instead of passing an API key with the call. For more information, see Authenticating to IBM Cloud.

  • IBM Cloud Pak for Data only. Pass an access token as you would with the Authorization header of an HTTP request. For more information, see Authenticating to IBM Cloud Pak for Data.

• model

  string

  The identifier of the model that is to be used for all recognition requests sent over the connection. (Note: The model ar-AR_BroadbandModel is deprecated; use ar-MS_BroadbandModel instead.) See Previous-generation languages and models and Next-generation languages and models.

  Allowable values: [ar-AR_BroadbandModel, ar-MS_BroadbandModel, ar-MS_Telephony, cs-CZ_Telephony, de-DE_BroadbandModel, de-DE_NarrowbandModel, de-DE_Telephony, en-AU_BroadbandModel, en-AU_NarrowbandModel, en-AU_Telephony, en-GB_BroadbandModel, en-GB_NarrowbandModel, en-GB_Telephony, en-IN_Telephony, en-US_BroadbandModel, en-US_Multimedia, en-US_NarrowbandModel, en-US_ShortForm_NarrowbandModel, en-US_Telephony, es-AR_BroadbandModel, es-AR_NarrowbandModel, es-ES_BroadbandModel, es-ES_NarrowbandModel, es-ES_Telephony, es-CL_BroadbandModel, es-CL_NarrowbandModel, es-CO_BroadbandModel, es-CO_NarrowbandModel, es-MX_BroadbandModel, es-MX_NarrowbandModel, es-PE_BroadbandModel, es-PE_NarrowbandModel, fr-CA_BroadbandModel, fr-CA_NarrowbandModel, fr-CA_Telephony, fr-FR_BroadbandModel, fr-FR_Multimedia, fr-FR_NarrowbandModel, fr-FR_Telephony, hi-IN_Telephony, it-IT_BroadbandModel, it-IT_NarrowbandModel, it-IT_Telephony, ja-JP_BroadbandModel, ja-JP_Multimedia, ja-JP_NarrowbandModel, ko-KR_BroadbandModel, ko-KR_Multimedia, ko-KR_NarrowbandModel, ko-KR_Telephony, nl-BE_Telephony, nl-NL_BroadbandModel, nl-NL_NarrowbandModel, nl-NL_Telephony, pt-BR_BroadbandModel, pt-BR_NarrowbandModel, pt-BR_Telephony, zh-CN_BroadbandModel, zh-CN_NarrowbandModel]

  Default: en-US_BroadbandModel

• language_customization_id

  string

  The customization ID (GUID) of a custom language model that is to be used for all requests sent over the connection. The base model of the specified custom language model must match the model that is specified with the model parameter. You must make the request with credentials for the instance of the service that owns the custom model. Omit the parameter to use the specified model with no custom language model. See Using a custom language model for speech recognition.

  Note: Use this parameter instead of the deprecated customization_id parameter.

• acoustic_customization_id

  string

  The customization ID (GUID) of a custom acoustic model that is to be used for the request. The base model of the specified custom acoustic model must match the model that is specified with the model parameter. You must make the request with credentials for the instance of the service that owns the custom model. Omit the parameter to use the specified model with no custom acoustic model. See Using a custom acoustic model for speech recognition.

• base_model_version

  string

  The version of the specified base model that is to be used for all requests sent over the connection. Multiple versions of a base model can exist when a model is updated for internal improvements. The parameter is intended primarily for use with custom models that have been upgraded for a new base model. The default value depends on whether the parameter is used with or without a custom model. See Making speech recognition requests with upgraded custom models.

• x-watson-learning-opt-out

  string

  Indicates whether IBM can use data that is sent over the connection to improve the service for future users. Specify true to prevent IBM from accessing the logged data. See Data collection.

  Default: false

• x-watson-metadata

  string

  Associates a customer ID with all data that is passed over the connection. The parameter accepts the argument customer_id={id}, where {id} is a random or generic string that is to be associated with the data. URL-encode the argument to the parameter, for example customer_id%3dmy_ID. By default, no customer ID is associated with the data. See Data labels.

• customization_id

  string

  Deprecated. Use the language_customization_id parameter to specify the customization ID (GUID) of a custom language model that is to be used with all requests sent over the connection. Do not specify both parameters with a request.

Parameters of WebSocket text messages

Parameters

• action

  Required*

  string

  The action that is to be performed.

  Allowable values:

  • start initiates a recognition request. The message can also include any other optional parameters that are described in this table. After sending this text message, the client sends the data as a binary message (blob).

    Between recognition requests, the client can send new start messages to modify the parameters that are to be used for subsequent requests. By default, the service continues to use the parameters that were specified with the previous start message.

  • stop indicates that all audio data for the request has been sent to the service. The client can send additional requests with the same or different parameters.

• objectMode

  boolean

  Indicates how the data event handler is to return the response from the service:

  • If false, the event handler returns only a string with the final transcription of the recognition results, regardless of the parameters that you pass with the request. You must set the encoding for your instance of the RecognizeStream object to UTF-8 by including a call that is similar to the following line of code in your application:

    recognizeStream.setEncoding('utf8');

    Do not include this call if you set the objectMode parameter to true.

  • If true, the event handler returns the recognition results exactly as it receives them from the service: as one or more instances of a SpeechRecognitionResults object.

  For more information, see the Example request for the method.

• audio

  Required*

  java.io.InputStream AudioSource

  The audio that is to be transcribed.

  An AudioSource object that provides the audio that is to be transcribed.

• content-type

  contentType

  content_type

  content_type

  Required*

  string str

  The format (MIME type) of the audio. For more information about specifying an audio format, see Audio formats (content types) in the method description.

  Allowable values: [application/octet-stream, audio/alaw, audio/basic, audio/flac, audio/g729, audio/l16, audio/mp3, audio/mpeg, audio/mulaw, audio/ogg, audio/ogg;codecs=opus, audio/ogg;codecs=vorbis, audio/wav, audio/webm, audio/webm;codecs=opus, audio/webm;codecs=vorbis]

• callback

  recognize_callback

  Required*

  object

  A BaseRecognizeCallback object that implements the RecognizeCallback interface to handle events from the WebSocket connection. Override the definitions of the object's default methods to respond to events as needed by your application.

  A RecognizeCallback object that defines methods to handle events from the WebSocket connection. Override the definitions of the object's default methods to respond to events as needed by your application.

• audio

  File

  The audio that is to be transcribed.

• chunk_data

  boolean

  If true, the WebSocketClient expects to receive data in chunks rather than as a single audio file. See Audio transmission.

  Default: false

• model

  string str

  The identifier of the model that is to be used for the recognition request. (Note: The model ar-AR_BroadbandModel is deprecated; use ar-MS_BroadbandModel instead.) See Previous-generation languages and models and Next-generation languages and models.

  Allowable values: [ar-AR_BroadbandModel, ar-MS_BroadbandModel, ar-MS_Telephony, cs-CZ_Telephony, de-DE_BroadbandModel, de-DE_NarrowbandModel, de-DE_Telephony, en-AU_BroadbandModel, en-AU_NarrowbandModel, en-AU_Telephony, en-GB_BroadbandModel, en-GB_NarrowbandModel, en-GB_Telephony, en-IN_Telephony, en-US_BroadbandModel, en-US_Multimedia, en-US_NarrowbandModel, en-US_ShortForm_NarrowbandModel, en-US_Telephony, es-AR_BroadbandModel, es-AR_NarrowbandModel, es-ES_BroadbandModel, es-ES_NarrowbandModel, es-ES_Telephony, es-CL_BroadbandModel, es-CL_NarrowbandModel, es-CO_BroadbandModel, es-CO_NarrowbandModel, es-MX_BroadbandModel, es-MX_NarrowbandModel, es-PE_BroadbandModel, es-PE_NarrowbandModel, fr-CA_BroadbandModel, fr-CA_NarrowbandModel, fr-CA_Telephony, fr-FR_BroadbandModel, fr-FR_Multimedia, fr-FR_NarrowbandModel, fr-FR_Telephony, hi-IN_Telephony, it-IT_BroadbandModel, it-IT_NarrowbandModel, it-IT_Telephony, ja-JP_BroadbandModel, ja-JP_Multimedia, ja-JP_NarrowbandModel, ko-KR_BroadbandModel, ko-KR_Multimedia, ko-KR_NarrowbandModel, ko-KR_Telephony, nl-BE_Telephony, nl-NL_BroadbandModel, nl-NL_NarrowbandModel, nl-NL_Telephony, pt-BR_BroadbandModel, pt-BR_NarrowbandModel, pt-BR_Telephony, zh-CN_BroadbandModel, zh-CN_NarrowbandModel]

  Default: en-US_BroadbandModel

• languageCustomizationId

  language_customization_id

  string str

  The customization ID (GUID) of a custom language model that is to be used for the request. The base model of the specified custom language model must match the model that is specified with the model parameter. You must make the request with credentials for the instance of the service that owns the custom model. Omit the parameter to use the specified model with no custom language model. See Using a custom language model for speech recognition.

  Note: Use this parameter instead of the deprecated customization_id customizationId parameter.

• acousticCustomizationId

  acoustic_customization_id

  string str

  The customization ID (GUID) of a custom acoustic model that is to be used for the request. The base model of the specified custom acoustic model must match the model that is specified with the model parameter. You must make the request with credentials for the instance of the service that owns the custom model. Omit the parameter to use the specified model with no custom acoustic model. See Using a custom acoustic model for speech recognition.

• customization_weight

  customizationWeight

  double float

  If you specify a customization ID when you open the connection, If you specify a customization ID, you can use the customization weight to tell the service how much weight to give to words from the custom language model compared to those from the base model for the current request.

  Specify a value between 0.0 and 1.0. Unless a different customization weight was specified for the custom model when it was trained, the default value is 0.3. A customization weight that you specify overrides a weight that was specified when the custom model was trained.

  The default value yields the best performance in general. Assign a higher value if your audio makes frequent use of OOV words from the custom model. Use caution when you set the weight: a higher value can improve the accuracy of phrases from the custom model's domain, but it can negatively affect performance on non-domain phrases.

  See Using customization weight.

• base_model_version

  baseModelVersion

  string str

  The version of the specified base model that is to be used for the request. Multiple versions of a base model can exist when a model is updated for internal improvements. The parameter is intended primarily for use with custom models that have been upgraded for a new base model. The default value depends on whether the parameter is used with or without a custom model. See Making speech recognition requests with upgraded custom models.

• inactivity_timeout

  inactivityTimeout

  integer int

  The time in seconds after which, if only silence (no speech) is detected in the audio, the connection is closed. The default is 30 seconds. The parameter is useful for stopping audio submission from a live microphone when a user simply walks away. Use -1 for infinity. See Inactivity timeout.

  Default: 30

• interim_results

  interimResults

  boolean bool

  If true, the service returns intermediate hypotheses as a stream of JSON SpeechRecognitionResults objects before returning final results for an utterance. If false, the service returns only a single SpeechRecognitionResults object with final results for any utterance. (See the objectMode parameter for information about controlling the response from the method.)

  • For previous-generation models, interim results are available for all models. To receive interim results, set the interim_results interimResults parameter to true.

  • For next-generation models, interim results are available only for those models that support low latency. To receive interim results, see both the interim_results interimResults and low_latency lowLatency parameters to true.

  For for information, see:

  • Interim results

  • Requesting interim results and low latency

  • How the service sends recognition results

  Default: false

• keywords

  string[] [string] list[str] Array<String>

  An array of keyword strings to spot in the audio. Each keyword string can include one or more string tokens. Keywords are spotted only in the final results, not in interim hypotheses. If you specify any keywords, you must also specify a keywords threshold. Omit the parameter or specify an empty array if you do not need to spot keywords.

  You can spot a maximum of 1000 keywords with a single request. A single keyword can have a maximum length of 1024 characters, though the maximum effective length for double-byte languages might be shorter. Keywords are case-insensitive.

  See Keyword spotting.

• keywords_threshold

  keywordsThreshold

  float

  A confidence value that is the lower bound for spotting a keyword. A word is considered to match a keyword if its confidence is greater than or equal to the threshold. Specify a probability between 0.0 and 1.0. No keyword spotting is performed if you omit the parameter. If you specify a threshold, you must also specify one or more keywords. See Keyword spotting.

• max_alternatives

  maxAlternatives

  integer int

  The maximum number of alternative transcripts that the service is to return. By default, the service returns a single transcript. If you specify a value of 0, the service uses the default value, 1. See Maximum alternatives.

  Default: 1

• word_alternatives_threshold

  wordAlternativesThreshold

  float

  A confidence value that is the lower bound for identifying a hypothesis as a possible word alternative (also known as "Confusion Networks"). An alternative word is considered if its confidence is greater than or equal to the threshold. Specify a probability between 0.0 and 1.0. By default, the service computes no alternative words. See Word alternatives.

• word_confidence

  wordConfidence

  boolean bool

  If true, the service returns a confidence measure in the range of 0.0 to 1.0 for each word. By default, no word confidence measures are returned. See Word confidence.

  Default: false

• timestamps

  boolean bool

  If true, the service returns time alignment for each word. By default, no timestamps are returned. See Word timestamps.

  Default: false

• profanity_filter

  profanityFilter

  boolean bool

  If true, the service filters profanity from all output except for keyword results by replacing inappropriate words with a series of asterisks. Set the parameter to false to return results with no censoring.

  Note: The parameter can be used with US English and Japanese transcription only. See Profanity filtering.

  Default: true

• smart_formatting

  smartFormatting

  boolean bool

  If true, the service converts dates, times, series of digits and numbers, phone numbers, currency values, and internet addresses into more readable, conventional representations in the final transcript of a recognition request. For US English, the service also converts certain keyword strings to punctuation symbols. By default, no smart formatting is performed.

  Beta: The parameter is beta functionality. It can be used with US English, Japanese, and Spanish transcription only. See Smart formatting.

  Default: false

• speaker_labels

  speakerLabels

  boolean bool

  If true, the response includes labels that identify which words were spoken by which participants in a multi-person exchange. By default, the service returns no speaker labels. Setting speaker_labels speakerLabels to true forces the timestamps parameter to be true, regardless of whether you specify false for the parameter.

  • For previous-generation models, can be used with Australian English, US English, German, Japanese, Korean, and Spanish (both broadband and narrowband models) and UK English (narrowband model) transcription only.

  • For next-generation models, can be used with Czech, English (Australian, Indian, UK, and US), German, Japanese, Korean, and Spanish transcription only.

  Beta: The parameter is beta functionality. Restrictions and limitations apply to the use of speaker labels for both types of models. See Speaker labels.

  Default: false

• http_proxy_host

  str

  If you are passing requests through a proxy, specify the hostname of the proxy server. Use the http_proxy_port parameter to specify the port number at which the proxy listens. Omit both parameters if you are not using a proxy.

  Default: None

• http_proxy_port

  str

  If you are passing requests through a proxy, specify the port number at which the proxy service listens. Use the http_proxy_host parameter to specify the hostname of the proxy. Omit both parameters if you are not using a proxy.

  Default: None

• customizationId

  customization_id

  string str

  Deprecated. Use the language_customization_id languageCustomizationId parameter to specify the customization ID (GUID) of a custom language model that is to be used with the request. Do not specify both parameters with a request.

• grammarName

  grammar_name

  string str

  The name of a grammar that is to be used with the recognition request. If you specify a grammar, you must also use the language_customization_id languageCustomizationId parameter to specify the name of the custom language model for which the grammar is defined. The service recognizes only strings that are recognized by the specified grammar; it does not recognize other custom words from the model's words resource.

  Beta: The parameter is beta functionality. See Using a grammar for speech recognition.

• redaction

  boolean bool

  If true, the service redacts, or masks, numeric data from final transcripts. The feature redacts any number that has three or more consecutive digits by replacing each digit with an X character. It is intended to redact sensitive numeric data, such as credit card numbers. By default, the service performs no redaction.

  When you enable redaction, the service automatically enables smart formatting, regardless of whether you explicitly disable that feature. To ensure maximum security, the service also disables keyword spotting (ignores the keywords and keywords_threshold keywordsThreshold parameters) and returns only a single final transcript (forces the max_alternatives maxAlternatives parameter to be 1).

  Beta: The parameter is beta functionality. It can be used with US English, Japanese, and Korean transcription only. See Numeric redaction.

  Default: false

• processing_metrics

  processingMetrics

  boolean bool

  If true, requests processing metrics about the service's transcription of the input audio. The service returns processing metrics at the interval that is specified by the processing_metrics_interval processingMetricsInterval parameter. It also returns processing metrics for transcription events, for example, for final and interim results. By default, the service returns no processing metrics. See Processing metrics.

  Default: false

• processing_metrics_interval

  processingMetricsInterval

  float

  Specifies the interval in seconds at which the service is to return processing metrics. The parameter is ignored unless the processing_metrics processingMetrics parameter is set to true.

  The parameter accepts a minimum value of 0.1 seconds. The level of precision is not restricted, so you can specify values such as 0.25 and 0.125.

  The service does not impose a maximum value. If you want to receive processing metrics only for transcription events instead of at periodic intervals, set the value to a large number. If the value is larger than the duration of the audio, the service returns processing metrics only for transcription events.

  See Processing metrics.

  Default: 1.0

• audio_metrics

  audioMetrics

  boolean bool

  If true, requests detailed information about the signal characteristics of the input audio. The service returns audio metrics with the final transcription results. By default, the service returns no audio metrics. See Audio metrics.

  Default: false

• end_of_phrase_silence_time

  endOfPhraseSilenceTime

  double float

  If true, specifies the duration of the pause interval at which the service splits a transcript into multiple final results. If the service detects pauses or extended silence before it reaches the end of the audio stream, its response can include multiple final results. Silence indicates a point at which the speaker pauses between spoken words or phrases.

  Specify a value for the pause interval in the range of 0.0 to 120.0.

  • A value greater than 0 specifies the interval that the service is to use for speech recognition.

  • A value of 0 indicates that the service is to use the default interval. It is equivalent to omitting the parameter.

  The default pause interval for most languages is 0.8 seconds. The default for Chinese is 0.6 seconds.

  See End of phrase silence time.

  Default: 0.8

• split_transcript_at_phrase_end

  splitTranscriptAtPhraseEnd

  boolean bool

  If true, directs the service to split the transcript into multiple final results based on semantic features of the input, for example, at the conclusion of meaningful phrases such as sentences. The service bases its understanding of semantic features on the base language model that you use with a request. Custom language models and grammars can also influence how and where the service splits a transcript. By default, the service splits transcripts based solely on the pause interval. The feature is generally available for US English and UK English only.

  See Split transcript at phrase end.

  Default: false

• speech_detector_sensitivity

  speechDetectorSensitivity

  double float

  The sensitivity of speech activity detection that the service is to perform. Use the parameter to suppress word insertions from music, coughing, and other non-speech events. The service biases the audio it passes for speech recognition by evaluating the input audio against prior models of speech and non-speech activity.

  Specify a value between 0.0 and 1.0:

  • 0.0 suppresses all audio (no speech is transcribed).

  • 0.5 (the default) provides a reasonable compromise for the level of sensitivity.

  • 1.0 suppresses no audio (speech detection sensitivity is disabled).

  The values increase on a monotonic curve.

  The parameter is supported with all next-generation models and with most previous-generation models. See Speech detector sensitivity and Language model support.

  Default: 0.5

• background_audio_suppression

  backgroundAudioSuppression

  double float

  The level to which the service is to suppress background audio based on its volume to prevent it from being transcribed as speech. Use the parameter to suppress side conversations or background noise.

  Specify a value between 0.0 and 1.0:

  • 0.0 (the default) provides no suppression (background audio suppression is disabled).

  • 0.5 provides a reasonable level of audio suppression for general usage.

  • 1.0 suppresses all audio (no audio is transcribed).

  The values increase on a monotonic curve.

  The parameter is supported with all next-generation models and with most previous-generation models. See Background audio suppression and Language model support.

  Default: 0.0

• low_latency

  lowLatency

  boolean bool

  If true for next-generation Multimedia and Telephony models that support low latency, directs the service to produce results even more quickly than it usually does. Next-generation models produce transcription results faster than previous-generation models. The low_latency parameter causes the models to produce results even more quickly, though the results might be less accurate when the parameter is used.

  Note: The low_latency lowLatency parameter is not available for previous-generation Broadband and Narrowband models. It is available only for some next-generation models. To obtain interim results with a next-generation model, the model must support low latency and both the interim_results interimResults and low_latency lowLatency parameters must be set to true.

  • For a list of next-generation models that support low latency, see Supported next-generation language models.

  • For more information about the low_latency lowLatency parameter, see Low latency.

  Default: false

Methods

• onopen({event})

  The status of the connection's opening.

• onmessage({event})

  Response messages from the service, including the results of the request as one or more JSON SpeechRecognitionResults objects.

• onerror({event})

  Errors for the connection or request.

• onclose({event})

  The status of the connection's closing.

Methods

• void onConnected()

  The WebSocket connection is established.

• void onListening()

  The service is listening for audio.

• void onTranscription
(SpeechRecognitionResults {speechRecognitionResults})

  Results for the request are received from the service.

• void onTranscriptionComplete()

  Final results for the request have been returned by the service.

• void onError(java.lang.Exception {e})

  An error occurs in the WebSocket connection.

• void onInactivityTimeout
(java.lang.RuntimeException {runtimeException})

  An inactivity timeout occurs for the request.

• void onDisconnected()

  The WebSocket connection is closed.

Events

• data

  Results for the request are received on the stream.

• readable

  Data is available to be read from the stream.

• end

  No data remains to be read from the stream.

• close

  The WebSocket connection is closed.

• error

  An error occurs in the WebSocket connection.

Methods

• on_connected()

  The WebSocket connection is established.

• on_listening()

  The service is listening for audio.

• on_data({data})

  Returns all response data for the request from the service.

• on_hypothesis({hypothesis})

  Returns interim results or maximum alternatives from the service when those responses are requested.

• on_transcription({transcript})

  Returns final transcription results for the request from the service.

• on_error({error})

  Reports an error in the WebSocket connection.

• on_inactivity_timeout({error})

  Reports an inactivity timeout for the request.

Return code

• 1000

  The connection closed normally.

• 1001

  The connection closed because the remote peer is leaving.

• 1002

  The connection closed due to a protocol error.

• 1003

  The connection closed because the service could not process the input from the client.

• 1004

  Reserved response code.

• 1005

  The connection closed for a reason other than those defined by the remaining return codes.

• 1006

  The connection closed abnormally.

• 1007

  The connection closed because the service received invalid data.

• 1008

  The connection closed due to a policy violation.

• 1009

  The connection closed because the frame size exceeded the 4 MB limit.

• 1010

  The connection closed because the client requested a required extension that is not available.

• 1011

  The connection closed because the service encountered an unexpected internal condition that prevents it from fulfilling the request.

• 1015

  The connection was not established due to a TLS handshake error.