Eve library

Lecture Generation Specification

Guide

Revision 1

On this page

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#

  1. Topic Validation: Verify topic is within knowledge domain, safe, and appropriate
  2. Outline Generation: Scholar agent creates structured lecture outline
  3. Librarian Retrieval: RAG pipeline retrieves relevant sources
  4. Coverage Check: Curator agent validates source diversity and accuracy
  5. Scholar Draft: Generate full transcript with inline citations
  6. Safety Scan: Moderation service checks for policy violations
  7. SSML Narrator: Convert to SSML with prosody markers
  8. TTS Synthesis: Chatterbox generates audio stream
  9. Quality Check: Validate audio (clipping, artifacts, loudness)
  10. 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#

  1. Topic Cache: Popular topics pre-generated
  2. Outline Cache: Reusable outlines for similar topics
  3. Audio Cache: CDN caching of HLS segments
  4. 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#

  1. Alpha: 3-minute lectures, limited topics
  2. Beta: 5-10 minute lectures, all traditions
  3. GA: Full duration range, all features