Microsoft Translator Speech to Text Service

(Unofficial) NodeJS service wrapper for Microsoft Translator Speech API

npm install ms-translator-speech-service

Installation

1. Install NodeJS on your computer
2. Create a new directory for your code project if you haven't already
3. Open a terminal and run npm install ms-translator-speech-service from your project directory

Usage

You'll first need to create a Microsoft Translator Speech API key. You can do this while logged in to the Azure Portal.

The following code will get you up and running with the essentials:

const translationService = require('ms-translator-speech-service');

const options = {
  subscriptionKey: '<your api key>',
  toLanguage: 'fr',
  fromLanguage: 'en',
  features: {
    partial: false,
    timingInfo: true
  }
};

const translator = new translationService(options);

translator.start((error, service) => {
  if (!error) {
    console.log('translator service started.');
  }
});

See the API section of these docs for details on configuration and methods.

Example

Scenario: translating an existing audio speech file. Remember to check the Translation API docs for details on the audio data format needed.

const translationService = require('ms-translator-speech-service');

// set up and connect to Translator API
const options = {
  subscriptionKey: '<your api key>',
  toLanguage: 'fr',
  fromLanguage: 'en'
};

// create new translator service instance
const translator = new translationService(options);

// start service
translator.start((error, service) => {
  if (error) return console.error(error);

  // listen for incoming translation results
  service.on('message', (message) => {
    const translation = JSON.parse(message.utf8Data);
    console.log(translation);
    translator.stop(_ => console.log('translator stopped.'));
  });

  // send audio file content to translator service
  service.sendFile('/path/to/audio.wav', (error) => {
    if (error) console.log(error);
  });
});

More Examples:

The following additional examples can be found in the examples directory:

• Profanity handling
• Text to Speech

Clone this repo, run npm install and you'll be able to run them.

API Reference

TranslatorService(options)

• options Object
• Returns TranslatorService

Creates a new instance of TranslatorService.

const translator = new translationService(options);

Available options are below:

| name | type | description | default | required | |---------------------------|-----------|----------------------------------------------------------------------------------------------------------|---------|----------| | subscriptionKey | String | your Translator API key | n/a | yes | | fromLanguage | String | the language you want to translate from. See supported languages in the official Microsoft Translator API docs. | 'en' | no | | toLanguage | String | the language you want to translate to. See supported languages in the official Microsoft Translator API docs. | 'en' | no | | correlationId | String | a unique id in order to tie together multiple speech sources when translating. See official Microsoft Translator API docs for more details. | null | no | | features | Object | additional features needed from the API | {} | no | | partial | Boolean | defined under the features option. Returns partial translation results in additional to final results. | false | no | | timingInfo | Boolean | defined under the features option. Returns timing info in translation results. | false | no | | textToSpeech | Boolean | defined under the features option. Returns binary audio messages in addition to text translation messages. | false | no | | profanityAction | String | type of profanity handling you want in the translation results. Choose from Marked, Deleted, or NoAction | Marked | no | | profanityMarker | String | type of profanity marker you want if you have specified profanities to be marked. Choose from Asterisk, or Tag | Asterisk | no | | voice | String | name of the voice you'd like the text to speech to be created with. Must have textToSpeech set to true in features option. See supported voices in the official Microsoft Translator API docs | '' | no | | format | String | file format you'd like the text to speech to be returned as. Choose from audio/wav or audio/mp3 | audio/wav | no |

translator.start(callback)

• callback Function

Connects to the Speech API websocket on your behalf and returns the websocket instance once connected. Callback follows the errorback pattern.

translator.start((error, service) => {
  if (!error) console.log('translator service started.');
});

translator.stop(callback)

• callback Function

Disconnects from the established websocket connection to the Speech API. Callback follows the errorback pattern.

translator.stop((error) => {
  if (!error) console.log('translator service stopped.');
});

service.send(buffer)

• buffer Buffer

Sends an audio payload to the Speech API websocket connection. Audio payload is a native NodeJS Buffer.

See the 'Sending Audio' section of the Translation API docs for details on the data format needed.

service.send(myAudioBufferChunk);

service.sendFile(filepath, callback)

• filepath String
• callback Function (optional)

Streams an audio file from disk to the Speech API websocket connection. Optional callback follows errorback pattern.

See the 'Sending Audio' section of the Translation API docs for details on the data format needed for the audio file.

service.sendFile('/path/to/audiofile.wav', (error) => {
  if (!error) console.log('file sent.');
});

service.on('message', callback)

• callback Function

Event listener for incoming translation message payloads from the Speech API. Message payload is a JSON object.

service.on('message', (message) => {
  console.log(message);
});

/*
 Example text message payload:

 {"type": "utf8", "utf8Data": '{"type":"final","id":"0","recognition":"Hello world","translation":"Hello world"}'}
 
 Example audio binary message (text to speech feature) payload:

 { type: 'binary',
  binaryData: <Buffer 52 49 46 46 86 4c 01 00 57 41 56 45 66 6d 74 20 12 00 00 00 3e ... > }

*/

service.on('close', callback)

• callback Function

Event listener for Speech API websocket connection closures.

service.on('close', () => {
  console.log('Speech API connection closed');
});

service.on('error', callback)

• callback Function

Event listener for incoming Speech API websocket connection errors.

service.on('error', (error) => {
  console.log(error);
});