Deepgram JavaScript SDK (deepgram/deepgram-js-sdk)

Deepgram JavaScript SDK

https://github.com/deepgram/deepgram-js-sdk
Admin
The Deepgram JavaScript SDK provides a comprehensive set of tools for developers to integrate...

Tokens:38,332
Snippets:220
Trust Score:9.2
Update:2 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# Deepgram JavaScript SDK

The Deepgram JavaScript SDK (`@deepgram/sdk`) is an isomorphic client library for interacting with the Deepgram AI speech and language APIs. It provides comprehensive support for speech-to-text transcription (both pre-recorded and real-time streaming), text-to-speech synthesis, text intelligence analysis, and conversational voice agents. The SDK works in both Node.js and browser environments, with WebSocket-based features having full browser support and REST API features requiring a proxy for browser use due to CORS restrictions.

The SDK is built with TypeScript and offers a clean, namespace-based API design where all functionality is accessed through a single client instance. It supports multiple authentication methods including API keys, temporary access tokens, and proxy authentication. The library handles both synchronous and asynchronous operations, with built-in error handling that returns structured `{ result, error }` response objects. Key features include live streaming transcription with WebSockets, pre-recorded audio/video transcription, text-to-speech with multiple voice models, text intelligence for sentiment and intent analysis, and a Voice Agent API for building conversational AI applications.

## Installation

Install the SDK from npm to use it in your Node.js or browser project.

```bash
npm install @deepgram/sdk
# or
pnpm install @deepgram/sdk
# or
yarn add @deepgram/sdk
```

## Client Initialization

### createClient - Create Deepgram Client

The `createClient` function initializes the Deepgram SDK client with authentication credentials. It supports API keys, access tokens, and proxy authentication methods.

```javascript
import { createClient } from "@deepgram/sdk";

// Method 1: API key as string
const deepgram = createClient("YOUR_DEEPGRAM_API_KEY");

// Method 2: API key in options object
const deepgram = createClient({ key: "YOUR_DEEPGRAM_API_KEY" });

// Method 3: Use environment variable (DEEPGRAM_API_KEY)
const deepgram = createClient();

// Method 4: Access token authentication
const deepgram = createClient({ accessToken: "YOUR_ACCESS_TOKEN" });

// Method 5: Proxy authentication for browser
const deepgram = createClient("proxy", {
  global: { fetch: { options: { proxy: { url: "http://localhost:8080" } } } },
});

// Method 6: Custom API URL (e.g., beta environment)
const deepgram = createClient("YOUR_API_KEY", {
  global: { fetch: { options: { url: "https://api.beta.deepgram.com" } } },
});

// Method 7: Auth factory for automatic token refresh
const deepgram = createClient({
  accessToken: async () => {
    const tokenClient = createClient("YOUR_API_KEY");
    const { result } = await tokenClient.auth.grantToken();
    return result.access_token;
  }
});
```

## Speech-to-Text (Transcription)

### listen.prerecorded.transcribeUrl - Transcribe Audio from URL

Transcribes pre-recorded audio from a publicly accessible URL. Returns the full transcription with word-level timing, confidence scores, and alternative transcripts.

```javascript
import { createClient } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

const { result, error } = await deepgram.listen.prerecorded.transcribeUrl(
  { url: "https://dpgr.am/spacewalk.wav" },
  {
    model: "nova-3",           // Latest Deepgram model
    smart_format: true,        // Apply formatting (punctuation, etc.)
    language: "en",            // Language code
    punctuate: true,           // Add punctuation
    diarize: true,             // Speaker diarization
    utterances: true,          // Split into utterances
  }
);

if (error) {
  console.error("Transcription error:", error);
} else {
  // Access transcript
  const transcript = result.results.channels[0].alternatives[0].transcript;
  console.log("Transcript:", transcript);

  // Access word-level details
  const words = result.results.channels[0].alternatives[0].words;
  words.forEach(word => {
    console.log(`${word.word} (${word.start}s - ${word.end}s, confidence: ${word.confidence})`);
  });
}
```

