### Initialize and Start Server (Makefile)

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

Recommended way to set up and run the Deno backend and frontend servers using the provided Makefile. Includes initialization, environment setup, and starting the servers.

```bash
# Using Makefile (recommended)
make init                    # Initialize submodules and dependencies
cp sample.env .env           # Configure your DEEPGRAM_API_KEY
make start                   # Start both backend and frontend servers

# Or start servers individually
make start-backend           # Start backend only (port 8081)
make start-frontend          # Start frontend only (port 8080)
```

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

### Manual project setup with Deno and pnpm

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

Clone the repository and install frontend dependencies manually before configuring the environment variables.

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

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

### Initialize and Start the Application

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

Commands to clone submodules, install dependencies, configure the environment, and launch 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/deno-text-to-speech/blob/main/README.md

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

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

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

### Install Dependencies

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

Commands to install dependencies for the backend and frontend components.

```bash
# Deno auto-resolves deps on first run
```

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

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

### Start Server Directly with Deno

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

Alternative method to start the Deno backend server using direct Deno execution commands. Supports watch mode for development.

```bash
# Using Deno directly
deno run --allow-net --allow-read --allow-env server.ts

# With watch mode for development
deno run --allow-net --allow-read --allow-env --watch server.ts
```

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

### Start and Stop Commands

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

Utility commands for managing the application lifecycle, including starting components individually and cleaning the build.

```bash
make start
```

```bash
# Terminal 1 — Backend
deno task start

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

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

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

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

### Conventional Commits Examples

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

Follow these examples for commit messages to maintain a consistent commit history.

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

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

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

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

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

### Run backend and frontend servers

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

Start the Deno backend and the pnpm frontend development server in separate terminal sessions.

```bash
# Terminal 1 - Backend (port 8081)
deno run --allow-net --allow-read --allow-env server.ts

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

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

### Get API Metadata

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

Retrieves metadata about the starter application, including its title, description, author, and tags, from the deepgram.toml configuration.

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

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

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

### Deno Tasks for Server Management

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

Utilize Deno tasks for common server operations like starting, running with watch mode, type-checking, and caching dependencies.

```bash
# Using Deno tasks
deno task start              # Start server
deno task start-backend      # Start with watch mode
deno task check              # Type-check server.ts
deno task cache              # Cache dependencies
```

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

### Text-to-Speech Error: Missing Text

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

Example of an error response when the 'text' field is missing or not a string in the request payload.

```bash
# Error response for missing text
curl -X POST http://localhost:8081/api/text-to-speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{}'

# Returns:
{
  "error": {
    "type": "ValidationError",
    "code": "INVALID_INPUT",
    "message": "text field is required and must be a string",
    "details": {
      "originalError": "Error: text field is required and must be a string"
    }
  }
}
```

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

### Text-to-Speech Error: Missing/Invalid Token

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

Example of an error response (401 Unauthorized) when the Authorization header is missing or the JWT token is invalid.

