HearText API

FastAPI backend for HearText — an audiobook / EPUB reading app with Clerk auth, online bookstore, reading progress sync, ElevenLabs TTS, and offline Sherpa-ONNX / Piper voice packs.

Features

Area	Endpoints (prefix /v1)
Auth / profile	GET/PATCH/DELETE /me (Clerk JWT; delete also removes Clerk user when CLERK_SECRET_KEY is set)
Bookshelf	/books, /progress
Annotations	/annotations (bookmark / note / highlight)
Catalog	/catalog list/search/featured/rankings/categories, TOC, chapter preview, download, shelf
Admin catalog	/admin/catalog upload / patch / delete / categories
Online TTS	/tts, /voices/clone (ElevenLabs)
Offline voices	/offline-voices list/featured/sample/download; /admin/offline-voices

Stack

• Python 3.12, FastAPI, SQLAlchemy async + Alembic
• Postgres, Redis, MinIO
• Clerk (JWT + optional Backend API)
• Docker (hys998/heartext-api)

Quick start (local)

# 1. Dependencies
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

# 2. Infra
docker compose -f docker-compose.deps.yml up -d

# 3. Env
copy .env.example .env
# fill CLERK_*, DATABASE_URL, REDIS_URL, MINIO_*, ELEVENLABS_*, ADMIN_CLERK_USER_IDS

# 4. Migrate + run
$env:PYTHONPATH='.'
alembic upgrade head
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Health: GET http://127.0.0.1:8000/health
OpenAPI: http://127.0.0.1:8000/docs

Import samples

# Standard Ebooks into catalog (compatible EPUB + subjects from book pages)
python scripts/import_standard_ebooks.py --limit 10

# Fill remaining catalog budget (polite crawl; keep --delay >= 1)
python scripts/import_standard_ebooks.py --delay 1.25

# Remove legacy Project Gutenberg catalog rows + MinIO objects
python scripts/wipe_gutenberg_catalog.py

# Piper offline voice packs (separate 2 GiB budget)
python scripts/import_offline_voices.py --limit 10
python scripts/import_offline_voices.py --attach-samples

Auth helper

Open tools/get-clerk-token.html in a browser (uses Clerk publishable key) to copy a Bearer token for /docs.

Docker

# Build & push
$env:DOCKER_IMAGE='hys998/heartext-api:0.2.2'
docker compose -f docker-compose.build.yml build
docker push $env:DOCKER_IMAGE
docker push hys998/heartext-api:latest

VPS: see docs/docker-hub.md and docs/openresty.md.
Catalog notes: docs/catalog.md.

# On server (example)
docker compose pull   # or build from ./src
docker compose up -d
docker compose exec api alembic upgrade head

Configuration

Copy .env.example → .env. Never commit .env.

Important variables:

• CLERK_ISSUER / CLERK_JWKS_URL / CLERK_SECRET_KEY
• ADMIN_CLERK_USER_IDS — comma-separated Clerk user_… ids for /v1/admin/*
• CATALOG_STORAGE_BUDGET_BYTES (default 20 GiB)
• OFFLINE_VOICE_STORAGE_BUDGET_BYTES (default 2 GiB)
• ELEVENLABS_API_KEY

Feedback

POST /v1/feedback — in-app feedback from the Android client. Auth optional (Bearer when signed in).

Body: message (required), contact?, app_version?, app_version_code?, device_info?, platform?.

Project layout

app/           FastAPI app, models, services
alembic/       DB migrations
scripts/       Import / seed / smoke tools
fixtures/      Gutenberg + offline-voice manifests
docs/          Deploy notes
Dockerfile     API image
docker-compose*.yml

License / content

Imported Gutenberg texts are US public domain via Project Gutenberg — verify jurisdiction before commercial use.
Piper voices: see rhasspy/piper-voices licenses.