oriyomi

ori—to fold, yomi—to read. Sentence-sync read-along that folds a document into speech.

oriyomi turns dense study material into something you can actually get through. Upload a textbook chapter, notes, or a PDF, and it becomes a listen-along experience: natural neural speech plays while the exact sentence being spoken is highlighted on screen. Optional comprehension quizzes close the loop — because hearing a chapter and understanding it are not the same thing.

Why oriyomi

Dense textbooks are overwhelming. A wall of text is hard to start, hard to stay oriented inside, and easy to abandon halfway through a chapter. Existing read-aloud tools either don't lock eyes and ears on the same sentence, or hide good neural voices behind API keys and paid usage.

oriyomi was built from that frustration. The name blends two Japanese words — ori (折り, to fold) and yomi (読み, to read). Like origami, you start with a flat, overwhelming sheet of paper. The parser creases it into logical sections; each section folds into clean speech you can follow along with. You aren't just hearing a textbook — you're reshaping it into something structured and digestible, one fold at a time.

What it does

1. Bring your material — upload .txt, .md, .pdf, or .docx, or paste text directly.
2. Fold the document — structure detection surfaces chapters and sections automatically.
3. Listen and read along — sentence-level timestamps highlight the exact sentence being spoken, at any speed (0.5×–2.0×).
4. Check yourself — an optional Gemini-powered comprehension quiz verifies you actually understood the fold.

No accounts. No subscriptions. No paid speech APIs. Free Microsoft Edge neural voices power the whole reading experience.

Features

• Sentence-sync read-along — the player highlights the sentence being spoken, driven by word-boundary timestamps from the TTS engine
• Document structure detection — chapters and sections are detected and turned into parallel "folds"; the first fold plays while the rest are still generating
• 9 curated free US English voices — the best Microsoft Edge neural voices, no API key required
• Adjustable speed — 0.5× to 2.0×, applied live without re-generating audio
• Text zoom — scale the reading pane to your eyes
• Optional comprehension quiz — Gemini-generated multiple-choice questions with explanations; the reader works fully without a Gemini key
• Zero gates — paste or upload and listen; nothing stands between you and the material

Quick start

Prerequisites

• Docker and Docker Compose

Run everything

cp .env.example .env   # optional: add GEMINI_API_KEY for the quiz
docker compose up --build

• Frontend: http://localhost:3000
• API: http://localhost:8000

The Next.js app proxies /api/* to the backend, so the browser never needs to know where the API lives.

Run without Docker

Backend:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py

Frontend:

cd frontend
npm install
npm run dev

Open http://localhost:3000. Point the frontend at the API with API_PROXY_URL=http://localhost:8000 (or NEXT_PUBLIC_API_URL if you prefer a direct browser call).

Environment

Variable	Service	Required	Purpose
NEXT_PUBLIC_SUPABASE_URL	frontend	Yes (deployed)	Supabase project URL. Inlined at build time from frontend/.env.local locally.
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY	frontend	Yes (deployed)	Supabase publishable (anon) key. Same inlining rules.
GEMINI_API_KEY	app	No	Enables the comprehension quiz. Without it, the reader still works; the quiz degrades gracefully.
SUPABASE_URL	app	Yes (deployed)	FastAPI: persistent words-folded counter. Without it the counter is in-memory and resets on every serverless cold start — stats freeze near 0.
SUPABASE_SERVICE_ROLE_KEY	app	Yes (deployed)	FastAPI: service-role key backing the counter RPC.
FFMPEG_PATH	app	No	Explicit ffmpeg binary for MP3 chunk merging. Defaults to the static binary bundled via imageio-ffmpeg, then PATH.
ALLOWED_ORIGINS	app	No	CORS origins for direct browser → API calls. Defaults to http://localhost:3000,http://127.0.0.1:3000. Unused when the Next.js proxy is in play.
API_PROXY_URL	frontend (Docker)	No	Where the Next dev/proxy forwards /api/*. Defaults to http://localhost:8000.

Deploying to Vercel

The two NEXT_PUBLIC_SUPABASE_* vars must be set in the Vercel project (Settings → Environment Variables, scoped to the frontend service) before the first deploy. They are inlined into the client bundle at build time — a deployment without them builds cleanly but every page returns 500 Internal Server Error (the auth middleware has no project to talk to). After adding or changing them, redeploy so the bundle is rebuilt.

The app (FastAPI) service also needs SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY (same values, scoped to the app service) or the words-folded counter resets on every serverless cold start and the stat stays frozen near 0 on all devices. The reader and TTS work either way; only the counter and quiz degrade. After setting them, check the app service logs for Words-folded counter: Supabase-backed to confirm.

Run the supabase/migrations/ SQL against your project (0001 → 0005 in order). 0005 is required in production: this project loads pg-safeupdate, which rejects the original increment_words_folded body's WHERE-less UPDATE, so every increment failed silently.

Local setup: copy the values from your Supabase project into frontend/.env.local (see frontend/.env.example).

The TTS API

The FastAPI backend is also usable on its own — free text-to-speech with sentence-level timestamps, no API key.

GET /api/voices

Returns the 9 highest-quality US English voices, ordered best first.

This is the beginning of the README. Read the rest at the original. Read the full README ↗