### Initialize and Run Project

Source: https://context7.com/deepgram-starters/node-flux/llms.txt

Commands to initialize the project, install dependencies, and start the backend and frontend servers. Use individual commands to start servers separately or run contract conformance tests.

```bash
# Check prerequisites (git, node, pnpm)
make check-prereqs

# Initialize project (submodules + all dependencies)
make init

# Start both servers in parallel
make start
# Backend runs at http://localhost:8081
# Frontend runs at http://localhost:8080

# Start servers individually
make start-backend   # Backend API server only
make start-frontend  # Frontend dev server only

# Run contract conformance tests (requires running app)
make test

# Update submodules to latest commits
make update

# Clean all node_modules and build artifacts
make clean

# Show git and submodule status
make status

# Eject frontend from submodule to regular directory
make eject-frontend
```

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

### Initialize and Start Project

Source: https://github.com/deepgram-starters/node-flux/blob/main/AGENTS.md

Commands to clone submodules, install dependencies, configure environment variables, and launch the development servers.

```bash
# Initialize (clone submodules + install deps)
make init

# Set up environment
test -f .env || cp sample.env .env  # then set DEEPGRAM_API_KEY

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

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

### Initialize and Start Node Flux App

Source: https://github.com/deepgram-starters/node-flux/blob/main/README.md

Use these Makefile commands to initialize the project, set up your API key, and start the application servers. Ensure you have a Deepgram API key.

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

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

### Install Dependencies

Source: https://github.com/deepgram-starters/node-flux/blob/main/AGENTS.md

Commands to install required packages for the backend and frontend using corepack pnpm.

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

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

### Start Node Flux Backend and Frontend Servers

Source: https://github.com/deepgram-starters/node-flux/blob/main/README.md

Run the backend server using `node --no-deprecation server.js` and the frontend development server using `pnpm run dev -- --port 8080 --no-open`. Ensure you start them in separate terminals.

```bash
# Terminal 1 - Backend (port 8081)
node --no-deprecation server.js

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

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

### Start and Stop Commands

Source: https://github.com/deepgram-starters/node-flux/blob/main/AGENTS.md

Utility commands for managing the lifecycle of the backend and frontend processes.

```bash
make start
```

```bash
# Terminal 1 — Backend
node server.js

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

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

### Clone and Install Node Flux Dependencies

Source: https://github.com/deepgram-starters/node-flux/blob/main/README.md

Clone the project repository, install Node.js dependencies using pnpm, and copy the sample environment file to set your Deepgram API key. This method is an alternative to using the Makefile.

```bash
git clone --recurse-submodules https://github.com/deepgram-starters/node-flux.git
cd node-flux
pnpm install
cd frontend && pnpm install && cd ..
cp sample.env .env  # Add your DEEPGRAM_API_KEY
```

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

### Conventional Commit Examples

Source: https://github.com/deepgram-starters/node-flux/blob/main/AGENTS.md

Standardized commit message formats for the project.

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

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

### Add Keyterms Query Parameters

Source: https://github.com/deepgram-starters/node-flux/blob/main/AGENTS.md

Example of how to pass multiple keyterm parameters in a WebSocket URL query string.

```text
?keyterm=Deepgram&keyterm=Nova&keyterm=Aura
```

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

### GET /api/session

Source: https://github.com/deepgram-starters/node-flux/blob/main/AGENTS.md

Issues a JWT session token for authentication.

```APIDOC
## GET /api/session

### Description
Issues a JWT session token used for authenticating WebSocket connections.

### Method
GET

### Endpoint
/api/session

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

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

### Establish WebSocket Connection with Flux Parameters

Source: https://context7.com/deepgram-starters/node-flux/llms.txt

This example demonstrates a complete WebSocket connection to the Flux API, including various parameters for real-time transcription. Configure audio encoding, sample rate, end-of-turn detection thresholds, and custom vocabulary hints.

