JavaScript Library

Before start

You can use Zeroth on any web browser that supports getUserMedia.

In this tutorial, we demonstrate how to use the zeroth-js library.

HTML File

index.html
<!DOCTYPE html>
<html>
<body>
  <div>
    <h2>Zeroth Demo</h2>
    <h3>Record</h3>
    <p>
      <button class='start'>start</button>
      <button class='stop'>stop</button>
    </p>
    <h3>Response</h3>
    <p>
      <span><b>transcript only - </b></span>
      <span class='transcript'></span>
    </p>
    <p>
      <span><b>complete json - </b></span>
      <span class='json'></span>
    </p>
  </div>
  <!-- Import zeroth-js here -->
  <script src='app.js'></script>
</body>
</html>

Importing zeroth-js

  • ZerothBase

    • Basic functions for connecting with Zeroth API and sending data

    • Audio capture functions not included.

  • ZerothMic

    • Extension of ZerothBase for using browser's microphone recording function.

    • Easily enable real-time STT (i.e. transcriptions as the user is talking).

  • ZerothFile

    • Extension of ZerothBase with function for sending recorded audio files.

In this example we will demonstrate usage of ZerothMic.

NPM

npm install goodatlas/zeroth-js

Using this method, you can import zeroth-js as follows:

ES6

import { ZerothMic } from 'zeroth-js';

ES5 - CommonJS

var ZerothMic = require('zeroth-js').ZerothMic

CDN

Include the js file directly in your web app using a<script> tag.

<script src="https://somecdn/zeroth.min.js"></script>

Using this method, you can use zeroth-js as follows:

CDN is not supported for alpha version. Please download zeroth.min.js from here

ES5 - UMD Build

var ZerothMic = Zeroth.ZerothMic

Get Access Token

Using with Server (Secure way, Recommended)

You should add one API endpoint in your server to get accessToken. Please check this page.

REST API

Create GET endpoint named /get-token (whatever you want) in your server. This endpoint will return response of our this REST API.

For example, If you are using node.js, express and axios , Your code will look like below.

const express = require('express');
const axios = require('axios');
const app = express();
​
app.get('/get-token', function (req, res) {
  const url = 'https://zeroth.goodatlas.com:2053/token';
  const opt = {
    headers: {
        Authorization : `$YOUR_APP_ID:$YOUR_APP_SECRET`
      }
    };
  axios.get(url, opt)
    .then(({ data }) => res.send(data['access_token'])) // This will return accessToken to Client
    // Your error handler here
})

⚠️ important you have to replace$YOUR_APP_ID and$YOUR_APP_SECRETwith yours from Zeroth Console. You will have to create new application.

That's all what you need in server side. and You should use accessToken parameter instead of appId, appSecret.

Using without Server (Less secure but simple way)

zeroth-js will issue accessToken based on your appId, appSecret in parameter.

Parameters

Using with Server

Link (Get Access Token > Using with Server)

const params = {
    language: 'kor', // Required. You can choose 'eng' for English or 'kor' for Korean
    accessToken: '$YOUR_ACCESS_TOKEN', // Required. You should get access token from your sever
    finalOnly: false, // Optional(Default: false) If this is 'true', you will get only final results.
    ws: false, // Optional(Default: false) We are using WebSocket Secure (wss). If this is true, we will use 'ws' instead of 'wss'
    debug: true // Optional(Default: false) If this is 'true', you will get all logs from Zeroth.
}

⚠️ important you have to replace $YOUR_ACCESS_TOKEN with access_token what you got from here

Using without Server

Link (Get Access Token > Using without Server)

const params = {
    language: 'kor', // Required. You can choose 'eng' for English or 'kor' for Korean
    appId: '$YOUR_APP_ID', // Required. You can get your appId with create new application in zeroth-console
    appSecret: '$YOUR_APP_SECRET', // Required. You can get your appSecret with create new application in zeroth-console
    finalOnly: false, // Optional(Default: false) If this is 'true', you will get only final results.
    ws: false, // Optional(Default: false) We are using WebSocket Secure (wss). If this is true, we will use 'ws' instead of 'wss'
    debug: true // Optional(Default: false) If this is 'true', you will get all logs from Zeroth.
}

⚠️ important you have to replace$YOUR_APP_ID and$YOUR_APP_SECRETwith yours from Zeroth Console. You will have to create new application.

In this case, zeroth-js will issue accessToken based on your appId, appSecret

Difference between with server, without server

Only difference is using accessToken or using appId and appSecret in parameter.

But we recommend Using with Server way because of security issue.

Initialize Zeroth

Create an app.js file, and import zeroth-js into your directory.

After importing, initialize Zeroth and add the following parameters.

const params = {
    language: 'kor',
    appId: '$YOUR_APP_ID',
    appSecret: '$YOUR_APP_SECRET',
    finalOnly: false,
    ws: false,
    debug: true
}

⚠️ important you have to replace$YOUR_APP_ID and$YOUR_APP_SECRETwith yours from Zeroth Console. You will have to create new application.

