slow-reader/README.md

Slow Reader

A web-based reading tool that creates "meaningful friction" by automatically revealing text at an set pace, encouraging deeper engagement and preventing skimming.

Features

• Text reveals automatically
• Spacebar to pause, but no fast-forward button. Escape to exit
• Gentle highlighting through text with past words dimmed
• Customizable base WPM speed
• Three modes: text, PDF, URL parsing

Tech Stack

• Backend: Python with FastAPI, WebSockets for real-time text progression
• Frontend: Vue.js 3 with Vite
• Text Processing: NLTK
• Package Management: uv for Python dependencies
• Text parsing: Client-side parsing with PDF.js, URL content parsing with readability-lxml

Quick Start

1. Install dependencies:

   # Backend dependencies (using uv)
   uv sync
   
   # Frontend dependencies
   cd frontend && npm install
   

2. Start the application:

   ./start.sh
   

3. Open your browser: Navigate to http://localhost:3000

Manual Startup

If you prefer to run servers separately:

Backend (Terminal 1):

cd backend
uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000

Frontend (Terminal 2):

cd frontend
npm run dev

Usage

1. Paste or type your text into the input area
2. Adjust the base reading speed if desired (100-300 WPM)
3. Click "Start Reading" to begin your mindful reading session
4. Use Spacebar to pause/slow down when needed
5. Press Escape to exit reading mode at any time

Development

• Linting: Run uv run ruff check for Python code linting
• Format: Run uv run ruff format for Python code formatting
• API Documentation: Visit http://localhost:8000/docs when backend is running

Future Plans :)

• Browser extension
• Content-type specific pacing
• Reading analytics and progress tracking