### Manual project setup with Node.js and pnpm

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

Clone the repository and install dependencies for both the root and frontend directories manually.

```bash
git clone --recurse-submodules https://github.com/deepgram-starters/node-live-text-to-speech.git
cd node-live-text-to-speech
pnpm install
cd frontend && pnpm install && cd ..
cp sample.env .env  # Add your DEEPGRAM_API_KEY
```

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

### Initialize and Start Application

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

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

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

### Initialize and start project with Makefile

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

Use the provided Makefile to initialize the environment, configure the API key, and start the application.

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

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

### Install Dependencies

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

Commands to install backend and frontend dependencies using corepack pnpm.

```bash
corepack pnpm install
cd frontend && corepack pnpm install
```

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

### Start Backend and Frontend Separately

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

Instructions to start the Node.js backend and the Vite development server for the frontend independently.

```bash
# Terminal 1 — Backend
node server.js

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

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

### Run backend and frontend servers

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

Start the backend and frontend services in separate terminal sessions.

```bash
# Terminal 1 - Backend (port 8081)
node --no-deprecation server.js

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

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

### Conventional Commits Examples

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

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

```bash
feat(node-live-text-to-speech): add diarization support
```

```bash
fix(node-live-text-to-speech): resolve WebSocket close handling
```

```bash
refactor(node-live-text-to-speech): simplify session endpoint
```

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

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

### GET /api/metadata

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

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

```APIDOC
## GET /api/metadata

### Description
Returns project configuration from the deepgram.toml file.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Success Response (200)
- **title** (string) - Application 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
- **tags** (array) - List of relevant tags

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

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

### GET /api/session

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

Issues a JWT token required for authenticating WebSocket connections to the live TTS service. Tokens are valid for 1 hour.

```APIDOC
## GET /api/session

### Description
Issues a JWT token for authenticating WebSocket connections.

### Method
GET

### Endpoint
/api/session

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

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

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

### Manage Development with Makefile

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

Use these commands to initialize the project, manage dependencies, and run development servers.

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

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

# Copy sample.env to .env and add your DEEPGRAM_API_KEY
cp sample.env .env
# Edit .env and add your API key

# Start both backend and frontend servers in parallel
make start

# Or start servers individually
make start-backend   # Backend API on port 8081
make start-frontend  # Frontend dev server on port 8080

# Other useful commands
make update          # Update submodules to latest commits
make clean           # Remove node_modules and build artifacts
make status          # Show git and submodule status
make test            # Run contract conformance tests
```

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

### Deploy with Docker

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

Build and run the application using the provided multi-stage Dockerfile.

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

# Run container with environment variables
docker run -p 8080:8080 \
  -e DEEPGRAM_API_KEY=your_api_key \
  -e SESSION_SECRET=your_session_secret \
  deepgram-live-tts
```

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

### Run Conformance Tests

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

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

```bash
make test
```

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

### Deploy to Fly.io

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

Use the Fly CLI to authenticate, set secrets, and deploy the application.

```bash
# Install Fly CLI and authenticate
flyctl auth login

# Set secrets
flyctl secrets set DEEPGRAM_API_KEY=your_api_key
flyctl secrets set SESSION_SECRET=your_session_secret

# Deploy to Fly.io
flyctl deploy
```

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

### Configure Environment Variables

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

Set these variables in your .env file to configure the server port, host, and session security.

```text
PORT=8081                    # Backend API server port
HOST=0.0.0.0                 # Server host binding
SESSION_SECRET=your_secret   # JWT signing secret (auto-generated if not set)
```

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

### Configure WebSocket Query Parameters

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

Demonstrates how to programmatically construct the WebSocket URL with specific TTS configuration parameters.

```javascript
// Available WebSocket query parameters
const params = {
  model: 'aura-asteria-en',     // Voice model (default: aura-asteria-en)
  encoding: 'linear16',          // Audio encoding: linear16, mp3, opus, flac, aac (default: linear16)
  sample_rate: '48000',          // Sample rate in Hz (default: 48000)
  container: 'none'              // Container format: none, wav (default: none)
};

// Construct WebSocket URL with parameters
const url = new URL('ws://localhost:8081/api/live-text-to-speech');
url.searchParams.set('model', params.model);
url.searchParams.set('encoding', params.encoding);
url.searchParams.set('sample_rate', params.sample_rate);
url.searchParams.set('container', params.container);

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

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

### Clean Rebuild Project

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

Commands to remove build artifacts and node modules, then re-initialize the project.

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

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

### Retrieve Project Metadata

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

Fetches configuration details from the deepgram.toml file.

```bash
# Get project metadata
curl http://localhost:8081/api/metadata

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

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

### Set Environment Variables

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

Required configuration for the server to authenticate with Deepgram.

```bash
# Required environment variable
DEEPGRAM_API_KEY=your_deepgram_api_key_here
```

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

### Update Frontend Submodule

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

Steps to commit changes in the local frontend copy and update the 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"
```

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

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

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

WebSocket endpoint for real-time text-to-speech streaming. Requires JWT authentication via subprotocol and supports various audio configuration parameters.

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

### Description
Proxies messages between clients and Deepgram's TTS API for real-time audio synthesis.

### Method
WS

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

### Parameters
#### Query Parameters
- **model** (string) - Optional - Voice model (default: aura-asteria-en)
- **encoding** (string) - Optional - Audio encoding: linear16, mp3, opus, flac, aac (default: linear16)
- **sample_rate** (integer) - Optional - Sample rate in Hz (default: 48000)
- **container** (string) - Optional - Container format: none, wav (default: none)

### Request Example
// Connect with JWT token in subprotocol
const ws = new WebSocket('ws://localhost:8081/api/live-text-to-speech?model=aura-asteria-en', ['access_token.<token>']);

// Send text to synthesize
ws.send(JSON.stringify({
  type: 'Speak',
  text: 'Hello, this is a test.'
}));
```

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

### Connect to Live TTS WebSocket

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

Establishes a WebSocket connection using a JWT token and handles bidirectional communication for text synthesis and audio playback.

```javascript
// Client-side WebSocket connection example
const sessionResponse = await fetch('http://localhost:8081/api/session');
const { token } = await sessionResponse.json();

// Connect with JWT token in subprotocol
const ws = new WebSocket(
  'ws://localhost:8081/api/live-text-to-speech?model=aura-asteria-en&encoding=linear16&sample_rate=48000&container=none',
  [`access_token.${token}`]
);

ws.onopen = () => {
  console.log('Connected to TTS WebSocket');

  // Send text to synthesize
  ws.send(JSON.stringify({
    type: 'Speak',
    text: 'Hello, this is a test of Deepgram live text-to-speech.'
  }));
};

ws.onmessage = (event) => {
  if (event.data instanceof Blob) {
    // Binary audio data - play or process the audio
    const audioBlob = event.data;
    const audioUrl = URL.createObjectURL(audioBlob);
    const audio = new Audio(audioUrl);
    audio.play();
  } else {
    // JSON control message from Deepgram
    const message = JSON.parse(event.data);
    console.log('TTS event:', message);
  }
};

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

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

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

### Manual Endpoint Check with cURL

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

Perform manual checks on API endpoints using cURL and format the output with Python's JSON tool. These commands verify the /api/metadata and /api/session endpoints.

```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 via REST API

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

Use this endpoint to retrieve a JWT token required for authenticating WebSocket connections.

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

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

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

### Stop All Running Processes

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

A command to find and terminate processes listening on ports 8080 and 8081.

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

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

### WebSocket Message Protocol

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

Defines the JSON messages that the client sends to the server to control text-to-speech synthesis.

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

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

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

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

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