Speak Migration Deep Dive

Overview

Migrate between language learning platforms, import student progress, and transition from legacy speech APIs.

Prerequisites

• Completed speak-install-auth setup
• Valid API credentials configured
• Understanding of Speak API patterns

Instructions

Step 1: Configuration

Configure migration deep dive for your Speak integration. Speak uses OpenAI's GPT-4o for AI tutoring and Whisper for speech recognition.

// speak_migration_deep_dive_config.ts
const config = {
  apiKey: process.env.SPEAK_API_KEY!,
  appId: process.env.SPEAK_APP_ID!,
  environment: process.env.NODE_ENV || 'development',
};

Step 2: Implementation

// Core implementation for speak migration deep dive
import { SpeakClient } from '@speak/language-sdk';

const client = new SpeakClient(config);

// Production-ready implementation
async function setup() {
  const health = await client.health.check();
  console.log("Status:", health.status);
  return health;
}

Step 3: Verification

curl -sf -H "Authorization: Bearer $SPEAK_API_KEY" https://api.speak.com/v1/health | jq .

Output

• Speak Migration Deep Dive configured and verified
• Production-ready Speak integration
• Error handling and monitoring in place

Error Handling

Resources

• Speak Website
• OpenAI Realtime API
• Speak GPT-4 Blog

Next Steps

For production checklist, see speak-prod-checklist.

Examples

Basic: Apply migration deep dive with default settings for a standard Speak integration.

Production: Configure with monitoring, alerting, and team-specific language learning requirements.

Speak Multi-Environment Setup

Overview

Configure Speak across dev, staging, and production with separate API keys and mock modes.

Prerequisites

• Completed speak-install-auth setup
• Valid API credentials configured
• Understanding of Speak API patterns

Instructions

Step 1: Configuration

Configure multi env setup for your Speak integration. Speak uses OpenAI's GPT-4o for AI tutoring and Whisper for speech recognition.

// speak_multi_env_setup_config.ts
const config = {
  apiKey: process.env.SPEAK_API_KEY!,
  appId: process.env.SPEAK_APP_ID!,
  environment: process.env.NODE_ENV || 'development',
};

Step 2: Implementation

// Core implementation for speak multi-environment setup
import { SpeakClient } from '@speak/language-sdk';

const client = new SpeakClient(config);

// Production-ready implementation
async function setup() {
  const health = await client.health.check();
  console.log("Status:", health.status);
  return health;
}

Step 3: Verification

curl -sf -H "Authorization: Bearer $SPEAK_API_KEY" https://api.speak.com/v1/health | jq .

Output

• Speak Multi-Environment Setup configured and verified
• Production-ready Speak integration
• Error handling and monitoring in place

Error Handling

Resources

• Speak Website
• OpenAI Realtime API
• Speak GPT-4 Blog

Next Steps

For production checklist, see speak-prod-checklist.

Examples

Basic: Apply multi env setup with default settings for a standard Speak integration.

Production: Configure with monitoring, alerting, and team-specific language learning requirements.

Speak Observability

Overview

Monitor Speak API health, assessment latency, session metrics, and pronunciation score distributions.

Prerequisites

• Completed speak-install-auth setup
• Valid API credentials configured
• Understanding of Speak API patterns

Instructions

Step 1: Configuration

Configure observability for your Speak integration. Speak uses OpenAI's GPT-4o for AI tutoring and Whisper for speech recognition.

// speak_observability_config.ts
const config = {
  apiKey: process.env.SPEAK_API_KEY!,
  appId: process.env.SPEAK_APP_ID!,
  environment: process.env.NODE_ENV || 'development',
};

Step 2: Implementation

// Core implementation for speak observability
import { SpeakClient } from '@speak/language-sdk';

const client = new SpeakClient(config);

// Production-ready implementation
async function setup() {
  const health = await client.health.check();
  console.log("Status:", health.status);
  return health;
}

Step 3: Verification

curl -sf -H "Authorization: Bearer $SPEAK_API_KEY" https://api.speak.com/v1/health | jq .

Output

• Speak Observability configured and verified
• Production-ready Speak integration
• Error handling and monitoring in place

Error Handling

Resources

• Speak Website
• OpenAI Realtime API
• Speak GPT-4 Blog

Next Steps

For production checklist, see speak-prod-checklist.

Examples

Basic: Apply observability with default settings for a standard Speak integration.

Production: Configure with monitoring, alerting, and team-specific language learning requirements.

