### Bun Project Setup and Commands

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

Provides commands for initializing the project, installing dependencies, starting the backend and frontend servers, and performing maintenance tasks using Make or direct Bun commands.

```bash
# Quick start with Makefile
make init                    # Initialize submodules and install dependencies
cp sample.env .env           # Create environment file
# Edit .env and add DEEPGRAM_API_KEY

make start                   # Start both backend (8081) and frontend (8080)

# Individual server commands
make start-backend           # Start backend API server only
make start-frontend          # Start frontend dev server only

# Maintenance commands
make check-prereqs           # Verify git, bun, pnpm are installed
make update                  # Update submodules to latest commits
make clean                   # Remove node_modules and build artifacts
make status                  # Show git and submodule status
make build                   # Build frontend for production

# Direct Bun commands
bun install                  # Install backend dependencies
bun run server.ts            # Start backend server
bun --watch run server.ts    # Start with hot reload (dev mode)

```

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

### Initialize and Start the Application

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

Commands to initialize the project 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
```

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

### Install Dependencies

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

Commands to install dependencies for the backend and frontend.

```bash
bun install
Frontend: cd frontend && bun install
```

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

### Initialize and Start Bun Live Transcription App

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

Use this Makefile to set up your environment, add your Deepgram API key, and start the local development server. Open http://localhost:8080 in your browser.

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

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

### Commit Examples for Bun Live Transcription

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

Examples of conventional commit messages used in this project. Follow this format for all commits.

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

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

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

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

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

### Start and Stop Commands

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

Utility commands for managing the lifecycle of the development servers.

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

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

### GET /api/metadata - Project Metadata Endpoint

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

Returns metadata about the starter application from the `deepgram.toml` configuration file, including title, description, author, and supported use cases.

```APIDOC
## GET /api/metadata - Project Metadata Endpoint

### Description
Returns metadata about the starter application from the `deepgram.toml` configuration file, including title, description, author, and supported use cases.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Success Response (200)
- **title** (string) - The title of the project.
- **description** (string) - A brief description of the project.
- **author** (string) - The author of the project.
- **repository** (string) - The URL of the project repository.
- **useCase** (string) - The primary use case of the application.
- **language** (string) - The programming language used.
- **framework** (string) - The framework or runtime used.
- **sdk** (string) - The SDK used (if any).
- **tags** (array of strings) - Tags associated with the project.

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

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

### GET /health - Health Check Endpoint

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

A simple health check endpoint for monitoring and load balancer configurations.

```APIDOC
## GET /health - Health Check Endpoint

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

### Method
GET

### Endpoint
/health

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

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

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

### Stream Microphone Audio to Deepgram WebSocket

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

Captures microphone audio, processes it into linear16 format, and sends it as binary messages to a Deepgram WebSocket connection. Includes setup for audio context and handling transcription results.

```javascript
// Capture microphone audio and stream to WebSocket

async function startMicrophoneStreaming(ws) {
  // Get microphone access
  const stream = await navigator.mediaDevices.getUserMedia({
    audio: {
      channelCount: 1,
      sampleRate: 16000,
      echoCancellation: true,
      noiseSuppression: true
    }
  });

  // Create audio context for processing
  const audioContext = new AudioContext({ sampleRate: 16000 });
  const source = audioContext.createMediaStreamSource(stream);
  const processor = audioContext.createScriptProcessor(4096, 1, 1);

  processor.onaudioprocess = (event) => {
    if (ws.readyState === WebSocket.OPEN) {
      const inputData = event.inputBuffer.getChannelData(0);

      // Convert float32 to int16 (linear16 encoding)
      const int16Data = new Int16Array(inputData.length);
      for (let i = 0; i < inputData.length; i++) {
        int16Data[i] = Math.max(-32768, Math.min(32767, inputData[i] * 32768));
      }

      // Send binary audio data
      ws.send(int16Data.buffer);
    }
  };

  source.connect(processor);
  processor.connect(audioContext.destination);

  return { stream, audioContext, processor };
}

