{"id":13714,"library":"openai-realtime-api","title":"OpenAI Realtime Voice API Client","description":"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.","status":"active","version":"1.0.8","language":"javascript","source_language":"en","source_url":"https://github.com/transitive-bullshit/openai-realtime-api","tags":["javascript","typescript"],"install":[{"cmd":"npm install openai-realtime-api","lang":"bash","label":"npm"},{"cmd":"yarn add openai-realtime-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add openai-realtime-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is ESM-only and requires Node.js >= 18, so CommonJS `require()` is not supported.","wrong":"const RealtimeClient = require('openai-realtime-api')","symbol":"RealtimeClient","correct":"import { RealtimeClient } from 'openai-realtime-api'"},{"note":"It is best practice to use `import type` for type-only imports like `RealtimeClientOptions` to ensure they are stripped during compilation.","wrong":"import { RealtimeClientOptions } from 'openai-realtime-api'","symbol":"RealtimeClientOptions","correct":"import type { RealtimeClientOptions } from 'openai-realtime-api'"},{"note":"Provides TypeScript definitions for all conversation and API events emitted by the client, enabling strongly-typed event handlers for robustness.","symbol":"RealtimeCustomEvents","correct":"import type { RealtimeCustomEvents } from 'openai-realtime-api'"}],"quickstart":{"code":"import { RealtimeClient } from 'openai-realtime-api';\n\n// Create a new client; apiKey defaults to process.env.OPENAI_API_KEY in Node.js\n// For browser usage, explicitly pass apiKey or use a relay server.\nconst client = new RealtimeClient({\n  apiKey: process.env.OPENAI_API_KEY ?? '', // Required for browser or if env var not set\n  sessionConfig: {\n    instructions: 'You are a great, upbeat friend.',\n    voice: 'alloy'\n  }\n});\n\n// Update session configuration before connecting, for example.\nclient.updateSession({\n  turn_detection: null,\n  input_audio_transcription: { model: 'whisper-1', language: 'en' }\n});\n\n// Example of custom event handling with type safety\nclient.on('conversation.updated', (event) => {\n  const { item, delta } = event; // 'event' is fully-typed\n  console.log('Conversation updated:', item.text);\n});\n\nclient.on('speech.response', (event) => {\n  console.log('API response:', event.text);\n});\n\nasync function runConversation() {\n  try {\n    await client.connect();\n    console.log('Connected to OpenAI Realtime API.');\n\n    // Send an initial message to start the conversation\n    client.sendUserMessageContent('Hello, how are you today?');\n\n    // Keep the client alive for a few seconds to receive responses\n    await new Promise(resolve => setTimeout(resolve, 10000));\n\n    await client.disconnect();\n    console.log('Disconnected.');\n  } catch (error) {\n    console.error('Realtime API error:', error);\n  }\n}\n\nrunConversation();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The `openai-realtime-api` package is ESM-only and explicitly requires Node.js version 18 or higher for server-side environments.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"OpenAI API Key handling behavior differs between Node.js and browser environments, potentially leading to authentication failures.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Direct 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.6"}],"env_vars":null,"search_vec":"'1.0.8':57 '100':79 '18':91 'across':86 'activ':62 'address':43 'aim':117 'api':4,10,28 'applic':134 'browser':92 'bug':45,71 'build':129 'bun':94 'cli':104 'client':5,20 'cloudflar':95 'comprehens':84 'consol':114 'current':53 'demo':115 'deno':93 'depend':74 'develop':63,125 'developer-friend':124 'differenti':77 'direct':31 'drop':35 'drop-in':34 'event':81 'exampl':105 'experi':127 'fix':72 'focus':69 'fork':32 'frequent':66 'friend':126 'handler':83 'implement':52 'includ':78 'inclus':98 'inconsist':47 'interact':22 'javascript':88,137 'key':76 'librari':59 'like':102 'maintain':60 'minor':67 'node.js':90,103 'numer':44 'offer':119 'openai':1,8,24,112,136 'openai-realtime-api':7 'openai/openai-realtime-api-beta':40 'origin':51 'pace':64 'packag':11 'present':48 'project':41 'provid':12 'real':131 'real-tim':130 'realtim':2,9,26,113 'relay':108 'releas':68 'reliabl':122 'replac':37 'robust':14 'runtim':89 'server':109 'simpl':107 'stabl':55 'strong':17 'strongly-typ':16 'support':85 'time':132 'tool':101 'type':18,80 'typescript':19,138 'updat':75 'use':100 'various':87 'version':56 'voic':3,27,133 'worker':96","created_at":"2026-04-20T01:55:55.549822+00:00","updated_at":"2026-04-20T01:55:55.549822+00:00","problems":[{"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.","cause":"Attempting to use CommonJS `require()` syntax to import this ESM-only package.","error":"ERR_REQUIRE_ESM"},{"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' })`.","cause":"The OpenAI API key was not successfully provided to the `RealtimeClient` instance.","error":"Error: Missing OpenAI API Key"},{"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.","cause":"Problems establishing a WebSocket connection, often due to CORS policy, network restrictions, or an incorrect `relayServerUrl`.","error":"WebSocket connection to 'wss://api.openai.com/v1/realtime/speech' failed: (or similar CORS/network error)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/transitive-bullshit/openai-realtime-api","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/openai-realtime-api","openapi_spec":null,"status_page":null,"smithery":null,"categories":["llm-agents","ai-ml","http-networking","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}