### Initialize and Start Backend and Frontend Servers

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

Use this command to initialize the project, including cloning submodules and installing dependencies, then start both the backend and frontend servers.

```bash
make init
test -f .env || cp sample.env .env
make start
```

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

### Manage Project Initialization and Development

Source: https://context7.com/deepgram-starters/bun-live-text-to-speech/llms.txt

Provides Make commands for project setup, dependency installation, server execution, and testing.

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

# Initialize project: clone submodules + install all dependencies
make init

# Set up environment
cp sample.env .env
# Edit .env and add your DEEPGRAM_API_KEY

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

# Start servers separately
make start-backend   # Backend only on port 8081
make start-frontend  # Frontend only on port 8080

# Run conformance tests (requires running servers)
make test

# Update submodules to latest versions
make update

# Clean build artifacts
make clean

# Show git and submodule status
make status
```

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

### Start Backend Server Separately

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

Run this command in a dedicated terminal to start only the backend server using Bun.

```bash
bun run server.ts
```

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

### Install Backend and Frontend Dependencies

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

Install dependencies for both the backend (using Bun) and the frontend (using Bun for Vite).

```bash
bun install
cd frontend && bun install
```

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

### Initialize and Start Local Development

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

Use these commands to set up the environment and launch the application locally.

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

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

### Start Frontend Development Server Separately

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

Run this command in a dedicated terminal to start only the frontend development server using Vite. It specifies the port and disables automatic opening.

```bash
cd frontend && bun run dev -- --port 8080 --no-open
```

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

### Perform a Clean Rebuild

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

Execute this command to remove all installed dependencies and build artifacts, then re-initialize the project. This is useful for ensuring a clean state.

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

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

### GET /api/metadata

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

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

```APIDOC
## GET /api/metadata

### Description
Returns metadata about the application, such as the use case, framework, and programming language.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Success Response (200)
- **useCase** (string) - The application use case
- **framework** (string) - The backend framework
- **language** (string) - The programming language
```

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

### GET /api/session

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

Retrieves a JWT session token for authenticating WebSocket connections.

```APIDOC
## GET /api/session

### Description
Issues a JWT session token required for authenticating the WebSocket connection to the live text-to-speech service.

### Method
GET

### Endpoint
/api/session

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

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

### Configure Server Environment Variables

Source: https://context7.com/deepgram-starters/bun-live-text-to-speech/llms.txt

Defines required and optional environment variables for the backend server, including API keys and network settings.

```bash
# Create .env file from sample
cp sample.env .env

# Required configuration
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# Optional configuration (defaults shown)
PORT=8081                    # Backend server port
HOST=0.0.0.0                 # Server bind address
SESSION_SECRET=your_secret   # JWT signing secret (auto-generated if not set)
```

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

### Configure Audio Encoding Options

Source: https://context7.com/deepgram-starters/bun-live-text-to-speech/llms.txt

Set audio encoding format, sample rate, and container type for synthesized audio. Ensure frontend audio playback configuration matches these settings.

```javascript
// Supported encoding options
const encodingOptions = {
  encoding: ['linear16', 'mp3', 'opus', 'mulaw', 'alaw'],
  sample_rate: ['8000', '16000', '24000', '48000'],  // Hz
  container: ['none', 'wav', 'ogg']
};

// Example: MP3 encoding with WAV container
const wsUrl = new URL('ws://localhost:8081/api/live-text-to-speech');
wsUrl.searchParams.set('model', 'aura-asteria-en');
wsUrl.searchParams.set('encoding', 'mp3');
wsUrl.searchParams.set('sample_rate', '48000');
wsUrl.searchParams.set('container', 'wav');

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

// Important: When changing encoding or sample_rate, update frontend
// audio playback configuration to match
```

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

### Fetch Project Metadata

Source: https://context7.com/deepgram-starters/bun-live-text-to-speech/llms.txt

Retrieves project metadata, including title, description, and tags, from the deepgram.toml configuration file.

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

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

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

### Process Audio Playback with Web Audio API

Source: https://context7.com/deepgram-starters/bun-live-text-to-speech/llms.txt

Converts incoming Int16 PCM data to Float32 and manages sequential playback using the Web Audio API. Requires the client sample rate to match the server configuration.

