Agent skill

deepgram-debug-bundle

Collect Deepgram debug evidence for support and troubleshooting. Use when preparing support tickets, investigating issues, or collecting diagnostic information for Deepgram problems. Trigger: "deepgram debug", "deepgram support ticket", "collect deepgram logs", "deepgram diagnostic", "deepgram debug bundle".

Stars 1,803
Forks 241

Install this agent skill to your Project

npx add-skill https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/saas-packs/deepgram-pack/skills/deepgram-debug-bundle

SKILL.md

Deepgram Debug Bundle

Current State

!node --version 2>/dev/null || echo 'Node.js not installed' !npm list @deepgram/sdk 2>/dev/null | grep deepgram || echo '@deepgram/sdk not found' !python3 --version 2>/dev/null || echo 'Python not installed'

Overview

Collect comprehensive debug information for Deepgram support tickets. Generates a sanitized bundle with environment info, API connectivity tests, audio analysis, request/response logs, and a minimal reproduction script. All API keys are automatically redacted.

Prerequisites

  • Deepgram API key configured
  • ffprobe available for audio analysis (part of ffmpeg)
  • Sample audio that reproduces the issue

Instructions

Step 1: Environment Collection Script

bash
#!/bin/bash
set -euo pipefail
BUNDLE_DIR="deepgram-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

# System info
{
  echo "=== System ==="
  uname -a
  echo ""
  echo "=== Node.js ==="
  node --version 2>/dev/null || echo "Not installed"
  echo ""
  echo "=== @deepgram/sdk ==="
  npm list @deepgram/sdk 2>/dev/null || echo "Not installed"
  echo ""
  echo "=== Python ==="
  python3 --version 2>/dev/null || echo "Not installed"
  pip show deepgram-sdk 2>/dev/null || echo "Not installed"
} > "$BUNDLE_DIR/environment.txt"

Step 2: API Connectivity Tests

bash
# Test REST API
{
  echo "=== REST API Test ==="
  echo "Timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
  echo ""
  echo "--- Project listing ---"
  curl -s -w "\nHTTP: %{http_code} | Time: %{time_total}s\n" \
    'https://api.deepgram.com/v1/projects' \
    -H "Authorization: Token $DEEPGRAM_API_KEY" 2>&1 | \
    sed "s/$DEEPGRAM_API_KEY/REDACTED/g"
  echo ""
  echo "--- Transcription test (Bueller sample) ---"
  curl -s -w "\nHTTP: %{http_code} | Time: %{time_total}s\n" \
    -X POST 'https://api.deepgram.com/v1/listen?model=nova-3&smart_format=true' \
    -H "Authorization: Token $DEEPGRAM_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url":"https://static.deepgram.com/examples/Bueller-Life-moves-702702706.wav"}' 2>&1 | \
    sed "s/$DEEPGRAM_API_KEY/REDACTED/g"
  echo ""
  echo "--- WebSocket handshake test ---"
  curl -s -w "\nHTTP: %{http_code}\n" -o /dev/null \
    'https://api.deepgram.com/v1/listen' \
    -H "Authorization: Token $DEEPGRAM_API_KEY" \
    -H "Upgrade: websocket" 2>&1 | \
    sed "s/$DEEPGRAM_API_KEY/REDACTED/g"
} > "$BUNDLE_DIR/connectivity.txt"

Step 3: Audio Analysis

bash
# Analyze problem audio file (if provided)
analyze_audio() {
  local file="$1"
  local outfile="$BUNDLE_DIR/audio-analysis.txt"

  {
    echo "=== Audio Analysis: $(basename "$file") ==="
    echo "File size: $(stat -f%z "$file" 2>/dev/null || stat -c%s "$file" 2>/dev/null)"
    echo ""

    if command -v ffprobe &>/dev/null; then
      echo "--- FFprobe Output ---"
      ffprobe -v quiet -print_format json -show_format -show_streams "$file"
      echo ""

      echo "--- Key Properties ---"
      local codec=$(ffprobe -v quiet -show_entries stream=codec_name -of csv=p=0 "$file")
      local rate=$(ffprobe -v quiet -show_entries stream=sample_rate -of csv=p=0 "$file")
      local channels=$(ffprobe -v quiet -show_entries stream=channels -of csv=p=0 "$file")
      local duration=$(ffprobe -v quiet -show_entries format=duration -of csv=p=0 "$file")
      local bitdepth=$(ffprobe -v quiet -show_entries stream=bits_per_sample -of csv=p=0 "$file")

      echo "Codec: $codec"
      echo "Sample rate: $rate Hz"
      echo "Channels: $channels"
      echo "Bit depth: $bitdepth"
      echo "Duration: ${duration}s"
      echo ""

      # Check for common issues
      echo "--- Compatibility Check ---"
      [[ "$rate" -lt 8000 ]] && echo "WARNING: Sample rate below 8kHz minimum"
      [[ "$rate" -gt 48000 ]] && echo "WARNING: Sample rate above 48kHz — consider downsampling"
      [[ "$channels" -gt 2 ]] && echo "WARNING: >2 channels — Deepgram supports mono/stereo"
    else
      echo "ffprobe not available — install ffmpeg for audio analysis"
      echo ""
      echo "--- File header (hex) ---"
      xxd -l 16 "$file"
    fi
  } > "$outfile"
}

