### Initialize and Start Project

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

Use these commands to initialize the project by cloning submodules and installing dependencies, then set up the environment by copying the sample .env file and setting your Deepgram API key, and finally 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 Backend and Frontend Dependencies

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

Instructions for installing backend and frontend dependencies. For the backend, Go modules are auto-downloaded on build. For the frontend, navigate to the `frontend` directory and run `corepack pnpm install`.

```bash
Install: go mod download
Frontend: cd frontend && corepack pnpm install
```

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

### Make Commands - Development Workflow

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

Provides a list of `make` commands for common development tasks, including setup, starting servers, building, and testing.

```APIDOC
## Make Commands - Development Workflow

The Makefile provides standardized commands for project setup, development, and maintenance.

### Available Commands
- **`make check-prereqs`**: Check prerequisites (git, go, pnpm).
- **`make init`**: Initialize project: clone submodules + install all dependencies.
- **`make start`**: Start development (both backend and frontend).
- **`make start-backend`**: Start backend server (Go server on http://localhost:8081).
- **`make start-frontend`**: Start frontend development server (Vite dev server on http://localhost:8080).
- **`make build`**: Build frontend for production.
- **`make test`**: Run contract conformance tests (requires running server).
- **`make update`**: Update submodules to latest commits.
- **`make clean`**: Clean build artifacts.
- **`make status`**: Show git and submodule status.
- **`make eject-frontend`**: Eject frontend from submodule to regular directory (irreversible).
```

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

### Start Backend and Frontend Separately

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

This demonstrates how to start the backend and frontend servers in separate terminals. The backend is run using `go run .`, and the frontend is started with `corepack pnpm run dev` after navigating to the frontend directory.

```bash
# Terminal 1 — Backend
go run .

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

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

### Initialize and Start the Application

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

Use the Makefile commands to set up the environment and launch the local development server.

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

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

### Configure Voice Models and Audio Parameters

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

Lists available Aura voice models and provides an example connection string with query parameters.

```bash
# Available voice models (aura-* series)
# aura-asteria-en   - English, female
# aura-luna-en      - English, female
# aura-stella-en    - English, female
# aura-athena-en    - English, female
# aura-hera-en      - English, female
# aura-orion-en     - English, male
# aura-arcas-en     - English, male
# aura-perseus-en   - English, male
# aura-angus-en     - English, male
# aura-orpheus-en   - English, male
# aura-helios-en    - English, male
# aura-zeus-en      - English, male

# Connect with different voice and encoding
ws://localhost:8081/api/live-text-to-speech?model=aura-orion-en&encoding=mp3&sample_rate=24000&container=none

# Parameter options:
# model       - Any aura-* voice
# encoding    - linear16, mp3, opus, mulaw, alaw
# sample_rate - 8000 to 48000
# container   - none, wav, ogg
```

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

### Conventional Commit Format Examples

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

Standardized commit message structure for project contributions.

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

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

### GET /api/metadata

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

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

```APIDOC
## GET /api/metadata

### Description
Returns project metadata from the deepgram.toml configuration file, including title, description, use case, language, framework, 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) - Backend framework
- **sdk** (string) - SDK information
- **tags** (array) - List of relevant tags

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

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

### Clean and Rebuild Project

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

This command removes the `node_modules` directory and `.vite` cache from the frontend, then re-initializes the project by cloning submodules and installing dependencies.

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

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

### GET /health

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

Returns the health status of the server.

```APIDOC
## GET /health

### Description
Returns a simple health status response indicating the server is running.

### Method
GET

### Endpoint
/health

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

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

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

### GET /api/session

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

Issues a signed JWT token for authenticating WebSocket connections. The token is valid for 1 hour and uses HS256 signing.

```APIDOC
## GET /api/session

### Description
Issues a signed JWT token for authenticating WebSocket connections. The token is valid for 1 hour and uses HS256 signing with the server's session secret.

### Method
GET

### Endpoint
/api/session

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

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

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

### Development Workflow Commands

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

Standardized Makefile commands for project initialization, building, and testing.

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

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

# Start development (both backend and frontend)
make start