### listen.prerecorded.transcribeFile - Transcribe Local Audio File

Transcribes audio from a local file buffer. Supports various audio formats including WAV, MP3, FLAC, and more.

```javascript
import { createClient } from "@deepgram/sdk";
import { readFileSync } from "fs";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

// Read audio file as buffer
const audioBuffer = readFileSync("./audio/recording.wav");

const { result, error } = await deepgram.listen.prerecorded.transcribeFile(
  audioBuffer,
  {
    model: "nova-3",
    smart_format: true,
    detect_language: true,     // Auto-detect language
    paragraphs: true,          // Group into paragraphs
    summarize: "v2",           // Include summary
    topics: true,              // Extract topics
    intents: true,             // Detect intents
    sentiment: true,           // Analyze sentiment
  }
);

if (error) {
  console.error("Error:", error);
} else {
  console.log("Transcript:", result.results.channels[0].alternatives[0].transcript);
  console.log("Detected language:", result.results.channels[0].detected_language);

  if (result.results.summary) {
    console.log("Summary:", result.results.summary.short);
  }
}
```

### listen.prerecorded.transcribeUrlCallback - Async Transcription with Callback

Submits audio for transcription and receives results via webhook callback. Useful for long audio files where you don't want to wait for completion.

```javascript
import { createClient, CallbackUrl } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

const { result, error } = await deepgram.listen.prerecorded.transcribeUrlCallback(
  { url: "https://dpgr.am/spacewalk.wav" },
  new CallbackUrl("https://your-server.com/webhook/transcription"),
  {
    model: "nova-3",
    smart_format: true,
  }
);

if (error) {
  console.error("Error submitting transcription:", error);
} else {
  console.log("Request ID:", result.request_id);
  // Results will be POSTed to your callback URL when ready
}
```

### listen.live - Live Streaming Transcription (WebSocket)

Establishes a WebSocket connection for real-time audio transcription. Supports continuous streaming with interim and final results.

```javascript
import { createClient, LiveTranscriptionEvents } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

// Create live transcription connection
const connection = deepgram.listen.live({
  model: "nova-3",
  language: "en",
  smart_format: true,
  interim_results: true,      // Get partial results as speech is detected
  utterance_end_ms: 1000,     // Silence duration to end utterance
  vad_events: true,           // Voice activity detection events
  endpointing: 300,           // Endpointing sensitivity in ms
});

// Handle connection opened
connection.on(LiveTranscriptionEvents.Open, () => {
  console.log("WebSocket connection opened");

  // Send audio data (from microphone, file, or stream)
  // connection.send(audioChunk);  // Buffer or ArrayBuffer
});

// Handle transcription results
connection.on(LiveTranscriptionEvents.Transcript, (data) => {
  const transcript = data.channel.alternatives[0].transcript;

  if (data.is_final) {
    console.log("Final:", transcript);
  } else {
    console.log("Interim:", transcript);
  }
});

// Handle speech started
connection.on(LiveTranscriptionEvents.SpeechStarted, (data) => {
  console.log("Speech detected at:", data.timestamp);
});

// Handle utterance end
connection.on(LiveTranscriptionEvents.UtteranceEnd, (data) => {
  console.log("Utterance ended");
});

// Handle errors
connection.on(LiveTranscriptionEvents.Error, (error) => {
  console.error("WebSocket error:", error);
});

// Handle connection closed
connection.on(LiveTranscriptionEvents.Close, () => {
  console.log("WebSocket connection closed");
});

// Send audio from a stream (example with BBC radio)
import fetch from "cross-fetch";

fetch("http://stream.live.vc.bbcmedia.co.uk/bbc_world_service")
  .then((r) => r.body)
  .then((stream) => {
    stream.on("readable", () => {
      const chunk = stream.read();
      if (chunk) connection.send(chunk);
    });
  });

// Keep connection alive (send every 8 seconds if no audio)
setInterval(() => {
  connection.keepAlive();
}, 8000);

// Request graceful close when done
connection.requestClose();
```

