Getting started

Include the library

Since we are still in an early phase of the library development, the package is not published to NPM yet. You must download and install it with:

npm install --no-cache /path/to/allomedia-uhlive-0.12.0.tgz

For now, the JavaScript SDK is compatible with Chrome-based browsers and Firefox. Support for other browsers and Node.js will come later.


Quick start

The simpliest way to get started is to create the two following files:

  • index.html:
<!DOCTYPE html>
<html>
<head>
<script type="module" src="main.js"></script>
</head>
<body>
<div id="uhlive"></div>
</body>
</html>
  • main.js:
import { Uhlive } from "@allomedia/uhlive";
const uhlive = new Uhlive("YOUR-IDENTIFIER", "YOUR-TOKEN");
uhlive.connect().join("my-conversation-id");

With this setup, you'll be able to see the transcription in the <div id="uhlive"></div> wrapper.

If we want to specify a speaker identifier, and display only final segments, we'd do:

import { Uhlive } from "@allomedia/uhlive";
const uhlive = new Uhlive("YOUR-IDENTIFIER", "YOUR-TOKEN");
uhlive.connect().join("my-conversation-id", {
ignoreEvents: ["WordsDecoded"];
speaker: "john",
});

Check the join method options for the list of all possible parameters.


API usage

Connect to the server

Don't forget to change YOUR-IDENTIFIER and YOUR-TOKEN by your owns.

import { Uhlive } from "@allomedia/uhlive";

// Set with your own identifier and token
const uhlive = new Uhlive("YOUR-IDENTIFIER", "YOUR-TOKEN");
uhlive.connect();

Check the connect() API reference.


Join a conversation

With a single connection, you can join several conversations. Think of a conversation as a conference call instance, or a room on a chat service. Only people who have joined the conversation can access the exchanged data.

const conversation = uhlive.join("my-conversation-id");

The join() method also takes an optionnal options parameter. Here is an example:

const conversation = uhlive.join("my-conversation-id", {
speaker: "my-speaker-id",
model: "fr",
interim_results: false,
rescoring: true
});

If you want to disable the automatic display of the transcript in the wrapper, set the wrapper property to an empty string or null value.

You can read more about ASR parameters here.

There is no verification on our side of the uniqueness of the speakers id you provide. If you expect it to be unique, you must manage it on your side.


Send audio

We currently only support getting audio from the microphone. This is done automatically by joining a conversation, and will ask to access your microphone.

// This will ask the permission to access your microphone
uhlive.join("my-conversion-id");

Receive transcription

To receive the transcript of the streamed audio, you must subscribe to the words_decoded or/and segment_decoded events, which will pass the payload to your callback function.

Note that this is not needed by default, because Uhlive-js will populate the wrapper defined in the Conversation.join method ("uhlive" by default). You need to use these methods if you want to perform custom actions on words/segments decoded.

The words_decoded event is triggered when the backend sends an interim transcript. Following words_decoded events for the same audio are susceptible to be different, until a final transcript is sent with the segment_decoded event.

conversation.onWordsDecoded((payload) => {
// Do something with `payload`
});

conversation.onSegmentDecoded((payload) => {
// Do something with `payload`
});

Alternatively, you can use the following syntax:

uhlive
.join("my-conversation-id")
.onWordsDecoded((payload) => {
// Do something with `payload`
})
.onSegmentDecoded((payload) => {
// Do something with `payload`
});

Get notified when a speaker leave the conversation

It can be interesting to execute an action when a speaker leave the conversation. This can be done with the speaker_left event, as follow:

uhlive.onSpeakerLeft((speakerId) => {
// Do something with `speakerId`
});

Leave a conversation

conversation.leave();
// or
uhlive.leave("my-conversation-id");
// your can also leave all the conversations at once
uhlive.leaveAllConversations();

Disconnect from the server

uhlive.disconnect();

Enrich events

You can read a description of what Enrich events are here.

You don't need to listen to these events if you use the wrapper option (which is enabled by default). Those events are useful only if you want to perform custom actions on Enrich events.


Listen for number found event

const uhlive = new Uhlive("my-token");
const myConversation = uhlive.join("my-conversation");
myConversation.onEntityNumberFound((entity) => {
// Do something with `entity`...
});

Listen for ordinal found event

const uhlive = new Uhlive("my-token");
const myConversation = uhlive.join("my-conversation");
myConversation.onEntityOrdinalFound((entity) => {
// Do something with `entity`...
});

There you go! You are now able to send an audio and receive its transcription.

To dive in deeper, you can browse the API Reference documentation.

If you are stuck, want to suggest something, or just want to say hello, send us an e-mail to support@allo-media.fr.