// Usage
const { token } = await fetch('http://localhost:8081/api/session').then(r => r.json());
const ws = new WebSocket('ws://localhost:8081/api/live-transcription', [`access_token.${token}`]);

ws.onopen = async () => {
  const audio = await startMicrophoneStreaming(ws);

  // Stop streaming after 30 seconds
  setTimeout(() => {
    audio.processor.disconnect();
    audio.stream.getTracks().forEach(track => track.stop());
    ws.close(1000, 'Finished');
  }, 30000);
};

ws.onmessage = (event) => {
  const result = JSON.parse(event.data);
  if (result.is_final && result.channel?.alternatives?.[0]?.transcript) {
    console.log('Final:', result.channel.alternatives[0].transcript);
  }
};

```

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

### GET /api/session - Session Token Endpoint

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

Issues a signed JWT session token for WebSocket authentication. Tokens expire after 1 hour and must be included in WebSocket connections via the subprotocol header.

```APIDOC
## GET /api/session - Session Token Endpoint

### Description
Issues a signed JWT session token for WebSocket authentication. Tokens expire after 1 hour and must be included in WebSocket connections via the subprotocol header.

### Method
GET

### Endpoint
/api/session

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

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

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

### Run Conformance Tests

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

Execute conformance tests for the application. Ensure the app is running before executing.

```bash
make test
```

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

### Configure Environment Variables

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

Set required API keys and optional server configurations in the .env file.

```bash
# Required - Your Deepgram API key
DEEPGRAM_API_KEY=your_api_key_here

# Optional configuration with defaults
PORT=8081           # Backend API server port
HOST=0.0.0.0        # Server host binding
SESSION_SECRET=your_secret_here  # JWT signing secret (auto-generated if not set)
```

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

### Connect to Live Transcription WebSocket

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

Establish a WebSocket connection with JWT authentication and configure transcription parameters via query strings.

```javascript
// Browser JavaScript - Connect to live transcription WebSocket

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

// Step 2: Connect WebSocket with token in subprotocol
const wsUrl = new URL('ws://localhost:8081/api/live-transcription');

// Configure transcription parameters (all optional, defaults shown)
wsUrl.searchParams.set('model', 'nova-3');        // Deepgram model
wsUrl.searchParams.set('language', 'en');         // Language code
wsUrl.searchParams.set('encoding', 'linear16');   // Audio encoding
wsUrl.searchParams.set('sample_rate', '16000');   // Sample rate in Hz
wsUrl.searchParams.set('channels', '1');          // Audio channels
wsUrl.searchParams.set('smart_format', 'true');   // Smart formatting
wsUrl.searchParams.set('punctuate', 'true');      // Add punctuation
wsUrl.searchParams.set('diarize', 'false');       // Speaker diarization

// Connect with JWT in subprotocol header
const ws = new WebSocket(wsUrl.toString(), [`access_token.${token}`]);

ws.onopen = () => {
  console.log('Connected to transcription service');
  // Start sending audio data...
};

ws.onmessage = (event) => {
  const result = JSON.parse(event.data);
  // Deepgram transcription result
  if (result.channel?.alternatives?.[0]?.transcript) {
    console.log('Transcript:', result.channel.alternatives[0].transcript);
  }
};

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

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

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

### Check Server Health

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

Verify the operational status of the backend server.

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

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

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

### Retrieve Project Metadata

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

Fetch application metadata defined in the deepgram.toml configuration file.

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

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

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

### Configure Deepgram Transcription Parameters

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

Demonstrates how to set various Deepgram transcription parameters, such as model, language, encoding, and sample rate, by building a WebSocket URL with query parameters.

```javascript
// All supported transcription parameters
const params = {
  // Required parameters (have defaults)
  model: 'nova-3',          // 'nova-3', 'nova-2', 'enhanced', 'base'
  language: 'en',           // ISO 639-1 language code
  encoding: 'linear16',     // 'linear16', 'flac', 'mulaw', 'amr-nb', 'amr-wb', 'opus', 'speex'
  sample_rate: '16000',     // Audio sample rate in Hz
  channels: '1',            // Number of audio channels
  smart_format: 'true',     // Apply smart formatting

  // Optional parameters (only sent if explicitly set)
  punctuate: 'true',        // Add punctuation to transcripts
  diarize: 'true',          // Enable speaker diarization
  filler_words: 'true'      // Include filler words (um, uh)
};

