Deepgram Transcription

Overview

When to Use This Skill

• Transcribing audio files (mp3, wav, m4a, aac, etc.)
• Transcribing video files (mp4, mov, avi, mkv, etc.)
• Converting speech in media files to text
• Creating transcripts with or without timestamps
• Processing multiple recordings for documentation

Core Workflow

1. Determine Input Type

• Can be transcribed directly
• Smaller file sizes, faster uploads

• Should extract audio first for files >50MB
• Reduces upload time significantly (e.g., 190MB video → 3MB audio)
• No quality loss for transcription purposes

2. Extract Audio (For Video Files)

ffmpeg -i input_video.mp4 -vn -acodec aac -b:a 128k output_audio.m4a -y

• -vn

  : No video (audio only)

• -acodec aac

  : AAC audio codec

• -b:a 128k

  : 128kbps bitrate (good quality, small size)

• -y

  : Overwrite output file

3. Transcribe with Deepgram

scripts/transcribe.py

scripts/transcribe.py input_file.mp4 \
  --api-key YOUR_DEEPGRAM_API_KEY \
  --output-dir ./transcripts \
  --extract-audio

curl -X POST "https://api.deepgram.com/v1/listen?model=nova-2&smart_format=true" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: audio/mp4" \
  --data-binary @audio_file.m4a \
  -o transcription.json

4. Extract and Save Results

{
  "results": {
    "channels": [{
      "alternatives": [{
        "transcript": "Full text here...",
        "words": [
          {"word": "hello", "start": 0.5, "end": 0.9, "confidence": 0.99}
        ]
      }]
    }]
  }
}

cat transcription.json | python3 -c "import json, sys; data=json.load(sys.stdin); print(data['results']['channels'][0]['alternatives'][0]['transcript'])" > transcript.txt

Using the Transcription Script

scripts/transcribe.py

Basic Usage

# Transcribe a video file (auto-extracts audio)
scripts/transcribe.py video.mp4 --api-key YOUR_KEY --extract-audio

# Transcribe an audio file directly
scripts/transcribe.py audio.mp3 --api-key YOUR_KEY

# Specify output directory
scripts/transcribe.py video.mov --api-key YOUR_KEY --output-dir ./transcripts

Advanced Options

# Use a different Deepgram model
scripts/transcribe.py file.mp4 --api-key YOUR_KEY --model whisper-large

# Disable smart formatting
scripts/transcribe.py file.mp4 --api-key YOUR_KEY --no-smart-format

# Custom audio bitrate when extracting
scripts/transcribe.py file.mp4 --api-key YOUR_KEY --extract-audio --audio-bitrate 192k

Output Files

1. {filename}_transcription.json

   - Full Deepgram response with timestamps

2. {filename}_transcript.txt

   - Clean text transcript only

Recommended Settings

nova-2

• Latest and most accurate model
• Good balance of speed and quality
• Handles various accents and audio quality

• Automatic punctuation
• Proper capitalization
• Number formatting
• Better readability

• Excellent speech quality
• Small file size
• Fast uploads

Common Scenarios

Scenario 1: Single Video File

# User: "Transcribe this video recording"
scripts/transcribe.py recording.mp4 --api-key KEY --extract-audio

Scenario 2: Multiple Screen Recordings

# Extract audio from all videos first
for f in *.mov; do
  ffmpeg -i "$f" -vn -acodec aac -b:a 128k "${f%.mov}_audio.m4a" -y
done

# Transcribe all audio files
for f in *_audio.m4a; do
  scripts/transcribe.py "$f" --api-key KEY --output-dir ./transcripts
done

Scenario 3: Audio-Only File

# Direct transcription (no extraction needed)
scripts/transcribe.py podcast.mp3 --api-key KEY

Troubleshooting

File Access Issues

• Check file permissions:

  ls -l filename

• Ensure file exists:

  file filename

• Use absolute paths if needed

Large File Uploads Timing Out

1. Always extract audio first (

   --extract-audio

   )
2. Increase timeout in script if needed
3. Consider splitting long recordings

API Key Issues

• Verify API key is correct
• Check Deepgram account has available credits
• Ensure no extra spaces in key

File Size Guidelines

Resources

scripts/transcribe.py

• Audio extraction from video
• Deepgram API calls
• Response parsing
• Output file generation

references/api_reference.md

• Available models and features
• API parameters and options
• Response format details
• Best practices