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.

feat: Seedance reference-video preset; README as product copy

wangfenga00a47d27b8b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.md
index 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.
```bash
pip 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:
```python
from pathlib import Path
from 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.md
index 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 把一段参考片变成深度白模:只记录走位、别的什么都没有。近处白、远处黑,
+每一帧都和上一帧严丝合缝。没有脸,没有衣服,没有风格。只有这个镜头本身。
+
+把白模交给视频模型,提示词里写你要的长相,出来的就是参考片的走位和运镜,演的是你的人。
```bash
pip 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 里调:
```python
from pathlib import Path
from 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.py
index 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 honest
max_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 install
with 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.py
index 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.py
index 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 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})")
+ 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.py
index 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 this
max_seconds: float | None # warn beyond this
note: 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.md
index 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.md
index 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.py
index 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)