# Product Requirements Document (PRD): Be My Anchor **Status**: Approved (Post Grill-Me) **Target Version**: 2.0 (Full Refactor) **Architecture**: TypeScript / Node.js Fullstack **Primary Output**: `docs/prd.md` --- ## 1. Executive Summary & Vision **Be My Anchor** transforms written materials—technical blogs, research papers, news articles, novels, and documentation—into an engaging, listening-first multimedia experience. Rather than relying on brittle, heavy web scrapers or monotone text-to-speech readers, Be My Anchor adopts an **API-first ingestion** model combined with: 1. **High-Fidelity Audio Generation**: Seamless multi-provider 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. **Synchronized Visual Companion**: A web player that dynamically surfaces referenced figures, diagrams, and code snippets in sync with the audio narration. --- ## 2. Core Philosophy & Phased Strategy ``` ┌─────────────────────────────────────────────────────────────┐ │ Phase 1: Robust Audio Generation Core │ │ - Multi-provider TTS (Edge TTS, OpenAI, ElevenLabs) │ │ - Long-form text chunking & audio stitching │ │ - Basic web player & episode library │ └──────────────────────────────┬──────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Phase 2: Hearing-Front Content Transformation │ │ - "Feynman" Deep-Dive Presenter Persona │ │ - Dual-Host Dialogue Persona (NotebookLM style) │ │ - Script stage cue tagging │ └──────────────────────────────┬──────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Phase 3: Interactive Synchronized Multimedia Player │ │ - Timestamped visual cues (figures, code, diagrams) │ │ - Karaoke-style synced transcript │ │ - Stage-aware responsive visual pane │ └─────────────────────────────────────────────────────────────┘ ``` --- ## 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, breaking down equations, and explaining diagrams. - **Visual Need**: When the narrator says *"Looking at Figure 2, the ingress traffic routes through..."*, Figure 2 automatically appears on screen. ### 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 rhetorical questions, and adding contextual background not directly present in the source article. - **Visual Need**: Highlight cards, quotes, and source citations appearing on the dashboard. ### 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 / Assets) │ └─────────────┬──────────────┘ │ ▼ ┌────────────────────────────┐ │ Hearing-Front Script Engine│ │ (LLM: OpenAI / Claude) │ │ - Rewrites text for ear │ │ - Generates Stage Cues │ └─────────────┬──────────────┘ │ Script with Stage Marks │ ▼ ┌────────────────────────────┐ │ TTS Generation Core │ │ ┌──────────┐ ┌───────────┐ │ │ │ Edge TTS │ │OpenAI TTS │ │ │ └──────────┘ └───────────┘ │ │ ┌────────────────────────┐ │ │ │ ElevenLabs (Multi-Voice│ │ │ └────────────────────────┘ │ │ - Chunker & Audio Stitcher │ │ - Timing Aligner (VTT/JSON)│ └─────────────┬──────────────┘ │ ▼ ┌───────────────────────────────────┴───────────────────────────────────┐ │ Data & Storage │ │ - Database: Prisma ORM (MongoDB / PostgreSQL) │ │ - File Storage: Local static / S3-compatible (Audio MP3s & Figures) │ └───────────────────────────────────┬───────────────────────────────────┘ │ ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ Interactive Web Player (Next.js / TS) │ │ ┌───────────────────────┐ ┌───────────────────────────────────────┐ │ │ │ Audio Player UI │ │ Synchronized Visual Stage │ │ │ │ - Waveform / Scrubber│ │ - Figures / Diagrams from post │ │ │ │ - Speed / ±15s Skips │ │ - Syntax-highlighted code snippets │ │ │ │ - Live Transcript │ │ - Key takeaway summary cards │ │ │ └───────────────────────┘ └───────────────────────────────────────┘ │ └───────────────────────────────────────────────────────────────────────┘ ``` --- ## 5. Functional Requirements ### 5.1 Content Ingestion (API-Driven) - Provide a clean REST API accepting: - `title`: String - `content`: Plain text or Markdown (including image references `![alt](url)`) - `format_mode`: `'feynman'` | `'dual_host'` | `'verbatim'` - `voice_config`: Provider preference (`edge` | `openai` | `elevenlabs`), voice IDs, speed - `supplemental_materials`: Optional array of images/figures, captions, and links - No requirement for headless Selenium or browser dependencies on the server. ### 5.2 Hearing-Front Content Transformation - **Verbatim Cleaner**: Strips markdown artifacts, normalizes punctuation, phonetic hints for acronyms. - **Feynman Script Generator**: - Rewrites technical content into an oral lecture/walkthrough. - Generates `[STAGE: figure_id]` or `[STAGE: code_block_id]` inline tags corresponding to visual assets. - **Dual-Host Dialogue Generator**: - Turns article content into an interactive conversation between Host A (e.g., inquisitive, relatable) and Host B (e.g., domain expert). - Emits speaker-tagged lines: `SpeakerA: ...` and `SpeakerB: ...`. ### 5.3 TTS Engine & Audio Processing - **Provider Abstraction Interface (`ITextToSpeechProvider`)**: - `EdgeTTSProvider`: Free, instant, high-quality neural voices (`en-US-ChristopherNeural`, `en-US-JennyNeural`, etc.), zero API key required. - `OpenAITTSProvider`: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`. - `ElevenLabsProvider`: High-fidelity multi-voice assignment with voice cloning or distinct character voices for multi-host dialogue. - **Long-Text Chunker**: - Breaks script into sentence/clause chunks respecting provider character limits (e.g. 4096 chars). - Handles speaker switching in dual-host mode without awkward pauses. - **Audio Stitcher & Aligner**: - Stitches chunk audio files into a unified master `.mp3`. - Outputs a timing manifest (`timings.json` or WebVTT) recording the start and end timestamp of each paragraph, speaker turn, and stage marker. ### 5.4 Synchronized Web View & Media Player - **Episode Library**: - List of generated episodes with duration, creation date, mode, and status (`processing`, `ready`, `failed`). - **Audio Player Controls**: - Play / Pause, Progress scrubber, Current time / Total duration. - Jump Back 15s (`-15s`), Jump Forward 15s (`+15s`). - Playback speed selection (0.8x, 1.0x, 1.25x, 1.5x, 2.0x). - **Synchronized Transcript Pane**: - Interactive transcript that auto-scrolls and highlights the active paragraph/dialogue turn as audio plays. - Clicking any paragraph seeks playback directly to that timestamp. - **Synchronized Stage (Supplemental Visual Information)**: - Responsive visual viewport alongside or above the player. - When the audio reaches a tagged stage (e.g. timestamp 02:15): - Automatically displays the relevant figure, architecture diagram, equation, or code snippet. - Provides zoom/expand view for detailed inspection. - Gracefully transitions to summary notes when no specific figure is active. --- ## 6. Data Model (Prisma Schema Specification) ```prisma datasource db { provider = "postgresql" // or "mongodb" url = env("DATABASE_URL") } generator client { provider = "prisma-client-js" } enum ProcessingStatus { PENDING SCRIPTING SYNTHESIZING READY FAILED } enum ScriptMode { VERBATIM FEYNMAN DUAL_HOST } model Episode { id String @id @default(cuid()) @map("_id") title String originalContent String scriptContent String? mode ScriptMode @default(FEYNMAN) status ProcessingStatus @default(PENDING) durationSeconds Float? audioUrl String? timingsJson String? // Serialized timestamp cues stages StageItem[] createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } model StageItem { id String @id @default(cuid()) @map("_id") episodeId String timestampSeconds Float type String // "IMAGE" | "CODE" | "CALLOUT" title String? content String // Image URL or Code snippet / Callout text caption String? episode Episode @relation(fields: [episodeId], references: [id], onDelete: Cascade) } ``` --- ## 7. API Specification ### `POST /api/episodes` Creates a new conversion job. ```json { "title": "Understanding Kubernetes Ingress Controllers", "content": "# Markdown content...", "mode": "FEYNMAN", "ttsProvider": "edge", "voiceOptions": { "primaryVoice": "en-US-ChristopherNeural", "speed": 1.0 }, "visualAssets": [ { "id": "fig-1", "type": "IMAGE", "url": "https://example.com/arch.png", "caption": "Figure 1: Ingress routing architecture" } ] } ``` **Response**: `202 Accepted` with `{ "episodeId": "clx...", "status": "PENDING" }`. ### `GET /api/episodes/:id` Retrieves episode details, audio URL, processing status, transcript timings, and stage markers. ### `GET /api/episodes` Lists all generated episodes for the library view. --- ## 8. Technical Stack | Component | Technology | Rationale | | --- | --- | --- | | **Runtime & Language** | Node.js (v20+) / TypeScript | Rapid prototyping, strong typing, zero Python venv/setup friction. | | **Framework** | Next.js (App Router) | Unified backend API routes + reactive frontend player in one repo. | | **Database & ORM** | Prisma + MongoDB or PostgreSQL | Lightweight document/relational storage matching user preference. | | **Audio Generation** | `msedge-tts`, OpenAI API, ElevenLabs SDK | Free zero-key tier (Edge) + premium commercial options. | | **Audio Processing** | `fluent-ffmpeg` or Web Audio APIs | Fast server-side audio stitching and silence injection. | | **LLM Orchestration** | Vercel AI SDK / OpenAI SDK | Streaming script generation and structured stage extraction. | | **Styling** | Tailwind CSS / Lucide Icons | Clean modern aesthetic, responsive audio controls. | --- ## 9. Implementation Roadmap ### Phase 1: Core Audio Generation & Minimal Player (Week 1) - [ ] Initialize Next.js + TypeScript project structure and Prisma configuration. - [ ] Implement `ITextToSpeechProvider` interface with `EdgeTTSProvider` and `OpenAITTSProvider`. - [ ] Build audio chunking, concatenation, and static file delivery. - [ ] Implement basic Web Player UI (Play/Pause, Scrubber, Episode list). ### Phase 2: Hearing-Front Script Engine (Week 2) - [ ] Implement prompt templates for: - Feynman Master Presenter (single host, 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: Synchronized Visual Stages (Week 3) - [ ] Extract or link visual assets (figures/diagrams/code) to script stages. - [ ] Build the interactive Stage Viewer in the web player: - Figure transitions locked to audio progress. - Interactive transcript with click-to-seek. - [ ] End-to-end testing with technical papers, blog posts, and news feeds.