### Initialize and Start Application

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

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

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

### Install Dependencies and Start Servers with Node.js & pnpm

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

Clone the repository, install backend and frontend dependencies using pnpm, and configure your API key. Start both servers in separate terminals.

```bash
git clone --recurse-submodules https://github.com/deepgram-starters/node-transcription.git
cd node-transcription
pnpm install
cd frontend && pnpm install && cd ..
cp sample.env .env  # Add your DEEPGRAM_API_KEY
```

```bash
# Terminal 1 - Backend (port 8081)
node server.js

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

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

### Initialize and Start Project with Makefile

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

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

Commands to install backend and frontend dependencies using corepack pnpm.

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

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

### Start and Stop Commands

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

Utility commands for managing the application lifecycle, including starting, stopping, and rebuilding.

```bash
make start
```

```bash
# Terminal 1 — Backend
node server.js

# 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 node_modules frontend/node_modules frontend/.vite
make init
```

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

### Conventional Commit Examples

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

Standardized commit message formats for project contributions.

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

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

### Example Usage: Transcribe from URL

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

Demonstrates how to call the `transcribeFromUrl` function and log the resulting transcript to the console.

```javascript
const result = await transcribeFromUrl(
  "https://static.deepgram.com/examples/interview_speech-analytics.wav"
);
console.log(result.transcript);
```

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

### GET /api/metadata

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

Retrieves application metadata including title, description, SDK version, and tags defined in the configuration.

```APIDOC
## GET /api/metadata

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

### 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.
- **sdk** (string) - Deepgram SDK version.
- **tags** (array) - List of relevant tags.

#### Response Example
{
  "title": "Node Transcription",
  "description": "Get started using Deepgram's Transcription with this Node demo app",
  "sdk": "4.11.3",
  "tags": ["transcription", "stt"]
}
```

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

### Get Application Metadata

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

Retrieves configuration details from the deepgram.toml file, including SDK version and supported tags.

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

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

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

### Error Handling: Missing Authentication Token

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

Example of a `curl` command to trigger a 401 Unauthorized error due to a missing authentication token. The response indicates an `AuthenticationError` with code `MISSING_TOKEN`.

```bash
# Missing authentication token - returns 401
curl -X POST http://localhost:8081/api/transcription \
  -F "url=https://example.com/audio.wav"

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

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

### GET /api/session

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

Issues a signed JWT token required for authenticating subsequent transcription requests. Tokens are valid for 1 hour.

```APIDOC
## GET /api/session

### Description
Issues a signed JWT token for authenticating subsequent API requests.

### Method
GET

### Endpoint
/api/session

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

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

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

### Error Handling: Missing Input

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

Example of a `curl` command to trigger a 400 Bad Request error when neither a file nor a URL is provided. The response details a `ValidationError` with code `MISSING_INPUT`.

```bash
# Missing file or URL - returns 400
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN"

# Response:
# {
#   "error": {
#     "type": "ValidationError",
#     "code": "MISSING_INPUT",
#     "message": "Either file or url must be provided",
#     "details": {
#       "originalError": "Error: Either file or url must be provided"
#     }
#   }
# }
```

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

### Get Session Token

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

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

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

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

# Store token for subsequent requests
TOKEN=$(curl -s http://localhost:8081/api/session | jq -r '.token')
echo $TOKEN
```

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

### Error Handling: Expired Token

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

Example of an error response object for an expired authentication token. This would typically result in a 401 Unauthorized status code.

```json
# Expired token - returns 401
# {
#   "error": {
#     "type": "AuthenticationError",
#     "code": "INVALID_TOKEN",
#     "message": "Session expired, please refresh the page"
#   }
# }
```

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

### Configure Environment Variables

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

Sets up the application environment by copying the sample template and defining required API keys and server settings.

```bash
# Copy sample environment file
cp sample.env .env

# Required: Add your Deepgram API key
# Get your key at https://console.deepgram.com
DEEPGRAM_API_KEY=your_api_key_here

# Optional: Configure server port (default: 8081)
PORT=8081

# Optional: Configure server host (default: 0.0.0.0)
HOST=0.0.0.0

# Optional: Set session secret for production (auto-generated if not set)
SESSION_SECRET=your_secure_random_secret
```

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

