Feature guide

Audio and speech practice

Approved narration, speech synthesis, browser recording, audio limits, and speaking scenarios.

← Technical overview

What this domain owns

Safe generation and handling of learning audio. It does not accept arbitrary text-to-speech requests.

Feature flow diagram

Audio button or speaking activity
        │
        v
/api/audio/speech ──> origin + rate-limit checks
        │
        v
Published narration validation
        │
        v
Cache ──hit──> audio response
  │ miss
  v
Speech synthesizer ──> cached audio ──> playback UI

This diagram shows the normal direction of control and data. Follow it before changing a boundary or adding a dependency.

Class and relationship diagram

┌──────────────┐ request ┌────────────────────┐ validates ┌──────────────────┐
│ Audio button │────────▶│ /api/audio/speech │─────────▶│ Published content│
└──────────────┘         ├────────────────────┤          └──────────────────┘
                         │ + origin check     │
                         │ + rate limit       │
                         └──────────┬─────────┘
                                    ▼
                         ┌────────────────────┐
                         │ Speech cache/service│
                         └──────────┬─────────┘
                                    ▼
                             ┌──────────────┐
                             │ AudioPlayer  │
                             └──────────────┘

Boxes show the important data types or services. Their fields and main methods are listed inside; arrows show the primary dependency or data relationship.

Sequence diagram

Learner
Audio button
Speech API
Security
Published narration
Cache/service
request narration
request approved text
check origin + rate limit
request allowed
confirm text is allowed
narration approved
retrieve or synthesise audio
playable audio
return playable audio
play narration

Read this from top to bottom: each arrow is the next interaction in the normal successful path.

Start here in the code

Choose any filename to open it directly in VS Code.

How it works

  1. Learner requests lesson audio.
  2. Route checks trusted origin and generation limit.
  3. Narration input is validated against published content.
  4. Speech service returns cached or generated audio.
  5. UI plays audio or stores learner recording metadata.

Read this code

app/api/audio/speech/route.tsOpen in VS Code — Only synthesize approved learning narration

const text = request.nextUrl.searchParams.get('text') ?? '';
await assertTrustedOrigin(request);
await rateLimit(request, 'speech');

if (!isPublishedNarration(text)) {
  return Response.json({ error: 'Unknown narration.' }, { status: 400 });
}

What each part is doing

  1. The request may name only narration already published by the course.
  2. Origin and rate-limit checks protect a costly external speech service.
  3. Do not turn this endpoint into general text-to-speech without a separate product and safety design.

This is a deliberately short excerpt of the real pattern, with unrelated details omitted. Read the named file for the complete implementation.

Related API and server boundaries

  • POST /api/audio/speech
  • Assignment recording routes for classroom work.

Tests to read and run

Implementation notes

This is the home for detailed explanations, decision records, request examples, and diagrams for this feature. Add new feature-specific documentation here instead of expanding the platform overview.