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
feat: Seedance reference-video preset; README as product copy
wangfenga00a47d27b8b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 75ad94f..0a4356c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,11 @@# Changelog+## 0.2.1 — 2026-09-11+- `--target seedance`: 24 fps, frame size a multiple of 16, ≤ 15 s, and a warning when the frame+ falls below the 407,696-pixel floor — all from the official Seedance reference-video spec.+- `Target.min_pixels` and the matching pipeline warning.+- README rewritten as a product page (Seedance first); Seedance recipe in the usage guide; demo default preset is now `seedance`.+## 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.diff --git a/README.md b/README.mdindex 9ac9a46..69c8f96 100644--- a/README.md+++ b/README.md@@ -1,122 +1,116 @@<h1 align="center">depthcat</h1><p align="center"><b>Copy the shot, not the actors.</b></p>-<p align="center">Turn a reference video into a depth blockout your video model can follow — same staging, same camera, your cast, your style.</p>-<p align="center"><img src="docs/demo.gif" width="560" alt="left: reference video, right: the depth blockout depthcat makes from it"></p>+<p align="center"><img src="docs/demo.gif" width="720" alt="a fight scene, its depth blockout, and a new fight generated from it"></p>+<p align="center"><sub>A fight scene. Its depth blockout. A new take — different fighters, same choreography, same camera.</sub></p>+<p align="center"><a href="README.zh-CN.md">中文</a> · <a href="docs/USAGE.md">User guide</a> · <a href="https://huggingface.co/spaces/maosika/depthcat">Hugging Face</a> · <a href="CHANGELOG.md">Changelog</a></p><p align="center"><a href="https://github.com/maosika-ai/depthcat/actions/workflows/ci.yml"><img src="https://github.com/maosika-ai/depthcat/actions/workflows/ci.yml/badge.svg" alt="ci"></a><a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="Apache-2.0"></a>-<img src="https://img.shields.io/badge/python-3.10%20%7C%203.12-blue" alt="python"><img src="https://img.shields.io/badge/runs%20on-CUDA%20%C2%B7%20Apple%20Silicon%20%C2%B7%20CPU-555" alt="platforms"></p>-<p align="center"><a href="README.zh-CN.md">中文</a> · <a href="docs/USAGE.md">User guide</a> · <a href="https://huggingface.co/spaces/maosika/depthcat">Hugging Face</a> · <a href="CHANGELOG.md">Changelog</a></p>----## The problem+## Every shot is two things.++Where everyone stands. How big they are. The way they move. The way the camera moves.+That's the **staging** — and it's what makes a great shot great.++Then there's who they are, what they wear, how the light falls. That's the **look**.-You found a clip with exactly the blocking you want — she walks in from the door, he-struggles in the background, the camera pushes in slowly. Now try to get that out of a-video model:+Until now you couldn't take one without the other. Describe the staging in words and the+model gives you something else every time. Hand it the footage and it takes the faces,+the wardrobe, the style — everything you didn't ask for.-- **Prompts don't do staging.** "Woman in foreground, man behind her, slow push-in" comes- out different every run.-- **Feeding the clip itself copies too much.** Faces, wardrobe, lighting and style come- along — and real-people footage gets rejected by most models' content checks.+## Keep the choreography. Change everything else.-## What depthcat does+depthcat turns a reference clip into a depth blockout: a clean, silent record of the+staging and nothing else. Near is white, far is black, every frame in step with the last.+No faces. No costumes. No style. Just the shot.-It strips the reference down to the one thing you actually wanted from it: **where things-are, how big they are, how they and the camera move** — as a near-white / far-black depth-video, the format depth ControlNets are trained on.+Give the blockout to your video model along with a prompt for the look, and you get the+reference's blocking and camera with your cast in it.```bashpip install git+https://github.com/maosika-ai/depthcat-depthcat reference.mp4 -o blockout.mp4 --target h3+depthcat reference.mp4 -o blockout.mp4 --target seedance```-```-reference.mp4 ──▶ depthcat ──▶ blockout.mp4 ──┐- ├──▶ video model (depth ControlNet) ──▶ your clip-your prompt: cast, wardrobe, lighting, style ──┘-```--Feed `blockout.mp4` to MiniMax H3 Fun ControlNet, Wan VACE or any depth-conditioned-generator, describe the *look* in the prompt, and the result keeps the reference's-staging and camera with none of its identity.--## Made for+That's the whole thing.-- **Short-drama and film teams** — reuse a shot's blocking with your own characters.-- **Ads and product video** — put the camera move of a reference spot on your product.-- **Anyone iterating on a scene** — lock staging once, change cast and style freely.+## Works with the models you already use.-## Why not …+**Seedance 2.0 and 2.5.** Add the blockout as a reference video and ask for its motion+and camera. The blockout meets the API's reference-video requirements out of the box —+24 fps, H.264, sized for the model — and because it carries no likeness, it passes the+content checks that stop real footage.-| alternative | what you give up |-|---|---|-| Depth capture inside a hosted video app | Works only in that app; nothing to script, batch, or plug into your own pipeline. |-| A single-image depth node per frame in ComfyUI | Flickers — each frame is normalised on its own. You also build fps, size and encoding yourself. |-| A hosted depth-video API | Pay per second and upload your footage. Fine for a test, not for a pipeline. |-| **depthcat** | A CLI and a Python function. Video-native model, whole-clip normalisation, generator presets, Apache-2.0 end to end. Runs on an 8 GB GPU or a Mac. |--## Details that matter+```+参考@视频1的动作与运镜。两名武者在雨夜屋顶对决,黑色劲装,冷蓝月光,电影感。+```-- **Temporal consistency from the model, not a blur.** Video Depth Anything runs 32-frame- windows with overlap and aligns them; single-image models cannot do this.-- **One normalisation for the whole clip.** Per-frame min/max makes a static wall change- brightness when someone walks toward the camera; the generator reads that as motion.-- **Inference at model resolution, output at yours.** A 12 s 720p clip needs ~4 GB of RAM,- not 8–20 GB. The RAM need is estimated before running and refused if it won't fit.-- **Frames by timestamp, size by crop, quality by CRF.** 30 → 24 fps really gives 24; frame- size is cropped to the generator's multiple, never padded; x264 CRF 12 so the control- signal has no banding.-- **Licence you can ship with.** Apache-2.0 model by default; the non-commercial variants- are opt-in and say so out loud.+**MiniMax H3 Fun ControlNet.** Use the blockout as the depth condition. 24 fps, frame size+a multiple of 32, up to 15 seconds — the preset handles it.-## Presets+**Wan VACE, and any depth ControlNet.** It's a standard near-white depth video. If your+model reads depth, it reads this.-| `--target` | fps | frame size | max | for |+| `--target` | fps | frame size | length | ||---|---|---|---|---|-| `h3` | 24 | multiple of 32 | 15 s | [MiniMax-H3-Fun-Controlnet-Union](https://huggingface.co/alibaba-pai/MiniMax-H3-Fun-Controlnet-Union) |-| `wan` | 16 | multiple of 16 | – | Wan 2.1 VACE (values from the docs, not yet verified end-to-end) |+| `seedance` | 24 | ×16, ≥ 407,696 px | ≤ 15 s | Seedance 2.0 / 2.5 reference video |+| `h3` | 24 | ×32 | ≤ 15 s | MiniMax H3 Fun ControlNet |+| `wan` | 16 | ×16 | – | Wan 2.1 VACE || `none` | source | even | – | anything |-## Measured+## Steady by design.++A blockout is only useful if the model trusts it. So depthcat is built around the details+that make a depth video hold still.-| device | precision | ms / frame | host RAM |-|---|---|---|---|-| RTX 4090, torch 2.8 cu128 | fp16 | **70** (31 with `--input-size 364`) | 4.5 GB |-| Apple M2 Max, torch 2.9.1 | fp32 | ~500 | ~4 GB |+- **It sees the whole clip.** The model works on overlapping windows of 32 frames and+ aligns them, so depth doesn't jitter from frame to frame.+- **One scale for the entire shot.** Brightness means distance, and it means the same+ distance in frame 1 and frame 300. A wall doesn't pulse because someone walked past it.+- **Nothing the model didn't ask for.** Frames are picked by timestamp, so 24 fps is+ really 24. Frame size is trimmed to the model's grid, never padded with black. The+ encode is clean enough that the depth gradient has no banding.-294 frames at 736×1280, Small model. Details and more platforms in the [user guide](docs/USAGE.md).+## Made for the pace of a studio.-## Python+A 12-second shot takes about 20 seconds on an RTX 4090 — 70 ms a frame, 31 with the+fast setting. It runs on a MacBook. It needs about 4 GB of memory for a 720p clip, and it+tells you before it starts if a clip won't fit.++Batch a folder of references in a shell loop, or call it from Python:```pythonfrom pathlib import Pathfrom depthcat import RunConfig, run-result = run(RunConfig(input=Path("reference.mp4"), output=Path("blockout.mp4"), target="h3"))-print(result.frames, result.ms_per_frame)+run(RunConfig(input=Path("reference.mp4"), output=Path("blockout.mp4"), target="seedance"))```-## Licence+## Yours to ship.-Code: Apache-2.0. Default weights: Video-Depth-Anything-**Small**, Apache-2.0-([DepthAnything/Video-Depth-Anything](https://github.com/DepthAnything/Video-Depth-Anything),-CVPR 2025; model code vendored under `depthcat/third_party/`, see [NOTICE](NOTICE)).-Base/Large weights are CC-BY-NC-4.0 and only load when asked for explicitly.+depthcat is Apache-2.0, and so is the model it runs by default — Video Depth Anything+Small, from ByteDance (CVPR 2025), vendored under `depthcat/third_party/`. Use it in a+product, a pipeline, a service. The larger research-only variants exist and are clearly+labelled; they never load unless you ask.-## Roadmap+## Get started-`--people-only` (SAM 2 silhouettes) · pose / canny / normal outputs from the same pass ·-PyPI · Docker · ComfyUI example workflow · a runnable Hugging Face Space+```bash+pip install git+https://github.com/maosika-ai/depthcat # ffmpeg on PATH+pip install "depthcat[ffmpeg] @ git+https://github.com/maosika-ai/depthcat" # or bundle one+depthcat --help+```-## Contributing+Weights (111 MB) download on first run. Behind a firewall: `export HF_ENDPOINT=https://hf-mirror.com`.-Issues and PRs welcome — [CONTRIBUTING.md](CONTRIBUTING.md). `ruff check` and `pytest`-run in CI on Ubuntu and Windows, plus the real model on CPU.+Everything else — every option, presets, recipes for each model, troubleshooting — is in+the **[user guide](docs/USAGE.md)**. Issues and pull requests are welcome; see+[CONTRIBUTING.md](CONTRIBUTING.md).-<p align="center"><sub>Built at <a href="https://www.maosika.com">Maoska 猫斯卡</a>, a studio that ships AI short drama every day.</sub></p>+<p align="center"><sub>Made by <a href="https://www.maosika.com">Maoska 猫斯卡</a>, a studio that ships AI short drama every day.</sub></p>diff --git a/README.zh-CN.md b/README.zh-CN.mdindex 11f745a..a711d77 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -1,115 +1,104 @@<h1 align="center">depthcat</h1><p align="center"><b>复制走位,不复制演员。</b></p>-<p align="center">把参考视频抽成视频模型能跟着走的深度白模——走位一样、镜头一样,人是你的,画风是你的。</p>-<p align="center"><img src="docs/demo.gif" width="560" alt="左:参考片;右:depthcat 抽出的深度白模"></p>+<p align="center"><img src="docs/demo.gif" width="720" alt="一段武打参考片、它的深度白模、用白模生成的新武打片"></p>+<p align="center"><sub>一段武打。它的深度白模。一段新片——换了人,招式和镜头一模一样。</sub></p>+<p align="center"><a href="README.md">English</a> · <a href="docs/USAGE.zh-CN.md">使用手册</a> · <a href="https://huggingface.co/spaces/maosika/depthcat">Hugging Face</a> · <a href="CHANGELOG.md">更新日志</a></p><p align="center"><a href="https://github.com/maosika-ai/depthcat/actions/workflows/ci.yml"><img src="https://github.com/maosika-ai/depthcat/actions/workflows/ci.yml/badge.svg" alt="ci"></a><a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="Apache-2.0"></a>-<img src="https://img.shields.io/badge/python-3.10%20%7C%203.12-blue" alt="python"><img src="https://img.shields.io/badge/%E8%BF%90%E8%A1%8C%E4%BA%8E-CUDA%20%C2%B7%20Apple%20Silicon%20%C2%B7%20CPU-555" alt="platforms"></p>-<p align="center"><a href="README.md">English</a> · <a href="docs/USAGE.zh-CN.md">使用手册</a> · <a href="https://huggingface.co/spaces/maosika/depthcat">Hugging Face</a> · <a href="CHANGELOG.md">更新日志</a></p>----## 你遇到的问题+## 一个镜头,其实是两件事。-你找到一段走位、运镜都对的片子——女主从门口走进来,男人在后面挣扎,镜头缓缓推近。-现在想让视频模型照这个拍:+谁站在哪。多大。怎么动。镜头怎么跟。+这是**走位**——一个好镜头之所以好,就好在这里。-- **提示词管不了走位。**"女主在前景、男人在她身后、镜头慢推",写一百遍,每次出来都不一样。-- **直接喂参考片,带走的太多。** 人脸、服装、光线、画风全跟过来;真人素材还大概率过不了模型的审核。+然后才是他们是谁、穿什么、光怎么打。这是**长相**。-这就是 LibTV「深度动作捕捉」在做的事——把参考片抽成深度白模再去生成。depthcat-把这一步做成了你自己电脑上的一条命令:开源、可商用、能进你自己的流水线。+以前这两件事分不开。用文字描述走位,模型每次给你的都不一样;把片子直接喂进去,+它把人脸、服装、画风全拿走了——你根本没要这些。-## depthcat 做什么+## 招式留下,其余全换。-把参考片剥到只剩你真正想要的那一层:**谁在哪、多大、怎么动、镜头怎么动**——-输出近白远黑的深度视频,正是深度 ControlNet 训练时吃的格式。+depthcat 把一段参考片变成深度白模:只记录走位、别的什么都没有。近处白、远处黑,+每一帧都和上一帧严丝合缝。没有脸,没有衣服,没有风格。只有这个镜头本身。++把白模交给视频模型,提示词里写你要的长相,出来的就是参考片的走位和运镜,演的是你的人。```bashpip install git+https://github.com/maosika-ai/depthcat-depthcat 参考片.mp4 -o 白模.mp4 --target h3+depthcat 参考片.mp4 -o 白模.mp4 --target seedance```-```-参考片.mp4 ──▶ depthcat ──▶ 白模.mp4 ──┐- ├──▶ 视频模型(深度 ControlNet)──▶ 你的片子-你的提示词:人物、服装、光线、画风 ─────┘-```--把 `白模.mp4` 交给 MiniMax H3 Fun ControlNet、Wan VACE 或任何带深度控制的生成模型,-提示词只写**长相**,出来的片子保留参考片的走位和镜头,不带一点它的身份。--## 给谁用+就这么多。-- **短剧、影视团队** —— 把一段好走位套到自己的角色身上。-- **广告、产品视频** —— 把参考广告的运镜放到自己的产品上。-- **反复打磨一个场景的人** —— 走位锁一次,人物和画风随便换。+## 你在用的模型,它都接得上。-## 为什么不用别的+**Seedance 2.0 和 2.5。** 把白模当参考视频传进去,让它参考动作和运镜。+白模出厂就符合官方参考视频的要求——24 fps、H.264、尺寸合规——而且因为它不含任何真人特征,+真人素材过不了的审核,它能过。-| 替代方案 | 你要放弃什么 |-|---|---|-| 某个视频 App 里的深度捕捉 | 只能在那个 App 里用;没法写脚本、批处理、接进自己的流水线。 |-| ComfyUI 里逐帧跑单图深度节点 | 会闪——每帧各自归一化。fps、尺寸、编码还得自己搭。 |-| 托管的深度视频 API | 按秒收费,素材要传到别人服务器。测一下行,当流水线不行。 |-| **depthcat** | 一条命令、一个 Python 函数。视频原生模型、整段归一化、生成模型预设、端到端 Apache-2.0。8 GB 显卡或 Mac 就能跑。 |--## 决定成败的细节+```+参考@视频1的动作与运镜。两名武者在雨夜屋顶对决,黑色劲装,冷蓝月光,电影感。+```-- **时序一致性来自模型,不是靠模糊。** Video Depth Anything 用 32 帧窗口重叠推理并对齐;单图模型做不到。-- **整段视频只归一化一次。** 逐帧 min/max 会让静止的墙在有人走近镜头时忽明忽暗,生成模型把它读成运动。-- **按模型分辨率推理,按你要的尺寸输出。** 12 秒 720p 只要约 4 GB 内存,不是 8–20 GB。跑之前先估算,放不下就拒绝。-- **帧按时间戳选、尺寸靠裁、质量靠 CRF。** 30→24 fps 真的是 24;尺寸裁到生成模型要的倍数、绝不补边;x264 CRF 12,控制信号没有色带。-- **能随产品一起发的许可。** 默认 Apache-2.0 权重;非商用的变体要显式指定,运行时会明说。+**MiniMax H3 Fun ControlNet。** 白模作为 depth 条件。24 fps、边长 32 的倍数、最长 15 秒,预设都替你算好了。-## 预设+**Wan VACE 和任何深度 ControlNet。** 它就是标准的近白远黑深度视频。模型认深度,就认它。-| `--target` | fps | 尺寸 | 上限 | 对应 |+| `--target` | fps | 尺寸 | 时长 | ||---|---|---|---|---|-| `h3` | 24 | 32 的倍数 | 15 秒 | [MiniMax-H3-Fun-Controlnet-Union](https://huggingface.co/alibaba-pai/MiniMax-H3-Fun-Controlnet-Union) |-| `wan` | 16 | 16 的倍数 | – | Wan 2.1 VACE(按文档取值,尚未端到端实测) |+| `seedance` | 24 | 16 的倍数,≥ 407,696 像素 | ≤ 15 秒 | Seedance 2.0 / 2.5 参考视频 |+| `h3` | 24 | 32 的倍数 | ≤ 15 秒 | MiniMax H3 Fun ControlNet |+| `wan` | 16 | 16 的倍数 | – | Wan 2.1 VACE || `none` | 原片 | 偶数 | – | 通用 |-## 实测+## 稳,是设计出来的。-| 设备 | 精度 | ms / 帧 | 宿主内存 |-|---|---|---|---|-| RTX 4090,torch 2.8 cu128 | fp16 | **70**(`--input-size 364` 时 31) | 4.5 GB |-| Apple M2 Max,torch 2.9.1 | fp32 | 约 500 | 约 4 GB |+白模只有让模型信得过才有用。所以 depthcat 围绕"深度视频怎么才能不抖"来做。-294 帧 @ 736×1280,Small 模型。更多平台与细节见[使用手册](docs/USAGE.zh-CN.md)。+- **它看的是整段片子。** 模型以 32 帧为一个窗口重叠推理并对齐,深度不会一帧一帧地跳。+- **整个镜头只用一把尺子。** 亮度就是距离,第 1 帧和第 300 帧里同样的亮度是同样的距离。+ 有人从墙前走过,墙不会跟着呼吸。+- **不给模型任何它没要的东西。** 帧按时间戳选,24 fps 就是 24;尺寸裁到模型的网格上,绝不补黑边;+ 编码干净到深度渐变没有色带。-安装时国内请先 `export HF_ENDPOINT=https://hf-mirror.com`,权重 111 MB。+## 跟得上一个工作室的节奏。-## Python+12 秒的镜头,RTX 4090 上约 20 秒——每帧 70 毫秒,快速档 31 毫秒。MacBook 也能跑。+720p 一段片约 4 GB 内存,放不下会在开始之前告诉你。++一个 shell 循环批量处理整个文件夹,或者从 Python 里调:```pythonfrom pathlib import Pathfrom depthcat import RunConfig, run-result = run(RunConfig(input=Path("参考片.mp4"), output=Path("白模.mp4"), target="h3"))-print(result.frames, result.ms_per_frame)+run(RunConfig(input=Path("参考片.mp4"), output=Path("白模.mp4"), target="seedance"))```-## 许可+## 放心用在产品里。-代码 Apache-2.0。默认权重 Video-Depth-Anything-**Small**,Apache-2.0-([DepthAnything/Video-Depth-Anything](https://github.com/DepthAnything/Video-Depth-Anything),-CVPR 2025;模型代码 vendored 在 `depthcat/third_party/`,见 [NOTICE](NOTICE))。-Base/Large 权重是 CC-BY-NC-4.0,只在显式指定时加载。+depthcat 是 Apache-2.0,它默认用的模型也是——字节跳动的 Video Depth Anything Small(CVPR 2025),+vendored 在 `depthcat/third_party/`。用在产品、流水线、服务里都行。更大的研究用变体也在,+标得清清楚楚,不主动指定就不会加载。-## 路线图+## 开始-`--people-only`(SAM 2 人物剪影)· 同一遍推理顺带出骨架 / 边缘 / 法线 ·-PyPI · Docker · ComfyUI 示例工作流 · 可在线运行的 Hugging Face Space+```bash+pip install git+https://github.com/maosika-ai/depthcat # 自己有 ffmpeg+pip install "depthcat[ffmpeg] @ git+https://github.com/maosika-ai/depthcat" # 或者自带一个+depthcat --help+```-## 参与+权重 111 MB,首次运行自动下载。国内:`export HF_ENDPOINT=https://hf-mirror.com`。-欢迎 issue 和 PR —— [CONTRIBUTING.md](CONTRIBUTING.md)。CI 在 Ubuntu 和 Windows 上跑 `ruff check` 和 `pytest`,外加 CPU 真模型。+其余的——全部参数、预设、每个模型的接法、排错——都在**[使用手册](docs/USAGE.zh-CN.md)**。+欢迎 issue 和 PR,见 [CONTRIBUTING.md](CONTRIBUTING.md)。<p align="center"><sub>出品:<a href="https://www.maosika.com">猫斯卡</a>,每天都在出 AI 短剧的工作室。</sub></p>diff --git a/demo/app.py b/demo/app.pyindex 300b58f..fd7b6e6 100644--- a/demo/app.py+++ b/demo/app.py@@ -25,7 +25,7 @@ def make_blockout(video: str | None, target: str, input_size: int, invert: bool,raise gr.Error("Upload a video first.")workdir = Path(tempfile.mkdtemp(prefix="depthcat-"))out = workdir / "blockout.mp4"- fps_cap = {"none": 24.0, "h3": None, "wan": None}[target] # keep the free CPU honest+ fps_cap = {"none": 24.0, "seedance": None, "h3": None, "wan": None}[target] # keep the free CPU honestmax_frames = int(LIMITS["max_seconds"] * 24)cfg = RunConfig(input=Path(video),@@ -56,7 +56,7 @@ with gr.Blocks(title="depthcat") as demo:gr.Markdown(f"""# depthcat-**Video → depth blockout** for video-generation ControlNets (MiniMax H3 Fun, Wan VACE, …).+**Video → depth blockout** for video generation: Seedance reference video, MiniMax H3 Fun ControlNet, Wan VACE, ….Keeps a shot's staging and camera, drops faces, wardrobe and style.Code and CLI: [github.com/maosika-ai/depthcat](https://github.com/maosika-ai/depthcat) · Apache-2.0@@ -68,10 +68,10 @@ Expect 1–3 minutes. For full clips and GPU speed, run it locally: `pip installwith gr.Column():src = gr.Video(label="Reference video", sources=["upload"])target = gr.Radio(- ["h3", "none", "wan"],- value="h3",+ ["seedance", "h3", "wan", "none"],+ value="seedance",label="Target preset",- info="h3 = 24 fps, ×32 (MiniMax H3 Fun ControlNet)",+ info="seedance = 24 fps, ×16 (Seedance 2.0/2.5 reference video); h3 = 24 fps, ×32 (MiniMax H3 Fun ControlNet)",)with gr.Accordion("Advanced", open=False):input_size = gr.Radio(diff --git a/depthcat/_version.py b/depthcat/_version.pyindex d3ec452..3ced358 100644--- a/depthcat/_version.py+++ b/depthcat/_version.py@@ -1 +1 @@-__version__ = "0.2.0"+__version__ = "0.2.1"diff --git a/depthcat/pipeline.py b/depthcat/pipeline.pyindex 356d095..3ebbda4 100644--- a/depthcat/pipeline.py+++ b/depthcat/pipeline.py@@ -179,6 +179,9 @@ def run(cfg: RunConfig, reporter: Reporter | None = None) -> RunResult:del depthsif (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})")+ if target.min_pixels and p.out_w * p.out_h < target.min_pixels:+ rep.step("warn", f"{p.out_w}x{p.out_h} is below {target.key}'s minimum of {target.min_pixels:,} pixels "+ "— the API will reject it; use a larger source or raise --max-res")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))diff --git a/depthcat/targets.py b/depthcat/targets.pyindex badfdfa..bc9271a 100644--- a/depthcat/targets.py+++ b/depthcat/targets.py@@ -19,10 +19,17 @@ class Target:multiple: int # frame size rounded down to a multiple of thismax_seconds: float | None # warn beyond thisnote: str+ min_pixels: int = 0 # warn below this many output pixels (w*h)TARGETS: dict[str, Target] = {"none": Target("none", None, 2, None, "keep source fps; only make dimensions even"),+ # Seedance 2.0 / 2.5 (Volcengine Ark "创建视频生成任务" API, reference_video role), from+ # the official parameter page: mp4 H.264, fps 24–60, per-clip 2–15 s on 2.0 (2–30 s on+ # 2.5), aspect 0.4–2.5, side 300–6000 px, total pixels ≥ 407,696, file ≤ 200 MB.+ # The blockout goes in as @视频N and the prompt asks for its motion and camera.+ "seedance": Target("seedance", 24.0, 16, 15.0,+ "Seedance 2.0/2.5 reference video (@视频N: motion + camera)", min_pixels=407_696),# MiniMax-H3-Fun-Controlnet-Union: 24 fps fixed, H/W multiples of 32, ≤15 s."h3": Target("h3", 24.0, 32, 15.0, "MiniMax H3 Fun ControlNet (depth/pose/canny/hed/mlsd)"),# Wan 2.1 VACE control videos: 16 fps, H/W multiples of 16.diff --git a/docs/USAGE.md b/docs/USAGE.mdindex 39d6333..8b42620 100644--- a/docs/USAGE.md+++ b/docs/USAGE.md@@ -48,7 +48,7 @@ depthcat INPUT -o OUTPUT [options]| option | default | notes ||---|---|---|-| `--target none\|h3\|wan` | `none` | fps + frame-size preset, see [Targets](#targets). |+| `--target none\|seedance\|h3\|wan` | `none` | fps + frame-size preset, see [Targets](#targets). || `--fps N` | preset or source | Frames are chosen by timestamp, so 30 → 24 yields 24, not 30. Never upsamples. || `--max-res N` | `1280` | Cap on the output's longer side. Inference always runs at model resolution regardless. || `--max-frames N` | all | Stop after N source frames. |@@ -81,6 +81,7 @@ depthcat INPUT -o OUTPUT [options]| `--target` | fps | frame size | max length | notes ||---|---|---|---|---|| `none` | source | even | – | |+| `seedance` | 24 | multiple of 16 (centre crop), ≥ 407,696 px (warns) | 15 s (warns) | Seedance 2.0 / 2.5 reference video (`@视频N` motion + camera) || `h3` | 24 | multiple of 32 (centre crop) | 15 s (warns) | MiniMax-H3-Fun-Controlnet-Union depth input || `wan` | 16 | multiple of 16 | – | Wan 2.1 VACE control video; values from the docs, not yet verified end-to-end |@@ -116,6 +117,30 @@ model — handy for testing your own integration in milliseconds.## Recipes+### Seedance 2.0 / 2.5 (reference video)++1. `depthcat ref.mp4 -o ref_depth.mp4 --target seedance` (24 fps, ×16, ≤ 15 s).+2. Submit it as a **reference video** (API: `role: "reference_video"`; in the console, attach it as+ a video reference) and address it in the prompt as `@视频1`, asking for its motion and camera:++ ```+ 参考@视频1的动作与运镜。两名武者在雨夜屋顶对决,黑色劲装,冷蓝月光,电影感。+ ```++ Describe only the *look* — cast, wardrobe, lighting, style. Staging comes from the video.+3. What the official reference-video spec asks for, and what the preset does about it:++ | official requirement | preset |+ |---|---|+ | mp4 / mov, H.264 or H.265 | H.264 mp4, yuv420p |+ | 24 – 60 fps | 24 fps |+ | 2.0: 2 – 15 s per clip, ≤ 15 s total · 2.5: 2 – 30 s per clip, ≤ 30 s total | warns above 15 s |+ | width × height ≥ 407,696 px, each side 300 – 6,000 px, aspect 0.4 – 2.5 | warns below the pixel floor — raise `--max-res` or use a larger source |+ | ≤ 200 MB | CRF 12 keeps a 15 s 1080p clip well under |++ Seedance 2.5 allows up to 30 s; pass `--fps 24` without `--target` and check the size yourself+ if you need the longer window.+### MiniMax H3 Fun ControlNet (ComfyUI)1. `depthcat ref.mp4 -o ref_depth.mp4 --target h3` (24 fps, ×32, ≤ 15 s).diff --git a/docs/USAGE.zh-CN.md b/docs/USAGE.zh-CN.mdindex 5b39bfd..de6c351 100644--- a/docs/USAGE.zh-CN.md+++ b/docs/USAGE.zh-CN.md@@ -47,7 +47,7 @@ depthcat 输入 -o 输出 [选项]| 选项 | 默认 | 说明 ||---|---|---|-| `--target none\|h3\|wan` | `none` | fps + 尺寸预设,见[目标预设](#目标预设)。 |+| `--target none\|seedance\|h3\|wan` | `none` | fps + 尺寸预设,见[目标预设](#目标预设)。 || `--fps N` | 预设或原片 | 按**时间戳**选帧,30→24 真的是 24。绝不向上插帧。 || `--max-res N` | `1280` | 输出长边上限。推理永远在模型分辨率进行,与此无关。 || `--max-frames N` | 全部 | 只处理前 N 帧。 |@@ -80,6 +80,7 @@ depthcat 输入 -o 输出 [选项]| `--target` | fps | 尺寸 | 时长上限 | 说明 ||---|---|---|---|---|| `none` | 原片 | 偶数 | – | |+| `seedance` | 24 | 16 的倍数(居中裁),≥ 407,696 像素(不够警告) | 15 秒(超了警告) | Seedance 2.0 / 2.5 参考视频(`@视频N` 继承动作与运镜) || `h3` | 24 | 32 的倍数(居中裁) | 15 秒(超了警告) | MiniMax-H3-Fun-Controlnet-Union 深度输入 || `wan` | 16 | 16 的倍数 | – | Wan 2.1 VACE 控制视频;按文档取值,尚未端到端实测 |@@ -113,6 +114,29 @@ write_gray_video(upsample_frames(gray, 1280, 736), "out.mp4", fps, size=(1280, 7## 实战配方+### Seedance 2.0 / 2.5(参考视频)++1. `depthcat 参考.mp4 -o 参考_depth.mp4 --target seedance`(24 fps、16 倍数、≤15 秒)。+2. 作为**参考视频**提交(API 里 `role: "reference_video"`;控制台里当视频参考挂上),+ 提示词用 `@视频1` 指向它,要它的动作与运镜:++ ```+ 参考@视频1的动作与运镜。两名武者在雨夜屋顶对决,黑色劲装,冷蓝月光,电影感。+ ```++ 提示词只写**长相**——人物、服装、光线、画风。走位和镜头由视频决定。+3. 官方对参考视频的要求,以及预设替你做了什么:++ | 官方要求 | 预设 |+ |---|---|+ | mp4 / mov,H.264 或 H.265 | H.264 mp4,yuv420p |+ | 24 – 60 fps | 24 fps |+ | 2.0:单段 2 – 15 秒、总计 ≤ 15 秒 · 2.5:单段 2 – 30 秒、总计 ≤ 30 秒 | 超 15 秒警告 |+ | 宽×高 ≥ 407,696 像素,单边 300 – 6,000,宽高比 0.4 – 2.5 | 低于像素下限警告——调大 `--max-res` 或换更大的原片 |+ | ≤ 200 MB | CRF 12 下 15 秒 1080p 远小于此 |++ Seedance 2.5 允许到 30 秒:需要更长时不加 `--target`、只传 `--fps 24`,尺寸自己核一下。+### MiniMax H3 Fun ControlNet(ComfyUI)1. `depthcat 参考.mp4 -o 参考_depth.mp4 --target h3`(24 fps、32 倍数、≤15 秒)。diff --git a/tests/test_postprocess.py b/tests/test_postprocess.pyindex 629960e..9cd674c 100644--- a/tests/test_postprocess.py+++ b/tests/test_postprocess.py@@ -60,3 +60,8 @@ def test_center_crop_is_centred():def test_h3_preset_matches_published_constraints():t = TARGETS["h3"]assert (t.fps, t.multiple, t.max_seconds) == (24.0, 32, 15.0)+++def test_seedance_preset():+ t = TARGETS["seedance"]+ assert (t.fps, t.multiple, t.max_seconds, t.min_pixels) == (24.0, 16, 15.0, 407_696)