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

13 KiB
Raw Permalink Blame History

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)

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.

{
  "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)

  • Next.js + TypeScript project structure and Prisma configuration.
  • ITextToSpeechProvider interface with EdgeTTSProvider and OpenAITTSProvider.
  • Long-text chunking, concatenation, and static file delivery.
  • 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)

  • Global AudioProvider ensuring uninterrupted audio playback across all navigation.
  • Fullscreen Zen Player with auto-scrolling synchronized transcript & tap-to-seek.
  • Dedicated Add Article View (/new) for extensible settings.
  • PWA manifest & mobile-responsive design for phone listening.
Reference in New Issue View Git Blame Copy Permalink