### Initialize and Start the Application

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

Commands to initialize submodules, install dependencies, and start 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 Application

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

Use 'make start' to run both the backend and frontend of the application, or 'make start-backend' to run only the backend server.

```bash
# Start the application (backend + frontend)
make start

# Or start backend only
make start-backend
```

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

### Start and Stop Commands

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

Individual commands for starting the backend and frontend separately, stopping all processes, or performing a clean rebuild.

```bash
make start
```

```bash
# Terminal 1 — Backend
bun run server.ts

# Terminal 2 — Frontend
cd frontend && bun 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
```

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

### Initialize and Start Transcription App

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

Use these make commands to initialize the project, set up your Deepgram API key, and start the local development server. Open http://localhost:8080 in your browser to access the app.

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

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

### Initialize Project Dependencies

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

Clone the repository, navigate to the directory, and use the 'make init' command to initialize submodules and install project dependencies.

```bash
# Clone the repository and initialize
git clone https://github.com/deepgram-starters/bun-transcription.git
cd bun-transcription

# Initialize submodules and install dependencies
make init
```

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

### Get Application Metadata

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

Retrieve metadata about the starter application, including its title, description, author, repository, and technical details like language and framework.

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

# Response
{
  "title": "Bun Transcription",
  "description": "Get started using Deepgram's speech-to-text with this Bun demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
  "repository": "https://github.com/deepgram-starters/bun-transcription",
  "useCase": "transcription",
  "language": "typescript",
  "framework": "bun",
  "tags": ["speech-to-text", "transcription", "prerecorded", "bun", "typescript"]
}
```

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

### Conventional Commits Examples

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

Examples of commit messages following the conventional commits format. Ensure all commits adhere to this standard for consistency.

```bash
feat(bun-transcription): add diarization support
```

```bash
fix(bun-transcription): resolve WebSocket close handling
```

```bash
refactor(bun-transcription): simplify session endpoint
```

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

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

### GET /api/metadata

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

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

```APIDOC
## GET /api/metadata

### Description
Returns app metadata such as useCase, framework, and language.

### Method
GET

### Endpoint
/api/metadata
```

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

### GET /api/metadata - Application Metadata

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

Retrieves metadata about the starter application, including its title, description, author, repository, use case, language, framework, and tags. This information is typically sourced from the application's 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) - The title of the application.
- **description** (string) - A brief description of the application.
- **author** (string) - Information about the author or team.
- **repository** (string) - URL to the application's source code repository.
- **useCase** (string) - The primary use case of the application.
- **language** (string) - The programming language used.
- **framework** (string) - The framework or runtime used.
- **tags** (array) - An array of relevant tags.

#### Response Example
```json
{
  "title": "Bun Transcription",
  "description": "Get started using Deepgram's speech-to-text with this Bun demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
  "repository": "https://github.com/deepgram-starters/bun-transcription",
  "useCase": "transcription",
  "language": "typescript",
  "framework": "bun",
  "tags": ["speech-to-text", "transcription", "prerecorded", "bun", "typescript"]
}
```
```

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

### GET /api/session

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

Issues a JWT session token for authentication.

```APIDOC
## GET /api/session

### Description
Issues a JWT session token for use in authenticated requests.

### Method
GET

### Endpoint
/api/session
```

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

### GET /health - Health Check

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

A simple health check endpoint designed for monitoring purposes and load balancer probes. It returns a status indicating whether the application is operational.

```APIDOC
## GET /health

### Description
Simple health check endpoint for monitoring and load balancer probes.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Indicates the health status of the application, typically 'ok'.

#### Response Example
```json
{
  "status": "ok"
}
```
```

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

### GET /api/session - Issue JWT Session Token

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

This endpoint issues a signed JWT session token. This token is required for authenticating subsequent API requests to the transcription service. Tokens have a validity period of 1 hour.

```APIDOC
## GET /api/session

### Description
Issues a signed JWT session token for authenticating subsequent API requests. Tokens expire after 1 hour.

### Method
GET

### Endpoint
/api/session

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

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

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

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

### Configure Environment Variables

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

Copy the sample environment file and add your Deepgram API key. Optional settings for port, host, and session secret are also available.

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

# Edit .env with your configuration
DEEPGRAM_API_KEY=your_api_key_here

# Optional settings (defaults shown)
PORT=8081
HOST=0.0.0.0
SESSION_SECRET=your_secret_for_production
```

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

