EVI TypeScript Quickstart

A quickstart guide for integrating the Empathic Voice Interface (EVI) with TypeScript.

EVI TypeScript Quickstart

A quickstart guide for integrating the Empathic Voice Interface (EVI) with TypeScript.

In this guide, you’ll learn how to integrate EVI into your TypeScript applications using Hume’s TypeScript SDK.

Installation: Install the hume package.
Authentication: Instantiate the Hume client using your API credentials.
Connection: Initialize a WebSocket connection to interact with EVI.
Audio capture: Capture and stream audio input.
Audio playback: Play back EVI’s streamed audio output.
Interruption: Handle user interruptions client-side.

Looking for sample code?

See the complete implementation of this guide on GitHub

TypeScript SDK

Explore or contribute to Hume’s TypeScript SDK on GitHub

This guide primarily targets web browser implementations. For non-browser environments (e.g., Node.js), audio capture and playback implementation will vary based on your runtime context.

Installation

Install the Hume TypeScript SDK package.

pnpm

npm

yarn

bun

1 pnpm i hume

Authentication

Instantiate the Hume client with your API credentials to authenticate. Visit our Getting your API keys page for details on how to obtain your credentials.

This example uses direct API key authentication for simplicity. For production browser environments, implement the Token authentication strategy instead to prevent exposing your API key to the client.

Load API keys from environment variables. Avoid hardcoding them in your code to prevent credential leaks and unauthorized access.

Initialize Hume client with credentials

1 import { Hume, HumeClient } from 'hume';
2 
3 const client = new HumeClient({
4   apiKey: HUME_API_KEY, // Load from environment variables
5 });

Connection

With the Hume client instantiated, establish an authenticated WebSocket connection using the client’s empathicVoice.chat.connect method, and assign WebSocket event handlers.

Establish a connection with EVI

1 import type { SubscribeEvent } from "hume/api/resources/empathicVoice/resources/chat";
2 import type { CloseEvent } from "hume/core/websocket/events";
3 
4 const socket = await client.empathicVoice.chat.connect({
5   configId: HUME_CONFIG_ID, // optional
6 });
7 
8 // Placeholder event handlers to be updated in later steps
9 function handleOpen() {}
10 function handleMessage(msg: SubscribeEvent) {}
11 function handleError(err: Event | Error) {}
12 function handleClose(e: CloseEvent) {}
13 
14 socket.on('open', handleOpen);
15 socket.on('message', handleMessage);
16 socket.on('error', handleError);
17 socket.on('close', handleClose);

Audio capture

Capture audio input from the user’s microphone and stream it to EVI over the WebSocket:

Request microphone access from the user.
Obtain the audio stream using the MediaStream API.
Record audio chunks using the MediaRecorder API.
Encode each audio chunk in base64.
Stream encoded audio to EVI by sending audio_input messages to Hume over WebSocket using the SDK’s sendAudioInput method.

Audio capture logic

1 import {
2   convertBlobToBase64,
3   ensureSingleValidAudioTrack,
4   getAudioStream,
5   getBrowserSupportedMimeType,
6 } from 'hume';
7 
8 let recorder: MediaRecorder | null = null;
9 
10 async function startAudioCapture(
11   socket: ChatSocket,
12   timeSliceMs = 80
13 ): Promise<MediaRecorder> {
14   const mimeTypeResult = getBrowserSupportedMimeType();
15   const mimeType = mimeTypeResult.success
16     ? mimeTypeResult.mimeType
17     : MimeType.WEBM;
18 
19   const micAudioStream = await getAudioStream();
20   ensureSingleValidAudioTrack(micAudioStream);
21 
22   const recorder = new MediaRecorder(micAudioStream, { mimeType });
23   recorder.ondataavailable = async (e: BlobEvent) => {
24     if (e.data.size > 0 && socket.readyState === WebSocket.OPEN) {
25       const data = await convertBlobToBase64(e.data);
26       socket.sendAudioInput({ data });
27     }
28   };
29   recorder.onerror = (e) => console.error("MediaRecorder error:", e);
30   recorder.start(timeSliceMs);
31 
32   return recorder;
33 }

Accepted audio formats include: mp3, wav, aac, ogg, flac, webm, avr, cdda, cvs/vms, aiff, au, amr, mp2, mp4, ac3, avi, wmv, mpeg, ircam.