```bash
# Error response for missing/invalid token
curl -X POST http://localhost:8081/api/text-to-speech \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello"}'

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

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

### Integrate Deepgram TTS in TypeScript

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

A client-side implementation for fetching a session token and requesting audio synthesis, including a browser-based playback example.

```typescript
// TTS Client for browser or Deno
async function textToSpeech(text: string, model?: string): Promise<ArrayBuffer> {
  // First, get a session token
  const sessionResponse = await fetch('http://localhost:8081/api/session');
  const { token } = await sessionResponse.json();

  // Build URL with optional model parameter
  const url = new URL('http://localhost:8081/api/text-to-speech');
  if (model) {
    url.searchParams.set('model', model);
  }

  // Make the TTS request
  const response = await fetch(url.toString(), {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`,
    },
    body: JSON.stringify({ text }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

  return response.arrayBuffer();
}

// Usage example - play audio in browser
async function speakText(text: string) {
  try {
    const audioData = await textToSpeech(text, 'aura-2-thalia-en');
    const blob = new Blob([audioData], { type: 'audio/mpeg' });
    const audioUrl = URL.createObjectURL(blob);
    const audio = new Audio(audioUrl);
    await audio.play();
  } catch (error) {
    console.error('TTS Error:', error.message);
  }
}

// Example call
speakText('Welcome to the Deepgram text-to-speech demo!');
```

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

### Convert Text to Speech (Default Model)

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

The main text-to-speech endpoint. Converts text input into binary audio data. Requires a valid JWT session token in the Authorization header. This example uses the default voice model.

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

# Convert text to speech with 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 the Deepgram text-to-speech demo!"}' \
  --output speech.mp3
```

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

### Run Conformance Tests

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

Execute conformance tests for the application. Ensure the app is running before executing this command.

```bash
make test
```

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

### Metadata API

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

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

```APIDOC
## GET /api/metadata

### Description
Returns metadata about the starter application from the deepgram.toml configuration file, including project title, description, author, and tags.

### Method
GET

### Endpoint
/api/metadata

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

### Response
#### Success Response (200)
- **title** (string) - The title of the project.
- **description** (string) - A brief description of the project.
- **author** (string) - Information about the author(s).
- **repository** (string) - URL to the project'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 project.

#### Response Example
```json
{
  "title": "Deno Text-to-Speech",
  "description": "Get started using Deepgram's Text-to-Speech with this Deno demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
  "repository": "https://github.com/deepgram-starters/deno-text-to-speech",
  "useCase": "text-to-speech",
  "language": "typescript",
  "framework": "deno",
  "sdk": "4.11.3",
  "tags": ["text-to-speech", "tts", "speech-synthesis", "typescript", "deno"]
}
```
```

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

### Environment Configuration

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

Configure the application using environment variables in a .env file. Ensure DEEPGRAM_API_KEY is set.

```bash
# Required - Your Deepgram API key
DEEPGRAM_API_KEY=your_api_key_here

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

# Optional - Server host (default: 0.0.0.0)
HOST=0.0.0.0

# Optional - Session secret for JWT auth (auto-generated if not set)
SESSION_SECRET=your_secure_session_secret
```

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

### Convert Text to Speech (Specific Model)

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

Use this endpoint to convert text to speech with a specific voice model by providing the 'model' query parameter. Requires a valid JWT session token.

```bash
# Use a specific 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 using the Andromeda voice model."}' \
  --output speech-andromeda.mp3
```

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

### Manual Endpoint Checks

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

Perform manual checks on the /api/metadata and /api/session endpoints using curl and json_tool.

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

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

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

### Text-to-Speech API

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

Main text-to-speech endpoint that converts text input into binary audio data using Deepgram's TTS service. Requires a valid JWT session token in the Authorization header.

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

### Description
Main text-to-speech endpoint that converts text input into binary audio data using Deepgram's TTS service. Requires a valid JWT session token in the Authorization header.

### Method
POST

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

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

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

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

# Convert text to speech with 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 the Deepgram text-to-speech demo!"}' \
  --output speech.mp3

# Use a specific 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 using the Andromeda voice model."}' \
  --output speech-andromeda.mp3
```

### Response
#### Success Response (200)
- (binary/octet-stream) - The synthesized audio data in MP3 format.

#### Error Response
- **error** (object) - Contains details about the error.
  - **type** (string) - The type of error (e.g., 'ValidationError', 'AuthenticationError').
  - **code** (string) - A specific error code (e.g., 'INVALID_INPUT', 'MISSING_TOKEN').
  - **message** (string) - A human-readable error message.
  - **details** (object) - Additional details about the error (optional).

#### Response Example (Missing text)
```json
{
  "error": {
    "type": "ValidationError",
    "code": "INVALID_INPUT",
    "message": "text field is required and must be a string",
    "details": {
      "originalError": "Error: text field is required and must be a string"
    }
  }
}
```

#### Response Example (Missing/Invalid token)
```json
{
  "error": {
    "type": "AuthenticationError",
    "code": "MISSING_TOKEN",
    "message": "Authorization header with Bearer token is required"
  }
}
```
```

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

### Request Session Token

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

Use this endpoint to issue a signed JWT session token. The token is required for authenticating subsequent API requests and expires after 1 hour.

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

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

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

### User Authentication API

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

Issues a signed JWT session token required for authenticating subsequent API requests. The token expires after 1 hour.

```APIDOC
## GET /api/session

### Description
Issues a signed JWT session token required for authenticating subsequent API requests. The token expires after 1 hour.

### Method
GET

### Endpoint
/api/session

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

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

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

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