### Install Frontend Dependencies

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

Navigate to the frontend directory and install its dependencies using pnpm.

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

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

### Initialize and Start Django App with Makefile

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

Use the Makefile for a streamlined local development setup. Ensure your DEEPGRAM_API_KEY is added to the .env file.

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

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

### Install Backend Dependencies

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

Create a Python virtual environment and install the backend dependencies listed in requirements.txt.

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

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

### Initialize and Start Django App

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

Use these make commands to initialize the project, set up the environment by copying the sample .env file, 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 Frontend Separately

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

Manually start the Vite development server for the frontend, specifying the port and disabling auto-opening.

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

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

### Start Django Backend Separately

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

Manually start the Django backend server using Daphne, specifying the host and port.

```bash
# Terminal 1 — Backend
./venv/bin/daphne -b 0.0.0.0 -p 8081 config.asgi:application
```

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

### Clone and Set Up Django Transcription Project

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

Clone the repository, set up a Python virtual environment, install dependencies, and install frontend dependencies. Remember to add your DEEPGRAM_API_KEY to the .env file.

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

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

### Conventional Commit Examples

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

Standardized commit message formats for the project.

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

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

### GET /api/metadata

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

Returns application configuration and metadata.

```APIDOC
## GET /api/metadata

### Description
Returns application configuration and metadata from the deepgram.toml file.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Success Response (200)
- **title** (string) - Application title
- **description** (string) - App description
- **author** (string) - Author information
- **repository** (string) - GitHub repository URL

#### Response Example
{
  "title": "Django Transcription",
  "description": "Get started using Deepgram's Transcription with this Django demo app"
}
```

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

### Start Frontend Development Server

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

Run the frontend development server using pnpm on port 8080. This command is intended to be run in a separate terminal.

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

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

### Start Django Backend Server

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

Run the Django backend server using Daphne on port 8081. This command is intended to be run in a separate terminal.

```bash
# Terminal 1 - Backend (port 8081)
./venv/bin/daphne -b 0.0.0.0 -p 8081 config.asgi:application
```

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

### GET /api/metadata

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

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

```APIDOC
## GET /api/metadata

### Description
This endpoint returns metadata about the application, such as its intended use case, the framework it's built on (e.g., Django), and the primary language.

### Method
GET

### Endpoint
/api/metadata

### Parameters
None

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

#### Response Example
```json
{
  "useCase": "Audio Transcription",
  "framework": "Django",
  "language": "Python"
}
```
```

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

### Get Application Metadata

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

Retrieves application configuration and metadata defined in deepgram.toml.

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

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

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

### GET /api/session

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

Issues a JWT session token for authentication.

```APIDOC
## GET /api/session

### Description
This endpoint issues a JSON Web Token (JWT) session token. This token is used to authenticate subsequent requests to protected API endpoints.

### Method
GET

### Endpoint
/api/session

### Parameters
None

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

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
```

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

### Configure Deepgram Features

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

Examples of parameters that can be added to the Deepgram API call options object to enable various features like language detection, diarization, punctuation, and summarization.

```json
{
  "language": "es",
  "diarize": true,
  "punctuate": true,
  "smart_format": true,
  "paragraphs": true,
  "utterances": true,
  "keywords": ["deepgram"],
  "redact": ["pci", "ssn"],
  "summarize": "v2",
  "topics": true,
  "detect_topics": true
}
```

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

### Get Session Token

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

Retrieves a JWT token required for authenticating subsequent API requests. Tokens are valid for one hour.

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

# Response
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDk4MzQyMDAsImV4cCI6MTcwOTgzNzgwMH0.abc123..."
}
```

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

### Clean Rebuild Project

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

Remove virtual environment, node modules, and Vite cache, then re-initialize the project.

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

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

### Run Tests and Check Endpoints

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

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

### Development Workflow Commands

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

Makefile commands for managing the development environment, running servers, and executing tests.

```bash
# Initialize the project (creates venv, installs dependencies)
make init

# Copy environment template and add your API key
cp sample.env .env
# Edit .env and set DEEPGRAM_API_KEY=your_key

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

# Start only the backend (for API development)
make start-backend

# Run contract conformance tests
make test

# Clean all build artifacts
make clean

# Check project and submodule status
make status
```

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

### Manage Frontend Submodule

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

Commands to update and commit changes 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"
```

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

### Configure Environment Variables

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

Defines required and optional settings in the .env file, including the Deepgram API key.

```bash
# .env configuration file

# Required - Your Deepgram API key from https://console.deepgram.com
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# Optional - Backend server configuration
PORT=8081
HOST=0.0.0.0

# Optional - Set in production for secure JWT session handling
SESSION_SECRET=your_random_secret_key_here
```

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

### Handle API Errors

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

Demonstrates structured error responses for authentication and validation failures.

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

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

# Validation error - missing required input
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer <valid-token>"
```

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

### Transcribe Audio from URL

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

Processes publicly accessible audio files via URL. Requires a valid session token in the Authorization header.

```bash
# Transcribe audio from URL
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer <your-session-token>" \
  -F "url=https://static.deepgram.com/examples/interview_speech-analytics.wav" \
  -F "model=nova-3"