## Text-to-Speech

### speak.request - Single Request Text-to-Speech

Converts text to speech audio using Deepgram's Aura voice models. Returns an audio stream that can be saved to a file or played directly.

```javascript
import { createClient } from "@deepgram/sdk";
import { writeFileSync } from "fs";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

const text = "Hello! Welcome to Deepgram's text-to-speech API. This is a demonstration of natural-sounding voice synthesis.";

// Request text-to-speech conversion
const response = await deepgram.speak.request(
  { text },
  {
    model: "aura-asteria-en",    // Voice model
    encoding: "mp3",             // Output format: mp3, wav, flac, etc.
    sample_rate: 24000,          // Sample rate in Hz
  }
);

// Get audio stream and headers
const stream = await response.getStream();
const headers = await response.getHeaders();

if (stream) {
  // Collect audio chunks
  const chunks = [];
  for await (const chunk of stream) {
    chunks.push(chunk);
  }
  const audioBuffer = Buffer.concat(chunks);

  // Save to file
  writeFileSync("output.mp3", audioBuffer);
  console.log("Audio saved to output.mp3");

  // Check response metadata
  console.log("Content-Type:", headers.get("content-type"));
  console.log("Request-ID:", headers.get("x-request-id"));
}
```

### speak.live - Live Streaming Text-to-Speech (WebSocket)

Establishes a WebSocket connection for streaming text-to-speech. Allows sending text incrementally and receiving audio chunks in real-time.

```javascript
import { createClient, LiveTTSEvents } from "@deepgram/sdk";
import { writeFileSync } from "fs";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

// Create live TTS connection
const connection = deepgram.speak.live({
  model: "aura-asteria-en",
  encoding: "linear16",
  sample_rate: 24000,
});

const audioChunks = [];

// Handle connection opened
connection.on(LiveTTSEvents.Open, () => {
  console.log("TTS WebSocket opened");

  // Send text for synthesis
  connection.sendText("Hello! This is the first sentence.");
  connection.sendText("And here is another sentence to speak.");

  // Flush to trigger audio generation
  connection.flush();
});

// Handle audio data received
connection.on(LiveTTSEvents.Audio, (audioData) => {
  console.log("Received audio chunk:", audioData.length, "bytes");
  audioChunks.push(audioData);
});

// Handle flush confirmation
connection.on(LiveTTSEvents.Flushed, () => {
  console.log("Buffer flushed, audio generated");
});

// Handle metadata
connection.on(LiveTTSEvents.Metadata, (metadata) => {
  console.log("Metadata:", metadata);
});

// Handle warnings
connection.on(LiveTTSEvents.Warning, (warning) => {
  console.warn("TTS Warning:", warning);
});

// Handle errors
connection.on(LiveTTSEvents.Error, (error) => {
  console.error("TTS Error:", error);
});

// Handle connection closed
connection.on(LiveTTSEvents.Close, () => {
  console.log("TTS WebSocket closed");

  // Save collected audio
  const audioBuffer = Buffer.concat(audioChunks);
  writeFileSync("live_output.wav", audioBuffer);
  console.log("Audio saved to live_output.wav");
});

// Clear buffer if needed
// connection.clear();

// Request close when done
// connection.requestClose();
```

## Voice Agent API

### agent - Voice Agent WebSocket

Creates an interactive voice agent that can converse with users in real-time. The agent listens to speech, processes it with an LLM, and responds with synthesized speech.

