docs/WEB_DEV_GUIDE.md

# Web UI — developer guide

Setup, run, deploy (FastAPI + React). Product scope: **[SPEC_WEB_UI.md](./SPEC_WEB_UI.md)**.

**Imports:** Code under `VideoGeneration-release/web/`. Run Python with cwd **`VideoGeneration-release`** and **`PYTHONPATH=.`** (not `web/` alone).

## Prerequisites

Python 3.10+, Node 18+, npm, **ffmpeg** on `PATH`.

## Python venv

```bash
cd /path/to/VideoGeneration-release
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r web/requirements.txt
```

## Environment variables

Do not commit secrets.

| Variable | Purpose |
|----------|---------|
| `GEMINI_API_KEY` | Server-side API key. |
| `WEB_UI_PASSWORD` | Login password. |
| `SESSION_SECRET` | Session signing, e.g. `openssl rand -hex 32`. |
| `GENERATION_OPTIONS_PATH` | Optional; overrides default `web/config/generation_options.json`. |
| `SESSION_COOKIE_SECURE` | Optional. `1`/`true`/`yes` for HTTPS-only cookies (e.g. Hugging Face). Unset for local `http://127.0.0.1`. Proxy must send `X-Forwarded-Proto` (see Hugging Face / Docker below). |

```bash
export GEMINI_API_KEY="your_key"
export WEB_UI_PASSWORD="password"
export SESSION_SECRET="$(openssl rand -hex 32)"
```

## `generation_options.json`

Edit **`web/config/generation_options.json`** (or path from `GENERATION_OPTIONS_PATH`). UI loads it via **`GET /api/config/generation-options`** after login. JSON-only changes need no frontend rebuild.

- **`image`**: `models`, `aspect_ratios`, `resolutions`.
- **`video`** / **`video_frames`**: `models`, `aspect_ratios`, `resolutions`, `durations_seconds`. On **`video`**, **`supports_reference_images: false`** disables reference images for that model (e.g. Veo 3 / Veo 3 Fast — prompt-only; Veo 3.1 Lite — also no reference images). With reference images, duration is **8s**. **首尾帧** route is always **8s**. On **`video_frames`**, **`supports_end_frame: false`** (e.g. Veo 3 / Veo 3 Fast) means only the start frame is used; end-frame UI and last-frame conditioning are omitted.

## Build frontend

```bash
cd web/frontend
npm install
npm run build
```

Output: **`web/backend/static/`**. Without it, root URL returns 503.

## Run server

```bash
cd /path/to/VideoGeneration-release
PYTHONPATH=. uvicorn web.backend.main:app --host 127.0.0.1 --port 8000
```

LAN: `--host 0.0.0.0`. Dev: `--reload`.

## Dev (hot reload)

**API:** `PYTHONPATH=. uvicorn web.backend.main:app --reload --host 127.0.0.1 --port 8000` from repo root.

**Vite:** `cd web/frontend && npm run dev` — proxies `/api` to 8000; open the printed URL (e.g. `http://127.0.0.1:5173`).

## Stable URL

Use your own DNS/domain, static IP, reverse proxy, or tunnel — no hostname is baked into the app.

## Checklist

- [ ] `ffmpeg -version`
- [ ] `pip install -r web/requirements.txt`
- [ ] `npm run build` in `web/frontend` at least once
- [ ] `GEMINI_API_KEY`, `WEB_UI_PASSWORD`, `SESSION_SECRET` set
- [ ] Uvicorn from repo root with `PYTHONPATH=.`

## Hugging Face Spaces (Docker)

Use **Docker** Space (`sdk: docker`). **`Dockerfile`** at repo root beside `web/` and `assets/`.

### Create & upload

[Hugging Face](https://huggingface.co/) → New Space → **SDK: Docker**. Root **`README.md`** YAML must validate (`sdk: docker`; **`colorFrom`** / **`colorTo`** each one of: `red`, `yellow`, `green`, `blue`, `indigo`, `purple`, `pink`, `gray`).

**Upload** from **`VideoGeneration-release`** (contains `Dockerfile`, `web/`, `assets/`):

```bash
pip install -U huggingface_hub
huggingface-cli login
cd /path/to/VideoGeneration-release
hf upload YOUR_USERNAME/YOUR_SPACE_NAME . . --repo-type space
```

Or add git remote `https://huggingface.co/spaces/USER/SPACE` and push.

### Secrets

**Settings → Variables and secrets** — same names as the env table above (case-sensitive). Optional: `GENERATION_OPTIONS_PATH`. Saving restarts the Space.

### Runtime (Dockerfile)

Listens on **`PORT`** or **7860**. **`--forwarded-allow-ips='*'`** is required behind HF’s proxy so HTTPS and session cookies work. **ffmpeg** in image. Cold start can take minutes.

### Local Docker

```bash
cd /path/to/VideoGeneration-release
docker build -t gemini-studio-web .
docker run --rm -p 7860:7860 \
  -e GEMINI_API_KEY="your_key" \
  -e WEB_UI_PASSWORD="your_password" \
  -e SESSION_SECRET="$(openssl rand -hex 32)" \
  gemini-studio-web
```

Open `http://127.0.0.1:7860`.