### Initialize and Start Java Project

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

Use the Makefile to initialize the environment and start the application. Ensure the DEEPGRAM_API_KEY is set in the .env file.

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

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

### Install Frontend Dependencies

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

Navigate to the frontend directory and use pnpm to install project dependencies.

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

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

### Initialize and Start the Java Transcription App

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

Run these commands to initialize the project, set up environment variables, and start both 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
```

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

### Run Quick Start Commands

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

Executes prerequisite checks for the development environment.

```bash
# Check prerequisites (git, java 21+, mvn, pnpm)
make check-prereqs
```

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

### Install Backend Dependencies

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

Use Maven to resolve and install backend dependencies as defined in the pom.xml file.

```bash
mvn dependency:resolve
```

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

### Start Java Transcription App Servers Separately

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

Use these commands to start the backend and frontend servers independently. The backend uses Maven, and the frontend uses Vite with pnpm.

```bash
# Terminal 1 — Backend
mvn compile exec:java

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

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

### Get Application Metadata

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

Retrieve metadata about the starter application, including its title, description, author, repository, use case, language, framework, and SDK. This endpoint does not require authentication.

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

# Response
{
  "title": "Java Transcription Starter",
  "description": "Get started using Deepgram's Transcription with this Java demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
  "repository": "https://github.com/deepgram-starters/java-transcription",
  "useCase": "transcription",
  "language": "Java",
  "framework": "Javalin",
  "sdk": "N/A"
}
```

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

### Conventional Commit Examples

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

Standardized commit message formats for project contributions.

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

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

### GET /api/metadata - Application Metadata

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

Returns metadata about the starter application from the `deepgram.toml` configuration file. Useful for identifying the use case, framework, and language of the starter. No authentication required.

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

### Description
Returns metadata about the starter application from the `deepgram.toml` configuration file. Useful for identifying the use case, framework, and language of the starter. No authentication required.

### Method
GET

### Endpoint
/api/metadata

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

### Response
#### Success Response (200)
- **title** (string) - The title of the starter application.
- **description** (string) - A brief description of the starter application.
- **author** (string) - The author(s) of the starter application.
- **repository** (string) - The URL of the code repository.
- **useCase** (string) - The primary use case of the starter.
- **language** (string) - The programming language used.
- **framework** (string) - The web framework used.
- **sdk** (string) - The SDK used (if any).

#### Response Example
```json
{
  "title": "Java Transcription Starter",
  "description": "Get started using Deepgram's Transcription with this Java demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
  "repository": "https://github.com/deepgram-starters/java-transcription",
  "useCase": "transcription",
  "language": "Java",
  "framework": "Javalin",
  "sdk": "N/A"
}
```
```

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

### GET /api/metadata

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

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

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

### GET /api/session

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

Issues a JWT session token for authentication.

```APIDOC
## GET /api/session

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

### Method
GET

### Endpoint
/api/session

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

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

### Error Response for Missing Authentication

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

This example shows the error response when attempting to access the transcription endpoint without proper JWT authentication. A 401 Unauthorized status is returned with details about the missing token.

```bash
# Error response (no auth)
curl -X POST http://localhost:8081/api/transcription \
  -F "url=https://example.com/audio.wav"

