audiobook/.kiro/specs/text-to-audiobook/SCRIPT_REVIEW_FEATURE.md

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