### Initialize and Start Project with Makefile

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

Use 'make init' to initialize submodules and install dependencies, then 'make start' to run both backend and frontend.

```bash
# Quick start with Makefile
make init                    # Initialize submodules and install dependencies
cp sample.env .env           # Create .env file
# Edit .env and add DEEPGRAM_API_KEY
make start                   # Start both backend (8081) and frontend (8080)
```

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

### Manual Project Setup without Makefile

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

Steps for manually setting up the project by updating git submodules, managing Go dependencies, and installing frontend dependencies.

```bash
# Manual setup without Make
git submodule update --init --recursive
go mod tidy
cd frontend && corepack pnpm install
cd ..
```

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

### Initialize and Start the Go Application

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

Use these commands to initialize the project, configure environment variables, and start the local server.

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

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

### Install Dependencies

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

Commands to install backend Go modules and frontend dependencies.

```bash
go mod download
Frontend: cd frontend && corepack pnpm install
```

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

### Manual Project Start (Two Terminals)

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

Instructions for starting the backend and frontend servers manually in separate terminals.

```bash
# Manual start (two terminals)
# Terminal 1:
go run .
# Terminal 2:
cd frontend && pnpm run dev -- --port 8080 --no-open
```

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

### Initialize and Start Application

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

Commands to initialize submodules, set up environment variables, 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
```

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

### Start and Stop Commands

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

Individual commands for managing the application lifecycle, including starting components separately, stopping processes, and performing clean rebuilds.

```bash
make start
```

```bash
# Terminal 1 — Backend
go 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 frontend/node_modules frontend/.vite
make init
```

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

### Makefile Commands for Project Management

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

A collection of Makefile commands for various project management tasks including installation, building, testing, and cleanup.

```bash
# Individual commands
make check-prereqs           # Verify git, go, pnpm are installed
make install                 # Install Go dependencies only
make install-frontend        # Install frontend dependencies only
make build                   # Build frontend for production
make start-backend           # Start backend only
make start-frontend          # Start frontend only
make test                    # Run conformance tests
make update                  # Update git submodules
make clean                   # Remove build artifacts
make status                  # Show git/submodule status
make eject-frontend          # Convert frontend submodule to regular directory
```

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

### Conventional Commits Examples

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

Examples of commit messages following the conventional commits format. Use these to maintain a consistent commit history.

```git
feat(go-live-transcription): add diarization support
```

```git
fix(go-live-transcription): resolve WebSocket close handling
```

```git
refactor(go-live-transcription): simplify session endpoint
```

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

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

### Request Metadata (Bash)

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

Retrieve project metadata, such as title, description, and repository URL, by making a GET request to the /api/metadata endpoint.

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

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

### Use Session Token for WebSocket Connection (JavaScript)

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

Example of how to fetch a session token and establish a WebSocket connection to the live transcription endpoint. The JWT is passed as a WebSocket subprotocol.

```javascript
const response = await fetch('http://localhost:8081/api/session');
const { token } = await response.json();