```javascript
// Audio playback setup for Linear16 PCM at 24kHz
const audioContext = new AudioContext({ sampleRate: 24000 });
const audioQueue = [];
let isPlaying = false;

// Convert Int16 PCM to Float32 for Web Audio API
function int16ToFloat32(int16Array) {
  const float32Array = new Float32Array(int16Array.length);
  for (let i = 0; i < int16Array.length; i++) {
    float32Array[i] = int16Array[i] / 32768.0;
  }
  return float32Array;
}

// Process incoming audio data
socket.onmessage = (event) => {
  if (event.data instanceof ArrayBuffer) {
    const int16Data = new Int16Array(event.data);
    const float32Data = int16ToFloat32(int16Data);
    audioQueue.push(float32Data);

    if (!isPlaying) {
      playNextChunk();
    }
  }
};

// Play audio chunks sequentially
function playNextChunk() {
  if (audioQueue.length === 0) {
    isPlaying = false;
    return;
  }

  isPlaying = true;
  const audioData = audioQueue.shift();

  const buffer = audioContext.createBuffer(1, audioData.length, 24000);
  buffer.getChannelData(0).set(audioData);

  const source = audioContext.createBufferSource();
  source.buffer = buffer;
  source.connect(audioContext.destination);
  source.onended = playNextChunk;
  source.start();
}
```

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

### Testing and Endpoint Verification

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

Commands to execute conformance tests and manually verify API endpoints using curl.

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

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

### Update Frontend Submodule Reference

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

After making changes to the frontend code and committing them within the submodule, use these commands to stage and commit the updated submodule reference in the main project.

```bash
cd frontend && git add . && git commit -m "feat: description"
cd .. && git add frontend && git commit -m "chore(deps): update frontend submodule"
```

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

### Health Check Endpoint

Source: https://context7.com/deepgram-starters/bun-live-text-to-speech/llms.txt

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

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

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

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

### Configure Voice Model via WebSocket URL

Source: https://context7.com/deepgram-starters/bun-live-text-to-speech/llms.txt

Sets the voice model and audio parameters as query parameters in the WebSocket connection URL. Changing models requires a new connection.

```javascript
// Available Aura voice models (examples)
const voiceModels = [
  'aura-asteria-en',      // Default - Female English voice
  'aura-2-thalia-en',     // Thalia voice
  'aura-2-andromeda-en',  // Andromeda voice
];

// Connect with a specific voice model
const wsUrl = new URL('ws://localhost:8081/api/live-text-to-speech');
wsUrl.searchParams.set('model', 'aura-2-thalia-en');
wsUrl.searchParams.set('encoding', 'linear16');
wsUrl.searchParams.set('sample_rate', '24000');
wsUrl.searchParams.set('container', 'none');

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

// Note: To change voice mid-stream, you must disconnect and reconnect
// with a new model parameter
```

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

### WS /api/live-text-to-speech

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

WebSocket endpoint for streaming text to Deepgram and receiving real-time audio.

```APIDOC
## WS /api/live-text-to-speech

### Description
Streams text to Deepgram for real-time audio generation. Requires a JWT session token in the subprotocol (access_token.<jwt>).

### Method
WS

### Endpoint
/api/live-text-to-speech

### Request Body
- **type** (string) - Message type: "Speak", "Flush", "Clear", or "Close"
- **text** (string) - The text to synthesize (required for "Speak" type)

### Request Example
{
  "type": "Speak",
  "text": "Hello world"
}

### Response
#### Success Response
- **binary** (blob) - Raw PCM audio chunks (when container=none)
```

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

### Stop All Running Servers

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

This command identifies and terminates processes listening on ports 8080 and 8081, effectively stopping both backend and frontend servers.

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

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

### Control WebSocket Synthesis Commands

Source: https://context7.com/deepgram-starters/bun-live-text-to-speech/llms.txt

Sends JSON commands to the WebSocket to manage text-to-speech operations like speaking, flushing, clearing, or closing the connection.

```javascript
// Send text for synthesis (queues text for audio generation)
socket.send(JSON.stringify({
  type: 'Speak',
  text: 'This is the first sentence.'
}));

// Queue additional text
socket.send(JSON.stringify({
  type: 'Speak',
  text: 'This is the second sentence.'
}));

// Flush the buffer to receive all queued audio
socket.send(JSON.stringify({
  type: 'Flush'
}));

// Clear pending audio (cancel synthesis in progress)
socket.send(JSON.stringify({
  type: 'Clear'
}));

// Gracefully close the connection
socket.send(JSON.stringify({
  type: 'Close'
}));
```

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

