### Setup project with .NET SDK and pnpm

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

Manually clone the repository and install dependencies for both backend and frontend.

```bash
git clone --recurse-submodules https://github.com/deepgram-starters/csharp-transcription.git
cd csharp-transcription
dotnet restore
cd frontend && corepack pnpm install && cd ..
cp sample.env .env  # Add your DEEPGRAM_API_KEY
```

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

### Initialize and start project with Makefile

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

Use the provided Makefile to initialize the environment and start the application.

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

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

### Install Project Dependencies

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

Commands to install required dependencies for the backend and frontend.

```bash
dotnet restore
Frontend: cd frontend && corepack pnpm install
```

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

### Initialize and Start C# Transcription App

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

Clone the repository, initialize submodules, configure environment variables, and start the backend and frontend servers.

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

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

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

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

### Makefile Commands for Project Management

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

A collection of Makefile commands for setting up, developing, testing, and maintaining the C# Deepgram starter project. Includes commands for dependency installation, starting services, and cleaning build artifacts.

```bash
# Setup commands
make check-prereqs     # Check for required tools (git, dotnet)
make init              # Initialize submodules and install all dependencies
make install-backend   # Install backend dependencies only
make install-frontend  # Install frontend dependencies only

# Development commands
make start             # Start application (backend + frontend in parallel)
make start-backend     # Start backend only (port 8081)
make start-frontend    # Start frontend only (port 8080)
make test              # Run contract conformance tests

# Maintenance commands
make update            # Update submodules to latest commits
make clean             # Remove build artifacts and node_modules
make status            # Show git and submodule status
make eject-frontend    # Convert frontend submodule to regular directory
```

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

### Get Application Metadata (GET /api/metadata)

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

Retrieve metadata about the starter application, including its title, description, repository, and supported technologies.

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

# Response
{
  "title": "C# Transcription",
  "description": "Get started using Deepgram's Transcription with this C# demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
  "repository": "https://github.com/deepgram-starters/csharp-transcription",
  "useCase": "transcription",
  "language": "csharp",
  "framework": "dotnet",
  "sdk": "6.6.1",
  "tags": ["transcription", "stt", "speech-to-text", "asr", "pre-recorded", "csharp", "dotnet"]
}
```

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

### Manage Application Lifecycle

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

Commands for starting, stopping, and rebuilding the application services.

```bash
make start
```

```bash
# Terminal 1 — Backend
dotnet run

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

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

### Initialize and Start the Application

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

Commands to initialize the project, 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
```

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

### Conventional Commit Examples

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

Standardized commit message formats for the project.

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

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

### Run backend and frontend servers

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

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

```bash
# Terminal 1 - Backend (port 8081)
dotnet run

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

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

### GET /api/metadata - Application Metadata

Source: https://context7.com/deepgram-starters/csharp-transcription/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.

### Method
GET

### Endpoint
/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.
- **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 framework used.
- **sdk** (string) - The SDK version used.
- **tags** (array of strings) - Tags associated with the application.

### Response Example
```json
{
  "title": "C# Transcription",
  "description": "Get started using Deepgram's Transcription with this C# demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
  "repository": "https://github.com/deepgram-starters/csharp-transcription",
  "useCase": "transcription",
  "language": "csharp",
  "framework": "dotnet",
  "sdk": "6.6.1",
  "tags": ["transcription", "stt", "speech-to-text", "asr", "pre-recorded", "csharp", "dotnet"]
}
```
```

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

### GET /api/metadata

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

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

```APIDOC
## GET /api/metadata

### Description
This endpoint provides metadata about the application, such as its intended use case, the backend framework it utilizes, and the programming language.

### Method
GET

### Endpoint
`/api/metadata`

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

#### Response Example
```json
{
  "useCase": "Speech-to-Text Transcription",
  "framework": ".NET",
  "language": "C#"
}
```
```

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

### GET /api/session

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

Issues a JWT session token for authentication.

```APIDOC
## GET /api/session