```javascript
import { createClient, AgentEvents } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

// Create agent connection
const connection = deepgram.agent();

// Handle connection opened
connection.on(AgentEvents.Open, () => {
  console.log("Agent connected");

  // Configure the agent
  connection.configure({
    // Tags for analytics and filtering
    tags: ["customer-support", "demo"],

    agent: {
      // Speech-to-text configuration
      listen: {
        provider: {
          type: "deepgram",
          model: "nova-3"
        }
      },

      // Text-to-speech configuration
      speak: {
        provider: {
          type: "deepgram",
          model: "aura-asteria-en"
        }
      },

      // LLM configuration
      think: {
        provider: {
          type: "open_ai",
          model: "gpt-4o-mini"
        },
        instructions: "You are a helpful customer service assistant. Be concise and friendly."
      },

      // Initial greeting
      greeting: "Hello! How can I help you today?"
    }
  });
});

// Handle settings applied
connection.on(AgentEvents.SettingsApplied, () => {
  console.log("Agent configuration applied");
  // Now safe to start sending audio
});

// Handle welcome event
connection.on(AgentEvents.Welcome, (data) => {
  console.log("Welcome, request ID:", data.request_id);
});

// Handle conversation text (both user and agent messages)
connection.on(AgentEvents.ConversationText, (data) => {
  console.log(`${data.role}: ${data.content}`);
});

// Handle user started speaking
connection.on(AgentEvents.UserStartedSpeaking, () => {
  console.log("User speaking...");
});

// Handle agent thinking
connection.on(AgentEvents.AgentThinking, (data) => {
  console.log("Agent thinking:", data.content);
});

// Handle agent started speaking
connection.on(AgentEvents.AgentStartedSpeaking, (data) => {
  console.log("Agent responding (latency:", data.total_latency, "ms)");
});

// Handle agent audio
connection.on(AgentEvents.Audio, (audioData) => {
  // Play or save audio response
  // audioPlayer.play(audioData);
});

// Handle agent finished speaking
connection.on(AgentEvents.AgentAudioDone, () => {
  console.log("Agent finished speaking");
});

// Handle function call requests (for custom actions)
connection.on(AgentEvents.FunctionCallRequest, (data) => {
  console.log("Function call requested:", data.functions);

  // Process function calls
  data.functions.forEach(async (fn) => {
    if (fn.name === "get_weather") {
      const args = JSON.parse(fn.arguments);
      const weather = await getWeather(args.location);

      // Send function response
      connection.functionCallResponse({
        function_call_id: fn.id,
        output: JSON.stringify(weather)
      });
    }
  });
});

// Handle errors
connection.on(AgentEvents.Error, (error) => {
  console.error("Agent error:", error);
});

// Handle connection closed
connection.on(AgentEvents.Close, () => {
  console.log("Agent disconnected");
});

// Send user audio (from microphone)
// connection.send(audioBuffer);

// Inject agent message programmatically
connection.injectAgentMessage("Please hold while I look that up.");

// Inject user message (text-based input)
connection.injectUserMessage("What is the weather in New York?");

// Update agent prompt mid-conversation
connection.updatePrompt("You are now a technical support specialist.");

// Update voice model
connection.updateSpeak({ provider: { type: "deepgram", model: "aura-orion-en" } });

// Keep connection alive (send every 8 seconds)
setInterval(() => connection.keepAlive(), 8000);
```

## Text Intelligence

### read.analyzeText - Analyze Text Content

Analyzes text for sentiment, intent, topics, and other linguistic features using Deepgram's text intelligence models.

```javascript
import { createClient } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

const text = `
The customer service was excellent! The representative was patient and
helpful in resolving my billing issue. I will definitely recommend this
company to my friends. However, the hold time was a bit long.
`;

const { result, error } = await deepgram.read.analyzeText(
  { text },
  {
    language: "en",
    sentiment: true,           // Analyze sentiment
    intents: true,             // Detect intents
    topics: true,              // Extract topics
    summarize: true,           // Generate summary
  }
);

if (error) {
  console.error("Analysis error:", error);
} else {
  console.log("Analysis results:", JSON.stringify(result, null, 2));

  // Access sentiment
  if (result.results.sentiments) {
    result.results.sentiments.segments.forEach(segment => {
      console.log(`Sentiment: ${segment.sentiment} (${segment.text})`);
    });
  }

  // Access topics
  if (result.results.topics) {
    result.results.topics.segments.forEach(segment => {
      segment.topics.forEach(topic => {
        console.log(`Topic: ${topic.topic} (confidence: ${topic.confidence})`);
      });
    });
  }
}
```

