docs/WEB_DEV_GUIDE.md

Web UI — developer guide

Set up, run, and deploy the Gemini Studio Web stack (FastAPI + React). Product scope: SPEC_WEB_UI.md.

Imports: Code lives under VideoGeneration-release/web/. Use PYTHONPATH=. with cwd = VideoGeneration-release (parent of web/). Do not set PYTHONPATH to web/ alone.

1. Prerequisites

• Python 3.10+
• Node.js 18+ and npm (frontend build)
• ffmpeg on PATH (strip audio from MP4s)

2. Python venv

From VideoGeneration-release:

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

3. Environment variables

Do not commit secrets; use a .env with your process manager if you like.

Variable	Purpose
GEMINI_API_KEY	Server-side only.
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.

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

4. generation_options.json

Edit web/config/generation_options.json (or the file from GENERATION_OPTIONS_PATH). The UI loads GET /api/config/generation-options after login. JSON-only changes need no frontend rebuild; React/TS/CSS changes do.

• image: models (value + label), aspect_ratios, resolutions, thinking_levels.
• video / video_frames: models, aspect_ratios, resolutions, durations_seconds. On video, supports_reference_images (e.g. Veo Lite = false). With reference images, duration is forced to 8s. 首尾帧 route always 8s (no 4/6s like prompt-only 720p).

5. Build frontend

cd web/frontend
npm install
npm run build

Output: web/backend/static/. Missing build → root URL returns 503.

6. Run server

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: add --reload.

7. Dev mode (hot reload)

A — API, cwd VideoGeneration-release:

PYTHONPATH=. uvicorn web.backend.main:app --reload --host 127.0.0.1 --port 8000

B — Vite (web/frontend): npm run dev (proxies /api to 8000). Open the printed URL (e.g. http://127.0.0.1:5173).

8. Stable URL

The app does not provide a hostname. Use DNS to a domain you control, static/elastic IP, reverse proxy (nginx/Caddy), or a tunnel (Cloudflare Tunnel, Tailscale Funnel, etc.). One DNS name → current server when you move machines.

9. 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 VideoGeneration-release with PYTHONPATH=.

10. Hugging Face Spaces (Docker)

Use Docker (sdk: docker), not Streamlit/Gradio. Dockerfile at repo root next to web/ and assets/.

10.1 Create Space

Hugging Face → New Space → SDK: Docker. Space id: YOUR_USERNAME/YOUR_SPACE_NAME.

10.2 Root README.md

YAML frontmatter must validate. This repo’s README is preconfigured.

• sdk: docker
• colorFrom / colorTo: each must be one of red, yellow, green, blue, indigo, purple, pink, gray (other names → upload error).

10.3 Upload

Cwd: VideoGeneration-release (contains Dockerfile, web/, assets/).

CLI (write token):

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

Example:

hf upload LehongWu/VideoGeneration-release . . --repo-type space

Then check Space → Logs for the Docker build.

Git:

git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
git push -u hf main

Or connect GitHub in Space settings and push there.

10.4 Secrets

Settings → Variables and secrets — names must match exactly (case-sensitive). Same as §3.

Name	Purpose
GEMINI_API_KEY	Gemini key; never commit.
WEB_UI_PASSWORD	Login password.
SESSION_SECRET	e.g. openssl rand -hex 32.

Optional: GENERATION_OPTIONS_PATH (custom JSON path inside the container).

Saving restarts the Space. Never put secrets in Git or README.md.

10.5 Runtime

• Listens on PORT or 7860 (Dockerfile: uvicorn ... --port ${PORT:-7860}).
• --forwarded-allow-ips='*' — required behind HF’s reverse proxy so X-Forwarded-Proto: https is trusted. Without it, Uvicorn often sees http, session cookies misbehave, and the UI keeps asking you to log in.
• ffmpeg in image.
• First build / cold start can take minutes.

10.6 Local Docker

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.