### Description
This endpoint generates and returns a JSON Web Token (JWT) which can be used for authenticating subsequent requests, particularly for WebSocket connections.

### Method
GET

### Endpoint
`/api/session`

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

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

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

### Deepgram Features

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

Guide on how to add various Deepgram features to the transcription process.

```APIDOC
## Adding Deepgram Features

The transcription API supports numerous Deepgram features that can be enabled by passing specific parameters.

### Parameters

| Feature |
|---| 
| Language |
| Diarization |
| Punctuation |
| Smart Format |
| Paragraphs |
| Utterances |
| Keywords |
| Redaction |
| Summarize |
| Topics |
| Sentiment |

### Examples

- **Language**: `"es"`, `"fr"` - Transcribe non-English audio.
- **Diarization**: `true` - Identify different speakers.
- **Punctuation**: `true` - Add punctuation to transcript.
- **Smart Format**: `true` - Format numbers, dates, etc.
- **Paragraphs**: `true` - Add paragraph breaks.
- **Utterances**: `true` - Split by speaker turns.
- **Keywords**: `["deepgram"]` - Boost specific terms.
- **Redaction**: `["pci", "ssn"]` - Redact sensitive data.
- **Summarize**: `"v2"` - Add a summary.
- **Topics**: `true` - Detect topics.
- **Sentiment**: `true` - Detect sentiment.

**Backend Change**: Add these parameters to the SDK call options object or API query string.

**Frontend Change (Optional)**: Add UI controls in `frontend/main.js` and pass them as form data or query parameters.
```

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

### Health Check (GET /health)

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

Ping the health check endpoint to verify the service status.

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

# Response
{
  "status": "ok",
  "service": "transcription"
}
```

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

### Request Session Token (GET /api/session)

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

Obtain a JWT session token for authenticating transcription requests. Tokens are valid for 1 hour.

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

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

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

### Transcription Error Responses

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

Examples of error responses for missing input or invalid authentication when using the transcription endpoint.

```json
# 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"
    }
  }
}

# Error response (authentication)
{
  "error": {
    "type": "AuthenticationError",
    "code": "INVALID_TOKEN",
    "message": "Invalid or expired session token"
  }
}
```

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

### GET /health - Health Check

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

Health check endpoint for monitoring and load balancer integration. Returns service status.

```APIDOC
## GET /health

### Description
Health check endpoint for monitoring and load balancer integration. Returns service status.

### Method
GET

### Endpoint
/health

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

### Response Example
```json
{
  "status": "ok",
  "service": "transcription"
}
```
```

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

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

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

Issues a JWT session token required for authenticating transcription requests. Tokens expire after 1 hour (3600 seconds).

```APIDOC
## GET /api/session

### Description
Issues a JWT session token required for authenticating transcription requests. Tokens expire after 1 hour (3600 seconds).

### Method
GET

### Endpoint
/api/session

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

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

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

### Initialize Deepgram Client and Transcribe Audio in C#

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

Initializes the Deepgram client with an API key and demonstrates transcription from both a URL and local file bytes. Ensure the DEEPGRAM_API_KEY environment variable is set.

```csharp
using Deepgram;
using Deepgram.Models.Listen.v1.REST;

// Initialize Deepgram library
Library.Initialize();

// Create REST client with API key
var apiKey = Environment.GetEnvironmentVariable("DEEPGRAM_API_KEY");
var deepgramClient = ClientFactory.CreateListenRESTClient(apiKey);

// Transcribe from URL
var schema = new PreRecordedSchema { Model = "nova-3" };
var response = await deepgramClient.TranscribeUrl(
    new UrlSource("https://dpgr.am/spacewalk.wav"),
    schema
);

// Access transcription results
var transcript = response.Results?.Channels?[0]?.Alternatives?[0]?.Transcript;
var words = response.Results?.Channels?[0]?.Alternatives?[0]?.Words;

// Transcribe from file bytes
byte[] audioBytes = await File.ReadAllBytesAsync("audio.wav");
var fileResponse = await deepgramClient.TranscribeFile(audioBytes, schema);
```

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

