### Initialize and Start Application

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

Commands to clone submodules, install dependencies, 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 Ruby Application

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

Use the Makefile commands to initialize the environment, configure the API key, and start the local development server.

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

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

### Dependency Installation

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

Commands to install required dependencies for the backend and frontend.

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

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

### Start and Stop Commands

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

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

```bash
make start
```

```bash
# Terminal 1 — Backend
bundle exec ruby app.rb

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

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

### Conventional Commits Examples

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

Examples of commit messages following the conventional commits format for this project.

```git
feat(ruby-transcription): add diarization support
```

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

```git
refactor(ruby-transcription): simplify session endpoint
```

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

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

### Manual Endpoint Checks

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

Examples of using curl to check the /api/metadata and /api/session endpoints, with JSON output formatted using Python.

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

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

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

### GET /api/metadata

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

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

```APIDOC
## GET /api/metadata

### Description
Returns metadata about the application configuration.

### Method
GET

### Endpoint
/api/metadata

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

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

### GET /api/session

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

Issues a JWT session token for authentication.

```APIDOC
## GET /api/session

### Description
Issues a JWT session token used for authenticating subsequent requests, including WebSocket connections.

### Method
GET

### Endpoint
/api/session

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

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

### Project Lifecycle Management with Makefile

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

Standard commands for initializing, running, testing, and cleaning the project environment.

```makefile
make check-prereqs
make init
cp sample.env .env
make start
make start-backend
make start-frontend
make test
make update
make clean
make status
```

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

### Run Conformance Tests

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

Command to run conformance tests for the application. Requires the application to be running.

```bash
# Run conformance tests (requires app to be running)
make test
```

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

### Docker Deployment Configuration

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

Commands and configuration for building and running the application within a Docker container.

```dockerfile
docker build -t ruby-transcription -f deploy/Dockerfile .
docker run -p 8080:8080 \
  -e DEEPGRAM_API_KEY=your_api_key \
  -e SESSION_SECRET=your_secret \
  ruby-transcription
```

```yaml
version: '3.8'
services:
  app:
    build:
      context: .
      dockerfile: deploy/Dockerfile
    ports:
      - "8080:8080"
    environment:
      - DEEPGRAM_API_KEY=${DEEPGRAM_API_KEY}
      - SESSION_SECRET=${SESSION_SECRET}
```

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

### Retrieve Application Metadata

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

Fetch configuration details from the deepgram.toml file.

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

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

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

### Environment Variables Configuration

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

Configures the application through environment variables, typically set in a .env file. Includes Deepgram API key, server port, bind address, and JWT signing secret.

```bash
# .env file configuration

# Required - Your Deepgram API key
DEEPGRAM_API_KEY=your_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 (auto-generated if not set)
# Set this in production for consistent sessions across restarts
SESSION_SECRET=your_secret_key_here
```

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

### Commit Frontend Changes in Submodule

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

Steps to commit and push changes made to the frontend submodule. Ensure you are in the correct directory before committing.

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

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

### Check Server Health

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

Verify the operational status of the service.

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

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

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

### Authenticate with Session Token

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

Retrieve a JWT session token and store it for use in subsequent authenticated requests.

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

# Response
{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE3MDk4..."
}

# Use the token in subsequent requests
export TOKEN=$(curl -s http://localhost:8081/api/session | jq -r '.token')
```

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

### Transcribe Audio via API

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

Submit audio files or URLs for transcription using various Deepgram model options and features.

```bash
# Transcribe an audio file upload
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@recording.mp3" \
  -F "model=nova-3" \
  -F "language=en" \
  -F "smart_format=true"

# Response
{
  "transcript": "Hello, this is a test recording.",
  "words": [
    {"word": "Hello", "start": 0.0, "end": 0.5, "confidence": 0.98},
    {"word": "this", "start": 0.6, "end": 0.8, "confidence": 0.99}
  ],
  "metadata": {
    "model_uuid": "abc123",
    "request_id": "def456",
    "model_name": "nova-3"
  },
  "duration": 5.2
}

# Transcribe from URL
curl -X POST "http://localhost:8081/api/transcription?model=nova-3&diarize=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "url=https://example.com/audio.mp3"

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

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

### Execute Deepgram Transcription in Ruby

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

Send raw audio data to the Deepgram API using Ruby's Net::HTTP library.

```ruby
require 'net/http'
require 'json'

def call_deepgram_transcription(audio_data, params)
  uri = URI('https://api.deepgram.com/v1/listen')

  # Build query string from params
  query_parts = params.reject { |_, v| v.nil? || v.empty? }.map { |k, v| "#{k}=#{v}" }
  uri.query = query_parts.join('&') unless query_parts.empty?

  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.read_timeout = 120
  http.open_timeout = 30

  req = Net::HTTP::Post.new(uri)
  req['Authorization'] = "Token #{API_KEY}"
  req['Content-Type'] = 'application/octet-stream'
  req.body = audio_data

  response = http.request(req)
  raise "Deepgram API returned status #{response.code}: #{response.body}" unless response.is_a?(Net::HTTPSuccess)

  JSON.parse(response.body)
