Registry / llm-agents / openai-realtime-api

openai-realtime-api

JSON →
library1.0.8jsnpmunverified

The `openai-realtime-api` package provides a robust and strongly-typed TypeScript client for interacting with OpenAI's realtime voice API. As a direct fork and drop-in replacement for the `openai/openai-realtime-api-beta` project, it addresses numerous bugs and inconsistencies present in the original implementation. Currently at stable version `1.0.8`, the library maintains an active development pace with frequent minor releases focused on bug fixes and dependency updates. Key differentiators include 100% typed events and handlers, comprehensive support across various JavaScript runtimes (Node.js >= 18, browsers, Deno, Bun, Cloudflare Workers), and inclusion of useful tools like Node.js CLI examples, a simple relay server, and an OpenAI Realtime Console demo. It aims to offer a more reliable and developer-friendly experience for building real-time voice applications with OpenAI.

npm install openai-realtime-api
INSTALL
IMPORT
SIG · OPENAI-REALTIME-AP
O
openai-realtime-api
llm-agentsjavascriptv1.0.8
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.

RealtimeClient
import { RealtimeClient } from 'openai-realtime-api'
const RealtimeClient = require('openai-realtime-api')
This package is ESM-only and requires Node.js >= 18, so CommonJS `require()` is not supported.
RealtimeClientOptions
import type { RealtimeClientOptions } from 'openai-realtime-api'
import { RealtimeClientOptions } from 'openai-realtime-api'
It is best practice to use `import type` for type-only imports like `RealtimeClientOptions` to ensure they are stripped during compilation.
RealtimeCustomEvents
import type { RealtimeCustomEvents } from 'openai-realtime-api'
Provides TypeScript definitions for all conversation and API events emitted by the client, enabling strongly-typed event handlers for robustness.

This quickstart demonstrates initializing the `RealtimeClient`, configuring a session, attaching event listeners for conversation updates and speech responses, connecting to the OpenAI API, sending a user message, and handling disconnections. It highlights TypeScript usage and API key management.

import { RealtimeClient } from 'openai-realtime-api'; // Create a new client; apiKey defaults to process.env.OPENAI_API_KEY in Node.js // For browser usage, explicitly pass apiKey or use a relay server. const client = new RealtimeClient({ apiKey: process.env.OPENAI_API_KEY ?? '', // Required for browser or if env var not set sessionConfig: { instructions: 'You are a great, upbeat friend.', voice: 'alloy' } }); // Update session configuration before connecting, for example. client.updateSession({ turn_detection: null, input_audio_transcription: { model: 'whisper-1', language: 'en' } }); // Example of custom event handling with type safety client.on('conversation.updated', (event) => { const { item, delta } = event; // 'event' is fully-typed console.log('Conversation updated:', item.text); }); client.on('speech.response', (event) => { console.log('API response:', event.text); }); async function runConversation() { try { await client.connect(); console.log('Connected to OpenAI Realtime API.'); // Send an initial message to start the conversation client.sendUserMessageContent('Hello, how are you today?'); // Keep the client alive for a few seconds to receive responses await new Promise(resolve => setTimeout(resolve, 10000)); await client.disconnect(); console.log('Disconnected.'); } catch (error) { console.error('Realtime API error:', error); } } runConversation();
Debug
Known issues
breakingThe `openai-realtime-api` package is ESM-only and explicitly requires Node.js version 18 or higher for server-side environments.
fix
Ensure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json` or `.mjs` file extensions) and that your Node.js runtime is version 18 or newer. Replace all CommonJS `require()` calls with ES Module `import` statements.
affects: >=1.0.0
gotchaOpenAI API Key handling behavior differs between Node.js and browser environments, potentially leading to authentication failures.
fix
In Node.js, the `OPENAI_API_KEY` environment variable is automatically detected. For browser environments, or if the environment variable is not set, you must explicitly pass the `apiKey` string in the `RealtimeClientOptions` during client initialization.
affects: >=1.0.0
gotchaDirect browser connections to the OpenAI Realtime API may encounter CORS restrictions or expose your API key. The library provides support for a relay server to mitigate these issues.
fix
For production browser deployments, it is highly recommended to deploy and utilize the included relay server (as detailed in the package's README). Configure the `RealtimeClient` with the `relayServerUrl` option to proxy requests and secure your OpenAI API key.
affects: >=1.0.0
gotchaWhen providing `input_audio_transcription` options without a specified `frequency`, the client will automatically apply a default frequency value, which may not align with specific audio input requirements.
fix
If your application requires a precise audio transcription frequency, ensure it is explicitly set within the `sessionConfig.input_audio_transcription.frequency` property when initializing or updating the client's session configuration.
affects: >=1.0.6
Errors
Common errors & fixes
ERR_REQUIRE_ESM
Attempting to use CommonJS `require()` syntax to import this ESM-only package.
fix
Update your project to use ES Module `import` statements. If in Node.js, ensure your `package.json` contains `"type": "module"` or use `.mjs` file extensions for your source files.
Error: Missing OpenAI API Key
The OpenAI API key was not successfully provided to the `RealtimeClient` instance.
fix
For Node.js, ensure `process.env.OPENAI_API_KEY` is set. For browser clients or explicit control, pass the `apiKey` directly as an option: `new RealtimeClient({ apiKey: 'YOUR_API_KEY' })`.
WebSocket connection to 'wss://api.openai.com/v1/realtime/speech' failed: (or similar CORS/network error)
Problems establishing a WebSocket connection, often due to CORS policy, network restrictions, or an incorrect `relayServerUrl`.
fix
Verify network connectivity and firewall settings. For browser environments, check browser developer console for CORS errors; if present, implement and configure the `relayServerUrl` option with your proxy server.
Upgrade
Version history
1.0.8latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
14 hits · last 30 days
node
12
Amazon
1
OpenAI (training)
1
Resources
openai-realtime-api — npm install openai-realtime-api · libregistry