Skip to content

Commit 0643630

Browse files
github-actions[bot]examples-botlukeocodesclaude
authored
[Example] 280 — Express.js + React Full-Stack Live Transcription (TypeScript) (#127)
## New example: Express.js + React Full-Stack Live Transcription (TypeScript) <!-- metadata type: example number: 260 slug: express-react-live-transcription-ts language: TypeScript products: stt integrations: express-react --> **Integration:** Express.js + React | **Language:** TypeScript | **Products:** STT ### What this shows A full-stack monorepo with an Express.js backend and React (Vite) frontend that demonstrates real-time live transcription. The server proxies WebSocket audio to Deepgram Nova-3 so the API key never leaves the backend. The React UI displays interim and final transcripts with speaker diarization labels. ### Required secrets None — only DEEPGRAM_API_KEY required Closes #32 --- *Built by Engineer on 2026-04-02* --------- Co-authored-by: examples-bot <noreply@deepgram.com> Co-authored-by: Luke Oliff <luke@lukeoliff.com> Co-authored-by: Claude <noreply@anthropic.com>
1 parent cb71d64 commit 0643630

18 files changed

Lines changed: 4004 additions & 0 deletions

File tree

‎examples/280-express-react-live-transcription-ts/.env.example‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# Deepgram — https://console.deepgram.com/
2+
DEEPGRAM_API_KEY=

‎examples/280-express-react-live-transcription-ts/.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
node_modules/
2+
dist/
3+
.env
4+
tsconfig.tsbuildinfo

‎examples/280-express-react-live-transcription-ts/README.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Express.js + React Live Transcription (TypeScript)
2+
3+
A full-stack application with an Express.js backend and React frontend that demonstrates real-time live transcription using Deepgram's Nova-3 model. The server proxies WebSocket connections so your API key never leaves the backend.
4+
5+
## What you'll build
6+
7+
A monorepo with an Express.js server and a React (Vite) client. The browser captures microphone audio via `getUserMedia`, streams raw PCM through a WebSocket to the Express server, which proxies it to Deepgram Live STT. Transcripts — including interim results and speaker diarization labels — flow back to the React UI in real time.
8+
9+
## Prerequisites
10+
11+
- Node.js 18+
12+
- Deepgram account — [get a free API key](https://console.deepgram.com/)
13+
14+
## Environment variables
15+
16+
| Variable | Where to find it |
17+
|----------|-----------------|
18+
| `DEEPGRAM_API_KEY` | [Deepgram console](https://console.deepgram.com/) |
19+
20+
## Install and run
21+
22+
```bash
23+
# 1. Clone and enter the example directory
24+
cd examples/280-express-react-live-transcription-ts
25+
26+
# 2. Copy env file and add your Deepgram API key
27+
cp .env.example server/.env
28+
29+
# 3. Install dependencies
30+
cd server && npm install && cd ../client && npm install && cd ..
31+
32+
# 4a. Development (two terminals)
33+
cd server && npm run dev # Express on :3000
34+
cd client && npm run dev # Vite on :5173 (proxies WS to :3000)
35+
36+
# 4b. Production
37+
cd client && npm run build # Build React into client/dist
38+
cd ../server && npm run build && npm start # Serves everything on :3000
39+
```
40+
41+
Open `http://localhost:5173` (dev) or `http://localhost:3000` (prod) and click **Start Listening**.
42+
43+
## Key parameters
44+
45+
| Parameter | Value | Description |
46+
|-----------|-------|-------------|
47+
| `model` | `nova-3` | Latest general-purpose STT model with best accuracy |
48+
| `encoding` | `linear16` | Raw 16-bit PCM — avoids browser codec overhead |
49+
| `sample_rate` | `16000` | 16 kHz — sufficient for speech, lower bandwidth |
50+
| `interim_results` | `true` | Partial transcripts while still speaking |
51+
| `smart_format` | `true` | Auto punctuation, capitalisation, number formatting |
52+
| `diarize` | `true` | Speaker labels (Speaker 0, Speaker 1, …) |
53+
| `utterance_end_ms` | `1500` | Silence threshold before finalising an utterance |
54+
55+
## How it works
56+
57+
1. The React client requests microphone access via `getUserMedia` (mono, 16 kHz).
58+
2. An `AudioContext` + `ScriptProcessorNode` converts float32 samples to 16-bit PCM.
59+
3. PCM chunks are sent over a WebSocket to the Express server at `/listen`.
60+
4. The server opens a Deepgram Live STT connection and proxies audio chunks via `sendBinary()`.
61+
5. Deepgram returns JSON messages with `channel.alternatives[0].transcript` and `is_final`.
62+
6. The server relays each message back to the browser WebSocket.
63+
7. React state updates show final transcripts (with optional speaker labels) and greyed-out interim text.
64+
65+
```
66+
Browser (React) Express Server Deepgram
67+
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
68+
│ getUserMedia │─ PCM ──▶│ /listen WS │─ PCM ──▶│ Live STT │
69+
│ │ │ proxy │ │ Nova-3 │
70+
│ Transcript UI│◀─ JSON ──│ │◀─ JSON ──│ │
71+
└──────────────┘ └──────────────┘ └──────────────┘
72+
```
73+
74+
## Starter templates
75+
76+
[deepgram-starters](https://github.com/orgs/deepgram-starters/repositories)

‎examples/280-express-react-live-transcription-ts/client/index.html‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
6+
<title>Deepgram Live Transcription</title>
7+
</head>
8+
<body>
9+
<div id="root"></div>
10+
<script type="module" src="/src/main.tsx"></script>
11+
</body>
12+
</html>

0 commit comments

Comments
 (0)