### read.analyzeUrl - Analyze Text from URL

Analyzes text content from a URL source for sentiment, intent, and other features.

```javascript
import { createClient } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

const { result, error } = await deepgram.read.analyzeUrl(
  { url: "https://example.com/article.txt" },
  {
    language: "en",
    sentiment: true,
    summarize: true,
  }
);

if (error) {
  console.error("Error:", error);
} else {
  console.log("Analysis:", result);
}
```

## Authentication & Token Management

### auth.grantToken - Generate Temporary Access Token

Creates a temporary access token with a short TTL (default 30 seconds). Useful for browser applications where you don't want to expose your API key.

```javascript
import { createClient } from "@deepgram/sdk";

// Server-side: Generate token using API key
const serverClient = createClient(process.env.DEEPGRAM_API_KEY);

const { result, error } = await serverClient.auth.grantToken({
  ttl_seconds: 60  // Optional: custom TTL (max varies by plan)
});

if (error) {
  console.error("Token error:", error);
} else {
  console.log("Access token:", result.access_token);
  console.log("Expires in:", result.expires_in, "seconds");

  // Client-side: Use token for API calls
  const clientApp = createClient({ accessToken: result.access_token });

  // Now use clientApp for transcription, etc.
  const response = await clientApp.listen.prerecorded.transcribeUrl(
    { url: "https://dpgr.am/spacewalk.wav" },
    { model: "nova-3" }
  );
}
```

### manage.getTokenDetails - Get Current Token Information

Retrieves details about the currently authenticated token including scopes and project information.

```javascript
import { createClient } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

const { result, error } = await deepgram.manage.getTokenDetails();

if (error) {
  console.error("Error:", error);
} else {
  console.log("Token details:", result);
  console.log("Scopes:", result.scopes);
  console.log("Project ID:", result.project_id);
}
```

## Project Management

### manage.getProjects - List All Projects

Retrieves all projects accessible by the current API key.

```javascript
import { createClient } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

const { result, error } = await deepgram.manage.getProjects();

if (error) {
  console.error("Error:", error);
} else {
  result.projects.forEach(project => {
    console.log(`Project: ${project.name} (ID: ${project.project_id})`);
  });
}
```

### manage.getProject - Get Project Details

Retrieves details for a specific project by ID.

```javascript
import { createClient } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);
const projectId = "your-project-id";

const { result, error } = await deepgram.manage.getProject(projectId);

if (error) {
  console.error("Error:", error);
} else {
  console.log("Project name:", result.name);
  console.log("Company:", result.company);
}
```

### manage.updateProject - Update Project

Updates project settings such as name and company.

```javascript
import { createClient } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

const { result, error } = await deepgram.manage.updateProject(
  "your-project-id",
  {
    name: "Updated Project Name",
    company: "My Company Inc."
  }
);

if (error) {
  console.error("Error:", error);
} else {
  console.log("Update result:", result.message);
}
```

### manage.deleteProject - Delete Project

Permanently deletes a project and all associated data.

```javascript
import { createClient } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

const { error } = await deepgram.manage.deleteProject("project-id-to-delete");

if (error) {
  console.error("Delete failed:", error);
} else {
  console.log("Project deleted successfully");
}
```

## API Key Management

### manage.getProjectKeys - List API Keys

Lists all API keys for a project.

```javascript
import { createClient } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

const { result, error } = await deepgram.manage.getProjectKeys("your-project-id");

if (error) {
  console.error("Error:", error);
} else {
  result.api_keys.forEach(key => {
    console.log(`Key: ${key.api_key_id} - ${key.comment}`);
    console.log(`  Created: ${key.created}`);
    console.log(`  Scopes: ${key.scopes.join(", ")}`);
  });
}
```

### manage.createProjectKey - Create API Key