### Testing Commands

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

Commands for running conformance tests and verifying API endpoint responses.

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

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

### Initialize Deepgram Client

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

Initialize the Deepgram client using your API key from environment variables. This is the first step before making any transcription requests.

```javascript
const { createClient } = require("@deepgram/sdk");

// Initialize Deepgram client with API key
const deepgram = createClient(process.env.DEEPGRAM_API_KEY);
```

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

### Transcribe Audio from URL

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

Transcribe audio directly from a given URL. Specify the desired transcription model, defaulting to 'nova-3'. Returns the transcript, word timings, and duration.

```javascript
async function transcribeFromUrl(audioUrl, model = "nova-3") {
  const response = await deepgram.listen.prerecorded.transcribeUrl(
    { url: audioUrl },
    { model }
  );

  const result = response.result?.results?.channels?.[0]?.alternatives?.[0];
  return {
    transcript: result.transcript,
    words: result.words,
    duration: response.result.metadata?.duration
  };
}
```

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

### Transcribe Audio from URL

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

Transcribes remote audio files using Deepgram's prerecorded API. Supports optional model selection via the model parameter.

```bash
# Transcribe audio from URL with default nova-3 model
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "url=https://static.deepgram.com/examples/interview_speech-analytics.wav"

# Response:
# {
#   "transcript": "This is the transcribed text from the audio...",
#   "words": [
#     { "word": "This", "start": 0.0, "end": 0.15, "confidence": 0.99 },
#     { "word": "is", "start": 0.15, "end": 0.25, "confidence": 0.98 }
#   ],
#   "duration": 45.5,
#   "metadata": {
#     "model_uuid": "abc123...",
#     "request_id": "xyz789...",
#     "model_name": "nova-3"
#   }
# }

# Use a specific model (nova-2, nova, enhanced, base)
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "url=https://example.com/audio.mp3" \
  -F "model=nova-2"
```

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

### Transcribe Audio from File Buffer

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

Transcribe audio from a file buffer. Requires the buffer, MIME type, and optionally a transcription model. Returns the transcript, word timings, and duration.

```javascript
async function transcribeFromFile(buffer, mimetype, model = "nova-3") {
  const response = await deepgram.listen.prerecorded.transcribeFile(buffer, {
    model,
    mimetype
  });

  const result = response.result?.results?.channels?.[0]?.alternatives?.[0];
  return {
    transcript: result.transcript,
    words: result.words,
    duration: response.result.metadata?.duration
  };
}
```

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

### Transcribe Audio from File Upload

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

Transcribes local audio files uploaded via multipart form data. Supports various formats including WAV, MP3, and FLAC.

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

# Transcribe with specific model
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@recording.mp3" \
  -F "model=nova-3"

# Response format is identical to URL transcription:
# {
#   "transcript": "Hello world this is a test recording...",
#   "words": [...],
#   "duration": 12.3,
#   "metadata": {
#     "model_uuid": "...",
#     "request_id": "...",
#     "model_name": "nova-3"
#   }
# }
```

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

### POST /api/transcription

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

Transcribes audio from either a remote URL or a local file upload. Supports model selection and returns transcription text with word-level timestamps.

```APIDOC
## POST /api/transcription

### Description
Transcribes audio from a remote URL or local file upload using Deepgram's transcription models.

### Method
POST

### Endpoint
/api/transcription

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

### Response
#### Success Response (200)
- **transcript** (string) - The full transcribed text.
- **words** (array) - List of words with start, end, and confidence scores.
- **duration** (number) - Duration of the audio in seconds.
- **metadata** (object) - Details about the model and request ID.

#### Response Example
{
  "transcript": "This is the transcribed text from the audio...",
  "words": [
    { "word": "This", "start": 0.0, "end": 0.15, "confidence": 0.99 }
  ],
  "duration": 45.5,
  "metadata": {
    "model_uuid": "abc123...",
    "request_id": "xyz789...",
    "model_name": "nova-3"
  }
}
```

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