In this tutorial, We will using Using without Server way for convenience. If you are using Using with Server way, please replace appId , appSecret parameters with accessToken parameter.

const zeroth = new ZerothMic(params);

That's it! Create an app.js file to start recording.

App.js

app.js
const params = {
    language: 'kor',
    appId: '$YOUR_APP_ID',
    appSecret: '$YOUR_APP_SECRET',
    finalOnly: false,
    ws: false,
    debug: true
}

const zeroth = new ZerothMic(params);

Start recording

Now, you are ready to use Zeroth with the microphone in your browser. To start recording, just call the start() function.

These are Zeroth's event callbacks:

  • onconnect

    • Upon successful connection to Zeroth

    • Add "start audio recording" or "prepare to send audio file" logic in here.

  • ondata

    • Upon getting a result from Zeroth

    • You can get the full JSON result and add logic related to the result here.

  • ondisconnect

    • Upon disconnecting from Zeroth.

    • Add "stop recording" logic in here.

  • onerror

    • When you couldn't connected with Zeroth, or there's some error between Zeroth.

    • Add error handling here.

Now, let's add logic. First, get elements from our html.

const start = document.querySelector('.start'); // Start button
const stop = document.querySelector('.stop'); // Stop button
const transcript = document.querySelector('.transcript'); // Where transcribed text will be shown. 
const json = document.querySelector('.json'); // Where full JSON result will be shown. 
stop.disabled = true; // Stop button is initally disabled.

Create an onSuccess function to add event callbacks to Zeroth. We will use the onSuccess function when start() 's getUserMedia() is successful.

Learn more about getUserMedia() here.

const onSuccess = () => {
  zeroth.onconnect = () => {
    stop.disabled = false; // Turn on stop button
  };

  zeroth.ondata = data => {
    transcript.textContent = data.transcript; // Add only transcribed text to `transcript` element
    json.textContent = JSON.stringify(data); // Add full JSON result to `json` element
  };

  zeroth.ondisconnect = () => {
    start.disabled = false; // Turn on Start button
    zeroth.stop(); // Stop recording
  };

  zeroth.onerror = error => {
    transcript.textContent = 'zeroth error: ' + error; // Add error message to `transcript` element
    zeroth.stop(); // Stop recording
  };
};

Then, add onclickevent to call start() and stop()

start.onclick = () => {
  zeroth.start() // When `Start` button is clicked, try to start recording.
    .then(() => {
        console.log('Successfully initialized recording');
        onSuccess()
        // What to do after recording is initialized
    })
    .catch(() => {
        console.log('Your browser doesn\'t support recording');
        // What to do if recording fails to initialize
    });
};

  stop.onclick = () => {
    zeroth.stop(); // When `Stop` button clicked, stop recording.
  };
};

Full Code example

That's it! You have now successfully made a speech-to-text web application.

You can find more examples here.

index.html
<!DOCTYPE html>
<html>
<body>
  <div>
    <h2>Zeroth Demo</h2>
    <h3>Record</h3>
    <p>
      <button class='start'>start</button>
      <button class='stop'>stop</button>
    </p>
    <h3>Response</h3>
    <p>
      <span><b>transcript only - </b></span>
      <span class='transcript'></span>
    </p>
    <p>
      <span><b>complete json - </b></span>
      <span class='json'></span>
    </p>
  </div>

  <script src='zeroth.min.js'></script><!-- Importing zeroth.min.js -->
  <script src='app.js'></script>
</body>
</html>

⚠️ important you have to replace$YOUR_APP_ID and$YOUR_APP_SECRETwith yours from Zeroth Console. You will have to create new application.

app.js
const start = document.querySelector('.start');
const stop = document.querySelector('.stop');
const transcript = document.querySelector('.transcript');
const json = document.querySelector('.json');
stop.disabled = true;

const params = {
    language: 'kor',
    appId: '$YOUR_APP_ID',
    appSecret: '$YOUR_APP_SECRET',
    finalOnly: false,
    ws: false,
    debug: true
}

const zeroth = new ZerothMic(params);
    
const onError = err => {
  transcript.textContent = 'getUserMedia error: ' + err;
};

const onSuccess = () => {
  zeroth.onconnect = () => {
    start.disabled = true;
    stop.disabled = false;
  };
​
  zeroth.ondata = data => {
    transcript.textContent = data.transcript;
    json.textContent = JSON.stringify(data);
  };
​
  zeroth.ondisconnect = () => {
    start.disabled = false;
    stop.disabled = true;
  };
​
  zeroth.onerror = error => {
    transcript.textContent = 'zeroth error: ' + error; 
    zeroth.stop(); 
  };
};

start.onclick = () => {
  zeroth.start()
    .then(onSuccess)
    .catch(onError);  
  start.disabled = true; // Disable start button
};

stop.onclick = () => {
  zeroth.stop();
  stop.disabled = true;  // Disable Stop button
};

PreviousWebSocket(realtime)NextFAQ

Last updated