### Configure Environment Variables

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

Set up environment variables in the .env file, including the required Deepgram API key and optional server configurations.

```bash
# Required - Get your API key at https://console.deepgram.com
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# Optional - Server configuration (defaults shown)
PORT=8081
HOST=0.0.0.0

# Optional - Set in production for consistent JWT signing
SESSION_SECRET=your_32_byte_hex_secret
```

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

### Run Tests and Check Endpoints

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

Commands to execute conformance tests and verify API endpoints using curl.

```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 and Run Docker Image for C# Application

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

Commands to build the Docker image for the C# transcription application and run it as a container. The container requires the DEEPGRAM_API_KEY to be set as an environment variable.

```bash
# Build Docker image
docker build -f deploy/Dockerfile -t csharp-transcription .

# Run container with API key
docker run -p 8080:8080 \
  -e DEEPGRAM_API_KEY=your_api_key \
  csharp-transcription

# Access at http://localhost:8080
```

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

### Transcribe Audio from File Upload (POST /api/transcription)

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

Upload an audio file directly to the transcription endpoint. Ensure the file path is correct.

```bash
# Transcribe from file upload
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/audio.wav" \
  -F "model=nova-2"
```

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

### Transcribe Audio from URL (POST /api/transcription)

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

Submit an audio file URL to the transcription endpoint. Requires a Bearer token obtained from the /api/session endpoint. The 'model' parameter is optional.

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

# Transcribe from URL
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "url=https://dpgr.am/spacewalk.wav" \
  -F "model=nova-3"

# Response
{
  "transcript": "Yeah, as I said, it's a great day here at Houston...",
  "words": [
    {
      "word": "yeah",
      "start": 0.08,
      "end": 0.32,
      "confidence": 0.99,
      "punctuated_word": "Yeah,"
    },
    {
      "word": "as",
      "start": 0.32,
      "end": 0.48,
      "confidence": 0.98,
      "punctuated_word": "as"
    }
  ],
  "metadata": {
    "model_uuid": "a]c123-def456-...",
    "request_id": "req_abc123...",
    "model_name": "nova-3"
  },
  "duration": 25.933313
}
```

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

### Caddyfile for Production Reverse Proxy and Rate Limiting

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

Configuration for Caddy as a reverse proxy in a production environment. It includes rate limiting for API endpoints to protect against excessive requests and proxies traffic to the backend service.

```caddyfile
{ 
    order rate_limit before basicauth
}

:8080 {
    # Session endpoint: 5 req/min per IP
    handle /api/session {
        rate_limit {
            zone session {
                key {remote_host}
                events 5
                window 1m
            }
        }
        reverse_proxy localhost:8081
    }

    # API endpoints: 120 req/min per IP
    handle /api/* {
        rate_limit {
            zone api {
                key {remote_host}
                events 120
                window 1m
            }
        }
        reverse_proxy localhost:8081
    }

    # Health check proxied to backend
    handle /health {
        reverse_proxy localhost:8081
    }

    # Static frontend assets
    handle {
        root * /app/frontend/dist
        file_server
    }
}
```

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

### Update Frontend Submodule

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

Commands to commit and push changes within the frontend submodule and update the parent repository reference.

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

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

### POST /api/transcription - Transcribe Audio

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

Main transcription endpoint that accepts audio files or URLs and returns transcribed text. Requires Bearer token authentication.

```APIDOC
## POST /api/transcription

### Description
Main transcription endpoint that accepts audio files or URLs and returns transcribed text. Requires Bearer token authentication from `/api/session`.

### Method
POST

### Endpoint
/api/transcription

### Parameters
#### Request Body
- **file** (file) - Required/Optional - Audio file upload (WAV, MP3, etc.). Use either `file` or `url`.
- **url** (string) - Required/Optional - URL to an audio file. Use either `file` or `url`.
- **model** (string) - Optional - Deepgram model to use (default: "nova-3").

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

# Transcribe from URL
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "url=https://dpgr.am/spacewalk.wav" \
  -F "model=nova-3"

# Transcribe from file upload
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/audio.wav" \
  -F "model=nova-2"
```

