### Initialize and Start Application

Source: https://github.com/deepgram-starters/cpp-transcription/blob/main/AGENTS.md

Commands to initialize submodules, install dependencies, and start 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 and Stop Commands

Source: https://github.com/deepgram-starters/cpp-transcription/blob/main/AGENTS.md

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

```bash
make start
```

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

# 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 build frontend/node_modules frontend/.vite
make init
```

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

### Initialize and Start C++ Transcription App

Source: https://github.com/deepgram-starters/cpp-transcription/blob/main/README.md

Use this Makefile command to initialize the project, copy the sample environment file, and start the local development server. Ensure your DEEPGRAM_API_KEY is added to the .env file.

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

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

### Install Dependencies

Source: https://github.com/deepgram-starters/cpp-transcription/blob/main/AGENTS.md

Commands to install backend C++ dependencies via CMake and frontend dependencies via pnpm.

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

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

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

### Start Backend Server Individually with Make

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Run only the C++ backend API, which will be accessible on port 8081.

```bash
make start-backend
```

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

### Start Backend and Frontend Servers with Make

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Launch both the C++ backend API on port 8081 and the Vite development server for the frontend on port 8080.

```bash
make start
```

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

### Start Frontend Server Individually with Make

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Launch the Vite development server for the frontend, typically accessible on port 8080.

```bash
make start-frontend
```

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

### Conventional Commit Examples

Source: https://github.com/deepgram-starters/cpp-transcription/blob/main/AGENTS.md

Standardized commit message formats for the project.

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

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

### Check Prerequisites with Make

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Verify that all necessary development tools (git, cmake, g++, vcpkg, pnpm) are installed and accessible in your environment.

```bash
make check-prereqs
```

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

### Run C++ Transcription Backend

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Execute the compiled C++ backend application. This command starts the server and displays its API endpoints.

```bash
./build/cpp-transcription
```

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

### Example Deepgram Transcription Request

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Send an audio file to the transcription API with specified Deepgram parameters like model, language, diarization, and punctuation.

```bash
curl -X POST "http://localhost:8081/api/transcription" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@interview.mp3" \
  -F "model=nova-3" \
  -F "language=en" \
  -F "diarize=true" \
  -F "punctuate=true" \
  -F "paragraphs=true" \
  -F "smart_format=true"
```

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

### Initialize Project with Make

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Set up the project by cloning any necessary git submodules and compiling the C++ backend.

```bash
make init
```

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

### Environment Configuration

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Set up the required environment variables for the application.

```bash
# Create .env file from template
cp sample.env .env

# Required configuration
DEEPGRAM_API_KEY=your_deepgram_api_key_here
```

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

### Configure and Build Release Version with CMake

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Configure the project for a release build using CMake and vcpkg, then compile the release artifacts.

```bash
cmake -B build -S . \
  -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake \
  -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release
```

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

### Configure C++ Project with CMake and vcpkg

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Set up the build environment using CMake, integrating with vcpkg for C++ dependency management. Ensure C++20 is supported.

```bash
export VCPKG_ROOT=/path/to/vcpkg
cmake -B build -S . \
  -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
```

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

### Run Contract Conformance Tests with Make

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Execute tests to ensure the project adheres to its defined contracts and specifications.

```bash
make test
```

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

### Run Tests and Check Endpoints

Source: https://github.com/deepgram-starters/cpp-transcription/blob/main/AGENTS.md

Commands to execute the test suite and verify API endpoint responses.

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

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

### Build C++ Project with CMake

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Compile the C++ backend using CMake after the configuration step. This command builds the project in the 'build' directory.

```bash
cmake --build build
```

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

### Clean Build Artifacts with Make

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Remove compiled files and other build-related artifacts to prepare for a clean build.

```bash
make clean
```

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

### Build Docker Image for Transcription Service

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Create a Docker image for the C++ transcription application using a multi-stage Dockerfile. This image includes Caddy for proxying.

```dockerfile
docker build -f deploy/Dockerfile -t cpp-transcription .
```

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

### App Metadata API

Source: https://github.com/deepgram-starters/cpp-transcription/blob/main/AGENTS.md

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

```APIDOC
## GET /api/metadata

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