```javascript
const params = new URLSearchParams({
  encoding: 'linear16',           // Audio encoding: 'linear16' or 'opus'
  sample_rate: '16000',           // Sample rate: 8000-48000
  eot_threshold: '0.7',           // End-of-turn confidence: 0.0-1.0 (higher = more conservative)
  eager_eot_threshold: '0.5',     // Tentative EOT threshold (optional)
  eot_timeout_ms: '5000'          // Silence timeout in ms: 0-30000
});
// Add multiple keyterms for custom vocabulary hints
params.append('keyterm', 'Deepgram');
params.append('keyterm', 'Flux');

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

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

### GET /api/metadata

Source: https://github.com/deepgram-starters/node-flux/blob/main/AGENTS.md

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

```APIDOC
## GET /api/metadata

### Description
Returns app metadata such as the use case, framework, and programming language.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Success Response (200)
- **useCase** (string) - The application use case
- **framework** (string) - The framework used
- **language** (string) - The programming language
```

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

### Fetch Project Metadata with cURL

Source: https://context7.com/deepgram-starters/node-flux/llms.txt

Retrieve project metadata, such as title, description, and repository URL, by making a GET request to the /api/metadata endpoint. The response is returned in JSON format.

```bash
curl -s http://localhost:8081/api/metadata | jq
```

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

### GET /api/metadata - Project Metadata

Source: https://context7.com/deepgram-starters/node-flux/llms.txt

Retrieves project metadata parsed from the `deepgram.toml` configuration file, providing details about the application's configuration and purpose.

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

### Description
Returns project metadata parsed from the `deepgram.toml` configuration file, including use case, language, framework, and other standardization-compliant fields.

### Method
GET

### Endpoint
/api/metadata

### Parameters
None

### Request Example
```bash
# Fetch project metadata
curl -s http://localhost:8081/api/metadata | jq
```

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

#### Response Example
```json
{
  "title": "Node Flux",
  "description": "Get started using Deepgram's Flux API for real-time transcription...",
  "author": "Deepgram DX Team <devrel@deepgram.com>",
  "repository": "https://github.com/deepgram-starters/node-flux",
  "useCase": "flux",
  "language": "javascript",
  "framework": "node",
  "sdk": "N/A",
  "tags": ["flux", "turn-detection", "real-time-transcription", "streaming-stt"]
}
```
```

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

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

Source: https://context7.com/deepgram-starters/node-flux/llms.txt

Generates a signed JWT token for authenticating WebSocket connections to the Deepgram Flux API. The token is valid for 1 hour and must be passed as a WebSocket subprotocol.

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

### Description
Generates a signed JWT token for authenticating WebSocket connections. The token is valid for 1 hour and must be passed as a WebSocket subprotocol in the format `access_token.<jwt>` when connecting to the `/api/flux` endpoint.

### Method
GET

### Endpoint
/api/session

### Parameters
None

### Request Example
```bash
# Request a session token
curl -s http://localhost:8081/api/session | jq
```

### Response
#### Success Response (200)
- **token** (string) - The JWT token for WebSocket authentication.

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

### 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/flux', [
  `access_token.${token}`
]);
```
```

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

### Configure Environment Variables

Source: https://context7.com/deepgram-starters/node-flux/llms.txt

Set up your Deepgram API key and other application settings by copying the sample environment file and editing it. Ensure SESSION_SECRET is set in production for secure JWT signing.

```bash
# .env configuration file
DEEPGRAM_API_KEY=your_deepgram_api_key_here  # Required: Get from console.deepgram.com
PORT=8081                                     # Optional: Backend server port (default: 8081)
HOST=0.0.0.0                                  # Optional: Server bind address (default: 0.0.0.0)
SESSION_SECRET=your_random_secret_here        # Optional: JWT signing secret for production

# Quick setup commands
cp sample.env .env
# Edit .env and add your DEEPGRAM_API_KEY
make init    # Initialize submodules and install dependencies
make start   # Start both backend (8081) and frontend (8080) servers
```

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

