Speak Core Workflow A: AI Conversation Practice
Overview
Primary workflow for Speak: AI-powered conversation practice with real-time pronunciation feedback and adaptive tutoring. Speak uses GPT-4o for conversation generation and OpenAI's Realtime API for speech processing, delivering sub-second response times.
Prerequisites
- Completed
speak-install-auth setup
- Valid API credentials configured
- Audio handling capabilities (microphone or pre-recorded files)
Instructions
Step 1: Start a Conversation Session
import { SpeakClient } from '@speak/language-sdk';
const client = new SpeakClient({
apiKey: process.env.SPEAK_API_KEY!,
appId: process.env.SPEAK_APP_ID!,
language: 'es',
});
// Start a restaurant ordering scenario in Spanish
const session = await client.startConversation({
scenario: 'ordering-food',
language: 'es',
level: 'intermediate',
nativeLanguage: 'en',
maxTurns: 10,
feedbackDetail: 'phoneme', // 'word' or 'phoneme'
});
console.log('Session started:', session.id);
console.log('AI Tutor:', session.firstPrompt.text);
// "Bienvenido al restaurante. Soy tu camarero. Que le gustaria ordenar?"
Step 2: Send Student Responses
// Submit audio for pronunciation scoring
const turn1 = await client.sendTurn(session.id, {
audioPath: './recordings/student-response-1.wav',
});
console.log('Tutor:', turn1.tutorText);
console.log('Pronunciation:', turn1.pronunciationScore); // 0-100
console.log('Grammar:', turn1.corrections);
// [{original: "yo quiero", suggestion: "quisiera", note: "More polite form for ordering"}]
console.log('Vocabulary:', turn1.vocabularyNotes);
// ["camarero = waiter", "ordenar = to order"]
// Or submit text (skips pronunciation scoring)
const turn2 = await client.sendTurn(session.id, {
text: 'Quisiera una ensalada y un vaso de agua, por favor.',
});
