deepgram-hello-world

Deepgram Hello World

Overview

Minimal working examples for Deepgram speech-to-text. Transcribe an audio URL in 5 lines with createClient + listen.prerecorded.transcribeUrl. Includes local file transcription, Python equivalent, and Nova-3 model selection.

Prerequisites

• npm install @deepgram/sdk completed
• DEEPGRAM_API_KEY environment variable set
• Audio source: URL or local file (WAV, MP3, FLAC, OGG, M4A)

Instructions

Step 1: Transcribe Audio from URL (TypeScript)

import { createClient } from '@deepgram/sdk';

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

async function main() {
  const { result, error } = await deepgram.listen.prerecorded.transcribeUrl(
    { url: 'https://static.deepgram.com/examples/Bueller-Life-moves-702702706.wav' },
    {
      model: 'nova-3',        // Latest model — best accuracy
      smart_format: true,     // Auto-punctuation, paragraphs, numerals
      language: 'en',
    }
  );

  if (error) throw error;

  const transcript = result.results.channels[0].alternatives[0].transcript;
  console.log('Transcript:', transcript);
  console.log('Confidence:', result.results.channels[0].alternatives[0].confidence);
}

main();

Step 2: Transcribe a Local File

import { createClient } from '@deepgram/sdk';
import { readFileSync } from 'fs';

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

async function transcribeFile(filePath: string) {
  const audio = readFileSync(filePath);

  const { result, error } = await deepgram.listen.prerecorded.transcribeFile(
    audio,
    {
      model: 'nova-3',
      smart_format: true,
      // Deepgram auto-detects format, but you can specify:
      mimetype: 'audio/wav',
    }
  );

  if (error) throw error;

  console.log(result.results.channels[0].alternatives[0].transcript);
}

transcribeFile('./meeting-recording.wav');

Step 3: Python Equivalent

import os
from deepgram import DeepgramClient, PrerecordedOptions

client = DeepgramClient(os.environ["DEEPGRAM_API_KEY"])

# URL transcription
url = {"url": "https://static.deepgram.com/examples/Bueller-Life-moves-702702706.wav"}
options = PrerecordedOptions(model="nova-3", smart_format=True, language="en")

response = client.listen.rest.v("1").transcribe_url(url, options)
transcript = response.results.channels[0].alternatives[0].transcript
print(f"Transcript: {transcript}")
print(f"Confidence: {response.results.channels[0].alternatives[0].confidence}")

# Local file transcription
with open("meeting.wav", "rb") as audio:
    source = {"buffer": audio.read(), "mimetype": "audio/wav"}
    response = client.listen.rest.v("1").transcribe_file(source, options)
    print(response.results.channels[0].alternatives[0].transcript)

Step 4: Add Features

// Enable diarization (speaker identification)
const { result } = await deepgram.listen.prerecorded.transcribeUrl(
  { url: audioUrl },
  {
    model: 'nova-3',
    smart_format: true,
    diarize: true,         // Speaker labels
    utterances: true,      // Turn-by-turn segments
    paragraphs: true,      // Paragraph formatting
  }
);

// Print speaker-labeled output
if (result.results.utterances) {
  for (const utterance of result.results.utterances) {
    console.log(`Speaker ${utterance.speaker}: ${utterance.transcript}`);
  }
}

Step 5: Explore Model Options

Model	Use Case	Speed	Accuracy
nova-3	General — best accuracy	Fast	Highest
nova-2	General — proven stable	Fast	Very High
nova-2-meeting	Conference rooms, multiple speakers	Fast	High
nova-2-phonecall	Low-bandwidth phone audio	Fast	High
base	Cost-sensitive, high-volume	Fastest	Good
whisper-large	Multilingual (100+ languages)	Slow	High

Step 6: Run It

# TypeScript
npx tsx hello-deepgram.ts

# Python
python hello_deepgram.py

Output

• Working transcription from URL or local file
• Printed transcript text with confidence score
• Optional: speaker-labeled utterances

Error Handling

Error	Cause	Solution
401 Unauthorized	Invalid API key	Check DEEPGRAM_API_KEY
400 Bad Request	Unsupported audio format	Use WAV, MP3, FLAC, OGG, or M4A
Empty transcript	No speech in audio	Verify audio has audible speech
ENOTFOUND	URL not reachable	Check audio URL is publicly accessible
Cannot find module '@deepgram/sdk'	SDK not installed	Run npm install @deepgram/sdk

Resources

• Pre-recorded Audio Guide
• Model Options
• Smart Formatting
• Sample Audio Files

Next Steps

Proceed to deepgram-core-workflow-a for production transcription patterns or deepgram-core-workflow-b for live streaming.