Status: ✅ Complete Version: 1.0 Last Updated: December 2025 Author: Engineering Team
1. Overview#
1.1 Summary#
The Lecture Generation system creates on-demand audio lectures on topics within the knowledge base. Users specify a topic, duration, and preferences; the system generates a structured lecture with citations, produces a transcript, and synthesizes audio.
1.2 Business Context#
- Goal: Provide encyclopedia-style learning through polished audio content
- Users: Students seeking structured explanations on specific topics
- Value: High-quality educational content without pre-recording
1.3 Success Metrics#
| Metric | Target |
|---|---|
| Generation start | < 2 seconds |
| TTS first-byte | < 600ms |
| Citation coverage | > 85% of claims |
| User satisfaction | > 4.0/5.0 |
| Completion rate | > 70% |
2. Requirements#
2.1 Functional Requirements#
| ID | Requirement | Priority |
|---|---|---|
| FR-1 | Users can specify topic | P0 |
| FR-2 | Users can select duration | P0 |
| FR-3 | Users can select tradition filter | P1 |
| FR-4 | Users can select voice | P1 |
| FR-5 | System generates structured outline | P0 |
| FR-6 | System retrieves relevant sources | P0 |
| FR-7 | System produces cited transcript | P0 |
| FR-8 | System synthesizes audio | P0 |
| FR-9 | Users can download for offline | P1 |
| FR-10 | Users can adjust playback speed | P1 |
2.2 Non-Functional Requirements#
| ID | Requirement | Target |
|---|---|---|
| NFR-1 | Generation latency | Start < 2s |
| NFR-2 | Audio quality | -16 LUFS normalized |
| NFR-3 | Concurrent generations | 100+ |
| NFR-4 | Cache hit rate | > 40% popular topics |
| NFR-5 | Error rate | < 1% |
3. Generation Pipeline#
text
┌─────────────────────────────────────────────────────────────────────────────┐
│ LECTURE GENERATION PIPELINE │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Topic │────>│ Validate │────>│ Outline │ │
│ │ Input │ │ & Map │ │ Generation │ │
│ └─────────────┘ └─────────────┘ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Coverage │<────│ Scholar │<────│ Librarian │ │
│ │ Check │ │ Draft │ │ Retrieval │ │
│ └──────┬──────┘ └─────────────┘ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Safety │────>│ SSML │────>│ TTS │ │
│ │ Scan │ │ Narrator │ │ Synthesis │ │
│ └─────────────┘ └─────────────┘ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Publish │<────│ Package │<────│ Quality │ │
│ │ & Cache │ │ Media │ │ Check │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
3.1 Pipeline Stages#
- Topic Validation: Verify topic is within knowledge domain, safe, and appropriate
- Outline Generation: Scholar agent creates structured lecture outline
- Librarian Retrieval: RAG pipeline retrieves relevant sources
- Coverage Check: Curator agent validates source diversity and accuracy
- Scholar Draft: Generate full transcript with inline citations
- Safety Scan: Moderation service checks for policy violations
- SSML Narrator: Convert to SSML with prosody markers
- TTS Synthesis: Chatterbox generates audio stream
- Quality Check: Validate audio (clipping, artifacts, loudness)
- Package & Publish: Create HLS segments, transcript, publish
4. API Design#
4.1 Generate Lecture#
http
POST /v1/lectures
Authorization: Bearer <token>
Content-Type: application/json
{
"topic": "The concept of non-self in Buddhist philosophy",
"duration_min": 10,
"tradition": ["buddhism", "zen"],
"lang": "en-US",
"voice": "calm_female_1",
"outline_level": "detailed",
"include_citations": true
}
4.2 Response#
json
{
"lecture_id": "lec_abc123",
"status": "generating",
"estimated_duration_ms": 600000,
"stream_url": "https://cdn.example.com/lectures/lec_abc123/stream.m3u8",
"transcript_url": "https://cdn.example.com/lectures/lec_abc123/transcript.json",
"citations": [
{
"text": "The Buddha taught anatta...",
"source": "Anattalakkhana Sutta",
"confidence": 0.95
}
],
"created_at": "2025-01-15T10:30:00Z"
}
4.3 Get Lecture Status#
http
GET /v1/lectures/{lecture_id}
json
{
"lecture_id": "lec_abc123",
"status": "ready",
"progress_pct": 100,
"stream_url": "...",
"transcript_url": "...",
"duration_ms": 598000,
"word_count": 1450,
"citations_count": 8
}
5. Data Model#
5.1 Lectures Table#
sql
CREATE TABLE lectures (
id UUID PRIMARY KEY,
topic TEXT NOT NULL,
duration_target_min INTEGER NOT NULL,
duration_actual_ms INTEGER,
lang VARCHAR(10) NOT NULL,
voice_id VARCHAR(100),
tradition TEXT[],
status VARCHAR(20) NOT NULL DEFAULT 'pending',
outline JSONB,
transcript_ref TEXT,
audio_ref TEXT,
citations JSONB,
generation_metrics JSONB,
created_at TIMESTAMPTZ DEFAULT NOW(),
completed_at TIMESTAMPTZ,
CONSTRAINT valid_status CHECK (status IN (
'pending', 'generating', 'ready', 'failed', 'expired'
))
);
5.2 Lecture Outline Schema#
json
{
"title": "Non-Self in Buddhist Philosophy",
"duration_target_min": 10,
"sections": [
{
"title": "Introduction",
"duration_sec": 60,
"key_points": ["Definition of anatta", "Historical context"]
},
{
"title": "The Three Marks of Existence",
"duration_sec": 180,
"key_points": ["Impermanence", "Suffering", "Non-self"]
},
{
"title": "Practical Implications",
"duration_sec": 240,
"key_points": ["Meditation practice", "Daily life application"]
},
{
"title": "Conclusion",
"duration_sec": 60,
"key_points": ["Summary", "Further exploration"]
}
]
}
6. Audio Processing#
6.1 SSML Generation#
xml
<speak>
<prosody rate="95%" pitch="-2st">
<p>
<s>Today, we explore the profound Buddhist concept of
<emphasis level="moderate">anattā</emphasis>,
or non-self.</s>
</p>
<break time="500ms"/>
<p>
<s>The Buddha taught that clinging to a fixed sense of self
leads to suffering.</s>
</p>
</prosody>
</speak>
6.2 Audio Specifications#
| Parameter | Value |
|---|---|
| Format | Opus (streaming), AAC (download) |
| Sample rate | 48 kHz |
| Bit rate | 96 kbps |
| Loudness | -16 LUFS |
| Peak | -1 dBFS |
| Silence threshold | -40 dB |
7. Caching Strategy#
7.1 Cache Layers#
- Topic Cache: Popular topics pre-generated
- Outline Cache: Reusable outlines for similar topics
- Audio Cache: CDN caching of HLS segments
- Transcript Cache: Searchable transcript index
7.2 Cache Invalidation#
- Topic cache: 7 days TTL
- Audio cache: 30 days TTL
- Knowledge update triggers re-generation queue
8. Testing Strategy#
8.1 Test Scenarios#
| Scenario | Test Type |
|---|---|
| Valid topic generates | Integration |
| Invalid topic rejected | Unit |
| Duration accuracy | Integration |
| Citation coverage | Integration |
| Audio quality | Automated QA |
| Concurrent generation | Load |
| Cache hit/miss | Performance |
8.2 Quality Gates#
- Lecture completes within 2x target duration
- Citation coverage > 85%
- Audio passes loudness check
- No moderation flags
- Transcript aligns with audio
9. Rollout Plan#
9.1 Feature Flags#
| Flag | Description |
|---|---|
lecture_gen_enabled |
Master enable |
lecture_gen_streaming |
Stream during generation |
lecture_gen_voices |
Voice selection |
lecture_gen_download |
Offline download |
9.2 Phased Rollout#
- Alpha: 3-minute lectures, limited topics
- Beta: 5-10 minute lectures, all traditions
- GA: Full duration range, all features