fix: use noarchive mode and enable console to debug PYZ TOC error

Bypasses PYZ archive entirely — modules stored as individual .pyc files.
Console enabled temporarily to capture error output.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.github/workflows/release.yml

@@ -0,0 +1,115 @@
+name: Build & Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  # ── Windows ────────────────────────────────────────────────
+  windows:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Python dependencies
+        run: pip install pyinstaller PyQt6 python-mpv
+
+      - name: Fetch ffmpeg
+        shell: pwsh
+        run: |
+          $ffUrl = "https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-win64-gpl.zip"
+          Invoke-WebRequest $ffUrl -OutFile ffmpeg.zip
+          Expand-Archive ffmpeg.zip -DestinationPath ffmpeg-tmp
+          $bin = Get-ChildItem -Path ffmpeg-tmp -Recurse -Filter ffmpeg.exe | Select-Object -First 1
+          Copy-Item "$($bin.DirectoryName)\ffmpeg.exe" .
+          Copy-Item "$($bin.DirectoryName)\ffprobe.exe" .
+
+      - name: Fetch libmpv
+        shell: pwsh
+        run: |
+          $release = Invoke-RestMethod "https://api.github.com/repos/shinchiro/mpv-winbuild-cmake/releases/latest"
+          $asset = $release.assets | Where-Object { $_.name -like "mpv-dev-x86_64-v3-*" } | Select-Object -First 1
+          Invoke-WebRequest $asset.browser_download_url -OutFile mpv-dev.7z
+          7z x mpv-dev.7z -ompv-dev
+          Copy-Item mpv-dev\libmpv-2.dll .
+
+      - name: Build with PyInstaller
+        run: pyinstaller 8cut.spec
+
+      - name: Package
+        shell: pwsh
+        run: Compress-Archive -Path dist\8cut\* -DestinationPath 8cut-windows.zip
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: 8cut-windows
+          path: 8cut-windows.zip
+
+  # ── macOS (Apple Silicon) ──────────────────────────────────
+  macos:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Python dependencies
+        run: pip install pyinstaller PyQt6 python-mpv
+
+      - name: Install native deps
+        run: |
+          brew install mpv ffmpeg
+          cp "$(brew --prefix mpv)/lib/libmpv.2.dylib" .
+          cp "$(brew --prefix ffmpeg)/bin/ffmpeg" .
+          cp "$(brew --prefix ffmpeg)/bin/ffprobe" .
+
+      - name: Build with PyInstaller
+        run: pyinstaller 8cut.spec
+
+      - name: Fix dylib rpaths
+        run: |
+          DYLIB="dist/8cut/libmpv.2.dylib"
+          if [ -f "$DYLIB" ]; then
+            install_name_tool -id @executable_path/libmpv.2.dylib "$DYLIB"
+          fi
+
+      - name: Package
+        run: |
+          cd dist
+          zip -r ../8cut-macos-arm64.zip 8cut.app
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: 8cut-macos-arm64
+          path: 8cut-macos-arm64.zip
+
+  # ── Create GitHub Release ──────────────────────────────────
+  release:
+    needs: [windows, macos]
+    if: ${{ always() && startsWith(github.ref, 'refs/tags/v') && (needs.windows.result == 'success' || needs.macos.result == 'success') }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v2
+        with:
+          draft: false
+          generate_release_notes: true
+          files: artifacts/**/*.zip

.gitignore

@@ -2,3 +2,4 @@ __pycache__/
 *.pyc
 *.pyo
 .pytest_cache/
+.worktrees/

8cut.bat

@@ -0,0 +1,3 @@
+@echo off
+cd /d "%~dp0"
+python main.py %*

8cut.spec

@@ -0,0 +1,142 @@
+# -*- mode: python ; coding: utf-8 -*-
+"""PyInstaller spec for 8-cut.
+
+Usage:
+    pyinstaller 8cut.spec
+
+Platform-specific notes:
+    Windows: place libmpv-2.dll, ffmpeg.exe, ffprobe.exe next to main.py
+             before building, or set FFMPEG_DIR / MPV_DIR env vars.
+    macOS:   place libmpv.2.dylib, ffmpeg, ffprobe next to main.py
+             before building, or set FFMPEG_DIR / MPV_DIR env vars.
+    Linux:   system libmpv and ffmpeg are used from PATH (not bundled).
+"""
+
+import os
+import platform
+import sys
+from pathlib import Path
+
+block_cipher = None
+system = platform.system()
+
+# ---------- paths ----------------------------------------------------------
+
+base = Path(SPECPATH)
+ffmpeg_dir = Path(os.environ.get("FFMPEG_DIR", base))
+mpv_dir = Path(os.environ.get("MPV_DIR", base))
+
+# ---------- data files -----------------------------------------------------
+
+datas = []
+
+# YOLOv8 model (optional — large, skip if missing)
+yolo = base / "yolov8n.pt"
+if yolo.exists():
+    datas.append((str(yolo), "."))
+
+# ---------- native binaries ------------------------------------------------
+
+binaries = []
+
+if system == "Windows":
+    for name in ("libmpv-2.dll",):
+        p = mpv_dir / name
+        if p.exists():
+            binaries.append((str(p), "."))
+    for name in ("ffmpeg.exe", "ffprobe.exe"):
+        p = ffmpeg_dir / name
+        if p.exists():
+            binaries.append((str(p), "."))
+
+elif system == "Darwin":
+    for name in ("libmpv.2.dylib", "libmpv.dylib"):
+        p = mpv_dir / name
+        if p.exists():
+            binaries.append((str(p), "."))
+            break
+    for name in ("ffmpeg", "ffprobe"):
+        p = ffmpeg_dir / name
+        if p.exists():
+            binaries.append((str(p), "."))
+
+# ---------- analysis -------------------------------------------------------
+
+a = Analysis(
+    [str(base / "main.py")],
+    pathex=[str(base)],
+    binaries=binaries,
+    datas=datas,
+    hiddenimports=[
+        "mpv",
+        "PyQt6.QtOpenGL",
+        "PyQt6.QtOpenGLWidgets",
+    ],
+    hookspath=[],
+    hooksconfig={},
+    runtime_hooks=[],
+    excludes=[
+        # ultralytics is optional and huge — exclude from frozen build
+        "ultralytics",
+        "torch",
+        "torchvision",
+        "onnxruntime",
+        "opencv-python",
+        # test / dev
+        "pytest",
+        "hypothesis",
+    ],
+    noarchive=True,
+    cipher=block_cipher,
+)
+
+pyz = PYZ(a.pure, cipher=block_cipher)
+
+# ---------- executable -----------------------------------------------------
+
+exe_kwargs = dict(
+    pyz=pyz,
+    a=a,
+    name="8cut",
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=False,
+    upx=False,
+    console=True,  # temporary: show errors on launch
+)
+
+if system == "Darwin":
+    exe_kwargs["icon"] = str(base / "assets" / "logo.png")
+elif system == "Windows":
+    ico = base / "assets" / "logo.ico"
+    if ico.exists():
+        exe_kwargs["icon"] = str(ico)
+
+exe = EXE(**exe_kwargs)
+
+# ---------- collect --------------------------------------------------------
+
+coll = COLLECT(
+    exe,
+    a.binaries,
+    a.datas,
+    strip=False,
+    upx=False,
+    name="8cut",
+)
+
+# ---------- macOS .app bundle (only on Darwin) -----------------------------
+
+if system == "Darwin":
+    app = BUNDLE(
+        coll,
+        name="8cut.app",
+        icon=str(base / "assets" / "logo.png"),
+        bundle_identifier="com.8cut.app",
+        info_plist={
+            "CFBundleDisplayName": "8cut",
+            "CFBundleShortVersionString": "1.0.0",
+            "NSHighResolutionCapable": True,
+            "LSMinimumSystemVersion": "11.0",
+        },
+    )

README.md

@@ -1,32 +1,63 @@
 # 8-cut
 
-[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://github.com/ethanfel/8-cut/blob/master/LICENSE)
+<p align="center">
+  <img src="assets/logo.svg" alt="8-cut — 8-second clips for foley datasets" width="720">
+</p>
 
-**Source:** https://github.com/ethanfel/8-cut
+<p align="center">
+  <a href="https://github.com/ethanfel/8-cut/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-GPLv3-blue.svg" alt="License: GPL v3"></a>
+</p>
 
-A desktop tool for cutting 8-second clips from video files, designed for building [SELVA](https://github.com/google-deepmind/selva) datasets.
+A desktop tool for cutting 8-second clips from video files, designed for building foley datasets.
 
 ## Overview
 
-8-cut lets you scrub through a video, mark a cut point, and export a fixed 8-second clip with one keypress. It tracks every export in a local SQLite database so you can resume a session or switch between resolution variants of the same source without duplicating work.
+8-cut lets you scrub through a video, mark a cut point, and export a batch of overlapping 8-second clips with one keypress. It tracks every export in a local SQLite database so you can resume a session without duplicating work.
 
-All clips are exactly 8 seconds — this is a hard constraint of the SELVA format.
+All clips are exactly 8 seconds — the standard length for foley sound datasets.
+
+<p align="center">
+  <img src="assets/segment-diagram.svg" alt="Batch export diagram — 3 overlapping 8-second clips offset by a 3-second spread" width="720">
+</p>
 
 ## Features
 
-- **Frame-accurate scrubbing** — click or drag the timeline; arrow keys and J/K/L for frame-by-frame stepping
-- **Keyboard shortcuts** — J/L step one frame, Shift+J/L step one second, Space/P play/pause, K pause and return to cursor, E export, M jump to next marker
-- **Two export formats** — H.264/AAC MP4 or lossless WebP image sequence (frames + `.wav` audio extracted alongside)
-- **Portrait crop** — crop to 9:16, 4:5, or 1:1 before export; adjustable horizontal crop position
-- **Resize** — scale short side to a fixed pixel size (e.g. 256)
-- **Export history** — timeline markers show previously exported clips; fuzzy filename matching detects resolution variants of the same file (e.g. `_2160p` vs `_1080p`)
-- **Mask generation** — generate binary foreground masks per-frame using SAM2 (segmentation) or Depth Anything V2 (depth-based), via a bundled venv
-- **Playlist** — drag-and-drop multiple files; duplicates are ignored
+- **Frame-accurate scrubbing** — click or drag the timeline; arrow keys and J/L for frame-by-frame, Shift for 1-second steps
+- **Batch export** — export multiple overlapping clips per cut point with configurable count and spread offset
+- **Two export formats** — H.264 MP4 with lossless PCM audio, or WebP image sequence (frames + `.wav`)
+- **Portrait crop** — crop to 9:16, 4:5, or 1:1 before export; click the video or crop bar to reposition
+- **Random portrait** — optionally apply a random portrait crop to a subset of each batch
+- **Resize** — scale short side to a fixed pixel size (e.g. 512)
+- **Sound annotation** — label and category fields saved to the clip database; label also written to `dataset.json`
+- **Export history** — timeline markers show previously exported clips; double-click to enter overwrite mode; right-click to delete
+- **End-frame preview** — floating window shows the last frame of the selection region
+- **Playlist** — drag-and-drop or use the Open Files button; right-click to remove items
+- **Playback loop** — plays the exact selection region on loop so you can preview what will be exported
+- **Group operations** — delete or overwrite acts on all sub-clips in a batch, not just one
+- **Profiles** — switch between independent marker sets (e.g. "landscape" vs "portrait") for the same video
+
+## Keyboard shortcuts
+
+| Key | Action |
+|-----|--------|
+| `Left` / `J` | Step back 1 frame |
+| `Right` / `L` | Step forward 1 frame |
+| `Shift+Left` / `Shift+J` | Step back 1 second |
+| `Shift+Right` / `Shift+L` | Step forward 1 second |
+| `Space` / `P` | Toggle play/pause |
+| `K` | Pause and snap to cursor |
+| `E` | Export |
+| `M` | Jump to next marker (wraps) |
+| `N` | Next file in playlist |
+| `G` | Toggle cursor lock |
+| `?` / `F1` | Show keyboard shortcuts |
+
+Shortcuts are suppressed when a text field has focus.
 
 ## Requirements
 
 - Python 3.11+
-- `ffmpeg` in `PATH`
+- `ffmpeg` on `PATH`
 - PyQt6
 - python-mpv (requires libmpv)
 
@@ -34,15 +65,15 @@ All clips are exactly 8 seconds — this is a hard constraint of the SELVA forma
 pip install -r requirements.txt
 ```
 
-For mask generation tools, additional dependencies (PyTorch, transformers, segment-anything-2, opencv) are installed into `~/.8cut/venv/` via the Settings dialog.
-
 ### Platform notes
 
-**Linux** — install libmpv via your package manager (`apt install libmpv-dev` / `pacman -S mpv`).
+| Platform | libmpv |
+|----------|--------|
+| **Linux** | `apt install libmpv-dev` or `pacman -S mpv` |
+| **macOS** | `brew install mpv` |
+| **Windows** | Download `mpv-2.dll` from [mpv Windows builds](https://sourceforge.net/projects/mpv-player-windows/files/libmpv/) and place it in `PATH` or next to `main.py` |
 
-**macOS** — install libmpv via Homebrew: `brew install mpv`.
-
-**Windows** — `python-mpv` requires `mpv-2.dll` in `PATH` or in the same directory as `main.py`. Download it from the [mpv Windows builds](https://sourceforge.net/projects/mpv-player-windows/files/libmpv/) page (pick the latest `mpv-dev-x86_64-*.7z`, extract `mpv-2.dll`). Also ensure `ffmpeg.exe` is in `PATH` (e.g. via [winget](https://winget.run/): `winget install ffmpeg`).
+Windows also needs `ffmpeg.exe` on `PATH` (e.g. `winget install ffmpeg`).
 
 ## Usage
 
@@ -50,49 +81,52 @@ For mask generation tools, additional dependencies (PyTorch, transformers, segme
 python main.py
 ```
 
-Drop a video onto the playlist or use the file picker. Scrub to your cut point, set the output folder and clip name, then press **Export** (or `E`).
+Drop videos onto the queue or click **+ Open Files**. Scrub to your cut point, then press **Export** (or `E`).
 
-### Export formats
+### Export layout
 
-| Format | Output |
-|--------|--------|
-| MP4 | `<folder>/<name>_NNN.mp4` — H.264 video + AAC audio |
-| WebP sequence | `<folder>/<name>_NNN/frame_%04d.webp` — lossless WebP frames + `<name>_NNN.wav` PCM audio |
-
-### Keyboard shortcuts
-
-| Key | Action |
-|-----|--------|
-| `←` / `J` | Step back 1 frame |
-| `→` / `L` | Step forward 1 frame |
-| `Shift+←` / `Shift+J` | Step back 1 second |
-| `Shift+→` / `Shift+L` | Step forward 1 second |
-| `Space` / `P` | Toggle play/pause |
-| `K` | Pause and snap video to cursor |
-| `E` | Export clip |
-| `M` | Jump to next export marker (wraps) |
-
-Arrow keys and J/K/L are ignored when a text field has focus.
-
-### Mask generation tools
-
-> **Warning:** The mask generation feature is untested and may not work reliably. For production use, consider [ComfyUI](https://github.com/comfyanonymous/ComfyUI) instead.
-
-Two standalone scripts live in `tools/`. They are run by the app via a managed venv but can also be called directly:
+Each export creates a group subfolder containing the overlapping sub-clips:
 
 ```
-python tools/sam_masks.py  --input clip.mp4 --output masks_dir/
-python tools/depth_masks.py --input clip.mp4 --output masks_dir/
+output/
+  clip_001/
+    clip_001_0.mp4      # starts at cursor
+    clip_001_1.mp4      # starts at cursor + spread
+    clip_001_2.mp4      # starts at cursor + 2 * spread
+  clip_002/
+    ...
 ```
 
-Both output one binary PNG per frame (`frame_0000.png`, …) where white = foreground.
+With WebP sequence format, each sub-clip becomes a directory of frames plus a `.wav`:
 
-- **SAM2** (`sam_masks.py`) — uses `facebook/sam2-hiera-large`; center-point prompt propagated across all frames
-- **Depth Anything V2** (`depth_masks.py`) — uses `depth-anything/Depth-Anything-V2-Large-hf`; Otsu threshold on the depth map
+```
+output/
+  clip_001/
+    clip_001_0/
+      frame_0001.webp
+      frame_0002.webp
+      ...
+    clip_001_0.wav
+```
+
+### Sound annotation
+
+Set a **Label** (e.g. "dog barking") and **Category** (Human / Animal / Vehicle / Tool / Music / Nature / Sport / Other) before exporting. These are saved to:
+
+- `dataset.json` in the export folder — one entry per clip with `path` and `label`
+- The SQLite database — label and category, for recall when you revisit a marker
+
+Labels persist between exports so you can cut many clips of the same class without retyping.
+
+### Overwrite and delete
+
+- **Double-click** a timeline marker to enter overwrite mode — the next export re-encodes all clips in that group to their original paths
+- **Right-click** a marker to delete it from the database
+- The **Delete** button removes all clips in a group from disk, database, and `dataset.json`
 
 ## Database
 
-Export history is stored in `~/.8cut.db` (SQLite). The database records filename, start time, and output path for every clip. When you open a file, 8-cut checks whether a similar filename has been processed before (stripping resolution tags like `_2160p`, `_1080p`, codec tags, etc.) and pre-populates the timeline with existing markers.
+Export history is stored in `~/.8cut.db` (SQLite). The database records filename, start time, output path, label, category, and all encoding settings for every clip. When you open a file, 8-cut matches the filename and pre-populates the timeline with existing markers.
 
 ## Testing
 
@@ -100,7 +134,7 @@ Export history is stored in `~/.8cut.db` (SQLite). The database records filename
 pytest tests/ -v
 ```
 
-38 unit tests covering path builders, ffmpeg command generation, time formatting, and the processed-clips database.
+46 unit tests covering path builders, ffmpeg command generation, time formatting, database operations, group queries, profile isolation, and annotation handling.
 
 ## License
 

assets/logo.svg

@@ -0,0 +1,95 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 200">
+  <defs>
+    <linearGradient id="timeline-bg" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#1e1e1e"/>
+      <stop offset="100%" stop-color="#2a2a2a"/>
+    </linearGradient>
+    <linearGradient id="selection" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#3c82dc" stop-opacity="0.6"/>
+      <stop offset="100%" stop-color="#3c82dc" stop-opacity="0.3"/>
+    </linearGradient>
+    <linearGradient id="eight-grad" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#ffd230"/>
+      <stop offset="100%" stop-color="#e6a800"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Background -->
+  <rect width="720" height="200" rx="12" fill="#161616"/>
+
+  <!-- Timeline track -->
+  <rect x="40" y="100" width="640" height="48" rx="4" fill="url(#timeline-bg)" stroke="#333" stroke-width="1"/>
+
+  <!-- Timeline lane -->
+  <rect x="40" y="112" width="640" height="24" rx="2" fill="#2a2a2a"/>
+
+  <!-- Selection region (8 seconds) -->
+  <rect x="240" y="100" width="140" height="48" rx="2" fill="url(#selection)"/>
+  <line x1="240" y1="100" x2="240" y2="148" stroke="#3c82dc" stroke-width="2" stroke-opacity="0.8"/>
+  <line x1="380" y1="100" x2="380" y2="148" stroke="#3c82dc" stroke-width="2" stroke-opacity="0.8"/>
+
+  <!-- Playhead -->
+  <line x1="240" y1="96" x2="240" y2="152" stroke="#ffd230" stroke-width="2"/>
+  <polygon points="234,96 246,96 240,104" fill="#ffd230"/>
+
+  <!-- Ruler ticks -->
+  <g stroke="#555" stroke-width="1">
+    <line x1="80"  y1="100" x2="80"  y2="108"/>
+    <line x1="120" y1="100" x2="120" y2="105"/>
+    <line x1="160" y1="100" x2="160" y2="108"/>
+    <line x1="200" y1="100" x2="200" y2="105"/>
+    <line x1="240" y1="100" x2="240" y2="108"/>
+    <line x1="280" y1="100" x2="280" y2="105"/>
+    <line x1="320" y1="100" x2="320" y2="108"/>
+    <line x1="360" y1="100" x2="360" y2="105"/>
+    <line x1="400" y1="100" x2="400" y2="108"/>
+    <line x1="440" y1="100" x2="440" y2="105"/>
+    <line x1="480" y1="100" x2="480" y2="108"/>
+    <line x1="520" y1="100" x2="520" y2="105"/>
+    <line x1="560" y1="100" x2="560" y2="108"/>
+    <line x1="600" y1="100" x2="600" y2="105"/>
+    <line x1="640" y1="100" x2="640" y2="108"/>
+  </g>
+
+  <!-- Export markers -->
+  <g>
+    <line x1="130" y1="100" x2="130" y2="148" stroke="#dc3c3c" stroke-width="2"/>
+    <rect x="130" y="102" width="14" height="12" rx="1" fill="#c83232"/>
+    <text x="137" y="112" font-family="sans-serif" font-size="9" fill="white" text-anchor="middle">1</text>
+  </g>
+  <g>
+    <line x1="390" y1="100" x2="390" y2="148" stroke="#dc3c3c" stroke-width="2"/>
+    <rect x="390" y="102" width="14" height="12" rx="1" fill="#c83232"/>
+    <text x="397" y="112" font-family="sans-serif" font-size="9" fill="white" text-anchor="middle">2</text>
+  </g>
+  <g>
+    <line x1="540" y1="100" x2="540" y2="148" stroke="#dc3c3c" stroke-width="2"/>
+    <rect x="540" y="102" width="14" height="12" rx="1" fill="#c83232"/>
+    <text x="547" y="112" font-family="sans-serif" font-size="9" fill="white" text-anchor="middle">3</text>
+  </g>
+
+  <!-- "8" numeral -->
+  <text x="100" y="72" font-family="'Helvetica Neue', Helvetica, Arial, sans-serif" font-size="72" font-weight="bold" fill="url(#eight-grad)">8</text>
+
+  <!-- "-cut" text -->
+  <text x="148" y="70" font-family="'Helvetica Neue', Helvetica, Arial, sans-serif" font-size="48" font-weight="300" fill="#cccccc">-cut</text>
+
+  <!-- Scissors icon near playhead -->
+  <g transform="translate(296, 82) scale(0.7)" fill="none" stroke="#999" stroke-width="2" stroke-linecap="round">
+    <circle cx="5" cy="5" r="4" />
+    <circle cx="5" cy="19" r="4" />
+    <line x1="9" y1="7" x2="20" y2="17"/>
+    <line x1="9" y1="17" x2="20" y2="7"/>
+  </g>
+
+  <!-- Tagline -->
+  <text x="400" y="72" font-family="'Helvetica Neue', Helvetica, Arial, sans-serif" font-size="14" fill="#777">8-second clips for foley datasets</text>
+
+  <!-- Duration label in selection -->
+  <text x="310" y="130" font-family="'Courier New', monospace" font-size="13" fill="#aad4ff" text-anchor="middle" opacity="0.9">8.0s</text>
+
+  <!-- Time labels -->
+  <text x="40"  y="166" font-family="'Courier New', monospace" font-size="10" fill="#666">0:00</text>
+  <text x="230" y="166" font-family="'Courier New', monospace" font-size="10" fill="#e6a800">1:15</text>
+  <text x="640" y="166" font-family="'Courier New', monospace" font-size="10" fill="#666">5:00</text>
+</svg>

assets/segment-diagram.svg

@@ -0,0 +1,62 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 260">
+  <defs>
+    <marker id="al" markerWidth="6" markerHeight="4" refX="0" refY="2" orient="auto">
+      <path d="M6,0 L0,2 L6,4" fill="#777"/>
+    </marker>
+    <marker id="ar" markerWidth="6" markerHeight="4" refX="6" refY="2" orient="auto">
+      <path d="M0,0 L6,2 L0,4" fill="#777"/>
+    </marker>
+    <marker id="gl" markerWidth="6" markerHeight="4" refX="0" refY="2" orient="auto">
+      <path d="M6,0 L0,2 L6,4" fill="#e6a800"/>
+    </marker>
+    <marker id="gr" markerWidth="6" markerHeight="4" refX="6" refY="2" orient="auto">
+      <path d="M0,0 L6,2 L0,4" fill="#e6a800"/>
+    </marker>
+  </defs>
+
+  <!-- Background -->
+  <rect width="720" height="260" rx="12" fill="#161616"/>
+
+  <!-- Cursor / playhead -->
+  <text x="110" y="32" font-family="'Courier New', monospace" font-size="11" fill="#e6a800" text-anchor="middle">cursor</text>
+  <polygon points="104,38 116,38 110,46" fill="#ffd230"/>
+  <line x1="110" y1="46" x2="110" y2="195" stroke="#ffd230" stroke-width="1.5" stroke-dasharray="4,3"/>
+
+  <!-- Dashed guide lines at clip start offsets -->
+  <line x1="212" y1="56" x2="212" y2="195" stroke="#444" stroke-width="1" stroke-dasharray="2,4"/>
+  <line x1="314" y1="56" x2="314" y2="195" stroke="#444" stroke-width="1" stroke-dasharray="2,4"/>
+
+  <!-- Clip 0 -->
+  <text x="20" y="74" font-family="'Courier New', monospace" font-size="10" fill="#999">clip_001_0</text>
+  <rect x="110" y="56" width="272" height="28" rx="4" fill="#3c82dc" opacity="0.9"/>
+  <text x="246" y="74" font-family="'Courier New', monospace" font-size="11" fill="white" text-anchor="middle" opacity="0.9">8s</text>
+
+  <!-- Spread annotation 1 -->
+  <line x1="110" y1="88" x2="110" y2="104" stroke="#666" stroke-width="1"/>
+  <line x1="212" y1="88" x2="212" y2="104" stroke="#666" stroke-width="1"/>
+  <line x1="114" y1="96" x2="208" y2="96" stroke="#777" stroke-width="1" marker-start="url(#al)" marker-end="url(#ar)"/>
+  <text x="161" y="93" font-family="'Courier New', monospace" font-size="9" fill="#999" text-anchor="middle">spread 3s</text>
+
+  <!-- Clip 1 -->
+  <text x="20" y="126" font-family="'Courier New', monospace" font-size="10" fill="#999">clip_001_1</text>
+  <rect x="212" y="108" width="272" height="28" rx="4" fill="#5a9be6" opacity="0.85"/>
+  <text x="348" y="126" font-family="'Courier New', monospace" font-size="11" fill="white" text-anchor="middle" opacity="0.9">8s</text>
+
+  <!-- Spread annotation 2 -->
+  <line x1="212" y1="140" x2="212" y2="156" stroke="#666" stroke-width="1"/>
+  <line x1="314" y1="140" x2="314" y2="156" stroke="#666" stroke-width="1"/>
+  <line x1="216" y1="148" x2="310" y2="148" stroke="#777" stroke-width="1" marker-start="url(#al)" marker-end="url(#ar)"/>
+  <text x="263" y="145" font-family="'Courier New', monospace" font-size="9" fill="#999" text-anchor="middle">spread 3s</text>
+
+  <!-- Clip 2 -->
+  <text x="20" y="178" font-family="'Courier New', monospace" font-size="10" fill="#999">clip_001_2</text>
+  <rect x="314" y="160" width="272" height="28" rx="4" fill="#78b4f0" opacity="0.8"/>
+  <text x="450" y="178" font-family="'Courier New', monospace" font-size="11" fill="white" text-anchor="middle" opacity="0.9">8s</text>
+
+  <!-- Total span annotation -->
+  <line x1="110" y1="198" x2="110" y2="218" stroke="#e6a800" stroke-width="1"/>
+  <line x1="586" y1="198" x2="586" y2="218" stroke="#e6a800" stroke-width="1"/>
+  <line x1="114" y1="210" x2="582" y2="210" stroke="#e6a800" stroke-width="1" marker-start="url(#gl)" marker-end="url(#gr)"/>
+  <text x="348" y="235" font-family="'Courier New', monospace" font-size="12" fill="#e6a800" text-anchor="middle">total span: 14s</text>
+  <text x="348" y="250" font-family="'Courier New', monospace" font-size="10" fill="#666" text-anchor="middle">8 + (n&#x2212;1) &#xd7; spread</text>
+</svg>

assets/social-preview.svg

@@ -0,0 +1,132 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 640">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#141414"/>
+      <stop offset="100%" stop-color="#1a1a1a"/>
+    </linearGradient>
+    <linearGradient id="tl-bg" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#1e1e1e"/>
+      <stop offset="100%" stop-color="#262626"/>
+    </linearGradient>
+    <linearGradient id="sel" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#3c82dc" stop-opacity="0.55"/>
+      <stop offset="100%" stop-color="#3c82dc" stop-opacity="0.2"/>
+    </linearGradient>
+    <linearGradient id="eight" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#ffd230"/>
+      <stop offset="100%" stop-color="#d4a000"/>
+    </linearGradient>
+    <linearGradient id="glow" x1="0.5" y1="0" x2="0.5" y2="1">
+      <stop offset="0%" stop-color="#ffd230" stop-opacity="0.08"/>
+      <stop offset="100%" stop-color="#ffd230" stop-opacity="0"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Background -->
+  <rect width="1280" height="640" fill="url(#bg)"/>
+
+  <!-- Subtle glow behind title -->
+  <ellipse cx="640" cy="200" rx="400" ry="140" fill="url(#glow)"/>
+
+  <!-- Title: "8" -->
+  <text x="440" y="250" font-family="'Helvetica Neue', Helvetica, Arial, sans-serif" font-size="180" font-weight="bold" fill="url(#eight)">8</text>
+
+  <!-- Title: "-cut" -->
+  <text x="560" y="244" font-family="'Helvetica Neue', Helvetica, Arial, sans-serif" font-size="110" font-weight="300" fill="#cccccc">-cut</text>
+
+  <!-- Tagline -->
+  <text x="640" y="310" font-family="'Helvetica Neue', Helvetica, Arial, sans-serif" font-size="26" fill="#777" text-anchor="middle">8-second video clips for foley datasets</text>
+
+  <!-- ===== Timeline ===== -->
+
+  <!-- Timeline track -->
+  <rect x="120" y="380" width="1040" height="72" rx="6" fill="url(#tl-bg)" stroke="#333" stroke-width="1"/>
+
+  <!-- Timeline lane -->
+  <rect x="120" y="398" width="1040" height="36" rx="3" fill="#2a2a2a"/>
+
+  <!-- Ruler ticks -->
+  <g stroke="#555" stroke-width="1">
+    <line x1="172" y1="380" x2="172" y2="392"/>
+    <line x1="224" y1="380" x2="224" y2="387"/>
+    <line x1="276" y1="380" x2="276" y2="392"/>
+    <line x1="328" y1="380" x2="328" y2="387"/>
+    <line x1="380" y1="380" x2="380" y2="392"/>
+    <line x1="432" y1="380" x2="432" y2="387"/>
+    <line x1="484" y1="380" x2="484" y2="392"/>
+    <line x1="536" y1="380" x2="536" y2="387"/>
+    <line x1="588" y1="380" x2="588" y2="392"/>
+    <line x1="640" y1="380" x2="640" y2="387"/>
+    <line x1="692" y1="380" x2="692" y2="392"/>
+    <line x1="744" y1="380" x2="744" y2="387"/>
+    <line x1="796" y1="380" x2="796" y2="392"/>
+    <line x1="848" y1="380" x2="848" y2="387"/>
+    <line x1="900" y1="380" x2="900" y2="392"/>
+    <line x1="952" y1="380" x2="952" y2="387"/>
+    <line x1="1004" y1="380" x2="1004" y2="392"/>
+    <line x1="1056" y1="380" x2="1056" y2="387"/>
+    <line x1="1108" y1="380" x2="1108" y2="392"/>
+  </g>
+
+  <!-- Selection region -->
+  <rect x="460" y="380" width="220" height="72" rx="2" fill="url(#sel)"/>
+  <line x1="460" y1="380" x2="460" y2="452" stroke="#3c82dc" stroke-width="2" stroke-opacity="0.8"/>
+  <line x1="680" y1="380" x2="680" y2="452" stroke="#3c82dc" stroke-width="2" stroke-opacity="0.8"/>
+
+  <!-- Playhead -->
+  <line x1="460" y1="372" x2="460" y2="456" stroke="#ffd230" stroke-width="2.5"/>
+  <polygon points="452,372 468,372 460,384" fill="#ffd230"/>
+
+  <!-- Duration label -->
+  <text x="570" y="422" font-family="'Courier New', monospace" font-size="18" fill="#aad4ff" text-anchor="middle" opacity="0.8">8.0s</text>
+
+  <!-- Export markers -->
+  <g>
+    <line x1="260" y1="380" x2="260" y2="452" stroke="#dc3c3c" stroke-width="2"/>
+    <rect x="260" y="383" width="18" height="15" rx="2" fill="#c83232"/>
+    <text x="269" y="395" font-family="sans-serif" font-size="11" fill="white" text-anchor="middle" font-weight="bold">1</text>
+  </g>
+  <g>
+    <line x1="700" y1="380" x2="700" y2="452" stroke="#dc3c3c" stroke-width="2"/>
+    <rect x="700" y="383" width="18" height="15" rx="2" fill="#c83232"/>
+    <text x="709" y="395" font-family="sans-serif" font-size="11" fill="white" text-anchor="middle" font-weight="bold">2</text>
+  </g>
+  <g>
+    <line x1="940" y1="380" x2="940" y2="452" stroke="#dc3c3c" stroke-width="2"/>
+    <rect x="940" y="383" width="18" height="15" rx="2" fill="#c83232"/>
+    <text x="949" y="395" font-family="sans-serif" font-size="11" fill="white" text-anchor="middle" font-weight="bold">3</text>
+  </g>
+
+  <!-- Scissors icon -->
+  <g transform="translate(554, 356) scale(0.9)" fill="none" stroke="#999" stroke-width="2" stroke-linecap="round">
+    <circle cx="5" cy="5" r="4"/>
+    <circle cx="5" cy="19" r="4"/>
+    <line x1="9" y1="7" x2="20" y2="17"/>
+    <line x1="9" y1="17" x2="20" y2="7"/>
+  </g>
+
+  <!-- Time labels below timeline -->
+  <text x="120" y="476" font-family="'Courier New', monospace" font-size="13" fill="#555">0:00</text>
+  <text x="448" y="476" font-family="'Courier New', monospace" font-size="13" fill="#e6a800">2:30</text>
+  <text x="1110" y="476" font-family="'Courier New', monospace" font-size="13" fill="#555">8:20</text>
+
+  <!-- ===== Feature pills ===== -->
+  <g font-family="'Helvetica Neue', Helvetica, Arial, sans-serif" font-size="15">
+    <!-- Pill backgrounds -->
+    <rect x="260" y="520" width="120" height="30" rx="15" fill="#222" stroke="#444" stroke-width="1"/>
+    <rect x="400" y="520" width="130" height="30" rx="15" fill="#222" stroke="#444" stroke-width="1"/>
+    <rect x="550" y="520" width="120" height="30" rx="15" fill="#222" stroke="#444" stroke-width="1"/>
+    <rect x="690" y="520" width="140" height="30" rx="15" fill="#222" stroke="#444" stroke-width="1"/>
+    <rect x="850" y="520" width="130" height="30" rx="15" fill="#222" stroke="#444" stroke-width="1"/>
+
+    <!-- Pill text -->
+    <text x="320" y="540" fill="#aaa" text-anchor="middle">Batch export</text>
+    <text x="465" y="540" fill="#aaa" text-anchor="middle">Portrait crop</text>
+    <text x="610" y="540" fill="#aaa" text-anchor="middle">Annotation</text>
+    <text x="760" y="540" fill="#aaa" text-anchor="middle">Fuzzy matching</text>
+    <text x="915" y="540" fill="#aaa" text-anchor="middle">WebP + WAV</text>
+  </g>
+
+  <!-- Bottom border accent -->
+  <rect x="0" y="636" width="1280" height="4" fill="#ffd230" opacity="0.3"/>
+</svg>

docs/plans/2026-04-14-keyframe-crop-modes-design.md

@@ -0,0 +1,51 @@
+# Keyframe crop modes design
+
+## Problem
+
+Currently, crop keyframes only store position (time, center). The random portrait and random square checkboxes apply globally to the entire batch. When a batch spans a scene change (e.g. wide landscape to close-up), portrait crop may only make sense for part of the span.
+
+## Solution
+
+Extend keyframes to snapshot the full crop state — position, ratio, and random crop flags — so each sub-clip in a batch inherits crop settings from the latest keyframe at or before its start time.
+
+## Keyframe data
+
+Expand from `(time, center)` to `(time, center, ratio, rand_portrait, rand_square)`:
+
+- `time` (float) — absolute time in seconds
+- `center` (float) — horizontal crop position, 0.0 to 1.0
+- `ratio` (str | None) — portrait combo value: `None`, `"9:16"`, `"4:5"`, or `"1:1"`
+- `rand_portrait` (bool) — random portrait checkbox state
+- `rand_square` (bool) — random square checkbox state
+
+## Setting keyframes
+
+Same interaction as today: click the crop bar while in lock mode. The click now snapshots the current center, portrait combo selection, rand_portrait checkbox, and rand_square checkbox into the keyframe.
+
+## Export application
+
+For each sub-clip job:
+
+1. Find the latest keyframe where `kt <= start_time + 0.05`.
+2. Apply its `center` and `ratio` to the job.
+3. Collect the effective `rand_portrait` and `rand_square` flags.
+4. After all keyframes are resolved, apply random crop selection only to sub-clips whose effective flags are set. The random selection (`n_random = max(1, eligible_count // 3)`) operates within each flag group independently.
+
+When no keyframes exist, behavior is unchanged (global checkboxes apply to all clips).
+
+## Timeline diamond colors
+
+Each keyframe diamond on the timeline is color-coded by its random crop flags:
+
+- No random flags — gold (current color, `#ffb400`)
+- Portrait only — red (`QColor(220, 60, 60)`)
+- Square only — blue (`QColor(60, 180, 220)`)
+- Both — split diamond: left half red, right half blue
+
+## Playback preview in lock mode
+
+When scrubbing in lock mode, `_on_seek_changed` already updates the crop bar preview from keyframes. This extends to also update the portrait combo and random checkboxes to reflect the effective state at the current playback position, so the user sees what each region's settings are.
+
+## Clearing
+
+Toggling lock off clears all keyframes (existing behavior, unchanged).

docs/plans/2026-04-14-keyframe-crop-modes-implementation.md

@@ -0,0 +1,634 @@
+# Keyframe Crop Modes Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Extend crop keyframes to snapshot ratio and random crop flags, so different sub-clips in a batch inherit different crop settings based on timeline position.
+
+**Architecture:** Widen the keyframe tuple from `(time, center)` to `(time, center, ratio, rand_portrait, rand_square)`. All existing keyframe code paths (set, delete, clear, render, apply-at-export, preview-on-scrub) are updated to carry and use the new fields. Diamond rendering on the timeline uses color to indicate which random flags are set.
+
+**Tech Stack:** Python, PyQt6 (QPainter for diamonds)
+
+---
+
+### Task 1: Add a helper to resolve the effective keyframe at a given time
+
+The keyframe lookup pattern (iterate sorted list, take latest where `kt <= t + 0.05`) is repeated 3 times in main.py. Extract it as a pure function so we can test it and reuse it cleanly with the new wider tuple.
+
+**Files:**
+- Modify: `main.py:48-53` (module-level functions area)
+- Test: `tests/test_utils.py`
+
+**Step 1: Write the failing tests**
+
+Add to `tests/test_utils.py`:
+
+```python
+from main import resolve_keyframe
+
+def test_resolve_keyframe_empty():
+    assert resolve_keyframe([], 5.0) is None
+
+def test_resolve_keyframe_before_first():
+    kfs = [(3.0, 0.5, None, False, False)]
+    assert resolve_keyframe(kfs, 1.0) is None
+
+def test_resolve_keyframe_exact():
+    kfs = [(2.0, 0.3, "9:16", True, False)]
+    assert resolve_keyframe(kfs, 2.0) == (2.0, 0.3, "9:16", True, False)
+
+def test_resolve_keyframe_between():
+    kfs = [
+        (1.0, 0.2, None, False, False),
+        (5.0, 0.8, "1:1", False, True),
+    ]
+    assert resolve_keyframe(kfs, 3.0) == (1.0, 0.2, None, False, False)
+
+def test_resolve_keyframe_after_last():
+    kfs = [
+        (1.0, 0.2, None, False, False),
+        (5.0, 0.8, "1:1", False, True),
+    ]
+    assert resolve_keyframe(kfs, 10.0) == (5.0, 0.8, "1:1", False, True)
+
+def test_resolve_keyframe_tolerance():
+    kfs = [(4.0, 0.5, None, True, True)]
+    # 4.0 <= 3.96 + 0.05 = 4.01, so it should match
+    assert resolve_keyframe(kfs, 3.96) == (4.0, 0.5, None, True, True)
+```
+
+**Step 2: Run tests to verify they fail**
+
+Run: `pytest tests/test_utils.py -k resolve_keyframe -v`
+Expected: FAIL (ImportError — function does not exist yet)
+
+**Step 3: Write the implementation**
+
+Add to `main.py` after the `format_time` function (around line 53):
+
+```python
+def resolve_keyframe(
+    keyframes: list[tuple[float, float, str | None, bool, bool]],
+    t: float,
+    tolerance: float = 0.05,
+) -> tuple[float, float, str | None, bool, bool] | None:
+    """Return the latest keyframe at or before *t*, or None."""
+    result = None
+    for kf in keyframes:
+        if kf[0] <= t + tolerance:
+            result = kf
+        else:
+            break
+    return result
+```
+
+**Step 4: Run tests to verify they pass**
+
+Run: `pytest tests/test_utils.py -k resolve_keyframe -v`
+Expected: 6 PASS
+
+**Step 5: Commit**
+
+```bash
+git add main.py tests/test_utils.py
+git commit -m "feat: add resolve_keyframe helper for widened keyframe tuples"
+```
+
+---
+
+### Task 2: Widen keyframe tuple and update storage
+
+Change `_crop_keyframes` from `list[tuple[float, float]]` to `list[tuple[float, float, str | None, bool, bool]]` in both `TimelineWidget` and `MainWindow`. Update `set_crop_keyframes` signature.
+
+**Files:**
+- Modify: `main.py:735` (TimelineWidget._crop_keyframes)
+- Modify: `main.py:786-787` (TimelineWidget.set_crop_keyframes)
+- Modify: `main.py:1755` (MainWindow._crop_keyframes)
+
+**Step 1: Update TimelineWidget**
+
+At line 735, change:
+```python
+self._crop_keyframes: list[tuple[float, float]] = []  # [(time, center)]
+```
+to:
+```python
+self._crop_keyframes: list[tuple[float, float, str | None, bool, bool]] = []
+```
+
+At lines 786-787, change:
+```python
+def set_crop_keyframes(self, kfs: list[tuple[float, float]]) -> None:
+    self._crop_keyframes = kfs
+```
+to:
+```python
+def set_crop_keyframes(self, kfs: list[tuple[float, float, str | None, bool, bool]]) -> None:
+    self._crop_keyframes = kfs
+```
+
+**Step 2: Update MainWindow**
+
+At line 1755, change:
+```python
+self._crop_keyframes: list[tuple[float, float]] = []  # [(time, center), ...] sorted
+```
+to:
+```python
+self._crop_keyframes: list[tuple[float, float, str | None, bool, bool]] = []  # sorted by time
+```
+
+**Step 3: Run existing tests**
+
+Run: `pytest tests/ -v`
+Expected: All 46 + 6 new = 52 PASS (no existing tests touch keyframes directly)
+
+**Step 4: Commit**
+
+```bash
+git add main.py
+git commit -m "refactor: widen keyframe tuple to carry ratio and random flags"
+```
+
+---
+
+### Task 3: Update keyframe creation to snapshot crop state
+
+When the user clicks the crop bar in lock mode, snapshot the current ratio, rand_portrait, and rand_square into the keyframe.
+
+**Files:**
+- Modify: `main.py:2519-2538` (_on_crop_click lock-mode branch)
+
+**Step 1: Update the keyframe creation code**
+
+At lines 2525-2532, change:
+```python
+            self._crop_keyframes = [
+                (t, c) for t, c in self._crop_keyframes
+                if abs(t - play_t) > 0.05
+            ]
+            self._crop_keyframes.append((play_t, frac))
+            self._crop_keyframes.sort()
+            self._timeline.set_crop_keyframes(self._crop_keyframes)
+            _log(f"Crop keyframe: t={play_t:.2f}s center={frac:.3f} ({len(self._crop_keyframes)} total)")
+```
+to:
+```python
+            ratio_text = self._cmb_portrait.currentText()
+            kf_ratio = None if ratio_text == "Off" else ratio_text
+            kf_rand_p = self._chk_rand_portrait.isChecked()
+            kf_rand_s = self._chk_rand_square.isChecked()
+            self._crop_keyframes = [
+                kf for kf in self._crop_keyframes
+                if abs(kf[0] - play_t) > 0.05
+            ]
+            self._crop_keyframes.append((play_t, frac, kf_ratio, kf_rand_p, kf_rand_s))
+            self._crop_keyframes.sort()
+            self._timeline.set_crop_keyframes(self._crop_keyframes)
+            _log(f"Crop keyframe: t={play_t:.2f}s center={frac:.3f} ratio={kf_ratio} rp={kf_rand_p} rs={kf_rand_s} ({len(self._crop_keyframes)} total)")
+```
+
+**Step 2: Update keyframe deletion filter**
+
+At lines 2356-2357, change:
+```python
+        self._crop_keyframes = [
+            (t, c) for t, c in self._crop_keyframes
+            if abs(t - time) > 0.05
+        ]
+```
+to:
+```python
+        self._crop_keyframes = [
+            kf for kf in self._crop_keyframes
+            if abs(kf[0] - time) > 0.05
+        ]
+```
+
+**Step 3: Run existing tests**
+
+Run: `pytest tests/ -v`
+Expected: All 52 PASS
+
+**Step 4: Commit**
+
+```bash
+git add main.py
+git commit -m "feat: snapshot ratio and random flags into crop keyframes"
+```
+
+---
+
+### Task 4: Update export to apply full keyframe state
+
+Replace the keyframe application loop and random crop logic in `_on_export` to use the new fields.
+
+**Files:**
+- Modify: `main.py:2754-2782` (keyframe application + random crop logic in _on_export)
+- Test: `tests/test_utils.py`
+
+**Step 1: Write a test for the export keyframe resolution logic**
+
+Add to `tests/test_utils.py`:
+
+```python
+from main import apply_keyframes_to_jobs
+
+def test_apply_keyframes_no_keyframes():
+    jobs = [(0.0, "/out/a", None, 0.5), (3.0, "/out/b", None, 0.5)]
+    result = apply_keyframes_to_jobs(jobs, [], base_center=0.5, base_ratio=None,
+                                     base_rand_p=True, base_rand_s=False)
+    # No keyframes: jobs get base values; rand flags come from base
+    assert result == [
+        (0.0, "/out/a", None, 0.5, True, False),
+        (3.0, "/out/b", None, 0.5, True, False),
+    ]
+
+def test_apply_keyframes_with_keyframes():
+    kfs = [
+        (0.0, 0.3, "9:16", True, False),
+        (4.0, 0.7, None, False, True),
+    ]
+    jobs = [
+        (0.0, "/out/a", None, 0.5),
+        (3.0, "/out/b", None, 0.5),
+        (6.0, "/out/c", None, 0.5),
+    ]
+    result = apply_keyframes_to_jobs(jobs, kfs, base_center=0.5, base_ratio=None,
+                                     base_rand_p=False, base_rand_s=False)
+    assert result == [
+        (0.0, "/out/a", "9:16", 0.3, True, False),
+        (3.0, "/out/b", "9:16", 0.3, True, False),
+        (6.0, "/out/c", None, 0.7, False, True),
+    ]
+
+def test_apply_keyframes_before_first_uses_base():
+    kfs = [(5.0, 0.8, "1:1", False, True)]
+    jobs = [(1.0, "/out/a", None, 0.5)]
+    result = apply_keyframes_to_jobs(jobs, kfs, base_center=0.5, base_ratio="4:5",
+                                     base_rand_p=True, base_rand_s=False)
+    assert result == [(1.0, "/out/a", "4:5", 0.5, True, False)]
+```
+
+**Step 2: Run tests to verify they fail**
+
+Run: `pytest tests/test_utils.py -k apply_keyframes -v`
+Expected: FAIL (ImportError)
+
+**Step 3: Write the apply_keyframes_to_jobs function**
+
+Add to `main.py` after `resolve_keyframe`:
+
+```python
+def apply_keyframes_to_jobs(
+    jobs: list[tuple[float, str, str | None, float]],
+    keyframes: list[tuple[float, float, str | None, bool, bool]],
+    base_center: float,
+    base_ratio: str | None,
+    base_rand_p: bool,
+    base_rand_s: bool,
+) -> list[tuple[float, str, str | None, float, bool, bool]]:
+    """Resolve each job's crop state from keyframes, returning widened tuples.
+
+    Returns list of (start, path, ratio, center, rand_portrait, rand_square).
+    """
+    result = []
+    for s, o, _r, _c in jobs:
+        kf = resolve_keyframe(keyframes, s)
+        if kf is not None:
+            _, center, ratio, rp, rs = kf
+        else:
+            center, ratio, rp, rs = base_center, base_ratio, base_rand_p, base_rand_s
+        result.append((s, o, ratio, center, rp, rs))
+    return result
+```
+
+**Step 4: Run tests to verify they pass**
+
+Run: `pytest tests/test_utils.py -k apply_keyframes -v`
+Expected: 3 PASS
+
+**Step 5: Update _on_export to use the new functions**
+
+Replace lines 2754-2782 (the keyframe application block + random crop block) with:
+
+```python
+            # Apply crop keyframes (or fall back to base state).
+            rand_portrait = self._chk_rand_portrait.isChecked()
+            rand_square = self._chk_rand_square.isChecked()
+            widened = apply_keyframes_to_jobs(
+                jobs, self._crop_keyframes,
+                base_center=base_center, base_ratio=base_ratio,
+                base_rand_p=rand_portrait, base_rand_s=rand_square,
+            )
+
+            # Random crop: for each clip whose effective flags are set,
+            # ~1 in 3 gets a random ratio applied.
+            final_jobs = []
+            # Collect indices eligible for random crop, grouped by flag combo.
+            portrait_eligible = [i for i, w in enumerate(widened) if w[4]]
+            square_eligible = [i for i, w in enumerate(widened) if w[5]]
+            rand_indices: set[int] = set()
+            if portrait_eligible and n_clips > 1:
+                n = max(1, len(portrait_eligible) // 3)
+                rand_indices.update(random.sample(portrait_eligible, min(n, len(portrait_eligible))))
+            if square_eligible and n_clips > 1:
+                n = max(1, len(square_eligible) // 3)
+                rand_indices.update(random.sample(square_eligible, min(n, len(square_eligible))))
+
+            for i, (s, o, ratio, center, rp, rs) in enumerate(widened):
+                if i in rand_indices:
+                    pool = []
+                    if rp:
+                        pool.append("9:16")
+                    if rs:
+                        pool.append("1:1")
+                    if pool:
+                        ratio = random.choice(pool)
+                jobs.append((s, o, ratio, center))
+
+            # Replace jobs with the resolved list.
+            jobs = jobs[n_clips:]  # drop the original entries, keep the new ones
+```
+
+Note: `jobs` was built with `n_clips` entries in the loop above. We append resolved entries and then slice off the originals.
+
+Actually, a cleaner rewrite of the tail — replace the entire block from the keyframe comment through the random crop block with:
+
+```python
+            # Apply crop keyframes (or fall back to base state).
+            rand_portrait = self._chk_rand_portrait.isChecked()
+            rand_square = self._chk_rand_square.isChecked()
+            widened = apply_keyframes_to_jobs(
+                jobs, self._crop_keyframes,
+                base_center=base_center, base_ratio=base_ratio,
+                base_rand_p=rand_portrait, base_rand_s=rand_square,
+            )
+
+            # Random crop: eligible clips (per their keyframe flags) have
+            # ~1 in 3 chance of getting a random ratio applied.
+            portrait_eligible = [i for i, w in enumerate(widened) if w[4]]
+            square_eligible = [i for i, w in enumerate(widened) if w[5]]
+            rand_indices: dict[int, list[str]] = {}
+            if portrait_eligible and n_clips > 1:
+                n = max(1, len(portrait_eligible) // 3)
+                for i in random.sample(portrait_eligible, min(n, len(portrait_eligible))):
+                    rand_indices.setdefault(i, []).append("9:16")
+            if square_eligible and n_clips > 1:
+                n = max(1, len(square_eligible) // 3)
+                for i in random.sample(square_eligible, min(n, len(square_eligible))):
+                    rand_indices.setdefault(i, []).append("1:1")
+
+            jobs = []
+            for i, (s, o, ratio, center, _rp, _rs) in enumerate(widened):
+                if i in rand_indices:
+                    ratio = random.choice(rand_indices[i])
+                jobs.append((s, o, ratio, center))
+```
+
+**Step 6: Run all tests**
+
+Run: `pytest tests/ -v`
+Expected: All PASS
+
+**Step 7: Commit**
+
+```bash
+git add main.py tests/test_utils.py
+git commit -m "feat: apply keyframe crop modes during export"
+```
+
+---
+
+### Task 5: Update diamond rendering with color coding
+
+Color-code timeline keyframe diamonds based on their random flags.
+
+**Files:**
+- Modify: `main.py:898-910` (TimelineWidget.paintEvent keyframe diamond section)
+
+**Step 1: Replace the diamond rendering block**
+
+Replace lines 898-910:
+```python
+            # ── crop keyframe diamonds ────────────────────────────────────
+            if self._crop_keyframes and self._duration > 0:
+                for (kt, _kc) in self._crop_keyframes:
+                    kx = int(kt / self._duration * w)
+                    d = 4  # half-size of diamond
+                    ky = h - d - 2  # near bottom of track
+                    diamond = QPolygon([
+                        QPoint(kx, ky - d), QPoint(kx + d, ky),
+                        QPoint(kx, ky + d), QPoint(kx - d, ky),
+                    ])
+                    p.setBrush(QColor(255, 180, 0))
+                    p.setPen(Qt.PenStyle.NoPen)
+                    p.drawPolygon(diamond)
+```
+
+with:
+```python
+            # ── crop keyframe diamonds ────────────────────────────────────
+            if self._crop_keyframes and self._duration > 0:
+                _KF_GOLD = QColor(255, 180, 0)
+                _KF_RED = QColor(220, 60, 60)
+                _KF_BLUE = QColor(60, 180, 220)
+                for kf in self._crop_keyframes:
+                    kt = kf[0]
+                    rp = kf[3] if len(kf) > 3 else False
+                    rs = kf[4] if len(kf) > 4 else False
+                    kx = int(kt / self._duration * w)
+                    d = 4  # half-size of diamond
+                    ky = h - d - 2  # near bottom of track
+                    if rp and rs:
+                        # Split diamond: left half red, right half blue
+                        left = QPolygon([
+                            QPoint(kx, ky - d), QPoint(kx, ky + d),
+                            QPoint(kx - d, ky),
+                        ])
+                        right = QPolygon([
+                            QPoint(kx, ky - d), QPoint(kx + d, ky),
+                            QPoint(kx, ky + d),
+                        ])
+                        p.setPen(Qt.PenStyle.NoPen)
+                        p.setBrush(_KF_RED)
+                        p.drawPolygon(left)
+                        p.setBrush(_KF_BLUE)
+                        p.drawPolygon(right)
+                    else:
+                        diamond = QPolygon([
+                            QPoint(kx, ky - d), QPoint(kx + d, ky),
+                            QPoint(kx, ky + d), QPoint(kx - d, ky),
+                        ])
+                        if rp:
+                            color = _KF_RED
+                        elif rs:
+                            color = _KF_BLUE
+                        else:
+                            color = _KF_GOLD
+                        p.setPen(Qt.PenStyle.NoPen)
+                        p.setBrush(color)
+                        p.drawPolygon(diamond)
+```
+
+**Step 2: Update the context menu keyframe hit detection**
+
+At line 980, change:
+```python
+        for (kt, _kc) in self._crop_keyframes:
+```
+to:
+```python
+        for kf in self._crop_keyframes:
+            kt = kf[0]
+```
+
+And remove the `_kc` reference — use `kf[0]` for `kt` only. The rest of the hit-detection logic stays the same.
+
+**Step 3: Run all tests**
+
+Run: `pytest tests/ -v`
+Expected: All PASS
+
+**Step 4: Manual test**
+
+Launch the app, load a video, enable lock mode, set keyframes with different combinations of random portrait/square. Verify:
+- Gold diamond when no random flags set
+- Red diamond when only portrait
+- Blue diamond when only square
+- Split red/blue when both
+
+**Step 5: Commit**
+
+```bash
+git add main.py
+git commit -m "feat: color-code keyframe diamonds by crop mode"
+```
+
+---
+
+### Task 6: Update lock-mode scrub preview
+
+When scrubbing in lock mode, update the crop bar, overlay, and (visually) the random checkboxes to reflect the effective keyframe state at the playback position.
+
+**Files:**
+- Modify: `main.py:2605-2621` (_on_seek_changed)
+
+**Step 1: Replace the keyframe preview block**
+
+Replace lines 2610-2621:
+```python
+        if self._crop_keyframes:
+            center = self._crop_center
+            for kt, kc in self._crop_keyframes:
+                if kt <= t + 0.05:
+                    center = kc
+                else:
+                    break
+            self._crop_bar.set_crop_center(center)
+            ratio = self._cmb_portrait.currentText()
+            if ratio != "Off":
+                self._mpv.set_crop_overlay(_RATIOS[ratio], center)
+```
+
+with:
+```python
+        if self._crop_keyframes:
+            kf = resolve_keyframe(self._crop_keyframes, t)
+            if kf is not None:
+                _, center, ratio, rp, rs = kf
+                self._crop_bar.set_crop_center(center)
+                if ratio is not None:
+                    self._mpv.set_crop_overlay(_RATIOS[ratio], center)
+                else:
+                    self._update_rand_overlays()
+```
+
+**Step 2: Run all tests**
+
+Run: `pytest tests/ -v`
+Expected: All PASS
+
+**Step 3: Commit**
+
+```bash
+git add main.py
+git commit -m "feat: preview effective keyframe crop state during lock-mode scrub"
+```
+
+---
+
+### Task 7: Update overwrite-mode keyframe application
+
+The overwrite path (lines 2727-2738) also builds jobs. It doesn't currently apply keyframes, but should for consistency.
+
+**Files:**
+- Modify: `main.py:2727-2738` (overwrite branch in _on_export)
+
+**Step 1: Check and update**
+
+After the overwrite jobs are built, apply the same `apply_keyframes_to_jobs` logic if keyframes exist. The overwrite branch builds `jobs` as `(start, path, base_ratio, base_center)` — same shape as the normal path.
+
+Add after line 2738 (`self._overwrite_group = []`):
+
+```python
+            rand_portrait = self._chk_rand_portrait.isChecked()
+            rand_square = self._chk_rand_square.isChecked()
+            if self._crop_keyframes:
+                widened = apply_keyframes_to_jobs(
+                    jobs, self._crop_keyframes,
+                    base_center=base_center, base_ratio=base_ratio,
+                    base_rand_p=rand_portrait, base_rand_s=rand_square,
+                )
+                jobs = [(s, o, r, c) for s, o, r, c, _rp, _rs in widened]
+```
+
+**Step 2: Run all tests**
+
+Run: `pytest tests/ -v`
+Expected: All PASS
+
+**Step 3: Commit**
+
+```bash
+git add main.py
+git commit -m "feat: apply keyframe crop modes in overwrite exports too"
+```
+
+---
+
+### Task 8: Update import in test file and final validation
+
+**Files:**
+- Modify: `tests/test_utils.py:2` (import line)
+
+**Step 1: Update imports**
+
+At line 2, add the new functions to the import:
+```python
+from main import build_export_path, format_time, build_ffmpeg_command, build_sequence_dir, build_audio_extract_command, build_annotation_json_path, upsert_clip_annotation, resolve_keyframe, apply_keyframes_to_jobs
+```
+
+(This should already be done incrementally in Tasks 1 and 4, but verify it's correct.)
+
+**Step 2: Run full test suite**
+
+Run: `pytest tests/ -v`
+Expected: All 55 tests PASS (46 original + 6 resolve_keyframe + 3 apply_keyframes)
+
+**Step 3: Manual integration test**
+
+1. Launch `python main.py`, load a video
+2. Enable lock mode (G or click lock button)
+3. Scrub to a position, enable "1 random portrait", click crop bar → red diamond appears
+4. Scrub forward, disable portrait, enable "1 random square", click crop bar → blue diamond appears
+5. Scrub forward, enable both, click crop bar → split red/blue diamond
+6. Set clip count to 6+, spread to 2s, export
+7. Verify that sub-clips falling in each keyframe region get the correct random crop behavior
+8. Right-click a diamond to delete it — verify it disappears
+
+**Step 4: Commit**
+
+```bash
+git add tests/test_utils.py
+git commit -m "test: verify imports for keyframe crop mode helpers"
+```

requirements.txt

@@ -1,3 +1,4 @@
 PyQt6>=6.4
 python-mpv>=1.0
 pytest>=7.0
+ultralytics>=8.0

setup-windows.ps1

@@ -0,0 +1,59 @@
+# 8-cut Windows setup script
+# Run once: powershell -ExecutionPolicy Bypass -File setup-windows.ps1
+#
+# Prerequisites: Python 3.10+ must be installed and on PATH
+#   https://www.python.org/downloads/
+
+$ErrorActionPreference = "Stop"
+$root = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+Write-Host "=== 8-cut Windows Setup ===" -ForegroundColor Cyan
+
+# ── Python deps ────────────────────────────────────────────
+Write-Host "`nInstalling Python dependencies..."
+pip install PyQt6 python-mpv
+
+# ── libmpv ─────────────────────────────────────────────────
+$mpvDll = Join-Path $root "libmpv-2.dll"
+if (Test-Path $mpvDll) {
+    Write-Host "`nlibmpv-2.dll already present, skipping." -ForegroundColor Green
+} else {
+    Write-Host "`nDownloading libmpv..."
+    $release = Invoke-RestMethod "https://api.github.com/repos/shinchiro/mpv-winbuild-cmake/releases/latest"
+    $asset = $release.assets | Where-Object { $_.name -like "mpv-dev-x86_64-v3-*" } | Select-Object -First 1
+    $tmpFile = Join-Path $root "mpv-dev.7z"
+    Invoke-WebRequest $asset.browser_download_url -OutFile $tmpFile
+    7z x $tmpFile -o"$root\mpv-dev" -y | Out-Null
+    Copy-Item "$root\mpv-dev\libmpv-2.dll" $root
+    Remove-Item $tmpFile -Force
+    Remove-Item "$root\mpv-dev" -Recurse -Force
+    Write-Host "libmpv-2.dll downloaded." -ForegroundColor Green
+}
+
+# ── ffmpeg ─────────────────────────────────────────────────
+$ffmpeg = Join-Path $root "ffmpeg.exe"
+if (Test-Path $ffmpeg) {
+    Write-Host "`nffmpeg.exe already present, skipping." -ForegroundColor Green
+} else {
+    # Check if ffmpeg is on PATH
+    $onPath = Get-Command ffmpeg -ErrorAction SilentlyContinue
+    if ($onPath) {
+        Write-Host "`nffmpeg found on PATH: $($onPath.Source)" -ForegroundColor Green
+    } else {
+        Write-Host "`nDownloading ffmpeg..."
+        $ffUrl = "https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-win64-gpl.zip"
+        $tmpZip = Join-Path $root "ffmpeg.zip"
+        Invoke-WebRequest $ffUrl -OutFile $tmpZip
+        Expand-Archive $tmpZip -DestinationPath "$root\ffmpeg-tmp" -Force
+        $bin = Get-ChildItem -Path "$root\ffmpeg-tmp" -Recurse -Filter ffmpeg.exe | Select-Object -First 1
+        Copy-Item "$($bin.DirectoryName)\ffmpeg.exe" $root
+        Copy-Item "$($bin.DirectoryName)\ffprobe.exe" $root
+        Remove-Item $tmpZip -Force
+        Remove-Item "$root\ffmpeg-tmp" -Recurse -Force
+        Write-Host "ffmpeg.exe downloaded." -ForegroundColor Green
+    }
+}
+
+Write-Host "`n=== Setup complete ===" -ForegroundColor Cyan
+Write-Host "Run 8-cut with: python main.py"
+Write-Host "Or double-click: 8cut.bat"

tests/test_utils.py

@@ -1,24 +1,24 @@
 import tempfile, os, json
-from main import build_export_path, format_time, build_ffmpeg_command, build_mask_output_dir, build_sequence_dir, build_audio_extract_command, build_annotation_json_path, upsert_clip_annotation
-from main import _normalize_filename, ProcessedDB
+from main import build_export_path, format_time, build_ffmpeg_command, build_sequence_dir, build_audio_extract_command, build_annotation_json_path, upsert_clip_annotation, resolve_keyframe, apply_keyframes_to_jobs
+from main import ProcessedDB
 
 
 def test_build_export_path_first():
-    assert build_export_path("/out", "clip", 1) == "/out/clip_001.mp4"
+    assert build_export_path("/out", "clip", 1) == "/out/clip_001/clip_001.mp4"
 
 def test_build_export_path_counter():
-    assert build_export_path("/out", "clip", 42) == "/out/clip_042.mp4"
+    assert build_export_path("/out", "clip", 42) == "/out/clip_042/clip_042.mp4"
 
 def test_build_export_path_deep_counter():
-    assert build_export_path("/out", "shot", 999) == "/out/shot_999.mp4"
+    assert build_export_path("/out", "shot", 999) == "/out/shot_999/shot_999.mp4"
 
 def test_build_export_path_sub():
-    assert build_export_path("/out", "clip", 1, sub=0) == "/out/clip_001_0.mp4"
-    assert build_export_path("/out", "clip", 1, sub=2) == "/out/clip_001_2.mp4"
+    assert build_export_path("/out", "clip", 1, sub=0) == "/out/clip_001/clip_001_0.mp4"
+    assert build_export_path("/out", "clip", 1, sub=2) == "/out/clip_001/clip_001_2.mp4"
 
 def test_build_sequence_dir_sub():
-    assert build_sequence_dir("/out", "clip", 1, sub=0) == "/out/clip_001_0"
-    assert build_sequence_dir("/out", "clip", 1, sub=1) == "/out/clip_001_1"
+    assert build_sequence_dir("/out", "clip", 1, sub=0) == "/out/clip_001/clip_001_0"
+    assert build_sequence_dir("/out", "clip", 1, sub=1) == "/out/clip_001/clip_001_1"
 
 def test_format_time_seconds():
     assert format_time(0.0) == "0:00.0"
@@ -53,63 +53,47 @@ def test_ffmpeg_command_with_resize():
     assert cmd[-1] == "/out/clip_001.mp4"
 
 
-# --- _normalize_filename ---
-
-def test_normalize_strips_extension():
-    assert _normalize_filename("clip.mp4") == "clip"
-
-def test_normalize_strips_resolution():
-    assert _normalize_filename("clip_2160p.mp4") == "clip"
-
-def test_normalize_strips_1080p():
-    assert _normalize_filename("clip_1080p.mkv") == "clip"
-
-def test_normalize_strips_multiple_tags():
-    assert _normalize_filename("show_1080p_HDR.mkv") == "show"
-
-def test_normalize_lowercases():
-    assert _normalize_filename("MyVideo_4K.mp4") == "myvideo"
-
-def test_normalize_collapses_separators():
-    assert _normalize_filename("my__video--2160p.mp4") == "my_video"
-
-
 # --- ProcessedDB ---
 
-def test_db_add_and_find_exact():
+def test_db_add_and_get_markers():
     with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
         path = f.name
     try:
         db = ProcessedDB(path)
         db.add("video.mp4", 12.5, "/out/clip_001.mp4")
-        assert db.find_similar("video.mp4") == "video.mp4"
+        markers = db.get_markers("video.mp4")
+        assert len(markers) == 1
+        assert markers[0][0] == 12.5
     finally:
         os.unlink(path)
 
-def test_db_find_similar_resolution_variant():
+def test_db_exact_match_only():
     with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
         path = f.name
     try:
         db = ProcessedDB(path)
         db.add("episode_s01e01_2160p.mkv", 0.0, "/out/ep_001.mp4")
-        assert db.find_similar("episode_s01e01_1080p.mkv") == "episode_s01e01_2160p.mkv"
+        # Different filename — no match even if similar
+        assert db.get_markers("episode_s01e01_1080p.mkv") == []
+        # Exact filename — match
+        assert len(db.get_markers("episode_s01e01_2160p.mkv")) == 1
     finally:
         os.unlink(path)
 
-def test_db_find_similar_no_match():
+def test_db_no_match():
     with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
         path = f.name
     try:
         db = ProcessedDB(path)
         db.add("alpha.mp4", 0.0, "/out/alpha_001.mp4")
-        assert db.find_similar("completely_different_zzzz.mp4") is None
+        assert db.get_markers("completely_different.mp4") == []
     finally:
         os.unlink(path)
 
 def test_db_disabled_survives_bad_path():
     db = ProcessedDB("/no/such/directory/8cut.db")
     db.add("x.mp4", 0.0, "/out/x_001.mp4")   # must not raise
-    assert db.find_similar("x.mp4") is None
+    assert db.get_markers("x.mp4") == []
 
 def test_db_get_markers_returns_sorted():
     with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
@@ -127,19 +111,6 @@ def test_db_get_markers_returns_sorted():
     finally:
         os.unlink(path)
 
-def test_db_get_markers_fuzzy_match():
-    with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
-        path = f.name
-    try:
-        db = ProcessedDB(path)
-        db.add("show_2160p.mkv", 5.0, "/out/s_001.mp4")
-        markers = db.get_markers("show_1080p.mkv")
-        assert len(markers) == 1
-        assert markers[0][0] == 5.0
-        assert markers[0][2] == "/out/s_001.mp4"
-    finally:
-        os.unlink(path)
-
 def test_db_get_markers_no_match():
     with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
         path = f.name
@@ -182,16 +153,6 @@ def test_ffmpeg_command_portrait_off():
     cmd = build_ffmpeg_command("/in/video.mp4", 0.0, "/out/clip.mp4")
     assert "-vf" not in cmd
 
-def test_mask_output_dir_basic():
-    assert build_mask_output_dir("/out/clip_001.mp4") == "/out/clip_001_masks"
-
-def test_mask_output_dir_mkv():
-    assert build_mask_output_dir("/out/my_clip.mkv") == "/out/my_clip_masks"
-
-def test_mask_output_dir_nested():
-    assert build_mask_output_dir("/a/b/c/shot_042.mp4") == "/a/b/c/shot_042_masks"
-
-
 # --- build_audio_extract_command ---
 
 def test_audio_extract_output_path():
@@ -216,10 +177,10 @@ def test_audio_extract_timing():
 
 
 def test_build_sequence_dir_basic():
-    assert build_sequence_dir("/out", "clip", 1) == "/out/clip_001"
+    assert build_sequence_dir("/out", "clip", 1) == "/out/clip_001/clip_001"
 
 def test_build_sequence_dir_counter():
-    assert build_sequence_dir("/out", "clip", 42) == "/out/clip_042"
+    assert build_sequence_dir("/out", "clip", 42) == "/out/clip_042/clip_042"
 
 def test_ffmpeg_command_image_sequence():
     cmd = build_ffmpeg_command("/in/v.mp4", 0.0, "/out/seq_001", image_sequence=True)
@@ -296,3 +257,184 @@ def test_db_stores_label_and_category():
         assert row == ("dog barking", "Animal")
     finally:
         os.unlink(path)
+
+
+def test_db_get_group_returns_all_sub_clips():
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+        path = f.name
+    try:
+        db = ProcessedDB(path)
+        db.add("video.mp4", 10.0, "/out/clip_001/clip_001_0.mp4")
+        db.add("video.mp4", 10.0, "/out/clip_001/clip_001_1.mp4")
+        db.add("video.mp4", 10.0, "/out/clip_001/clip_001_2.mp4")
+        group = db.get_group("/out/clip_001/clip_001_0.mp4")
+        assert len(group) == 3
+        assert "/out/clip_001/clip_001_0.mp4" in group
+        assert "/out/clip_001/clip_001_2.mp4" in group
+    finally:
+        os.unlink(path)
+
+
+def test_db_get_group_isolates_by_start_time():
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+        path = f.name
+    try:
+        db = ProcessedDB(path)
+        db.add("video.mp4", 10.0, "/out/clip_001/clip_001_0.mp4")
+        db.add("video.mp4", 10.0, "/out/clip_001/clip_001_1.mp4")
+        db.add("video.mp4", 30.0, "/out/clip_002/clip_002_0.mp4")
+        group = db.get_group("/out/clip_001/clip_001_0.mp4")
+        assert len(group) == 2
+    finally:
+        os.unlink(path)
+
+
+def test_db_delete_group_removes_all():
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+        path = f.name
+    try:
+        db = ProcessedDB(path)
+        db.add("video.mp4", 10.0, "/out/clip_001/clip_001_0.mp4")
+        db.add("video.mp4", 10.0, "/out/clip_001/clip_001_1.mp4")
+        db.add("video.mp4", 30.0, "/out/clip_002/clip_002_0.mp4")
+        deleted = db.delete_group("/out/clip_001/clip_001_0.mp4")
+        assert len(deleted) == 2
+        # clip_002 should still exist
+        markers = db.get_markers("video.mp4")
+        assert len(markers) == 1
+        assert markers[0][0] == 30.0
+    finally:
+        os.unlink(path)
+
+
+def test_db_get_group_disabled():
+    db = ProcessedDB("/no/such/directory/8cut.db")
+    assert db.get_group("/out/clip_001.mp4") == []
+
+
+def test_db_delete_group_disabled():
+    db = ProcessedDB("/no/such/directory/8cut.db")
+    assert db.delete_group("/out/clip_001.mp4") == []
+
+
+# --- Profiles ---
+
+def test_db_markers_isolated_by_profile():
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+        path = f.name
+    try:
+        db = ProcessedDB(path)
+        db.add("video.mp4", 10.0, "/out/a_001.mp4", profile="landscape")
+        db.add("video.mp4", 20.0, "/out/b_001.mp4", profile="portrait")
+        land = db.get_markers("video.mp4", profile="landscape")
+        port = db.get_markers("video.mp4", profile="portrait")
+        assert len(land) == 1
+        assert land[0][0] == 10.0
+        assert len(port) == 1
+        assert port[0][0] == 20.0
+    finally:
+        os.unlink(path)
+
+
+def test_db_get_profiles():
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+        path = f.name
+    try:
+        db = ProcessedDB(path)
+        assert db.get_profiles() == []
+        db.add("a.mp4", 0.0, "/out/a.mp4", profile="beta")
+        db.add("b.mp4", 0.0, "/out/b.mp4", profile="alpha")
+        db.add("c.mp4", 0.0, "/out/c.mp4", profile="beta")
+        profiles = db.get_profiles()
+        assert profiles == ["alpha", "beta"]
+    finally:
+        os.unlink(path)
+
+
+def test_db_get_profiles_disabled():
+    db = ProcessedDB("/no/such/directory/8cut.db")
+    assert db.get_profiles() == []
+
+
+def test_db_default_profile_backward_compat():
+    """Existing tests pass without explicit profile — defaults to 'default'."""
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+        path = f.name
+    try:
+        db = ProcessedDB(path)
+        db.add("video.mp4", 5.0, "/out/clip.mp4")
+        markers = db.get_markers("video.mp4")  # no profile arg
+        assert len(markers) == 1
+        assert markers[0][0] == 5.0
+        assert db.get_profiles() == ["default"]
+    finally:
+        os.unlink(path)
+
+
+# --- resolve_keyframe ---
+
+def test_resolve_keyframe_empty():
+    assert resolve_keyframe([], 5.0) is None
+
+def test_resolve_keyframe_before_first():
+    kfs = [(3.0, 0.5, None, False, False)]
+    assert resolve_keyframe(kfs, 1.0) is None
+
+def test_resolve_keyframe_exact():
+    kfs = [(2.0, 0.3, "9:16", True, False)]
+    assert resolve_keyframe(kfs, 2.0) == (2.0, 0.3, "9:16", True, False)
+
+def test_resolve_keyframe_between():
+    kfs = [
+        (1.0, 0.2, None, False, False),
+        (5.0, 0.8, "1:1", False, True),
+    ]
+    assert resolve_keyframe(kfs, 3.0) == (1.0, 0.2, None, False, False)
+
+def test_resolve_keyframe_after_last():
+    kfs = [
+        (1.0, 0.2, None, False, False),
+        (5.0, 0.8, "1:1", False, True),
+    ]
+    assert resolve_keyframe(kfs, 10.0) == (5.0, 0.8, "1:1", False, True)
+
+def test_resolve_keyframe_tolerance():
+    kfs = [(4.0, 0.5, None, True, True)]
+    assert resolve_keyframe(kfs, 3.96) == (4.0, 0.5, None, True, True)
+
+
+# --- apply_keyframes_to_jobs ---
+
+def test_apply_keyframes_no_keyframes():
+    jobs = [(0.0, "/out/a", None, 0.5), (3.0, "/out/b", None, 0.5)]
+    result = apply_keyframes_to_jobs(jobs, [], base_center=0.5, base_ratio=None,
+                                     base_rand_p=True, base_rand_s=False)
+    assert result == [
+        (0.0, "/out/a", None, 0.5, True, False),
+        (3.0, "/out/b", None, 0.5, True, False),
+    ]
+
+def test_apply_keyframes_with_keyframes():
+    kfs = [
+        (0.0, 0.3, "9:16", True, False),
+        (4.0, 0.7, None, False, True),
+    ]
+    jobs = [
+        (0.0, "/out/a", None, 0.5),
+        (3.0, "/out/b", None, 0.5),
+        (6.0, "/out/c", None, 0.5),
+    ]
+    result = apply_keyframes_to_jobs(jobs, kfs, base_center=0.5, base_ratio=None,
+                                     base_rand_p=False, base_rand_s=False)
+    assert result == [
+        (0.0, "/out/a", "9:16", 0.3, True, False),
+        (3.0, "/out/b", "9:16", 0.3, True, False),
+        (6.0, "/out/c", None, 0.7, False, True),
+    ]
+
+def test_apply_keyframes_before_first_uses_base():
+    kfs = [(5.0, 0.8, "1:1", False, True)]
+    jobs = [(1.0, "/out/a", None, 0.5)]
+    result = apply_keyframes_to_jobs(jobs, kfs, base_center=0.5, base_ratio="4:5",
+                                     base_rand_p=True, base_rand_s=False)
+    assert result == [(1.0, "/out/a", "4:5", 0.5, True, False)]

tools/depth_masks.py

@@ -1,75 +0,0 @@
-"""Depth Anything V2 mask generation script.
-
-Usage:
-    python tools/depth_masks.py --input video.mp4 --output masks_dir/
-
-Outputs one binary PNG per frame: frame_0000.png, frame_0001.png, …
-Foreground = white (255), background = black (0), via Otsu threshold on depth map.
-Requires: torch, transformers, opencv-python, Pillow
-"""
-import argparse
-import os
-import sys
-
-import cv2
-import numpy as np
-from PIL import Image
-from transformers import pipeline
-
-
-def main():
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--input", required=True)
-    parser.add_argument("--output", required=True)
-    args = parser.parse_args()
-
-    os.makedirs(args.output, exist_ok=True)
-
-    import torch
-    device = "cuda" if torch.cuda.is_available() else "cpu"
-    print(f"Using device: {device}", flush=True)
-
-    pipe = pipeline(
-        "depth-estimation",
-        model="depth-anything/Depth-Anything-V2-Large-hf",
-        device=device,
-    )
-
-    cap = cv2.VideoCapture(args.input)
-    if not cap.isOpened():
-        print(f"ERROR: cannot open {args.input}", file=sys.stderr)
-        sys.exit(1)
-
-    total = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
-    idx = 0
-    while True:
-        ret, frame = cap.read()
-        if not ret:
-            break
-
-        pil_img = Image.fromarray(cv2.cvtColor(frame, cv2.COLOR_BGR2RGB))
-        result = pipe(pil_img)
-        depth = np.array(result["depth"])  # float32 array
-
-        # Normalise to 0–255
-        d_min, d_max = depth.min(), depth.max()
-        if d_max > d_min:
-            depth_u8 = ((depth - d_min) / (d_max - d_min) * 255).astype(np.uint8)
-        else:
-            depth_u8 = np.zeros_like(depth, dtype=np.uint8)
-
-        # Otsu threshold: closer objects (higher depth value) = foreground
-        _, mask = cv2.threshold(depth_u8, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
-
-        out_path = os.path.join(args.output, f"frame_{idx:04d}.png")
-        cv2.imwrite(out_path, mask)
-
-        idx += 1
-        print(f"frame {idx}/{total}", flush=True)
-
-    cap.release()
-    print("done", flush=True)
-
-
-if __name__ == "__main__":
-    main()

tools/sam_masks.py

@@ -1,83 +0,0 @@
-"""SAM2 mask generation script.
-
-Usage:
-    python tools/sam_masks.py --input video.mp4 --output masks_dir/
-
-Outputs one binary PNG per frame: frame_0000.png, frame_0001.png, …
-Uses center of first frame as positive point prompt, propagates across all frames.
-Requires: torch, segment-anything-2, opencv-python
-"""
-import argparse
-import os
-import sys
-import tempfile
-
-import cv2
-import numpy as np
-
-
-def main():
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--input", required=True)
-    parser.add_argument("--output", required=True)
-    args = parser.parse_args()
-
-    os.makedirs(args.output, exist_ok=True)
-
-    import torch
-    device = "cuda" if torch.cuda.is_available() else "cpu"
-    print(f"Using device: {device}", flush=True)
-
-    # Extract frames to temp directory (SAM2 video predictor needs image files)
-    with tempfile.TemporaryDirectory() as frame_dir:
-        cap = cv2.VideoCapture(args.input)
-        if not cap.isOpened():
-            print(f"ERROR: cannot open {args.input}", file=sys.stderr)
-            sys.exit(1)
-
-        total = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
-        width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
-        height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
-        idx = 0
-        while True:
-            ret, frame = cap.read()
-            if not ret:
-                break
-            cv2.imwrite(os.path.join(frame_dir, f"{idx:04d}.jpg"), frame)
-            idx += 1
-        cap.release()
-
-        print(f"Extracted {idx} frames", flush=True)
-
-        # SAM2: use from_pretrained (SAM2.1+ / HuggingFace integration)
-        from sam2.sam2_video_predictor import SAM2VideoPredictor
-
-        predictor = SAM2VideoPredictor.from_pretrained(
-            "facebook/sam2-hiera-large"
-        ).to(device)
-
-        with torch.inference_mode():
-            state = predictor.init_state(video_path=frame_dir)
-
-            # Center of first frame as positive point prompt
-            cx, cy = width // 2, height // 2
-            _, _, _ = predictor.add_new_points_or_box(
-                inference_state=state,
-                frame_idx=0,
-                obj_id=1,
-                points=np.array([[cx, cy]], dtype=np.float32),
-                labels=np.array([1], dtype=np.int32),
-            )
-
-            for frame_idx, obj_ids, out_mask_logits in predictor.propagate_in_video(state):
-                # out_mask_logits: (N_objects, 1, H, W) — threshold logits at 0
-                mask = (out_mask_logits[0].squeeze().cpu().numpy() > 0.0).astype(np.uint8) * 255
-                out_path = os.path.join(args.output, f"frame_{frame_idx:04d}.png")
-                cv2.imwrite(out_path, mask)
-                print(f"frame {frame_idx + 1}/{total}", flush=True)
-
-    print("done", flush=True)
-
-
-if __name__ == "__main__":
-    main()