# Start servers individually
make start-backend   # Go server on http://localhost:8081
make start-frontend  # Vite dev server on http://localhost:8080

# Build frontend for production
make build

# Run contract conformance tests (requires running server)
make test

# Update submodules to latest commits
make update

# Clean build artifacts
make clean

# Show git and submodule status
make status

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

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

### Deploy to Fly.io

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

Deploy the application to Fly.io using the `fly deploy` command. The `fly.toml` configuration file specifies app settings, region, and environment variables.

```bash
# Deploy to Fly.io
fly deploy
```

```toml
# fly.toml configuration reference:
app = 'go-live-text-to-speech'
primary_region = 'ord'
[http_service]
  internal_port = 8080
  force_https = true
[env]
  PORT = "8081"
  HOST = "0.0.0.0"
```

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

### Build and Run Docker Image

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

Build the Docker image for the application and run it as a container. Ensure to replace `your_api_key` and `your_secret` with your actual Deepgram API key and session secret.

```bash
# Build Docker image
docker build -f deploy/Dockerfile -t go-live-tts .

# Run container
docker run -p 8080:8080 \
  -e DEEPGRAM_API_KEY=your_api_key \
  -e SESSION_SECRET=your_secret \
  go-live-tts
```

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

### Configure Environment Variables

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

Defines required and optional environment variables for the backend server.

```bash
# sample.env - Copy to .env and configure

# Required: Your Deepgram API key
DEEPGRAM_API_KEY=your_api_key_here

# Optional: Backend server port (default: 8081)
PORT=8081

# Optional: Server bind address (default: 0.0.0.0)
HOST=0.0.0.0

# Optional: JWT signing secret (auto-generated if not set)
# Set explicitly in production for token validation across restarts
SESSION_SECRET=your_secret_here
```

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

### Testing and Endpoint Verification

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

Commands to execute conformance tests and verify API endpoints.

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

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

### Configuration - Environment Variables

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

Details the environment variables used to configure the backend server and Deepgram integration.

```APIDOC
## Configuration - Environment Variables

Configure the application through environment variables. The `DEEPGRAM_API_KEY` is required, while other settings have sensible defaults for development.

### Environment Variables
- **DEEPGRAM_API_KEY** (string) - Required - Your Deepgram API key.
- **PORT** (integer) - Optional - Backend server port (default: 8081).
- **HOST** (string) - Optional - Server bind address (default: 0.0.0.0).
- **SESSION_SECRET** (string) - Optional - JWT signing secret (auto-generated if not set). Set explicitly in production for token validation across restarts.

### Example (`.env` file)
```bash
DEEPGRAM_API_KEY=your_api_key_here
PORT=8081
HOST=0.0.0.0
SESSION_SECRET=your_secret_here
```
```

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

### Voice Models and Audio Parameters

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

Lists available voice models and explains the audio parameters that can be configured via query parameters for the WebSocket connection.

```APIDOC
## Voice Models and Audio Parameters

The WebSocket connection accepts query parameters to configure voice synthesis. Available Aura voices include various languages and styles. Audio encoding must match frontend playback configuration.

### Available Voice Models (Aura Series)
- `aura-asteria-en` - English, female
- `aura-luna-en` - English, female
- `aura-stella-en` - English, female
- `aura-athena-en` - English, female
- `aura-hera-en` - English, female
- `aura-orion-en` - English, male
- `aura-arcas-en` - English, male
- `aura-perseus-en` - English, male
- `aura-angus-en` - English, male
- `aura-orpheus-en` - English, male
- `aura-helios-en` - English, male
- `aura-zeus-en` - English, male

### Audio Parameter Options
- **model** (string) - Specifies the voice model.
- **encoding** (string) - Audio encoding format: `linear16`, `mp3`, `opus`, `mulaw`, `alaw`.
- **sample_rate** (integer) - Audio sample rate: 8000 to 48000.
- **container** (string) - Container format: `none`, `wav`, `ogg`.

### Example Connection String
```bash
ws://localhost:8081/api/live-text-to-speech?model=aura-orion-en&encoding=mp3&sample_rate=24000&container=none
```
```

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