# Response (401 Unauthorized)
{
  "error": {
    "type": "AuthenticationError",
    "code": "MISSING_TOKEN",
    "message": "Authorization header with Bearer token is required"
  }
```

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

### GET /health - Health Check

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

Simple health check endpoint for container orchestration and load balancer health probes. Returns a JSON status object. No authentication required.

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

### Description
Simple health check endpoint for container orchestration and load balancer health probes. Returns a JSON status object. No authentication required.

### Method
GET

### Endpoint
/health

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

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

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

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

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

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

Issues a signed JWT token for authenticating subsequent API requests. The token is valid for 1 hour and must be included in the Authorization header for protected endpoints. No authentication required for this endpoint.

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

### Description
Issues a signed JWT token for authenticating subsequent API requests. The token is valid for 1 hour and must be included in the Authorization header for protected endpoints. No authentication required for this endpoint.

### Method
GET

### Endpoint
/api/session

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

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

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

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

### Manage Project Lifecycle with Makefile

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

Use these commands to initialize, run, test, and clean the project environment.

```bash
make init
cp sample.env .env
make start
make start-backend
make start-frontend
make test
make clean
make update
```

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

### Clean and Rebuild Project

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

Execute this command to remove build artifacts and node modules, then re-initialize the project dependencies.

```bash
rm -rf target frontend/node_modules frontend/.vite
make init
```

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

### Run Project Tests and Endpoint Checks

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

Commands to execute the test suite and verify API endpoints.

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

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

### Initialize Deepgram Client and Transcribe Audio

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

Initializes the Deepgram client using an API key and demonstrates transcription from both URLs and file bytes. The response is handled using a visitor pattern to support both immediate and callback-based results.

```java
import com.deepgram.DeepgramClient;
import com.deepgram.resources.listen.v1.media.requests.ListenV1RequestUrl;
import com.deepgram.resources.listen.v1.media.types.MediaTranscribeResponse;
import com.deepgram.types.ListenV1Response;

// Initialize the Deepgram client with API key
DeepgramClient dgClient = DeepgramClient.builder()
        .apiKey(System.getenv("DEEPGRAM_API_KEY"))
        .build();

// Transcribe from URL
MediaTranscribeResponse result = dgClient.listen().v1().media().transcribeUrl(
        ListenV1RequestUrl.builder()
                .url("https://static.deepgram.com/examples/Bueller-Life-moves-702MB.wav")
                .build()
);

// Transcribe from file bytes
byte[] audioBytes = Files.readAllBytes(Path.of("audio.mp3"));
MediaTranscribeResponse result = dgClient.listen().v1().media().transcribeFile(audioBytes);

// Handle the response using visitor pattern (union type)
Map<String, Object> response = result.visit(
        new MediaTranscribeResponse.Visitor<Map<String, Object>>() {
            @Override
            public Map<String, Object> visit(ListenV1Response value) {
                // Immediate transcription result
                String transcript = value.getResults()
                        .getChannels().get(0)
                        .getAlternatives().get().get(0)
                        .getTranscript().orElse("");
                return Map.of("transcript", transcript);
            }

            @Override
            public Map<String, Object> visit(ListenV1AcceptedResponse value) {
                // Callback mode - request accepted for processing
                return Map.of("status", "accepted", "request_id", value.getRequestId());
            }
        }
);
```

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

### Configure Environment Variables

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

Defines required environment variables and provides a helper utility to load them from a .env file with system environment variable priority.

```bash
# .env file configuration
# Required - Deepgram API key from https://console.deepgram.com
DEEPGRAM_API_KEY=your_api_key_here

# Optional - Backend server configuration
PORT=8081
HOST=0.0.0.0

# Optional - JWT signing secret (auto-generated if not set)
SESSION_SECRET=your_random_secret_here
```

```java
import io.github.cdimascio.dotenv.Dotenv;

// Load .env file (ignores if missing)
Dotenv dotenv = Dotenv.configure()
        .ignoreIfMissing()
        .load();

// Get environment variable with fallback
String getEnv(String key, String defaultValue) {
    // System env takes priority (Docker, Fly.io)
    String value = System.getenv(key);
    if (value != null && !value.isEmpty()) {
        return value;
    }
    // Fall back to .env file
    value = dotenv.get(key);
    if (value != null && !value.isEmpty()) {
        return value;
    }
    return defaultValue;
}

// Usage
int port = Integer.parseInt(getEnv("PORT", "8081"));
String host = getEnv("HOST", "0.0.0.0");
String apiKey = getEnv("DEEPGRAM_API_KEY", null);
```

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

### Manage Frontend Submodule

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

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

### Verify API Endpoints

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

Use curl to manually verify the backend metadata and session endpoints.

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

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

### Stop All Running Servers

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

This command finds and kills processes listening on ports 8080 and 8081, effectively stopping both backend and frontend servers.

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

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

### Transcribe Audio from URL

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

This endpoint transcribes audio from a provided URL. It requires JWT authentication via a Bearer token in the Authorization header. The response includes the transcription text, word-level timestamps, and metadata.

```bash
# Transcribe from URL
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "url=https://static.deepgram.com/examples/Bueller-Life-moves-702MB.wav"

# Response
{
  "transcript": "Yeah, I would think I was being set up if I wasn't...",
  "words": [
    {"text": "Yeah", "start": 0.32, "end": 0.56},
    {"text": "I", "start": 0.64, "end": 0.72},
    {"text": "would", "start": 0.72, "end": 0.96}
  ],
  "metadata": {
    "request_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  }
```

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

### Implement JWT Session Authentication

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

Configures HMAC-SHA256 signing for JWT tokens and provides methods for token creation and request validation. Requires the auth0-jwt library.

```java
import com.auth0.jwt.JWT;
import com.auth0.jwt.algorithms.Algorithm;
import com.auth0.jwt.interfaces.JWTVerifier;
import java.time.Instant;

// Configure JWT signing algorithm
String sessionSecret = System.getenv("SESSION_SECRET");
Algorithm jwtAlgorithm = Algorithm.HMAC256(sessionSecret);
JWTVerifier jwtVerifier = JWT.require(jwtAlgorithm).build();

// Create a new session token (valid for 1 hour)
String createSessionToken() {
    Instant now = Instant.now();
    return JWT.create()
            .withIssuedAt(now)
            .withExpiresAt(now.plusSeconds(3600))
            .sign(jwtAlgorithm);
}

// Validate token from Authorization header
boolean requireSession(Context ctx) {
    String authHeader = ctx.header("Authorization");
    if (authHeader == null || !authHeader.startsWith("Bearer ")) {
        ctx.status(401).json(Map.of(
                "error", Map.of(
                        "type", "AuthenticationError",
                        "code", "MISSING_TOKEN",
                        "message", "Authorization header with Bearer token is required"
                )
        ));
        return true; // Block request
    }

    String token = authHeader.substring(7);
    try {
        jwtVerifier.verify(token);
        return false; // Authorized
    } catch (TokenExpiredException e) {
        ctx.status(401).json(Map.of("error", Map.of("code", "INVALID_TOKEN", "message", "Session expired")));
        return true;
    }
}
```

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

### Transcribe Audio from File Upload

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

This endpoint transcribes audio from a file upload. It requires JWT authentication via a Bearer token in the Authorization header. The response includes the transcription text, word-level timestamps, and metadata.

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

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

### Request Session Token

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

Use this endpoint to obtain a JWT token for authenticating subsequent API requests. The token is valid for 1 hour. No authentication is required for this endpoint.

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

# Response
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDk4NDg4MDAsImV4cCI6MTcwOTg1MjQwMH0.abc123..."
}

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

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

### POST /api/transcription

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

Transcribes audio files or URLs using Deepgram's pre-recorded 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) - Required - The audio file or URL to be transcribed.

### Response
#### Success Response (200)
- **transcript** (object) - The transcription result from Deepgram.
```

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

### Configure Deepgram Transcription Features

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

Apply these parameters to the SDK request options to enable specific transcription capabilities like diarization, formatting, and model selection.

```java
.language("es")
.language("fr")
.diarize(true)
.punctuate(true)
.smartFormat(true)
.paragraphs(true)
.utterances(true)
.keywords(List.of("deepgram", "transcription"))
.redact(List.of("pci", "ssn"))
.summarize("v2")
.topics(true)
.model("nova-3")
.model("nova-2")
.model("base")
```

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

### POST /api/transcription - Transcribe Audio

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

Main transcription endpoint that accepts either a file upload or a URL to an audio file. Requires JWT authentication via Bearer token. Returns the transcription text along with word-level timestamps and metadata.

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

### Description
Main transcription endpoint that accepts either a file upload or a URL to an audio file. Requires JWT authentication via Bearer token. Returns the transcription text along with word-level timestamps and metadata.

### Method
POST

### Endpoint
/api/transcription

### Parameters
#### Query Parameters
- **url** (string) - Required - URL to an audio file.

#### Request Body
- **file** (file) - Required - Audio file to transcribe.

### Request Example
```bash
# Transcribe from URL
curl -X POST http://localhost:8081/api/transcription \
  -H "Authorization: Bearer $TOKEN" \
  -F "url=https://static.deepgram.com/examples/Bueller-Life-moves-702MB.wav"

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

### Response
#### Success Response (200)
- **transcript** (string) - The transcribed text.
- **words** (array) - An array of word objects, each containing text, start, and end timestamps.
  - **text** (string) - The transcribed word.
  - **start** (number) - The start time of the word in seconds.
  - **end** (number) - The end time of the word in seconds.
- **metadata** (object) - Metadata about the transcription request.
  - **request_id** (string) - The unique ID for the transcription request.

#### Response Example
```json
{
  "transcript": "Yeah, I would think I was being set up if I wasn't...",
  "words": [
    {"text": "Yeah", "start": 0.32, "end": 0.56},
    {"text": "I", "start": 0.64, "end": 0.72},
    {"text": "would", "start": 0.72, "end": 0.96}
  ],
  "metadata": {
    "request_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  }
}
```

#### Error Response (401 Unauthorized)
- **error** (object) - Error details.
  - **type** (string) - The type of error.
  - **code** (string) - The error code.
  - **message** (string) - A descriptive error message.

#### Error Response Example
```json
{
  "error": {
    "type": "AuthenticationError",
    "code": "MISSING_TOKEN",
    "message": "Authorization header with Bearer token is required"
  }
}
```
```

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

### Health Check

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

A simple health check endpoint designed for container orchestration and load balancer probes. It returns a JSON object indicating the service status.

```bash
# Check service health
curl -s http://localhost:8081/health

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

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