### Manual Project Setup

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

Perform a manual installation of the backend and frontend environments.

```bash
# Clone repository with submodules
git clone --recurse-submodules https://github.com/deepgram-starters/flask-transcription.git
cd flask-transcription

# Set up Python virtual environment
python3 -m venv venv
./venv/bin/pip install -r requirements.txt

# Install frontend dependencies
cd frontend && corepack pnpm install && cd ..

# Configure environment
cp sample.env .env
# Edit .env and add your DEEPGRAM_API_KEY

# Start backend (Terminal 1)
./venv/bin/python app.py

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

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

### Manual Environment Setup

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

Clone the repository and manually install Python and pnpm dependencies.

```bash
git clone --recurse-submodules https://github.com/deepgram-starters/flask-transcription.git
cd flask-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
```

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

### Install Dependencies

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

Commands to install backend and frontend dependencies.

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

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

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

### Initialize and Start via Makefile

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

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

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

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

### Initialize Project

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

Commands to clone submodules, install dependencies, and configure the environment.

```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
```

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

### GET /api/metadata

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

Returns metadata about the starter application from the configuration file.

```APIDOC
## GET /api/metadata

### Description
Returns metadata about the starter application from the deepgram.toml configuration file, including use case, framework, and SDK version information.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Success Response (200)
- **title** (string) - Application title
- **description** (string) - Application description
- **author** (string) - Author information
- **repository** (string) - GitHub repository URL
- **useCase** (string) - Primary use case
- **language** (string) - Programming language
- **framework** (string) - Web framework
- **sdk** (string) - SDK version
- **tags** (array) - List of relevant tags

#### Response Example
{
  "title": "Flask Transcription",
  "description": "Get started using Deepgram's Pre-Recorded Transcription with this Flask demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com>",
  "repository": "https://github.com/deepgram-starters/flask-transcription",
  "useCase": "transcription",
  "language": "python",
  "framework": "flask",
  "sdk": "6.0.0-rc.1",
  "tags": ["transcription", "stt"]
}
```

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

### Start and Stop Servers

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

Commands to manage the lifecycle of the backend and frontend servers.

```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
```

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

### Conventional Commits Examples

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

Examples of commit messages following the conventional commits format.

```git
feat(flask-transcription): add diarization support
```

```git
fix(flask-transcription): resolve WebSocket close handling
```

```git
refactor(flask-transcription): simplify session endpoint
```

```git
chore(deps): update frontend submodule
```

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

### Run Backend and Frontend Servers

Source: https://github.com/deepgram-starters/flask-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
```

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

### Customization Guide

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

Instructions on how to customize the transcription model, input modes, and response format.

```APIDOC
## Customization Guide

### Changing the Default Model
In the backend, find the `DEFAULT_MODEL` or `model` variable (typically near the top of the file or in the transcription handler). Change it to any supported model:
- `nova-3` (default, best accuracy)
- `nova-2` (previous generation)
- `base` (fastest, lower accuracy)

The frontend also has a model dropdown — update `frontend/main.js` if you want to change the default selection there.

### Changing Input Modes
The app supports two input modes:
1. **File upload** — User uploads an audio file
2. **URL** — User provides a URL to an audio file

To add a new pre-defined URL, edit `frontend/index.html` and add a radio button option.

### Modifying the Response Format
The `formatTranscriptionResponse()` function in the backend shapes what the frontend receives. You can include extra fields from Deepgram's response (words with timestamps, confidence scores, speaker labels, etc.).
```

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

### Get Application Metadata

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

Retrieves metadata about the starter application, including its use case, framework, and SDK version, from the deepgram.toml configuration.

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

# Response:
# {
#   "title": "Flask Transcription",
#   "description": "Get started using Deepgram's Pre-Recorded Transcription with this Flask demo app",
#   "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
#   "repository": "https://github.com/deepgram-starters/flask-transcription",
#   "useCase": "transcription",
#   "language": "python",
#   "framework": "flask",
#   "sdk": "6.0.0-rc.1",
#   "tags": ["transcription", "stt", "speech-to-text", "asr", "pre-recorded", "python", "flask"]
# }
```

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

### Error Response: Invalid Input

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

Example of an error response when required input parameters like 'file' or 'url' are missing. Returns a 400 status code.

```bash
# Missing file or URL (400):
# {
#   "error": {
#     "type": "ValidationError",
#     "code": "INVALID_INPUT",
#   }
# }
```

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

### Error Response: Missing or Invalid Token

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

Example of an error response when the authentication token is missing or invalid. Returns a 401 status code.

```bash
# Missing or invalid token
curl -X POST http://localhost:8081/api/transcription \
  -F "url=https://example.com/audio.mp3"