### Connect to Live TTS WebSocket in JavaScript

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

Establishes an authenticated WebSocket connection to the TTS proxy and handles binary audio streaming and metadata messages.

```javascript
// JavaScript WebSocket client example
async function connectTTS() {
  // 1. Get session token
  const response = await fetch('http://localhost:8081/api/session');
  const { token } = await response.json();

  // 2. Connect WebSocket with authentication and TTS parameters
  const params = new URLSearchParams({
    model: 'aura-asteria-en',      // Voice model
    encoding: 'linear16',           // Audio encoding: linear16, mp3, opus, mulaw, alaw
    sample_rate: '48000',           // Sample rate: 8000-48000
    container: 'none'               // Container: none, wav, ogg
  });

  const ws = new WebSocket(
    `ws://localhost:8081/api/live-text-to-speech?${params}`,
    [`access_token.${token}`]       // JWT in subprotocol
  );

  // 3. Handle incoming audio data
  ws.onmessage = (event) => {
    if (event.data instanceof Blob) {
      // Binary audio data - process for playback
      event.data.arrayBuffer().then(buffer => {
        const int16Array = new Int16Array(buffer);
        // Convert Int16 PCM to Float32 for Web Audio API
        const float32Array = new Float32Array(int16Array.length);
        for (let i = 0; i < int16Array.length; i++) {
          float32Array[i] = int16Array[i] / 32768.0;
        }
        // Queue for AudioContext playback...
      });
    } else {
      // JSON metadata message
      console.log('Metadata:', JSON.parse(event.data));
    }
  };

  // 4. Send text for synthesis
  ws.onopen = () => {
    // Queue text for synthesis
    ws.send(JSON.stringify({ type: 'Speak', text: 'Hello, world!' }));
    ws.send(JSON.stringify({ type: 'Speak', text: 'This is streaming TTS.' }));

    // Flush buffer to signal end of text
    ws.send(JSON.stringify({ type: 'Flush' }));
  };

  return ws;
}

// WebSocket message types:
// { "type": "Speak", "text": "Hello world" }  - Queue text for synthesis
// { "type": "Flush" }                          - Signal end of text, flush audio buffer
// { "type": "Clear" }                          - Cancel pending audio
// { "type": "Close" }                          - Graceful disconnect
```

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

### API Endpoints

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

Overview of the available API endpoints for the Go Live Text-to-Speech application.

```APIDOC
## GET /api/session

### Description
Issues a JWT session token for authentication.

### Method
GET

### Endpoint
/api/session

### Parameters
None

### Request Example
None

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

#### Response Example
```json
{
  "token": "your_jwt_token"
}
```
```

```APIDOC
## GET /api/metadata

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

### Method
GET

### Endpoint
/api/metadata

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **useCase** (string) - The use case of the application.
- **framework** (string) - The backend framework used.
- **language** (string) - The programming language used.

#### Response Example
```json
{
  "useCase": "live-text-to-speech",
  "framework": "go",
  "language": "go"
}
```
```

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

### Description
Streams text to Deepgram for real-time audio generation using WebSockets. Authentication is handled via JWT session tokens using the `access_token.<jwt>` subprotocol.

### Method
WS (WebSocket)

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

### Parameters
#### Query Parameters
- **model** (string) - Optional - Voice selection. Defaults to `aura-asteria-en`.
- **encoding** (string) - Optional - Audio encoding. Defaults to `linear16`. Options: `linear16`, `mp3`, `opus`, `mulaw`, `alaw`.
- **sample_rate** (string) - Optional - Audio sample rate. Defaults to `48000`. Options: `8000`-`48000`.
- **container** (string) - Optional - Audio container. Defaults to `none`. Options: `none`, `wav`, `ogg`.

### Request Body
Client sends JSON messages to the server:
- `{ "type": "Speak", "text": "Hello world" }` — Queue text for synthesis.
- `{ "type": "Flush" }` — Signal end of text, flush audio buffer.
- `{ "type": "Clear" }` — Cancel pending audio.
- `{ "type": "Close" }` — Graceful disconnect.

### Request Example
```json
{
  "type": "Speak",
  "text": "This is a test message."
}
```

### Response
#### Success Response
- **Audio Chunks** (binary) - Server streams back binary audio data. If `container=none`, raw PCM data is sent. Otherwise, audio is encapsulated in the specified container format.

#### Response Example
(Binary audio data stream)
```

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