# Response
{
  "transcript": "Hello, and welcome to today's interview discussion...",
  "words": [
    {"text": "Hello", "start": 0.0, "end": 0.42},
    {"text": "and", "start": 0.44, "end": 0.56},
    {"text": "welcome", "start": 0.58, "end": 0.92}
  ],
  "duration": 45.23,
  "metadata": {
    "model_uuid": "abc-123-def",
    "request_id": "req-456-ghi",
    "model_name": "nova-3"
  }
}
```

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

### Transcribe Local Audio File

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

Uploads and transcribes local audio files. Supports formats such as WAV, MP3, and FLAC.

```bash
# Transcribe uploaded audio file
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer <your-session-token>" \
  -F "file=@/path/to/audio.wav" \
  -F "model=nova-3"

# Response
{
  "transcript": "This is the transcribed text from your audio file.",
  "words": [
    {"text": "This", "start": 0.0, "end": 0.15},
    {"text": "is", "start": 0.17, "end": 0.25},
    {"text": "the", "start": 0.27, "end": 0.35}
  ],
  "duration": 12.5,
  "metadata": {
    "model_uuid": "abc-123-def",
    "request_id": "req-789-jkl",
    "model_name": "nova-3"
  }
}
```

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

### POST /api/transcription

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

Transcribes audio from a URL or a direct file upload using Deepgram's Nova models.

```APIDOC
## POST /api/transcription

### Description
Accepts a URL or a direct file upload to transcribe audio. Supports common formats like WAV, MP3, and FLAC.

### Method
POST

### Endpoint
/api/transcription

### Parameters
#### Request Body
- **url** (string) - Optional - URL of the audio file to transcribe
- **file** (binary) - Optional - Local audio file to upload
- **model** (string) - Required - The Deepgram model to use (e.g., nova-3)

### Response
#### Success Response (200)
- **transcript** (string) - The transcribed text
- **words** (array) - Word-level timestamps
- **duration** (number) - Duration of the audio in seconds
- **metadata** (object) - Request and model metadata

#### Response Example
{
  "transcript": "Hello, and welcome to today's interview discussion...",
  "words": [{"text": "Hello", "start": 0.0, "end": 0.42}],
  "duration": 45.23,
  "metadata": {"model_name": "nova-3"}
}
```

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

### API Endpoints

Source: https://github.com/deepgram-starters/django-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/transcription` | POST | JWT | Transcribes audio files or URLs using Deepgram's pre-recorded API. |
```

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

### Stop Running Servers

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

This command finds processes listening on ports 8080 and 8081 and terminates them.

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

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

### POST /api/transcription

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

Transcribes audio files or URLs using Deepgram's pre-recorded API. Requires JWT authentication.

```APIDOC
## POST /api/transcription

### Description
This endpoint processes audio data, either uploaded directly or provided via a URL, and transcribes it using Deepgram's speech-to-text capabilities. It requires a valid JWT token for authentication.

### Method
POST

### Endpoint
/api/transcription

### Parameters
#### Request Body
- **audio_file** (file) - Required - The audio file to transcribe.
- **audio_url** (string) - Optional - A URL pointing to the audio file to transcribe.

### Request Example
```json
{
  "audio_url": "http://example.com/audio.mp3"
}
```

### Response
#### Success Response (200)
- **transcript** (string) - The transcribed text.
- **metadata** (object) - Metadata about the transcription process.

#### Response Example
```json
{
  "transcript": "This is the transcribed text from the audio.",
  "metadata": {
    "duration": 10.5,
    "channels": 1
  }
}
```
```

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

### Deepgram Python Transcription Integration

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

Functions for transcribing audio from URLs or local files using the Deepgram SDK.

```python
import os
from deepgram import DeepgramClient
from dotenv import load_dotenv

load_dotenv()

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

# Transcribe from URL
def transcribe_url(audio_url: str, model: str = "nova-3"):
    response = deepgram.listen.v1.media.transcribe_url(
        url=audio_url,
        model=model,
        smart_format=True,
    )
    result = response.results.channels[0].alternatives[0]
    return {
        "transcript": result.transcript,
        "words": [
            {"text": w.word, "start": w.start, "end": w.end}
            for w in result.words
        ] if result.words else [],
        "duration": response.metadata.duration,
    }

# Transcribe from file
def transcribe_file(file_path: str, model: str = "nova-3"):
    with open(file_path, "rb") as audio_file:
        file_data = audio_file.read()

    response = deepgram.listen.v1.media.transcribe_file(
        request=file_data,
        model=model,
        smart_format=True,
    )
    result = response.results.channels[0].alternatives[0]
    return {
        "transcript": result.transcript,
        "words": [
            {"text": w.word, "start": w.start, "end": w.end}
            for w in result.words
        ] if result.words else [],
        "duration": response.metadata.duration,
    }

# Usage
transcript = transcribe_url("https://static.deepgram.com/examples/interview_speech-analytics.wav")
print(transcript["transcript"])
```

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

### API Error Response Format

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

The JSON structure returned by the API when a request fails validation.

```json
{
  "error": {
    "type": "ValidationError",
    "code": "INVALID_INPUT",
    "message": "Either 'file' or 'url' must be provided"
  }
}
```

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