@ekaone/rendition

OpenAI Realtime Translation SDK — WebSocket + WebRTC transports, React hook, zero-dependency core.

npm install @ekaone/rendition

Transports

| Transport | When to use | |---|---| | "webrtc" | Browser mic capture — audio flows via RTCPeerConnection, no manual audio piping | | "websocket" | Server-side pipelines — Twilio, SIP, broadcast ingest, media workers |

createTranslationSession() auto-selects: "webrtc" in browser, "websocket" in Node.

React hook (Vite / Next.js)

npm install react react-dom

import { useTranslationSession } from "@ekaone/rendition/react";

function TranslationWidget() {
  const {
    status,
    outputTranscript,
    inputTranscript,
    isSpeaking,
    mediaStream,
    connect,
    disconnect,
    error,
  } = useTranslationSession({
    apiKey: ephemeralClientSecret, // from your backend — never ship raw key to browser
    targetLanguage: "es",          // BCP-47 tag
    transport: "webrtc",           // mic → WebRTC → OpenAI
  });

  function toggleMic() {
    if (!mediaStream) return;
    for (const track of mediaStream.getAudioTracks()) {
      track.enabled = !track.enabled;
    }
  }

  return (
    <div>
      <p>Status: {status} {isSpeaking && "(speaking)"}</p>
      <button onClick={connect} disabled={status !== "idle" && status !== "closed"}>Start</button>
      <button onClick={disconnect} disabled={status === "idle" || status === "closed"}>Stop</button>
      <button onClick={toggleMic} disabled={!mediaStream}>Mute / Unmute</button>
      {error && <p>Error: {error}</p>}
      <p><strong>Source:</strong> {inputTranscript}</p>
      <p><strong>Translation:</strong> {outputTranscript}</p>
    </div>
  );
}

Hook options

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | required | OpenAI API key or ephemeral client secret | | targetLanguage | string | required | BCP-47 output language tag, e.g. "es", "fr", "ja" | | transport | "webrtc" \| "websocket" | "webrtc" in browser | Transport to use | | safetyIdentifier | string | — | Hashed user ID sent as OpenAI-Safety-Identifier header | | model | string | "gpt-realtime-translate" | Model override | | wsEndpoint | string | OpenAI default | Custom WebSocket endpoint | | onAudioDelta | (delta: string) => void | — | Override audio playback (WebSocket path) | | autoConnect | boolean | false | Connect automatically on mount |

Hook result

| Field | Type | Description | |---|---|---| | status | TranslationSessionStatus | idle \| connecting \| ready \| translating \| closing \| closed \| error | | outputTranscript | string | Accumulated translated transcript | | inputTranscript | string | Accumulated source transcript | | isSpeaking | boolean | true while translated transcript deltas are actively arriving (~700 ms idle reset) | | mediaStream | MediaStream \| null | Local mic stream (WebRTC only) — use to mute/replace the mic track | | connect | () => Promise<void> | Start the session | | disconnect | () => Promise<void> | Gracefully close | | appendAudio | (b64: string) => void | Append audio manually (WebSocket path) | | error | string \| null | Last error message |

Core API (framework-agnostic)

createTranslationSession(config)

import { createTranslationSession } from "@ekaone/rendition";

const session = await createTranslationSession({
  apiKey: process.env.OPENAI_API_KEY,
  targetLanguage: "fr",
  transport: "websocket",
});

session.on("session.output_transcript.delta", (evt) => {
  process.stdout.write(evt.delta);
});

session.on("session.output_audio.delta", (evt) => {
  // write evt.delta (base64 PCM16) to your media output
});

session.appendAudio(base64Pcm16Chunk);

await session.close();

createNodeWebSocketSession(config)

Server-side variant using the ws package — supports Authorization and OpenAI-Safety-Identifier headers that browser WebSocket cannot set.

npm install ws

import { createNodeWebSocketSession } from "@ekaone/rendition";

const session = await createNodeWebSocketSession({
  apiKey: process.env.OPENAI_API_KEY,
  targetLanguage: "ja",
  safetyIdentifier: "hashed-user-id",
});

Audio utilities

Audio helpers are available via a dedicated subpath so they do not bloat the session protocol surface:

import {
  float32ToBase64Pcm16,
  base64Pcm16ToFloat32,
  playPcm16Delta,
} from "@ekaone/rendition/utils";

// Web Audio Float32 → base64 PCM16 (for appendAudio)
const b64 = float32ToBase64Pcm16(float32Array);

// base64 PCM16 → Float32 (for custom playback)
const float32 = base64Pcm16ToFloat32(b64);

// Play a delta chunk directly via Web Audio API
playPcm16Delta(audioContext, b64, 24000);

The same helpers are also re-exported from the main @ekaone/rendition entry for backwards compatibility.

Session events

| Event | Payload | Description | |---|---|---| | session.output_audio.delta | { delta: string } | Base64 PCM16 translated audio chunk | | session.output_transcript.delta | { delta: string } | Translated transcript delta | | session.input_transcript.delta | { delta: string } | Source transcript delta | | session.closed | — | Session fully flushed and closed | | session.created | { session } | Session created | | session.updated | { session } | Session config updated | | error | { error } | API error |

Session lifecycle

idle → connecting → ready → translating → closing → closed
                                        ↘ error

WebSocket teardown follows the spec:

1. Send session.close
2. Keep reading events — do not close the socket yet
3. Receive session.closed → close the socket

Skipping step 2 drops buffered translated audio still draining from the session.

Exports

| Import path | Contents | |---|---| | @ekaone/rendition | createTranslationSession, createNodeWebSocketSession, WebSocketSession, WebRTCSession, audio utils, all types | | @ekaone/rendition/react | useTranslationSession, hook types | | @ekaone/rendition/utils | float32ToBase64Pcm16, base64Pcm16ToFloat32, playPcm16Delta |

Architecture

src/
├── types/         # Shared TypeScript types
├── core/
│   ├── emitter.ts             # Typed zero-dep event emitter
│   ├── audio.ts               # PCM16 ↔ Float32, Web Audio playback
│   ├── websocket-session.ts   # Browser + Node WebSocket sessions
│   ├── webrtc-session.ts      # Browser WebRTC session
│   └── factory.ts             # createTranslationSession()
├── react/
│   ├── useTranslationSession.ts
│   └── index.ts
├── utils/
│   └── index.ts               # Audio helper re-exports
└── index.ts       # Core barrel

License

MIT © Eka Prasetia

Links

• npm Package
• GitHub Repository
• Issue Tracker