Invoke the startAudioCapture function within handleOpen to start streaming audio once a connection is established:

Start audio capture on open

1 async function handleOpen() {
2   console.log("Socket opened");
3   recorder = await startAudioCapture(socket!);
4 }

Update your handleClose function to ensure audio capture stops appropriately on disconnect:

Stop audio capture on close

1 function handleClose(e: CloseEvent) {
2   console.log("Socket closed:", e);
3   recorder?.stream.getTracks().forEach((t) => t.stop());
4   recorder = null;
5 }

Audio playback

Handle playback of audio responses from EVI using the Hume TypeScript SDK’s EVIWebAudioPlayer.

Initialize the audio player when the WebSocket connection opens.
Queue audio responses received from EVI for playback.
Dispose of the audio player when the WebSocket connection closes to release resources.

After starting audio capture, initialize the player within handleOpen.

Initialize player on open

1 import { EVIWebAudioPlayer } from "hume";
2 
3 let player = new EVIWebAudioPlayer();
4 
5 async function handleOpen() {
6   console.log("Socket opened");
7   recorder = await startAudioCapture(socket!);
8   await player.init();
9 }

Update handleMessage to enqueue received audio responses for playback:

Enqueue EVI response audio for playback

1 import type { SubscribeEvent } from "hume/api/resources/empathicVoice/resources/chat";
2 
3 // Define a WebSocket message event handler to play audio output
4 async function handleMessage(msg: SubscribeEvent) {
5   switch (msg.type) {
6     case 'audio_output':
7       await player.enqueue(msg);
8       break;
9   }
10 }

Update handleClose to dispose of the audio player when the WebSocket disconnects:

Dispose player on close

1 function handleClose(e: CloseEvent) {
2   console.log("Socket closed:", e);
3   recorder?.stream.getTracks().forEach((t) => t.stop());
4   recorder = null;
5   player?.dispose();
6 }

Interruption

When an interruption is detected, EVI will immediately stop sending further response messages and wait for the user’s new input.

The client must then explicitly handle the interruption by stopping ongoing audio playback.

To stop audio playback on user interruption, update handleMessage to invoke EVIWebAudioPlayer.stop when you receive a user_interruption message:

Stop playback on interruption

1 function handleMessage(msg: SubscribeEvent) {
2   switch (message.type) {
3     case 'audio_output':
4       await player.enqueue(msg);
5       break;
6     case 'user_interruption':
7       player.stop();
8       break;
9   }
10 }

Next steps

Congratulations! You’ve successfully implemented a real-time conversational application using Hume’s Empathic Voice Interface (EVI). In this quickstart, you’ve learned the core aspects of authentication, WebSocket communication, audio streaming, playback handling, and interruption management.

Next, consider exploring these areas to enhance your EVI application:

Configure EVI

See detailed instructions on how you can customize EVI for your application needs.

Chat History

Learn how you can access and manage conversation transcripts and expression measures.

For further details and practical examples, explore the API Reference and our Hume API Examples on GitHub.

In this guide, you’ll learn how to integrate EVI into your TypeScript applications using Hume’s TypeScript SDK.

Installation: Install the hume package.
Authentication: Instantiate the Hume client using your API credentials.
Connection: Initialize a WebSocket connection to interact with EVI.
Audio capture: Capture and stream audio input.
Audio playback: Play back EVI’s streamed audio output.
Interruption: Handle user interruptions client-side.

Looking for sample code?

See the complete implementation of this guide on GitHub

TypeScript SDK

Explore or contribute to Hume’s TypeScript SDK on GitHub

This guide primarily targets web browser implementations. For non-browser environments (e.g., Node.js), audio capture and playback implementation will vary based on your runtime context.

Installation

Install the Hume TypeScript SDK package.

pnpm

npm

yarn

bun

1 pnpm i hume

Authentication

Instantiate the Hume client with your API credentials to authenticate. Visit our Getting your API keys page for details on how to obtain your credentials.

Load API keys from environment variables. Avoid hardcoding them in your code to prevent credential leaks and unauthorized access.

Initialize Hume client with credentials

1 import { Hume, HumeClient } from 'hume';
2 
3 const client = new HumeClient({
4   apiKey: HUME_API_KEY, // Load from environment variables
5 });

Connection

