Live Translator

Browser-based live translation app for internal use. This repository is a customized derivative of the OpenAI Cookbook browser translation demo, adapted for translating live international events in a browser tab into Vietnamese captions and transcript.

Upstream source: https://developers.openai.com/cookbook/examples/voice_solutions/realtime_translation_guide

Code provenance:

• Original inspiration: OpenAI Cookbook realtime translation guide
• Repository basis: upstream demo repository
• Customizations in this repo: auth gate, session handling, production headers, VPS deployment hardening, and meeting-session UX

What It Does

• Captures audio from either the user's microphone or a selected browser tab.
• Creates a short-lived OpenAI Realtime Translation client secret on the server.
• Sends the selected input audio to Realtime Translation over WebRTC.
• Displays translated transcript deltas and event/debug state.
• Automatically detects the spoken source language and fixes the output language to Vietnamese.

Good source tabs:

• Official government speech or press conference.
• Federal Reserve / central bank speech.
• K-pop, athlete, or celebrity interview from an official channel.
• Product launch, keynote, or live event in English, Korean, Japanese, or Chinese.

Setup

Create a local .env file in this folder:

OPENAI_API_KEY=your-openai-api-key

Optional:

OPENAI_TRANSLATION_MODEL=gpt-realtime-translate
PORT=5173
HOST=127.0.0.1

# Optional internal login for web access
APP_AUTH_USERNAME=your-username
APP_AUTH_PASSWORD=your-password
APP_AUTH_SECRET=replace-with-a-long-random-secret
APP_AUTH_TTL_SECONDS=28800

For Docker or VPS deployment, set HOST=0.0.0.0 so the app binds outside the container loopback.

Run

npm install
npm run dev

Open the printed local URL, normally:

http://127.0.0.1:5173

VPS / Docker

Minimal VPS deployment:

docker build -t live-translator .
docker run -d \
  --name live-translator \
  -p 5173:5173 \
  --env-file .env \
  live-translator

If you use Docker, make sure .env includes HOST=0.0.0.0.

Health check:

GET /healthz

Recommended reverse proxy setup:

• Terminate TLS in Nginx or a similar proxy.
• Forward X-Forwarded-Proto: https.
• Keep the app container private on the VPS network.
• Point your monitoring to /healthz.

For a full VPS + subdomain + WordPress-isolation walkthrough, see DEPLOYMENT.md.

End-User Flow

1. Open this app; the spoken source language is detected automatically.
2. Choose Microphone or Browser tab audio as the audio source.
3. For microphone input, click Use microphone and allow access.
4. For tab input, click Choose event tab, pick the source tab, and enable tab audio.
5. Follow the Vietnamese translated transcript, audio meter, and WebRTC status.
6. Use the event log and session status to verify the session is stable.

Validation

npm test

Attribution

This project builds on the OpenAI Cookbook browser translation demo and keeps that upstream origin visible for users, contributors, and deployers.