### Initialize and Start Project

Source: https://github.com/deepgram-starters/cpp-live-transcription/blob/main/AGENTS.md

Use these make commands to initialize the project, set up environment variables, and start both the backend and frontend servers.

```bash
# Initialize (clone submodules + install deps)
make init

# Set up environment
test -f .env || cp sample.env .env  # then set DEEPGRAM_API_KEY

# Start both servers
make start
# Backend: http://localhost:8081
# Frontend: http://localhost:8080
```

--------------------------------

### Start Backend and Frontend Separately

Source: https://github.com/deepgram-starters/cpp-live-transcription/blob/main/AGENTS.md

Instructions for starting the backend and frontend servers in separate terminals if not using the `make start` command.

```bash
# Terminal 1 — Backend
./build/app

# Terminal 2 — Frontend
cd frontend && corepack pnpm run dev -- --port 8080 --no-open
```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/deepgram-starters/cpp-live-transcription/blob/main/AGENTS.md

Install frontend Node.js dependencies using pnpm.

```bash
cd frontend && corepack pnpm install
```

--------------------------------

### Initialize and Start Live Transcription (Makefile)

Source: https://github.com/deepgram-starters/cpp-live-transcription/blob/main/README.md

Use this Makefile to initialize the project, set up your Deepgram API key, and start the live transcription server. Ensure you have a .env file with your DEEPGRAM_API_KEY.

```bash
make init
cp sample.env .env  # Add your DEEPGRAM_API_KEY
make start
```

--------------------------------

### Build and Run Backend Server with Make

Source: https://context7.com/deepgram-starters/cpp-live-transcription/llms.txt

Utilize Make commands to initialize submodules, build the project, and start the backend and frontend services. Use 'make start-backend' to run only the backend.

```bash
# Setup commands:
cp sample.env .env
# Edit .env and add your DEEPGRAM_API_KEY

# Build and run with Make:
make init          # Initialize submodules and build
make start         # Start both backend (8081) and frontend (8080)
make start-backend # Start backend only
```

--------------------------------

### Install C++ Dependencies with vcpkg and CMake

Source: https://github.com/deepgram-starters/cpp-live-transcription/blob/main/AGENTS.md

Install backend C++ dependencies using vcpkg and build the project with CMake. Ensure the VCPKG_ROOT environment variable is set.

```bash
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" && cmake --build build
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/deepgram-starters/cpp-live-transcription/blob/main/AGENTS.md

Standardized commit message formats for project version control.

```text
feat(cpp-live-transcription): add diarization support
fix(cpp-live-transcription): resolve WebSocket close handling
refactor(cpp-live-transcription): simplify session endpoint
chore(deps): update frontend submodule
```

--------------------------------

### GET /api/metadata

Source: https://context7.com/deepgram-starters/cpp-live-transcription/llms.txt

Returns project metadata parsed from the deepgram.toml configuration file.

```APIDOC
## GET /api/metadata

### Description
Returns project metadata parsed from the [meta] section of the deepgram.toml configuration file, including project title, description, author, and tags.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Success Response (200)
- **title** (string) - Project title
- **description** (string) - Project description
- **author** (string) - Author information
- **repository** (string) - Repository URL
- **useCase** (string) - Primary use case
- **language** (string) - Programming language
- **framework** (string) - Web framework
- **sdk** (string) - SDK used
- **tags** (array) - List of project tags

#### Response Example
{
  "title": "C++ Live Transcription",
  "description": "Get started using Deepgram's Live Transcription with this C++ demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com>",
  "repository": "https://github.com/deepgram-starters/cpp-live-transcription",
  "useCase": "live-transcription",
  "language": "C++",
  "framework": "Crow",
  "sdk": "N/A",
  "tags": ["live-transcription", "live-stt", "real-time-transcription", "cpp", "crow"]
}
```

--------------------------------

### GET /health

Source: https://context7.com/deepgram-starters/cpp-live-transcription/llms.txt

Simple health check endpoint for monitoring and load balancer integration.

```APIDOC
## GET /health

### Description
Simple health check endpoint for monitoring and load balancer integration. Returns OK status when the server is running.

### Method
GET

### Endpoint
/health
```

--------------------------------

### GET /api/session

Source: https://context7.com/deepgram-starters/cpp-live-transcription/llms.txt

Issues a signed JWT token with a 1-hour expiry for authenticating WebSocket connections.

```APIDOC
## GET /api/session

### Description
Issues a signed JWT token with 1-hour expiry for authenticating WebSocket connections. The token uses HS256 algorithm and is required for establishing live transcription sessions.

### Method
GET

### Endpoint
/api/session

### Response
#### Success Response (200)
- **token** (string) - The signed JWT token.