### Method
GET

### Endpoint
/api/metadata

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **useCase** (string) - The primary use case of the application.
- **framework** (string) - The backend framework used (e.g., Crow).
- **language** (string) - The programming language used (e.g., C++).

#### Response Example
{
  "useCase": "Transcription",
  "framework": "Crow",
  "language": "C++"
}
```

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

### View Git and Submodule Status with Make

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Display the current status of the git repository and its submodules.

```bash
make status
```

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

### Retrieve Application Metadata

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Fetch application configuration details from the deepgram.toml file.

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

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

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

### CMake Project Configuration

Source: https://github.com/deepgram-starters/cpp-transcription/blob/main/CMakeLists.txt

Configures the C++ project, sets the standard to C++20, and finds necessary dependencies like Crow, nlohmann_json, OpenSSL, and CURL. This is essential for building the transcription application.

```cmake
cmake_minimum_required(VERSION 3.20)
project(cpp-transcription VERSION 0.1.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Crow CONFIG REQUIRED)
find_package(nlohmann_json CONFIG REQUIRED)
find_package(OpenSSL REQUIRED)
find_package(CURL 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
)
```

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

### Run Transcription Service with Docker

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Deploy the C++ transcription application as a Docker container. It maps port 8080 and accepts Deepgram API and session secrets as environment variables.

```bash
docker run -d \
  -p 8080:8080 \
  -e DEEPGRAM_API_KEY=your_api_key \
  -e SESSION_SECRET=your_production_secret \
  cpp-transcription
```

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

### Manage Frontend Submodule

Source: https://github.com/deepgram-starters/cpp-transcription/blob/main/AGENTS.md

Commands to update and commit changes to the frontend git submodule.

```bash
cd frontend && git add . && git commit -m "feat: description"
```

```bash
cd frontend && git push origin main
```

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

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

### Update Git Submodules with Make

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Fetch the latest changes from all git submodules tracked by the project.

```bash
make update
```

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

### Health Check

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Verify the server status for monitoring purposes.

```bash
# Health check
curl -X GET http://localhost:8081/health

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

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

### User Authentication API

Source: https://github.com/deepgram-starters/cpp-transcription/blob/main/AGENTS.md

Issues JWT session tokens for user authentication.

```APIDOC
## GET /api/session

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

### Method
GET

### Endpoint
/api/session

### Parameters
#### Query Parameters
None

#### Request Body
None

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

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

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

### Transcribe Audio Files

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Transcribe audio via file upload or URL. Requires a valid JWT Bearer token in the Authorization header.

```bash
# Transcribe an audio file with default settings (nova-3 model)
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@recording.wav"

# Transcribe from URL with custom model
curl -X POST "http://localhost:8081/api/transcription?model=nova-2" \
  -H "Authorization: Bearer $TOKEN" \
  -F "url=https://static.deepgram.com/examples/Bueller-Life-moves-702.mp3"

# Enable diarization and punctuation
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@meeting.mp3" \
  -F "model=nova-3" \
  -F "diarize=true" \
  -F "punctuate=true" \
  -F "paragraphs=true"

# Response:
{
  "transcript": "Life moves pretty fast. If you don't stop and look around once in a while, you could miss it.",
  "words": [
    {"word": "life", "start": 0.08, "end": 0.32, "confidence": 0.98},
    {"word": "moves", "start": 0.32, "end": 0.56, "confidence": 0.99}
  ],
  "duration": 4.5,
  "metadata": {
    "model_name": "nova-3",
    "model_uuid": "abc-123-def",
    "request_id": "req-456-ghi"
  }
}