### Connect to Live TTS WebSocket

Source: https://context7.com/deepgram-starters/bun-live-text-to-speech/llms.txt

Establishes a WebSocket connection to the Deepgram Live TTS API. Requires JWT authentication and supports various audio and voice parameters via query strings.

```javascript
// Browser JavaScript example for connecting to Live TTS WebSocket

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

// Step 2: Connect to WebSocket with authentication and parameters
const wsUrl = new URL('ws://localhost:8081/api/live-text-to-speech');
wsUrl.searchParams.set('model', 'aura-asteria-en');      // Voice model
wsUrl.searchParams.set('encoding', 'linear16');          // Audio encoding
wsUrl.searchParams.set('sample_rate', '24000');          // Sample rate in Hz
wsUrl.searchParams.set('container', 'none');             // Container format

const socket = new WebSocket(wsUrl.toString(), [`access_token.${token}`]);
socket.binaryType = 'arraybuffer';

// Step 3: Handle connection events
socket.onopen = () => {
  console.log('Connected to Live TTS');

  // Send text to synthesize
  socket.send(JSON.stringify({
    type: 'Speak',
    text: 'Hello, welcome to Deepgram Live Text-to-Speech!'
  }));

  // Flush to signal end of text and receive audio
  socket.send(JSON.stringify({ type: 'Flush' }));
};

socket.onmessage = (event) => {
  if (event.data instanceof ArrayBuffer) {
    // Binary audio data (PCM Int16 when encoding=linear16, container=none)
    const audioData = new Int16Array(event.data);
    console.log(`Received ${audioData.length} audio samples`);
    // Process audio for playback...
  } else {
    // JSON metadata messages
    const message = JSON.parse(event.data);
    console.log('Received message:', message);
  }
};

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

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

```

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

### Conventional Commits Format

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

Standardized commit message format for project contributions. Exclude Co-Authored-By lines when using Claude.

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

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

### Request Session Token

Source: https://context7.com/deepgram-starters/bun-live-text-to-speech/llms.txt

Use this endpoint to obtain a JWT session token for authenticating WebSocket connections. The token is signed server-side and has a 1-hour expiration.

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

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

# Store the token for WebSocket authentication
TOKEN=$(curl -s http://localhost:8081/api/session | jq -r '.token')
echo "Session token: $TOKEN"
```

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

### WebSocket Message Protocol for Text-to-Speech

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

Defines the JSON messages the client sends to the server to control text-to-speech synthesis and audio flushing. The server responds with binary audio chunks.

```json
{ "type": "Speak", "text": "Hello world" }
```

```json
{ "type": "Flush" }
```

```json
{ "type": "Clear" }
```

```json
{ "type": "Close" }
```

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

### Handle WebSocket Errors and Server Messages

Source: https://context7.com/deepgram-starters/bun-live-text-to-speech/llms.txt

Implement error handling for WebSocket connections and parse server error messages. Handle specific error codes for targeted responses.

```javascript
// Error message structure from server
interface ErrorMessage {
  type: 'Error';
  description: string;
  code: string;  // 'UNKNOWN_ERROR', 'PROVIDER_ERROR', etc.
}

socket.onmessage = (event) => {
  if (typeof event.data === 'string') {
    const message = JSON.parse(event.data);

    if (message.type === 'Error') {
      console.error(`TTS Error [${message.code}]: ${message.description}`);

      // Handle specific error codes
      switch (message.code) {
        case 'PROVIDER_ERROR':
          console.log('Deepgram connection issue - retrying...');
          break;
        case 'UNKNOWN_ERROR':
          console.log('Unexpected error occurred');
          break;
      }
    }
  }
};

// Handle connection errors
socket.onerror = (error) => {
  console.error('WebSocket connection error:', error);
};

// Handle unexpected disconnections
socket.onclose = (event) => {
  if (event.code !== 1000) {
    console.error(`Unexpected disconnect: ${event.code} - ${event.reason}`);
    // Implement reconnection logic if needed
  }
};
```

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