Speak Performance Tuning

Overview

Optimize Speak API latency with audio preprocessing, response caching, and connection pooling.

Prerequisites

• Completed speak-install-auth setup
• Valid API credentials configured
• Understanding of Speak API patterns

Instructions

Step 1: Configuration

Configure performance tuning for your Speak integration. Speak uses OpenAI's GPT-4o for AI tutoring and Whisper for speech recognition.

// speak_performance_tuning_config.ts
const config = {
  apiKey: process.env.SPEAK_API_KEY!,
  appId: process.env.SPEAK_APP_ID!,
  environment: process.env.NODE_ENV || 'development',
};

Step 2: Implementation

// Core implementation for speak performance tuning
import { SpeakClient } from '@speak/language-sdk';

const client = new SpeakClient(config);

// Production-ready implementation
async function setup() {
  const health = await client.health.check();
  console.log("Status:", health.status);
  return health;
}

Step 3: Verification

curl -sf -H "Authorization: Bearer $SPEAK_API_KEY" https://api.speak.com/v1/health | jq .

Output

• Speak Performance Tuning configured and verified
• Production-ready Speak integration
• Error handling and monitoring in place

Error Handling

Resources

• Speak Website
• OpenAI Realtime API
• Speak GPT-4 Blog

Next Steps

For production checklist, see speak-prod-checklist.

Examples

Basic: Apply performance tuning with default settings for a standard Speak integration.

Production: Configure with monitoring, alerting, and team-specific language learning requirements.

Speak Production Checklist

Overview

Production readiness checklist for Speak language learning integrations: auth, audio pipeline, monitoring, and compliance.

Prerequisites

• Completed speak-install-auth setup
• Valid API credentials configured
• ffmpeg installed for audio processing

Instructions

Authentication

• [ ] API keys stored in secrets manager
• [ ] Key rotation schedule established (90 days)
• [ ] Separate keys for dev/staging/production
• [ ] Error handling for expired keys

Audio Pipeline

• [ ] Audio preprocessor converts to WAV 16kHz mono
• [ ] File size validation (< 25MB)
• [ ] Duration validation (0.5s - 60s)
• [ ] Background noise detection/warning
• [ ] Fallback for unsupported audio formats

Rate Limiting & Performance

• [ ] Rate-limited client wrapper implemented
• [ ] Retry logic with exponential backoff on 429
• [ ] Request queue for batch assessments
• [ ] Response caching where appropriate

Monitoring & Alerting

• [ ] API response time tracking
• [ ] Error rate monitoring (target < 1%)
• [ ] Rate limit hit tracking
• [ ] Assessment score distribution monitoring
• [ ] Session completion rate tracking

Compliance

• [ ] Student data privacy policy documented
• [ ] Audio data retention policy implemented
• [ ] COPPA compliance verified (if applicable)
• [ ] FERPA compliance verified (if educational)
• [ ] GDPR data processing agreement (if EU users)

Verification Script

#!/bin/bash
set -euo pipefail
echo "Speak Production Readiness"
curl -sf -H "Authorization: Bearer $SPEAK_API_KEY" \
  https://api.speak.com/v1/health | jq '.status'
echo "  Auth: PASS"
ffmpeg -version > /dev/null 2>&1 && echo "  ffmpeg: PASS" || echo "  ffmpeg: FAIL"
echo "Checks complete."

Output

• Checklist implementation complete
• Speak API integration verified
• Production-ready patterns applied

Error Handling

Resources

• Speak Website

Speak Rate Limits

Overview

Handle Speak API rate limits with exponential backoff, request queuing, and optimization strategies.

Prerequisites

• Completed speak-install-auth setup
• Valid API credentials configured
• Understanding of Speak API patterns

Instructions

Rate Limit Overview

Rate-Limited Client

class RateLimitedSpeakClient {
  private lastRequest = 0;
  private minDelay: number;

  constructor(private client: SpeakClient, requestsPerMinute: number = 60) {
    this.minDelay = 60000 / requestsPerMinute;
  }

  private async throttle() {
    const elapsed = Date.now() - this.lastRequest;
    if (elapsed < this.minDelay) {
      await new Promise(r => setTimeout(r, this.minDelay - elapsed));
    }
    this.lastRequest = Date.now();
  }

  async assessPronunciation(config: PronunciationConfig) {
    await this.throttle();
    return this.retryOn429(() => this.client.assessPronunciation(config));
  }

