Registry / llm-agents / ultravox-client

ultravox-client

JSON →
library0.1.0jsnpmunverified

The `ultravox-client` library provides a web client SDK for integrating Ultravox's real-time, speech-to-speech AI capabilities into web applications. Written in TypeScript, it offers an event-driven API for managing interactive voice sessions. The current stable version is 0.5.0, indicating it is still in active development with potential for API changes in future minor releases. It enables developers to join AI-powered calls, listen for session status changes, and receive real-time speech transcripts from both users and AI agents. Key differentiators include its focus on low-latency, real-time voice interaction and its comprehensive event model for managing session state and data flow within a web browser environment, abstracting away the underlying WebSocket complexities.

npm install ultravox-client
INSTALL
IMPORT
SIG · ULTRAVOX-CLIENT
U
ultravox-client
llm-agentsjavascriptv0.1.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

UltravoxSession
import { UltravoxSession } from 'ultravox-client';
const { UltravoxSession } = require('ultravox-client');
This library is primarily designed for modern web environments and uses ES Modules. CommonJS `require` is not the intended way to import.
UltravoxSessionStatus
import { UltravoxSessionStatus } from 'ultravox-client';
import UltravoxSessionStatus from 'ultravox-client';
UltravoxSessionStatus is an enum used for session state; ensure it's imported as a named export.
UltravoxSession (Type)
import type { UltravoxSession } from 'ultravox-client';
For TypeScript projects, use `import type` when only importing the type definition for better tree-shaking and build performance.

This quickstart initializes an `UltravoxSession`, sets up event listeners for session status changes and real-time transcript updates, and attempts to connect to an Ultravox AI call using a provided WebSocket URL. It demonstrates how to monitor the call's state, process incoming speech-to-text data, and manage the session lifecycle within a web application.

import { UltravoxSession } from 'ultravox-client'; // In a real application, replace this with a URL obtained securely from your backend // which generates it via the Ultravox API. Do NOT hardcode or expose API keys. const ULTRAVOX_JOIN_URL = 'wss://your-call-join-url'; // Placeholder for demonstration const session = new UltravoxSession(); session.addEventListener('status', (event) => { console.log('Session status changed: ', session.status); if (session.status === 'disconnected') { console.log('Ultravox session disconnected. Attempting to reconnect if desired.'); } else if (session.status === 'listening') { console.log('Ultravox is now listening for your voice input. Speak freely!'); } else if (session.status === 'speaking') { console.log('Ultravox AI is responding...'); } }); session.addEventListener('transcripts', (event) => { // `session.transcripts` is an array of all received transcripts. // This event fires for both partial and final transcripts. const currentTranscripts = session.transcripts; console.log('Current transcripts: ', currentTranscripts); // Example: Find and log the latest final transcript const lastFinalTranscript = currentTranscripts.findLast(t => t.isFinal); if (lastFinalTranscript) { console.log(`[${lastFinalTranscript.speaker}]: ${lastFinalTranscript.text}`); } }); async function startUltravoxSession() { try { console.log('Attempting to join Ultravox call at:', ULTRAVOX_JOIN_URL); await session.joinCall(ULTRAVOX_JOIN_URL); console.log('Successfully joined Ultravox call. Waiting for initial status...'); } catch (error) { console.error("Failed to join call, ensure URL is valid and network is available:", error); } } startUltravoxSession(); // Example: To leave the call after some user interaction or timeout // setTimeout(() => { // console.log('Leaving Ultravox call after a demonstration period...'); // session.leaveCall(); // }, 60000); // Automatically leave after 60 seconds
Debug
Known issues
breakingAs the package is currently in an early development stage (version 0.5.0), the API is subject to breaking changes in minor versions. Developers should pin exact versions and review release notes carefully when upgrading.
fix
Refer to the official Ultravox documentation and changelog for specific breaking changes when upgrading to new minor versions. Consider using a version lock (`~0.x.y` instead of `^0.x.y`) in your `package.json` for stability.
affects: <1.0.0
gotchaWhen developing or building the `ultravox-client` SDK itself, a build error 'Missing version.js file' might occur. This indicates an issue with the build tooling not generating the version file prior to compilation.
fix
Execute `pnpm publish --dry-run --git-checks=false` in the SDK's root directory. This command often triggers the necessary pre-publish scripts that generate the `version.js` file, resolving the build dependency.
affects: >=0.1.0
gotchaThe `UltravoxSession.joinCall()` method requires a WebSocket URL that must be generated by the Ultravox API (typically from a backend server). This URL is not static and cannot be created directly within the client-side application.
fix
Implement a backend service that interacts with the Ultravox API to securely generate and provide the `joinCall` URL to your web client. Do not embed API keys directly in client-side code.
affects: >=0.1.0
Errors
Common errors & fixes
Error: Missing version.js file
The build process for the Ultravox Client SDK failed to locate or generate the `version.js` file, which is required for package metadata.
fix
Navigate to the SDK's root directory and run `pnpm publish --dry-run --git-checks=false`. This command should trigger the necessary pre-publish hooks that generate `version.js`.
WebSocket connection failed: Error during WebSocket handshake: Unexpected response code: 403
The WebSocket server rejected the connection request, often due to an invalid or expired `joinCall` URL, or incorrect authentication/authorization.
fix
Verify that the `joinCall` URL passed to `session.joinCall()` is current, valid, and correctly generated by your backend using the Ultravox API. Ensure your server-side logic handles token expiry and renewal correctly.
TypeError: Failed to construct 'WebSocket': The URL 'invalid-url' is invalid.
The URL provided to `session.joinCall()` is not a valid WebSocket (ws:// or wss://) URL format.
fix
Ensure the URL passed to `session.joinCall()` is a properly formatted WebSocket URL, starting with `ws://` or `wss://`, and that it resolves to an accessible endpoint.
Upgrade
Version history
0.1.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
40 hits · last 30 days
node
34
OpenAI (training)
1
Resources
ultravox-client — npm install ultravox-client · libregistry