### Initialize and Start Application

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

Commands to clone submodules, install dependencies, and launch the development 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
```

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

### Manual project setup with Python and pnpm

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

Clone the repository and install dependencies manually for both the backend and frontend.

```bash
git clone --recurse-submodules https://github.com/deepgram-starters/fastapi-live-transcription.git
cd fastapi-live-transcription
python3 -m venv venv
./venv/bin/pip install -r requirements.txt
cd frontend && corepack pnpm install && cd ..
cp sample.env .env  # Add your DEEPGRAM_API_KEY
```

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

### Start Backend and Frontend Servers

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

Start both the backend and frontend servers using the 'make start' command. The backend runs on http://localhost:8081 and the frontend on http://localhost:8080.

```bash
make start
```

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

### Install Dependencies

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

Commands to install backend and frontend requirements.

```bash
python3 -m venv venv && ./venv/bin/pip install -r requirements.txt
```

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

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

### Initialize and start project with Makefile

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

Use the provided Makefile to initialize the environment and start the application. Ensure the DEEPGRAM_API_KEY is set in the .env file.

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

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

### Start Backend and Frontend Servers Individually

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

Alternatively, start the backend and frontend servers in separate terminals using 'make start-backend' and 'make start-frontend'.

```bash
make start-backend   # Terminal 1
make start-frontend  # Terminal 2
```

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

### Manage Application Lifecycle

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

Commands for starting, stopping, and rebuilding the application environment.

```bash
make start
```

```bash
# Terminal 1 — Backend
./venv/bin/python app.py

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

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

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

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

### Clone Repository and Initialize Project

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

Clone the repository, navigate into the directory, and initialize the project by creating a virtual environment and installing dependencies.

```bash
git clone --recurse-submodules https://github.com/deepgram-starters/fastapi-live-transcription.git
cd fastapi-live-transcription
make init
```

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

### Conventional Commit Examples

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

Standardized commit message formats for project version control.

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

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

### Run backend and frontend servers

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

Start the backend and frontend services in separate terminal sessions.

```bash
# Terminal 1 - Backend (port 8081)
./venv/bin/python app.py

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

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

### GET /api/metadata

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

Returns application metadata including use case, framework, and language.

```APIDOC
## GET /api/metadata

### Description
Returns application metadata.

### Method
GET

### Endpoint
/api/metadata

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **useCase** (string) - The use case of the application.
- **framework** (string) - The backend framework used (e.g., FastAPI).
- **language** (string) - The programming language used (e.g., Python).

#### Response Example
```json
{
  "useCase": "Live Transcription",
  "framework": "FastAPI",
  "language": "Python"
}
```
```

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

### GET /api/metadata

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

Retrieves project metadata including title, description, and configuration tags.

```APIDOC
## GET /api/metadata

### Description
Returns project metadata from the deepgram.toml configuration file, including title, description, author information, 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) - Backend framework
- **tags** (array) - List of project tags

#### Response Example
{
  "title": "FastAPI Live Transcription",
  "description": "Get started using Deepgram's Live STT with this FastAPI demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com>",
  "repository": "https://github.com/deepgram-starters/fastapi-live-transcription",
  "useCase": "live-transcription",
  "language": "python",
  "framework": "fastapi",
  "tags": ["live-transcription", "live-stt"]
}
```

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

### GET /api/session

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

Issues a JWT session token for authentication.

```APIDOC
## GET /api/session

### Description
Issues a JWT session token.

### Method
GET

### Endpoint
/api/session

### Parameters
None

### Request Example
None

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

#### Response Example
```json
{
  "token": "your_jwt_token_here"
}
```
```

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

### Handle Authentication Errors

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

Example of a 401 error response when accessing a protected endpoint without a valid token.

```bash
# Missing token error (401)
curl -X GET http://localhost:8081/api/protected-endpoint
```

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

### GET /api/session

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

Issues a JWT session token required for authenticating WebSocket connections. The token is valid for 1 hour.

```APIDOC
## GET /api/session

### Description
Issues a JWT session token for authenticating WebSocket connections. The token expires after 1 hour and must be included in WebSocket connection requests via the subprotocol header.

### Method
GET

### Endpoint
/api/session

### Response
#### Success Response (200)
- **token** (string) - JWT session token

