• Python: 3.13 recommended (your install log shows Python 3.14 fails building pydantic-core)
• FFmpeg must be installed and available in PATH (for automatic audio extraction from video files)
• Create and activate a virtualenv (recommended)
• Install deps:
  • pip install -r backend/requirements.txt
• Set environment variables:
  • ASSEMBLYAI_API_KEY
  • GEMINI_API_KEY

You can use the template at backend/env.example and copy it to a local .env in backend/ (or export vars in your shell).

If you must stay on Python 3.14, one workaround is:

• export PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 but the more reliable fix is using Python 3.13.

If you use pyenv, this repo includes backend/.python-version so cd backend will automatically select Python 3.13.1 (once pyenv is initialized in your shell).

If python3 -V still shows 3.14 inside backend/, your shell likely isn't loading pyenv. Add the following to your dotfiles and restart the terminal:

• ~/.zprofile:
  • export PYENV_ROOT="$HOME/.pyenv"
  • export PATH="$PYENV_ROOT/bin:$PATH"
  • eval "$(pyenv init --path)"
• ~/.zshrc:
  • eval "$(pyenv init - zsh)"

Then recreate the venv (from backend/):

• rm -rf .venv
• python3 -m venv .venv
• source .venv/bin/activate
• python -m pip install -r requirements.txt

From the backend/ directory:

• uvicorn app.main:app --reload

• Health: GET /health
• Subtitle pipeline: POST /api/v1/subtitle

Example:

• curl -F "file=@/path/to/video.mp4" "http://localhost:8000/api/v1/subtitle"

Response includes:

• Full transcript: text
• Word timestamps: words[]
• Re-segmented phrases: phrases[]