speak-local-dev-loop

Overview

Set up a fast local development workflow for Speak language learning integrations. Includes mock tutor responses for offline development, audio test fixtures, and a debug mode for scoring analysis.

Prerequisites

• Completed speak-install-auth setup
• Node.js 18+ with npm/pnpm
• ffmpeg installed (for audio conversion)

Instructions

Step 1: Project Structure

speak-app/
  src/
    speak/client.ts       # Speak API client
    speak/tutor.ts        # AI tutor conversation manager
    speak/pronunciation.ts # Pronunciation assessment
    speak/audio.ts        # Audio recording and preprocessing
  tests/
    mocks/                # Mock responses for offline dev
    fixtures/             # Sample audio files for testing
    unit/                 # Unit tests with mocked API
    integration/          # Integration tests (needs API key)
  .env.development        # Dev credentials
  .env.test              # Test credentials (mock mode)

Step 2: Mock Tutor for Offline Development

// tests/mocks/mock-speak-client.ts
export class MockSpeakClient {
  async startConversation(config: any) {
    return {
      id: 'mock-session-123',
      firstPrompt: {
        text: 'Hola! Bienvenido. Como te llamas?',
        audioUrl: null,
      },
    };
  }

  async sendTurn(sessionId: string, input: any) {
    return {
      tutorText: 'Muy bien! Tu pronunciacion es buena.',
      pronunciationScore: 85,
      corrections: [],
      vocabularyNotes: ['llamo = I call myself'],
    };
  }

  async assessPronunciation(config: any) {
    return {
      score: 82,
      words: [
        { text: 'Hola', score: 95, phonemes: [] },
        { text: 'como', score: 78, phonemes: [
          { symbol: 'o', score: 65, suggestion: 'Round lips more' }
        ]},
      ],
    };
  }
}

Step 3: Audio Test Fixtures

# Generate test audio files using text-to-speech
# macOS:
say -v "Paulina" "Hola, como estas" -o tests/fixtures/hola-es.wav
# Linux:
espeak -v es "Hola, como estas" -w tests/fixtures/hola-es.wav

# Convert to required format
ffmpeg -i tests/fixtures/hola-es.wav -ar 16000 -ac 1 tests/fixtures/hola-es-16k.wav

Step 4: Development Scripts

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "dev:mock": "SPEAK_MOCK_MODE=true tsx watch src/index.ts",
    "test": "vitest run",
    "test:watch": "vitest",
    "lesson:test": "tsx src/test-lesson.ts"
  }
}

Step 5: Debug Mode

// Enable detailed scoring output
const DEBUG = process.env.SPEAK_DEBUG === 'true';

function logAssessment(result: PronunciationResult) {
  if (!DEBUG) return;
  console.log('=== Pronunciation Debug ===');
  for (const word of result.words) {
    const flag = word.score < 70 ? 'WEAK' : 'OK';
    console.log(`  [${flag}] "${word.text}": ${word.score}/100`);
    for (const p of word.phonemes || []) {
      if (p.score < 70) {
        console.log(`    phoneme "${p.symbol}": ${p.score} - ${p.suggestion}`);
      }
    }
  }
}

Output

• Project structure with client, tests, and mocks
• Mock tutor client for offline development
• Audio test fixtures generated with TTS
• Debug mode for pronunciation analysis
• Development scripts for fast iteration

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | ffmpeg not found | Not installed | Install via brew install ffmpeg or apt install ffmpeg | | Mock mode not activating | Env var not set | Check SPEAK_MOCK_MODE=true | | Audio file too large | Long recording | Trim to 30 seconds max for testing | | Test timeout | Slow API response | Use mock mode for unit tests |

Resources

• Vitest
• ffmpeg
• Web Speech API

Next Steps

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

Examples

Mock-first development: Run npm run dev:mock to iterate on UI and conversation flow without API calls. Switch to real API for integration testing.

Audio quality testing: Record samples at different quality levels and compare pronunciation scores to calibrate your recording pipeline.