end

# Usage example
audio_data = File.read('recording.mp3', mode: 'rb')
params = { 'model' => 'nova-3', 'language' => 'en', 'smart_format' => 'true' }
result = call_deepgram_transcription(audio_data, params)
puts result.dig('results', 'channels', 0, 'alternatives', 0, 'transcript')
```

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

### Transcription Parameters Configuration

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

Lists available query parameters for the transcription endpoint to customize Deepgram's behavior, such as model selection, language, smart formatting, diarization, and punctuation.

```bash
# Model selection (default: nova-3)
model=nova-3|nova-2|nova|enhanced|base

# Language code (default: en)
language=en|es|fr|de|...

# Smart formatting for numbers, dates, etc. (default: true)
smart_format=true|false

# Speaker diarization - identify different speakers
diarize=true

# Add punctuation to transcript
punctuat=true

# Add paragraph breaks
paragraphs=true

# Split by speaker turns
utterances=true

# Include filler words (um, uh, etc.)
filler_words=true
```

```bash
# Complete example with all options
curl -X POST "http://localhost:8081/api/transcription" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@meeting.wav" \
  -F "model=nova-3" \
  -F "language=en" \
  -F "smart_format=true" \
  -F "diarize=true" \
  -F "punctuate=true" \
  -F "paragraphs=true" \
  -F "utterances=true"
```

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

### Metadata API

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

Returns metadata about the application from deepgram.toml configuration file. Used for standardization compliance and service discovery.

```APIDOC
## GET /api/metadata

### Description
Returns metadata about the application from deepgram.toml configuration file. Used for standardization compliance and service discovery.

### Method
GET

### Endpoint
/api/metadata

### Request Example
```bash
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) - The author of the application.
- **repository** (string) - The URL of 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.
- **tags** (array) - An array of tags associated with the application.

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

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

### POST /api/transcription

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

Transcribes audio files or URLs using Deepgram's pre-recorded speech-to-text API.

```APIDOC
## POST /api/transcription

### Description
Transcribes audio files or URLs using Deepgram's pre-recorded API. Requires a valid JWT session token.

### Method
POST

### Endpoint
/api/transcription

### Request Body
- **audio** (file/url) - The audio file to upload or a URL pointing to an audio file.

### Response
#### Success Response (200)
- **transcription** (object) - The transcribed text and associated metadata returned by Deepgram.
```

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

### Call Deepgram Transcription from URL

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

Transcribes audio from a provided URL by sending a JSON payload containing the URL to the Deepgram API. Requires Net::HTTP and JSON libraries. Ensure API_KEY is set.

```ruby
def call_deepgram_transcription_url(audio_url, params)
  uri = URI('https://api.deepgram.com/v1/listen')

  query_parts = params.reject { |_, v| v.nil? || v.empty? }.map { |k, v| "#{k}=#{v}" }
  uri.query = query_parts.join('&') unless query_parts.empty?

  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.read_timeout = 120
  http.open_timeout = 30

  req = Net::HTTP::Post.new(uri)
  req['Authorization'] = "Token #{API_KEY}"
  req['Content-Type'] = 'application/json'
  req.body = JSON.generate({ url: audio_url })

  response = http.request(req)
  raise "Deepgram API returned status #{response.code}: #{response.body}" unless response.is_a?(Net::HTTPSuccess)

  JSON.parse(response.body)
end
```

```ruby
# Usage example
params = { 'model' => 'nova-3', 'diarize' => 'true', 'punctuate' => 'true' }
result = call_deepgram_transcription_url('https://example.com/podcast.mp3', params)
puts result.dig('results', 'channels', 0, 'alternatives', 0, 'transcript')
```

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

### Require Session! JWT Authentication Helper

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

A Sinatra helper that validates JWT tokens from the Authorization header. It halts with a 401 JSON error if the token is missing, expired, or invalid. Requires JWT and SESSION_SECRET.

```ruby
helpers do
  def require_session!
    auth_header = request.env['HTTP_AUTHORIZATION']

    unless auth_header&.start_with?('Bearer ')
      halt 401, { 'Content-Type' => 'application/json' }, JSON.generate(
        error: {
          type: 'AuthenticationError',
          code: 'MISSING_TOKEN',
          message: 'Authorization header with Bearer token is required'
        }
      )
    end

    token = auth_header.sub('Bearer ', '')
    begin
      JWT.decode(token, SESSION_SECRET, true, algorithm: 'HS256')
    rescue JWT::ExpiredSignature
      halt 401, { 'Content-Type' => 'application/json' }, JSON.generate(
        error: { type: 'AuthenticationError', code: 'INVALID_TOKEN', message: 'Session expired' }
      )
    rescue JWT::DecodeError
      halt 401, { 'Content-Type' => 'application/json' }, JSON.generate(
        error: { type: 'AuthenticationError', code: 'INVALID_TOKEN', message: 'Invalid session token' }
      )
    end
  end