#### Response Example
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDk4..."
}
```

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

### Retrieve Project Metadata

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

Fetch project configuration details from the /api/metadata endpoint.

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

# Response
{
  "title": "FastAPI Live Transcription",
  "description": "Get started using Deepgram's Live STT with this FastAPI demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
  "repository": "https://github.com/deepgram-starters/fastapi-live-transcription",
  "useCase": "live-transcription",
  "language": "python",
  "framework": "fastapi",
  "sdk": "N/A",
  "tags": ["live-transcription", "live-stt", "real-time-transcription", "real-time-asr", "streaming-transcription", "live-speech-to-text", "python", "fastapi"]
}
```

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

### Other Useful Makefile Commands

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

Provides a list of other helpful commands for managing the project, including cleaning build artifacts, updating submodules, checking status, and running tests.

```bash
# Other useful commands
make clean           # Remove venv, node_modules, build artifacts
make update          # Update git submodules
make status          # Show repository and submodule status
make test            # Run contract conformance tests
```

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

### Testing and Metadata Retrieval Commands

Source: https://github.com/deepgram-starters/fastapi-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 Environment Variables

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

Copy the sample environment file and edit it to include your Deepgram API key.

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

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

### Configure Environment Variables

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

Set the required Deepgram API key and optional server settings in a .env file.

```bash
# .env file configuration

# Required - Deepgram API key for STT service
DEEPGRAM_API_KEY=your_deepgram_api_key_here

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

# Optional - Server host binding (default: 0.0.0.0)
HOST=0.0.0.0

# Optional - JWT session secret (auto-generated if not set)
SESSION_SECRET=your_secure_random_secret
```

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

### Implement Live Transcription via WebSocket

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

Connect to the WebSocket endpoint using the session token and stream audio from the browser microphone.

```javascript
// Browser JavaScript example for live transcription

// Step 1: Get session token
const sessionResponse = await fetch('http://localhost:8081/api/session');
const { token } = await sessionResponse.json();

// Step 2: Connect to WebSocket with authentication and transcription options
const wsUrl = new URL('ws://localhost:8081/api/live-transcription');
wsUrl.searchParams.set('model', 'nova-2');           // Deepgram model
wsUrl.searchParams.set('language', 'en');            // Language code
wsUrl.searchParams.set('smart_format', 'true');      // Enable smart formatting
wsUrl.searchParams.set('interim_results', 'true');   // Get partial results
wsUrl.searchParams.set('punctuate', 'true');         // Add punctuation
wsUrl.searchParams.set('encoding', 'linear16');      // Audio encoding
wsUrl.searchParams.set('sample_rate', '16000');      // Sample rate in Hz

const socket = new WebSocket(wsUrl.toString(), [`access_token.${token}`]);

socket.onopen = () => {
  console.log('Connected to live transcription');
};

socket.onmessage = (event) => {
  const data = JSON.parse(event.data);

  // Handle transcription results from Deepgram
  if (data.type === 'Results') {
    const transcript = data.channel.alternatives[0].transcript;
    const isFinal = data.is_final;
    console.log(`[${isFinal ? 'Final' : 'Interim'}]: ${transcript}`);
  }

  // Handle errors
  if (data.type === 'Error') {
    console.error(`Error: ${data.description} (${data.code})`);
  }
};

socket.onerror = (error) => {
  console.error('WebSocket error:', error);
};

socket.onclose = (event) => {
  console.log(`Connection closed: ${event.code} ${event.reason}`);
};

// Step 3: Stream audio from microphone
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const mediaRecorder = new MediaRecorder(stream, { mimeType: 'audio/webm' });

mediaRecorder.ondataavailable = (event) => {
  if (event.data.size > 0 && socket.readyState === WebSocket.OPEN) {
    socket.send(event.data);
  }
};

// Start recording with 250ms chunks
mediaRecorder.start(250);

// To stop transcription
// mediaRecorder.stop();
// socket.close();
```

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

### Frontend Submodule Management Commands

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

Commands to update and commit changes to the frontend git submodule.

```bash
cd frontend && git add . && git commit -m "feat: description"
```

```bash
cd frontend && git push origin main
```

```bash
cd .. && git add frontend && git commit -m "chore(deps): update frontend submodule"
```

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