### Response
#### Success Response (200)
- **transcript** (string) - The transcribed text.
- **words** (array) - An array of word objects, each containing word, start/end times, confidence, and punctuated word.
- **metadata** (object) - Metadata about the transcription request, including model UUID, request ID, and model name.
- **duration** (number) - The duration of the audio in seconds.

#### Response Example
```json
{
  "transcript": "Yeah, as I said, it's a great day here at Houston...",
  "words": [
    {
      "word": "yeah",
      "start": 0.08,
      "end": 0.32,
      "confidence": 0.99,
      "punctuated_word": "Yeah,"
    },
    {
      "word": "as",
      "start": 0.32,
      "end": 0.48,
      "confidence": 0.98,
      "punctuated_word": "as"
    }
  ],
  "metadata": {
    "model_uuid": "a]c123-def456-...",
    "request_id": "req_abc123...",
    "model_name": "nova-3"
  },
  "duration": 25.933313
}
```

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

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

#### Error Response Example (Authentication)
```json
{
  "error": {
    "type": "AuthenticationError",
    "code": "INVALID_TOKEN",
    "message": "Invalid or expired session token"
  }
}
```
```

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

### POST /api/transcription

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

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

```APIDOC
## POST /api/transcription

### Description
This endpoint handles the transcription of audio data. It can accept audio either as a file upload or via a URL.

### Method
POST

### Endpoint
`/api/transcription`

### Parameters
#### Request Body
- **audio_file** (file) - Required - The audio file to transcribe.
- **audio_url** (string) - Required - The URL of the audio file to transcribe.

### Request Example
```json
{
  "audio_url": "http://example.com/audio.mp3"
}
```

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

#### Response Example
```json
{
  "transcript": "This is the transcribed text.",
  "metadata": {
    "duration": 10.5,
    "channels": 1
  }
}
```
```

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

### API Endpoints

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

Overview of the available API endpoints for the C# transcription application.

```APIDOC
## API Endpoints

| Endpoint | Method | Auth | Purpose |
|---|---|---|---|
| `/api/session` | GET | None | Issue JWT session token |
| `/api/metadata` | GET | None | Return app metadata (useCase, framework, language) |
| `/api/transcription` | POST | JWT | Transcribes audio files or URLs using Deepgram's pre-recorded API. |
```

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

### Create JWT Session Token in C#

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

Generates a JWT session token with a specified expiry time and HMAC-SHA256 signing credentials. This token is used for authenticating API requests.

```csharp
using System.IdentityModel.Tokens.Jwt;
using Microsoft.IdentityModel.Tokens;

// Create session token (1 hour expiry)
string CreateSessionToken(SymmetricSecurityKey secretKey)
{
    var handler = new JwtSecurityTokenHandler();
    var descriptor = new SecurityTokenDescriptor
    {
        Expires = DateTime.UtcNow.AddSeconds(3600),
        SigningCredentials = new SigningCredentials(
            secretKey,
            SecurityAlgorithms.HmacSha256Signature
        ),
    };
    var token = handler.CreateToken(descriptor);
    return handler.WriteToken(token);
}
```

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

### Validate JWT Session Token in C#

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

Validates a given JWT session token against a secret key using HMAC-SHA256. Returns true if the token is valid, false otherwise.

```csharp
using System.IdentityModel.Tokens.Jwt;
using Microsoft.IdentityModel.Tokens;

// Validate session token
bool ValidateSessionToken(string token, SymmetricSecurityKey secretKey)
{
    try
    {
        var handler = new JwtSecurityTokenHandler();
        handler.ValidateToken(token, new TokenValidationParameters
        {
            ValidateIssuerSigningKey = true,
            IssuerSigningKey = secretKey,
            ValidateIssuer = false,
            ValidateAudience = false,
            ClockSkew = TimeSpan.Zero,
        }, out _);
        return true;
    }
    catch
    {
        return false;
    }
}
```

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