### Manual Environment Setup

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

Manual steps to clone the repository, set up a virtual environment, and install dependencies.

```bash
git clone --recurse-submodules https://github.com/deepgram-starters/flask-text-to-speech.git
cd flask-text-to-speech
python3 -m venv venv
./venv/bin/pip install -r requirements.txt
cd frontend && corepack pnpm install && cd ..
cp sample.env .env  # Add your DEEPGRAM_API_KEY
```

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

### Initialize and Start Flask App

Source: https://github.com/deepgram-starters/flask-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
```

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

### Start Frontend Separately

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

Instructions to start the Vite development server for the frontend in its own terminal.

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

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

### Initialize and Start via Makefile

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

Recommended workflow for local development using the provided Makefile.

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

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

### Makefile Commands for Project Initialization and Development

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

Provides common development tasks for the project, including initializing submodules, installing dependencies, starting development servers, and managing Python and frontend packages.

```bash
# Project initialization
make init              # Initialize submodules and install all dependencies
make check-prereqs     # Verify git, python3, pip are installed

# Development servers
make start             # Start both backend (8081) and frontend (8080)
make start-backend     # Start backend only
make start-frontend    # Start frontend only

# Dependency management
make install-backend   # Install Python dependencies only
make install-frontend  # Install frontend dependencies only
make update            # Update git submodules to latest
```

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

### Dependency Installation

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Command to initialize project dependencies using the Makefile.

```bash
# Option 1: Use Makefile (recommended)
make init
```

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

### Start Flask Backend Separately

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

Instructions to start the Flask backend server in its own terminal.

```bash
# Terminal 1 — Backend
./venv/bin/python app.py
```

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

### Install Project Dependencies

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-starters-standardization-design.md

Methods for installing Python and frontend dependencies.

```bash
# Option 1: Use Makefile (recommended)
make init

# Option 2: Manual install
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
cd frontend && pnpm install && cd ..
```

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

### Manual Dependency Installation

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Provides an alternative method for installing dependencies manually, including setting up a Python virtual environment, installing Python requirements, and installing frontend packages.

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
cd frontend && pnpm install && cd ..
```

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

### Install Frontend Dependencies

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

Installs Node.js frontend dependencies using pnpm.

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

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

### Install Dependencies using Makefile

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Installs project dependencies, including Python packages and frontend assets, by executing the 'init' target in the Makefile.

```bash
make init
```

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

### Run Development and Production Servers

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-starters-standardization-design.md

Commands to start the application in development or production modes.

```bash
# Development mode (with hot reload):
make dev

# Production mode (build and serve):
make build
make start
```

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

### Makefile Help and Initialization

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Commonly used make commands for managing the project. 'make help' displays all available commands, and 'make init' initializes submodules and installs dependencies.

```bash
make help
```

```bash
make init
```

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

### Build and Run App in Production Mode

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Builds the frontend for production and then starts the Flask production server using commands from the Makefile.

```bash
make build
make start
```

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

### Git Operations for Project Setup

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Commands for committing documentation changes and verifying build outputs.

```bash
git add README.md && git commit -m "docs: standardize README to match Node.js pattern with submodule instructions"
```

```bash
make init
```

```bash
make build
```

```bash
ls frontend/dist/
```

```bash
git push origin main
```

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

### Install Backend Dependencies

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

Installs Python backend dependencies using pip within a virtual environment.

```bash
python3 -m venv venv && ./venv/bin/pip install -r requirements.txt
```

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

### Run Application Commands

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Commands to run the application in development or production mode. 'make dev' starts the development server with hot reload, while 'make build' and 'make start' are for production deployment.

```bash
make dev
```

```bash
make build
```

```bash
make start
```

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

### Initialize and Start Flask TTS Project

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

Clone the repository, initialize submodules, and set up the project environment. Ensure your Deepgram API key is added to the .env file.

```bash
git clone --recurse-submodules https://github.com/deepgram-starters/flask-text-to-speech.git
cd flask-text-to-speech
make init

cp sample.env .env
# Edit .env and add your DEEPGRAM_API_KEY

make start
```

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

### Conventional Commit Examples

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

Standardized commit message formats for project version control.

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

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

### Configure Environment Variables

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-starters-standardization-design.md