const ws = new WebSocket(
  'ws://localhost:8081/api/live-transcription?model=nova-3&language=en',
  [`access_token.${token}`]  // JWT passed as subprotocol
);
```

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

### Start and Stop Live Transcription in Browser

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

Connects to the Deepgram transcription service, streams microphone audio, and handles transcription results. Requires a session token obtained from a backend API. Ensure the audio context is configured with the correct sample rate.

```javascript
async function startTranscription() {
  // 1. Get session token
  const tokenResponse = await fetch('http://localhost:8081/api/session');
  const { token } = await tokenResponse.json();

  // 2. Build WebSocket URL with Deepgram parameters
  const params = new URLSearchParams({
    model: 'nova-3',           // STT model: nova-3, nova-2, base
    language: 'en',            // BCP-47 language code
    smart_format: 'true',      // Smart formatting
    punctuate: 'true',         // Auto-punctuation
    diarize: 'false',          // Speaker identification
    filler_words: 'false',     // Include filler words
    encoding: 'linear16',      // Audio encoding
    sample_rate: '16000',      // Sample rate in Hz
    channels: '1'              // Mono audio
  });

  // 3. Connect with JWT subprotocol
  const ws = new WebSocket(
    `ws://localhost:8081/api/live-transcription?${params}`,
    [`access_token.${token}`]
  );

  ws.onopen = () => console.log('Connected to transcription service');

  ws.onmessage = (event) => {
    const result = JSON.parse(event.data);
    // Deepgram response structure
    if (result.channel?.alternatives?.[0]?.transcript) {
      const transcript = result.channel.alternatives[0].transcript;
      const isFinal = result.is_final;
      console.log(`${isFinal ? '[FINAL]' : '[INTERIM]'}: ${transcript}`);
    }
  };

  ws.onerror = (error) => console.error('WebSocket error:', error);
  ws.onclose = () => console.log('Connection closed');

  // 4. Stream microphone audio
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  const audioContext = new AudioContext({ sampleRate: 16000 });
  const source = audioContext.createMediaStreamSource(stream);
  const processor = audioContext.createScriptProcessor(4096, 1, 1);

  processor.onaudioprocess = (e) => {
    if (ws.readyState === WebSocket.OPEN) {
      // Convert Float32 to Int16 PCM
      const float32 = e.inputBuffer.getChannelData(0);
      const int16 = new Int16Array(float32.length);
      for (let i = 0; i < float32.length; i++) {
        int16[i] = Math.max(-32768, Math.min(32767, float32[i] * 32768));
      }
      ws.send(int16.buffer);
    }
  };

  source.connect(processor);
  processor.connect(audioContext.destination);

  return { ws, audioContext, stream };
}

// Stop transcription
function stopTranscription({ ws, audioContext, stream }) {
  ws.close();
  audioContext.close();
  stream.getTracks().forEach(track => track.stop());
}
```

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

### Health Check (Bash)

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

Perform a simple health check by sending a GET request to the /health endpoint. This is useful for monitoring and load balancer probes.

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

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

### Build Docker Image

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

Command to build the Docker image for the Go Live Transcription application.

```dockerfile
# Build the Docker image
docker build -f deploy/Dockerfile -t go-live-transcription .
```

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

### Run Conformance Tests

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

Execute conformance tests for the application. This command requires the application to be running.

```bash
make test
```

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

### Fly.io Deployment Commands

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

Commands for deploying the application to Fly.io, including launching, setting secrets, and deploying.

```bash
# fly.toml for Fly.io deployment
# Deploy to Fly.io
fly launch
fly secrets set DEEPGRAM_API_KEY=your_api_key
fly secrets set SESSION_SECRET=your_production_secret
fly deploy
```

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

### Environment Configuration for Deepgram API Key

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

Sets up environment variables for the application, including the Deepgram API key, backend server port, bind address, and JWT signing secret. The DEEPGRAM_API_KEY is mandatory for operation.

```bash
# .env file configuration

# Required - Your Deepgram API key
DEEPGRAM_API_KEY=your_deepgram_api_key_here

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

# Optional - Server bind address (default: 0.0.0.0)
HOST=0.0.0.0

# Optional - JWT signing secret for production
# If not set, a random 32-byte secret is generated at startup
SESSION_SECRET=your_secure_random_secret_here
```

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

### Run Docker Container

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

Command to run the Docker container, exposing port 8080 and setting necessary environment variables.

```bash
# Run with environment variables
docker run -p 8080:8080 \
  -e DEEPGRAM_API_KEY=your_api_key \
  -e SESSION_SECRET=your_production_secret \
  go-live-transcription
