deepgram-hello-world

Create a minimal working Deepgram transcription example. Use when starting a new Deepgram integration, testing your setup, or learning basic Deepgram API patterns. Trigger: "deepgram hello world", "deepgram example", "deepgram quick start", "simple transcription", "transcribe audio".

SKILL.md

Quality

Evals

Security

Deepgram Hello World

Examples

Transcribe a short licensed fixture in the development project, verify the response shape and selected model/language, and remove the fixture according to the test policy. Keep only a correlation ID and aggregate result in logs; do not use a customer call or retain its transcript as a tutorial artifact.

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

Next Steps

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

Repository: jeremylongshore/tons-of-skills-marketplace
Path: plugins/saas-packs/deepgram-pack/skills/deepgram-hello-world/SKILL.md
Commit: 88dcf65

Last updated: 3 days ago
First committed: 9 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.