end
```

```ruby
# Usage in routes
post '/api/transcription' do
  require_session!
  # ... protected endpoint logic
end
```

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

### Transcription API

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

Main transcription endpoint that accepts audio file uploads via multipart/form-data or URLs to audio files. Requires JWT authentication. Supports various Deepgram transcription options via query parameters.

```APIDOC
## POST /api/transcription

### Description
Main transcription endpoint that accepts audio file uploads via multipart/form-data or URLs to audio files. Requires JWT authentication. Supports various Deepgram transcription options via query parameters.

### Method
POST

### Endpoint
/api/transcription

### Parameters
#### Query Parameters
- **model** (string) - Optional - Specifies the Deepgram model to use (e.g., nova-3, nova-2, base).
- **language** (string) - Optional - Specifies the language of the audio.
- **smart_format** (boolean) - Optional - Enables smart formatting.
- **diarize** (boolean) - Optional - Enables speaker diarization.
- **paragraphs** (boolean) - Optional - Enables paragraph detection.
- **punctuate** (boolean) - Optional - Enables punctuation.

#### Request Body
- **file** (file) - Required (when not using URL) - The audio file to transcribe.
- **url** (string) - Required (when not using file) - The URL of the audio file to transcribe.

### Request Example
```bash
# Transcribe an audio file upload
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@recording.mp3" \
  -F "model=nova-3" \
  -F "language=en" \
  -F "smart_format=true"

# Transcribe from URL
curl -X POST "http://localhost:8081/api/transcription?model=nova-3&diarize=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "url=https://example.com/audio.mp3"

# With speaker diarization and paragraphs
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@meeting.wav" \
  -F "model=nova-3" \
  -F "diarize=true" \
  -F "paragraphs=true" \
  -F "punctuate=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.
- **metadata** (object) - Metadata about the transcription request.
  - **model_uuid** (string) - The UUID of the model used.
  - **request_id** (string) - The ID of the request.
  - **model_name** (string) - The name of the model used.
- **duration** (number) - The duration of the audio in seconds.

#### Response Example
```json
{
  "transcript": "Hello, this is a test recording.",
  "words": [
    {"word": "Hello", "start": 0.0, "end": 0.5, "confidence": 0.98},
    {"word": "this", "start": 0.6, "end": 0.8, "confidence": 0.99}
  ],
  "metadata": {
    "model_uuid": "abc123",
    "request_id": "def456",
    "model_name": "nova-3"
  },
  "duration": 5.2
}
```
```

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

### User Authentication API

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

Issues a signed JWT token for session authentication. The token is valid for 1 hour and must be included in subsequent API requests as a Bearer token in the Authorization header.

```APIDOC
## GET /api/session

### Description
Issues a signed JWT token for session authentication. The token is valid for 1 hour and must be included in subsequent API requests as a Bearer token in the Authorization header.

### Method
GET

### Endpoint
/api/session

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

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

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

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

### Health Check API

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

Simple health check endpoint for monitoring and container orchestration platforms like Fly.io and Kubernetes.

```APIDOC
## GET /health

### Description
Simple health check endpoint for monitoring and container orchestration platforms like Fly.io and Kubernetes.

### Method
GET

### Endpoint
/health

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

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

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

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

### Format Deepgram Transcription Response

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

Extracts and formats key transcription fields from the raw Deepgram API response into a simplified structure suitable for frontend display. Requires the model name used for transcription.

```ruby
def format_transcription_response(dg_response, model_name)
  result = dg_response.dig('results', 'channels', 0, 'alternatives', 0)
  raise 'No transcription results returned from Deepgram' unless result

  metadata = {
    model_uuid: dg_response.dig('metadata', 'model_uuid'),
    request_id: dg_response.dig('metadata', 'request_id'),
    model_name: model_name
  }

  response = {
    transcript: result['transcript'] || '',
    words: result['words'] || [],
    metadata: metadata
  }

  duration = dg_response.dig('metadata', 'duration')
  response[:duration] = duration if duration

  response
end
```

```ruby
# Usage example
dg_response = call_deepgram_transcription(audio_data, params)
formatted = format_transcription_response(dg_response, 'nova-3')
# => { transcript: "Hello world", words: [...], metadata: {...}, duration: 2.5 }
```

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