#### Response Example
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MTcwMDAwMzYwMH0.signature"
}
```

--------------------------------

### Build and Run Backend Server with CMake

Source: https://context7.com/deepgram-starters/cpp-live-transcription/llms.txt

Manually build the C++ project using CMake. Configure the build directory, build the project, and then execute the compiled binary.

```bash
# Or build manually with CMake:
cmake -B build
cmake --build build
./build/cpp-live-transcription
```

--------------------------------

### Configure Backend Server with Environment Variables

Source: https://context7.com/deepgram-starters/cpp-live-transcription/llms.txt

Set environment variables in a .env file to configure the backend server at startup. Ensure DEEPGRAM_API_KEY is provided. Other variables like PORT, HOST, and SESSION_SECRET are optional.

```dotenv
# .env file configuration
# Required: Your Deepgram API key
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# Optional: Backend API server port (default: 8081)
PORT=8081

# Optional: Server bind address (default: 0.0.0.0)
HOST=0.0.0.0

# Optional: Session secret for JWT signing (auto-generated if not set)
# Set in production for consistent token validation across restarts
SESSION_SECRET=your_32_byte_secret_here
```

--------------------------------

### Run Project Tests

Source: https://github.com/deepgram-starters/cpp-live-transcription/blob/main/AGENTS.md

Commands to execute conformance tests and verify API endpoints.

```bash
# Run conformance tests (requires app to be running)
make test

# Manual endpoint check
curl -sf http://localhost:8081/api/metadata | python3 -m json.tool
curl -sf http://localhost:8081/api/session | python3 -m json.tool
```

--------------------------------

### Configure C++ Live Transcription Project with CMake

Source: https://github.com/deepgram-starters/cpp-live-transcription/blob/main/CMakeLists.txt

This CMakeLists.txt file sets up the build environment for a C++ live transcription application. It specifies the C++ standard, finds and links required libraries, and defines the executable target.

```cmake
cmake_minimum_required(VERSION 3.20)
project(cpp-live-transcription VERSION 0.1.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Crow CONFIG REQUIRED)
find_package(nlohmann_json CONFIG REQUIRED)
find_package(OpenSSL REQUIRED)
find_package(Boost REQUIRED COMPONENTS system)

add_executable(${PROJECT_NAME} src/main.cpp)

target_link_libraries(${PROJECT_NAME} PRIVATE
    Crow::Crow
    nlohmann_json::nlohmann_json
    OpenSSL::SSL
    OpenSSL::Crypto
    Boost::system
)
```

--------------------------------

### Clean Rebuild Project

Source: https://github.com/deepgram-starters/cpp-live-transcription/blob/main/AGENTS.md

Command to perform a clean rebuild of the project by removing build artifacts and dependencies, then re-initializing.

```bash
rm -rf build frontend/node_modules frontend/.vite
make init
```

--------------------------------

### Retrieve Project Metadata via cURL

Source: https://context7.com/deepgram-starters/cpp-live-transcription/llms.txt

Fetches project configuration details parsed from the deepgram.toml file.

```bash
# Get project metadata
curl -X GET http://localhost:8081/api/metadata

# Response:
{
  "title": "C++ Live Transcription",
  "description": "Get started using Deepgram's Live Transcription with this C++ demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
  "repository": "https://github.com/deepgram-starters/cpp-live-transcription",
  "useCase": "live-transcription",
  "language": "C++",
  "framework": "Crow",
  "sdk": "N/A",
  "tags": ["live-transcription", "live-stt", "real-time-transcription", "cpp", "crow"]
}
```

--------------------------------

### Check Server Health

Source: https://context7.com/deepgram-starters/cpp-live-transcription/llms.txt

Use this command to verify if the backend server is running and accessible.

```bash
curl -X GET http://localhost:8081/health
```

--------------------------------

### Update Frontend Submodule

Source: https://github.com/deepgram-starters/cpp-live-transcription/blob/main/AGENTS.md

Commands to commit and push changes within the frontend submodule directory.

```bash
cd frontend && git add . && git commit -m "feat: description"
cd frontend && git push origin main
cd .. && git add frontend && git commit -m "chore(deps): update frontend submodule"
```

--------------------------------

### WS /api/live-transcription

Source: https://context7.com/deepgram-starters/cpp-live-transcription/llms.txt

Establishes a bidirectional WebSocket connection that proxies audio data to Deepgram's Live Transcription API.

```APIDOC
## WS /api/live-transcription

### Description
Establishes a bidirectional WebSocket connection that proxies audio data to Deepgram's Live Transcription API. Requires JWT authentication via the `access_token.<jwt>` subprotocol.

### Method
WS

### Endpoint
/api/live-transcription

