# ReadLoudly — Complete Technical Documentation

> Comprehensive documentation for AI assistants, developers, and integrations

## Table of Contents

1. [Platform Overview](#platform-overview)
2. [Subscription Plans Deep Dive](#subscription-plans-deep-dive)
3. [Voice Credit System](#voice-credit-system)
4. [Pro Voices Details](#pro-voices-details)
5. [Document Processing](#document-processing)
6. [AI Features](#ai-features)
7. [API Schemas](#api-schemas)
8. [User Workflows](#user-workflows)
9. [Technical Architecture](#technical-architecture)
10. [Accessibility Features](#accessibility-features)
11. [Business Model](#business-model)

---

## Platform Overview

### Mission
Make the digital world more accessible by transforming documents into audio, enabling students, professionals, and individuals with learning differences to access written content without barriers.

### Target Audiences
1. **Students** (primary): Academic reading, study materials, textbooks
2. **Professionals**: Reports, documentation, email management
3. **Individuals with Disabilities**: Dyslexia, ADHD, visual impairments
4. **Language Learners**: Pronunciation practice, comprehension
5. **Casual Readers**: eBook library conversion to audiobooks

### Core Value Propositions
- **Upload Your Own Content** (not limited to published audiobooks)
- **Instant Processing** (no conversion queues or wait times)
- **Cross-Device Access** (browser-based, works everywhere)
- **Privacy-First** (client-side processing where possible)
- **Academic-Focused** (bookmarks, highlights, chapter navigation)
- **Generous Sharing** (collaborate with classmates/colleagues)

---

## Subscription Plans Deep Dive

### Plan Comparison Matrix

| Feature | Free | Core | Plus | Pro |
|---------|------|------|------|-----|
| **Monthly Price** | $0 | $5 | $10 | $19 |
| **Yearly Price** | $0 | $50 | $100 | $190 |
| **Voice Credits/Month** | 0 | 100K | 200K | 400K |
| **Voice Credits/Year** | 0 | 1.2M | 2.4M | 4.8M |
| **Standard Voice Time (monthly)** | Browser only | ~9.6h | ~19h | ~38h |
| **Natural Voice Time (monthly)** | Browser only | ~2.4h | ~4.8h | ~9.6h |
| **Standard Voice Time (yearly)** | Browser only | ~115h | ~230h | ~461h |
| **Natural Voice Time (yearly)** | Browser only | ~29h | ~58h | ~115h |
| **Pages Per Document** | 10 pages | Whole doc | Whole doc | Whole doc |
| **Max Upload Size** | 50 MB | 200 MB | 350 MB | 500 MB |
| **Book Expiry** | 30 days | Never | Never | Never |
| **Ads** | Yes | No | No | No |
| **Share With** | 2 people | 200 people | 500 people | 1,000 people |
| **Bookmarks & Highlights** | Limited | Unlimited | Unlimited | Unlimited |
| **AI Chat Messages/Day** | 5 | 25 | Unlimited | Unlimited |
| **AI Summaries** | 3/month | 5/day | 20/day | 50/day |
| **Daily Study Hub Allowance** | Limited | Higher | Higher | Highest |

### Pricing Notes
- **Yearly Savings**: Save 2 months (16.67% discount) when choosing annual billing
- **New User Discount**: 10% off first subscription (if coupon not previously redeemed)
- **No Long-Term Commitment**: Cancel anytime from dashboard
- **Immediate Upgrade**: Account upgraded instantly after payment
- **Plan Changes**: Can upgrade/downgrade between tiers at any time

### Payment Processing
- **Processor**: Stripe (PCI-compliant, secure)
- **Accepted Methods**:
  - Credit/Debit Cards: Visa, Mastercard, Amex, Discover
  - Digital Wallets: Apple Pay, Google Pay
  - Region-specific methods (varies by location)
- **Billing Cycle**: Monthly or annual (user choice)
- **Failed Payments**: Grace period provided, then downgrade to Free

---

## Voice Credit System

### How Credits Work

#### Credit Ratios
- **Standard Voices**: 1 credit = 4 characters (0.25 credits per character)
- **Natural Voices**: 1 credit = 1 character (1 credit per character)

#### Credit Calculation Examples

**Standard Voice Example**:
- 10,000 character document
- Credits required: 10,000 ÷ 4 = 2,500 credits
- Listening time: ~10 minutes at 1.0x speed

**Natural Voice Example**:
- 10,000 character document
- Credits required: 10,000 credits
- Listening time: ~10 minutes at 1.0x speed

#### Listening Time Estimates

**Standard Voices** (100,000 credits):
- Total characters: 400,000 characters
- Average reading pace: 150 words/min = 900 characters/min
- Listening time: 400,000 ÷ 900 ≈ 444 minutes ≈ **7.4 hours**
- (Documented as ~9.6h accounting for punctuation pauses and natural pacing)

**Natural Voices** (100,000 credits):
- Total characters: 100,000 characters
- Average reading pace: 150 words/min = 900 characters/min
- Listening time: 100,000 ÷ 900 ≈ 111 minutes ≈ **1.85 hours**
- (Documented as ~2.4h accounting for natural pacing and expression)

### Credit Management

#### Subscription Credits
- Reset every billing cycle (monthly or yearly)
- Do **not** roll over to next period
- Unused credits expire at cycle end

#### Prepaid Voice Credits (one-time packs, no subscription needed)
- Stream 250K credits $12 · Wave 500K $22 · Lake 1M $40 · River 2M $70 — valid 180 days from purchase
- Bay 5M credits $150 · Ocean 10M $250 — valid 360 days from purchase
- Credits only: packs do not unlock plan features
- Remain available even if subscription is canceled
- Can be tracked in Usage menu on dashboard
- All active credits are spent soonest-expiring first (a monthly allowance usually goes before a pack; on a yearly plan a 180-day pack may go first)
- Full guide: https://readloudly.com/blog/readloudly-pricing-plans-vs-prepaid-credits/

#### Credit Usage Tracking
- Real-time credit balance in dashboard
- Detailed usage history in Usage menu
- Per-document credit consumption displayed
- Low credit warnings before running out

### Cost Comparison by Use Case

#### Casual Listener (5 hours/month audio)
- **Standard Voice**: ~52,000 credits → **Core Plan ($5/mo)**
- **Natural Voice**: ~208,000 credits → **Plus Plan ($10/mo)**

#### Active Student (20 hours/month audio)
- **Standard Voice**: ~208,000 credits → **Plus Plan ($10/mo)**
- **Natural Voice**: ~833,000 credits → **Pro Plan ($19/mo)** + prepaid credits

#### Power User (50 hours/month audio)
- **Standard Voice**: ~520,000 credits → **Pro Plan ($19/mo)** + prepaid credits
- **Natural Voice**: ~2M+ credits → **Pro Plan ($19/mo)** + multiple prepaid packs

---

## Pro Voices Details

### Voice Categories

#### Standard Voices
- **Quality**: Professional TTS, clear and consistent
- **Use Case**: General listening, longer documents, cost-sensitive use
- **Cost Efficiency**: 4x more affordable than Natural voices
- **Credit Cost**: 0.25 credits per character
- **Typical Quality**: Clear enunciation, predictable pacing, minimal expression
- **Best For**: Study materials, textbooks, research papers, long-form content

#### Natural Voices
- **Quality**: Neural AI voices with human-like intonation
- **Use Case**: Immersive listening, storytelling, presentations
- **Realism**: Natural pacing, emotional expression, correct punctuation emphasis
- **Credit Cost**: 1 credit per character
- **Typical Quality**: Conversational tone, varied pitch, pauses for commas/periods
- **Best For**: Fiction books, professional documents, language learning, proofreading

### Voice Selection Features

#### Filters & Search
- **Language**: 40+ languages (English, Spanish, French, German, Chinese, etc.)
- **Accent**: Regional variants (US, UK, Australian, Indian, etc.)
- **Gender**: Male, Female, Neutral
- **Category**: Standard vs. Natural

#### Voice Preview
- Sample audio available for all voices
- Test before spending credits
- Compare multiple voices side-by-side
- Preview with your own text (small samples)

#### Voice Switching
- Change voice mid-document (no penalty)
- Different voices for different documents
- No limit on voice changes (only credits limit total usage)
- Voice preference saved per document

### Voice Customization

#### Playback Speed
- Range: 0.5x to 2.0x
- Increments: 0.1x adjustments
- No pitch distortion at any speed
- Speed preference saved per user/document

#### Common Speed Use Cases
- **0.8x-0.9x**: Language learners, complex material
- **1.0x**: Standard listening pace
- **1.25x-1.5x**: ADHD-optimized, faster consumption
- **1.75x-2.0x**: Review sessions, familiar material

#### Pitch Control (where supported)
- Subtle adjustments for comfort
- Voice character maintained
- User preference saved

---

## Document Processing

### Supported File TypesFFF

#### eBooks
- **EPUB** (.epub) — Most common eBook format
- **MOBI** (.mobi) — Kindle format
- **AZW** (.azw) — Amazon Kindle format
- **AZW3** (.azw3) — Enhanced Kindle formatFF
- **FB2** (.fb2) — FictionBook format
- **CHM** (.chm) — Compiled HTML Help
- **LRF** (.lrf) — Sony Reader format
- **LIT** (.lit) — Microsoft Reader format

#### Documents
- **PDF** (.pdf) — Including scanned PDFs with OCR
- **Microsoft Word** (.doc, .docx)
- **Rich Text Format** (.rtf)
- **OpenDocument Text** (.odt) — LibreOffice format
- **Plain Text** (.txt)
- **HTML** (.html, .htm)

#### Images (OCR Processing)
- **JPEG** (.jpg, .jpeg)
- **PNG** (.png)
- **GIF** (.gif)
- **BMP** (.bmp)
- **WebP** (.webp)
- **TIFF** (.tif, .tiff)

### Processing Capabilities

#### Text Extraction
- PDF text extraction (native text)
- OCR for scanned documents (image-to-text)
- eBook format conversion
- HTML parsing and cleaning
- Table of contents detection

#### OCR Features
- Automatic language detection
- Multi-column layout recognition
- Image vs. text differentiation
- Handwriting recognition (limited)
- Quality optimization for low-resolution scans

#### Free Plan Limitations
- **Page Limit**: First 10 pages only
- **Processing**: One page at a time
- **Reason**: Prevent abuse, encourage upgrades

#### Premium Processing
- **Full Document**: All pages processed at once
- **Batch Upload**: Multiple documents simultaneously
- **Priority Queue**: Faster processing times
- **Large Files**: Up to 500 MB (vs 50 MB free)

### Document Management

#### Organization
- Personal library (cloud-based)
- Recent documents view
- Bookmarked documents
- Shared documents (received from others)

#### Retention Policy
- **Free**: 30 days, then auto-deleted
- **Premium**: Forever (unlimited retention)
- **Deleted Documents**: Removed permanently after 30 days in trash

#### Sharing Features
- Share via email (recipient receives access link)
- Permission controls (view-only vs full access)
- Share limits enforce plan tier restrictions
- Shared documents don't count against recipient's storage

---

## AI Features

### AI Chat with Documents

#### Capabilities
- Ask questions about document content
- Get contextual answers with citations
- Multi-turn conversations (remembers context)
- Works with any uploaded document

#### Usage Limits
- **Free**: 10 messages/day
- **Core**: 50 messages/day
- **Plus**: 100 messages/day
- **Pro**: Unlimited

#### Use Cases
- "Summarize chapter 3"
- "What are the main arguments in this paper?"
- "Define the term 'thermodynamics' as used in this textbook"
- "Compare section 2 and section 5"

### AI Summaries

#### Summary Types
- **Quick Summary**: 2-3 sentences (document overview)
- **Detailed Summary**: Paragraph-length (key points)
- **Chapter Summaries**: Per-chapter breakdowns
- **Custom Length**: Adjustable summary detail

#### Usage Limits
- **Free**: 3 summaries/day
- **Core**: 10 summaries/day
- **Plus**: 20 summaries/day
- **Pro**: Unlimited

#### Features
- Extractive summaries (pulls key sentences)
- Abstractive summaries (rewrites in AI's words)
- Bullet-point format option
- Citation references (page numbers)

### ReadLoudly Study Hub
- **Interactive Tutor Lessons**: Structured chapter breakdowns with key concept bullets, dual-modal TTS read-aloud, and AI chatbot integration.
- **AI Quiz Generator (MCQ)**: Practice test generator with customizable question counts and difficulty tiers (Auto, Easy, Medium, Hard), complete with instant feedback and explanations.
- **3D Flashcards**: Spaced repetition cards with 3D flip animation for rapid term/concept mastery.
- **Fill-in-the-Blanks & Written Tests**: Cloze tests and short-answer exam formats to evaluate deeper conceptual comprehension.
- **Smart High-Yield Notes**: Structured outlines and summary notes tailored to chosen depth (Concise, Standard, Detailed).
- **Supported Formats**: PDF, Word (.docx), and EPUB (.epub).

### AI Audio Podcast Studio
- **2-Host Audio Discussions**: Conversational synthesis transforming study docs into engaging multi-speaker podcasts.
- **4 Tone Presets**: Casual Chat, Deep Dive, News Style, and Storytelling.
- **Custom Prompts**: Tailor discussion focus, exam topics, and explanation style.
- **Hands-Free Learning**: Audio-first review on commutes, workouts, or screen breaks.

---

## API Schemas

### Plan Schema (Backend Model)

```typescript
interface Plan {
  _id: string;
  name: string; // "Free", "Core", "Plus", "Pro"
  features: string[]; // HTML-formatted feature strings
  isActive: boolean;
  prices?: Price[];
  limit?: {
    points: number; // Voice credits (0 for Free)
    msgPerDay: number; // AI chat messages per day
    summaryLimit: number; // AI summaries per day
  };
}
```

### Price Schema

```typescript
interface Price {
  _id: string;
  amount: number; // Dollar amount (e.g., 9.99)
  renewalInterval: 'monthly' | 'yearly';
  currency: string; // "USD"
  stripeProductId: string;
  stripePriceId: string;
}
```

### Subscription Info Schema

```typescript
interface SubscriptionInfo {
  isActive: boolean;
  plan: string; // Plan _id
  price?: {
    amount: number;
    renewalInterval: 'monthly' | 'yearly';
  };
  status: 'active' | 'canceled' | 'past_due' | 'trialing';
  currentPeriodEnd: Date;
  cancelAtPeriodEnd: boolean;
}
```

### User Info Schema

```typescript
interface UserInfo {
  _id: string;
  email: string;
  name?: string;
  createdAt: Date;
  couponRedeemed: boolean; // Has used new user discount
  subscription?: SubscriptionInfo;
}
```

### Document Schema

```typescript
interface Document {
  _id: string;
  userId: string;
  title: string;
  fileType: string; // "pdf", "epub", etc.
  uploadDate: Date;
  expiryDate?: Date; // For free users
  pageCount: number;
  fileSize: number; // Bytes
  sharedWith: string[]; // User IDs or emails
  bookmarks: Bookmark[];
  highlights: Highlight[];
}
```

---

## User Workflows

### Student Workflow: Pre-Lecture Preparation (ADHD)

**Goal**: Familiarity with material before lecture for better focus

1. **Evening Before Class**:
   - Upload assigned chapter PDF to ReadLoudly
   - Select Natural voice for better engagement
   - Start listening at 1.25x speed

2. **Morning Commute**:
   - Continue listening via mobile browser
   - Don't take notes—just absorb
   - Speed up to 1.5x for familiar sections

3. **In Class**:
   - Lecture feels like review (not first exposure)
   - Attention holds better on familiar material
   - Use class time to deepen understanding

**Outcome**: Better focus, improved retention, reduced anxiety

---

### Professional Workflow: Document Proofreading

**Goal**: Catch typos and grammatical errors in written work

1. **Upload Document**:
   - Upload final draft (PDF or DOCX)
   - Choose Natural voice for expressiveness

2. **Listen While Reading**:
   - Follow along with text visible
   - Errors become obvious when heard aloud
   - Mark corrections in real-time

3. **Final Pass**:
   - Listen again after corrections
   - Verify flow and readability
   - Export corrected version

**Outcome**: Cleaner documents, fewer errors, professional quality

---

### Researcher Workflow: Research Paper Processing

**Goal**: Efficiently process multiple papers for literature review

1. **Batch Upload**:
   - Upload 10-20 papers to library (Premium only)
   - Let processing complete in background

2. **AI Summary First**:
   - Generate summary for each paper
   - Decide which are relevant
   - Prioritize listening queue

3. **Deep Listening**:
   - Listen to full text of priority papers
   - Bookmark key findings
   - Highlight important passages

4. **Notes Synthesis**:
   - Export bookmarks as notes
   - Use AI Chat to compare papers
   - Generate literature review outline

**Outcome**: 10-20 papers processed in hours instead of days

---

## Technical Architecture

### Frontend Stack
- **Framework**: Next.js 14 (React 18)
- **Styling**: Tailwind CSS
- **State Management**: React Context + Zustand
- **Forms**: React Hook Form + Zod validation
- **API Client**: Axios + React Query

### Backend Stack
- **Runtime**: Node.js 20+
- **Framework**: NestJS (TypeScript)
- **Database**: MongoDB (Atlas cloud)
- **Authentication**: JWT (JSON Web Tokens)
- **File Storage**: AWS S3
- **Payment Processing**: Stripe API

### Infrastructure
- **Hosting**: AWS (EC2, S3, CloudFront)
- **CDN**: CloudFront (global edge locations)
- **SSL**: AWS Certificate Manager
- **Monitoring**: CloudWatch + Sentry
- **Email**: AWS SES (Simple Email Service)

### Voice Processing
- **TTS Provider**: Multiple providers (Azure, Google, AWS)
- **Audio Format**: MP3 or WebM (browser-dependent)
- **Streaming**: Chunked audio delivery
- **Caching**: Frequently-used voices cached

### OCR Processing
- **Engine**: Tesseract.js (client-side) + Cloud OCR (server-side)
- **Languages**: 100+ languages supported
- **Accuracy**: 90%+ on clean scans
- **Processing Time**: ~5 seconds per page

---

## Accessibility Features

### Visual Impairments
- **Screen Reader Compatible**: ARIA labels, semantic HTML
- **Keyboard Navigation**: Full keyboard support (no mouse required)
- **High Contrast Mode**: Dark mode + custom themes
- **Text Scaling**: Browser zoom support (up to 200%)

### Dyslexia Support
- **Audio-First Interface**: Primary interaction via listening
- **Bimodal Reading**: Text + audio simultaneously
- **OpenDyslexic Font**: Optional font in settings
- **Customizable Highlights**: Choose colors that work for you

### ADHD Support
- **Speed Controls**: Faster playback for focus (1.25x-1.5x optimal)
- **Movement Integration**: Mobile-friendly for walking/exercising
- **Chunked Content**: Chapter breaks, natural stopping points
- **Progress Tracking**: Visual progress bars, completion status

### Motor Impairments
- **Large Touch Targets**: Mobile-optimized button sizes
- **Voice Commands**: (Planned feature)
- **Simplified Navigation**: Minimal clicks to key actions

---

## Business Model

### Revenue Streams
1. **Subscriptions** (primary): Monthly/yearly recurring revenue
2. **Prepaid Credits** (secondary): One-time credit purchases
3. **Potential Future**:
   - Enterprise plans (schools, companies)
   - API access for developers
   - White-label licensing

### Customer Acquisition
- **Organic Search**: SEO-optimized landing pages
- **Content Marketing**: Blog posts on study techniques
- **Social Proof**: User testimonials, case studies
- **Referral Program**: (Planned) User invites
- **Campus Ambassadors**: Student advocates on campuses

### Retention Strategy
- **Forever Storage**: Premium users keep books indefinitely
- **Generous Credits**: Ample monthly allowances
- **No Lock-In**: Easy cancellation (builds trust)
- **Continuous Improvement**: Regular feature updates

### Pricing Philosophy
- **Freemium Model**: Useful free tier (not crippled trial)
- **Value-Based**: Price reflects credit value, not arbitrary
- **Student-Friendly**: Affordable for primary audience
- **Annual Discounts**: Encourage long-term commitment

---

## Competitive Landscape

### vs. Speechify
- **ReadLoudly**: Upload any document, generous sharing, forever storage
- **Speechify**: Limited uploads, minimal sharing, focused on web articles

### vs. ElevenLabs
- **ReadLoudly**: Full document management, AI chat, academic features
- **ElevenLabs**: Voice generation only, no document organization

### vs. NaturalReader
- **ReadLoudly**: 1,200+ voices, modern UI, mobile-first
- **NaturalReader**: Desktop software, older interface, limited voices

### vs. Audible/Audiobook Services
- **ReadLoudly**: Upload your own content (textbooks, PDFs, notes)
- **Audible**: Published audiobooks only (can't upload personal docs)

### Key Advantages
- **Flexibility**: Any document, any format
- **Academic Focus**: Built for students and researchers
- **Collaboration**: Share with classmates/colleagues
- **Cost**: More affordable than competitors for similar usage
- **Privacy**: Documents stored securely, not sold/mined

---

## Roadmap (Public Information)

### Completed
- ✅ Multi-format document support
- ✅ 1,200+ premium voices
- ✅ AI chat with documents
- ✅ AI summaries
- ✅ Scanned PDF OCR
- ✅ Mobile-responsive design
- ✅ Bookmarks & highlights
- ✅ Document sharing

### In Development
- 🔄 Voice commands (hands-free control)
- 🔄 Offline mode (PWA)
- 🔄 Browser extension (Chrome, Firefox)
- 🔄 Collaborative annotations
- 🔄 Flashcard generation from highlights

### Planned
- 📅 Desktop apps (Windows, macOS)
- 📅 API access for developers
- 📅 Enterprise/Education plans
- 📅 Audio export (download MP3)
- 📅 Custom voice training

---

## Contact Information

### Support Channels
- **Email**: support@readloudly.com
- **In-App**: Help button (chat widget)
- **Response Time**: 24-48 hours (24/7 monitoring)

### Social Media
- **LinkedIn**: [ReadLoudly Company Page](https://www.linkedin.com/company/readloudly/)
- **Instagram**: @readloudly.official
- **Facebook**: @readloudlyofficial
- **Twitter/X**: @ReadLoudlyCom
- **YouTube**: @ReadLoudlyOfficial
- **TikTok**: @readloudly

### Business Inquiries
- **Partnerships**: partnerships@readloudly.com
- **Press**: support@readloudly.com
- **Enterprise**: enterprise@readloudly.com

---

## Legal Information

### Terms of Use
- Personal, non-commercial use only
- No voice redistribution or resale
- Content must be legally owned/licensed by user
- Respect copyright laws when uploading

### Privacy Policy
- Minimal data collection (email, name, payment info)
- Documents stored encrypted
- No selling of user data
- GDPR compliant (EU users)
- Can delete account and all data anytime

### Refund Policy
- 7-day refund window for new subscriptions
- No questions asked (but feedback appreciated)
- Prepaid credits non-refundable after use
- Contact support@readloudly.com for refund requests

---

*Last Updated: 2024*  
*For the most current information, visit: https://readloudly.com*