Deepgram Local Dev Loop

Overview

Set up an efficient local development workflow for Deepgram integration with fast feedback cycles.

Prerequisites

Completed deepgram-install-auth setup
Node.js 18+ with npm/pnpm or Python 3.10+
Sample audio files for testing
Environment variables configured

Instructions

Step 1: Create Project Structure

mkdir -p src tests fixtures
touch src/transcribe.ts tests/transcribe.test.ts

Step 2: Set Up Environment Files

# .env.development
DEEPGRAM_API_KEY=your-dev-api-key
DEEPGRAM_MODEL=nova-2

# .env.test
DEEPGRAM_API_KEY=your-test-api-key
DEEPGRAM_MODEL=nova-2

Step 3: Create Test Fixtures

# Download sample audio for testing
curl -o fixtures/sample.wav https://static.deepgram.com/examples/nasa-podcast.wav

Step 4: Set Up Watch Mode

{
  "scripts": {
    "dev": "tsx watch src/transcribe.ts",
    "test": "vitest",
    "test:watch": "vitest --watch"
  }
}

Output

Project structure with src, tests, fixtures directories
Environment files for development and testing
Watch mode scripts for rapid iteration
Sample audio fixtures for testing

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | Fixture Not Found | Missing audio file | Run fixture download script | | Env Not Loaded | dotenv not configured | Install and configure dotenv | | Watch Mode Fails | Missing tsx | Install tsx: npm i -D tsx | | API Rate Limited | Too many dev requests | Use cached responses in tests |

Examples

TypeScript Dev Setup

// src/transcribe.ts
import { createClient } from '@deepgram/sdk';
import { config } from 'dotenv';

config(); // Load .env

const deepgram = createClient(process.env.DEEPGRAM_API_KEY!);

export async function transcribeAudio(audioPath: string) {
  const audio = await Bun.file(audioPath).arrayBuffer();

  const { result, error } = await deepgram.listen.prerecorded.transcribeFile(
    Buffer.from(audio),
    { model: process.env.DEEPGRAM_MODEL || 'nova-2', smart_format: true }
  );

  if (error) throw error;
  return result.results.channels[0].alternatives[0].transcript;
}

// Dev mode: run with sample
if (import.meta.main) {
  transcribeAudio('./fixtures/sample.wav').then(console.log);
}

Test Setup with Vitest

// tests/transcribe.test.ts
import { describe, it, expect, beforeAll } from 'vitest';
import { transcribeAudio } from '../src/transcribe';

describe('Deepgram Transcription', () => {
  it('should transcribe audio file', async () => {
    const transcript = await transcribeAudio('./fixtures/sample.wav');
    expect(transcript).toBeDefined();
    expect(transcript.length).toBeGreaterThan(0);
  });

  it('should handle empty audio gracefully', async () => {
    await expect(transcribeAudio('./fixtures/empty.wav'))
      .rejects.toThrow();
  });
});

Mock Responses for Testing

// tests/mocks/deepgram.ts
export const mockTranscriptResponse = {
  results: {
    channels: [{
      alternatives: [{
        transcript: 'This is a test transcript.',
        confidence: 0.99,
        words: [
          { word: 'This', start: 0.0, end: 0.2, confidence: 0.99 },
          { word: 'is', start: 0.2, end: 0.3, confidence: 0.99 },
        ]
      }]
    }]
  }
};

Resources

Next Steps

Proceed to deepgram-sdk-patterns for production-ready code patterns.