Example content for the .env file required to store the Deepgram API key.

```bash
DEEPGRAM_API_KEY=your_api_key_here
```

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

### Get Application Metadata

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

Retrieve metadata about the starter application, including its use case, framework, language, and SDK version. This endpoint is used for standardization compliance.

```bash
# Get application metadata
curl -s http://localhost:8081/api/metadata | python3 -m json.tool

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

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

### Makefile for Project Operations

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

This Makefile provides a set of commands for initializing, developing, building, starting, updating, cleaning, and checking the status of the project. It standardizes operations across different environments.

```makefile
.PHONY: help init dev build start update clean status

help:
	@echo "Available commands:"
	@echo "  make init     - Initialize submodules and install dependencies"
	@echo "  make dev      - Start development servers (Flask + Vite HMR)"
	@echo "  make build    - Build frontend for production"
	@echo "  make start    - Start production server"
	@echo "  make update   - Update submodules to latest"
	@echo "  make clean    - Remove venv, node_modules and build artifacts"
	@echo "  make status   - Show git and submodule status"

init:
	@echo "Initializing submodules..."
	git submodule update --init --recursive
	@echo "Creating Python virtual environment..."
	python3 -m venv venv
	@echo "Installing Python dependencies..."
	./venv/bin/pip install -r requirements.txt
	@echo "Installing frontend dependencies..."
	cd frontend && pnpm install
	@echo "Setup complete! Run 'make dev' to start development."

dev:
	@echo "Starting development server..."
	@export NODE_ENV=development && ./venv/bin/python app.py

build:
	@echo "Building frontend for production..."
	cd frontend && pnpm build
	@echo "Build complete!"

start:
	@echo "Starting production server..."
	@export NODE_ENV=production && ./venv/bin/python app.py

update:
	@echo "Updating submodules..."
	git submodule update --remote --merge
	@echo "Submodules updated!"

clean:
	@echo "Cleaning build artifacts..."
	rm -rf venv/
	rm -rf frontend/node_modules/
	rm -rf frontend/dist/
	rm -rf __pycache__/
	rm -rf *.pyc
	@echo "Clean complete!"

status:
	@echo "Git status:"
	@git status --short
	@echo "\nSubmodule status:"
	@git submodule status
```

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

### Run App in Development Mode

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Starts the Flask development server with hot module replacement (HMR) enabled for the frontend, utilizing the 'dev' command from the Makefile.

```bash
make dev
```

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

### Docker Build and Run Commands

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

Builds the Docker image for the Flask application and runs it as a container. This example shows how to map ports and set environment variables, including the Deepgram API key.

```docker
# Build and run with Docker
docker build -f deploy/Dockerfile -t flask-tts .
docker run -p 8080:8080 -e DEEPGRAM_API_KEY=your_key flask-tts

# Or use docker-compose
# docker-compose.yml
version: '3.8'
services:
  flask-tts:
    build:
      context: .
      dockerfile: deploy/Dockerfile
    ports:
      - "8080:8080"
    environment:
      - DEEPGRAM_API_KEY=${DEEPGRAM_API_KEY}
      - SESSION_SECRET=${SESSION_SECRET}
    restart: unless-stopped
```

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

### GET /api/metadata - Application Metadata

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

Retrieves metadata about the Flask Text-to-Speech starter application, including its purpose, technology stack, and version information.

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

### Description
Returns metadata about the starter application, including use case, framework, language, and SDK version.

### Method
GET

### Endpoint
/api/metadata

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

### Response
#### Success Response (200)
- **title** (string) - The title of the application.
- **description** (string) - A brief description of the application.
- **author** (string) - Information about the author or team.
- **repository** (string) - URL to the project repository.
- **useCase** (string) - The primary use case of the application.
- **language** (string) - The programming language used.
- **framework** (string) - The web framework used.
- **sdk** (string) - The version of the SDK used.
- **tags** (array of strings) - Keywords or tags associated with the application.

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

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

### Generate Speech with Multiple Voices using Curl

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

This example uses curl to iterate through a list of voices, generating an MP3 file for each. It first obtains a session token and then makes POST requests to the API for each voice.

```bash
import subprocess
import json

voices = ["aura-2-thalia-en", "aura-2-zeus-en", "aura-2-luna-en"]