Step 4: Request/Response Logger

typescript
// Wrap Deepgram client to capture full request/response for debugging
import { createClient } from '@deepgram/sdk';
import { writeFileSync } from 'fs';

async function captureDebugRequest(audioSource: string | Buffer) {
  const client = createClient(process.env.DEEPGRAM_API_KEY!);
  const startTime = Date.now();

  try {
    const isUrl = typeof audioSource === 'string';
    const method = isUrl ? 'transcribeUrl' : 'transcribeFile';
    const source = isUrl ? { url: audioSource } : audioSource;
    const options = { model: 'nova-3' as const, smart_format: true };

    const { result, error } = isUrl
      ? await client.listen.prerecorded.transcribeUrl(source as any, options)
      : await client.listen.prerecorded.transcribeFile(source as any, options);

    const elapsed = Date.now() - startTime;

    const debugLog = {
      timestamp: new Date().toISOString(),
      method,
      options,
      elapsed_ms: elapsed,
      success: !error,
      error: error ? { message: error.message, status: (error as any).status } : null,
      result_summary: result ? {
        request_id: result.metadata?.request_id,
        duration: result.metadata?.duration,
        model: result.metadata?.model_info,
        transcript_length: result.results?.channels[0]?.alternatives[0]?.transcript?.length,
        confidence: result.results?.channels[0]?.alternatives[0]?.confidence,
      } : null,
    };

    writeFileSync('debug-request.json', JSON.stringify(debugLog, null, 2));
    console.log('Debug log written to debug-request.json');
    return debugLog;
  } catch (err: any) {
    const debugLog = {
      timestamp: new Date().toISOString(),
      elapsed_ms: Date.now() - startTime,
      error: { message: err.message, stack: err.stack },
    };
    writeFileSync('debug-request.json', JSON.stringify(debugLog, null, 2));
    throw err;
  }
}

Step 5: Package and Sanitize Bundle

bash
# Package everything (API keys already redacted in Step 2)
{
  echo "=== Deepgram Debug Bundle ==="
  echo "Created: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
  echo ""
  echo "Issue Description: [DESCRIBE YOUR ISSUE HERE]"
  echo ""
  echo "Files:"
  echo "  environment.txt    - System and SDK versions"
  echo "  connectivity.txt   - API connectivity test results"
  echo "  audio-analysis.txt - Audio file properties (if provided)"
  echo "  debug-request.json - Request/response capture (if run)"
  echo ""
  echo "Attach this bundle to your support ticket at:"
  echo "  https://developers.deepgram.com/support"
} > "$BUNDLE_DIR/README.txt"

# Final sanitization pass — remove any leaked keys
find "$BUNDLE_DIR" -type f -exec sed -i "s/$DEEPGRAM_API_KEY/REDACTED/g" {} +

tar czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
echo "Bundle created: $BUNDLE_DIR.tar.gz"

Step 6: Support Ticket Template

Subject: [Issue Type] — Brief Description

Environment:
- SDK: @deepgram/sdk v3.x.x
- Runtime: Node.js 20.x / Python 3.12
- OS: Ubuntu 22.04

Request ID: (from result.metadata.request_id)
Model: nova-3
Timestamp: 2026-03-22T12:00:00Z

Issue:
[Describe what you expected vs what happened]

Steps to Reproduce:
1. [Step 1]
2. [Step 2]
3. [Observe error]

Attachments:
- deepgram-debug-YYYYMMDD-HHMMSS.tar.gz
- Sample audio file (if shareable)

Output

  • deepgram-debug-YYYYMMDD-HHMMSS.tar.gz with sanitized diagnostics
  • Environment and connectivity test results
  • Audio file analysis with compatibility warnings
  • Request/response debug capture
  • Support ticket template

Error Handling

Issue Cause Resolution
ffprobe not found ffmpeg not installed apt install ffmpeg or brew install ffmpeg
Connectivity test 401 Key not exported export DEEPGRAM_API_KEY=your-key
Empty audio analysis File path wrong Verify file exists and is readable
Tar fails Permissions issue Check write permissions in current directory

Resources

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results