### Frontend Git Submodule Update Workflow

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

This outlines the process for modifying the frontend, which is managed as a git submodule. It involves editing files in the `frontend/` directory, committing changes within the submodule, pushing those changes, and then updating the submodule reference in the main project.

```bash
1. **Edit files in `frontend/`** — this is the working copy
2. **Test locally** — changes reflect immediately via Vite HMR
3. **Commit in the submodule:** `cd frontend && git add . && git commit -m "feat: description"`
4. **Push the frontend repo:** `cd frontend && git push origin main`
5. **Update the submodule ref:** `cd .. && git add frontend && git commit -m "chore(deps): update frontend submodule"`
```

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

### Request Project Metadata

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

Retrieve project metadata, including title, description, use case, language, and tags, from the `deepgram.toml` configuration file. This is useful for frontend display or API discovery.

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

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

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

### Stop All Running Servers

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

This command finds and kills processes listening on ports 8080 and 8081, effectively stopping both the frontend and backend servers.

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

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

### Health Check Endpoint

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

A simple health status endpoint that returns `{"status":"ok"}` to indicate the server is running. Useful for monitoring and orchestration systems.

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

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

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

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

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

Defines the JSON messages the client sends to the server to control text-to-speech synthesis. Includes commands for queuing text, flushing the buffer, clearing pending audio, and disconnecting.

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

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

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

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

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

### Request JWT Session Token

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

Use this endpoint to obtain a signed JWT token for authenticating WebSocket connections. The token is valid for 1 hour and uses HS256 signing.

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

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

# Use token in WebSocket connection (via subprotocol)
# WebSocket URL: ws://localhost:8081/api/live-text-to-speech?model=aura-asteria-en
# Subprotocol: access_token.<jwt_token>
```

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

### WebSocket TTS Proxy

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

Connects to the authenticated WebSocket endpoint for Deepgram's Live TTS API. Requires JWT authentication and supports various configuration parameters.

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

### Description
Authenticated WebSocket endpoint that proxies messages to Deepgram's Live TTS API. Requires JWT authentication via the `access_token.<jwt>` subprotocol. Supports configurable voice models, audio encoding, sample rates, and container formats through query parameters.

### Method
WS (WebSocket)

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

### Query Parameters
- **model** (string) - Optional - Specifies the voice model to use (e.g., `aura-asteria-en`).
- **encoding** (string) - Optional - Audio encoding format (e.g., `linear16`, `mp3`, `opus`, `mulaw`, `alaw`).
- **sample_rate** (integer) - Optional - Audio sample rate (e.g., 8000 to 48000).
- **container** (string) - Optional - Container format for audio (e.g., `none`, `wav`, `ogg`).

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

### Request Body (Messages)
- **{ "type": "Speak", "text": "Your text here" }** - Queues text for synthesis.
- **{ "type": "Flush" }** - Signals the end of text and flushes the audio buffer.
- **{ "type": "Clear" }** - Cancels pending audio.
- **{ "type": "Close" }** - Initiates a graceful disconnect.

### Response
- **Binary Blob**: Audio data.
- **JSON**: Metadata messages.

### Request Example (JavaScript)
```javascript
async function connectTTS() {
  const response = await fetch('http://localhost:8081/api/session');
  const { token } = await response.json();

  const params = new URLSearchParams({
    model: 'aura-asteria-en',
    encoding: 'linear16',
    sample_rate: '48000',
    container: 'none'
  });

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

  ws.onmessage = (event) => {
    if (event.data instanceof Blob) {
      // Process audio data
    } else {
      console.log('Metadata:', JSON.parse(event.data));
    }
  };

  ws.onopen = () => {
    ws.send(JSON.stringify({ type: 'Speak', text: 'Hello, world!' }));
    ws.send(JSON.stringify({ type: 'Flush' }));
  };

  return ws;
}
```
```

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