# Error response (missing input):
{
  "error": {
    "type": "ValidationError",
    "code": "MISSING_INPUT",
    "message": "Either file or url must be provided",
    "details": {
      "originalError": "Either file or url must be provided"
    }
  }
}
```

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

### Application Metadata

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

This endpoint returns metadata about the application, including its use case, programming language, framework, and tags, sourced from the `deepgram.toml` configuration file. It is unprotected and useful for identifying the application type.

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

### Description
Returns metadata about the application from the `deepgram.toml` configuration file. Provides information about the use case, programming language, framework, and associated tags. This endpoint is unprotected and useful for identifying the application type.

### Method
GET

### Endpoint
/api/metadata

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

### Response
#### Success Response (200)
- **title** (string) - The title of the application.
- **description** (string) - A description of the application.
- **author** (string) - Information about the author(s).
- **repository** (string) - URL to the application's 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 SDK used (if any).
- **tags** (array) - An array of relevant tags.

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

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

### Transcribe Audio Files

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

This endpoint transcribes audio files or URLs using Deepgram's pre-recorded speech-to-text API. It accepts multipart form data with either a `file` field or a `url` field and requires a valid JWT Bearer token in the Authorization header.

```APIDOC
## POST /api/transcription - Transcribe Audio Files

### Description
Transcribes audio files or URLs using Deepgram's pre-recorded speech-to-text API. Accepts multipart form data with either a `file` field containing raw audio bytes or a `url` field with a publicly accessible audio URL. Requires a valid JWT Bearer token in the Authorization header. Returns the transcript text, word-level timing data, and metadata.

### Method
POST

### Endpoint
/api/transcription

### Parameters
#### Query Parameters
- **model** (string) - Optional - Specifies the Deepgram model to use (e.g., nova-3, nova-2, base).

#### Request Body
- **file** (file) - Required - The raw audio file to transcribe.
- **url** (string) - Required - A publicly accessible URL to an audio file.
- **model** (string) - Optional - Specifies the Deepgram model to use (e.g., nova-3, nova-2, base).
- **diarize** (boolean) - Optional - Enables diarization to identify different speakers.
- **punctuate** (boolean) - Optional - Enables automatic punctuation.
- **paragraphs** (boolean) - Optional - Enables paragraph detection.

### Request Example
```bash
# Transcribe an audio file with default settings (nova-3 model)
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@recording.wav"

# Transcribe from URL with custom model
curl -X POST "http://localhost:8081/api/transcription?model=nova-2" \
  -H "Authorization: Bearer $TOKEN" \
  -F "url=https://static.deepgram.com/examples/Bueller-Life-moves-702.mp3"

# Enable diarization and punctuation
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@meeting.mp3" \
  -F "model=nova-3" \
  -F "diarize=true" \
  -F "punctuate=true" \
  -F "paragraphs=true"
```

### Response
#### Success Response (200)
- **transcript** (string) - The transcribed text.
- **words** (array) - An array of word objects, each containing the word, start time, end time, and confidence score.
- **duration** (number) - The duration of the audio in seconds.
- **metadata** (object) - Metadata about the transcription request.
  - **model_name** (string) - The name of the Deepgram model used.
  - **model_uuid** (string) - The UUID of the Deepgram model used.
  - **request_id** (string) - The unique ID for the transcription request.

#### Response Example
```json
{
  "transcript": "Life moves pretty fast. If you don't stop and look around once in a while, you could miss it.",
  "words": [
    {"word": "life", "start": 0.08, "end": 0.32, "confidence": 0.98},
    {"word": "moves", "start": 0.32, "end": 0.56, "confidence": 0.99}
  ],
  "duration": 4.5,
  "metadata": {
    "model_name": "nova-3",
    "model_uuid": "abc-123-def",
    "request_id": "req-456-ghi"
  }
}
```

#### Error Response (400)
- **error** (object) - Contains error details.
  - **type** (string) - The type of error.
  - **code** (string) - The error code.
  - **message** (string) - A descriptive error message.
  - **details** (object) - Additional error details.

