cutmap 0.1.1__tar.gz → 0.2.0__tar.gz

{cutmap-0.1.1 → cutmap-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cutmap
-Version: 0.1.1
+Version: 0.2.0
 Summary: Turn any video into a browsable, searchable storyboard — and auto-extract its B-roll. Local ffmpeg + perceptual hashing, no LLM.
 Project-URL: Homepage, https://github.com/xykong36/cutmap
 Project-URL: Issues, https://github.com/xykong36/cutmap/issues
@@ -52,10 +52,11 @@ Description-Content-Type: text/markdown
 
 # cutmap
 
-**Turn any video into a browsable, searchable storyboard — and auto-extract its B-roll.**
+**Read a video like a document.**
+Skim a long video in minutes to learn fast — or study it frame-by-frame to see exactly how it's cut.
 
-[![简体中文](https://img.shields.io/badge/lang-简体中文-lightgrey?style=flat-square)](https://github.com/xykong36/cutmap/blob/main/README.md)
-[![English](https://img.shields.io/badge/lang-English-2b7489?style=flat-square)](https://github.com/xykong36/cutmap/blob/main/README.en.md)
+[![English](https://img.shields.io/badge/lang-English-2b7489?style=flat-square)](https://github.com/xykong36/cutmap/blob/main/README.md)
+[![简体中文](https://img.shields.io/badge/lang-简体中文-lightgrey?style=flat-square)](https://github.com/xykong36/cutmap/blob/main/README.zh-CN.md)
 [![PyPI](https://img.shields.io/pypi/v/cutmap?style=flat-square&color=3775a9)](https://pypi.org/project/cutmap/)
 [![CI](https://github.com/xykong36/cutmap/actions/workflows/ci.yml/badge.svg)](https://github.com/xykong36/cutmap/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/xykong36/cutmap/blob/main/LICENSE)
@@ -64,27 +65,113 @@ Description-Content-Type: text/markdown
 
 </div>
 
-Give it a video and a subtitle file. Get back a single HTML page: the source player on
-the left, every distinct frame on the right, each captioned with what was being said.
-Click any frame to jump the player to that moment. Search the subtitles to locate a shot.
+Watching a video is slow and linear — you can't skim it the way you skim an article,
+and you can't Ctrl-F a moment. cutmap fixes that. Give it a video (and subtitles if you
+have them) and it builds a single HTML page you can actually **read**: every visually
+distinct frame laid out in order, each captioned with what was being said. Click a frame
+to jump the player there; search the subtitles to find a moment.
+
+![storyboard](https://raw.githubusercontent.com/xykong36/cutmap/main/examples/storyboard.png)
+
+<sub>Demo footage: [@林亦LYi](https://www.youtube.com/@lyi) — [《一个视频搞懂 DeepSeek V4！》](https://www.youtube.com/watch?v=WDQjRzVcX-A), all rights reserved by the creator</sub>
+
+Two things people use it for:
+
+- 📖 **Learn faster.** Turn a one-hour talk or tutorial into a page you scroll in a few
+  minutes. See the whole structure at a glance, search the transcript, and only play the
+  parts you actually need.
+- 🎬 **Study the edit ("拉片").** If you make videos, see exactly how someone cut theirs —
+  every shot change, every B-roll insert, every on-screen graphic — laid out as one storyboard.
+
+It runs entirely on your machine. **No LLM, no API key, no network.**
+
+---
+
+## Quick start
+
+### The easy way — just ask your AI agent
+
+cutmap ships with a [Claude Code](https://claude.com/claude-code) skill. Install it once,
+then talk in plain language — the agent downloads the video, runs cutmap, reads the
+result, and answers you:
 
 ```bash
-cutmap video.mp4 --srt video.srt
-open video/浏览.html
+pip install cutmap yt-dlp          # cutmap + video downloader
+brew install ffmpeg                # the video engine  (Linux: apt install ffmpeg)
+
+# install the bundled skill for Claude Code
+git clone https://github.com/xykong36/cutmap
+cp -r cutmap/skills/cutmap ~/.claude/skills/
 ```
 
-Everything runs locally through `ffmpeg` + `Pillow`. **No model calls, no API keys, no network.**
+Then just say things like:
 
-![storyboard](https://raw.githubusercontent.com/xykong36/cutmap/main/examples/storyboard.png)
+> **Download** `https://youtu.be/…` **and use cutmap to summarize what it covers**
+>
+> **Use cutmap on** `lecture.mp4` **and give me the section-by-section breakdown**
+>
+> **What's on screen around 3:41 in that video?** (process it with cutmap first)
 
-<sub>Demo footage: [@林亦LYi](https://www.youtube.com/@lyi) — [《一个视频搞懂 DeepSeek V4！》](https://www.youtube.com/watch?v=WDQjRzVcX-A), all rights reserved by the creator</sub>
+The agent handles the download, the flags, and reading the frames for you — you never
+touch the command line.
+
+### The manual way — command line
+
+```bash
+pip install cutmap
+brew install ffmpeg                # macOS   (Linux: apt install ffmpeg)
+
+cutmap video.mp4 --srt video.srt   # or just: cutmap video.mp4  (finds video.srt)
+open video/browse.html             # ← open this in your browser
+```
+
+That's it. Everything you need is in the `video/` folder next to your file.
 
 ---
 
-## Why not just screenshot every N seconds
+## What you get
 
-Interval sampling is both redundant and lossy. A 30-second talking-head passage yields
-ten identical stills; a fast montage cutting five shots in three seconds yields one.
+Output lands in a directory named after the video:
+
+```
+video/
+├── browse.html        ← open this: the interactive storyboard
+├── frames/            every distinct frame, labelled #index timecode seconds
+├── sheet_01..NN.jpg   4×4 contact sheets for scanning at a glance
+├── index.json         frame timestamps + aligned subtitles (machine readable)
+└── broll/             extracted B-roll clips + broll.json
+```
+
+### The browse page
+
+One self-contained HTML file — all CSS and JS inlined. Two tabs:
+
+**Storyboard** — every distinct frame with its caption
+**B-roll** — auto-looping clips (reads like a GIF wall)
+
+![B-roll clips auto-looping](https://raw.githubusercontent.com/xykong36/cutmap/main/examples/broll-demo.gif)
+
+<sub>The B-roll tab in motion: clips auto-loop like a GIF wall, but they are MP4 under the hood — 1/24 the size of actual GIFs</sub>
+
+What you can do on it:
+
+- **Click any frame or timecode** to seek the embedded player there (local file, no network)
+- **Search the subtitles** — matches the *normalised* text, so searching `DeepSeek` also
+  finds frames where the auto-transcription wrote `deep sick`
+- Long captions collapse behind `…expand`
+- Follows your system light / dark mode
+
+Contact sheets are also written on their own, for scanning a whole video in a few images:
+
+![contact sheet](https://raw.githubusercontent.com/xykong36/cutmap/main/examples/contact-sheet.jpg)
+
+---
+
+## How it works
+
+The interesting part is *which* frames it keeps. Sampling every N seconds is both
+redundant and lossy: a 30-second talking-head passage gives you ten identical stills;
+a fast montage cutting five shots in three seconds gives you one.
 
 cutmap asks a different question — not *"how often should I sample"* but
 **"which frames actually differ"**:
@@ -96,7 +183,10 @@ dense sample  →  perceptual hash each frame  →  compare against last kept fr
 
 Static passages collapse to a single frame. Every visual change gets one.
 
-### Why not ffmpeg's built-in scene detection
+<details>
+<summary><b>Why not ffmpeg's built-in scene detection?</b></summary>
+
+<br>
 
 `select='gt(scene,0.3)'` only catches **hard cuts**. Two things slip past it:
 
@@ -109,69 +199,50 @@ Measured on one 16-minute video: scene detection found **104** frames,
 perceptual dedup found **608**. One 25-second stretch that scene detection called
 a single shot actually contained three completely different pages.
 
+</details>
+
+<details>
+<summary><b>The algorithm's blind spot</b></summary>
 
-### A note on the algorithm's blind spot
+<br>
 
 dHash compares **relative brightness between adjacent pixels**, so it measures spatial
 structure, not colour. Two different flat colours produce an identical (all-zero)
 fingerprint and cannot be told apart. Footage that is largely flat-coloured or
-near-black will therefore dedup more aggressively than you might expect.
-
-This is also why transition cards are detected by mean luminance rather than by hash.
-
----
-
-## Install
-
-```bash
-pip install cutmap
-```
+near-black will therefore dedup more aggressively than you might expect. (This is also
+why transition cards are detected by mean luminance rather than by hash.)
 
-Requires **ffmpeg** on your `PATH`:
-
-```bash
-brew install ffmpeg          # macOS
-apt install ffmpeg           # Debian / Ubuntu
-```
+</details>
 
 ---
 
-## Usage
-
-```bash
-cutmap video.mp4                      # looks for video.srt alongside
-cutmap video.mp4 --srt subs.srt
-cutmap ./material-dir/                # dir containing 源片.mp4 + 字幕.srt
-```
-
-Output lands in a directory named after the video:
-
-```
-video/
-├── frames/            every distinct frame, labelled #index timecode seconds
-├── sheet_01..NN.jpg   4×4 contact sheets for scanning at a glance
-├── index.json         frame timestamps + aligned subtitles (machine readable)
-├── broll/             extracted B-roll clips + broll.json
-└── 浏览.html          ← open this
-```
+## Options
 
-### Options
+Most people never need these — the defaults are tuned for slides, screencasts, and
+talks. Reach for them when the frame count comes out too dense or too sparse.
 
 | Flag | Meaning |
 |---|---|
-| `--threshold N` | Frame density. Lower = denser. `6` dense / `10` default / `14` sparse |
+| `--threshold N` | Frame density. **Lower = more frames.** `6` dense / `10` default / `14` sparse / `24` structure-only |
 | `--fps N` | Dense sampling rate (default 2 — finest resolvable gap is 0.5s) |
-| `--cols/--rows` | Contact sheet grid (default 4×4) |
-| `--thumb-width` | Thumbnail width in px (default 480) |
 | `--seg-max N` | Max seconds per B-roll segment (default 45) |
 | `--clip-format` | `mp4` (default) / `gif` / `webp` |
-| `--no-broll` | Skip B-roll extraction |
+| `--no-broll` | Skip B-roll extraction (much faster) |
 | `--no-frames` | Keep only contact sheets, drop individual frames |
+| `--cols/--rows` | Contact sheet grid (default 4×4) |
+| `--thumb-width` | Thumbnail width in px (default 480) |
 | `--terms FILE` | Custom subtitle term-normalisation table |
 
-### Picking a density
+**Rule of thumb for density:** screencasts and slides → keep the default `10`. Real
+handheld / vlog / interview footage → start at `--threshold 20` (camera shake makes
+every frame look "different" otherwise).
 
-Measured on a 969-second video (2 fps sampling → 1936 raw frames):
+<details>
+<summary><b>Density, measured</b></summary>
+
+<br>
+
+On a 969-second video (2 fps sampling → 1936 raw frames):
 
 | Threshold | Kept | Avg gap | Good for |
 |---|---|---|---|
@@ -180,35 +251,10 @@ Measured on a 969-second video (2 fps sampling → 1936 raw frames):
 | 14 | 463 | 2.1s | Style study, quick scanning |
 | 24 | 241 | 4.0s | Structure only, close to a traditional shot list |
 
-The curve is smooth — there is no natural breakpoint. This is an **aesthetic choice,
-not a parameter with a computable optimum.**
-
----
+The curve is smooth — there is no natural breakpoint. This is an aesthetic choice,
+not a parameter with a computable optimum.
 
-## The browse page
-
-One self-contained HTML file. All CSS and JS inlined; only depends on the images and
-clips sitting next to it. Two tabs:
-
-**Storyboard** — every distinct frame with its caption
-**B-roll** — auto-looping clips (reads like a GIF wall)
-
-![b-roll](https://raw.githubusercontent.com/xykong36/cutmap/main/examples/broll.png)
-
-Shared behaviour:
-
-- Embedded source player up top — **click any timecode or frame to seek there**
-  (local file, no network)
-- Live subtitle search, matching against the **normalised** text
-  (searching `DeepSeek` finds frames whose ASR wrote `deep sick`)
-- Long captions collapse behind `…expand`
-- B-roll clips play only while in viewport (IntersectionObserver) — dozens of
-  simultaneously decoding videos will freeze a browser
-- Follows system light / dark mode
-
-Contact sheets are written separately, for scanning a whole video in a few images:
-
-![contact sheet](https://raw.githubusercontent.com/xykong36/cutmap/main/examples/contact-sheet.jpg)
+</details>
 
 ---
 
@@ -222,30 +268,18 @@ Frames are sorted into three buckets by three plain rules — no model involved:
 | **Transition card** | Mean luminance below 8 (black) or above 245 (white) |
 | **B-roll** | Everything else |
 
-Measured on one episode: B-roll 49 segments / 731s (75.5%),
-main shot 39 / 217s (22.4%), transitions 16 / 20s (2.1%).
-
 Screencast-style videos with no talking head degrade gracefully — no main shot is
 found, everything becomes B-roll, and `--seg-max` keeps it segmented.
 
-### Clip format
-
-Same nine-second segment:
-
-| Format | Size | Note |
-|---|---|---|
-| GIF 10fps | 1.96 MB | 256 colours; visible banding on gradients |
-| WebP | 0.39 MB | Middle ground |
-| **MP4** | **0.08 MB** | **Default** — 24× smaller than GIF, better quality |
-
-MP4 with `loop muted` is visually indistinguishable from a GIF in the page.
-Reach for `--clip-format gif` only when pasting into chat apps or note tools.
+Clips default to **MP4** (`loop muted`), which looks identical to a GIF in the page but
+is ~24× smaller (0.08 MB vs 1.96 MB for a 9-second segment). Use `--clip-format gif`
+only when pasting into chat apps or note tools.
 
 ---
 
 ## Subtitle term normalisation
 
-ASR mangles proper nouns. A built-in table normalises them:
+Auto-transcription mangles proper nouns. A built-in table normalises them:
 
 ```
 大家对deep sick新模型的期待值   →   大家对DeepSeek新模型的期待值
@@ -253,70 +287,61 @@ ASR mangles proper nouns. A built-in table normalises them:
 ```
 
 The real payoff is **search**: querying `DeepSeek` finds every frame whose subtitle
-was transcribed as `deep sick`.
+was transcribed as `deep sick`. The default table targets AI / tech content; bring your
+own with `--terms my_terms.txt` (one `regex => replacement` per line, see
+[`src/cutmap/terms.txt`](https://github.com/xykong36/cutmap/blob/main/src/cutmap/terms.txt)).
 
-The default table targets AI / tech content. Bring your own:
-
-```bash
-cutmap video.mp4 --terms my_terms.txt
-```
-
-Format is one `regex => replacement` per line — see
-[`src/cutmap/terms.txt`](https://github.com/xykong36/cutmap/blob/main/src/cutmap/terms.txt).
-
-**This is term normalisation, not proofreading.** It will not fix segmentation,
-grammar, or one-off errors — those need a language model, which is out of scope here.
+This is term normalisation, not proofreading — it will not fix grammar or one-off errors.
 
 ---
 
-## Troubleshooting
+## Getting footage manually
 
-Bugs hit while building this. Most of them **never raised an error** — they just
-quietly produced wrong output:
+If you're not using the agent skill, cutmap itself doesn't download anything — it works
+on local files. For YouTube / Bilibili, grab the video and subtitles with
+[yt-dlp](https://github.com/yt-dlp/yt-dlp):
 
-**`\b` word boundaries fail in mixed CJK/Latin text**
-CJK characters are `\w` in Python, so in `用grock测试` there is no boundary between
-`用` and `g`. `\bgrock\b` never matches. The term table uses
-`(?<![A-Za-z0-9])…(?![A-Za-z0-9])` instead.
+```bash
+yt-dlp --write-auto-subs --sub-langs "en,zh-Hans" --convert-subs srt \
+       -f "bv*[height<=720]+ba/b" -o "%(id)s.%(ext)s" "<URL>"
+cutmap <id>.mp4
+```
 
-**Flat frames can't be detected by standard deviation**
-Black transition cards usually have burned-in white subtitles, pushing stddev to
-23–33 — far above any "flat colour" threshold. Use mean luminance, and keep it tight
-(`<8`): loosening to `<25` misclassifies merely-dark footage as transitions.
+Respect the terms of service and copyright of wherever your footage comes from; use
+downloaded material for personal study and research only.
 
-**Subtitle time windows must not overlap**
-Adding a look-back to avoid empty captions makes adjacent frames claim the same cue,
-producing duplicated sentences when concatenated. Hence two fields:
-`subtitle` (display, may repeat) and `subtitle_own` (concatenation, strict half-open).
+---
 
-**ffmpeg concat resolves relative paths against the list file's directory**
-Contact sheet file lists must contain absolute paths.
+<details>
+<summary><b>Troubleshooting — bugs I hit building this</b></summary>
 
-**`-v error` suppresses `showinfo` output**
-Any ffmpeg-based statistics gathered with `-v error` silently come back as zero.
+<br>
 
-**Multi-threaded downloads corrupt files on exFAT** (if you fetch footage yourself)
-Pre-allocating and writing at multiple offsets over exFAT-on-USB yields files with
-the right size and wrong contents — `moov atom not found`. Download to local disk,
-then move.
+Most of these **never raised an error** — they just quietly produced wrong output:
 
----
+**`\b` word boundaries fail in mixed CJK/Latin text.** CJK characters are `\w` in Python,
+so in `用grock测试` there is no boundary between `用` and `g`. `\bgrock\b` never matches.
+The term table uses `(?<![A-Za-z0-9])…(?![A-Za-z0-9])` instead.
 
-## Getting footage
+**Flat frames can't be detected by standard deviation.** Black transition cards usually
+have burned-in white subtitles, pushing stddev to 23–33. Use mean luminance, kept tight
+(`<8`): loosening to `<25` misclassifies merely-dark footage as transitions.
 
-cutmap does not download anything — it works on local files.
+**Subtitle time windows must not overlap.** A look-back to avoid empty captions makes
+adjacent frames claim the same cue. Hence two fields: `subtitle` (display, may repeat)
+and `subtitle_own` (concatenation, strict half-open).
 
-For Bilibili, [BBDown](https://github.com/nilaoda/BBDown) muxes subtitles into the mp4;
-pull them out and hand both to cutmap:
+**ffmpeg concat resolves relative paths against the list file's directory** — contact
+sheet file lists must contain absolute paths.
 
-```bash
-BBDown <BV-id> --skip-ai false
-ffmpeg -i video.mp4 -map 0:m:language:chi subs.srt
-cutmap video.mp4 --srt subs.srt
-```
+**`-v error` suppresses `showinfo` output** — any ffmpeg statistics gathered with it
+silently come back as zero.
+
+**Multi-threaded downloads corrupt files on exFAT.** Pre-allocating and writing at
+multiple offsets over exFAT-on-USB yields files with the right size and wrong contents
+(`moov atom not found`). Download to local disk, then move.
 
-Respect the terms of service and copyright of wherever your footage comes from.
-Use downloaded material for personal study and research only.
+</details>
 
 ---
 
@@ -324,15 +349,13 @@ Use downloaded material for personal study and research only.
 
 Built on [ffmpeg](https://ffmpeg.org) and [Pillow](https://python-pillow.org).
 
-Special thanks to **[@林亦LYi](https://www.youtube.com/@lyi)**.
-
-This project started as an attempt to study the editing in his videos — dense cutting,
-interleaved infographics and animated demos. That is exactly the material naive
-interval-screenshotting handles worst, and it is what forced the perceptual-dedup
-approach in the first place. The screenshots in this README are from
-**[《一个视频搞懂 DeepSeek V4！》](https://www.youtube.com/watch?v=WDQjRzVcX-A)**, used solely to demonstrate this tool's
-output; all rights remain with the original creator. If he would prefer them removed,
-please open an issue and they will be replaced immediately.
+Special thanks to **[@林亦LYi](https://www.youtube.com/@lyi)**. This project started as an
+attempt to study the editing in his videos — dense cutting, interleaved infographics and
+animated demos — exactly the material naive interval-screenshotting handles worst. The
+screenshots in this README are from
+**[《一个视频搞懂 DeepSeek V4！》](https://www.youtube.com/watch?v=WDQjRzVcX-A)**, used solely
+to demonstrate this tool's output; all rights remain with the original creator. If he
+would prefer them removed, please open an issue and they will be replaced immediately.
 
 | | |
 |---|---|

cutmap-0.2.0/README.md

@@ -0,0 +1,317 @@
+<div align="center">
+
+# cutmap
+
+**Read a video like a document.**
+Skim a long video in minutes to learn fast — or study it frame-by-frame to see exactly how it's cut.
+
+[![English](https://img.shields.io/badge/lang-English-2b7489?style=flat-square)](https://github.com/xykong36/cutmap/blob/main/README.md)
+[![简体中文](https://img.shields.io/badge/lang-简体中文-lightgrey?style=flat-square)](https://github.com/xykong36/cutmap/blob/main/README.zh-CN.md)
+[![PyPI](https://img.shields.io/pypi/v/cutmap?style=flat-square&color=3775a9)](https://pypi.org/project/cutmap/)
+[![CI](https://github.com/xykong36/cutmap/actions/workflows/ci.yml/badge.svg)](https://github.com/xykong36/cutmap/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/xykong36/cutmap/blob/main/LICENSE)
+[![Python](https://img.shields.io/badge/python-3.9+-3776ab?style=flat-square&logo=python&logoColor=white)](https://www.python.org)
+[![No LLM](https://img.shields.io/badge/LLM-not%20required-success?style=flat-square)](#)
+
+</div>
+
+Watching a video is slow and linear — you can't skim it the way you skim an article,
+and you can't Ctrl-F a moment. cutmap fixes that. Give it a video (and subtitles if you
+have them) and it builds a single HTML page you can actually **read**: every visually
+distinct frame laid out in order, each captioned with what was being said. Click a frame
+to jump the player there; search the subtitles to find a moment.
+
+![storyboard](https://raw.githubusercontent.com/xykong36/cutmap/main/examples/storyboard.png)
+
+<sub>Demo footage: [@林亦LYi](https://www.youtube.com/@lyi) — [《一个视频搞懂 DeepSeek V4！》](https://www.youtube.com/watch?v=WDQjRzVcX-A), all rights reserved by the creator</sub>
+
+Two things people use it for:
+
+- 📖 **Learn faster.** Turn a one-hour talk or tutorial into a page you scroll in a few
+  minutes. See the whole structure at a glance, search the transcript, and only play the
+  parts you actually need.
+- 🎬 **Study the edit ("拉片").** If you make videos, see exactly how someone cut theirs —
+  every shot change, every B-roll insert, every on-screen graphic — laid out as one storyboard.
+
+It runs entirely on your machine. **No LLM, no API key, no network.**
+
+---
+
+## Quick start
+
+### The easy way — just ask your AI agent
+
+cutmap ships with a [Claude Code](https://claude.com/claude-code) skill. Install it once,
+then talk in plain language — the agent downloads the video, runs cutmap, reads the
+result, and answers you:
+
+```bash
+pip install cutmap yt-dlp          # cutmap + video downloader
+brew install ffmpeg                # the video engine  (Linux: apt install ffmpeg)
+
+# install the bundled skill for Claude Code
+git clone https://github.com/xykong36/cutmap
+cp -r cutmap/skills/cutmap ~/.claude/skills/
+```
+
+Then just say things like:
+
+> **Download** `https://youtu.be/…` **and use cutmap to summarize what it covers**
+>
+> **Use cutmap on** `lecture.mp4` **and give me the section-by-section breakdown**
+>
+> **What's on screen around 3:41 in that video?** (process it with cutmap first)
+
+The agent handles the download, the flags, and reading the frames for you — you never
+touch the command line.
+
+### The manual way — command line
+
+```bash
+pip install cutmap
+brew install ffmpeg                # macOS   (Linux: apt install ffmpeg)
+
+cutmap video.mp4 --srt video.srt   # or just: cutmap video.mp4  (finds video.srt)
+open video/browse.html             # ← open this in your browser
+```
+
+That's it. Everything you need is in the `video/` folder next to your file.
+
+---
+
+## What you get
+
+Output lands in a directory named after the video:
+
+```
+video/
+├── browse.html        ← open this: the interactive storyboard
+├── frames/            every distinct frame, labelled #index timecode seconds
+├── sheet_01..NN.jpg   4×4 contact sheets for scanning at a glance
+├── index.json         frame timestamps + aligned subtitles (machine readable)
+└── broll/             extracted B-roll clips + broll.json
+```
+
+### The browse page
+
+One self-contained HTML file — all CSS and JS inlined. Two tabs:
+
+**Storyboard** — every distinct frame with its caption
+**B-roll** — auto-looping clips (reads like a GIF wall)
+
+![B-roll clips auto-looping](https://raw.githubusercontent.com/xykong36/cutmap/main/examples/broll-demo.gif)
+
+<sub>The B-roll tab in motion: clips auto-loop like a GIF wall, but they are MP4 under the hood — 1/24 the size of actual GIFs</sub>
+
+What you can do on it:
+
+- **Click any frame or timecode** to seek the embedded player there (local file, no network)
+- **Search the subtitles** — matches the *normalised* text, so searching `DeepSeek` also
+  finds frames where the auto-transcription wrote `deep sick`
+- Long captions collapse behind `…expand`
+- Follows your system light / dark mode
+
+Contact sheets are also written on their own, for scanning a whole video in a few images:
+
+![contact sheet](https://raw.githubusercontent.com/xykong36/cutmap/main/examples/contact-sheet.jpg)
+
+---
+
+## How it works
+
+The interesting part is *which* frames it keeps. Sampling every N seconds is both
+redundant and lossy: a 30-second talking-head passage gives you ten identical stills;
+a fast montage cutting five shots in three seconds gives you one.
+
+cutmap asks a different question — not *"how often should I sample"* but
+**"which frames actually differ"**:
+
+```
+dense sample  →  perceptual hash each frame  →  compare against last kept frame
+                                             →  keep only if different enough
+```
+
+Static passages collapse to a single frame. Every visual change gets one.
+
+<details>
+<summary><b>Why not ffmpeg's built-in scene detection?</b></summary>
+
+<br>
+
+`select='gt(scene,0.3)'` only catches **hard cuts**. Two things slip past it:
+
+1. **Low-contrast transitions** — white slide to white webpage. Similar overall
+   luminance structure, so the difference score never crosses the threshold.
+2. **Intra-shot evolution** — text appearing line by line, charts animating,
+   table rows highlighting. Not a "cut" by any definition, but visually distinct.
+
+Measured on one 16-minute video: scene detection found **104** frames,
+perceptual dedup found **608**. One 25-second stretch that scene detection called
+a single shot actually contained three completely different pages.
+
+</details>
+
+<details>
+<summary><b>The algorithm's blind spot</b></summary>
+
+<br>
+
+dHash compares **relative brightness between adjacent pixels**, so it measures spatial
+structure, not colour. Two different flat colours produce an identical (all-zero)
+fingerprint and cannot be told apart. Footage that is largely flat-coloured or
+near-black will therefore dedup more aggressively than you might expect. (This is also
+why transition cards are detected by mean luminance rather than by hash.)
+
+</details>
+
+---
+
+## Options
+
+Most people never need these — the defaults are tuned for slides, screencasts, and
+talks. Reach for them when the frame count comes out too dense or too sparse.
+
+| Flag | Meaning |
+|---|---|
+| `--threshold N` | Frame density. **Lower = more frames.** `6` dense / `10` default / `14` sparse / `24` structure-only |
+| `--fps N` | Dense sampling rate (default 2 — finest resolvable gap is 0.5s) |
+| `--seg-max N` | Max seconds per B-roll segment (default 45) |
+| `--clip-format` | `mp4` (default) / `gif` / `webp` |
+| `--no-broll` | Skip B-roll extraction (much faster) |
+| `--no-frames` | Keep only contact sheets, drop individual frames |
+| `--cols/--rows` | Contact sheet grid (default 4×4) |
+| `--thumb-width` | Thumbnail width in px (default 480) |
+| `--terms FILE` | Custom subtitle term-normalisation table |
+
+**Rule of thumb for density:** screencasts and slides → keep the default `10`. Real
+handheld / vlog / interview footage → start at `--threshold 20` (camera shake makes
+every frame look "different" otherwise).
+
+<details>
+<summary><b>Density, measured</b></summary>
+
+<br>
+
+On a 969-second video (2 fps sampling → 1936 raw frames):
+
+| Threshold | Kept | Avg gap | Good for |
+|---|---|---|---|
+| 6 | 892 | 1.1s | Reconstructing every visual step (tutorial walkthroughs) |
+| **10** | **597** | **1.6s** | **Default** — balances coverage and readability |
+| 14 | 463 | 2.1s | Style study, quick scanning |
+| 24 | 241 | 4.0s | Structure only, close to a traditional shot list |
+
+The curve is smooth — there is no natural breakpoint. This is an aesthetic choice,
+not a parameter with a computable optimum.
+
+</details>
+
+---
+
+## B-roll detection
+
+Frames are sorted into three buckets by three plain rules — no model involved:
+
+| Bucket | Rule |
+|---|---|
+| **Main shot** | A cluster of near-identical frames recurring across >50% of the runtime — i.e. a locked-off camera |
+| **Transition card** | Mean luminance below 8 (black) or above 245 (white) |
+| **B-roll** | Everything else |
+
+Screencast-style videos with no talking head degrade gracefully — no main shot is
+found, everything becomes B-roll, and `--seg-max` keeps it segmented.
+
+Clips default to **MP4** (`loop muted`), which looks identical to a GIF in the page but
+is ~24× smaller (0.08 MB vs 1.96 MB for a 9-second segment). Use `--clip-format gif`
+only when pasting into chat apps or note tools.
+
+---
+
+## Subtitle term normalisation
+
+Auto-transcription mangles proper nouns. A built-in table normalises them:
+
+```
+大家对deep sick新模型的期待值   →   大家对DeepSeek新模型的期待值
+用grock测试                    →   用Grok测试
+```
+
+The real payoff is **search**: querying `DeepSeek` finds every frame whose subtitle
+was transcribed as `deep sick`. The default table targets AI / tech content; bring your
+own with `--terms my_terms.txt` (one `regex => replacement` per line, see
+[`src/cutmap/terms.txt`](https://github.com/xykong36/cutmap/blob/main/src/cutmap/terms.txt)).
+
+This is term normalisation, not proofreading — it will not fix grammar or one-off errors.
+
+---
+
+## Getting footage manually
+
+If you're not using the agent skill, cutmap itself doesn't download anything — it works
+on local files. For YouTube / Bilibili, grab the video and subtitles with
+[yt-dlp](https://github.com/yt-dlp/yt-dlp):
+
+```bash
+yt-dlp --write-auto-subs --sub-langs "en,zh-Hans" --convert-subs srt \
+       -f "bv*[height<=720]+ba/b" -o "%(id)s.%(ext)s" "<URL>"
+cutmap <id>.mp4
+```
+
+Respect the terms of service and copyright of wherever your footage comes from; use
+downloaded material for personal study and research only.
+
+---
+
+<details>
+<summary><b>Troubleshooting — bugs I hit building this</b></summary>
+
+<br>
+
+Most of these **never raised an error** — they just quietly produced wrong output:
+
+**`\b` word boundaries fail in mixed CJK/Latin text.** CJK characters are `\w` in Python,
+so in `用grock测试` there is no boundary between `用` and `g`. `\bgrock\b` never matches.
+The term table uses `(?<![A-Za-z0-9])…(?![A-Za-z0-9])` instead.
+
+**Flat frames can't be detected by standard deviation.** Black transition cards usually
+have burned-in white subtitles, pushing stddev to 23–33. Use mean luminance, kept tight
+(`<8`): loosening to `<25` misclassifies merely-dark footage as transitions.
+
+**Subtitle time windows must not overlap.** A look-back to avoid empty captions makes
+adjacent frames claim the same cue. Hence two fields: `subtitle` (display, may repeat)
+and `subtitle_own` (concatenation, strict half-open).
+
+**ffmpeg concat resolves relative paths against the list file's directory** — contact
+sheet file lists must contain absolute paths.
+
+**`-v error` suppresses `showinfo` output** — any ffmpeg statistics gathered with it
+silently come back as zero.
+
+**Multi-threaded downloads corrupt files on exFAT.** Pre-allocating and writing at
+multiple offsets over exFAT-on-USB yields files with the right size and wrong contents
+(`moov atom not found`). Download to local disk, then move.
+
+</details>
+
+---
+
+## Credits
+
+Built on [ffmpeg](https://ffmpeg.org) and [Pillow](https://python-pillow.org).
+
+Special thanks to **[@林亦LYi](https://www.youtube.com/@lyi)**. This project started as an
+attempt to study the editing in his videos — dense cutting, interleaved infographics and
+animated demos — exactly the material naive interval-screenshotting handles worst. The
+screenshots in this README are from
+**[《一个视频搞懂 DeepSeek V4！》](https://www.youtube.com/watch?v=WDQjRzVcX-A)**, used solely
+to demonstrate this tool's output; all rights remain with the original creator. If he
+would prefer them removed, please open an issue and they will be replaced immediately.
+
+| | |
+|---|---|
+| Source video | <https://www.youtube.com/watch?v=WDQjRzVcX-A> |
+| Creator | YouTube <https://www.youtube.com/@lyi> · Bilibili <https://space.bilibili.com/4401694> |
+
+## License
+
+MIT

{cutmap-0.1.1 → cutmap-0.2.0}/pyproject.toml

@@ -4,9 +4,9 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cutmap"
-version = "0.1.1"
+version = "0.2.0"
 description = "Turn any video into a browsable, searchable storyboard — and auto-extract its B-roll. Local ffmpeg + perceptual hashing, no LLM."
-readme = "README.en.md"   # PyPI 面向全球用户，用英文；GitHub 首页仍是中文
+readme = "README.md"   # 英文主版，同时用于 PyPI 与 GitHub 首页；中文见 README.zh-CN.md
 requires-python = ">=3.9"
 license = { file = "LICENSE" }
 keywords = ["video", "storyboard", "b-roll", "ffmpeg", "subtitle", "perceptual-hash", "分镜"]

{cutmap-0.1.1 → cutmap-0.2.0}/src/cutmap/__init__.py

@@ -1,2 +1,2 @@
 """cutmap —— 视频分镜分析：感知去重抽画面、B-roll 自动识别、图文对照浏览"""
-__version__ = "0.1.1"
+__version__ = "0.2.0"

{cutmap-0.1.1 → cutmap-0.2.0}/src/cutmap/cli.py

@@ -26,13 +26,13 @@ def _step(n: int, total: int, msg: str) -> None:
 def resolve(target: str, srt_opt: str | None):
     """输入 → (视频路径, 字幕路径或None, 工作目录)"""
     if os.path.isdir(target):
-        mp4 = os.path.join(target, "源片.mp4")
+        mp4 = os.path.join(target, "source.mp4")
         if not os.path.exists(mp4):
             cand = glob.glob(os.path.join(target, "*.mp4"))
             if not cand:
                 sys.exit(f"目录里没有 mp4: {target}")
             mp4 = max(cand, key=os.path.getsize)
-        srt = srt_opt or os.path.join(target, "字幕.srt")
+        srt = srt_opt or os.path.join(target, "subtitle.srt")
         return mp4, (srt if os.path.exists(srt) else None), target
 
     if os.path.isfile(target):

{cutmap-0.1.1 → cutmap-0.2.0}/src/cutmap/render.py

@@ -102,8 +102,8 @@ def build(outdir: str, terms: str | None = None, log=print) -> str:
 {broll_pane}
 <script>{JS}</script></body></html>
 """
-    out = os.path.join(outdir, "浏览.html")
+    out = os.path.join(outdir, "browse.html")
     open(out, "w", encoding="utf-8").write(page)
-    log(f"  ✓ 浏览.html ({os.path.getsize(out)//1024} KB, "
+    log(f"  ✓ browse.html ({os.path.getsize(out)//1024} KB, "
         f"分镜 {len(fcards)} + B-roll {len(bcards)})")
     return out

cutmap-0.1.1/README.en.md

@@ -1,294 +0,0 @@
-<div align="center">
-
-# cutmap
-
-**Turn any video into a browsable, searchable storyboard — and auto-extract its B-roll.**
-
-[![简体中文](https://img.shields.io/badge/lang-简体中文-lightgrey?style=flat-square)](https://github.com/xykong36/cutmap/blob/main/README.md)
-[![English](https://img.shields.io/badge/lang-English-2b7489?style=flat-square)](https://github.com/xykong36/cutmap/blob/main/README.en.md)
-[![PyPI](https://img.shields.io/pypi/v/cutmap?style=flat-square&color=3775a9)](https://pypi.org/project/cutmap/)
-[![CI](https://github.com/xykong36/cutmap/actions/workflows/ci.yml/badge.svg)](https://github.com/xykong36/cutmap/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/xykong36/cutmap/blob/main/LICENSE)
-[![Python](https://img.shields.io/badge/python-3.9+-3776ab?style=flat-square&logo=python&logoColor=white)](https://www.python.org)
-[![No LLM](https://img.shields.io/badge/LLM-not%20required-success?style=flat-square)](#)
-
-</div>
-
-Give it a video and a subtitle file. Get back a single HTML page: the source player on
-the left, every distinct frame on the right, each captioned with what was being said.
-Click any frame to jump the player to that moment. Search the subtitles to locate a shot.
-
-```bash
-cutmap video.mp4 --srt video.srt
-open video/浏览.html
-```
-
-Everything runs locally through `ffmpeg` + `Pillow`. **No model calls, no API keys, no network.**
-
-![storyboard](https://raw.githubusercontent.com/xykong36/cutmap/main/examples/storyboard.png)
-
-<sub>Demo footage: [@林亦LYi](https://www.youtube.com/@lyi) — [《一个视频搞懂 DeepSeek V4！》](https://www.youtube.com/watch?v=WDQjRzVcX-A), all rights reserved by the creator</sub>
-
----
-
-## Why not just screenshot every N seconds
-
-Interval sampling is both redundant and lossy. A 30-second talking-head passage yields
-ten identical stills; a fast montage cutting five shots in three seconds yields one.
-
-cutmap asks a different question — not *"how often should I sample"* but
-**"which frames actually differ"**:
-
-```
-dense sample  →  perceptual hash each frame  →  compare against last kept frame
-                                             →  keep only if different enough
-```
-
-Static passages collapse to a single frame. Every visual change gets one.
-
-### Why not ffmpeg's built-in scene detection
-
-`select='gt(scene,0.3)'` only catches **hard cuts**. Two things slip past it:
-
-1. **Low-contrast transitions** — white slide to white webpage. Similar overall
-   luminance structure, so the difference score never crosses the threshold.
-2. **Intra-shot evolution** — text appearing line by line, charts animating,
-   table rows highlighting. Not a "cut" by any definition, but visually distinct.
-
-Measured on one 16-minute video: scene detection found **104** frames,
-perceptual dedup found **608**. One 25-second stretch that scene detection called
-a single shot actually contained three completely different pages.
-
-
-### A note on the algorithm's blind spot
-
-dHash compares **relative brightness between adjacent pixels**, so it measures spatial
-structure, not colour. Two different flat colours produce an identical (all-zero)
-fingerprint and cannot be told apart. Footage that is largely flat-coloured or
-near-black will therefore dedup more aggressively than you might expect.
-
-This is also why transition cards are detected by mean luminance rather than by hash.
-
----
-
-## Install
-
-```bash
-pip install cutmap
-```
-
-Requires **ffmpeg** on your `PATH`:
-
-```bash
-brew install ffmpeg          # macOS
-apt install ffmpeg           # Debian / Ubuntu
-```
-
----
-
-## Usage
-
-```bash
-cutmap video.mp4                      # looks for video.srt alongside
-cutmap video.mp4 --srt subs.srt
-cutmap ./material-dir/                # dir containing 源片.mp4 + 字幕.srt
-```
-
-Output lands in a directory named after the video:
-
-```
-video/
-├── frames/            every distinct frame, labelled #index timecode seconds
-├── sheet_01..NN.jpg   4×4 contact sheets for scanning at a glance
-├── index.json         frame timestamps + aligned subtitles (machine readable)
-├── broll/             extracted B-roll clips + broll.json
-└── 浏览.html          ← open this
-```
-
-### Options
-
-| Flag | Meaning |
-|---|---|
-| `--threshold N` | Frame density. Lower = denser. `6` dense / `10` default / `14` sparse |
-| `--fps N` | Dense sampling rate (default 2 — finest resolvable gap is 0.5s) |
-| `--cols/--rows` | Contact sheet grid (default 4×4) |
-| `--thumb-width` | Thumbnail width in px (default 480) |
-| `--seg-max N` | Max seconds per B-roll segment (default 45) |
-| `--clip-format` | `mp4` (default) / `gif` / `webp` |
-| `--no-broll` | Skip B-roll extraction |
-| `--no-frames` | Keep only contact sheets, drop individual frames |
-| `--terms FILE` | Custom subtitle term-normalisation table |
-
-### Picking a density
-
-Measured on a 969-second video (2 fps sampling → 1936 raw frames):
-
-| Threshold | Kept | Avg gap | Good for |
-|---|---|---|---|
-| 6 | 892 | 1.1s | Reconstructing every visual step (tutorial walkthroughs) |
-| **10** | **597** | **1.6s** | **Default** — balances coverage and readability |
-| 14 | 463 | 2.1s | Style study, quick scanning |
-| 24 | 241 | 4.0s | Structure only, close to a traditional shot list |
-
-The curve is smooth — there is no natural breakpoint. This is an **aesthetic choice,
-not a parameter with a computable optimum.**
-
----
-
-## The browse page
-
-One self-contained HTML file. All CSS and JS inlined; only depends on the images and
-clips sitting next to it. Two tabs:
-
-**Storyboard** — every distinct frame with its caption
-**B-roll** — auto-looping clips (reads like a GIF wall)
-
-![b-roll](https://raw.githubusercontent.com/xykong36/cutmap/main/examples/broll.png)
-
-Shared behaviour:
-
-- Embedded source player up top — **click any timecode or frame to seek there**
-  (local file, no network)
-- Live subtitle search, matching against the **normalised** text
-  (searching `DeepSeek` finds frames whose ASR wrote `deep sick`)
-- Long captions collapse behind `…expand`
-- B-roll clips play only while in viewport (IntersectionObserver) — dozens of
-  simultaneously decoding videos will freeze a browser
-- Follows system light / dark mode
-
-Contact sheets are written separately, for scanning a whole video in a few images:
-
-![contact sheet](https://raw.githubusercontent.com/xykong36/cutmap/main/examples/contact-sheet.jpg)
-
----
-
-## B-roll detection
-
-Frames are sorted into three buckets by three plain rules — no model involved:
-
-| Bucket | Rule |
-|---|---|
-| **Main shot** | A cluster of near-identical frames recurring across >50% of the runtime — i.e. a locked-off camera |
-| **Transition card** | Mean luminance below 8 (black) or above 245 (white) |
-| **B-roll** | Everything else |
-
-Measured on one episode: B-roll 49 segments / 731s (75.5%),
-main shot 39 / 217s (22.4%), transitions 16 / 20s (2.1%).
-
-Screencast-style videos with no talking head degrade gracefully — no main shot is
-found, everything becomes B-roll, and `--seg-max` keeps it segmented.
-
-### Clip format
-
-Same nine-second segment:
-
-| Format | Size | Note |
-|---|---|---|
-| GIF 10fps | 1.96 MB | 256 colours; visible banding on gradients |
-| WebP | 0.39 MB | Middle ground |
-| **MP4** | **0.08 MB** | **Default** — 24× smaller than GIF, better quality |
-
-MP4 with `loop muted` is visually indistinguishable from a GIF in the page.
-Reach for `--clip-format gif` only when pasting into chat apps or note tools.
-
----
-
-## Subtitle term normalisation
-
-ASR mangles proper nouns. A built-in table normalises them:
-
-```
-大家对deep sick新模型的期待值   →   大家对DeepSeek新模型的期待值
-用grock测试                    →   用Grok测试
-```
-
-The real payoff is **search**: querying `DeepSeek` finds every frame whose subtitle
-was transcribed as `deep sick`.
-
-The default table targets AI / tech content. Bring your own:
-
-```bash
-cutmap video.mp4 --terms my_terms.txt
-```
-
-Format is one `regex => replacement` per line — see
-[`src/cutmap/terms.txt`](https://github.com/xykong36/cutmap/blob/main/src/cutmap/terms.txt).
-
-**This is term normalisation, not proofreading.** It will not fix segmentation,
-grammar, or one-off errors — those need a language model, which is out of scope here.
-
----
-
-## Troubleshooting
-
-Bugs hit while building this. Most of them **never raised an error** — they just
-quietly produced wrong output:
-
-**`\b` word boundaries fail in mixed CJK/Latin text**
-CJK characters are `\w` in Python, so in `用grock测试` there is no boundary between
-`用` and `g`. `\bgrock\b` never matches. The term table uses
-`(?<![A-Za-z0-9])…(?![A-Za-z0-9])` instead.
-
-**Flat frames can't be detected by standard deviation**
-Black transition cards usually have burned-in white subtitles, pushing stddev to
-23–33 — far above any "flat colour" threshold. Use mean luminance, and keep it tight
-(`<8`): loosening to `<25` misclassifies merely-dark footage as transitions.
-
-**Subtitle time windows must not overlap**
-Adding a look-back to avoid empty captions makes adjacent frames claim the same cue,
-producing duplicated sentences when concatenated. Hence two fields:
-`subtitle` (display, may repeat) and `subtitle_own` (concatenation, strict half-open).
-
-**ffmpeg concat resolves relative paths against the list file's directory**
-Contact sheet file lists must contain absolute paths.
-
-**`-v error` suppresses `showinfo` output**
-Any ffmpeg-based statistics gathered with `-v error` silently come back as zero.
-
-**Multi-threaded downloads corrupt files on exFAT** (if you fetch footage yourself)
-Pre-allocating and writing at multiple offsets over exFAT-on-USB yields files with
-the right size and wrong contents — `moov atom not found`. Download to local disk,
-then move.
-
----
-
-## Getting footage
-
-cutmap does not download anything — it works on local files.
-
-For Bilibili, [BBDown](https://github.com/nilaoda/BBDown) muxes subtitles into the mp4;
-pull them out and hand both to cutmap:
-
-```bash
-BBDown <BV-id> --skip-ai false
-ffmpeg -i video.mp4 -map 0:m:language:chi subs.srt
-cutmap video.mp4 --srt subs.srt
-```
-
-Respect the terms of service and copyright of wherever your footage comes from.
-Use downloaded material for personal study and research only.
-
----
-
-## Credits
-
-Built on [ffmpeg](https://ffmpeg.org) and [Pillow](https://python-pillow.org).
-
-Special thanks to **[@林亦LYi](https://www.youtube.com/@lyi)**.
-
-This project started as an attempt to study the editing in his videos — dense cutting,
-interleaved infographics and animated demos. That is exactly the material naive
-interval-screenshotting handles worst, and it is what forced the perceptual-dedup
-approach in the first place. The screenshots in this README are from
-**[《一个视频搞懂 DeepSeek V4！》](https://www.youtube.com/watch?v=WDQjRzVcX-A)**, used solely to demonstrate this tool's
-output; all rights remain with the original creator. If he would prefer them removed,
-please open an issue and they will be replaced immediately.
-
-| | |
-|---|---|
-| Source video | <https://www.youtube.com/watch?v=WDQjRzVcX-A> |
-| Creator | YouTube <https://www.youtube.com/@lyi> · Bilibili <https://space.bilibili.com/4401694> |
-
-## License
-
-MIT