251 lines
13 KiB
Markdown
251 lines
13 KiB
Markdown
# Product Requirements Document (PRD): Be My Anchor
|
|
|
|
**Status**: Approved
|
|
**Target Version**: 2.0 (Listening-First Audio Platform)
|
|
**Architecture**: TypeScript / Next.js Fullstack
|
|
**Primary Output**: `docs/prd.md`
|
|
|
|
---
|
|
|
|
## 1. Executive Summary & Vision
|
|
|
|
**Be My Anchor** transforms written materials—technical blogs, research papers, news articles, essays, and documentation—into an engaging, listening-first audio experience.
|
|
|
|
Rather than relying on brittle web scrapers or monotone text-to-speech readers, Be My Anchor adopts an **API-driven ingestion** model combined with:
|
|
|
|
1. **High-Fidelity Audio Generation**: Multi-provider neural TTS (Edge TTS, OpenAI, ElevenLabs) with smart text chunking and audio stitching.
|
|
2. **Hearing-Front Content Adaptation**: An LLM-powered scriptwriting engine that adapts dense text into conversational spoken formats (e.g., Feynman-style technical breakdown or 2-host conversational dialogue).
|
|
3. **Mobile-First Zen Listening Experience**: A distraction-free PWA listening environment with uninterrupted playback, synchronized auto-scrolling transcript, and tap-to-seek navigation.
|
|
|
|
---
|
|
|
|
## 2. Core Philosophy & Phased Strategy
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Phase 1: Robust Audio Generation Core │
|
|
│ - Multi-provider TTS (Edge TTS, OpenAI, ElevenLabs) │
|
|
│ - Long-form text chunking & audio stitching │
|
|
│ - Persistent audio player & episode library │
|
|
└──────────────────────────────┬──────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Phase 2: Hearing-Front Content Transformation │
|
|
│ - "Feynman" Deep-Dive Presenter Persona │
|
|
│ - Dual-Host Dialogue Persona (NotebookLM style) │
|
|
│ - Synchronized sentence & speaker timing manifests │
|
|
└──────────────────────────────┬──────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Phase 3: Mobile PWA & Zen Listening Experience │
|
|
│ - Fullscreen Zen player with synchronized transcript │
|
|
│ - Mobile PWA & MediaSession background lockscreen controls │
|
|
│ - Dedicated article studio and queue status tracking │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 3. User Personas & Modes of Operation
|
|
|
|
### Persona 1: The Engineer / Researcher ("The Feynman Mode")
|
|
|
|
- **Content**: Technical architecture posts, RFCs, research papers, algorithm deep-dives.
|
|
- **Narrator Style**: A world-class communicator (like Richard Feynman or a top tech lead) explaining concepts using intuitive analogies and breaking down dense material for the ear.
|
|
|
|
### Persona 2: The Informed Professional ("The Dual-Host Dialogue")
|
|
|
|
- **Content**: Industry news, opinion pieces, market shifts, newsletters.
|
|
- **Narrator Style**: Two AI co-hosts bantering, asking each other questions, and adding contextual background not directly present in the source article.
|
|
|
|
### Persona 3: The Audiobook / Direct Listener ("Verbatim Mode")
|
|
|
|
- **Content**: Novels, essays, speeches, narrative non-fiction.
|
|
- **Narrator Style**: Clear, expressive single-narrator audiobook delivery with sentence-by-sentence paragraph tracking.
|
|
|
|
---
|
|
|
|
## 4. System Architecture
|
|
|
|
```
|
|
┌────────────────────────────┐
|
|
│ API Ingestion Endpoint │
|
|
│ (Markdown / Text Input) │
|
|
└─────────────┬──────────────┘
|
|
│
|
|
▼
|
|
┌────────────────────────────┐
|
|
│ Hearing-Front Script Engine│
|
|
│ (LLM: OpenAI / Claude) │
|
|
│ - Rewrites text for ear │
|
|
│ - Speaker turn separation │
|
|
└─────────────┬──────────────┘
|
|
│
|
|
▼
|
|
┌────────────────────────────┐
|
|
│ TTS Generation Core │
|
|
│ ┌──────────┐ ┌───────────┐ │
|
|
│ │ Edge TTS │ │OpenAI TTS │ │
|
|
│ └──────────┘ └───────────┘ │
|
|
│ ┌────────────────────────┐ │
|
|
│ │ ElevenLabs (Multi-Voice│ │
|
|
│ └────────────────────────┘ │
|
|
│ - Chunker & Audio Stitcher │
|
|
│ - Timing Aligner (JSON) │
|
|
└─────────────┬──────────────┘
|
|
│
|
|
▼
|
|
┌───────────────────────────────────┴───────────────────────────────────┐
|
|
│ Data & Storage │
|
|
│ - Database: Prisma ORM (SQLite / PostgreSQL) │
|
|
│ - File Storage: Local static / S3-compatible (Audio MP3s) │
|
|
└───────────────────────────────────┬───────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌───────────────────────────────────────────────────────────────────────┐
|
|
│ Mobile-First Web App (Next.js / TS / PWA) │
|
|
│ ┌───────────────────────┐ ┌───────────────────────────────────────┐ │
|
|
│ │ Main Index View │ │ Zen Mode Player │ │
|
|
│ │ - Episode list │ │ - Fullscreen distraction-free player │ │
|
|
│ │ - Live status pills │ │ - Synchronized auto-scrolled script │ │
|
|
│ │ - Persistent bar │ │ - Tap-to-seek, large touch controls │ │
|
|
│ └───────────────────────┘ └───────────────────────────────────────┘ │
|
|
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
|
│ │ Dedicated Add Article View (/new) │ │
|
|
│ └─────────────────────────────────────────────────────────────────┘ │
|
|
└───────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Functional Requirements
|
|
|
|
### 5.1 Content Ingestion (API & UI Driven)
|
|
|
|
- Clean REST API & dedicated UI accepting:
|
|
- `title`: String
|
|
- `content`: Plain text or Markdown
|
|
- `mode`: `'VERBATIM'` | `'FEYNMAN'` | `'DUAL_HOST'`
|
|
- `voice_config`: Provider preference (`edge` | `openai` | `elevenlabs`), voice IDs, speed
|
|
|
|
### 5.2 Hearing-Front Content Transformation
|
|
|
|
- **Verbatim Cleaner**: Strips markdown artifacts, normalizes punctuation, phonetic hints.
|
|
- **Feynman Script Generator**: Rewrites technical content into an oral lecture/walkthrough.
|
|
- **Dual-Host Dialogue Generator**: Turns article content into an interactive conversation between Host A and Host B with speaker-tagged turns (`SpeakerA: ...`, `SpeakerB: ...`).
|
|
|
|
### 5.3 TTS Engine & Audio Processing
|
|
|
|
- **Provider Abstraction Interface (`ITextToSpeechProvider`)**:
|
|
- `EdgeTTSProvider`: Free, instant neural voices (`zh-CN-XiaoxiaoNeural`, `en-US-ChristopherNeural`, etc.).
|
|
- `OpenAITTSProvider`: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`.
|
|
- `ElevenLabsProvider`: High-fidelity multi-voice assignment for dual-host dialogue.
|
|
- **Long-Text Chunker & Audio Stitcher**:
|
|
- Breaks script into sentence/clause chunks respecting character limits.
|
|
- Stitches chunk audio files into a unified master `.mp3`.
|
|
- Generates synchronized sentence/turn timing manifests (`timingsJson`).
|
|
|
|
### 5.4 3-View Mobile-First Listening Experience
|
|
|
|
1. **Main Index View (`/`)**:
|
|
- Episode list with live statuses (`QUEUED`, `PROCESSING`, `READY`, `FAILED`, `CANCELED`).
|
|
- Card play/pause, duration, auto-polling while jobs are active.
|
|
- Persistent bottom mini-player bar that never interrupts playing audio.
|
|
2. **Zen Fullscreen Player**:
|
|
- Toggled via full-screen button on persistent bar.
|
|
- Synchronized transcript with active sentence highlighting and smooth auto-scroll.
|
|
- Tap-to-seek anywhere in transcript.
|
|
- Swipe-down gesture or minimize button to return to index without audio interruption.
|
|
3. **Dedicated Add Article View (`/new`)**:
|
|
- Standalone view for new posts with character/word count and duration estimation.
|
|
- Extensible for future M2 settings (prompts, dual voices).
|
|
|
|
---
|
|
|
|
## 6. Data Model (Prisma Schema Specification)
|
|
|
|
```prisma
|
|
datasource db {
|
|
provider = "sqlite" // or "postgresql"
|
|
url = env("DATABASE_URL")
|
|
}
|
|
|
|
generator client {
|
|
provider = "prisma-client-js"
|
|
}
|
|
|
|
model Episode {
|
|
id String @id @default(cuid())
|
|
title String
|
|
originalContent String
|
|
scriptContent String?
|
|
mode String @default("VERBATIM") // VERBATIM | FEYNMAN | DUAL_HOST
|
|
status String @default("PENDING") // QUEUED | PROCESSING | READY | FAILED | CANCELED
|
|
errorMessage String?
|
|
durationSeconds Float?
|
|
audioUrl String?
|
|
timingsJson String? // Serialized array of cues [{text, startTime, endTime, speaker}]
|
|
|
|
createdAt DateTime @default(now())
|
|
updatedAt DateTime @updatedAt
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 7. API Specification
|
|
|
|
### `POST /api/episodes`
|
|
|
|
Creates a new conversion job.
|
|
|
|
```json
|
|
{
|
|
"title": "Understanding Kubernetes Ingress",
|
|
"content": "# Markdown content...",
|
|
"mode": "VERBATIM",
|
|
"provider": "edge",
|
|
"voice": "en-US-ChristopherNeural"
|
|
}
|
|
```
|
|
|
|
### `GET /api/episodes/:id`
|
|
|
|
Retrieves episode details, audio URL, processing status, and transcript timings.
|
|
|
|
### `GET /api/episodes`
|
|
|
|
Lists all episodes for the index view.
|
|
|
|
### `DELETE /api/episodes/:id`
|
|
|
|
Deletes or cancels an episode.
|
|
|
|
---
|
|
|
|
## 8. Implementation Roadmap
|
|
|
|
### Phase 1: Core Audio Generation & Minimal Player (Completed)
|
|
|
|
- [x] Next.js + TypeScript project structure and Prisma configuration.
|
|
- [x] `ITextToSpeechProvider` interface with `EdgeTTSProvider` and `OpenAITTSProvider`.
|
|
- [x] Long-text chunking, concatenation, and static file delivery.
|
|
- [x] Basic synchronized transcript viewer and audio player.
|
|
|
|
### Phase 2: Hearing-Front Script Engine (Next)
|
|
|
|
- [ ] Implement prompt templates for:
|
|
- Feynman Master Presenter (conversational breakdown).
|
|
- Dual-Host Dialogue (speaker-tagged turns).
|
|
- [ ] Parse speaker tags and route chunks to distinct voices in the TTS pipeline.
|
|
- [ ] Output synchronized paragraph/sentence timestamp manifests.
|
|
|
|
### Phase 3: Mobile PWA & Zen Listening Experience (Current)
|
|
|
|
- [x] Global `AudioProvider` ensuring uninterrupted audio playback across all navigation.
|
|
- [x] Fullscreen Zen Player with auto-scrolling synchronized transcript & tap-to-seek.
|
|
- [x] Dedicated Add Article View (`/new`) for extensible settings.
|
|
- [x] PWA manifest & mobile-responsive design for phone listening.
|