MODELBEAST

Local-first web app that turns videos, images, and 3D files into meshes, splats, mocap, and rigged characters on the M3 Ultra. See PLAN.md for the full verified tool matrix and roadmap, and HANDOFF.md for the agent build brief (phases 1–4 instructions).

Run

/opt/homebrew/bin/uv run uvicorn server.main:app --host 0.0.0.0 --port 8777

Open http://localhost:8777 (or http://<tailscale-ip>:8777 from any device on the tailnet).

Develop

• Backend: server/ — FastAPI + SQLite (data/modelbeast.db), job runner executes operators as subprocesses.
• Frontend: web/ — React + Vite + three.js. After editing: cd web && npm run build (the server serves web/dist).
• Data: data/assets/ (asset store), data/jobs/ (job workdirs). Delete data/ to reset everything.

Operators

Each subfolder of server/operators/ with a manifest.json is an operator. The UI auto-renders its parameter form from params_schema (JSON Schema) and filters by the selected asset's kind (accepts).

Contract: the runner invokes <python> run.py --input <asset> --outdir <jobdir> --params '<json>'. Write outputs into the outdir; optionally write result.json ({"outputs": [{"path": ..., "name": ..., "meta": ...}]}) to control what gets registered as assets. stdout/stderr become the job log.

Current operators:

id	what
ffprobe	media inspection
ffmpeg_frames	video → frames (fps, mpdecimate dedupe, blur cull, max cap)
blender_convert	GLB/GLTF/OBJ/FBX/STL/PLY/USD/BLEND → GLB/FBX/OBJ/USD/USDZ/STL/PLY/BLEND via headless Blender

Heavy operators (trellis-mac, SF3D, COLMAP/Brush, FreeMoCap…) get their own uv venv: set "python": "<venv python path>" in the manifest. See PLAN.md Phase 1–4.