#### Error Response Example
```json
{
  "error": {
    "type": "ValidationError",
    "code": "MISSING_INPUT",
    "message": "Either file or url must be provided",
    "details": {
      "originalError": "Either file or url must be provided"
    }
  }
}
```
```

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

### Transcription API

Source: https://github.com/deepgram-starters/cpp-transcription/blob/main/AGENTS.md

Transcribes audio files or URLs using Deepgram's pre-recorded API. Requires JWT authentication.

```APIDOC
## POST /api/transcription

### Description
Transcribes audio files or URLs using Deepgram's pre-recorded API. Requires JWT authentication.

### Method
POST

### Endpoint
/api/transcription

### Parameters
#### Path Parameters
None

#### Query Parameters
- **language** (string) - Optional - Language code for transcription (e.g., "es", "fr").
- **diarize** (boolean) - Optional - Enable speaker diarization.
- **punctuate** (boolean) - Optional - Enable punctuation.
- **smart_format** (boolean) - Optional - Enable smart formatting for numbers, dates, etc.
- **paragraphs** (boolean) - Optional - Enable paragraph detection.
- **utterances** (boolean) - Optional - Enable utterance splitting.
- **keywords** (array of strings) - Optional - Boost specific terms.
- **redact** (array of strings) - Optional - Redact sensitive data (e.g., ["pci", "ssn"]).
- **summarize** (string) - Optional - Enable summarization (e.g., "v2").
- **detect_topics** (boolean) - Optional - Enable topic detection.
- **sentiment** (boolean) - Optional - Enable sentiment detection.

#### Request Body
- **audio** (file) - The audio file to transcribe.
- **url** (string) - URL to an audio file to transcribe.

### Request Example
```json
{
  "audio": "<base64_encoded_audio_data>"
}
```
OR
```json
{
  "url": "http://example.com/audio.mp3"
}
```

### Response
#### Success Response (200)
- **transcript** (string) - The transcribed text.
- **metadata** (object) - Metadata about the transcription.
- **results** (object) - Detailed transcription results.

#### Response Example
```json
{
  "transcript": "This is the transcribed text.",
  "metadata": {
    "duration": 10.5,
    "channels": 1
  },
  "results": {
    "channels": [
      {
        "alternatives": [
          {
            "transcript": "This is the transcribed text.",
            "words": [
              {
                "word": "This",
                "start": 0.1,
                "end": 0.3,
                "confidence": 0.98
              }
            ]
          }
        ]
      }
    ]
  }
}
```
```

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

### Health Check

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

This is a simple health check endpoint designed for monitoring and container orchestration platforms. It returns a JSON status indicating whether the server is running.

```APIDOC
## GET /health - Health Check

### Description
Simple health check endpoint for monitoring and container orchestration platforms like Fly.io. Returns a JSON status indicating the server is running. This endpoint is unprotected and always returns HTTP 200 when the server is operational.

### Method
GET

### Endpoint
/health

### Request Example
```bash
# Health check
curl -X GET http://localhost:8081/health
```

### Response
#### Success Response (200)
- **status** (string) - The status of the server (e.g., "ok").

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

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

### Issue JWT Session Token

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

Request a new session token for authenticating subsequent API requests. The token is valid for 1 hour.

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

# Response:
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MDk4MzYwMDAsImlhdCI6MTcwOTgzMjQwMH0.abc123signature"
}

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

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

### Issue JWT Session Token

Source: https://context7.com/deepgram-starters/cpp-transcription/llms.txt

This endpoint issues a new JWT session token for authenticating subsequent API requests. The token is signed with HS256 and expires after 1 hour. It is unprotected and should be called before making transcription requests.

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

### Description
Issues a new JWT session token for authenticating subsequent API requests. The token is signed with HS256 using a session secret (auto-generated or set via `SESSION_SECRET` environment variable) and expires after 1 hour. This endpoint is unprotected and should be called before making transcription requests.

### Method
GET

### Endpoint
/api/session

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

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

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

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