# Get session token
result = subprocess.run(
    ["curl", "-s", "http://localhost:8081/api/session"],
    capture_output=True, text=True
)
token = json.loads(result.stdout)["token"]

# Generate speech with each voice
for voice in voices:
    subprocess.run([
        "curl", "-X", "POST",
        f"http://localhost:8081/api/text-to-speech?model={voice}",
        "-H", f"Authorization: Bearer {token}",
        "-H", "Content-Type: application/json",
        "-d", json.dumps({"text": f"Hello, I am {voice.split('-')[2]}"}),
        "--output", f"{voice}.mp3"
    ])
    print(f"Generated: {voice}.mp3")
```

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

### Initialize Flask-SocketIO WebSocket Proxy

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-starters-standardization-design.md

Setup for a Flask application using SocketIO to proxy bidirectional WebSocket traffic to Deepgram.

```python
from flask import Flask
from flask_socketio import SocketIO
from flask_cors import CORS
import websocket

app = Flask(__name__, static_folder='./frontend/dist', static_url_path='/')
CORS(app)
socketio = SocketIO(app, cors_allowed_origins="*")

@socketio.on('connect')
def handle_connect():
    # Setup proxy to Deepgram WebSocket
    pass

if __name__ == '__main__':
    port = int(os.environ.get('PORT', 8080))
    socketio.run(app, host='0.0.0.0', port=port)
