# 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.