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.

docs: AGENT_INSTALL.md — step-by-step guide for AI coding agents, plus a copy-paste prompt in the READMEs

wangfeng10a1efbcea46
diff --git a/README.md b/README.md
index 23d208f..b0e545f 100644
--- a/README.md
+++ b/README.md
@@ -43,6 +43,18 @@ pip install reshot # needs ffmpeg on PATH
No ffmpeg? `pip install "reshot[ffmpeg]"` bundles one. No Python set up at all? [uv](https://docs.astral.sh/uv/) does everything in one line: `uvx --from "reshot[ffmpeg]" reshot reference.mp4 -o depth.mp4 --target seedance`. The model weights (111 MB) download on first run.
+### Or let your AI coding tool do it
+
+Using Claude Code, Codex, Cursor or any other AI agent? Paste this and it will install, verify the GPU, and run a test clip for you:
+
+```
+Install ReShot (the "reshot" package on PyPI) on this machine and get it working.
+Read https://raw.githubusercontent.com/maosika-ai/reshot/main/docs/AGENT_INSTALL.md and follow it step by step:
+detect the OS and GPU, install the right PyTorch build first, then `pip install "reshot[ffmpeg]"`,
+set HF_ENDPOINT=https://hf-mirror.com if I'm in China, run the fake-backend smoke test, then a real run
+on a short clip with --metrics and show me the numbers. Don't say it's done until depth.mp4 exists.
+```
+
### 2. Make the depth map
```bash
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 053d101..c43d91a 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -43,6 +43,18 @@ pip install reshot # 需要 PATH 里有 ffmpeg
没有 ffmpeg 就装 `pip install "reshot[ffmpeg]"`,自带一个。连 Python 都没配?用 [uv](https://docs.astral.sh/uv/) 一行搞定:`uvx --from "reshot[ffmpeg]" reshot 参考片.mp4 -o 深度图.mp4 --target seedance`。模型权重 111 MB,首次运行自动下载;国内先 `export HF_ENDPOINT=https://hf-mirror.com`。
+### 或者让你的 AI 编程工具来装
+
+用 Claude Code、Codex、Cursor 之类的 AI 工具?把下面这段粘给它,它会替你装好、验显卡、跑一段测试片:
+
+```
+在这台机器上安装 ReShot(PyPI 上的 "reshot" 包)并跑通。
+先读 https://raw.githubusercontent.com/maosika-ai/reshot/main/docs/AGENT_INSTALL.md,按它一步步做:
+识别系统和显卡,先装对应的 PyTorch,再 pip install "reshot[ffmpeg]";
+我在中国大陆,先设 HF_ENDPOINT=https://hf-mirror.com;跑一次假后端冒烟测试,再用一段短片真跑一次并加 --metrics,把数字给我看。
+depth.mp4 没生成出来之前不要说完成。
+```
+
### 2. 抽深度图
```bash
diff --git a/demo/space/index.html b/demo/space/index.html
index 36a69ea..c3dc3ea 100644
--- a/demo/space/index.html
+++ b/demo/space/index.html
@@ -55,7 +55,7 @@ reshot reference.mp4 -o depth.mp4 --target seedance</code></pre>
<h2>How to use it <span class="zh">/ 怎么用</span></h2>
<table>
-<tr><td><b>1</b></td><td><code>pip install reshot</code><br><span class="zh">装</span></td></tr>
+<tr><td><b>1</b></td><td><code>pip install reshot</code> — or paste into Claude Code / Codex: <i>"Install reshot from PyPI following https://raw.githubusercontent.com/maosika-ai/reshot/main/docs/AGENT_INSTALL.md and run a test clip"</i>. ComfyUI: install <a href="https://github.com/maosika-ai/ComfyUI-ReShot">ComfyUI-ReShot</a>.<br><span class="zh">装;或者把这句粘给 Claude Code / Codex 让它装;ComfyUI 用户装节点包</span></td></tr>
<tr><td><b>2</b></td><td><code>reshot reference.mp4 -o depth.mp4 --target seedance</code> — 24 fps, H.264, the Seedance reference-video spec out of the box; <code>--target h3</code> for MiniMax H3.<br><span class="zh">抽深度图;<code>--target seedance</code> 直接按 Seedance 参考视频规格出片</span></td></tr>
<tr><td><b>3</b></td><td><b>Seedance 2.0 / 2.5:</b> upload <code>depth.mp4</code> as a reference video and prompt <code>参考@视频1的动作与运镜,顺序与视频保持一致。</code> + the people and the look.<br><b>MiniMax H3:</b> attach it as <code>&lt;Video 1&gt;</code>, a character sheet as <code>&lt;Picture 1&gt;</code>; define <code>&lt;Video 1&gt;</code> as "the fight choreography and camera movement shown in &lt;Video 1&gt;, a grey depth map…" and state that "its grey depth look is not transferred". The full prompts for the three takes are in <a href="https://github.com/maosika-ai/reshot/tree/main/docs/prompts">docs/prompts</a>.<br><span class="zh">交给模型:Seedance 当参考视频上传并写「参考@视频1的动作与运镜」;MiniMax H3 挂成 &lt;Video 1&gt;、定妆图挂 &lt;Picture 1&gt;,明说灰色外观不要抄。三段片的完整提示词在 docs/prompts。</span></td></tr>
<tr><td><b>4</b></td><td>Same six shots, same camera, your cast — the three takes above. Tips that made them work: keep the reference under 15 s; for MiniMax H3 shrink the depth map (<code>--max-res 320</code>) so the grey silhouette doesn't pull the face shape; keep the size ratio between characters as the depth map has it.<br><span class="zh">出片。几条经验:参考片 15 秒以内;给 MiniMax H3 的深度图缩到 320(不然灰影会带脸型);角色体量比例别跟深度图打架。</span></td></tr>
diff --git a/docs/AGENT_INSTALL.md b/docs/AGENT_INSTALL.md
new file mode 100644
index 0000000..4452387
--- /dev/null
+++ b/docs/AGENT_INSTALL.md
@@ -0,0 +1,114 @@
+# ReShot — installation guide for AI coding agents
+
+You are an AI coding agent (Claude Code, Codex, Cursor, Gemini CLI, …) and a user asked you to
+set up **ReShot** on their machine. This page is written for you. Follow it top to bottom, verify
+every step with a command, and report what you found — do not tell the user "done" until step 6
+has produced a depth video.
+
+ReShot is a Python command-line tool: `reshot reference.mp4 -o depth.mp4 --target seedance`
+turns a video into a depth-map video for Seedance / MiniMax H3 / Wan. Package on PyPI: `reshot`.
+Source and full docs: https://github.com/maosika-ai/reshot
+
+## 1. Find out what the machine is
+
+Run and record:
+
+```bash
+python3 --version || python --version # need 3.10–3.12
+nvidia-smi --query-gpu=name,memory.total --format=csv,noheader 2>/dev/null || echo "no nvidia gpu"
+uname -a 2>/dev/null || ver
+ffmpeg -version 2>/dev/null | head -1 || echo "no ffmpeg"
+```
+
+Decide:
+- **GPU**: NVIDIA with ≥ 8 GB → CUDA. Apple Silicon → MPS (built into the macOS torch wheel). Otherwise CPU (works, ~1 s/frame).
+- **ffmpeg**: if missing, install the extra `reshot[ffmpeg]` (bundles a binary) instead of asking the user to install ffmpeg.
+- **Region**: if the user is in mainland China (ask if unsure), Hugging Face is unreachable — use the mirror in step 4.
+
+## 2. Install PyTorch for that hardware first
+
+`pip install reshot` pulls a generic `torch`, which on Linux/Windows may be the CPU-only build. Install the right torch **before** reshot:
+
+- NVIDIA (Linux/Windows): pick the CUDA build for the driver — `nvidia-smi` prints the max CUDA version top right. For CUDA 12.x:
+ `pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124`
+- macOS (Apple Silicon or Intel): `pip install torch torchvision`
+- CPU only: `pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu`
+
+Prefer a virtual environment (`python3 -m venv .venv && source .venv/bin/activate`, on Windows `.venv\Scripts\activate`) unless the user says otherwise. If `uv` is installed, `uv venv && uv pip install …` is fine too.
+
+## 3. Install ReShot
+
+```bash
+pip install "reshot[ffmpeg]" # or just: pip install reshot (when ffmpeg is on PATH)
+reshot --version # prints e.g. "reshot 0.3.7"
+```
+
+Verify torch sees the GPU:
+
+```bash
+python -c "import torch; print(torch.__version__, 'cuda' if torch.cuda.is_available() else ('mps' if torch.backends.mps.is_available() else 'cpu'))"
+```
+
+If it prints `cpu` on a machine with an NVIDIA card, step 2 installed the wrong build — reinstall torch with the CUDA index URL.
+
+## 4. Model weights (111 MB, once)
+
+They download from Hugging Face on the first real run into `~/.cache/huggingface/hub/`.
+In mainland China set the mirror in the same shell first:
+
+```bash
+export HF_ENDPOINT=https://hf-mirror.com # Windows PowerShell: $env:HF_ENDPOINT="https://hf-mirror.com"
+```
+
+Offline machine: fetch `video_depth_anything_vits.pth` from
+`https://huggingface.co/depth-anything/Video-Depth-Anything-Small` elsewhere and pass
+`--checkpoint /path/to/video_depth_anything_vits.pth`.
+
+## 5. Smoke test without the model (seconds, no download)
+
+```bash
+RESHOT_FAKE_BACKEND=1 reshot <any short .mp4> -o /tmp/reshot_smoke.mp4 --max-frames 8 --target seedance
+```
+
+(Windows PowerShell: `$env:RESHOT_FAKE_BACKEND=1; reshot …`.) This exercises decoding, presets and
+encoding with a fake depth model. It must print a `wrote` line. If it fails, the problem is ffmpeg
+or the input file, not the model.
+
+## 6. Real run
+
+Ask the user for a reference clip (or use one of theirs), keep it ≤ 15 s, then:
+
+```bash
+reshot reference.mp4 -o depth.mp4 --target seedance --metrics run.json
+```
+
+Read `run.json` back and report to the user: `device`, `precision`, `ms_per_frame`,
+`model_input_resolution`, `gpu_peak_reserved_bytes` (if CUDA), `output_size`. Open or describe
+`depth.mp4`: it must be grey, near objects white, far objects black.
+
+Defaults are right for almost everyone: `--quality fast` (the model works at 644×364 for 16:9,
+~3 GB VRAM). Only suggest `--quality full` (924×518, ~11 GB VRAM) if the card has ≥ 12 GB and the
+user cares about fine silhouettes.
+
+## 7. What to tell the user at the end
+
+- The exact command that worked on their machine, ready to reuse.
+- Where the depth video is, and that they upload it to Seedance as a *reference video* with a
+ prompt like `参考@视频1的动作与运镜,顺序与视频保持一致。` + their own description of people and look —
+ or attach it as `<Video 1>` for MiniMax H3 (see the README's step 3 for the prompt lines that matter).
+- For MiniMax H3 reference videos add `--target h3 --max-res 320`.
+- Batch: `reshot clips/*.mp4 -o depth/ --target seedance` runs a folder on one model load.
+- ComfyUI users: install the node pack https://github.com/maosika-ai/ComfyUI-ReShot instead of the CLI.
+
+## Common failures
+
+| symptom | fix |
+|---|---|
+| `ffmpeg not found` | `pip install "reshot[ffmpeg]"` |
+| `could not obtain weights` / download hangs | `HF_ENDPOINT=https://hf-mirror.com`, or `--checkpoint` with a local file |
+| `CUDA out of memory … 4.02 GiB` | the user passed `--quality full` on a < 12 GB card; use the default |
+| `RamBudgetError … use --max-frames N` | clip too long for the machine's RAM; trim, or `--max-frames N` as suggested, or `--force` |
+| runs on `cpu` although there is an NVIDIA card | wrong torch build; reinstall torch from the CUDA index URL |
+| `torch` build too old | reshot needs torch ≥ 2.1 |
+
+Made by Maosika 猫斯卡 (https://www.maosika.com), the AI short-drama production system.