With the Hume client instantiated, establish an authenticated WebSocket connection using the client’s empathicVoice.chat.connect method, and assign WebSocket event handlers.

Establish a connection with EVI

1 import type { SubscribeEvent } from "hume/api/resources/empathicVoice/resources/chat";
2 import type { CloseEvent } from "hume/core/websocket/events";
3 
4 const socket = await client.empathicVoice.chat.connect({
5   configId: HUME_CONFIG_ID, // optional
6 });
7 
8 // Placeholder event handlers to be updated in later steps
9 function handleOpen() {}
10 function handleMessage(msg: SubscribeEvent) {}
11 function handleError(err: Event | Error) {}
12 function handleClose(e: CloseEvent) {}
13 
14 socket.on('open', handleOpen);
15 socket.on('message', handleMessage);
16 socket.on('error', handleError);
17 socket.on('close', handleClose);

Audio capture

Capture audio input from the user’s microphone and stream it to EVI over the WebSocket:

Request microphone access from the user.
Obtain the audio stream using the MediaStream API.
Record audio chunks using the MediaRecorder API.
Encode each audio chunk in base64.
Stream encoded audio to EVI by sending audio_input messages to Hume over WebSocket using the SDK’s sendAudioInput method.

Audio capture logic

1 import {
2   convertBlobToBase64,
3   ensureSingleValidAudioTrack,
4   getAudioStream,
5   getBrowserSupportedMimeType,
6 } from 'hume';
7 
8 let recorder: MediaRecorder | null = null;
9 
10 async function startAudioCapture(
11   socket: ChatSocket,
12   timeSliceMs = 80
13 ): Promise<MediaRecorder> {
14   const mimeTypeResult = getBrowserSupportedMimeType();
15   const mimeType = mimeTypeResult.success
16     ? mimeTypeResult.mimeType
17     : MimeType.WEBM;
18 
19   const micAudioStream = await getAudioStream();
20   ensureSingleValidAudioTrack(micAudioStream);
21 
22   const recorder = new MediaRecorder(micAudioStream, { mimeType });
23   recorder.ondataavailable = async (e: BlobEvent) => {
24     if (e.data.size > 0 && socket.readyState === WebSocket.OPEN) {
25       const data = await convertBlobToBase64(e.data);
26       socket.sendAudioInput({ data });
27     }
28   };
29   recorder.onerror = (e) => console.error("MediaRecorder error:", e);
30   recorder.start(timeSliceMs);
31 
32   return recorder;
33 }

Accepted audio formats include: mp3, wav, aac, ogg, flac, webm, avr, cdda, cvs/vms, aiff, au, amr, mp2, mp4, ac3, avi, wmv, mpeg, ircam.

Invoke the startAudioCapture function within handleOpen to start streaming audio once a connection is established:

Start audio capture on open

1 async function handleOpen() {
2   console.log("Socket opened");
3   recorder = await startAudioCapture(socket!);
4 }

Update your handleClose function to ensure audio capture stops appropriately on disconnect:

Stop audio capture on close

1 function handleClose(e: CloseEvent) {
2   console.log("Socket closed:", e);
3   recorder?.stream.getTracks().forEach((t) => t.stop());
4   recorder = null;
5 }

Audio playback

Handle playback of audio responses from EVI using the Hume TypeScript SDK’s EVIWebAudioPlayer.

Initialize the audio player when the WebSocket connection opens.
Queue audio responses received from EVI for playback.
Dispose of the audio player when the WebSocket connection closes to release resources.

After starting audio capture, initialize the player within handleOpen.

Initialize player on open

1 import { EVIWebAudioPlayer } from "hume";
2 
3 let player = new EVIWebAudioPlayer();
4 
5 async function handleOpen() {
6   console.log("Socket opened");
7   recorder = await startAudioCapture(socket!);
8   await player.init();
9 }

Update handleMessage to enqueue received audio responses for playback:

Enqueue EVI response audio for playback

1 import type { SubscribeEvent } from "hume/api/resources/empathicVoice/resources/chat";
2 
3 // Define a WebSocket message event handler to play audio output
4 async function handleMessage(msg: SubscribeEvent) {
5   switch (msg.type) {
6     case 'audio_output':
7       await player.enqueue(msg);
8       break;
9   }
10 }

Update handleClose to dispose of the audio player when the WebSocket disconnects:

Dispose player on close

