### Project Setup with Makefile

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

Utilize Makefile commands for project initialization, starting servers, building, testing, and managing submodules. Ensure prerequisites like git, bun, and pnpm are installed.

```bash
# Check prerequisites (git, bun, pnpm)
make check-prereqs

# Initialize project (clone submodules + install dependencies)
make init

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

# Start servers individually
make start-backend   # Backend only
make start-frontend  # Frontend only

# Build frontend for production
make build

# Update git submodules to latest
make update

# Run contract conformance tests
make test

# Clean build artifacts
make clean

# Show repository and submodule status
make status

# Eject frontend from submodule to regular directory
make eject-frontend
```

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

### Initialize and Start Project

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

Commands to initialize submodules, install dependencies, and start the development 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 and Stop Servers

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

Commands for managing server lifecycles, including starting components separately and cleaning the build.

```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 Bun Flux App

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

Use this Makefile command to initialize the project, set up environment variables by copying the sample, and start the local development server.

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

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

### Configure Keyterms

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

Example of passing multiple keyterm parameters in a WebSocket query string.

```text
?keyterm=Deepgram&keyterm=Nova&keyterm=Aura
```

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

### Conventional Commits Examples

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

Examples of commit messages following the conventional commits format. This format helps in automating changelog generation and understanding commit history.

```git
feat(bun-flux): add diarization support
```

```git
fix(bun-flux): resolve WebSocket close handling
```

```git
refactor(bun-flux): simplify session endpoint
```

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

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

### GET /api/metadata

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

Retrieves project metadata parsed from the deepgram.toml configuration file.

```APIDOC
## GET /api/metadata

### Description
Returns project metadata including use case, framework, language, and tags.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Success Response (200)
- **title** (string) - Project title
- **description** (string) - Project description
- **author** (string) - Author information
- **repository** (string) - GitHub repository URL
- **useCase** (string) - Primary use case
- **language** (string) - Programming language
- **framework** (string) - Framework used
- **tags** (array) - List of relevant tags

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

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

### GET /health

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

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

```APIDOC
## GET /health

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

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The health status of the service.

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

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

### GET /api/session

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

Issues a signed JWT token required for authenticating WebSocket connections to the Flux transcription service.

```APIDOC
## GET /api/session

### Description
Issues a signed JWT token for authenticating WebSocket connections. Tokens expire after 1 hour and must be passed as a WebSocket subprotocol when connecting to the Flux endpoint.

### Method
GET

### Endpoint
/api/session

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

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

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

### Run Conformance Tests

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

Command to run conformance tests for the application. This requires the application to be running beforehand.

```bash
make test
```

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

### Configure Environment Variables

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

Set up your Deepgram API key and server configuration using a .env file. The SESSION_SECRET is optional and will be auto-generated if not provided.

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

# Optional - Server configuration
PORT=8081                    # Backend server port (default: 8081)
HOST=0.0.0.0                 # Bind address (default: 0.0.0.0)
SESSION_SECRET=your_secret   # JWT signing secret (auto-generated if not set)

# Copy sample.env to .env and configure
cp sample.env .env
```

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

### Retrieve Project Metadata

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

Fetch project configuration details including framework, language, and tags from the deepgram.toml file.

```bash
# Request metadata
curl -s http://localhost:8081/api/metadata | jq

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

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

### Commit Frontend Changes

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

Steps to commit and push changes made to the frontend submodule. Ensure you are in the correct directory before committing.

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

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

### Docker Deployment

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

Deploy the application using a Docker image with a Caddy reverse proxy. Set DEEPGRAM_API_KEY and SESSION_SECRET environment variables when running the container.

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

# Run the container
docker run -d \
  -p 8080:8080 \
  -e DEEPGRAM_API_KEY=your_api_key_here \
  -e SESSION_SECRET=your_production_secret \
  bun-flux

