### Initialize and Start Servers (Bash)

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

Initializes the project by cloning submodules and installing dependencies, then sets up the environment by copying a sample .env file and starting 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 the Application

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

Use make commands to initialize the project dependencies and start the backend and frontend servers.

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

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

# Start both servers
make start
# Backend: http://localhost:8081
# Frontend: http://localhost:8080
```

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

### Start Backend and Frontend Separately (Bash)

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

Starts the backend application by running the compiled binary and then starts the frontend development server using Vite. Ensure the frontend is configured to run on port 8080 and to not automatically open in a browser.

```bash
# Terminal 1 — Backend
./build/app

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

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

### C++ Backend Configuration and Routing

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

Key configuration constants and route registration example for the C++ backend using the Crow framework. Demonstrates JWT expiry and dependency setup.

```cpp
// Key configuration constants in src/main.cpp
static const std::string DEFAULT_MODEL = "aura-2-thalia-en";  // Default TTS voice
static const int JWT_EXPIRY_SECONDS = 3600;                   // 1 hour token expiry

// Main dependencies (vcpkg.json):
// - crow: HTTP server framework
// - nlohmann-json: JSON parsing
// - openssl: JWT HMAC-SHA256 signing
// - curl: HTTP client for Deepgram API
// - tomlplusplus: TOML config parsing

// Route registration example
CROW_ROUTE(app, "/api/text-to-speech").methods(crow::HTTPMethod::POST)(
    [](const crow::request& req) {
        return handle_text_to_speech(req);
    });

// The handle_text_to_speech function:
// 1. Validates JWT Bearer token
// 2. Parses JSON body for "text" field
// 3. Calls Deepgram API via generate_audio()
// 4. Returns binary audio/mpeg data or structured error JSON

```

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

### Install Frontend Dependencies (Bash)

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

Navigates to the frontend directory and installs project dependencies using pnpm, as defined in the frontend's package.json file.

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

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

### Initialize and Start the C++ Application

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

Use these commands to initialize the project environment, configure the API key, and launch the application.

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

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

### Install Backend Dependencies (Bash)

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

Configures the build system using CMake, specifying the vcpkg toolchain for C++ dependency management, and then builds the project. Ensure the VCPKG_ROOT environment variable is set.

```bash
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" && cmake --build build
```

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

### Conventional Commit Examples

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

Standardized commit message formats for project contributions.

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

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

### Clean Rebuild Project (Bash)

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

Removes build artifacts, frontend node modules, and Vite cache, then re-initializes the project by cloning submodules and installing dependencies.

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

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

### GET /api/metadata

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

Returns project metadata 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) - Backend framework
- **tags** (array) - List of project tags

#### Response Example
{
  "title": "C++ Text-to-Speech Starter",
  "useCase": "text-to-speech",
  "language": "C++",
  "framework": "Crow"
}
```

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

### GET /health

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

Returns a simple health check response to verify the server is running.

```APIDOC
## GET /health

### Description
Returns a simple health check response to verify the server is running.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Server status

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

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

### Deepgram TTS API Audio Format Options

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

Example of how to modify the backend to pass custom audio format parameters to the Deepgram TTS API. Requires backend code changes.

```bash
# Example with custom encoding (requires backend modification to pass through params)
# The backend currently passes only the model parameter to Deepgram
# To add format options, modify the generate_audio function in src/main.cpp

# Current implementation in generate_audio():
# std::string url = "https://api.deepgram.com/v1/speak?model=" + model;

# To add encoding support, modify to:
# std::string url = "https://api.deepgram.com/v1/speak?model=" + model + "&encoding=mp3";
```

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

### GET /api/session

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

Issues a JWT session token for authenticating subsequent API calls. The token is valid for 1 hour and must be included as a Bearer token in the Authorization header.

```APIDOC
## GET /api/session

### Description
Issues a JWT session token for authenticating subsequent API calls.

### Method
GET

### Endpoint
/api/session

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

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

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

### Configure Environment Variables

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

Define the required API keys and server settings in the .env file.

```bash
# .env file example
DEEPGRAM_API_KEY=your_deepgram_api_key_here
PORT=8081
HOST=0.0.0.0
SESSION_SECRET=your_production_secret_here
```

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

### Retrieve Project Metadata

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

Fetch configuration details from the project's metadata endpoint.

```bash
# Get project metadata
curl -sf http://localhost:8081/api/metadata | jq

# Response:
# {
#   "title": "C++ Text-to-Speech Starter",
#   "description": "Get started using Deepgram's Text-to-Speech with this C++ demo app",
#   "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
#   "repository": "https://github.com/deepgram-starters/cpp-text-to-speech",
#   "useCase": "text-to-speech",
#   "language": "C++",
#   "framework": "Crow",
#   "sdk": "N/A",
#   "tags": ["text-to-speech", "tts", "audio-generation", "cpp", "crow"]
# }
```

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

### Project Testing Commands

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

Commands for running conformance tests and verifying 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
```

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

### Makefile Commands for Project Management

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

Standardized commands for building, running, and managing the C++ TTS application. Use these for development and deployment tasks.

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

```bash
# Initialize project with submodules and dependencies
make init
```

```bash
# Build C++ backend only
make install-backend
```

```bash
# Start both backend and frontend servers
make start
```

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

```bash
# Build frontend for production
make build
```

```bash
# Run contract conformance tests (requires running app)
make test
```

```bash
# Update submodules to latest commits
make update
```

```bash
# Clean all build artifacts
make clean
```

```bash
# Show git and submodule status
make status
```

```bash
# Eject frontend submodule for standalone development
make eject-frontend
```

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

