Read2Me

Read2Me is a local-first document-to-audio system. The MVP focuses on TXT/Markdown input and a reliable end-to-end path to MP3 output, with PDF/EPUB planned post-midpoint and optional NLP features as stretch goals.

Quickstart

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

./scripts/run_app.sh

Open the Streamlit URL shown in the terminal and upload a TXT or Markdown file to create a job.

Local artifacts are stored in the OS temp directory by default. Override with READ2ME_DATA_DIR.

MVP Scope

• Minimum input support: TXT/Markdown (PDF/EPUB added post-midpoint).
• End-to-end pipeline: upload -> process -> MP3 -> download.
• Default local TTS adapter: pyttsx3.
• Deterministic regex cleanup and stable segmentation.
• Simple web UI for upload and output retrieval.

Execution plan and backlog are in docs/BACKLOG.md. Stretch goals are documented in docs/ROADMAP.md.

Start Here (New Teammates)

• Onboarding concepts: docs/FOUNDATIONS.md.
• Local setup: docs/SETUP.md.
• Work priorities and MVP checklist: docs/BACKLOG.md.
• Architecture overview: docs/ARCHITECTURE.md.
• Team workflow and PRs: docs/TEAM_CONTRIBUTIONS.md.

Architecture At A Glance

Input -> UI -> Orchestrator -> Extraction -> Cleaning/Preprocess -> Non-linguistic detection -> Optional multimodal description injection -> TTS -> Assembly -> Download MP3

Modules are organized under src/read2me/ to mirror this pipeline. See docs/ARCHITECTURE.md.

Repo Layout

• src/read2me/ - App code and pipeline modules.
• docs/ - Project plan, requirements, architecture, and team workflow.
• tests/ - Unit tests and smoke tests.
• scripts/ - Developer convenience scripts.
• .github/ - Issue templates and CI.

Development Workflow

• Branches: main, dev, and feature branches.
• PRs required with at least 1 reviewer.
• CI runs lint + tests; CODEOWNERS enforced.

Details are in docs/TEAM_CONTRIBUTIONS.md.