| # compare_deck |
| |
| A standalone review page for a batch of clips. You hand it a JSON manifest |
| and it writes one self-contained HTML file: a card grid with hover-play and |
| audio on click, a sortable metric table with inline bars, a head to head A/B |
| that plays both sides in sync (side by side or as a wipe) with a waveform |
| timeline and loop brackets, starred picks you can copy back as markdown, and |
| an export that records the current A/B view to a video file. |
| |
| The videos stay where they are. The page references them by path or URL and |
| nothing but the HTML is produced, so no media is ever committed here. |
| |
| Live example: <https://matlowai.github.io/flipbook/trueclock.html> (33 |
| clips, three metric columns, region spans marked on the timeline). |
| |
| ## Use |
| |
| Two steps: draft a manifest from a folder of clips, fill in the argument the |
| deck is making, build the page. |
| |
| ``` |
| python3 tools/compare_deck/make_manifest.py /path/to/clips deck.json \ |
| --title "block sweep" --posters /path/to/posters --metrics scores.csv \ |
| --src-prefix media/sweep --poster-prefix media/sweep/posters |
| # edit deck.json: fill group and desc on each row, label the metric columns |
| python3 tools/compare_deck/build_compare_page.py deck.json deck.html |
| ``` |
| |
| `make_manifest.py` probes fps, duration and aspect with ffprobe, matches |
| posters by stem, and merges metrics by stem from either a CSV (first column |
| is the stem unless you pass `--metrics-key`) or a directory of one flat JSON |
| per clip. It leaves `group` and `desc` empty on purpose. Grouping is the |
| claim the deck makes and a guessed one reads as evidence, so it stays a |
| human step. `--force` is required to overwrite an existing manifest, and |
| clips that disagree on fps are an error until you pick one with `--fps`. |
| |
| `build_compare_page.py` inlines the two vendored muxers (see |
| `vendor/NOTICE`) so the frame-exact export works with no network. Both |
| tools resolve their own paths from `__file__` and run from any cwd. |
| |
| ## Manifest |
| |
| Top level: |
| |
| | key | meaning | |
| |---|---| |
| | `title` | document title, also the localStorage key for stars | |
| | `h1`, `lede_html` | heading and one intro paragraph, HTML verbatim | |
| | `aspect` | CSS aspect ratio for the players, e.g. `"864/480"` | |
| | `fps` | the clock for frame numbers, spans, marks and export (default 24) | |
| | `media` | optional base path; rows may then omit `src`/`poster` and get `MEDIA/<arm>.mp4` and `.jpg` | |
| | `cols` | `[[key, label, decimals, sortdir], ...]`, the metric columns in table order | |
| | `groups` | the group filter's options; derived from the rows when empty | |
| | `rows` | one object per clip, below | |
| |
| Per row: `arm` (the id, and the stem for derived paths), `group`, `desc`, |
| `src`, `poster`, any of the metric keys named in `cols`, and optionally |
| `curve` (a list of per-frame values drawn as a sparkline and on the |
| timeline), `ref_curve` (a second faint line to compare against), `color` |
| (dot colour, defaults by group), and `spans` (`[[start_frame, end_frame]]`, |
| shaded on the timeline and blipped on entry and exit). |
| |
| The first row is the reference: it sorts to the top and both players load it |
| at startup. Rows in the `control` or `reference` group get the green dot. |
| |
| Minimal example: |
| |
| ```json |
| {"title": "block sweep", "aspect": "864/480", "fps": 24, |
| "cols": [["flash", "seam flash x", 2, 1]], |
| "rows": [ |
| {"arm": "control", "group": "control", "desc": "stock, no change", |
| "src": "media/control.mp4", "flash": 2.09, "spans": [[124, 157]]}, |
| {"arm": "pb4049", "group": "late-blocks", "desc": "physical in blocks 40-49", |
| "src": "media/pb4049.mp4", "flash": 1.31, "spans": [[124, 157]]}]} |
| ``` |
| |
| ## Keys in the page |
|
|
| `space` play/pause, `f` swap A and B, `1`/`2` which side you hear, `i`/`o` |
| loop in and out at the playhead. The gear opens region frames, a frame |
| counter and mark blips. Export offers VP9 or AV1 webm and H.264 mp4; the |
| frame-exact path seeks and encodes every frame, so it is not a screen |
| recording and does not drop frames under load. |
|
|
