Microsoft Azure Cognitive Services Speech SDK for JavaScript

Common errors

• CANCELED: Reason=ErrorDetails=<Connection was closed by the remote host. ErrorCode: 1000. ErrorType: ConnectionFailure>

  cause This error typically indicates an issue with the authentication key or region, or network connectivity problems preventing the WebSocket connection to the Azure Speech Service.
  fix Verify that `SPEECH_KEY` and `SPEECH_REGION` are correctly configured and match your Azure resource. Check network connectivity and firewall rules.

• TypeError: Cannot read properties of undefined (reading 'recognizeOnceAsync')

  cause This usually happens when `SpeechRecognizer` (or other SDK classes) is not properly initialized, or the `new` keyword is omitted during instantiation.
  fix Ensure that `new SpeechRecognizer(speechConfig, audioConfig)` is used and that `speechConfig` and `audioConfig` are valid instances.

Warnings

• breaking Speaker recognition and intent recognition support were removed from the SDK. Applications relying on these features must use older versions of the SDK or migrate to alternative services/implementations.
  Fix: If migrating is not an option, pin the SDK version to `1.46.x` or earlier. For new development, avoid using these deprecated features entirely.
• breaking SpeechRecognizer and TranslationRecognizer were updated to use V2 endpoints by default. This change means that `NoMatch` results may no longer be received as they were in previous versions, significantly altering recognition behavior.
  Fix: Review and update application logic that specifically handles `NoMatch` results. The SDK's behavior around partial and final results should be re-evaluated to accommodate this change.
• deprecated The `SpeechServiceConnection_EndSilenceTimeoutMs` property has been deprecated. While it may still function, its use is discouraged and it may be removed in future releases.
  Fix: Migrate to newer properties or methods that control speech segmentation and silence detection. Consult the latest API reference for recommended alternatives.
• gotcha The `FromEndpoint` API is now the recommended method for constructing a `SpeechConfig` for most scenarios, especially when working with `SpeechRecognizer`. While `FromSubscription` still works, `FromEndpoint` offers more flexibility and control.
  Fix: Consider refactoring `SpeechConfig` initialization to use `SpeechConfig.fromEndpoint()` where applicable, especially for advanced scenarios or custom endpoint configurations.

Install

• npm install microsoft-cognitiveservices-speech-sdk npm
• yarn add microsoft-cognitiveservices-speech-sdk yarn
• pnpm add microsoft-cognitiveservices-speech-sdk pnpm

Imports

• SpeechConfig
  wrong:

  const SpeechConfig = require('microsoft-cognitiveservices-speech-sdk');

  correct:

  import { SpeechConfig } from 'microsoft-cognitiveservices-speech-sdk';

  ESM imports are standard. CommonJS `require` can be used in older Node.js projects but is not recommended for new development due to potential bundling or tree-shaking issues.
• SpeechRecognizer
  wrong:

  import SpeechRecognizer from 'microsoft-cognitiveservices-speech-sdk';

  correct:

  import { SpeechRecognizer } from 'microsoft-cognitiveservices-speech-sdk';

  All core SDK classes are named exports, not default exports. Attempting to use a default import will result in `undefined`.
• AudioConfig
  wrong:

  import { audioConfig } from 'microsoft-cognitiveservices-speech-sdk';

  correct:

  import { AudioConfig } from 'microsoft-cognitiveservices-speech-sdk';

  Class names are PascalCase. Using camelCase for named imports will cause a 'module has no exported member' error.

Quickstart

Demonstrates basic speech-to-text recognition from microphone input, showing how to configure the SDK, listen for speech, and process the recognized text or cancellation events.

import { SpeechConfig, AudioConfig, SpeechRecognizer, ResultReason } from 'microsoft-cognitiveservices-speech-sdk';

const speechKey: string = process.env.SPEECH_KEY ?? '';
const speechRegion: string = process.env.SPEECH_REGION ?? '';

async function recognizeFromMicrophone(): Promise<void> {
    if (!speechKey || !speechRegion) {
        console.error('Please set the SPEECH_KEY and SPEECH_REGION environment variables.');
        return;
    }

    const speechConfig = SpeechConfig.fromSubscription(speechKey, speechRegion);
    speechConfig.speechRecognitionLanguage = 'en-US';

    const audioConfig = AudioConfig.fromDefaultMicrophoneInput();
    const recognizer = new SpeechRecognizer(speechConfig, audioConfig);

    console.log('Say something into your microphone...');

    recognizer.recognizeOnceAsync(result => {
        switch (result.reason) {
            case ResultReason.RecognizedSpeech:
                console.log(`RECOGNIZED: Text=${result.text}`);
                break;
            case ResultReason.NoMatch:
                console.log('NOMATCH: Speech could not be recognized.');
                break;
            case ResultReason.Canceled:
                const cancellationDetails = result.cancellationDetails;
                console.log(`CANCELED: Reason=${cancellationDetails?.reason}`);
                if (cancellationDetails?.errorDetails) {
                    console.log(`CANCELED: ErrorDetails=${cancellationDetails.errorDetails}`);
                }
                break;
        }
    });
}

recognizeFromMicrophone();