Deepgram Transcription

Overview

This skill enables efficient transcription of audio and video files using the Deepgram API. It automatically handles large video files by extracting audio first, reducing upload time and API costs. Outputs include both full JSON responses with timestamps and clean text transcripts.

When to Use This Skill

Use this skill when:

• 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

First, identify the input file type:

Audio files (mp3, wav, m4a, aac):

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

Video files (mp4, mov, avi, etc.):

• 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)

For video files, especially those larger than 50MB, extract audio before transcription:

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

Parameters:

• -vn: No video (audio only)
• -acodec aac: AAC audio codec
• -b:a 128k: 128kbps bitrate (good quality, small size)
• -y: Overwrite output file

This reduces file size by ~98% while preserving speech quality.

3. Transcribe with Deepgram

Use the provided scripts/transcribe.py script for automated transcription:

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

Or use curl directly for manual control:

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

The transcription response includes:

Full JSON (with timestamps, confidence scores, metadata):

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

Extract plain text transcript:

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

The scripts/transcribe.py provides a complete workflow:

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

The script generates:

1. {filename}_transcription.json - Full Deepgram response with timestamps
2. {filename}_transcript.txt - Clean text transcript only

Recommended Settings

Deepgram Model: nova-2

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

Smart Formatting: Enabled (default)

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

Audio Bitrate: 128kbps

• 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

If encountering permission errors:

• Check file permissions: ls -l filename
• Ensure file exists: file filename
• Use absolute paths if needed

Large File Uploads Timing Out

For very large files:

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

Input Type	Size	Recommendation
Audio	Any	Transcribe directly
Video	< 50MB	Can transcribe directly
Video	50-200MB	Extract audio first
Video	> 200MB	Must extract audio first

Resources

scripts/transcribe.py

Complete Python script handling:

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

Execute without loading into context for efficiency.

references/api_reference.md

Deepgram API documentation including:

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

Load into context when needing detailed API information.