### Start Backend and Frontend Separately

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

Instructions for starting the backend and frontend servers in separate terminals if not using the `make start` command.

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

# Terminal 2 — Frontend
cd frontend && bun run dev -- --port 8080 --no-open
```

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

### Initialize and Start Project with Make

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

Use these make commands to clone, initialize, configure environment variables, and start the backend and frontend servers.

```bash
# Clone and initialize the project
make init

# Configure environment (add your Deepgram API key)
cp sample.env .env
# Edit .env and set DEEPGRAM_API_KEY=your_api_key_here

# Start both backend and frontend servers
make start

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

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

### Initialize and Start the Application

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

Use these commands to initialize dependencies, set up environment variables, and start both 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 Frontend Dependencies

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

Navigates to the frontend directory and installs its dependencies using the Bun package manager.

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

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

### Install Backend Dependencies

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

Installs dependencies for the Bun backend using the Bun package manager.

```bash
bun install
```

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

### Clean Rebuild Project Dependencies

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

Removes installed modules and Vite cache, then re-initializes the project. Useful for a fresh start.

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

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

### Initialize and Start Bun TTS App

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

Use this Makefile command to initialize the project, set up environment variables with your Deepgram API key, and start the local development server.

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

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

### Get Application Metadata (GET /api/metadata)

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

Returns metadata about the starter application, including title, description, author, repository, and tags, as configured in deepgram.toml.

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

# Response:
# {
#   "title": "Bun Text-to-Speech",
#   "description": "Get started using Deepgram's 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-text-to-speech",
#   "useCase": "text-to-speech",
#   "language": "typescript",
#   "framework": "bun",
#   "sdk": "4.11.3",
#   "tags": ["text-to-speech", "tts", "audio-generation", "typescript", "bun"]
# }
```

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

### Conventional Commits Examples

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

Examples of commit messages that adhere to the conventional commits format. This format helps in automating changelog generation and maintaining a consistent commit history.

```git
feat(bun-text-to-speech): add diarization support
```

```git
fix(bun-text-to-speech): resolve WebSocket close handling
```

```git
refactor(bun-text-to-speech): simplify session endpoint
```

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

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

### GET /api/metadata - Application Metadata

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

Returns metadata about the starter application from deepgram.toml configuration.

```APIDOC
## GET /api/metadata - Application Metadata

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

### 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) - The author of the application.
- **repository** (string) - The URL of the application's repository.
- **useCase** (string) - The primary use case of the application.
- **language** (string) - The programming language used.
- **framework** (string) - The framework used.
- **sdk** (string) - The version of the SDK used.
- **tags** (array of strings) - Tags associated with the application.

### Response Example
```json
{
  "title": "Bun Text-to-Speech",
  "description": "Get started using Deepgram's 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-text-to-speech",
  "useCase": "text-to-speech",
  "language": "typescript",
  "framework": "bun",
  "sdk": "4.11.3",
  "tags": ["text-to-speech", "tts", "audio-generation", "typescript", "bun"]
}
```
```

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

### Health Check Endpoint (GET /health)

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

A simple health check endpoint designed for monitoring and load balancer configuration, returning a status of 'ok'.

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

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

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

### Request Session Token (GET /api/session)

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

Obtain a signed JWT session token required for authenticated API calls. Tokens expire after 1 hour.

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

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

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

### GET /health - Health Check

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

Simple health check endpoint for monitoring and load balancer configuration.

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

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

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The status of the application, typically "ok".

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

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

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

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

Issues a signed JWT session token required for authenticated API calls. Tokens expire after 1 hour.

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

### Description
Issues a signed JWT session token required for authenticated API calls. Tokens expire after 1 hour.

### Method
GET

### Endpoint
/api/session

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

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

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

### API Error Response Format

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

API errors return a structured JSON response with error type, code, and message. Examples include validation and authentication errors.

```json
// Validation Error (400) - Empty or invalid text
{
  "error": {
    "type": "ValidationError",
    "code": "EMPTY_TEXT",
    "message": "Text parameter is required",
    "details": {
      "originalError": "Error: Text parameter is required"
    }
  }
}

// Authentication Error (401) - Missing or invalid token
{
  "error": {
    "type": "AuthenticationError",
    "code": "MISSING_TOKEN",
    "message": "Authorization header with Bearer token is required"
  }
}

// Error codes: EMPTY_TEXT, INVALID_TEXT, TEXT_TOO_LONG, MODEL_NOT_FOUND, INVALID_TOKEN, MISSING_TOKEN
```

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

### Run Conformance Tests

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

Execute the project's conformance tests. Ensure the application is running before executing this command.

```bash
make test
```

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

### Environment Configuration Variables

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

Configure the application using environment variables in the .env file. Ensure your Deepgram API key is set.

```bash
# Required - Get your API key at https://console.deepgram.com
DEEPGRAM_API_KEY=your_deepgram_api_key