# The container runs:
# - Caddy reverse proxy on port 8080 (serves frontend + proxies /api to backend)
# - Bun backend on port 8081 (internal)
```

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

### Configure Flux API Parameters

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

Defines settings for audio encoding, end-of-turn detection, and custom vocabulary. Includes pre-configured query strings for low-latency, high-accuracy, and conversational AI use cases.

```javascript
// Flux parameter reference
const fluxParams = {
  // Audio encoding settings
  model: 'flux-general-en',      // Fixed to flux-general-en
  encoding: 'linear16',          // 'linear16' or 'opus'
  sample_rate: '16000',          // 8000-48000 Hz

  // End-of-turn detection tuning
  eot_threshold: '0.7',          // 0.0-1.0: Higher = more conservative (waits longer)
  eager_eot_threshold: '0.5',    // 0.0-1.0: Enable tentative end detection
  eot_timeout_ms: '5000',        // 0-30000: Silence timeout before auto-EOT

  // Custom vocabulary (can specify multiple)
  keyterm: ['Deepgram', 'Nova']  // Boost recognition of specific words
};

// Low-latency configuration (faster response, may cut off mid-sentence)
const lowLatencyParams = '?eot_threshold=0.3&eot_timeout_ms=2000';

// High-accuracy configuration (waits for complete utterances)
const highAccuracyParams = '?eot_threshold=0.9&eot_timeout_ms=8000';

// Conversational AI configuration (with eager detection for quick feedback)
const conversationalParams = '?eot_threshold=0.7&eager_eot_threshold=0.4&eot_timeout_ms=5000';
```

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

### Manual Endpoint Checks

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

Commands to manually check the `/api/metadata` and `/api/session` endpoints using curl. The output is formatted using Python's 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
```

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

### Perform Health Check

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

Verify service availability using the health check endpoint.

```bash
curl -s http://localhost:8081/health

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

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

### Connect to Deepgram Flux WebSocket API

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

Establishes a WebSocket connection to the Deepgram Flux API, including JWT authentication and configurable transcription parameters. Requires microphone access for audio streaming.

```javascript
// Complete WebSocket connection with Flux parameters
async function connectToFlux() {
  // Get session token
  const response = await fetch('http://localhost:8081/api/session');
  const { token } = await response.json();

  // Build WebSocket URL with Flux parameters
  const params = new URLSearchParams({
    encoding: 'linear16',
    sample_rate: '16000',
    eot_threshold: '0.7',          // End-of-turn confidence (0.0-1.0)
    eager_eot_threshold: '0.5',    // Tentative end-of-turn threshold
    eot_timeout_ms: '5000',        // Silence timeout in milliseconds
    keyterm: 'Deepgram'            // Custom vocabulary hint
  });

  // Add multiple keyterms
  params.append('keyterm', 'Nova');
  params.append('keyterm', 'Aura');

  const ws = new WebSocket(
    `ws://localhost:8081/api/flux?${params}`,
    [`access_token.${token}`]
  );

  ws.onopen = () => {
    console.log('Connected to Flux API');
    startAudioStream(ws);
  };

  ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    handleFluxEvent(data);
  };

  ws.onerror = (error) => console.error('WebSocket error:', error);
  ws.onclose = (event) => console.log(`Closed: ${event.code} ${event.reason}`);

  return ws;
}

// Handle Flux turn-based events
function handleFluxEvent(data) {
  switch (data.type) {
    case 'StartOfTurn':
      console.log('User started speaking');
      break;
    case 'Update':
      console.log('Interim transcript:', data.channel.alternatives[0].transcript);
      break;
    case 'EagerEndOfTurn':
      console.log('Tentative end detected (user might continue)');
      break;
    case 'TurnResumed':
      console.log('User continued speaking after pause');
      break;
    case 'EndOfTurn':
      console.log('Final transcript:', data.channel.alternatives[0].transcript);
      break;
  }
}

// Stream microphone audio to WebSocket
async function startAudioStream(ws) {
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  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);
      const pcm16 = new Int16Array(inputData.length);
      for (let i = 0; i < inputData.length; i++) {
        pcm16[i] = Math.max(-32768, Math.min(32767, inputData[i] * 32768));
      }
      ws.send(pcm16.buffer);
    }
  };

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

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

### Issue JWT Session Token

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

Request a session token for WebSocket authentication and pass it as a subprotocol when connecting to the Flux endpoint.

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

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

```javascript
// Using the token in JavaScript
const response = await fetch('http://localhost:8081/api/session');
const { token } = await response.json();

// Pass token as WebSocket subprotocol
const ws = new WebSocket('ws://localhost:8081/api/flux', [`access_token.${token}`]);
```

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