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
0.3.5: --quality auto|full|fast is the user's choice; measured full-vs-fast difference in the docs
wangfenge525be46df2a
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex b9ccd9f..05525f6 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,11 @@# Changelog+## 0.3.5 — 2026-09-12+- **`--quality auto|full|fast`** replaces the silent small-GPU fallback of 0.3.4: `full` is 518 px,+ `fast` 364 px, `auto` (default) picks by VRAM and says which it chose. `--input-size` stays as+ the expert override. Measured difference full vs fast on the same clip: mean 5.3/255 grey+ levels, 95 % of pixels within 15, edge energy −4.5 % — fine detail only.+## 0.3.4 — 2026-09-12- **Small GPUs work out of the box.** Measured on an RTX 3080 Ti: the default `--input-size 518`peaks at 7.4 GiB allocated / 10.9 GiB reserved and OOMs on an 8 GB card; 364 peaks atdiff --git a/README.md b/README.mdindex 60ad24d..37e0f10 100644--- a/README.md+++ b/README.md@@ -102,13 +102,15 @@ Things we learned making the demo:| | Runs? | Measured ||---|---|---|-| **NVIDIA, 12 GB or more** (RTX 3080 Ti, 4070, 4090 …) | Yes, full quality | 4090: 62 ms/frame, 11 GB VRAM peak · 3080 Ti: 83 ms/frame |-| **NVIDIA, 8 GB** (RTX 3070, 4060 …) | Yes — the tool switches to `--input-size 364` by itself | 3 GB VRAM, 34 ms/frame on a 3080 Ti; depth is slightly softer |+| **NVIDIA, 12 GB or more** (RTX 3080 Ti, 4070, 4090 …) | Yes, `--quality full` | 4090: 62 ms/frame, 11 GB VRAM peak · 3080 Ti: 83 ms/frame |+| **NVIDIA, 8 GB** (RTX 3070, 4060 …) | Yes, `--quality fast` (picked automatically) | 3 GB VRAM, 34 ms/frame on a 3080 Ti || **Apple Silicon** | Yes, slower | M2 Max: ~500 ms/frame, a 12 s clip in about 2.5 min || **CPU only** | Yes, slow | ~1.8 s/frame || **Host RAM** | 16 GB covers clips up to ~27 s at 720p | peak = 2 GB + 224 MB per second of 720p; the tool refuses before starting if a clip won't fit |-Verified on rented cards on 2026-09-12; the numbers are in `--metrics` output of those runs.+**`--quality`** is yours to choose: `auto` (default) takes `full` on cards with 11.5 GB or more and `fast` below that; pass `full` or `fast` to decide yourself. The difference, measured on the same 294-frame clip: the model sees the frame at 518 px vs 364 px on the short side; large shapes — people, props, who is nearer — come out identical, fine detail is softer at `fast` (a loose strand of hair merges into the cheek). Mean difference 5.3 of 255 grey levels, 95 % of pixels within 15, edge energy −4.5 %. For copying blocking and camera, `fast` is enough; for close-ups where fine silhouettes matter, use `full`. Experts can set the exact size with `--input-size`.++Verified on rented cards on 2026-09-12; the numbers are in the `--metrics` output of those runs.## Presetsdiff --git a/README.zh-CN.md b/README.zh-CN.mdindex 8c9688f..4b5294f 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -102,12 +102,14 @@ is transferred onto <Subject 1> and <Subject 2>; its grey depth look is not tran| | 能不能跑 | 实测 ||---|---|---|-| **N 卡 12 GB 及以上**(RTX 3080 Ti、4070、4090……) | 能,全画质 | 4090:62 ms/帧、显存峰值 11 GB;3080 Ti:83 ms/帧 |-| **N 卡 8 GB**(RTX 3070、4060……) | 能——工具自动切到 `--input-size 364` | 显存 3 GB、3080 Ti 上 34 ms/帧;深度图略软 |+| **N 卡 12 GB 及以上**(RTX 3080 Ti、4070、4090……) | 能,`--quality full` | 4090:62 ms/帧、显存峰值 11 GB;3080 Ti:83 ms/帧 |+| **N 卡 8 GB**(RTX 3070、4060……) | 能,`--quality fast`(自动选) | 显存 3 GB、3080 Ti 上 34 ms/帧 || **Apple 芯片** | 能,慢 | M2 Max 约 500 ms/帧,12 秒的片约 2.5 分钟 || **纯 CPU** | 能,很慢 | 约 1.8 秒/帧 || **内存** | 16 GB 能跑 720p 约 27 秒 | 峰值 = 2 GB + 每秒 720p 约 224 MB;放不下会在开始之前拒绝 |+**`--quality` 由你定**:`auto`(默认)在 11.5 GB 以上的卡取 `full`、以下取 `fast`;想自己定就直接传 `full` 或 `fast`。两者的差别(同一段 294 帧的片实测):模型看到的画面短边 518 像素还是 364 像素;大形状——人、道具、谁近谁远——两边一模一样,细的东西 `fast` 会软(脸颊旁一缕头发会糊进脸里)。平均差 5.3 个灰阶(满量程 255),95% 的像素差在 15 以内,边缘锐度低 4.5%。复制走位和运镜,`fast` 够用;特写里在意细轮廓,用 `full`。要精确尺寸用 `--input-size`。+2026-09-12 在租来的显卡上实测;数字都在那几次运行的 `--metrics` 输出里。## 预设diff --git a/demo/requirements.txt b/demo/requirements.txtindex 4caf100..549442d 100644--- a/demo/requirements.txt+++ b/demo/requirements.txt@@ -1,5 +1,5 @@--extra-index-url https://download.pytorch.org/whl/cputorchtorchvision-reshot[ffmpeg] @ git+https://github.com/maosika-ai/[email protected]+reshot[ffmpeg] @ git+https://github.com/maosika-ai/[email protected]gradio>=4.0diff --git a/demo/space/index.html b/demo/space/index.htmlindex 37b28d1..6de5313 100644--- a/demo/space/index.html+++ b/demo/space/index.html@@ -82,7 +82,8 @@ reshot reference.mp4 -o depth.mp4 --target seedance</code></pre><h2>Measured <span class="zh">/ 实测</span></h2><table><tr><th>device</th><th>ms / frame</th><th>host RAM</th></tr>-<tr><td>RTX 4090, fp16</td><td>70 (31 with <code>--input-size 364</code>)</td><td>4.5 GB</td></tr>+<tr><td>RTX 4090, fp16</td><td>62 (<code>--quality full</code>, 11 GB VRAM)</td><td>3.9 GB</td></tr>+<tr><td>RTX 3080 Ti, fp16</td><td>83 full · 34 <code>--quality fast</code> (3 GB VRAM)</td><td>3.5 GB</td></tr><tr><td>Apple M2 Max, fp32</td><td>~500</td><td>~4 GB</td></tr></table>diff --git a/docs/USAGE.md b/docs/USAGE.mdindex 8f1be48..08dd74a 100644--- a/docs/USAGE.md+++ b/docs/USAGE.md@@ -41,7 +41,8 @@ reshot INPUT -o OUTPUT [options]|---|---|---|| `--model small\|base\|large` | `small` | Only `small` is Apache-2.0. `base`/`large` are CC-BY-NC-4.0: allowed for research, a warning is printed. || `--device auto\|cuda\|mps\|cpu` | `auto` | fp16 on CUDA, fp32 elsewhere (fp16 on MPS is unusably slow). |-| `--input-size N` | `518` | Model short side, multiple of 14. `364` is ~2× faster with visibly softer edges. |+| `--quality Q` | `auto` | `full` = model sees 518 px on the short side (~11 GB VRAM), `fast` = 364 px (~3 GB, 2× faster, fine detail softer: mean Δ 5.3/255, edges −4.5 %). `auto` = full on ≥ 11.5 GB cards, fast below. |+| `--input-size N` | — | Expert: exact model short side, multiple of 14; overrides `--quality`. || `--checkpoint PATH` | – | Local `.pth`, skips the download. |### Outputdiff --git a/docs/USAGE.zh-CN.md b/docs/USAGE.zh-CN.mdindex f80036a..d0b7da1 100644--- a/docs/USAGE.zh-CN.md+++ b/docs/USAGE.zh-CN.md@@ -40,7 +40,8 @@ reshot 输入 -o 输出 [选项]|---|---|---|| `--model small\|base\|large` | `small` | 只有 `small` 是 Apache-2.0。`base`/`large` 是 CC-BY-NC-4.0:研究可用,运行时会警告。 || `--device auto\|cuda\|mps\|cpu` | `auto` | CUDA 用 fp16,其余 fp32(MPS 上 fp16 慢到不可用)。 |-| `--input-size N` | `518` | 模型短边,14 的倍数。`364` 快约一倍,边缘略软。 |+| `--quality Q` | `auto` | `full` = 模型看短边 518 像素(约 11 GB 显存),`fast` = 364 像素(约 3 GB、快一倍、细节略软:平均差 5.3/255、边缘 −4.5%)。`auto` = ≥11.5 GB 的卡取 full、以下取 fast。 |+| `--input-size N` | — | 专家用:精确指定模型短边,14 的倍数,覆盖 `--quality`。 || `--checkpoint 路径` | – | 本地 `.pth`,跳过下载。 |### 输出diff --git a/reshot/__init__.py b/reshot/__init__.pyindex 40c3f23..39bc9ca 100644--- a/reshot/__init__.py+++ b/reshot/__init__.py@@ -23,7 +23,7 @@ from ._version import __version__from .config import RunConfigfrom .errors import BackendError, InputError, RamBudgetError, ReshotError, ToolMissingErrorfrom .io import probe_video, read_video, write_gray_video-from .pipeline import Plan, RunResult, extract, plan, run, run_many+from .pipeline import Plan, RunResult, extract, plan, resolve_input_size, run, run_manyfrom .planning import memory_verdict, processing_max_resfrom .postprocess import to_gray, upsample_framesfrom .targets import TARGETS, Target, center_crop, fit_dimensions@@ -48,6 +48,7 @@ __all__ = ["probe_video","processing_max_res","read_video",+ "resolve_input_size","run","run_many","to_gray",diff --git a/reshot/_version.py b/reshot/_version.pyindex 334b899..a8d4557 100644--- a/reshot/_version.py+++ b/reshot/_version.py@@ -1 +1 @@-__version__ = "0.3.4"+__version__ = "0.3.5"diff --git a/reshot/cli.py b/reshot/cli.pyindex 20be998..954f0ff 100644--- a/reshot/cli.py+++ b/reshot/cli.py@@ -21,7 +21,7 @@ import sysfrom pathlib import Pathfrom ._version import __version__-from .config import BACKENDS, MODEL_VARIANTS, RunConfig+from .config import BACKENDS, MODEL_VARIANTS, QUALITIES, RunConfigfrom .errors import ReshotErrorfrom .pipeline import run, run_manyfrom .reporter import StderrReporter@@ -47,7 +47,19 @@ def build_parser() -> argparse.ArgumentParser:)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(+ "--quality",+ default="auto",+ choices=QUALITIES,+ help="full = model sees 518 px (needs ~11 GB VRAM), fast = 364 px (~3 GB, 2× faster, softer fine detail); "+ "auto picks by GPU size (default)",+ )+ g.add_argument(+ "--input-size",+ type=int,+ default=None,+ help="expert: model short side in px, multiple of 14; overrides --quality",+ )g.add_argument("--checkpoint", type=Path, help="local .pth instead of the Hugging Face download")g = p.add_argument_group("output")g.add_argument(@@ -108,6 +120,7 @@ def configs_from_args(args: argparse.Namespace) -> list[RunConfig]:fps=args.fps,max_res=args.max_res,max_frames=args.max_frames,+ quality=args.quality,input_size=args.input_size,invert=args.invert,clip_percent=args.clip,diff --git a/reshot/config.py b/reshot/config.pyindex 344ec41..e0408fd 100644--- a/reshot/config.py+++ b/reshot/config.py@@ -11,6 +11,7 @@ from .errors import InputErrorfrom .targets import TARGETSMODEL_VARIANTS = ("small", "base", "large")+QUALITIES = ("auto", "full", "fast") # model working size: auto = by VRAM, full = 518, fast = 364BACKENDS = ("vda", "fake")@@ -25,7 +26,8 @@ class RunConfig:fps: float | None = None # None = preset or sourcemax_res: int = 1280 # cap on the OUTPUT's longer sidemax_frames: int | None = None- input_size: int = 518 # model short side (multiple of 14)+ quality: str = "auto" # auto | full | fast — see QUALITIES; `input_size` overrides it+ input_size: int | None = None # model short side (multiple of 14); expert override of `quality`invert: bool = Falseclip_percent: float = 0.0gamma: float = 1.0@@ -44,8 +46,10 @@ class RunConfig: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 self.quality not in QUALITIES:+ raise InputError(f"unknown --quality {self.quality!r}; choose from {', '.join(QUALITIES)}")+ if self.input_size is not None and (self.input_size < 14 or self.input_size % 14):+ raise InputError("--input-size must be a positive 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:diff --git a/reshot/pipeline.py b/reshot/pipeline.pyindex 6002758..ef145d0 100644--- a/reshot/pipeline.py+++ b/reshot/pipeline.py@@ -76,6 +76,12 @@ class RunResult:return self.depth_seconds / max(self.frames, 1) * 1000.0+def _planning_input_size(cfg: RunConfig) -> int:+ if cfg.input_size is not None:+ return cfg.input_size+ return QUALITY_INPUT_SIZE.get(cfg.quality, QUALITY_INPUT_SIZE["full"])++def plan(cfg: RunConfig) -> Plan:"""Probe the source and decide sizes and frame counts. Cheap; no decoding."""try:@@ -99,7 +105,9 @@ def plan(cfg: RunConfig) -> Plan:# from a thumbnail. The three demo takes were made from full-resolution depth# downscaled afterwards, which is what this now does.cap = cfg.max_res if cfg.max_res > 0 else 10**9- proc_max_res = processing_max_res(src_w, src_h, cfg.input_size)+ # RAM planning uses the largest size `quality` may resolve to (auto → full), so the+ # estimate is never below what a big card will actually do.+ proc_max_res = processing_max_res(src_w, src_h, _planning_input_size(cfg))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))@@ -213,7 +221,7 @@ def _run_one(cfg: RunConfig, rep: Reporter, backend, backend_name: str) -> RunRe"model",f"{backend.info.name}/{backend.info.variant} on {backend.device} ({precision}), licence {backend.info.license}",)- input_size = _fit_input_size_to_vram(cfg.input_size, backend.device, rep)+ input_size = resolve_input_size(cfg, backend.device, rep)t1 = time.time()depths = backend.infer(frames, fps, input_size=input_size)depth_seconds = time.time() - t1@@ -307,12 +315,14 @@ def extract(return backend.infer(frames, fps, input_size=input_size), fps-#: Measured 2026-09-12 on an RTX 3080 Ti (12 GB), 294 frames at 518×900: input_size 518 peaks at-#: 7.4 GiB allocated / 10.9 GiB reserved and dies with "tried to allocate 4.02 GiB" when the-#: card is capped at 8 GB; input_size 364 peaks at 2.25 / 3.0 GiB and runs with a 6 GB cap.-#: So cards below this line get 364 by default instead of an OOM traceback.-VRAM_FULL_SIZE_MIN_BYTES = int(11.5 * 2**30)-VRAM_SMALL_INPUT_SIZE = 364+#: Model working size (short side) per quality. Measured 2026-09-12 on an RTX 3080 Ti (12 GB),+#: 294 frames of 736×1280:+#: full 518 → 7.4 GiB allocated / 10.9 GiB reserved, 83 ms/frame; OOMs on an 8 GB card+#: fast 364 → 2.25 / 3.0 GiB, 34 ms/frame; runs on 6 GB+#: Against each other over the whole clip: mean |Δ| 5.3 grey levels, 95th percentile 15,+#: edge energy −4.5 % — large shapes identical, fine detail (a strand of hair) softer at 364.+QUALITY_INPUT_SIZE = {"full": 518, "fast": 364}+VRAM_FULL_SIZE_MIN_BYTES = int(11.5 * 2**30) # below this, `auto` picks fastdef _cuda_total_bytes(device: str) -> int:@@ -327,21 +337,26 @@ def _cuda_total_bytes(device: str) -> int:return 0-def _fit_input_size_to_vram(input_size: int, device: str, rep: Reporter) -> int:- """Drop the model's working size on small GPUs (see VRAM_FULL_SIZE_MIN_BYTES).+def resolve_input_size(cfg: RunConfig, device: str, rep: Reporter | None = None) -> int:+ """What the model will actually see, from `quality` / `input_size` / the GPU.- Only the default is touched: a user who passed `--input-size` explicitly above 364- on a small card asked for it and gets the OOM (and the message that comes with it).+ Precedence: an explicit `input_size` wins; then `quality` full/fast; `auto` is full on+ a card with ≥ 11.5 GB (or anything that is not CUDA) and fast below that, and says so."""+ rep = rep or NullReporter()+ if cfg.input_size is not None:+ return cfg.input_size+ if cfg.quality in QUALITY_INPUT_SIZE:+ return QUALITY_INPUT_SIZE[cfg.quality]total = _cuda_total_bytes(device)- if total and total < VRAM_FULL_SIZE_MIN_BYTES and input_size == 518:+ if total and total < VRAM_FULL_SIZE_MIN_BYTES:rep.step(- "vram",- f"{gib(total)} GPU: using --input-size {VRAM_SMALL_INPUT_SIZE} (518 needs ~11 GB; "- f"364 needs ~3 GB and is 2× faster, slightly softer depth)",+ "quality",+ f"auto → fast on a {gib(total)} GPU (full needs ~11 GB; fast ~3 GB, 2× faster, "+ f"softer fine detail). Force it with --quality full.",)- return VRAM_SMALL_INPUT_SIZE- return input_size+ return QUALITY_INPUT_SIZE["fast"]+ return QUALITY_INPUT_SIZE["full"]def _license_ok(metrics: dict) -> bool:diff --git a/tests/test_pipeline.py b/tests/test_pipeline.pyindex 43dab95..52d0fe8 100644--- a/tests/test_pipeline.py+++ b/tests/test_pipeline.py@@ -126,20 +126,28 @@ def test_cli_batch_loads_model_once_and_skips_bad_clip(tmp_path, monkeypatch):assert not (out / "missing_depth.mp4").exists()-def test_small_gpu_drops_default_input_size_but_respects_explicit(tmp_path, monkeypatch):- """An 8 GB card gets input_size 364 instead of an OOM; an explicit --input-size is kept."""+def test_quality_resolution(tmp_path, monkeypatch):+ """auto: full on a big card, fast on a small one; full/fast are the user's call regardless;+ an explicit --input-size beats everything."""import reshot.pipeline as pl+ def cfg(**kw):+ return RunConfig(input=tmp_path / "x.mp4", output=tmp_path / "y.mp4", backend="fake", **kw)+monkeypatch.setattr(pl, "_cuda_total_bytes", lambda device: 8 * 2**30)steps = []class Rep:def step(self, tag, msg):- steps.append((tag, msg))+ steps.append(tag)- assert pl._fit_input_size_to_vram(518, "cuda", Rep()) == 364- assert steps and steps[0][0] == "vram"- assert pl._fit_input_size_to_vram(518 + 14, "cuda", Rep()) == 532 # explicit, left alone+ assert pl.resolve_input_size(cfg(), "cuda", Rep()) == 364 and steps == ["quality"]+ assert pl.resolve_input_size(cfg(quality="full"), "cuda") == 518 # user insists+ assert pl.resolve_input_size(cfg(quality="fast"), "cuda") == 364+ assert pl.resolve_input_size(cfg(input_size=700), "cuda") == 700monkeypatch.setattr(pl, "_cuda_total_bytes", lambda device: 24 * 2**30)- assert pl._fit_input_size_to_vram(518, "cuda", Rep()) == 518- assert pl._fit_input_size_to_vram(518, "cpu", Rep()) == 518+ assert pl.resolve_input_size(cfg(), "cuda") == 518+ assert pl.resolve_input_size(cfg(), "cpu") == 518+ assert pl.resolve_input_size(cfg(quality="fast"), "cpu") == 364+ with pytest.raises(InputError):+ cfg(quality="ultra")