```

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

### Manual Endpoint Checks

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

Manually check the /api/metadata and /api/session endpoints using curl. The output is formatted using Python's json.tool for readability.

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

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

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

### Test API Endpoints Manually

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

Commands to manually test the /api/metadata and /api/session endpoints using curl and format the output with json_tool.

```bash
# Test endpoints manually
curl -sf http://localhost:8081/api/metadata | python3 -m json.tool
curl -sf http://localhost:8081/api/session | python3 -m json.tool
```

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

### Configure WebSocket with Advanced Deepgram Parameters

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

Connects to the Deepgram API using a WebSocket with advanced parameters for fine-tuning transcription. Handles various Deepgram event types like Results, UtteranceEnd, and SpeechStarted. Ensure the `token` variable is defined and accessible.

```javascript
// WebSocket URL with advanced parameters
const advancedParams = new URLSearchParams({
  // Core settings
  model: 'nova-3',
  language: 'en',

  // Formatting
  smart_format: 'true',
  punctuate: 'true',

  // Real-time features
  interim_results: 'true',     // Show partial transcripts while speaking
  endpointing: '300',          // Silence duration (ms) before finalization
  utterance_end_ms: '1000',    // Detect end of utterance
  vad_events: 'true',          // Voice activity detection events

  // Advanced features
  diarize: 'true',             // Speaker identification
  keywords: 'Deepgram:2',      // Boost keyword with weight
  no_delay: 'true',            // Minimize latency (may reduce accuracy)

  // Audio settings
  encoding: 'linear16',
  sample_rate: '16000',
  channels: '1'
});

const ws = new WebSocket(
  `ws://localhost:8081/api/live-transcription?${advancedParams}`,
  [`access_token.${token}`]
);

// Handle different event types from Deepgram
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'Results':
      const alt = data.channel?.alternatives?.[0];
      if (alt?.transcript) {
        console.log(`Speaker ${data.channel.speaker || 0}: ${alt.transcript}`);
      }
      break;
    case 'UtteranceEnd':
      console.log('Utterance ended');
      break;
    case 'SpeechStarted':
      console.log('Speech detected');
      break;
  }
};
```

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

### Request Session Token (Bash)

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

Use this cURL command to request a JWT session token from the backend. This token is required for authenticating WebSocket connections.

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

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

### Stop All Servers

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

Command to stop all running servers on ports 8080 and 8081.

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

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

### Metadata Retrieval API

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

This endpoint retrieves project metadata, such as title, description, and repository information, which is loaded from the `deepgram.toml` configuration file. This is useful for frontend applications to display project details.

```APIDOC
## GET /api/metadata

### Description
Returns project metadata from the `deepgram.toml` configuration file. Useful for frontend applications to display project information and capabilities.

### Method
GET

### Endpoint
/api/metadata

### Parameters

### Request Body

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

### Response
#### Success Response (200)
- **title** (string) - The title of the project.
- **description** (string) - A brief description of the project.
- **author** (string) - Information about the project author.
- **repository** (string) - URL to the project's repository.
- **useCase** (string) - The primary use case of the application.
- **language** (string) - The programming language used for the backend.
- **framework** (string) - The framework used for the backend.
- **sdk** (string) - The SDK used (if any).
- **tags** (array of strings) - Tags associated with the project.

#### Response Example
```json
{
  "title": "Go Live Transcription",
  "description": "Get started using Deepgram's Live Transcription with this Go demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
  "repository": "https://github.com/deepgram-starters/go-live-transcription",
  "useCase": "live-transcription",
  "language": "go",
  "framework": "go",
  "sdk": "N/A",
  "tags": ["live-transcription", "live-stt", "real-time-transcription", "real-time-asr", "streaming-transcription", "live-speech-to-text", "go"]
}
```
```

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

### Session Token Generation API

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

This endpoint generates a JWT session token required for authenticating WebSocket connections to the live transcription service. Tokens are signed with HS256 and have a 1-hour expiration.

```APIDOC
## GET /api/session

### Description
Issues a JWT session token for WebSocket authentication. Tokens are signed with HS256 and expire after 1 hour. The token must be passed as a WebSocket subprotocol when connecting to the live transcription endpoint.

### Method
GET

### Endpoint
/api/session

### Parameters

### Request Body

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

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

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

### WebSocket Connection Example
```javascript
const response = await fetch('http://localhost:8081/api/session');
const { token } = await response.json();

const ws = new WebSocket(
  'ws://localhost:8081/api/live-transcription?model=nova-3&language=en',
  [`access_token.${token}`]  // JWT passed as subprotocol
);
```
```

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

### Health Check Endpoint

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

A simple health check endpoint designed for monitoring purposes and load balancer probes.

```APIDOC
## GET /health

### Description
Simple health check endpoint for monitoring and load balancer probes.

### Method
GET

### Endpoint
/health

### Parameters

### Request Body

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

### Response
#### Success Response (200)
- **status** (string) - Indicates the health status, typically "ok".

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

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