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
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.mdindex 23d208f..b0e545f 100644--- a/README.md+++ b/README.md@@ -43,6 +43,18 @@ pip install reshot # needs ffmpeg on PATHNo 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```bashdiff --git a/README.zh-CN.md b/README.zh-CN.mdindex 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. 抽深度图```bashdiff --git a/demo/space/index.html b/demo/space/index.htmlindex 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><Video 1></code>, a character sheet as <code><Picture 1></code>; define <code><Video 1></code> as "the fight choreography and camera movement shown in <Video 1>, 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 挂成 <Video 1>、定妆图挂 <Picture 1>,明说灰色外观不要抄。三段片的完整提示词在 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.mdnew file mode 100644index 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.