1 function handleClose(e: CloseEvent) {
2   console.log("Socket closed:", e);
3   recorder?.stream.getTracks().forEach((t) => t.stop());
4   recorder = null;
5   player?.dispose();
6 }

Interruption

When an interruption is detected, EVI will immediately stop sending further response messages and wait for the user’s new input.

The client must then explicitly handle the interruption by stopping ongoing audio playback.

To stop audio playback on user interruption, update handleMessage to invoke EVIWebAudioPlayer.stop when you receive a user_interruption message:

Stop playback on interruption

1 function handleMessage(msg: SubscribeEvent) {
2   switch (message.type) {
3     case 'audio_output':
4       await player.enqueue(msg);
5       break;
6     case 'user_interruption':
7       player.stop();
8       break;
9   }
10 }

Next steps

Next, consider exploring these areas to enhance your EVI application:

Configure EVI

See detailed instructions on how you can customize EVI for your application needs.

Chat History

Learn how you can access and manage conversation transcripts and expression measures.

For further details and practical examples, explore the API Reference and our Hume API Examples on GitHub.

1	import { Hume, HumeClient } from 'hume';
2
3	const client = new HumeClient({
4	apiKey: HUME_API_KEY, // Load from environment variables
5	});

1	import type { SubscribeEvent } from "hume/api/resources/empathicVoice/resources/chat";
2	import type { CloseEvent } from "hume/core/websocket/events";
3
4	const socket = await client.empathicVoice.chat.connect({
5	configId: HUME_CONFIG_ID, // optional
6	});
7
8	// Placeholder event handlers to be updated in later steps
9	function handleOpen() {}
10	function handleMessage(msg: SubscribeEvent) {}
11	function handleError(err: Event \| Error) {}
12	function handleClose(e: CloseEvent) {}
13
14	socket.on('open', handleOpen);
15	socket.on('message', handleMessage);
16	socket.on('error', handleError);
17	socket.on('close', handleClose);

1	import {
2	convertBlobToBase64,
3	ensureSingleValidAudioTrack,
4	getAudioStream,
5	getBrowserSupportedMimeType,
6	} from 'hume';
7
8	let recorder: MediaRecorder \| null = null;
9
10	async function startAudioCapture(
11	socket: ChatSocket,
12	timeSliceMs = 80
13	): Promise<MediaRecorder> {
14	const mimeTypeResult = getBrowserSupportedMimeType();
15	const mimeType = mimeTypeResult.success
16	? mimeTypeResult.mimeType
17	: MimeType.WEBM;
18
19	const micAudioStream = await getAudioStream();
20	ensureSingleValidAudioTrack(micAudioStream);
21
22	const recorder = new MediaRecorder(micAudioStream, { mimeType });
23	recorder.ondataavailable = async (e: BlobEvent) => {
24	if (e.data.size > 0 && socket.readyState === WebSocket.OPEN) {
25	const data = await convertBlobToBase64(e.data);
26	socket.sendAudioInput({ data });
27	}
28	};
29	recorder.onerror = (e) => console.error("MediaRecorder error:", e);
30	recorder.start(timeSliceMs);
31
32	return recorder;
33	}

1	async function handleOpen() {
2	console.log("Socket opened");
3	recorder = await startAudioCapture(socket!);
4	}

1	function handleClose(e: CloseEvent) {
2	console.log("Socket closed:", e);
3	recorder?.stream.getTracks().forEach((t) => t.stop());
4	recorder = null;
5	}

1	import { EVIWebAudioPlayer } from "hume";
2
3	let player = new EVIWebAudioPlayer();
4
5	async function handleOpen() {
6	console.log("Socket opened");
7	recorder = await startAudioCapture(socket!);
8	await player.init();
9	}

1	import type { SubscribeEvent } from "hume/api/resources/empathicVoice/resources/chat";
2
3	// Define a WebSocket message event handler to play audio output
4	async function handleMessage(msg: SubscribeEvent) {
5	switch (msg.type) {
6	case 'audio_output':
7	await player.enqueue(msg);
8	break;
9	}
10	}

1	function handleMessage(msg: SubscribeEvent) {
2	switch (message.type) {
3	case 'audio_output':
4	await player.enqueue(msg);
5	break;
6	case 'user_interruption':
7	player.stop();
8	break;
9	}
10	}