### Project Management Commands

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

Use these Makefile commands to manage project dependencies, development servers, and build processes.

```makefile
make check-prereqs     # Check for required tools (git, bun)
make init              # Initialize submodules and install all dependencies
make install-backend   # Install backend dependencies only
make install-frontend  # Install frontend dependencies only

# Development commands
make start             # Start application (backend + frontend)
make start-backend     # Start backend only (port 8081)
make start-frontend    # Start frontend only (port 8080)
make build             # Build frontend for production
make test              # Run contract conformance tests

# Maintenance commands
make update            # Update submodules to latest commits
make clean             # Remove node_modules and build artifacts
make status            # Show git and submodule status
make eject-frontend    # Eject frontend submodule into regular directory
```

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

### Testing Commands for Bun Transcription

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

Commands to run conformance tests and manually check API endpoints. Ensure the application is running before executing these commands.

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

```bash
# Manual endpoint check
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

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

Transcribe audio by providing a URL to the audio file. This endpoint also requires JWT authentication and supports various transcription options via query parameters.

```bash
# Transcribe from a URL
curl -X POST "http://localhost:8081/api/transcription?model=nova-3&language=en" \
  -H "Authorization: Bearer $TOKEN" \
  -F "url=https://example.com/audio.mp3"
```

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

### Fetch API Integration for Transcription

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

Functions for retrieving session tokens and performing audio transcriptions via the local backend API.

```typescript
// Get session token
async function getSessionToken(): Promise<string> {
  const response = await fetch('http://localhost:8081/api/session');
  const data = await response.json();
  return data.token;
}

// Transcribe audio file
async function transcribeFile(file: File): Promise<TranscriptionResult> {
  const token = await getSessionToken();

  const formData = new FormData();
  formData.append('file', file);

  const response = await fetch(
    'http://localhost:8081/api/transcription?model=nova-3&language=en&smart_format=true',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`
      },
      body: formData
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

  return response.json();
}

// Transcribe from URL
async function transcribeUrl(audioUrl: string): Promise<TranscriptionResult> {
  const token = await getSessionToken();

  const formData = new FormData();
  formData.append('url', audioUrl);

  const response = await fetch(
    'http://localhost:8081/api/transcription?model=nova-3&diarize=true',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`
      },
      body: formData
    }
  );

  return response.json();
}

// Usage example
const fileInput = document.querySelector('input[type="file"]');
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  try {
    const result = await transcribeFile(file);
    console.log('Transcript:', result.transcript);
    console.log('Duration:', result.duration, 'seconds');
    console.log('Words:', result.words.length);
  } catch (error) {
    console.error('Transcription failed:', error.message);
  }
});
```

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

### Transcribe with Advanced Options

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

Utilize advanced transcription features like speaker diarization, punctuation, and paragraph detection by setting corresponding query parameters. Requires JWT authentication.

```bash
# With additional options (diarization, punctuation, paragraphs)
curl -X POST "http://localhost:8081/api/transcription?model=nova-3&language=en&smart_format=true&diarize=true&punctuate=true&paragraphs=true" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@meeting.wav"
```

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

### Error Response: Missing Input

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

This error is returned if neither a file upload nor a URL is provided for transcription.

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

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

### Transcribe Audio File Upload

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

Send an audio file for transcription using the POST /api/transcription endpoint. Requires JWT authentication via Bearer token. Supports query parameters for model, language, and smart formatting.

```bash
# Transcribe an audio file upload
curl -X POST "http://localhost:8081/api/transcription?model=nova-3&language=en&smart_format=true" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@audio.mp3"
```

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

### Health Check Endpoint

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

A simple health check endpoint that returns a status of 'ok'. Useful for monitoring and load balancer probes.

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

# Response
{
  "status": "ok"
}
```

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

### POST /api/transcription

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

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

```APIDOC
## POST /api/transcription

### Description
Transcribes audio files or URLs using Deepgram's pre-recorded API. Requires a valid JWT session token.

### Method
POST

### Endpoint
/api/transcription
```

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

### Request JWT Session Token

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