```

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

### Open the App URL

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

This provides the URL to access the running Flask application in a web browser. It's typically http://localhost:8080 after starting the development or production server.

```markdown
### 🌐 Open the App
[http://localhost:8080](http://localhost:8080)
```

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

### Makefile Status and Git Commands

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Commands for checking project status and performing Git operations. 'make status' shows git and submodule status, and the example commit command standardizes README updates.

```bash
make status
```

```bash
git add README.md && git commit -m "docs: standardize README to match Node.js pattern with submodule instructions"
```

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

### GET /api/session - Issue JWT Session Token

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

This endpoint generates a JWT token required for authenticating subsequent API calls. This token-based approach provides secure, stateless authentication without exposing your Deepgram API key to clients.

```APIDOC
## GET /api/session - Issue JWT Session Token

### Description
Generates a JWT token for authenticating API calls.

### Method
GET

### Endpoint
/api/session

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

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

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

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

### Test and Push Commands

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Commands to test the application and push changes to the origin. Run 'make init' and 'make build' to ensure everything is working before pushing.

```bash
make init
make build
git push origin main
```

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

### Cloning and Initializing Projects

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Standard procedure for cloning repositories that utilize git submodules.

```bash
git clone --recurse-submodules https://github.com/deepgram-starters/flask-transcription.git
cd flask-transcription
```

```bash
# Option 1: Use Makefile (recommended)
make init
```

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

### Create Summary File

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Generate a summary file documenting the completion of Flask starters standardization. This file lists the key achievements of the standardization process.

```bash
echo "Flask Starters Standardization Complete" > /tmp/flask-standardization-complete.txt
echo "All 4 repositories now match Node.js pattern" >> /tmp/flask-standardization-complete.txt
cat /tmp/flask-standardization-complete.txt
```

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

### Run Backend and Frontend Servers

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

Commands to launch the backend and frontend services in separate terminal sessions.

```bash
# Terminal 1 - Backend (port 8081)
./venv/bin/python app.py

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

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

### Clone Repository with Submodules

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-starters-standardization-design.md

Command to clone the starter repository including the shared frontend submodule.

```bash
git clone --recurse-submodules https://github.com/deepgram-starters/flask-[feature].git
cd flask-[feature]
```

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

### Git and Makefile Integration

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Commands to track configuration changes in version control.

```bash
git add .gitignore && git commit -m "chore: standardize .gitignore with comprehensive patterns"
```

```bash
git add Makefile && git commit -m "feat: add Makefile for framework-agnostic operations"
```

```bash
git add deepgram.toml && git commit -m "fix(config): standardize deepgram.toml to use [build.config] and Makefile commands"
```

```bash
git add app.py && git commit -m "fix: change default port from 3000 to 8080 to match Node starters"
```

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

### Makefile Commands Reference

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-starters-standardization-design.md

Standardized Makefile commands for managing the project lifecycle.

```bash
make help              # Show all available commands
make init              # Initialize submodules and install dependencies
make dev               # Start development servers
make build             # Build frontend for production
make start             # Start production server
make update            # Update submodules to latest
make clean             # Remove venv, node_modules and build artifacts
make status            # Show git and submodule status
```

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

### Refactoring Project Structure

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Commands to remove legacy frontend folders and initialize them as git submodules.

```bash
cd /Users/lukeoliff/Projects/deepgram-starters/flask-transcription
git rm -r frontend
git commit -m "refactor: remove frontend folder to prepare for submodule"
git submodule add https://github.com/deepgram-starters/transcription-html frontend
git commit -m "feat: add transcription-html as git submodule"
```

```bash
mkdir -p .github
git mv CODE_OF_CONDUCT.md .github/
git mv CONTRIBUTING.md .github/
git mv SECURITY.md .github/
git commit -m "refactor: move community files to .github folder"
```

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

### Clone Repository with Submodules

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Clones the Flask Text-to-Speech starter repository, ensuring that all git submodules, including the frontend, are initialized and updated.

```bash
git clone --recurse-submodules https://github.com/deepgram-starters/flask-text-to-speech.git
cd flask-text-to-speech
```

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

### Run Contract Conformance Tests

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

Execute contract conformance tests for the project. This command is useful for verifying the integrity and compatibility of the project's components.

```bash
make test
```

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

### Clean Build Artifacts and Dependencies

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

Remove virtual environment, node_modules, and build artifacts. Use this command to ensure a clean state before rebuilding or redeploying.

```bash
make clean
```

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

### Clean Rebuild Project

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

Commands to clean build artifacts, remove dependencies, and re-initialize the project.

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

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

### Submodule and Repository Management

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Commands for removing legacy frontend folders and configuring git submodules.

```bash
cd /Users/lukeoliff/Projects/deepgram-starters/flask-live-transcription
git rm -r frontend
git commit -m "refactor: remove frontend folder to prepare for submodule"
git submodule add https://github.com/deepgram-starters/live-transcription-html frontend
git commit -m "feat: add live-transcription-html as git submodule"
```

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

### Move Community Files to .github/

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Organizes community-related files by moving them into the .github/ directory. This centralizes contribution and governance information.

```bash
mkdir -p .github
git mv CODE_OF_CONDUCT.md .github/
git mv CONTRIBUTING.md .github/
git mv SECURITY.md .github/
git commit -m "refactor: move community files to .github folder"
```

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

### Repository Cloning

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Command to clone the repository including all submodules.

```bash
git clone --recurse-submodules https://github.com/deepgram-starters/flask-live-transcription.git
cd flask-live-transcription
```

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

### Testing and Endpoint Verification

Source: https://github.com/deepgram-starters/flask-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
```

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

### Initialize Flask REST API Server

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-starters-standardization-design.md

Basic structure for a Flask REST API with CORS enabled and static file serving.

```python
from flask import Flask, request, send_from_directory
from flask_cors import CORS

app = Flask(__name__, static_folder='./frontend/dist', static_url_path='/')
CORS(app)

@app.route('/')
def index():
    return app.send_static_file('index.html')

@app.route('/tts/synthesize', methods=['POST'])
def synthesize():
    # Implementation
    pass

if __name__ == '__main__':
    port = int(os.environ.get('PORT', 8080))
    app.run(host='0.0.0.0', port=port)
```

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

### Verify Makefile Existence

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Confirm that a Makefile exists in the root directory of each specified Flask starter repository. This ensures consistent project management commands.

```bash
for repo in flask-text-to-speech flask-transcription flask-live-text-to-speech flask-live-transcription; do
  echo "=== $repo ==="
  cd "$repo"
  ls -la Makefile
  cd ..
done
```

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

### Add Live Text-to-Speech HTML as Git Submodule

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

This command removes the existing frontend directory and adds the live-text-to-speech-html repository as a git submodule. This is useful for managing shared frontend components across projects.

```bash
cd /Users/lukeoliff/Projects/deepgram-starters/flask-live-text-to-speech
git rm -r frontend
git commit -m "refactor: remove frontend folder to prepare for submodule"
git submodule add https://github.com/deepgram-starters/live-text-to-speech-html frontend
git commit -m "feat: add live-text-to-speech-html as git submodule"
```

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

### Move Community Files to .github/ Directory

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

This command creates a .github directory and moves community-related files (CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md) into it if they exist. This organizes project governance files.

```bash
mkdir -p .github
git mv CODE_OF_CONDUCT.md .github/ 2>/dev/null || true
git mv CONTRIBUTING.md .github/ 2>/dev/null || true
git mv SECURITY.md .github/ 2>/dev/null || true
git commit -m "refactor: move community files to .github folder" 2>/dev/null || echo "No files to move"
```

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

### Add Makefile for Framework-Agnostic Operations

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

This command adds a Makefile to the project, providing a consistent way to manage build, initialization, and other operations across different development environments. This is a feature to improve developer experience.

```bash
git add Makefile && git commit -m "feat: add Makefile for framework-agnostic operations"
```

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

### Convert Frontend Submodule to Directory

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

Convert the frontend submodule into a regular directory. This is an advanced operation for modifying the project structure.

```bash
make eject-frontend
```

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

### Standardized deepgram.toml Configuration

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-starters-standardization-design.md

Provides a consistent metadata and build configuration structure for Deepgram starters.

```toml
[meta]
title = "Flask [Feature]"
description = "..."
author = "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)"
useCase = "[Use Case]"
language = "Python"
framework = "Flask"
repository = "https://github.com/deepgram-starters/flask-[feature]"

[pre-build]
command = "make init"
message = "Dependencies installed (Python + frontend)"

[build]
command = "make build"
message = "Build completed"

[build.config]
sample = "sample.env"
output = ".env"

[post-build]
message = "Run `make start` to get up and running."
```

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

### Standard .gitignore for Python and Frontend

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

A comprehensive .gitignore file that excludes Python build artifacts, virtual environments, frontend dependencies, lock files, environment files, logs, and editor/OS specific files.

```gitignore
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
virtualenv/
env/
ENV/
*.egg-info/
dist/
build/

# Frontend (submodule)
frontend/node_modules/
frontend/dist/

# Lock files (Flask uses requirements.txt, frontend uses pnpm)
frontend/package-lock.json
frontend/yarn.lock

# Environment
.env
.env.local
*.local

# Logs
*.log

# Editor/OS
.vscode/
.idea/
*.swp
*.swo
*~
.DS_Store
Thumbs.db

# Testing
.pytest_cache/
.coverage
htmlcov/
```

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

### Fly.io Deployment Commands

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

Deploys the application to Fly.io. This involves launching the application, setting secrets such as the Deepgram API key and session secret, and then deploying the application.

```bash
# Deploy to Fly.io
fly launch
fly secrets set DEEPGRAM_API_KEY=your_api_key
fly secrets set SESSION_SECRET=$(openssl rand -hex 32)
fly deploy
```

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

### Verify Community Files

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Check for the presence of community files (CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md) within the .github/ directory of each specified Flask starter repository.

```bash
for repo in flask-text-to-speech flask-transcription flask-live-text-to-speech flask-live-transcription; do
  echo "=== $repo ==="
  cd "$repo"
  ls -la .github/
  cd ..
done
```

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

### Verify Repository Push Status

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Check the Git status for each specified Flask starter repository to ensure all changes have been committed and pushed. This confirms the repositories are up-to-date.

```bash
for repo in flask-text-to-speech flask-transcription flask-live-text-to-speech flask-live-transcription; do
  echo "=== $repo ==="
  cd "$repo"
  git status
  cd ..
done
```

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

### Standardizing Configuration Files

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Updates for deepgram.toml to integrate with Makefile build commands.

```toml
[pre-build]
command = "make init"
message = "Dependencies installed (Python + frontend)"

[build]
command = "make build"
message = "Build completed"

[build.config]
sample = "sample.env"
output = ".env"

[post-build]
message = "Run `make start` to get up and running."
```

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

### Python Configuration Loading (app.py)

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

Loads environment variables using `python-dotenv` and configures application settings. It validates the presence of the Deepgram API key and generates a session secret if none is provided.

```python
# Accessing configuration in app.py
import os
from dotenv import load_dotenv

load_dotenv(override=False)

# Configuration object
CONFIG = {
    "port": int(os.environ.get("PORT", 8081)),
    "host": os.environ.get("HOST", "0.0.0.0"),
}

# API key validation
API_KEY = os.environ.get("DEEPGRAM_API_KEY")
if not API_KEY:
    raise ValueError("DEEPGRAM_API_KEY environment variable is required")

# Session secret (auto-generated if not provided)
import secrets
SESSION_SECRET = os.environ.get("SESSION_SECRET") or secrets.token_hex(32)
```

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

### Verify Submodule Status

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Iterate through specified Flask starter repositories and check the status of their Git submodules. This ensures that the frontend submodules are correctly tracked.

```bash
for repo in flask-text-to-speech flask-transcription flask-live-text-to-speech flask-live-transcription; do
  echo "=== $repo ==="
  cd "$repo"
  git submodule status
  cd ..
done
```

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

### Add Git Submodule for Frontend

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Removes the existing frontend directory and adds a new one as a git submodule. This is part of standardizing the project structure.

```bash
cd /Users/lukeoliff/Projects/deepgram-starters/flask-text-to-speech
git rm -r frontend
git commit -m "refactor: remove frontend folder to prepare for submodule"
git submodule add https://github.com/deepgram-starters/text-to-speech-html frontend
git commit -m "feat: add text-to-speech-html as git submodule"
```

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

### Standardized Makefile Targets

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-starters-standardization-design.md

Defines common development and build commands for Flask projects.

```makefile
.PHONY: help init dev build start update clean status

help:              # Show all available commands
init:              # Initialize submodules and install dependencies (Python venv + frontend)
dev:               # Start development servers (Flask + Vite HMR)
build:             # Build frontend for production
start:             # Start production server
update:            # Update submodules to latest
clean:             # Remove venv, node_modules, build artifacts
status:            # Show git and submodule status
```

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

### Push Changes to Git Repository

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Stage changes, commit them with a descriptive message, and push to the origin main branch. This command sequence is used for version control.

```bash
git add README.md && git commit -m "docs: standardize README to match Node.js pattern with submodule instructions"
git push origin main
```

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

### Standardize .gitignore with Comprehensive Patterns

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

This command adds a standardized .gitignore file to the project, ensuring common development and build artifacts are ignored by git. This is a chore task for maintaining project cleanliness.

```bash
git add .gitignore && git commit -m "chore: standardize .gitignore with comprehensive patterns"
```

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

### Standardized .gitignore Template

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-starters-standardization-design.md

Comprehensive ignore patterns for Python, frontend submodules, environment files, and IDE artifacts.

```gitignore
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
venv/
env/
ENV/
*.egg-info/
dist/
build/

# Frontend (submodule)
frontend/node_modules/
frontend/dist/

# Lock files (Flask uses requirements.txt, frontend uses pnpm)
frontend/package-lock.json
frontend/yarn.lock

# Environment
.env
.env.local
*.local

# Logs
*.log

# Editor/OS
.vscode/
.idea/
*.swp
*.swo
*~
.DS_Store
Thumbs.db

# Testing
.pytest_cache/
.coverage
htmlcov/

# Temporary files
*.tmp
.cache/
```

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

### Update Frontend Submodule

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

Steps to commit changes in the local frontend copy and update the git submodule reference.

```bash
cd frontend && git add . && git commit -m "feat: description"
cd .. && git add frontend && git commit -m "chore(deps): update frontend submodule"
```

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

### Makefile Update and Cleanup Commands

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Commands for updating project submodules and cleaning build artifacts. 'make update' fetches the latest submodule changes, and 'make clean' removes generated files and directories.

```bash
make update
```

```bash
make clean
```

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

### Convert Text to Speech

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

Send a POST request with JSON text input to convert text into audio data. JWT authentication is required, and you can optionally specify a voice model using query parameters.

```bash
# Basic text-to-speech request (using default aura-2-thalia-en voice)
TOKEN=$(curl -s http://localhost:8081/api/session | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")

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

# Play the generated audio (macOS)
afplay speech.mp3

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

```bash
# Error handling - missing authentication
curl -X POST http://localhost:8081/api/text-to-speech \
  -H "Content-Type: application/json" \
  -d '{"text": "Test"}' \
  -w "\nHTTP Status: %{http_code}\n"

# Response:
# {"error":{"type":"AuthenticationError","code":"MISSING_TOKEN","message":"Authorization header with Bearer token is required"}}
# HTTP Status: 401
```

```bash
# Error handling - text too long (max 2000 characters)
curl -X POST http://localhost:8081/api/text-to-speech \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"text\": \"$(python3 -c 'print("a" * 2001)')\"}" \
  -w "\nHTTP Status: %{http_code}\n"

# Response:
# {"error":{"type":"SynthesisError","code":"TEXT_TOO_LONG","message":"Text exceeds maximum length of 2000 characters"}}
# HTTP Status: 400
```

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

### Environment Configuration (.env file)

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

Defines environment variables for configuring the Flask application, including API keys, server ports, and session secrets. Ensure sensitive information like API keys and session secrets are kept secure.

```bash
# .env file configuration

# Required - Your Deepgram API key
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# Optional - Server configuration
PORT=8081              # Backend API server port (default: 8081)
HIST=0.0.0.0           # Server bind address (default: 0.0.0.0)

# Production - Session security
SESSION_SECRET=your_secure_random_secret_here  # JWT signing secret

# Debug mode (development only)
FLASK_DEBUG=1          # Enable Flask debug mode
```

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

### Fix: Change Default Port in app.py

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

This commit changes the default port configuration in app.py from 3000 to 8080. This aligns the Flask starter with the port used in Node.js starters for consistency.

```python
Change port from 3000 to 8080
```

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

### JavaScript TTS Client for Browser Applications

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

This client handles session management, text synthesis, and audio playback in the browser. It requires a running backend server to obtain session tokens and synthesize speech.

```javascript
class TTSClient {
  constructor(baseUrl = 'http://localhost:8081') {
    this.baseUrl = baseUrl;
    this.token = null;
  }

  async getSession() {
    const response = await fetch(`${this.baseUrl}/api/session`);
    if (!response.ok) throw new Error('Failed to get session');
    const data = await response.json();
    this.token = data.token;
    return this.token;
  }

  async synthesize(text, model = 'aura-2-thalia-en') {
    if (!this.token) await this.getSession();

    const response = await fetch(
      `${this.baseUrl}/api/text-to-speech?model=${encodeURIComponent(model)}`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.token}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ text })
      }
    );

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error?.message || 'Synthesis failed');
    }

    return response.arrayBuffer();
  }

  async playText(text, model = 'aura-2-thalia-en') {
    const audioData = await this.synthesize(text, model);
    const blob = new Blob([audioData], { type: 'audio/mpeg' });
    const url = URL.createObjectURL(blob);

    const audio = new Audio(url);
    audio.onended = () => URL.revokeObjectURL(url);
    await audio.play();

    return audio;
  }
}

