Add realtime translation cookbook guide (#2667)

Author: erikakettleson-openai

.gitignore

@@ -15,6 +15,8 @@ downloads/
 eggs/
 .eggs/
 lib/
+!examples/voice_solutions/realtime_translation_guide/livekit-translation-demo/lib/
+!examples/voice_solutions/realtime_translation_guide/livekit-translation-demo/lib/**
 lib64
 parts/
 sdist/
@@ -103,6 +105,8 @@ celerybeat.pid
 
 # Environments
 .env
+.env.*
+!.env.example
 .venv
 env/
 venv/

examples/voice_solutions/realtime_translation_guide.mdx

@@ -0,0 +1,6 @@
+.env
+.env.*
+!.env.example
+.git
+node_modules
+npm-debug.log*

examples/voice_solutions/realtime_translation_guide/browser-translation-demo/.dockerignore

@@ -0,0 +1,4 @@
+OPENAI_API_KEY=
+OPENAI_TRANSLATION_MODEL=gpt-realtime-translate
+OPENAI_INPUT_TRANSCRIPTION_MODEL=gpt-realtime-whisper
+PORT=5173

examples/voice_solutions/realtime_translation_guide/browser-translation-demo/.env.example

@@ -0,0 +1,4 @@
+.env
+.env.*
+!.env.example
+node_modules/

examples/voice_solutions/realtime_translation_guide/browser-translation-demo/.gitignore

@@ -0,0 +1,11 @@
+FROM node:20-slim
+
+WORKDIR /app
+ENV NODE_ENV=production
+
+COPY --chown=node:node package.json ./
+COPY --chown=node:node src ./src
+
+USER node
+EXPOSE 5173
+CMD ["node", "src/server.js"]

examples/voice_solutions/realtime_translation_guide/browser-translation-demo/Dockerfile

@@ -0,0 +1,74 @@
+# Browser Realtime Translation Demo
+
+This is a small browser demo for one-way live translation from tab audio. The
+server creates a short-lived OpenAI Realtime Translation client secret, and the
+browser uses WebRTC to send captured tab audio and play translated speech with
+captions.
+
+## Setup
+
+Create a local `.env` file in this demo folder using `.env.example` as the list
+of required variables.
+
+Required:
+
+```bash
+OPENAI_API_KEY=your-openai-api-key
+```
+
+Optional:
+
+```bash
+OPENAI_TRANSLATION_MODEL=gpt-realtime-translate
+OPENAI_INPUT_TRANSCRIPTION_MODEL=gpt-realtime-whisper
+PORT=5173
+HOST=127.0.0.1
+```
+
+## Run
+
+From the cookbook repo root:
+
+```bash
+cd examples/voice_solutions/realtime_translation_guide/browser-translation-demo
+npm install
+npm run dev
+```
+
+Open the local URL printed by the server. Choose a browser tab with audio, pick
+the language you want to hear, and start translation.
+
+## Audio mix
+
+The app includes an Audio mix slider for balancing translated speech with the
+original tab audio. By default, it plays 85% translated audio and 15% original
+audio, matching the LiveKit demo.
+
+When the selected source is a browser tab, the demo still requests
+`suppressLocalAudioPlayback` in the `getDisplayMedia()` audio constraints.
+If the browser honors that setting, the slider controls both the translated
+audio and the original audio playback from this app. If the browser does not
+support local playback suppression, the source tab may continue playing outside
+the slider, so lower or mute the source tab if you hear too much original audio.
+
+## Validation
+
+From the cookbook repo root:
+
+```bash
+cd examples/voice_solutions/realtime_translation_guide/browser-translation-demo
+npm test
+```
+
+To run a live API smoke test:
+
+```bash
+npm run smoke
+```
+
+## Notes
+
+- The browser uses `getDisplayMedia()` so the user explicitly chooses the source
+  tab.
+- WebRTC handles browser audio transport, so the browser does not need to
+  resample tab audio or manually send PCM chunks.

examples/voice_solutions/realtime_translation_guide/browser-translation-demo/README.md

@@ -0,0 +1,15 @@
+{
+  "name": "browser-realtime-translation-demo",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "node --watch src/server.js",
+    "test": "node --test test/*.test.js",
+    "smoke": "node scripts/smoke-realtime.mjs"
+  }
+}