Deepgram Performance TuningSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: deepgram-performance-tuning
description: 'Optimize Deepgram API performance for faster transcription and lower
  latency.

  Use when improving transcription speed, reducing latency,

  or optimizing audio processing pipelines.

  Trigger: "deepgram performance", "speed up deepgram", "optimize transcription",

  "deepgram latency", "deepgram faster", "deepgram throughput".

  '
allowed-tools: Read, Write, Edit, Bash(ffmpeg:*), Bash(ffprobe:*)
version: 1.13.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- deepgram
- api
- performance
- optimization
compatibility: Designed for Claude Code
---
# Deepgram Performance Tuning

## Prerequisites

- A baseline for latency, throughput, quality, error/throttle rate, and a named service owner.
- Licensed non-sensitive fixtures, approved load window, and a rollback threshold.

## Examples

Measure the development/staging transcription baseline with short fixtures, change one concurrency, streaming, or model parameter, and compare aggregate quality/latency/error results. Keep the change only within the signed threshold; revert on regression and never use customer recordings as performance fixtures.

## Overview

Optimize Deepgram transcription performance through audio preprocessing with ffmpeg, model selection for speed vs accuracy, streaming for large files, parallel processing, result caching, and connection reuse. Targets: <2s latency for short files, 100+ files/minute batch throughput.

## Performance Levers

| Factor | Impact | Default | Optimized |
|--------|--------|---------|-----------|
| Audio format | High | Any format | 16kHz mono WAV |
| Model | High | nova-3 | base (speed) or nova-3 (accuracy) |
| File size | High | Full file sync | Stream >60s, callback >5min |
| Concurrency | Medium | Sequential | 50 parallel (p-limit) |
| Caching | Medium | None | Redis hash by audio+options |
| Features | Medium | All enabled | Disable unused (diarize, utterances) |

## Instructions

### Step 1: Audio Preprocessing with ffmpeg

```bash
# Optimal format for Deepgram: 16kHz, 16-bit, mono, WAV
ffmpeg -i input.mp3 \
  -ar 16000 \          # 16kHz sample rate (ideal for speech)
  -ac 1 \              # Mono channel
  -acodec pcm_s16le \  # 16-bit signed LE PCM
  -f wav \
  output.wav

# Remove silence (saves API cost + processing time)
ffmpeg -i input.wav \
  -af "silenceremove=stop_periods=-1:stop_duration=0.5:stop_threshold=-30dB" \
  -ar 16000 -ac 1 -acodec pcm_s16le \
  trimmed.wav

# Noise reduction + normalization
ffmpeg -i input.wav \
  -af "highpass=f=200,lowpass=f=3000,loudnorm=I=-16:TP=-1.5:LRA=11" \
  -ar 16000 -ac 1 -acodec pcm_s16le \
  clean.wav
```

```typescript
import { execSync } from 'child_process';
import { statSync } from 'fs';

function preprocessAudio(inputPath: string, outputPath: string): {
  originalSize: number;
  optimizedSize: number;
  savings: string;
} {
  const originalSize = statSync(inputPath).size;

  execSync(`ffmpeg -y -i "${inputPath}" \
    -af "silenceremove=stop_periods=-1:stop_duration=0.5:stop_threshold=-30dB,\
    highpass=f=200,lowpass=f=3000" \
    -ar 16000 -ac 1 -acodec pcm_s16le \
    "${outputPath}" 2>/dev/null`);

  const optimizedSize = statSync(outputPath).size;
  const savings = ((1 - optimizedSize / originalSize) * 100).toFixed(1);

  console.log(`Preprocessed: ${inputPath}`);
  console.log(`  Original: ${(originalSize / 1024).toFixed(0)}KB`);
  console.log(`  Optimized: ${(optimizedSize / 1024).toFixed(0)}KB (${savings}% smaller)`);

  return { originalSize, optimizedSize, savings };
}
```

### Step 2: Model Selection Strategy

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

type Priority = 'accuracy' | 'speed' | 'cost';

function selectModel(priority: Priority, audioDuration: number): string {
  // Nova-3: Best accuracy, fast, $0.0043/min (STT)
  // Nova-2: Proven stable, fast, $0.0043/min
  // Base:   Fastest, lower accuracy, $0.0048/min
  // Whisper: Multilingual (100+ langs), slower, $0.0048/min

  switch (priority) {
    case 'accuracy':
      return 'nova-3';
    case 'speed':
      return audioDuration > 300 ? 'base' : 'nova-2';  // Base for long files
    case 'cost':
      return 'nova-2';  // Same price as Nova-3, slightly faster
    default:
      return 'nova-3';
  }
}

// Feature cost: disable what you don't need
function optimizedOptions(priority: Priority) {
  return {
    model: selectModel(priority, 0),
    smart_format: true,      // Free — always enable
    punctuate: true,         // Free — always enable
    // These add processing time:
    diarize: priority === 'accuracy',   // Adds latency
    utterances: priority === 'accuracy',
    paragraphs: priority === 'accuracy',
    summarize: false,        // Only when needed
    detect_topics: false,    // Only when needed
    sentiment: false,        // Only when needed
  };
}
```

### Step 3: Streaming for Large Files

```typescript
import { createClient, LiveTranscriptionEvents } from '@deepgram/sdk';
import { createReadStream } from 'fs';

async function streamLargeFile(filePath: string): Promise<string> {
  const deepgram = createClient(process.env.DEEPGRAM_API_KEY!);
  const transcripts: string[] = [];

  return new Promise((resolve, reject) => {
    const connection = deepgram.listen.live({
      model: 'nova-3',
      smart_format: true,
      encoding: 'linear16',
      sample_rate: 16000,
      channels: 1,
    });

    connection.on(LiveTranscriptionEvents.Open, () => {
      // Stream file in 32KB chunks
      const stream = createReadStream(filePath, { highWaterMark: 32 * 1024 });

      stream.on('data', (chunk: Buffer) => {
        connection.send(chunk);
      });

      stream.on('end', () => {
        // Signal end of audio
        connection.finish();
      });

      stream.on('error', reject);
    });

    connection.on(LiveTranscriptionEvents.Transcript, (data) => {
      if (data.is_final) {
        const text = data.channel.alternatives[0]?.transcript;

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.