// Usage example
const tts = new TTSClient();

// Play text with default voice
document.getElementById('speakBtn').addEventListener('click', async () => {
  const text = document.getElementById('textInput').value;
  const voice = document.getElementById('voiceSelect').value;

  try {
    await tts.playText(text, voice);
    console.log('Audio playback complete');
  } catch (error) {
    console.error('TTS Error:', error.message);
  }
});

// Download audio file
async function downloadAudio(text, filename = 'speech.mp3') {
  const audioData = await tts.synthesize(text);
  const blob = new Blob([audioData], { type: 'audio/mpeg' });
  const url = URL.createObjectURL(blob);

  const a = document.createElement('a');
  a.href = url;
  a.download = filename;
  a.click();

  URL.revokeObjectURL(url);
}
```

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

### Show Git and Submodule Status

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

Display the current status of the Git repository and its submodules. This helps in understanding the project's version control state.

```bash
make status
```

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

### Stop Running Servers

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

Command to find and kill processes listening on ports 8080 and 8081.

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

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

### DeepgramTTSClient Class for Flask Text-to-Speech API

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

A Python client class to interact with the Flask Text-to-Speech API. It handles obtaining session tokens and synthesizing text to speech, with an option to save audio to a file.

```python
import requests
from pathlib import Path

class DeepgramTTSClient:
    """Client for Flask Text-to-Speech API"""

    def __init__(self, base_url: str = "http://localhost:8081"):
        self.base_url = base_url
        self.token = None

    def get_session(self) -> str:
        """Obtain a new JWT session token"""
        response = requests.get(f"{self.base_url}/api/session")
        response.raise_for_status()
        self.token = response.json()["token"]
        return self.token

    def synthesize(
        self,
        text: str,
        model: str = "aura-2-thalia-en",
        output_path: str = None
    ) -> bytes:
        """
        Convert text to speech

        Args:
            text: Text to synthesize (max 2000 characters)
            model: Voice model to use
            output_path: Optional file path to save audio

        Returns:
            Audio bytes
        """
        if not self.token:
            self.get_session()

        response = requests.post(
            f"{self.base_url}/api/text-to-speech",
            params={"model": model},
            headers={
                "Authorization": f"Bearer {self.token}",
                "Content-Type": "application/json"
            },
            json={"text": text}
        )
        response.raise_for_status()

        audio_data = response.content

        if output_path:
            Path(output_path).write_bytes(audio_data)
            print(f"Audio saved to: {output_path}")

        return audio_data

