Skip to content

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.

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.md
index 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 at
diff --git a/README.md b/README.md
index 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.
## Presets
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 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.txt
index 4caf100..549442d 100644
--- a/demo/requirements.txt
+++ b/demo/requirements.txt
@@ -1,5 +1,5 @@
--extra-index-url https://download.pytorch.org/whl/cpu
torch
torchvision
-reshot[ffmpeg] @ git+https://github.com/maosika-ai/[email protected]
+reshot[ffmpeg] @ git+https://github.com/maosika-ai/[email protected]
gradio>=4.0
diff --git a/demo/space/index.html b/demo/space/index.html
index 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.md
index 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. |
### Output
diff --git a/docs/USAGE.zh-CN.md b/docs/USAGE.zh-CN.md
index 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__.py
index 40c3f23..39bc9ca 100644
--- a/reshot/__init__.py
+++ b/reshot/__init__.py
@@ -23,7 +23,7 @@ from ._version import __version__
from .config import RunConfig
from .errors import BackendError, InputError, RamBudgetError, ReshotError, ToolMissingError
from .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_many
from .planning import memory_verdict, processing_max_res
from .postprocess import to_gray, upsample_frames
from .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.py
index 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.py
index 20be998..954f0ff 100644
--- a/reshot/cli.py
+++ b/reshot/cli.py
@@ -21,7 +21,7 @@ import sys
from pathlib import Path
from ._version import __version__
-from .config import BACKENDS, MODEL_VARIANTS, RunConfig
+from .config import BACKENDS, MODEL_VARIANTS, QUALITIES, RunConfig
from .errors import ReshotError
from .pipeline import run, run_many
from .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.py
index 344ec41..e0408fd 100644
--- a/reshot/config.py
+++ b/reshot/config.py
@@ -11,6 +11,7 @@ from .errors import InputError
from .targets import TARGETS
MODEL_VARIANTS = ("small", "base", "large")
+QUALITIES = ("auto", "full", "fast") # model working size: auto = by VRAM, full = 518, fast = 364
BACKENDS = ("vda", "fake")
@@ -25,7 +26,8 @@ class RunConfig:
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)
+ 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 = False
clip_percent: float = 0.0
gamma: 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.py
index 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 fast
def _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.py
index 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") == 700
monkeypatch.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")