### WS /api/live-transcription

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

Establishes a WebSocket connection for streaming microphone audio to Deepgram for real-time transcription. Authentication is handled via JWT.

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

### Description
Streams microphone audio to Deepgram for real-time transcription via WebSocket. Requires JWT authentication.

### Method
WS

### Endpoint
/api/live-transcription

### Parameters
#### Query Parameters
- **model** (string) - Optional - STT model (e.g., `nova-3`, `nova-2`, `base`). Default: `nova-3`.
- **language** (string) - Optional - Transcription language (BCP-47 code). Default: `en`.
- **smart_format** (boolean) - Optional - Enables smart formatting. Default: `true`.
- **encoding** (string) - Optional - Audio encoding format (e.g., `linear16`, `opus`, `flac`). Default: `linear16`.
- **sample_rate** (integer) - Optional - Audio sample rate (e.g., `8000`, `16000`, `44100`, `48000`). Default: `16000`.
- **channels** (integer) - Optional - Number of audio channels (1 for mono, 2 for stereo). Default: `1`.
- **interim_results** (boolean) - Optional - Show partial transcripts while speaking. Default: `false`.
- **endpointing** (integer) - Optional - Silence duration (ms) before finalization. Default: `null`.
- **utterance_end_ms** (integer) - Optional - Detect end of utterance in milliseconds. Default: `null`.
- **vad_events** (boolean) - Optional - Enable Voice Activity Detection events. Default: `false`.
- **diarize** (boolean) - Optional - Enable speaker identification. Default: `false`.
- **punctuate** (boolean) - Optional - Enable automatic punctuation. Default: `false`.
- **keywords** (string) - Optional - Boost specific keywords (e.g., `deepgram:2`).
- **no_delay** (boolean) - Optional - Minimize latency, potentially reducing accuracy. Default: `false`.

### Request Body
None (audio is streamed via WebSocket)

### Request Example
None

### Response
#### Success Response (1000 - Continue)
- **type** (string) - Indicates the type of message received (e.g., `isFinal`, `metadata`, `speech_final`).
- **channel** (integer) - The audio channel the transcription belongs to.
- **transcript** (string) - The transcribed text.
- **is_final** (boolean) - True if this is the final transcription for the current segment.

#### Response Example
```json
{
  "type": "isFinal",
  "channel": 0,
  "transcript": "This is a test transcription.",
  "is_final": true
}
```

#### Error Response
- **error** (string) - Description of the error.

#### Error Response Example
```json
{
  "error": "Authentication failed"
}
```
```

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

### WebSocket /api/live-transcription

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

A bidirectional WebSocket endpoint for real-time audio streaming and transcription results.

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

### Description
Real-time bidirectional WebSocket endpoint that proxies audio data to Deepgram and returns transcription results. Authentication is handled via the WebSocket subprotocol header using the JWT token from /api/session.

### Endpoint
/api/live-transcription

### Query Parameters
- **model** (string) - Optional - Deepgram model (e.g., nova-2)
- **language** (string) - Optional - Language code (e.g., en)
- **smart_format** (boolean) - Optional - Enable smart formatting
- **interim_results** (boolean) - Optional - Get partial results
- **punctuate** (boolean) - Optional - Add punctuation
- **encoding** (string) - Optional - Audio encoding (e.g., linear16)
- **sample_rate** (integer) - Optional - Sample rate in Hz

### Response
#### Success Response (200)
- **type** (string) - Message type (Results or Error)
- **channel** (object) - Transcription channel data
- **is_final** (boolean) - Indicates if the transcript segment is final
```

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

### API Endpoints

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

Overview of the available API endpoints, their methods, authentication requirements, and purpose.

```APIDOC
## API Endpoints

| Endpoint | Method | Auth | Purpose |
|----------|--------|------|---------|
| `/api/session` | GET | None | Issue JWT session token |
| `/api/metadata` | GET | None | Return app metadata (useCase, framework, language) |
| `/api/live-transcription` | WS | JWT | Streams microphone audio to Deepgram for real-time transcription. |
```

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

### Request Session Token

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

Retrieve a JWT session token via the /api/session endpoint for WebSocket authentication.

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

# Response
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDk4..."
}
```

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