ReShot — copy the shot, not the actors. Video → depth map, OpenPose skeleton or canny lines for Seedance 2.0/2.5 reference video, MiniMax H3 Fun ControlNet and Wan VACE. Apache-2.0. Open-sourced by Maosika 猫斯卡 (www.maosika.com), the AI short-drama production system.
Python ai-short-dramaai-videocannycomfyuicontrolnetdepth-anythingdepth-estimationdwposemaosikaminimaxopenposepose-controlnetpose-estimationseedanceshort-dramavideo-generationvideo-to-videowan
refactor: single pipeline for CLI and API, backend registry, typed errors, ruff-clean (0.2.0)
wangfengf6a5378f6cf0
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 8ca56f0..595005b 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -3,6 +3,15 @@ on:push: { branches: [main] }pull_request:jobs:+ lint:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4+ - uses: actions/setup-python@v5+ with: { python-version: "3.12" }+ - run: python -m pip install ruff+ - run: ruff check depthcat tests && ruff format --check depthcat tests+unit:name: unit (${{ matrix.os }}, py${{ matrix.python }})runs-on: ${{ matrix.os }}diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 0379b7e..75ad94f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,13 @@# Changelog+## 0.2.0 — 2026-09-11+- One pipeline: `depthcat.run(RunConfig)` is the single code path for the CLI and the Python API.+- Backend registry (`vda`, `fake`); `--backend fake` runs the whole pipeline without a model.+- Typed errors with exit codes (2 input · 3 RAM budget · 4 ffmpeg · 5 weights) and concrete fixes in the message.+- `RunConfig` validates arguments before any work; `plan()` exposes what a run will do.+- Metrics JSON now records the full config and plan.+- Lint (ruff) in CI; 28 tests without a model plus a real-model CPU smoke job.+## 0.1.0 — 2026-09-11- First release: `depthcat in.mp4 -o out.mp4` on Video Depth Anything Small (Apache-2.0).- Depth estimated at model resolution, whole-clip normalisation, near = white, x264 CRF 12.diff --git a/depthcat/__init__.py b/depthcat/__init__.pyindex 5ae3ebf..be59199 100644--- a/depthcat/__init__.py+++ b/depthcat/__init__.py@@ -1,8 +1,12 @@"""depthcat — turn any video into a depth "blockout" video for video-generation control.- from depthcat import extract, to_gray, write_gray_video- depths, fps = extract("in.mp4") # float32 [T, H, W], larger = closer- write_gray_video(to_gray(depths), "out.mp4", fps)+from pathlib import Path+from depthcat import RunConfig, run+run(RunConfig(input=Path("in.mp4"), output=Path("out.mp4"), target="h3"))++from depthcat import extract, to_gray, write_gray_video+depths, fps = extract("in.mp4") # float32 [T, H, W], larger = closer+write_gray_video(to_gray(depths), "out.mp4", fps)"""from __future__ import annotations@@ -10,56 +14,42 @@ from __future__ import annotationsimport os# Apple Silicon: cap the MPS allocator at 60 % of the recommended working set. Unified-# memory means GPU allocations count against the same RAM as everything else; without-# a cap a long clip grows until the OS starts killing processes (seen 2026-09-11).-# With the cap we get a clean MPS out-of-memory error instead. Must be set before-# torch is imported, which is why it lives here and not in the backend.+# memory means GPU allocations count against the same RAM as everything else; without a+# cap a long clip grows until the OS kills processes (seen 2026-09-11). Must be set+# before torch is imported, which is why it lives here.os.environ.setdefault("PYTORCH_MPS_HIGH_WATERMARK_RATIO", "0.6")-import numpy as np--from .backends import VDABackend, pick_device+from ._version import __version__+from .config import RunConfig+from .errors import BackendError, DepthcatError, InputError, RamBudgetError, ToolMissingErrorfrom .io import probe_video, read_video, write_gray_video+from .pipeline import Plan, RunResult, extract, plan, runfrom .planning import memory_verdict, processing_max_resfrom .postprocess import to_gray, upsample_frames-from .targets import TARGETS, center_crop, fit_dimensions--__version__ = "0.1.0"---def extract(- video: str,- *,- model: str = "small",- device: str = "auto",- max_res: int = 1280,- target_fps: float = -1,- max_frames: int = -1,- input_size: int = 518,- checkpoint: str | None = None,-) -> tuple[np.ndarray, float]:- """One call: decode → depth. Returns `(depths[T,H,W] float32, fps)`."""- # Infer at model resolution regardless of `max_res` — see planning.processing_max_res.- w, h, _, _ = probe_video(video)- proc = min(processing_max_res(w, h, input_size), max_res if max_res > 0 else 10**9)- frames, fps = read_video(video, max_frames=max_frames, target_fps=target_fps, max_res=proc)- backend = VDABackend(model, device=device, checkpoint=checkpoint)- return backend.infer(frames, fps, input_size=input_size), fps-+from .targets import TARGETS, Target, center_crop, fit_dimensions__all__ = [+ "TARGETS",+ "BackendError",+ "DepthcatError",+ "InputError",+ "Plan",+ "RamBudgetError",+ "RunConfig",+ "RunResult",+ "Target",+ "ToolMissingError","__version__",+ "center_crop","extract",+ "fit_dimensions",+ "memory_verdict",+ "plan","probe_video",+ "processing_max_res","read_video",- "write_gray_video",+ "run","to_gray","upsample_frames",- "processing_max_res",- "memory_verdict",- "TARGETS",- "fit_dimensions",- "center_crop",- "VDABackend",- "pick_device",+ "write_gray_video",]diff --git a/depthcat/_version.py b/depthcat/_version.pynew file mode 100644index 0000000..d3ec452--- /dev/null+++ b/depthcat/_version.py@@ -0,0 +1 @@+__version__ = "0.2.0"diff --git a/depthcat/backends/__init__.py b/depthcat/backends/__init__.pyindex f8e2ef8..c518008 100644--- a/depthcat/backends/__init__.py+++ b/depthcat/backends/__init__.py@@ -1,4 +1,23 @@+"""Backend registry. `get_backend("vda", model="small", device="auto")`."""++from __future__ import annotations++from typing import Any+from .base import BackendInfo, DepthBackend+from .fake import FakeBackendfrom .vda import VDABackend, pick_device-__all__ = ["BackendInfo", "DepthBackend", "VDABackend", "pick_device"]++def get_backend(name: str, **kwargs: Any) -> DepthBackend:+ """Instantiate a backend by name. Unknown names raise `BackendError`."""+ from ..errors import BackendError++ if name == "vda":+ return VDABackend(**kwargs)+ if name == "fake":+ return FakeBackend()+ raise BackendError(f"unknown backend {name!r}")+++__all__ = ["BackendInfo", "DepthBackend", "FakeBackend", "VDABackend", "get_backend", "pick_device"]diff --git a/depthcat/backends/fake.py b/depthcat/backends/fake.pynew file mode 100644index 0000000..c52897a--- /dev/null+++ b/depthcat/backends/fake.py@@ -0,0 +1,25 @@+"""A backend that returns a plausible depth field without loading a model.++For exercising everything *around* inference — I/O, encoding, presets, metrics,+remote job runners — in CI or on a laptop, in milliseconds and without downloads.+Select with `--backend fake` (or the env var `DEPTHCAT_FAKE_BACKEND=1`)."""++from __future__ import annotations++import numpy as np++from .base import BackendInfo+++class FakeBackend:+ info = BackendInfo(name="fake", variant="none", license="n/a", commercial_ok=True)+ fp32 = True+ device = "cpu"++ def infer(self, frames: np.ndarray, fps: float, *, input_size: int = 518) -> np.ndarray:+ t, h, w = frames.shape[:3]+ yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)+ # a soft radial "subject" in the middle that brightens over time+ base = 1.0 / (1.0 + ((xx - w / 2) ** 2 + (yy - h / 2) ** 2) / (0.15 * w * h))+ ramp = np.linspace(0.8, 1.0, num=max(t, 1), dtype=np.float32)+ return (base[None] * ramp[:, None, None]).astype(np.float32)diff --git a/depthcat/backends/vda.py b/depthcat/backends/vda.pyindex 8b30bda..cc6e70e 100644--- a/depthcat/backends/vda.py+++ b/depthcat/backends/vda.py@@ -18,7 +18,6 @@ prints a warning and sets ``info.commercial_ok = False``; the CLI surfaces this.from __future__ import annotationsimport logging-import osimport warningsimport numpy as np@@ -65,12 +64,15 @@ def _weights_path(variant: str, checkpoint: str | None) -> str:class VDABackend:def __init__(self,- variant: str = "small",+ model: str = "small",device: str = "auto",checkpoint: str | None = None,) -> None:+ variant = modelif variant not in _VARIANTS:- raise ValueError(f"unknown variant {variant!r}; choose from {sorted(_VARIANTS)}")+ from ..errors import BackendError++ raise BackendError(f"unknown model variant {variant!r}; choose from {sorted(_VARIANTS)}")from ..third_party.video_depth_anything.video_depth import VideoDepthAnythingself.variant = variant@@ -90,7 +92,15 @@ class VDABackend:stacklevel=2,)- path = _weights_path(variant, checkpoint)+ try:+ path = _weights_path(variant, checkpoint)+ except Exception as exc: # hub / network / offline-cache errors all land here+ from ..errors import BackendError++ raise BackendError(+ f"could not obtain weights for '{variant}': {exc}. "+ "Set HF_ENDPOINT to a mirror, or pass --checkpoint with a local .pth."+ ) from exclog.info("loading %s from %s on %s (fp32=%s)", variant, path, self.device, self.fp32)model = VideoDepthAnything(**_VARIANTS[variant])model.load_state_dict(torch.load(path, map_location="cpu"), strict=True)@@ -102,9 +112,7 @@ class VDABackend:# Upstream's infer_video_depth already does 32-frame windows with 10-frame overlap,# keyframe-based scale/shift alignment across windows and interpolation over the# seam. That is the temporal-consistency machinery — do not re-chunk outside it.- depths, _ = self.model.infer_video_depth(- frames, fps, input_size=input_size, device=self.device, fp32=self.fp32- )+ depths, _ = self.model.infer_video_depth(frames, fps, input_size=input_size, device=self.device, fp32=self.fp32)return np.asarray(depths, dtype=np.float32)diff --git a/depthcat/cli.py b/depthcat/cli.pyindex 11bbca7..c19fcfe 100644--- a/depthcat/cli.py+++ b/depthcat/cli.py@@ -1,173 +1,111 @@-"""`depthcat` command line.+"""`depthcat` command line: argv → RunConfig → pipeline.run().- depthcat in.mp4 -o out.mp4 # Apache-2.0 Small model, auto device- depthcat in.mp4 -o out.mp4 --target h3 # 24 fps, ×32 dims, ≤15 s for MiniMax H3- depthcat in.mp4 -o out.mp4 --npz depth.npz --metrics run.json+ depthcat in.mp4 -o out.mp4 # Apache-2.0 Small model, auto device+ depthcat in.mp4 -o out.mp4 --target h3 # 24 fps, ×32 dims, ≤15 s for MiniMax H3+ depthcat in.mp4 -o out.mp4 --npz d.npz --metrics run.json-Memory model: depth is estimated at the model's working resolution (short side 518 px)-and only the 8-bit result is upscaled to the output size, frame by frame while-encoding. A host-RAM estimate is printed and, if it exceeds half of physical RAM, the-run is refused with a concrete `--max-frames` suggestion (override with `--force`).+Exit codes: 0 ok · 1 unexpected · 2 bad input/arguments · 3 over RAM budget ·+4 ffmpeg missing · 5 backend/weights problem."""from __future__ import annotationsimport argparse-import jsonimport logging-import os-import platform-import resourceimport sys-import time+from pathlib import Path-import numpy as np--from . import __version__-from .backends import VDABackend, pick_device-from .io import probe_video, read_video, write_gray_video-from .planning import gib, memory_verdict, processing_max_res-from .postprocess import to_gray, upsample_frames-from .targets import TARGETS, fit_dimensions+from ._version import __version__+from .config import BACKENDS, MODEL_VARIANTS, RunConfig+from .errors import DepthcatError+from .pipeline import run+from .reporter import StderrReporter+from .targets import TARGETSdef build_parser() -> argparse.ArgumentParser:p = argparse.ArgumentParser(prog="depthcat",description="Video → depth blockout video for video-generation ControlNets.",+ epilog="Docs: https://github.com/maosika-ai/depthcat",+ )+ p.add_argument("input", type=Path, help="input video (anything ffmpeg/OpenCV can read)")+ p.add_argument("-o", "--output", type=Path, required=True, help="output .mp4")+ g = p.add_argument_group("model")+ g.add_argument(+ "--model",+ default="small",+ choices=MODEL_VARIANTS,+ help="Video Depth Anything variant; only 'small' is Apache-2.0 (default)",+ )+ g.add_argument("--backend", default="vda", choices=BACKENDS, help=argparse.SUPPRESS)+ g.add_argument("--device", default="auto", help="auto | cuda | mps | cpu")+ g.add_argument("--input-size", type=int, default=518, help="model short side, multiple of 14 (default 518)")+ g.add_argument("--checkpoint", type=Path, help="local .pth instead of the Hugging Face download")+ g = p.add_argument_group("output")+ g.add_argument(+ "--target",+ default="none",+ choices=sorted(TARGETS),+ help="fps / frame-size preset for a generator: " + ", ".join(f"{k}={v.note}" for k, v in TARGETS.items()),+ )+ g.add_argument("--fps", type=float, help="override output fps (default: preset or source)")+ g.add_argument(+ "--max-res", type=int, default=1280, help="cap the OUTPUT's longer side (inference runs at model resolution)"+ )+ g.add_argument("--max-frames", type=int, help="stop after N frames")+ g.add_argument("--invert", action="store_true", help="far = white instead of near = white")+ g.add_argument(+ "--clip", type=float, default=0.0, metavar="PCT", help="percentile clip on both tails before scaling")- p.add_argument("input", help="input video (anything ffmpeg/OpenCV can read)")- p.add_argument("-o", "--output", required=True, help="output .mp4")- p.add_argument("--model", default="small", choices=["small", "base", "large"],- help="VDA variant; only 'small' is Apache-2.0 (default)")- p.add_argument("--device", default="auto", help="auto | cuda | mps | cpu")- p.add_argument("--target", default="none", choices=sorted(TARGETS),- help="fps / size preset for a specific generator")- p.add_argument("--fps", type=float, default=-1, help="override output fps (-1 = preset or source)")- p.add_argument("--max-res", type=int, default=1280,- help="cap the longer side of the OUTPUT (inference always runs at model resolution)")- p.add_argument("--max-frames", type=int, default=-1, help="stop after N frames (-1 = all)")- p.add_argument("--input-size", type=int, default=518, help="model short side (multiple of 14)")- p.add_argument("--invert", action="store_true", help="far = white instead of near = white")- p.add_argument("--clip", type=float, default=0.0, metavar="PCT",- help="percentile clip on both tails before scaling (0 = exact min/max)")- p.add_argument("--gamma", type=float, default=1.0)- p.add_argument("--crf", type=int, default=12, help="x264 CRF; lower = larger, cleaner")- p.add_argument("--npz", help="also save raw float depth (at processing resolution) to this .npz")- p.add_argument("--metrics", help="write timing / memory / size metrics as JSON to this path")- p.add_argument("--checkpoint", help="local .pth instead of the Hugging Face download")- p.add_argument("--force", action="store_true", help="run even if the RAM estimate exceeds the budget")+ g.add_argument("--gamma", type=float, default=1.0, help=">1 darkens mid-tones")+ g.add_argument("--crf", type=int, default=12, help="x264 CRF; lower = larger, cleaner (default 12)")+ g.add_argument("--npz", type=Path, help="also save raw float depth (processing resolution)")+ g.add_argument("--metrics", type=Path, help="write timing / memory / size metrics as JSON")+ g = p.add_argument_group("safety")+ g.add_argument("--force", action="store_true", help="run even if the RAM estimate exceeds the budget")p.add_argument("-v", "--verbose", action="store_true")- p.add_argument("--version", action="version", version=__version__)+ p.add_argument("--version", action="version", version=f"depthcat {__version__}")return p-def _peak_rss_bytes() -> int:- ru = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss- # macOS reports bytes, Linux kilobytes.- return int(ru if platform.system() == "Darwin" else ru * 1024)---def _say(msg: str) -> None:- print(msg, file=sys.stderr, flush=True)+def config_from_args(args: argparse.Namespace) -> RunConfig:+ return RunConfig(+ input=args.input,+ output=args.output,+ model=args.model,+ backend=args.backend,+ device=args.device,+ target=args.target,+ fps=args.fps,+ max_res=args.max_res,+ max_frames=args.max_frames,+ input_size=args.input_size,+ invert=args.invert,+ clip_percent=args.clip,+ gamma=args.gamma,+ crf=args.crf,+ npz=args.npz,+ metrics=args.metrics,+ checkpoint=args.checkpoint,+ force=args.force,+ )def main(argv: list[str] | None = None) -> int:args = build_parser().parse_args(argv)- logging.basicConfig(level=logging.INFO if args.verbose else logging.WARNING,- format="%(levelname)s %(name)s: %(message)s")- target = TARGETS[args.target]- fps_req = args.fps if args.fps > 0 else (target.fps or -1)- metrics: dict = {"version": __version__, "input": args.input, "model": args.model, "target": args.target}- t0 = time.time()-- # ── plan: how big will this run be? ────────────────────────────────────────────- src_w, src_h, src_fps, src_n = probe_video(args.input)- out_fps = src_fps if fps_req <= 0 or fps_req >= src_fps else fps_req- n_frames = src_n if args.max_frames <= 0 else min(src_n, args.max_frames)- n_frames = int(round(n_frames * out_fps / src_fps)) if out_fps < src_fps else n_frames- proc_res = min(processing_max_res(src_w, src_h, args.input_size), args.max_res if args.max_res > 0 else 10**9)- scale = min(1.0, proc_res / max(src_w, src_h))- proc_w, proc_h = int(round(src_w * scale / 2) * 2), int(round(src_h * scale / 2) * 2)- verdict = memory_verdict(n_frames, proc_w, proc_h)- _say(f"plan {src_w}x{src_h} @ {src_fps:.3f} fps × {src_n} frames → process {proc_w}x{proc_h} × ~{n_frames} frames, "- f"host RAM ≈ {gib(verdict['estimate'])} (budget {gib(verdict['budget'])})")- metrics.update(source=[src_w, src_h, src_fps, src_n], process=[proc_w, proc_h, n_frames],- ram_estimate=verdict["estimate"], ram_budget=verdict["budget"])- if not verdict["ok"] and not args.force:- _say(f"abort estimated RAM exceeds budget. Try --max-frames {verdict['max_frames_ok']} "- f"(or split the clip), a smaller --input-size, or --force if you know the machine can take it.")- return 3-- # ── read ────────────────────────────────────────────────────────────────────────- frames, fps = read_video(args.input, max_frames=args.max_frames, target_fps=fps_req, max_res=proc_res)- t, h, w = frames.shape[:3]- _say(f"read {t} frames @ {fps:.3f} fps, {w}x{h} ({time.time() - t0:.1f}s)")- if target.max_seconds and t / fps > target.max_seconds + 1e-6:- _say(f"warn clip is {t / fps:.1f}s; {target.key} accepts ≤ {target.max_seconds:.0f}s — trim it")-- # ── depth ───────────────────────────────────────────────────────────────────────- device = pick_device(args.device)- if os.environ.get("DEPTHCAT_FAKE_BACKEND"):- # Dry-run mode for exercising the whole pipeline (I/O, encoding, metrics, remote- # runbook) without loading a model. Produces a plausible radial gradient.- _say("model FAKE backend (DEPTHCAT_FAKE_BACKEND set) — no inference")- yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)- base = 1.0 / (1.0 + ((xx - w / 2) ** 2 + (yy - h / 2) ** 2) / (0.15 * w * h))- depths = np.stack([base * (0.8 + 0.2 * i / max(1, t - 1)) for i in range(t)]).astype(np.float32)- precision, license_ = "none", "n/a"- dt = 0.0- else:- backend = VDABackend(args.model, device=device, checkpoint=args.checkpoint)- precision, license_ = ("fp32" if backend.fp32 else "fp16"), backend.info.license- _say(f"model {backend.info.name}/{backend.info.variant} on {device} ({precision}), licence {license_}")- t1 = time.time()- depths = backend.infer(frames, fps, input_size=args.input_size)- dt = time.time() - t1- del backend- _release_accelerator(device)- _say(f"depth {dt:.1f}s = {dt / t * 1000:.0f} ms/frame")- del frames- metrics.update(device=device, precision=precision, license=license_, frames=t, fps=fps,- depth_seconds=round(dt, 2), ms_per_frame=round(dt / t * 1000, 1))-- if args.npz:- np.savez_compressed(args.npz, depths=depths, fps=fps)- _say(f"npz {args.npz}")-- # ── grey → output size → encode (frame by frame) ────────────────────────────────- gray = to_gray(depths, invert=args.invert, clip_percent=args.clip, gamma=args.gamma)- del depths- out_scale = min(1.0, (args.max_res if args.max_res > 0 else 10**9) / max(src_w, src_h))- out_h, out_w = fit_dimensions(int(src_h * out_scale), int(src_w * out_scale), target.multiple)- if (out_h, out_w) != (h, w):- _say(f"size {w}x{h} → {out_w}x{out_h} (multiple of {target.multiple})")- out = write_gray_video(upsample_frames(gray, out_h, out_w), args.output, fps, crf=args.crf, size=(out_h, out_w))- total = time.time() - t0- peak = _peak_rss_bytes()- _say(f"wrote {out} ({total:.1f}s total, peak RSS {gib(peak)})")- metrics.update(output=str(out), output_size=[out_w, out_h], total_seconds=round(total, 1),- peak_rss_bytes=peak, output_bytes=os.path.getsize(out))- if args.metrics:- with open(args.metrics, "w", encoding="utf-8") as fh:- json.dump(metrics, fh, ensure_ascii=False, indent=2)- _say(f"metrics {args.metrics}")- if license_ not in ("Apache-2.0", "n/a"):- _say("note weights are non-commercial; use --model small for commercial work")- return 0---def _release_accelerator(device: str) -> None:- """Give cached GPU/MPS memory back before encoding; harmless on CPU."""+ logging.basicConfig(+ level=logging.INFO if args.verbose else logging.WARNING, format="%(levelname)s %(name)s: %(message)s"+ )try:- import torch-- if device == "cuda":- torch.cuda.empty_cache()- elif device == "mps":- torch.mps.empty_cache()- except Exception: # pragma: no cover- pass+ run(config_from_args(args), StderrReporter())+ except DepthcatError as exc:+ print(f"depthcat: {exc}", file=sys.stderr)+ return exc.exit_code+ except KeyboardInterrupt:+ print("depthcat: interrupted", file=sys.stderr)+ return 130+ return 0if __name__ == "__main__": # pragma: no coverdiff --git a/depthcat/config.py b/depthcat/config.pynew file mode 100644index 0000000..d36d73a--- /dev/null+++ b/depthcat/config.py@@ -0,0 +1,55 @@+"""Everything a run needs, in one immutable object. Built by the CLI from argv, or by+library users directly. Validation that does not need I/O happens in `__post_init__`+so mistakes surface before any work starts."""++from __future__ import annotations++from dataclasses import dataclass, field+from pathlib import Path++from .errors import InputError+from .targets import TARGETS++MODEL_VARIANTS = ("small", "base", "large")+BACKENDS = ("vda", "fake")+++@dataclass(frozen=True)+class RunConfig:+ input: Path+ output: Path+ model: str = "small"+ backend: str = "vda"+ device: str = "auto"+ target: str = "none"+ fps: float | None = None # None = preset or source+ max_res: int = 1280 # cap on the OUTPUT's longer side+ max_frames: int | None = None+ input_size: int = 518 # model short side (multiple of 14)+ invert: bool = False+ clip_percent: float = 0.0+ gamma: float = 1.0+ crf: int = 12+ npz: Path | None = None+ metrics: Path | None = None+ checkpoint: Path | None = None+ force: bool = False # ignore the RAM budget+ extra: dict = field(default_factory=dict) # free-form, echoed into metrics++ def __post_init__(self) -> None:+ if self.target not in TARGETS:+ raise InputError(f"unknown --target {self.target!r}; choose from {', '.join(sorted(TARGETS))}")+ if self.model not in MODEL_VARIANTS:+ raise InputError(f"unknown --model {self.model!r}; choose from {', '.join(MODEL_VARIANTS)}")+ if self.backend not in BACKENDS:+ raise InputError(f"unknown backend {self.backend!r}; choose from {', '.join(BACKENDS)}")+ if self.input_size % 14:+ raise InputError("--input-size must be a multiple of 14 (ViT patch size)")+ if not 0 <= self.clip_percent < 50:+ raise InputError("--clip must be in [0, 50)")+ if self.gamma <= 0:+ raise InputError("--gamma must be > 0")+ if not 0 <= self.crf <= 51:+ raise InputError("--crf must be in [0, 51]")+ if self.max_frames is not None and self.max_frames < 1:+ raise InputError("--max-frames must be ≥ 1")diff --git a/depthcat/errors.py b/depthcat/errors.pynew file mode 100644index 0000000..2cada86--- /dev/null+++ b/depthcat/errors.py@@ -0,0 +1,45 @@+"""User-facing errors. The CLI prints `str(exc)` and maps each to an exit code; library+users can catch `DepthcatError` for anything the tool considers a *user* problem+(bad input, over budget, missing tool) as opposed to a bug."""++from __future__ import annotations+++class DepthcatError(Exception):+ """Base class; `exit_code` is what the CLI returns."""++ exit_code = 1+++class InputError(DepthcatError):+ """The input video could not be opened or decoded."""++ exit_code = 2+++class RamBudgetError(DepthcatError):+ """The planned run would exceed the host-RAM budget (see planning.py)."""++ exit_code = 3++ def __init__(self, estimate: int, budget: int, max_frames_ok: int) -> None:+ self.estimate, self.budget, self.max_frames_ok = estimate, budget, max_frames_ok+ from .planning import gib++ super().__init__(+ f"estimated host RAM {gib(estimate)} exceeds the budget {gib(budget)}. "+ f"Try --max-frames {max_frames_ok} (or split the clip), a smaller --input-size, "+ "or --force if you know the machine can take it."+ )+++class ToolMissingError(DepthcatError):+ """A required external tool (ffmpeg) is missing."""++ exit_code = 4+++class BackendError(DepthcatError):+ """Unknown backend / model variant, or weights could not be loaded."""++ exit_code = 5diff --git a/depthcat/io.py b/depthcat/io.pyindex 31724d8..efb31e9 100644--- a/depthcat/io.py+++ b/depthcat/io.py@@ -10,8 +10,8 @@ from __future__ import annotationsimport shutilimport subprocess+from collections.abc import Iterablefrom pathlib import Path-from typing import Iterableimport cv2import numpy as np@@ -90,11 +90,13 @@ def ffmpeg_binary() -> str:return imageio_ffmpeg.get_ffmpeg_exe()except Exception as exc: # pragma: no cover - environment dependent- raise RuntimeError("ffmpeg not found; install ffmpeg or `pip install imageio-ffmpeg`") from exc+ from .errors import ToolMissingError++ raise ToolMissingError("ffmpeg not found; install ffmpeg or `pip install imageio-ffmpeg`") from excdef write_gray_video(- gray: "np.ndarray | Iterable[np.ndarray]",+ gray: np.ndarray | Iterable[np.ndarray],path: str | Path,fps: float,*,@@ -126,13 +128,35 @@ def write_gray_video(path = Path(path)path.parent.mkdir(parents=True, exist_ok=True)cmd = [- ffmpeg_binary(), "-y", "-loglevel", "error",- "-f", "rawvideo", "-pix_fmt", "gray", "-s", f"{w}x{h}", "-r", f"{fps:.6f}", "-i", "-",+ ffmpeg_binary(),+ "-y",+ "-loglevel",+ "error",+ "-f",+ "rawvideo",+ "-pix_fmt",+ "gray",+ "-s",+ f"{w}x{h}",+ "-r",+ f"{fps:.6f}",+ "-i",+ "-","-an",- "-c:v", "libx264", "-preset", "slow", "-crf", str(crf),- "-pix_fmt", "yuv420p", "-profile:v", "high",- "-g", str(max(1, int(round(fps * keyint_seconds)))),- "-movflags", "+faststart",+ "-c:v",+ "libx264",+ "-preset",+ "slow",+ "-crf",+ str(crf),+ "-pix_fmt",+ "yuv420p",+ "-profile:v",+ "high",+ "-g",+ str(max(1, round(fps * keyint_seconds))),+ "-movflags",+ "+faststart",str(path),]proc = subprocess.Popen(cmd, stdin=subprocess.PIPE, stderr=subprocess.PIPE)diff --git a/depthcat/pipeline.py b/depthcat/pipeline.pynew file mode 100644index 0000000..356d095--- /dev/null+++ b/depthcat/pipeline.py@@ -0,0 +1,256 @@+"""The pipeline: plan → read → depth → grey → encode. This is the only module that wires+the steps together; the CLI and the Python API both call `run()`.++ from depthcat import RunConfig, run+ result = run(RunConfig(input=Path("in.mp4"), output=Path("out.mp4"), target="h3"))++Design notes+------------+* Inference always runs at the model's working resolution (short side `input_size`).+ The 8-bit result is scaled to the output size frame by frame during encoding, so a+ 12 s 720p clip needs ~4 GB of host RAM instead of 8–20 GB (see planning.py).+* Normalisation is computed once over the whole clip; per-frame normalisation makes+ static geometry flicker, which the downstream generator reads as motion.+* Failure modes that are the *user's* to fix raise `DepthcatError` subclasses with a+ concrete suggestion; everything else propagates as a bug.+"""++from __future__ import annotations++import json+import os+import platform+import resource+import time+from dataclasses import asdict, dataclass+from pathlib import Path++import numpy as np++from ._version import __version__+from .backends import get_backend, pick_device+from .config import RunConfig+from .errors import InputError, RamBudgetError+from .io import probe_video, read_video, write_gray_video+from .planning import gib, memory_verdict, processing_max_res+from .postprocess import to_gray, upsample_frames+from .reporter import NullReporter, Reporter+from .targets import TARGETS, fit_dimensions+++@dataclass(frozen=True)+class Plan:+ """What the run will do, decided before any heavy work."""++ src_w: int+ src_h: int+ src_fps: float+ src_frames: int+ out_fps: float+ frames: int # frames that will be processed (after fps / max-frames)+ proc_w: int+ proc_h: int+ proc_max_res: int # value handed to read_video+ out_w: int+ out_h: int+ ram_estimate: int+ ram_budget: int+++@dataclass(frozen=True)+class RunResult:+ output: Path+ frames: int+ fps: float+ width: int+ height: int+ device: str+ precision: str+ license: str+ depth_seconds: float+ total_seconds: float+ peak_rss_bytes: int+ metrics: dict++ @property+ def ms_per_frame(self) -> float:+ return self.depth_seconds / max(self.frames, 1) * 1000.0+++def plan(cfg: RunConfig) -> Plan:+ """Probe the source and decide sizes and frame counts. Cheap; no decoding."""+ try:+ src_w, src_h, src_fps, src_n = probe_video(cfg.input)+ except FileNotFoundError as exc:+ raise InputError(f"cannot open {cfg.input}") from exc+ if src_w <= 0 or src_h <= 0:+ raise InputError(f"{cfg.input} has no video stream")++ target = TARGETS[cfg.target]+ fps_req = cfg.fps if cfg.fps else (target.fps or -1)+ out_fps = src_fps if fps_req <= 0 or fps_req >= src_fps else fps_req+ frames = src_n if cfg.max_frames is None else min(src_n, cfg.max_frames)+ if out_fps < src_fps:+ frames = round(frames * out_fps / src_fps)+ frames = max(frames, 1)++ cap = cfg.max_res if cfg.max_res > 0 else 10**9+ proc_max_res = min(processing_max_res(src_w, src_h, cfg.input_size), cap)+ scale = min(1.0, proc_max_res / max(src_w, src_h))+ proc_w, proc_h = (int(round(src_w * scale / 2) * 2), int(round(src_h * scale / 2) * 2))++ out_scale = min(1.0, cap / max(src_w, src_h))+ out_h, out_w = fit_dimensions(int(src_h * out_scale), int(src_w * out_scale), target.multiple)++ verdict = memory_verdict(frames, proc_w, proc_h)+ return Plan(+ src_w,+ src_h,+ src_fps,+ src_n,+ out_fps,+ frames,+ proc_w,+ proc_h,+ proc_max_res,+ out_w,+ out_h,+ verdict["estimate"],+ verdict["budget"],+ )+++def run(cfg: RunConfig, reporter: Reporter | None = None) -> RunResult:+ """Execute a full run. See module docstring."""+ rep = reporter or NullReporter()+ t0 = time.time()+ target = TARGETS[cfg.target]++ # ── plan ──────────────────────────────────────────────────────────────────+ p = plan(cfg)+ rep.step(+ "plan",+ f"{p.src_w}x{p.src_h} @ {p.src_fps:.3f} fps × {p.src_frames} → "+ f"process {p.proc_w}x{p.proc_h} × ~{p.frames}, host RAM ≈ {gib(p.ram_estimate)} "+ f"(budget {gib(p.ram_budget)})",+ )+ if p.ram_estimate > p.ram_budget and not cfg.force:+ raise RamBudgetError(+ p.ram_estimate, p.ram_budget, memory_verdict(p.frames, p.proc_w, p.proc_h)["max_frames_ok"]+ )++ # ── read ──────────────────────────────────────────────────────────────────+ fps_req = cfg.fps if cfg.fps else (target.fps or -1)+ frames, fps = read_video(cfg.input, max_frames=cfg.max_frames or -1, target_fps=fps_req, max_res=p.proc_max_res)+ t, h, w = frames.shape[:3]+ rep.step("read", f"{t} frames @ {fps:.3f} fps, {w}x{h}")+ if target.max_seconds and t / fps > target.max_seconds + 1e-6:+ rep.step("warn", f"clip is {t / fps:.1f}s; {target.key} accepts ≤ {target.max_seconds:.0f}s — trim it")++ # ── depth ─────────────────────────────────────────────────────────────────+ backend_name = "fake" if os.environ.get("DEPTHCAT_FAKE_BACKEND") else cfg.backend+ device = pick_device(cfg.device)+ backend = (+ get_backend("fake")+ if backend_name == "fake"+ else get_backend(+ "vda", model=cfg.model, device=device, checkpoint=str(cfg.checkpoint) if cfg.checkpoint else None+ )+ )+ precision = "fp32" if backend.fp32 else "fp16"+ rep.step(+ "model",+ f"{backend.info.name}/{backend.info.variant} on {backend.device} ({precision}), licence {backend.info.license}",+ )+ t1 = time.time()+ depths = backend.infer(frames, fps, input_size=cfg.input_size)+ depth_seconds = time.time() - t1+ del frames+ _release_accelerator(backend.device)+ del backend+ rep.step("depth", f"{depth_seconds:.1f}s = {depth_seconds / t * 1000:.0f} ms/frame")++ if cfg.npz:+ np.savez_compressed(cfg.npz, depths=depths, fps=fps)+ rep.step("npz", str(cfg.npz))++ # ── grey → encode ─────────────────────────────────────────────────────────+ gray = to_gray(depths, invert=cfg.invert, clip_percent=cfg.clip_percent, gamma=cfg.gamma)+ del depths+ if (p.out_h, p.out_w) != (h, w):+ rep.step("size", f"{w}x{h} → {p.out_w}x{p.out_h} (multiple of {target.multiple})")+ out = write_gray_video(+ upsample_frames(gray, p.out_h, p.out_w), cfg.output, fps, crf=cfg.crf, size=(p.out_h, p.out_w)+ )+ total = time.time() - t0+ peak = _peak_rss_bytes()+ rep.step("wrote", f"{out} ({total:.1f}s total, peak RSS {gib(peak)})")++ metrics = {+ "version": __version__,+ "config": {k: (str(v) if isinstance(v, Path) else v) for k, v in asdict(cfg).items()},+ "plan": asdict(p),+ "device": device,+ "precision": precision,+ "frames": t,+ "fps": fps,+ "depth_seconds": round(depth_seconds, 3),+ "ms_per_frame": round(depth_seconds / t * 1000, 1),+ "total_seconds": round(total, 2),+ "peak_rss_bytes": peak,+ "output": str(out),+ "output_size": [p.out_w, p.out_h],+ "output_bytes": os.path.getsize(out),+ }+ if cfg.metrics:+ with open(cfg.metrics, "w", encoding="utf-8") as fh:+ json.dump(metrics, fh, ensure_ascii=False, indent=2)+ rep.step("metrics", str(cfg.metrics))+ if not _license_ok(metrics):+ rep.step("note", "weights are non-commercial; use --model small for commercial work")++ return RunResult(+ out, t, fps, p.out_w, p.out_h, device, precision, backend_name, depth_seconds, total, peak, metrics+ )+++def extract(+ video: str | Path,+ *,+ model: str = "small",+ device: str = "auto",+ max_res: int = 1280,+ target_fps: float = -1,+ max_frames: int = -1,+ input_size: int = 518,+ checkpoint: str | None = None,+) -> tuple[np.ndarray, float]:+ """Convenience: decode → depth, no encoding. Returns `(depths[T,H,W] float32, fps)`.++ Same resolution policy as `run()`: frames are read at model resolution."""+ w, h, _, _ = probe_video(video)+ proc = min(processing_max_res(w, h, input_size), max_res if max_res > 0 else 10**9)+ frames, fps = read_video(video, max_frames=max_frames, target_fps=target_fps, max_res=proc)+ backend = get_backend("vda", model=model, device=device, checkpoint=checkpoint)+ return backend.infer(frames, fps, input_size=input_size), fps+++def _license_ok(metrics: dict) -> bool:+ return metrics["config"]["model"] == "small" or metrics["config"]["backend"] == "fake"+++def _peak_rss_bytes() -> int:+ ru = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss+ return int(ru if platform.system() == "Darwin" else ru * 1024) # macOS bytes, Linux KiB+++def _release_accelerator(device: str) -> None:+ try:+ import torch++ if device == "cuda":+ torch.cuda.empty_cache()+ elif device == "mps":+ torch.mps.empty_cache()+ except Exception:+ passdiff --git a/depthcat/py.typed b/depthcat/py.typednew file mode 100644index 0000000..e69de29diff --git a/depthcat/reporter.py b/depthcat/reporter.pynew file mode 100644index 0000000..6cfad41--- /dev/null+++ b/depthcat/reporter.py@@ -0,0 +1,27 @@+"""Progress reporting. The pipeline talks to a `Reporter`; the CLI supplies one that+writes timestamped lines to stderr, library users get silence by default."""++from __future__ import annotations++import sys+import time+from typing import Protocol+++class Reporter(Protocol):+ def step(self, tag: str, message: str) -> None: ...+++class NullReporter:+ def step(self, tag: str, message: str) -> None:+ return None+++class StderrReporter:+ """`[+12.3s] read 294 frames …` — tag padded so columns line up."""++ def __init__(self) -> None:+ self._t0 = time.time()++ def step(self, tag: str, message: str) -> None:+ print(f"[+{time.time() - self._t0:6.1f}s] {tag:<7s}{message}", file=sys.stderr, flush=True)diff --git a/depthcat/targets.py b/depthcat/targets.pyindex 9b34f4c..badfdfa 100644--- a/depthcat/targets.py+++ b/depthcat/targets.py@@ -15,8 +15,8 @@ import numpy as np@dataclass(frozen=True)class Target:key: str- fps: float | None # None = keep source fps- multiple: int # frame size rounded down to a multiple of this+ fps: float | None # None = keep source fps+ multiple: int # frame size rounded down to a multiple of thismax_seconds: float | None # warn beyond thisnote: str@@ -40,6 +40,6 @@ def center_crop(frames: np.ndarray, h: int, w: int) -> np.ndarray:Crop, not pad: a padded black border reads to the generator as a far wall."""- H, W = frames.shape[1], frames.shape[2]- top, left = (H - h) // 2, (W - w) // 2+ src_h, src_w = frames.shape[1], frames.shape[2]+ top, left = (src_h - h) // 2, (src_w - w) // 2return frames[:, top : top + h, left : left + w]diff --git a/pyproject.toml b/pyproject.tomlindex fd44a08..1e50816 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"[project]name = "depthcat"-version = "0.1.0"+dynamic = ["version"]description = "Turn any video into a depth blockout video for video-generation ControlNets (MiniMax H3, Wan VACE, ...)."readme = "README.md"license = { text = "Apache-2.0" }@@ -37,12 +37,20 @@ depthcat = "depthcat.cli:main"[project.urls]Homepage = "https://github.com/maosika-ai/depthcat"+[tool.setuptools.dynamic]+version = { attr = "depthcat._version.__version__" }+[tool.setuptools.packages.find]include = ["depthcat*"][tool.setuptools.package-data]"depthcat.third_party.video_depth_anything" = ["LICENSE"]+"depthcat" = ["py.typed"][tool.ruff]-line-length = 110+line-length = 120extend-exclude = ["depthcat/third_party"]++[tool.ruff.lint]+select = ["E", "F", "W", "I", "UP", "B", "SIM", "N", "RUF"]+ignore = ["E501", "RUF001", "RUF002", "RUF003"] # E501: formatter; RUF00x: unicode ×→ in comments is intentionaldiff --git a/tests/test_io.py b/tests/test_io.pyindex 32c27c8..97b6f3e 100644--- a/tests/test_io.py+++ b/tests/test_io.py@@ -6,6 +6,7 @@ import pytestfrom depthcat.io import read_video, write_gray_video+def _has_ffmpeg():try:from depthcat.io import ffmpeg_binarydiff --git a/tests/test_model_smoke.py b/tests/test_model_smoke.pyindex 9b07139..9fc908d 100644--- a/tests/test_model_smoke.py+++ b/tests/test_model_smoke.py@@ -1,6 +1,6 @@"""End-to-end with the real Small model on CPU. Opt-in (downloads 111 MB):- RUN_MODEL_TESTS=1 pytest tests/test_model_smoke.py+RUN_MODEL_TESTS=1 pytest tests/test_model_smoke.py"""import osdiff --git a/tests/test_pipeline.py b/tests/test_pipeline.pynew file mode 100644index 0000000..b1070c5--- /dev/null+++ b/tests/test_pipeline.py@@ -0,0 +1,81 @@+"""End-to-end through `run()` with the fake backend: exercises planning, decoding,+presets, cropping, encoding, npz and metrics — everything except the model."""++import json+from pathlib import Path++import cv2+import numpy as np+import pytest++from depthcat import RunConfig, RunResult, plan, run+from depthcat.errors import InputError, RamBudgetError+++def _clip(path: Path, frames=12, w=200, h=120, fps=30):+ vw = cv2.VideoWriter(str(path), cv2.VideoWriter_fourcc(*"mp4v"), fps, (w, h))+ for i in range(frames):+ vw.write(np.full((h, w, 3), (i * 10) % 256, np.uint8))+ vw.release()+ return path+++def test_run_end_to_end_with_h3_preset(tmp_path):+ src = _clip(tmp_path / "src.mp4")+ cfg = RunConfig(+ input=src,+ output=tmp_path / "out.mp4",+ backend="fake",+ target="h3",+ npz=tmp_path / "d.npz",+ metrics=tmp_path / "m.json",+ )+ res = run(cfg)+ assert isinstance(res, RunResult)+ # 200x120 → multiples of 32 → 192x96; 30 fps → 24 fps → 12 frames become ~10+ assert (res.width, res.height) == (192, 96)+ assert res.fps == 24 and 9 <= res.frames <= 10+ assert res.output.exists() and res.output.stat().st_size > 500+ z = np.load(tmp_path / "d.npz")+ assert z["depths"].shape[0] == res.frames+ m = json.loads((tmp_path / "m.json").read_text())+ assert m["output_size"] == [192, 96] and m["config"]["target"] == "h3"+++def test_plan_is_cheap_and_consistent(tmp_path):+ src = _clip(tmp_path / "src.mp4", frames=30, w=640, h=360)+ p = plan(RunConfig(input=src, output=tmp_path / "o.mp4", backend="fake"))+ assert (p.src_w, p.src_h, p.src_frames) == (640, 360, 30)+ assert p.proc_h == 360 # short side already ≤ 518: no downscale+ assert p.ram_estimate > 0 and p.ram_budget > 0+++def test_ram_budget_refuses_then_force_allows(tmp_path, monkeypatch):+ import depthcat.pipeline as pl++ src = _clip(tmp_path / "src.mp4")+ monkeypatch.setattr(pl, "memory_verdict", lambda *_: {"estimate": 10, "budget": 1, "ok": False, "max_frames_ok": 1})+ with pytest.raises(RamBudgetError) as ei:+ run(RunConfig(input=src, output=tmp_path / "o.mp4", backend="fake"))+ assert ei.value.exit_code == 3 and "--max-frames 1" in str(ei.value)+ run(RunConfig(input=src, output=tmp_path / "o.mp4", backend="fake", force=True))+++def test_config_validation_is_upfront(tmp_path):+ with pytest.raises(InputError):+ RunConfig(input=tmp_path / "x.mp4", output=tmp_path / "o.mp4", target="nope")+ with pytest.raises(InputError):+ RunConfig(input=tmp_path / "x.mp4", output=tmp_path / "o.mp4", input_size=500)+++def test_missing_input_is_a_user_error(tmp_path):+ with pytest.raises(InputError):+ run(RunConfig(input=tmp_path / "missing.mp4", output=tmp_path / "o.mp4", backend="fake"))+++def test_cli_exit_codes(tmp_path):+ from depthcat.cli import main++ src = _clip(tmp_path / "src.mp4")+ assert main([str(src), "-o", str(tmp_path / "o.mp4"), "--backend", "fake"]) == 0+ assert main([str(tmp_path / "nope.mp4"), "-o", str(tmp_path / "o.mp4"), "--backend", "fake"]) == 2diff --git a/tests/test_postprocess.py b/tests/test_postprocess.pyindex 5d7d662..629960e 100644--- a/tests/test_postprocess.py+++ b/tests/test_postprocess.py@@ -14,12 +14,12 @@ def test_global_normalisation_not_per_frame():d[0] = np.linspace(0, 1, 16).reshape(4, 4)d[1] = np.linspace(0, 10, 16).reshape(4, 4)g = to_gray(d)- assert g[0].max() <= 26 # 1/10 of 255+ assert g[0].max() <= 26 # 1/10 of 255assert g[1].max() == 255def test_near_is_white_by_default_and_invert_flips():- d = np.array([[[0.0, 5.0]]], np.float32) # larger = closer (VDA convention)+ d = np.array([[[0.0, 5.0]]], np.float32) # larger = closer (VDA convention)assert to_gray(d)[0, 0].tolist() == [0, 255]assert to_gray(d, invert=True)[0, 0].tolist() == [255, 0]@@ -42,8 +42,10 @@ def test_to_gray_rejects_wrong_rank():to_gray(np.zeros((2, 2), np.float32))[email protected]("h,w,m,exp", [(1280, 736, 32, (1280, 736)), (1080, 1920, 32, (1056, 1920)),- (7, 9, 2, (6, 8)), (10, 10, 32, (32, 32))])+ "h,w,m,exp",+ [(1280, 736, 32, (1280, 736)), (1080, 1920, 32, (1056, 1920)), (7, 9, 2, (6, 8)), (10, 10, 32, (32, 32))],+)def test_fit_dimensions_rounds_down_to_multiple(h, w, m, exp):assert fit_dimensions(h, w, m) == exp