{"id":17707911,"url":"https://github.com/transitive-bullshit/openai-realtime-api","last_synced_at":"2025-08-29T22:13:35.330Z","repository":{"id":258131031,"uuid":"872792801","full_name":"transitive-bullshit/openai-realtime-api","owner":"transitive-bullshit","description":"TypeScript client for OpenAI's realtime voice API.","archived":false,"fork":false,"pushed_at":"2025-07-18T18:23:52.000Z","size":1555,"stargazers_count":349,"open_issues_count":5,"forks_count":32,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-08-09T12:45:48.567Z","etag":null,"topics":["openai","realtime","voice"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/transitive-bullshit.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":".github/funding.yml","license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["transitive-bullshit"]}},"created_at":"2024-10-15T04:50:21.000Z","updated_at":"2025-07-18T18:23:56.000Z","dependencies_parsed_at":"2025-07-18T20:26:02.984Z","dependency_job_id":"ecfa3368-3e29-42bf-9b51-c4b2cd66e990","html_url":"https://github.com/transitive-bullshit/openai-realtime-api","commit_stats":null,"previous_names":["transitive-bullshit/openai-realtime-api"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/transitive-bullshit/openai-realtime-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transitive-bullshit%2Fopenai-realtime-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transitive-bullshit%2Fopenai-realtime-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transitive-bullshit%2Fopenai-realtime-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transitive-bullshit%2Fopenai-realtime-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/transitive-bullshit","download_url":"https://codeload.github.com/transitive-bullshit/openai-realtime-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transitive-bullshit%2Fopenai-realtime-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272772768,"owners_count":24990514,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-29T02:00:10.610Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["openai","realtime","voice"],"created_at":"2024-10-25T02:00:23.322Z","updated_at":"2025-08-29T22:13:35.278Z","avatar_url":"https://github.com/transitive-bullshit.png","language":"TypeScript","funding_links":["https://github.com/sponsors/transitive-bullshit"],"categories":["TypeScript"],"sub_categories":[],"readme":"# openai-realtime-api \u003c!-- omit from toc --\u003e\n\n\u003e TypeScript client for OpenAI's realtime voice API.\n\n\u003cp\u003e\n  \u003ca href=\"https://github.com/transitive-bullshit/openai-realtime-api/actions/workflows/main.yml\"\u003e\u003cimg alt=\"Build Status\" src=\"https://github.com/transitive-bullshit/openai-realtime-api/actions/workflows/main.yml/badge.svg\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/openai-realtime-api\"\u003e\u003cimg alt=\"NPM\" src=\"https://img.shields.io/npm/v/openai-realtime-api.svg\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/transitive-bullshit/openai-realtime-api/blob/main/license\"\u003e\u003cimg alt=\"MIT License\" src=\"https://img.shields.io/badge/license-MIT-blue\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://prettier.io\"\u003e\u003cimg alt=\"Prettier Code Formatting\" src=\"https://img.shields.io/badge/code_style-prettier-brightgreen.svg\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n- [Features](#features)\n- [Install](#install)\n- [Usage](#usage)\n  - [Server Usage](#server-usage)\n  - [Browser Usage](#browser-usage)\n  - [Relay Server](#relay-server)\n- [Examples](#examples)\n  - [Node.js Basic](#nodejs-basic)\n  - [Node.js Audio](#nodejs-audio)\n  - [Node.js Conversation](#nodejs-conversation)\n  - [OpenAI Realtime Console](#openai-realtime-console)\n- [TODO](#todo)\n- [License](#license)\n\n## Features\n\n- **Strongly typed** TS fork of [openai/openai-realtime-api-beta](https://github.com/openai/openai-realtime-api-beta)\n- [All events](./src/events.ts) and handlers are 100% typed\n- **Drop-in replacement for OpenAI's JS version**\n- Fixes many small bugs and inconsistencies\n  - ([#3](https://github.com/openai/openai-realtime-api-beta/issues/3), [#11](https://github.com/openai/openai-realtime-api-beta/pull/11), [#12](https://github.com/openai/openai-realtime-api-beta/pull/12), [#14](https://github.com/openai/openai-realtime-api-beta/issues/14), [#17](https://github.com/openai/openai-realtime-api-beta/pull/17), [#29](https://github.com/openai/openai-realtime-api-beta/pull/29), [#34](https://github.com/openai/openai-realtime-api-beta/pull/34), [#35](https://github.com/openai/openai-realtime-api-beta/pull/35), [#37](https://github.com/openai/openai-realtime-api-beta/pull/37), [#43](https://github.com/openai/openai-realtime-api-beta/pull/43), [#44](https://github.com/openai/openai-realtime-api-beta/pull/44), and likely others)\n- Published to NPM\n- Supports Node.js, browser, deno, bun, CF workers, etc\n- Includes Node.js CLI examples for easy local testing\n- Includes a simple relay server\n- Includes the [OpenAI Realtime Console demo](#openai-realtime-console) using this package 🔥\n\n## Install\n\n```sh\nnpm install openai-realtime-api\n```\n\nThis package is [ESM-only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). It requires `Node.js \u003e= 18`, a browser environment, or an equivalent JS runtime (Deno, Bun, CF workers, etc).\n\n## Usage\n\n\u003e [!IMPORTANT]\n\u003e All usage and events are 100% compatible with the [OpenAI JS version](https://github.com/openai/openai-realtime-api-beta). The main difference aside from bug fixes is that **all events are fully-typed**.\n\n```ts\nimport { RealtimeClient } from 'openai-realtime-api'\n\n// Create a new client; all params are optional; apiKey defaults to the\n// `OPENAI_API_KEY` environment variable (when using Node.js).\nconst client = new RealtimeClient({\n  sessionConfig: {\n    instructions: 'You are a great, upbeat friend.',\n    voice: 'alloy'\n  }\n})\n\n// Can change session config ahead of connecting.\nclient.updateSession({\n  turn_detection: null,\n  input_audio_transcription: { model: 'whisper-1' }\n})\n\n// Example of custom event handling\nclient.on('conversation.updated', (event) =\u003e {\n  // All events are fully-typed based on the event name.\n  // In this case, `event` will have the type `RealtimeCustomEvents.ConversationUpdatedEvent`\n  const { item, delta } = event\n\n  // Access the full list of conversation items.\n  const items = client.conversation.getItems()\n})\n\n// Connect to the Realtime API.\nawait client.connect()\n\n// Send a text message and trigger a response generation.\nclient.sendUserMessageContent([{ type: 'input_text', text: 'How are you?' }])\n\n// Wait for a completed response from the model.\n// (`event` will be of type `RealtimeServerEvents.ResponseDoneEvent`)\nconst event = await client.realtime.waitForNext('response.done')\n```\n\nSee [examples](#examples) for more complete demos.\n\nSee also the official [OpenAI Realtime API Guide](https://platform.openai.com/docs/guides/realtime) and [API Reference](https://platform.openai.com/docs/api-reference/realtime).\n\nFor more info on usage, tools, and custom events, see [OpenAI's readme](https://github.com/openai/openai-realtime-api-beta). Note that this package is 100% compatible with OpenAI's beta package in terms of both official and unofficial events. The only difference is that all events are typed.\n\n### Server Usage\n\n`RealtimeClient` takes in an optional `apiKey` which defaults to `process.env.OPENAI_API_KEY`.\n\n### Browser Usage\n\n`RealtimeClient` takes in an optional `url` which can be pointed at a relay server.\n\n```ts\nimport { RealtimeClient } from 'openai-realtime-api'\n\n// Create a browser client which points to a relay server.\nconst client = new RealtimeClient({ url: RELAY_SERVER_URL })\n```\n\nAlternatively, you can use `apiKey` with `RealtimeClient` in the browser, but you also have to pass `dangerouslyAllowAPIKeyInBrowser: true`.\n\n```ts\nimport { RealtimeClient } from 'openai-realtime-api'\n\n// Create a browser client which connects directly to the OpenAI realtime API\n// with an unsafe, client-side API key.\nconst client = new RealtimeClient({\n  apiKey: process.env.OPENAI_API_KEY,\n  dangerouslyAllowAPIKeyInBrowser: true\n})\n```\n\n\u003e [!CAUTION]\n\u003e We strongly recommend against including your API key in any client (mobile or browser). It can be useful for local testing, but for production, you should be using a relay server.\n\n### Relay Server\n\n```ts\nimport { RealtimeClient } from 'openai-realtime-api'\nimport { RealtimeRelay } from 'openai-realtime-api/node'\n\n// Setting `relay: true` disables tool calls and directly modifying the session,\n// since that will be the responsibility of the upstream client.\nconst client = new RealtimeClient({ relay: true })\nconst relay = new RealtimeRelay({ client })\n\nrelay.listen(8081)\n```\n\nNote that `RealtimeRelay` uses a different import path because it contains Node.js-specific code.\n\nA full example is included in [examples/node/relay-server.ts](./examples/node/relay-server.ts).\n\n## Examples\n\nTo run the included examples (requires `Node.js \u003e= 18`):\n\n1. Clone this repo\n2. Run `pnpm install`\n3. Setup `.env` with your `OPENAI_API_KEY`\n\nYou can set `debug: true` in the `RealtimeClient` constructor of these examples to print out the full event log.\n\n### Node.js Basic\n\nSimple Node.js demo using the `RealtimeClient` which sends a text message and waits for a complete response.\n\n- [examples/node/basic.ts](./examples/node/basic.ts)\n- Run `npx tsx examples/node/basic.ts`\n\n### Node.js Audio\n\nSimple Node.js demo using the `RealtimeClient` which sends a short audio message and waits for a complete response.\n\n- [examples/node/audio.ts](./examples/node/audio.ts)\n- Run `npx tsx examples/node/audio.ts`\n\n### Node.js Conversation\n\nSimple Node.js demo using the `RealtimeClient` with a microphone and speaker to simulate a full, back \u0026 forth conversation from the terminal.\n\n- [examples/node/convo.ts](./examples/node/convo.ts)\n- This demo uses the [mic](https://github.com/ashishbajaj99/mic) and [speaker](https://github.com/TooTallNate/node-speaker) npm packages\n- `mic` requires [sox](https://sourceforge.net/projects/sox/); on macOS, you can run `brew install sox`\n- `npx tsx examples/node/convo.ts`\n\n### OpenAI Realtime Console\n\nThis example has been imported from https://github.com/openai/openai-realtime-console ([at commit 6ea4dba](https://github.com/openai/openai-realtime-console/tree/6ea4dba795fee868c60ea9e8e7eba7469974b3e9)). The only change has been to replace `@openai/realtime-api-beta` with `openai-realtime-api` and to fix a few types.\n\n\u003cimg src=\"/examples/openai-realtime-console/readme/realtime-console-demo.png\" width=\"800\" /\u003e\n\nTo run the realtime console example:\n\n```sh\npnpm install\ncd examples/openai-realtime-console\npnpm start\n```\n\n## TODO\n\n- add an example using tools\n- add an example next.js app\n- improve readme docs\n\n## License\n\nMIT © [Travis Fischer](https://x.com/transitive_bs)\n\nIf you found this project interesting, [consider following me on Twitter](https://x.com/transitive_bs).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftransitive-bullshit%2Fopenai-realtime-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftransitive-bullshit%2Fopenai-realtime-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftransitive-bullshit%2Fopenai-realtime-api/lists"}