### Parameters
#### Query Parameters
- **model** (string) - Optional - Deepgram model (e.g., nova-3, nova-2). Default: nova-3
- **language** (string) - Optional - Language code. Default: en
- **smart_format** (boolean) - Optional - Enable smart formatting. Default: true
- **punctuate** (boolean) - Optional - Enable punctuation. Default: true
- **diarize** (boolean) - Optional - Speaker diarization. Default: false
- **filler_words** (boolean) - Optional - Include filler words. Default: false
- **encoding** (string) - Optional - Audio encoding format. Default: linear16
- **sample_rate** (integer) - Optional - Audio sample rate in Hz. Default: 16000
- **channels** (integer) - Optional - Number of audio channels. Default: 1
```

--------------------------------

### Stop All Running Servers

Source: https://github.com/deepgram-starters/cpp-live-transcription/blob/main/AGENTS.md

Command to find and kill processes listening on ports 8080 and 8081, effectively stopping both servers.

```bash
lsof -ti:8080,8081 | xargs kill -9 2>/dev/null
```

--------------------------------

### Establish WebSocket Transcription Connection

Source: https://context7.com/deepgram-starters/cpp-live-transcription/llms.txt

Connects to the transcription service and captures microphone audio for real-time processing. Requires a valid JWT token passed via the subprotocol.

```javascript
// Browser JavaScript example for live transcription
async function startTranscription() {
  // 1. Get session token from backend
  const response = await fetch('http://localhost:8081/api/session');
  const { token } = await response.json();

  // 2. Connect WebSocket with token and transcription options
  const ws = new WebSocket(
    'ws://localhost:8081/api/live-transcription?' +
    'model=nova-3&language=en&smart_format=true&punctuate=true',
    [`access_token.${token}`]  // JWT passed via subprotocol
  );

  ws.onopen = () => {
    console.log('Connected to transcription service');
    startAudioCapture(ws);
  };

  ws.onmessage = (event) => {
    const result = JSON.parse(event.data);
    if (result.channel?.alternatives?.[0]?.transcript) {
      console.log('Transcript:', result.channel.alternatives[0].transcript);
    }
  };

  ws.onerror = (error) => console.error('WebSocket error:', error);
  ws.onclose = () => console.log('Connection closed');
}

// Capture microphone audio and send to WebSocket
async function startAudioCapture(ws) {
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  const audioContext = new AudioContext({ sampleRate: 16000 });
  const source = audioContext.createMediaStreamSource(stream);
  const processor = audioContext.createScriptProcessor(4096, 1, 1);

  processor.onaudioprocess = (e) => {
    if (ws.readyState === WebSocket.OPEN) {
      const inputData = e.inputBuffer.getChannelData(0);
      const pcm16 = new Int16Array(inputData.length);
      for (let i = 0; i < inputData.length; i++) {
        pcm16[i] = Math.max(-32768, Math.min(32767, inputData[i] * 32768));
      }
      ws.send(pcm16.buffer);  // Send binary audio data
    }
  };

  source.connect(processor);
  processor.connect(audioContext.destination);
}

// Supported query parameters with defaults:
// model=nova-3        - Deepgram model (nova-3, nova-2, etc.)
// language=en         - Language code
// smart_format=true   - Enable smart formatting
// punctuate=true      - Enable punctuation
// diarize=false       - Speaker diarization
// filler_words=false  - Include filler words (um, uh)
// encoding=linear16   - Audio encoding format
// sample_rate=16000   - Audio sample rate in Hz
// channels=1          - Number of audio channels
```

--------------------------------

### JWT Authentication Structure and Flow

Source: https://context7.com/deepgram-starters/cpp-live-transcription/llms.txt

Illustrates the structure of a JWT token issued by the backend and the WebSocket authentication flow. Tokens are signed with HS256 and include issued at and expiry timestamps.

```cpp
// Token structure (issued by /api/session):
// Header: {"alg": "HS256", "typ": "JWT"}
// Payload: {"iat": <issued_at_timestamp>, "exp": <expiry_timestamp>}
// Signature: HMAC-SHA256(header.payload, session_secret)

// WebSocket authentication flow:
// 1. Client requests token: GET /api/session -> {"token": "<jwt>"}
// 2. Client connects with subprotocol: Sec-WebSocket-Protocol: access_token.<jwt>
// 3. Server validates token signature and expiry
// 4. Server accepts connection if valid, rejects with 401 if invalid

// Example token validation in onaccept handler:
// - Parse "access_token.<jwt>" from Sec-WebSocket-Protocol header
// - Verify HMAC-SHA256 signature matches
// - Check "alg" header is "HS256"
// - Verify "exp" claim > current time
// - Return validated protocol string for handshake response

// Security notes:
// - SESSION_SECRET should be set in production for consistent validation
// - If not set, a random 32-byte secret is generated at startup
// - Tokens expire after 1 hour (JWT_EXPIRY_SECS = 3600)
```

--------------------------------

### Request Session Token via cURL

Source: https://context7.com/deepgram-starters/cpp-live-transcription/llms.txt

Retrieves a signed JWT token required for authenticating WebSocket connections. The token is valid for one hour.

```bash
# Request a session token
curl -X GET http://localhost:8081/api/session

# Response:
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MTcwMDAwMzYwMH0.signature"
}

# Use the token in WebSocket connection via subprotocol:
# Sec-WebSocket-Protocol: access_token.<jwt_token>
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.