# Lecture Generation Specification

**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

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                        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

## Related Documents

- [TTS Service Architecture](../architecture.md#tts-service)
- [RAG Pipeline](../algorithms.md#rag-pipeline)
- [Content Safety](../operations.md#content-safety)