### Run Project Tests and Endpoint Checks

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

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

### Update Frontend Submodule

Source: https://github.com/deepgram-starters/node-flux/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"
cd frontend && git push origin main
cd .. && git add frontend && git commit -m "chore(deps): update frontend submodule"
```

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

### WS /api/flux

Source: https://github.com/deepgram-starters/node-flux/blob/main/AGENTS.md

WebSocket endpoint for real-time transcription with turn-based detection.

```APIDOC
## WS /api/flux

### Description
Advanced real-time transcription with turn-based detection. Requires JWT authentication via the `access_token.<jwt>` subprotocol.

### Method
WS

### Endpoint
/api/flux

### Query Parameters
- **model** (string) - Optional - Flux STT model (default: flux-general-en)
- **encoding** (string) - Optional - Audio encoding (linear16, opus; default: linear16)
- **sample_rate** (integer) - Optional - Audio sample rate (8000-48000; default: 16000)
- **eot_threshold** (float) - Optional - Confidence for end-of-turn detection (0.0-1.0; default: 0.7)
- **eager_eot_threshold** (float) - Optional - Threshold for tentative end-of-turn (0.0-1.0)
- **eot_timeout_ms** (integer) - Optional - Silence duration in ms before automatic EOT (0-30000; default: 5000)
- **keyterm** (string) - Optional - Custom vocabulary hints (repeated parameter)
```

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

### Handle WebSocket Events and Stream Audio

Source: https://context7.com/deepgram-starters/node-flux/llms.txt

This snippet shows how to handle incoming WebSocket messages from the Flux API, including different turn events and transcript updates. It also includes logic for streaming audio data from the microphone using MediaRecorder.

```javascript
ws.onopen = () => {
  console.log('Connected to Flux API');
  // Start streaming audio data as binary messages
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  // Handle different Flux turn events
  switch (data.type) {
    case 'StartOfTurn':
      console.log('User started speaking');
      break;
    case 'Update':
      console.log('Interim transcript:', data.channel.alternatives[0].transcript);
      break;
    case 'EagerEndOfTurn':
      console.log('Tentative end detected (user might continue)');
      break;
    case 'TurnResumed':
      console.log('User resumed speaking after eager EOT');
      break;
    case 'EndOfTurn':
      console.log('Final transcript:', data.channel.alternatives[0].transcript);
      break;
  }
};

ws.onerror = (error) => console.error('WebSocket error:', error);
ws.onclose = (event) => console.log(`Connection closed: ${event.code} ${event.reason}`);

// Stream audio from microphone
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const mediaRecorder = new MediaRecorder(stream, { mimeType: 'audio/webm' });

mediaRecorder.ondataavailable = (event) => {
  if (event.data.size > 0 && ws.readyState === WebSocket.OPEN) {
    ws.send(event.data);
  }
};

mediaRecorder.start(250); // Send audio chunks every 250ms
```

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

### Connect to Flux API via WebSocket

Source: https://context7.com/deepgram-starters/node-flux/llms.txt

Establishes a WebSocket connection to the /api/flux endpoint using a JWT session token. The token must be provided as a subprotocol in the format 'access_token.<jwt>'.

```javascript
const ws = new WebSocket('ws://localhost:8081/api/flux', [
  `access_token.${token}`
]);
```

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

### Obtain JWT Session Token with JavaScript

Source: https://context7.com/deepgram-starters/node-flux/llms.txt

This JavaScript snippet shows how to fetch a JWT session token from the /api/session endpoint using the Fetch API. The token is then used to establish a WebSocket connection.

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

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

### Request JWT Session Token with cURL

Source: https://context7.com/deepgram-starters/node-flux/llms.txt

Use this cURL command to request a JWT session token from the /api/session endpoint. The token is required for authenticating WebSocket connections.

```bash
curl -s http://localhost:8081/api/session | jq
```

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

### WS /api/flux - Real-Time Transcription WebSocket

Source: https://context7.com/deepgram-starters/node-flux/llms.txt

WebSocket endpoint for real-time speech-to-text transcription using Deepgram's Flux API. It requires JWT authentication and supports various configuration parameters.

```APIDOC
## WS /api/flux - Real-Time Transcription WebSocket