# Optional - Server configuration
PORT=8081
HOST=0.0.0.0

# Optional - Session authentication (auto-generated in development)
SESSION_SECRET=your_session_secret_for_production
```

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

### Generate Speech with Deepgram SDK

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

Initializes the Deepgram client and provides a function to convert text to an audio buffer using the Aura model.

```typescript
import { createClient } from "@deepgram/sdk";

// Initialize the Deepgram client
const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

// Generate audio from text
async function generateSpeech(text: string, model: string = "aura-2-thalia-en") {
  const response = await deepgram.speak.request({ text }, { model });
  const stream = await response.getStream();

  if (!stream) {
    throw new Error("No audio stream returned from Deepgram");
  }

  // Convert stream to buffer
  const reader = stream.getReader();
  const chunks: Uint8Array[] = [];

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    chunks.push(value);
  }

  // Concatenate chunks into single buffer
  const totalLength = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
  const result = new Uint8Array(totalLength);
  let offset = 0;
  for (const chunk of chunks) {
    result.set(chunk, offset);
    offset += chunk.length;
  }

  return result;
}

// Usage
const audioBuffer = await generateSpeech("Hello, world!");
await Bun.write("output.mp3", audioBuffer);
```

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

### Convert Text to Audio (POST /api/text-to-speech)

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

Converts text to speech audio using Deepgram's TTS API. Requires authentication via Bearer token and returns binary audio data (audio/mpeg).

```bash
# First obtain a session token
TOKEN=$(curl -s http://localhost:8081/api/session | jq -r '.token')

# Convert text to speech (default model: aura-2-thalia-en)
curl -X POST http://localhost:8081/api/text-to-speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"text": "Hello, welcome to Deepgram text to speech!"}' \
  --output output.mp3

# Use a different voice model
curl -X POST "http://localhost:8081/api/text-to-speech?model=aura-2-andromeda-en" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"text": "This is a different voice model speaking."}' \
  --output output-andromeda.mp3

# Available models include:
# - aura-2-thalia-en (default)
# - aura-2-theia-en
# - aura-2-andromeda-en
# See: https://developers.deepgram.com/docs/text-to-speech-models
```

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

### Manual Endpoint Check: Metadata

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

Perform a manual check on the /api/metadata endpoint using curl and format the output with Python's JSON tool.

```bash
curl -sf http://localhost:8081/api/metadata | python3 -m json.tool
```

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

### POST /api/text-to-speech - Convert Text to Audio

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

Converts text to speech audio using Deepgram's TTS API. Requires authentication via Bearer token. Returns binary audio data (audio/mpeg).

```APIDOC
## POST /api/text-to-speech - Convert Text to Audio

### Description
Converts text to speech audio using Deepgram's TTS API. Requires authentication via Bearer token. Returns binary audio data (audio/mpeg).

### Method
POST

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

### Query Parameters
- **model** (string) - Optional - The voice model to use. Defaults to `aura-2-thalia-en`.

### Parameters
#### Request Body
- **text** (string) - Required - The text to convert to speech.

### Request Example
```json
{
  "text": "Hello, welcome to Deepgram text to speech!"
}
```

### Response
#### Success Response (200)
- **audio/mpeg** (binary) - The generated audio data.

### Example Usage
```bash
# First obtain a session token
TOKEN=$(curl -s http://localhost:8081/api/session | jq -r '.token')

# Convert text to speech (default model: aura-2-thalia-en)
curl -X POST http://localhost:8081/api/text-to-speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"text": "Hello, welcome to Deepgram text to speech!"}' \
  --output output.mp3

# Use a different voice model
curl -X POST "http://localhost:8081/api/text-to-speech?model=aura-2-andromeda-en" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"text": "This is a different voice model speaking."}' \
  --output output-andromeda.mp3
```

### Available Models
- aura-2-thalia-en (default)
- aura-2-theia-en
- aura-2-andromeda-en
See: https://developers.deepgram.com/docs/text-to-speech-models
```

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

### Manual Endpoint Check: Session

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

Perform a manual check on the /api/session endpoint using curl and format the output with Python's JSON tool.

```bash
curl -sf http://localhost:8081/api/session | python3 -m json.tool
```

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

### Stop All Running Servers

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

Command to forcefully stop processes listening on ports 8080 and 8081.

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

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

### Error Response Format

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

API errors return a structured JSON response with error type, code, and message.

```APIDOC
## Error Response Format

API errors return a structured JSON response with error type, code, and message.

### Validation Error (400)
```json
{
  "error": {
    "type": "ValidationError",
    "code": "EMPTY_TEXT",
    "message": "Text parameter is required",
    "details": {
      "originalError": "Error: Text parameter is required"
    }
  }
}
```

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

### Common Error Codes
- EMPTY_TEXT
- INVALID_TEXT
- TEXT_TOO_LONG
- MODEL_NOT_FOUND
- INVALID_TOKEN
- MISSING_TOKEN
```

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