  private async retryOn429<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
    for (let i = 0; i < maxRetries; i++) {
      try {
        return await fn();
      } catch (err: any) {
        if (err.response?.status === 429 && i < maxRetries - 1) {
          const wait = parseInt(err.response.headers['retry-after'] || String(2 ** i));
          console.log(`Rate limited. Waiting ${wait}s...`);
          await new Promise(r => setTimeout(r, wait * 1000));
          continue;
        }
        throw err;
      }
    }
    throw new Error('Max retries exceeded');
  }
}

Batch Assessment Queue

async function batchAssess(client: RateLimitedSpeakClient, recordings: Recording[]) {
  const results = [];
  for (const rec of recordings) {
    const result = await client.assessPronunciation({
      audioPath: rec.path, targetText: rec.text, language: rec.lang,
    });
    results.push({ ...rec, score: result.score });
    console.log(`Assessed "${rec.text}": ${result.score}/100`);
  }
  return results;
}

Output

• Limits implementation complete
• Speak API integration verified
• Production-ready patterns applied

Error Handling

// speak_reference_architecture_config.ts
const config = {
  apiKey: process.env.SPEAK_API_KEY!,
  appId: process.env.SPEAK_APP_ID!,
  environment: process.env.NODE_ENV || 'development',
};

// Core implementation for speak reference architecture
import { SpeakClient } from '@speak/language-sdk';

const client = new SpeakClient(config);

// Production-ready implementation
async function setup() {
  const health = await client.health.check();
  console.log("Status:", health.status);
  return health;
}

curl -sf -H "Authorization: Bearer $SPEAK_API_KEY" https://api.speak.com/v1/health | jq .

Resources

• Speak Website
• OpenAI Realtime API
• Speak GPT-4 Blog

Next Steps

For production checklist, see speak-prod-checklist.

Examples

Basic: Apply reference architecture with default settings for a standard Speak integration.

Production: Configure with monitoring, alerting, and team-specific language learning requirements.

Speak SDK Patterns

Overview

Production patterns for Speak language learning API: conversation sessions, pronunciation assessment, audio preprocessing, and batch operations.

Prerequisites

• Completed speak-install-auth setup
• Valid API credentials configured
• ffmpeg installed for audio processing

Instructions

Pattern 1: Conversation Session Manager

class ConversationManager {
  private client: SpeakClient;
  private sessions: Map<string, SessionState> = new Map();

  async startLesson(language: string, scenario: string, level: string) {
    const session = await this.client.startConversation({
      scenario, language, level, nativeLanguage: 'en',
    });
    this.sessions.set(session.id, {
      turns: [], startTime: Date.now(), language,
    });
    return session;
  }

  async submitResponse(sessionId: string, audioPath: string) {
    const turn = await this.client.sendTurn(sessionId, { audioPath });
    this.sessions.get(sessionId)?.turns.push(turn);
    return turn;
  }

  async endAndReport(sessionId: string) {
    const summary = await this.client.endSession(sessionId);
    const state = this.sessions.get(sessionId)!;
    return {
      ...summary,
      duration: (Date.now() - state.startTime) / 1000,
      totalTurns: state.turns.length,
      avgPronunciation: state.turns.reduce((s, t) =>
        s + (t.pronunciationScore || 0), 0) / state.turns.length,
    };
  }
}

Pattern 2: Audio Preprocessor

import { execSync } from 'child_process';

function preprocessAudio(inputPath: string): string {
  const outputPath = inputPath.replace(/\.[^.]+$/, '.processed.wav');
  // Convert to WAV 16kHz mono PCM — required by Speak API
  execSync(
    `ffmpeg -y -i "${inputPath}" -ar 16000 -ac 1 -c:a pcm_s16le "${outputPath}"`,
    { stdio: 'pipe' }
  );
  return outputPath;
}

Pattern 3: Retry with Backoff

async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (err: any) {
      if (err.response?.status === 429 && i < maxRetries - 1) {
        const wait = parseInt(err.response.headers['retry-after'] || '5');
        await new Promise(r => setTimeout(r, wait * 1000));
        continue;
      }
      throw err;
    }
  }
  throw new Error('Max retries exceeded');
}

Pattern 4: Progress Tracker

class LearningProgress {
  private history: SessionSummary[] = [];

  addSession(summary: SessionSummary) {
    this.history.push(summary);
  }

  getReport() {
    const recent = this.history.slice(-10);
    return {
      totalSessio