Use this endpoint to obtain a signed JWT session 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 the token for use in authenticated requests
TOKEN=$(curl -s http://localhost:8081/api/session | jq -r '.token')
```

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

### Successful Transcription Response

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

A typical success response includes the full transcript, word-level timing with confidence scores, and metadata about the transcription request.

```json
{
  "transcript": "Hello, this is a sample transcription.",
  "words": [
    {"word": "Hello", "start": 0.0, "end": 0.5, "confidence": 0.99},
    {"word": "this", "start": 0.6, "end": 0.8, "confidence": 0.98}
  ],
  "metadata": {
    "model_uuid": "abc123",
    "request_id": "req_xyz",
    "model_name": "nova-3"
  },
  "duration": 5.2
}
```

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

### POST /api/transcription - Transcribe Audio

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

The main transcription endpoint. It accepts audio data either through a file upload or a URL pointing to an audio file. This endpoint requires JWT authentication via a Bearer token in the Authorization header. Various transcription options can be specified as query parameters.

```APIDOC
## POST /api/transcription

### Description
Main transcription endpoint that accepts audio files or URLs and returns transcribed text with metadata. Requires JWT authentication via Bearer token.

### Method
POST

### Endpoint
/api/transcription

### Query Parameters
#### Query Parameters
- **model** (string) - Optional - Deepgram model: nova-3, nova-2, nova, enhanced, base. Defaults to 'nova-3'.
- **language** (string) - Optional - Language code for transcription. Defaults to 'en'.
- **smart_format** (boolean) - Optional - Enable smart formatting. Defaults to 'true'.
- **diarize** (boolean) - Optional - Enable speaker diarization. Defaults to 'false'.
- **punctuate** (boolean) - Optional - Enable punctuation. Defaults to 'false'.
- **paragraphs** (boolean) - Optional - Enable paragraph detection. Defaults to 'false'.
- **utterances** (boolean) - Optional - Enable utterance detection. Defaults to 'false'.
- **filler_words** (boolean) - Optional - Enable filler word detection. Defaults to 'false'.

### Parameters
#### Request Body
- **file** (file) - Required if url is not provided - The audio file to transcribe.
- **url** (string) - Required if file is not provided - The URL of the audio file to transcribe.

### Request Example
```bash
# Transcribe an audio file upload
curl -X POST "http://localhost:8081/api/transcription?model=nova-3&language=en&smart_format=true" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@audio.mp3"

# Transcribe from a URL
curl -X POST "http://localhost:8081/api/transcription?model=nova-3&language=en" \
  -H "Authorization: Bearer $TOKEN" \
  -F "url=https://example.com/audio.mp3"

# With additional options (diarization, punctuation, paragraphs)
curl -X POST "http://localhost:8081/api/transcription?model=nova-3&language=en&smart_format=true&diarize=true&punctuate=true&paragraphs=true" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@meeting.wav"
```

### Response
#### Success Response (200)
- **transcript** (string) - The transcribed text.
- **words** (array) - An array of word-level transcription results, each with 'word', 'start', 'end', and 'confidence'.
- **metadata** (object) - Metadata about the transcription request, including 'model_uuid', 'request_id', and 'model_name'.
- **duration** (number) - The duration of the audio in seconds.

#### Response Example
```json
{
  "transcript": "Hello, this is a sample transcription.",
  "words": [
    {"word": "Hello", "start": 0.0, "end": 0.5, "confidence": 0.99},
    {"word": "this", "start": 0.6, "end": 0.8, "confidence": 0.98}
  ],
  "metadata": {
    "model_uuid": "abc123",
    "request_id": "req_xyz",
    "model_name": "nova-3"
  },
  "duration": 5.2
}
```

#### Error Response
- **error** (object) - Contains details about the error.
  - **type** (string) - The type of error (e.g., 'AuthenticationError', 'ValidationError').
  - **code** (string) - A specific error code (e.g., 'MISSING_TOKEN', 'MISSING_INPUT').
  - **message** (string) - A human-readable error message.

#### Error Response Example (Missing Authentication)
```json
{
  "error": {
    "type": "AuthenticationError",
    "code": "MISSING_TOKEN",
    "message": "Authorization header with Bearer token is required"
  }
}
```

#### Error Response Example (Missing Input)
```json
{
  "error": {
    "type": "ValidationError",
    "code": "MISSING_INPUT",
    "message": "Either file or url must be provided"
  }
}
```
```

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

### Error Response: Missing Authentication

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

This error response is returned when the required JWT Bearer token is missing in the Authorization header.

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

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