Creates a new API key with specified scopes and optional expiration.

```javascript
import { createClient } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

const { result, error } = await deepgram.manage.createProjectKey(
  "your-project-id",
  {
    comment: "Production transcription key",
    scopes: ["usage:write", "keys:read"],
    tags: ["production", "transcription"],
    time_to_live_in_seconds: 86400 * 30,  // 30 days
    // OR use expiration_date: "2024-12-31T23:59:59Z"
  }
);

if (error) {
  console.error("Error:", error);
} else {
  console.log("New API Key:", result.key);  // Only shown once!
  console.log("Key ID:", result.api_key_id);
}
```

### manage.deleteProjectKey - Delete API Key

Deletes an API key from a project.

```javascript
import { createClient } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

const { error } = await deepgram.manage.deleteProjectKey(
  "your-project-id",
  "key-id-to-delete"
);

if (error) {
  console.error("Delete failed:", error);
} else {
  console.log("API key deleted");
}
```

## Usage & Billing

### manage.getProjectUsageSummary - Get Usage Summary

Retrieves usage statistics for a project within a date range.

```javascript
import { createClient } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

const { result, error } = await deepgram.manage.getProjectUsageSummary(
  "your-project-id",
  {
    start: "2024-01-01",
    end: "2024-01-31",
    accessor: "model",  // Group by: model, method, language, etc.
  }
);

if (error) {
  console.error("Error:", error);
} else {
  console.log("Total hours:", result.resolution.hours);
  result.results.forEach(item => {
    console.log(`${item.accessor}: ${item.hours} hours, ${item.requests} requests`);
  });
}
```

### manage.getProjectBalances - Get Account Balances

Retrieves credit balance information for a project.

```javascript
import { createClient } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

const { result, error } = await deepgram.manage.getProjectBalances("your-project-id");

if (error) {
  console.error("Error:", error);
} else {
  result.balances.forEach(balance => {
    console.log(`Balance ID: ${balance.balance_id}`);
    console.log(`  Amount: ${balance.amount} ${balance.units}`);
    console.log(`  Expires: ${balance.expiration_date}`);
  });
}
```

## Models

### models.getAll - List All Available Models

Retrieves all globally available Deepgram models.

```javascript
import { createClient } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

const { result, error } = await deepgram.models.getAll();

if (error) {
  console.error("Error:", error);
} else {
  result.stt.forEach(model => {
    console.log(`STT Model: ${model.name} - ${model.description}`);
  });

  result.tts.forEach(model => {
    console.log(`TTS Model: ${model.name} - ${model.description}`);
  });
}
```

### manage.getAllModels - List Project Models

Retrieves models available for a specific project.

```javascript
import { createClient } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

const { result, error } = await deepgram.manage.getAllModels(
  "your-project-id",
  { include_outdated: false }
);

if (error) {
  console.error("Error:", error);
} else {
  console.log("Available models:", result);
}
```

## Self-Hosted (On-Prem) Credentials

### selfhosted.listCredentials - List Distribution Credentials

Lists self-hosted distribution credentials for a project.

```javascript
import { createClient } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

const { result, error } = await deepgram.selfhosted.listCredentials("your-project-id");

if (error) {
  console.error("Error:", error);
} else {
  result.distribution_credentials.forEach(cred => {
    console.log(`Credential: ${cred.member.email}`);
    console.log(`  ID: ${cred.distribution_credentials_id}`);
  });
}
```

### selfhosted.createCredentials - Create Distribution Credentials

Creates new self-hosted distribution credentials.

```javascript
import { createClient } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

const { result, error } = await deepgram.selfhosted.createCredentials(
  "your-project-id",
  {
    comment: "Production on-prem deployment",
    scopes: ["member"],
    provider: "docker"
  }
);

if (error) {
  console.error("Error:", error);
} else {
  console.log("Credential ID:", result.distribution_credentials_id);
  console.log("Member:", result.member);
}
```

## Caption Generation