### Description
WebSocket endpoint that proxies audio streams to Deepgram's Flux v2 Listen API. Requires JWT authentication via the `access_token.<jwt>` subprotocol. Supports configurable parameters for end-of-turn detection, audio encoding, and custom vocabulary hints.

### Method
WS (WebSocket)

### Endpoint
/api/flux

### Parameters
#### Query Parameters
- **encoding** (string) - Required - Audio encoding: `linear16` or `opus`.
- **sample_rate** (integer) - Required - Sample rate of the audio stream (e.g., 16000).
- **eot_threshold** (float) - Optional - End-of-turn confidence threshold (0.0-1.0). Higher values are more conservative.
- **eager_eot_threshold** (float) - Optional - Tentative end-of-turn threshold.
- **eot_timeout_ms** (integer) - Optional - Silence timeout in milliseconds (0-30000).
- **keyterm** (string) - Optional - Custom vocabulary hint. Can be specified multiple times.

#### Path Parameters
None

#### Request Body
Audio data is streamed as binary messages.

### Request Example
```javascript
// Complete WebSocket connection example with all Flux parameters
const response = await fetch('http://localhost:8081/api/session');
const { token } = await response.json();

// Build URL with Flux parameters
const params = new URLSearchParams({
  encoding: 'linear16',           // Audio encoding: 'linear16' or 'opus'
  sample_rate: '16000',           // Sample rate: 8000-48000
  eot_threshold: '0.7',           // End-of-turn confidence: 0.0-1.0 (higher = more conservative)
  eager_eot_threshold: '0.5',     // Tentative EOT threshold (optional)
  eot_timeout_ms: '5000'          // Silence timeout in ms: 0-30000
});
// Add multiple keyterms for custom vocabulary hints
params.append('keyterm', 'Deepgram');
params.append('keyterm', 'Flux');

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

ws.onopen = () => {
  console.log('Connected to Flux API');
  // Start streaming audio data as binary messages
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  // Handle different Flux turn events
  switch (data.type) {
    case 'StartOfTurn':
      console.log('User started speaking');
      break;
    case 'Update':
      console.log('Interim transcript:', data.channel.alternatives[0].transcript);
      break;
    case 'EagerEndOfTurn':
      console.log('Tentative end detected (user might continue)');
      break;
    case 'TurnResumed':
      console.log('User resumed speaking after eager EOT');
      break;
    case 'EndOfTurn':
      console.log('Final transcript:', data.channel.alternatives[0].transcript);
      break;
  }
};

ws.onerror = (error) => console.error('WebSocket error:', error);
ws.onclose = (event) => console.log(`Connection closed: ${event.code} ${event.reason}`);

// Stream audio from microphone
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const mediaRecorder = new MediaRecorder(stream, { mimeType: 'audio/webm' });

mediaRecorder.ondataavailable = (event) => {
  if (event.data.size > 0 && ws.readyState === WebSocket.OPEN) {
    ws.send(event.data);
  }
};

mediaRecorder.start(250); // Send audio chunks every 250ms
```

### Response
#### Success Response (200)
WebSocket connection established. Messages are sent back with transcription results and turn events.

#### Response Example
```json
{
  "type": "Update",
  "channel": {
    "alternatives": [
      {
        "transcript": "hello world"
      }
    ]
  }
}
```

#### Error Handling
- **WebSocket Errors**: Handle `onerror` events for connection issues.
- **Close Codes**: Handle `onclose` events for connection termination (e.g., `event.code`, `event.reason`).
```

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