# Response (401):
# {
#   "error": {
#     "type": "AuthenticationError",
#     "code": "MISSING_TOKEN",
#     "message": "Authorization header with Bearer token is required"
#   }
# }

# Expired token response (401):
# {
#   "error": {
#     "type": "AuthenticationError",
#     "code": "INVALID_TOKEN",
#     "message": "Session expired, please refresh the page"
#   }
# }
```

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

### GET /api/session

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

Issues a JWT token for authenticating subsequent API requests. Tokens expire after 1 hour.

```APIDOC
## GET /api/session

### Description
Issues a JWT token for authenticating subsequent API requests. Tokens expire after 1 hour and must be included in the Authorization header for protected endpoints.

### Method
GET

### Endpoint
/api/session

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

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

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

### Get Session Token

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

Requests a JWT token for authenticating subsequent API requests. Tokens expire after 1 hour.

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

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

# Store token for use in subsequent requests
TOKEN=$(curl -s http://localhost:8081/api/session | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")
```

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

### Manage Project with Makefile

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

Use Makefile commands to initialize dependencies, run servers, and execute tests.

```bash
# Initialize project (install all dependencies)
make init

# Start both backend and frontend servers
make start
# Backend: http://localhost:8081
# Frontend: http://localhost:8080

# Start only the backend
make start-backend

# Start only the frontend
make start-frontend

# Run contract conformance tests
make test

# Clean build artifacts
make clean

# Update git submodules
make update

# Check project status
make status
```

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

### Configure Environment Variables

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

Set up the required API keys and server configuration using a .env file.

```bash
# Create .env file from template
cp sample.env .env

# Required configuration
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# Optional configuration (defaults shown)
PORT=8081                    # Backend server port
HOST=0.0.0.0                 # Backend bind address
SESSION_SECRET=your_secret   # JWT signing secret (auto-generated if not set)
FLASK_DEBUG=0                # Set to 1 for debug mode
```

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

### Deploy with Docker

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

Build and run the application container with required environment variables.

```bash
# Build the Docker image
docker build -f deploy/Dockerfile -t flask-transcription .

# Run with environment variables
docker run -p 8080:8080 \
  -e DEEPGRAM_API_KEY=your_api_key \
  -e SESSION_SECRET=your_session_secret \
  flask-transcription

# Access the application at http://localhost:8080
```

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

### Run Conformance Tests

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

Command to execute conformance tests for the application. Requires the app to be running.

```bash
make test
```

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

### Commit Frontend Changes

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

Steps to commit and push changes made to the frontend 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"
```

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

### Transcribe Audio from URL (Default Model)

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

Transcribes audio from a publicly accessible URL using the default nova-3 model. Deepgram fetches the audio directly. Requires authentication.

```bash
# Transcribe audio from a URL
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "url=https://static.deepgram.com/examples/interview_speech-analytics.wav"
```

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

### Transcribe Audio File (Default Model)

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

Transcribes an uploaded audio file using Deepgram's pre-recorded speech-to-text API with the default nova-3 model. Requires authentication.

```bash
# Transcribe an audio file with default model (nova-3)
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/audio.mp3"
```

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

### Manual Endpoint Checks

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

Commands to manually check the /api/metadata and /api/session endpoints using curl and json_tool.

```bash
curl -sf http://localhost:8081/api/metadata | python3 -m json.tool
```

```bash
curl -sf http://localhost:8081/api/session | python3 -m json.tool
```

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

### Transcribe Audio from URL (Specific Model)

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

Transcribes audio from a URL using a specified Deepgram model. Requires authentication.

```bash
# Using a different model with URL transcription
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "url=https://example.com/audio.mp3" \
  -F "model=base"
```

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

### Configure Caddy Rate Limiting

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

Define rate limiting zones for API and session endpoints in the Caddyfile.

```caddyfile
{
    order rate_limit before basicauth
}

:8080 {
    # Session endpoint: 5 requests/minute per IP
    handle /api/session {
        rate_limit {
            zone session {
                key {remote_host}
                events 5
                window 1m
            }
        }
        reverse_proxy localhost:8081
    }

    # API endpoints: 120 requests/minute per IP
    handle /api/* {
        rate_limit {
            zone api {
                key {remote_host}
                events 120
                window 1m
            }
        }
        reverse_proxy localhost:8081
    }

    # Static assets
    handle {
        root * /app/frontend/dist
        file_server
    }
}
```

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

### Transcribe Audio File (Specific Model)

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

Transcribes an uploaded audio file using a specified Deepgram model. Requires authentication.

```bash
# Transcribe with a specific model
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/audio.wav" \
  -F "model=nova-2"
```

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

### Transcribe Audio Files and URLs

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

Use the Deepgram Python SDK to process local audio files or remote URLs.

```python
from deepgram import DeepgramClient
import os

# Initialize Deepgram client
api_key = os.environ.get("DEEPGRAM_API_KEY")
deepgram = DeepgramClient(api_key=api_key)

# Read audio file
with open("audio.mp3", "rb") as audio_file:
    file_content = audio_file.read()

# Transcribe with options
response = deepgram.listen.v1.media.transcribe_file(
    request=file_content,
    model="nova-3",           # Options: nova-3, nova-2, nova, enhanced, base
    smart_format=True,        # Format numbers, dates, etc.
)

# Access transcription results
result = response.results.channels[0].alternatives[0]
print(f"Transcript: {result.transcript}")
print(f"Confidence: {result.confidence}")
print(f"Duration: {response.metadata.duration}s")

# Access word-level timestamps
for word in result.words:
    print(f"  {word.word}: {word.start}s - {word.end}s")
```

```python
from deepgram import DeepgramClient

deepgram = DeepgramClient(api_key="your_api_key")

# Transcribe from URL
response = deepgram.listen.v1.media.transcribe_url(
    url="https://static.deepgram.com/examples/interview_speech-analytics.wav",
    model="nova-3",
    smart_format=True,
)

# Extract transcript
transcript = response.results.channels[0].alternatives[0].transcript
print(transcript)

# Access metadata
print(f"Request ID: {response.metadata.request_id}")
print(f"Model UUID: {response.metadata.model_uuid}")
```

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

### POST /api/transcription

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

Transcribes an audio file or audio from a URL using Deepgram's pre-recorded speech-to-text API.

```APIDOC
## POST /api/transcription

### Description
Transcribes an uploaded audio file or audio from a publicly accessible URL using Deepgram's pre-recorded speech-to-text API.

### Method
POST

### Endpoint
/api/transcription

### Parameters
#### Request Body
- **file** (binary) - Optional - Audio file for upload
- **url** (string) - Optional - Publicly accessible URL of the audio file
- **model** (string) - Optional - Deepgram model name (e.g., nova-3, nova-2, base)

### Response
#### Success Response (200)
- **transcript** (string) - The transcribed text
- **words** (array) - List of word objects with timestamps
- **duration** (float) - Duration of the audio
- **metadata** (object) - Request and model metadata

#### Response Example
{
  "transcript": "Hello, this is a test recording.",
  "words": [
    {"text": "Hello", "start": 0.0, "end": 0.5, "speaker": null}
  ],
  "duration": 2.5,
  "metadata": {
    "model_uuid": "abc123",
    "request_id": "xyz789",
    "model_name": "nova-3"
  }
}
```

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

### API Endpoints

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

Overview of the available API endpoints for the Flask transcription application.

```APIDOC
## API Endpoints

### GET /api/session

#### Description
Issue JWT session token.

#### Method
GET

#### Endpoint
/api/session

### GET /api/metadata

#### Description
Return app metadata (useCase, framework, language).

#### Method
GET

#### Endpoint
/api/metadata

### POST /api/transcription

#### Description
Transcribes audio files or URLs using Deepgram's pre-recorded API.

#### Method
POST

#### Endpoint
/api/transcription

#### Auth
JWT
```

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

### Deepgram Features for Transcription

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

Details on how to enable and configure various Deepgram features for audio transcription.

```APIDOC
## Adding Deepgram Features

The transcription API accepts many options. Add them to the options object passed to the SDK or API call:

| Feature | Parameter | Example Value | Effect |
|---------|-----------|---------------|--------|
| Language | `language` | `"es"`, `"fr"` | Transcribe non-English audio |
| Diarization | `diarize` | `true` | Identify different speakers |
| Punctuation | `punctuate` | `true` | Add punctuation to transcript |
| Smart Format | `smart_format` | `true` | Format numbers, dates, etc. |
| Paragraphs | `paragraphs` | `true` | Add paragraph breaks |
| Utterances | `utterances` | `true` | Split by speaker turns |
| Keywords | `keywords` | `["deepgram"]` | Boost specific terms |
| Redaction | `redact` | `["pci", "ssn"]` | Redact sensitive data |
| Summarize | `summarize` | `"v2"` | Add a summary |
| Topics | `topics` | `true` | Detect topics |
| Sentiment | `detect_topics` | `true` | Detect sentiment |

**Backend change:** Add parameters to the SDK call options object or API query string.

**Frontend change (optional):** Add UI controls (checkboxes, dropdowns) in `frontend/main.js` and pass them as form data or query parameters.
```

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