AssemblyAI Local Dev Loop

Overview

Set up a fast, reproducible local development workflow for AssemblyAI transcription and LeMUR projects with mocking, caching, and hot reload.

Prerequisites

Completed assemblyai-install-auth setup
Node.js 18+ with npm/pnpm
TypeScript project with tsx or ts-node

Instructions

Step 1: Project Structure

my-assemblyai-project/
├── src/
│   ├── assemblyai/
│   │   ├── client.ts       # Singleton client
│   │   ├── transcribe.ts   # Transcription helpers
│   │   └── lemur.ts        # LeMUR helpers
│   └── index.ts
├── tests/
│   ├── transcribe.test.ts
│   └── fixtures/
│       └── sample-transcript.json  # Cached API response
├── .env.local              # Local secrets (git-ignored)
├── .env.example            # Template for team
└── package.json

Step 2: Dev Scripts

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "test": "vitest",
    "test:watch": "vitest --watch",
    "transcribe": "tsx src/assemblyai/transcribe.ts"
  },
  "devDependencies": {
    "tsx": "^4.7.0",
    "vitest": "^1.6.0",
    "dotenv": "^16.4.0"
  },
  "dependencies": {
    "assemblyai": "^4.8.0"
  }
}

Step 3: Singleton Client with Env Loading

// src/assemblyai/client.ts
import 'dotenv/config';
import { AssemblyAI } from 'assemblyai';

let instance: AssemblyAI | null = null;

export function getClient(): AssemblyAI {
  if (!instance) {
    if (!process.env.ASSEMBLYAI_API_KEY) {
      throw new Error('ASSEMBLYAI_API_KEY not set. Copy .env.example to .env.local');
    }
    instance = new AssemblyAI({
      apiKey: process.env.ASSEMBLYAI_API_KEY,
    });
  }
  return instance;
}

Step 4: Cache Transcription Results for Fast Iteration

// src/assemblyai/transcribe.ts
import fs from 'fs';
import path from 'path';
import { getClient } from './client';
import type { Transcript } from 'assemblyai';

const CACHE_DIR = path.join(process.cwd(), '.assemblyai-cache');

export async function transcribeWithCache(
  audioUrl: string,
  options: Record<string, any> = {}
): Promise<Transcript> {
  const cacheKey = Buffer.from(audioUrl + JSON.stringify(options))
    .toString('base64url')
    .slice(0, 32);
  const cachePath = path.join(CACHE_DIR, `${cacheKey}.json`);

  // Return cached result in dev
  if (process.env.NODE_ENV !== 'production' && fs.existsSync(cachePath)) {
    console.log('[dev] Using cached transcript:', cacheKey);
    return JSON.parse(fs.readFileSync(cachePath, 'utf-8'));
  }

  const client = getClient();
  const transcript = await client.transcripts.transcribe({
    audio: audioUrl,
    ...options,
  });

  // Cache for next run
  fs.mkdirSync(CACHE_DIR, { recursive: true });
  fs.writeFileSync(cachePath, JSON.stringify(transcript, null, 2));
  console.log('[dev] Cached transcript:', cacheKey);

  return transcript;
}

Step 5: Test with Mocked Responses

// tests/transcribe.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { AssemblyAI } from 'assemblyai';

// Mock the assemblyai module
vi.mock('assemblyai', () => ({
  AssemblyAI: vi.fn().mockImplementation(() => ({
    transcripts: {
      transcribe: vi.fn().mockResolvedValue({
        id: 'test-transcript-id',
        status: 'completed',
        text: 'This is a test transcript.',
        audio_duration: 30,
        words: [
          { text: 'This', start: 0, end: 200, confidence: 0.99 },
          { text: 'is', start: 210, end: 350, confidence: 0.98 },
        ],
      }),
      get: vi.fn(),
      list: vi.fn(),
    },
    lemur: {
      task: vi.fn().mockResolvedValue({
        request_id: 'test-lemur-id',
        response: 'Test summary of the audio.',
      }),
    },
  })),
}));

describe('Transcription', () => {
  it('should transcribe audio and return text', async () => {
    const client = new AssemblyAI({ apiKey: 'test-key' });
    const result = await client.transcripts.transcribe({
      audio: 'https://example.com/audio.wav',
    });

    expect(result.status).toBe('completed');
    expect(result.text).toContain('test transcript');
    expect(result.words).toHaveLength(2);
  });

  it('should run LeMUR task on transcript', async () => {
    const client = new AssemblyAI({ apiKey: 'test-key' });
    const { response } = await client.lemur.task({
      transcript_ids: ['test-transcript-id'],
      prompt: 'Summarize this.',
    });

    expect(response).toContain('summary');
  });
});

Output

Hot-reloading dev server with tsx watch
Cached transcription results to avoid repeated API calls during dev
Mocked test suite that runs without API credentials
Environment variable management with .env.local

Examples

Use mocked responses by default and cache only synthetic, redacted test results in a directory excluded from version control. If a real integration call is necessary, use an approved short sample and dedicated development key, set an expiration for the cache, and remove the resulting transcript after the assertion passes.

Error Handling

Error	Cause	Solution
`ASSEMBLYAI_API_KEY not set`	Missing env file	Copy `.env.example` to `.env.local`
`Module not found: assemblyai`	Missing dependency	Run `npm install assemblyai`
Stale cache results	Outdated cache	Delete `.assemblyai-cache/` directory
Test timeout	Slow mock setup	Ensure mocks resolve synchronously

Resources

Next Steps

See assemblyai-sdk-patterns for production-ready code patterns.