almondcodes/hadithi.ai

Cinematic African narration — script to voice MVP (Next.js + FastAPI) # Hadithi AI Cinematic African narration MVP: script → voice style → async job → audio (play + download). **Demo:** hadithi-ai-smoky.vercel.app ## Layout - `frontend/` — Next.js (App Router) + Tailwind - `backend/` — FastAPI (`POST /generate`, `GET /status/{job_id}`, `GET /audio/{job_id}` for local files) - `worker/` — Redis consumer; stub MP3 by default or VoxCPM when configured - `shared/` — Shared enums (`VoiceStyle`) ## Prerequisites - Node 20+ and npm - Python 3.11+ - Docker (optional, for Redis) or a local Redis 7 ## Quick start ### One command (recommended) From the repo root, after first-time setup below: ```bash make install # once: venv, pip, npm, copies .env.example → .env if missing make dev # Redis (Docker) + API + worker + frontend — Ctrl+C stops all ``` Open localhost. Paste a script, generate, wait for the stub clip (default `HADITHI_USE_STUB=true`). If Docker is not running, start Redis yourself (`redis-server` or your cloud URL in `REDIS_URL`) before `make dev`. ### Manual (three terminals) #### 1. Redis ```bash docker compose up -d redis ``` Without Docker, run Redis 7 locally (for example `redis-server`) on `localhost:6379`, or point `REDIS_URL` at your instance. #### 2. Python API + worker From the repo root: ```bash python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt cp .env.example .env ``` Terminal A — API (serves local audio when R2 is not configured): ```bash export PYTHONPATH=. uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000 ``` Terminal B — worker: ```bash export PYTHONPATH=. python3 -m worker ``` #### 3. Frontend ```bash cd frontend # optional: echo 'NEXT_PUBLIC_API_URL=127.0.0.1' > .env.local npm install npm run dev ``` ## Environment | Variable | Purpose | |----------|---------| | `REDIS_URL` | Redis connection | | `CORS_ORIGINS` | Comma-separated origins for the API | | `PUBLIC_API_URL` | Base URL emb …