# Script Review Feature - Enhancement Specification

## Overview

This document describes the new **Script Review & Editing** feature that addresses the issue where AI-generated speaker assignments may not always be accurate. This feature gives users visibility and control over how the text is segmented and which character speaks each line.

## Problem Statement

When using AI to detect speakers in unmarked text, the system may:
- Incorrectly assign dialogue to the wrong character
- Miss some character dialogue
- Assign narrative text to a character instead of the narrator

Users currently have no way to see or correct these mistakes before generating the audiobook.

## Solution

Add a new **Script Review** phase between voice assignment and audio generation where users can:
1. See the complete script breakdown showing which character speaks each line
2. Edit speaker assignments for any segment
3. Skip the review if they trust the AI's assignments

## User Workflow

### Updated Flow
```
1. Text Input
   ↓
2. Role Detection (AI detects: Lily, Benny, Sammy, Narrator)
   ↓
3. Voice Assignment (User assigns voices to each role)
   ↓
4. **Script Review** (NEW - User reviews and edits speaker assignments)
   ↓
5. Audio Generation (Uses edited script)
   ↓
6. Playback & Download
```

### Script Review Interface

The review screen will show:

```
┌─────────────────────────────────────────────────────────────┐
│                    Review Script                             │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Segment 1:  [Narrator ▼]                                   │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ Once upon a time, in a tiny village surrounded by      │ │
│  │ lush green forests, there lived three best friends...  │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                              │
│  Segment 2:  [Lily ▼]                                       │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ "Have you guys heard about the new stream that just    │ │
│  │ appeared in the woods?"                                 │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                              │
│  Segment 3:  [Benny ▼]                                      │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ "Ooh, I love streams! Do we get to go see it now?"     │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                              │
│  ... (more segments)                                         │
│                                                              │
│  [Skip Review]              [Generate Audiobook]            │
└─────────────────────────────────────────────────────────────┘
```

## Technical Implementation

### New API Endpoint

**POST /api/tts/script**
- Request: `{ text: string, roles: string[] }`
- Response: `{ segments: [{ id: string, speaker: string, text: string }] }`
- Uses Ollama AI to segment text and assign speakers
- Returns editable script for frontend

### Updated Generation Endpoint

**POST /api/tts** (modified)
- Now accepts optional `segments` array
- If segments provided, uses them directly (respecting user edits)
- If no segments, falls back to original text-based segmentation
- Maintains backward compatibility

### Frontend Components

**New: ScriptReviewSection**
- Displays all segments with editable speaker dropdowns
- Allows users to change speaker for any segment
- Provides "Skip Review" option for quick generation
- Mobile-responsive design

**Updated: VoiceAssignmentSection**
- Button changes from "Generate Audiobook" to "Next: Review Script"
- Adds "Skip Review & Generate" option

**Updated: App Component**
- Adds 'review' phase to workflow
- Manages script segments state
- Handles segment editing

## Benefits

1. **Transparency**: Users can see exactly how the AI interpreted their text
2. **Control**: Users can correct any mistakes before generation
3. **Flexibility**: Users can skip review if they trust the AI
4. **Better Results**: Ensures the final audiobook matches user expectations

## Requirements Added

- **Requirement 15**: Complete specification for script review feature
  - 8 acceptance criteria covering all aspects
  - API endpoints, UI components, and user interactions

## Design Updates

- Added ScriptReviewSection component
- Added /api/tts/script endpoint
- Updated data models (ScriptSegment, ScriptRequest, ScriptResponse)
- Added 5 new correctness properties (Properties 32-35)
- Updated application workflow to include review phase

## Implementation Tasks

Added 8 new tasks (18-25) covering:
- Backend script generation endpoint
- Updated TTS generation to accept edited scripts
- Frontend API client updates
- ScriptReviewSection component
- App component workflow updates
- VoiceAssignmentSection updates
- Documentation
- Integration testing

## Testing Strategy

- Property tests for script completeness and structure
- Unit tests for all new components and endpoints
- Integration tests for complete workflow
- Manual testing with various text samples

## Future Enhancements

Potential improvements for later:
- Inline editing of segment text
- Merge/split segments
- Bulk speaker assignment
- Save/load script templates
- Export script as text file