haopengzhan/be-my-anchor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f033a6045c120bddfd0ae9935cf467648fe8dd76
be-my-anchor/docs/prd.md
T

313 lines
15 KiB
Markdown
Raw Blame History

# 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.
Reference in New Issue View Git Blame Copy Permalink