### webvtt / srt - Generate Captions from Transcription

Converts transcription results into WebVTT or SRT caption formats.

```javascript
import { createClient, webvtt, srt } from "@deepgram/sdk";

const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

// First, get a transcription with timing information
const { result, error } = await deepgram.listen.prerecorded.transcribeUrl(
  { url: "https://dpgr.am/spacewalk.wav" },
  {
    model: "nova-3",
    smart_format: true,
    utterances: true,  // Required for caption generation
  }
);

if (error) {
  console.error("Error:", error);
} else {
  // Generate WebVTT captions
  const vttCaptions = webvtt(result);
  console.log("WebVTT:\n", vttCaptions);
  // Output:
  // WEBVTT
  //
  // 00:00:00.000 --> 00:00:03.500
  // This is the first caption line.

  // Generate SRT captions
  const srtCaptions = srt(result);
  console.log("SRT:\n", srtCaptions);
  // Output:
  // 1
  // 00:00:00,000 --> 00:00:03,500
  // This is the first caption line.
}
```

## Browser Usage Examples

### Browser with CDN (UMD)

Use the SDK in browsers via CDN for quick prototyping.

```html
<!DOCTYPE html>
<html>
<head>
  <title>Deepgram Browser Example</title>
</head>
<body>
  <button id="start">Start Recording</button>
  <div id="transcript"></div>

  <script src="https://cdn.jsdelivr.net/npm/@deepgram/sdk"></script>
  <script>
    const { createClient, LiveTranscriptionEvents } = deepgram;

    // For live transcription (WebSocket works directly)
    const client = createClient("YOUR_API_KEY");

    document.getElementById("start").onclick = async () => {
      const connection = client.listen.live({
        model: "nova-3",
        smart_format: true,
      });

      connection.on(LiveTranscriptionEvents.Transcript, (data) => {
        const transcript = data.channel.alternatives[0].transcript;
        document.getElementById("transcript").innerText += transcript + " ";
      });

      // Get microphone access
      const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
      const mediaRecorder = new MediaRecorder(stream);

      mediaRecorder.ondataavailable = (event) => {
        if (event.data.size > 0) {
          connection.send(event.data);
        }
      };

      mediaRecorder.start(250); // Send chunks every 250ms
    };
  </script>
</body>
</html>
```

### Browser with ES Modules

Use the SDK with ES modules in modern browsers.

```html
<script type="module">
  import { createClient, LiveTranscriptionEvents } from "https://cdn.jsdelivr.net/npm/@deepgram/sdk/+esm";

  const client = createClient("YOUR_API_KEY");
  const connection = client.listen.live({ model: "nova-3" });

  connection.on(LiveTranscriptionEvents.Open, () => {
    console.log("Connected to Deepgram");
  });

  connection.on(LiveTranscriptionEvents.Transcript, (data) => {
    console.log("Transcript:", data.channel.alternatives[0].transcript);
  });
</script>
```

## Summary

The Deepgram JavaScript SDK provides a comprehensive interface for building speech-enabled applications. The primary use cases include real-time transcription for live streaming applications like video conferencing, podcasting, and accessibility tools; batch transcription for processing recorded audio files such as call center recordings, meeting transcripts, and media archives; text-to-speech synthesis for creating voiceovers, accessibility features, and interactive voice applications; and conversational AI with the Voice Agent API for building customer service bots, virtual assistants, and interactive voice response systems.

Integration patterns typically follow a namespace-based approach where `deepgram.listen` handles speech-to-text, `deepgram.speak` handles text-to-speech, `deepgram.read` handles text intelligence, `deepgram.agent()` creates voice agents, and `deepgram.manage` handles project and account management. For production applications, use API keys server-side and temporary access tokens for client-side browser applications. WebSocket-based features (live transcription, live TTS, voice agents) support direct browser connections, while REST API features require a proxy server in browser environments due to CORS restrictions. Error handling follows a consistent `{ result, error }` pattern, making it easy to handle failures gracefully across all API methods.