// Build URL with parameters
const url = new URL('ws://localhost:8081/api/live-transcription');
Object.entries(params).forEach(([key, value]) => {
  url.searchParams.set(key, value);
});

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

```

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

### WS /api/live-transcription - WebSocket Live Transcription

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

WebSocket endpoint for real-time audio transcription. Requires JWT authentication via the `access_token.<jwt>` subprotocol. Supports configurable transcription parameters passed as query strings.

```APIDOC
## WS /api/live-transcription - WebSocket Live Transcription

### Description
WebSocket endpoint for real-time audio transcription. Requires JWT authentication via the `access_token.<jwt>` subprotocol. Supports configurable transcription parameters passed as query strings.

### Method
WS (WebSocket)

### Endpoint
/api/live-transcription

### Query Parameters
- **model** (string) - Optional - The Deepgram transcription model to use (e.g., `nova-3`).
- **language** (string) - Optional - The language code for transcription (e.g., `en`).
- **encoding** (string) - Optional - The audio encoding format (e.g., `linear16`).
- **sample_rate** (integer) - Optional - The sample rate of the audio in Hz (e.g., `16000`).
- **channels** (integer) - Optional - The number of audio channels (e.g., `1`).
- **smart_format** (boolean) - Optional - Enable smart formatting (e.g., `true`).
- **punctuate** (boolean) - Optional - Enable punctuation (e.g., `true`).
- **diarize** (boolean) - Optional - Enable speaker diarization (e.g., `false`).

### Authentication
Requires JWT authentication via the `access_token.<jwt>` subprotocol in the WebSocket connection.

### Request Example
```javascript
// Browser JavaScript - Connect to live transcription WebSocket

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

// Step 2: Connect WebSocket with token in subprotocol
const wsUrl = new URL('ws://localhost:8081/api/live-transcription');

// Configure transcription parameters (all optional, defaults shown)
wsUrl.searchParams.set('model', 'nova-3');        // Deepgram model
wsUrl.searchParams.set('language', 'en');         // Language code
wsUrl.searchParams.set('encoding', 'linear16');   // Audio encoding
wsUrl.searchParams.set('sample_rate', '16000');   // Sample rate in Hz
wsUrl.searchParams.set('channels', '1');          // Audio channels
wsUrl.searchParams.set('smart_format', 'true');   // Smart formatting
wsUrl.searchParams.set('punctuate', 'true');      // Add punctuation
wsUrl.searchParams.set('diarize', 'false');       // Speaker diarization

// Connect with JWT in subprotocol header
const ws = new WebSocket(wsUrl.toString(), [`access_token.${token}`]);

ws.onopen = () => {
  console.log('Connected to transcription service');
  // Start sending audio data...
};

ws.onmessage = (event) => {
  const result = JSON.parse(event.data);
  // Deepgram transcription result
  if (result.channel?.alternatives?.[0]?.transcript) {
    console.log('Transcript:', result.channel.alternatives[0].transcript);
  }
};

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

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

### Response
#### Success Response (200)
- **channel** (object) - Contains transcription results.
  - **alternatives** (array) - An array of transcription alternatives.
    - **transcript** (string) - The transcribed text.

#### Response Example
```json
{
  "channel": {
    "alternatives": [
      {
        "transcript": "Hello world."
      }
    ]
  }
}
```
```

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

### Manual Endpoint Checks

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

Perform manual checks on the application's API endpoints using curl. The output is formatted with 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
```

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

### Request Session Token

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

Retrieve a signed JWT session token required for WebSocket authentication.

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

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

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