### Configure CMake for C++ Text-to-Speech

Source: https://github.com/deepgram-starters/cpp-text-to-speech/blob/main/CMakeLists.txt

Defines project settings, finds required external libraries, and links them to the executable.

```cmake
cmake_minimum_required(VERSION 3.20)
project(cpp-text-to-speech LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Find dependencies via vcpkg
find_package(Crow CONFIG REQUIRED)
find_package(nlohmann_json CONFIG REQUIRED)
find_package(OpenSSL REQUIRED)
find_package(CURL REQUIRED)
find_package(tomlplusplus CONFIG REQUIRED)

add_executable(${PROJECT_NAME} src/main.cpp)

target_link_libraries(${PROJECT_NAME} PRIVATE
    Crow::Crow
    nlohmann_json::nlohmann_json
    OpenSSL::SSL
    OpenSSL::Crypto
    CURL::libcurl
    tomlplusplus::tomlplusplus
)
```

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

### Check Server Health

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

Verify that the backend server is operational.

```bash
# Check server health
curl -sf http://localhost:8081/health | jq

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

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

### Convert Text to Speech

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

Send text to the API to generate MP3 audio, optionally specifying a voice model.

```bash
# Get session token first
TOKEN=$(curl -sf http://localhost:8081/api/session | jq -r '.token')

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

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

# Available Aura 2 voices:
# aura-2-thalia-en (default), aura-2-andromeda-en, aura-2-arcas-en,
# aura-2-atlas-en, aura-2-luna-en, aura-2-orion-en, aura-2-stella-en, aura-2-zeus-en

# Error handling example - missing token
curl -X POST http://localhost:8081/api/text-to-speech \
  -H "Content-Type: application/json" \
  -d '{"text": "Test"}' 2>/dev/null | jq
# Response: {"error":{"type":"AuthenticationError","code":"MISSING_TOKEN","message":"Authorization header with Bearer token is required"}}

# Error handling example - empty text
curl -X POST http://localhost:8081/api/text-to-speech \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": ""}' 2>/dev/null | jq
# Response: {"error":{"type":"ValidationError","code":"EMPTY_TEXT","message":"Text parameter is required"}}
```

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

### Update Frontend Submodule (Bash)

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

Commits changes made to the frontend directory within the submodule, pushes these changes to the frontend's main branch, and then updates the main project's reference to the frontend submodule.

```bash
# Commit in the submodule:
cd frontend && git add . && git commit -m "feat: description"
# Push the frontend repo:
cd frontend && git push origin main
# Update the submodule ref:
cd .. && git add frontend && git commit -m "chore(deps): update frontend submodule"
```

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

### POST /api/text-to-speech

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

Handles text-to-speech generation requests by validating JWT tokens, parsing input text, and proxying the request to the Deepgram API.

```APIDOC
## POST /api/text-to-speech

### Description
Processes a text-to-speech request. The backend validates the JWT Bearer token, parses the JSON body for text, and calls the Deepgram API to generate audio.

### Method
POST

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

### Parameters
#### Request Body
- **text** (string) - Required - The text content to be converted into speech.

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

#### Error Response (4xx/5xx)
- **error** (object) - Returns a structured error object containing type, code, message, and details.
```

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

### Stop All Running Servers (Bash)

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

Stops all processes listening on ports 8080 and 8081 by finding their PIDs using lsof and then killing them. Redirects errors to /dev/null to suppress messages for non-existent processes.

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

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

### POST /api/text-to-speech

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

Converts text to speech audio using Deepgram's TTS API. Requires JWT authentication via Bearer token.

```APIDOC
## POST /api/text-to-speech

### Description
Converts text to speech audio using Deepgram's TTS API. Returns binary audio data in MP3 format.

### Method
POST

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

### Parameters
#### Query Parameters
- **model** (string) - Optional - The voice model to use (e.g., aura-2-thalia-en)

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

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

### Response
#### Success Response (200)
- **binary** (audio/mpeg) - MP3 audio data
```

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

### Request a Session Token

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

Retrieve a JWT session token required for authenticating with protected API endpoints.

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

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

# Store token for subsequent requests
TOKEN=$(curl -sf http://localhost:8081/api/session | jq -r '.token')
echo "Session token: $TOKEN"
```

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

### Error Response Format

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

Standardized JSON structure for API error reporting.

```APIDOC
## Error Response Format

### Description
All API errors follow a consistent contract-compliant JSON structure.

### Response Example
{
  "error": {
    "type": "ValidationError",
    "code": "EMPTY_TEXT",
    "message": "Human-readable error message",
    "details": {
      "originalError": "Original error details"
    }
  }
}
```

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

### Deepgram API Error Response Format

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

Standard JSON structure for API errors, including type, code, message, and details. Useful for handling and debugging issues.

```json
# Error response structure
{
  "error": {
    "type": "ValidationError",       # or "AuthenticationError", "GenerationError"
    "code": "EMPTY_TEXT",            # e.g., MISSING_TOKEN, INVALID_TOKEN, MODEL_NOT_FOUND, TEXT_TOO_LONG
    "message": "Human-readable error message",
    "details": {
      "originalError": "Original error details"
    }
  }
}

# Common error codes:
# MISSING_TOKEN - No Authorization header provided
# INVALID_TOKEN - JWT signature invalid or malformed
# EMPTY_TEXT - Text field missing or empty/whitespace only
# INVALID_TEXT - Request body not valid JSON
# MODEL_NOT_FOUND - Specified voice model doesn't exist
# TEXT_TOO_LONG - Input text exceeds length limits

```

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