# Usage example
if __name__ == "__main__":
    client = DeepgramTTSClient()

    # Generate speech with default voice
    client.synthesize(
        "Welcome to the Flask Text-to-Speech demo!",
        output_path="welcome.mp3"
    )

    # Generate with different voice
    client.synthesize(
        "This message uses a different voice model.",
        model="aura-2-orion-en",
        output_path="orion_voice.mp3"
    )

    # Get raw audio bytes for streaming
    audio_bytes = client.synthesize("Quick announcement!")
    print(f"Generated {len(audio_bytes)} bytes of audio")
```

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

### Update deepgram.toml Configuration

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

This TOML configuration updates the Deepgram settings to use Makefile commands for initialization and building, and specifies the output for environment variables.

```toml
[pre-build]
command = "make init"
message = "Dependencies installed (Python + frontend)"

[build]
command = "make build"
message = "Build completed"

[build.config]
sample = "sample.env"
output = ".env" 

[post-build]
message = "Run `make start` to get up and running."
```

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

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

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

Converts provided text into speech using Deepgram's Text-to-Speech API. Supports optional voice model selection and requires JWT authentication.

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

### Description
Converts text input into audio data using Deepgram's Text-to-Speech API. Requires JWT authentication and allows specifying a voice model.

### Method
POST

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

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

### Request Body
- **text** (string) - Required - The text to convert to speech. Maximum length is 2000 characters.

### Request Example
```bash
# Basic text-to-speech request
TOKEN=$(curl -s http://localhost:8081/api/session | python3 -m json.tool | jq -r '.token')

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

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

### Response
#### Success Response (200)
- **audio data** (binary) - The generated audio stream in MP3 format.

#### Error Response (400)
- **error** (object) - Contains error details.
  - **type** (string) - The type of error (e.g., `SynthesisError`).
  - **code** (string) - The error code (e.g., `TEXT_TOO_LONG`).
  - **message** (string) - A human-readable error message.

#### Error Response (401)
- **error** (object) - Contains error details.
  - **type** (string) - The type of error (e.g., `AuthenticationError`).
  - **code** (string) - The error code (e.g., `MISSING_TOKEN`).
  - **message** (string) - A human-readable error message.

#### Response Example (Success)
(Binary audio data - e.g., MP3 file content)

#### Response Example (Error - Text Too Long)
```json
{
  "error": {
    "type": "SynthesisError",
    "code": "TEXT_TOO_LONG",
    "message": "Text exceeds maximum length of 2000 characters"
  }
}
```

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

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

### Change Default Port in app.py

Source: https://github.com/deepgram-starters/flask-text-to-speech/blob/main/docs/plans/2026-01-28-flask-standardization-implementation.md

Modifies the default port configuration in the Flask application file from 3000 to 8080 to align with Node.js starter project conventions.

```python
DEFAULT_PORT = 8080
```

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

### Request JWT Session Token

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

Obtain a JWT token for authenticating subsequent API calls. This token is required for secure, stateless authentication without exposing your Deepgram API key.

```bash
# Request a new session token
curl -s http://localhost:8081/api/session | python3 -m json.tool

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

# Store token for subsequent requests
TOKEN=$(curl -s http://localhost:8081/api/session | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")
echo "Session token: $TOKEN"
```

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