cutnow 0.1.0__tar.gz

cutnow-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vcut contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cutnow-0.1.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: cutnow
+Version: 0.1.0
+Summary: Deterministic, inspectable video editing for agents — solutions, ops and EDL.
+Author: vcut contributors
+License: MIT
+Keywords: video,editing,ffmpeg,edl,agent,clip
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: imageio-ffmpeg>=0.4
+Provides-Extra: clip
+Requires-Dist: onnxruntime>=1.16; extra == "clip"
+Requires-Dist: tokenizers>=0.15; extra == "clip"
+Provides-Extra: qc
+Requires-Dist: opencv-python-headless>=4.8; extra == "qc"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# cutnow
+
+**A deterministic editing engine that agents can drive and humans can audit.**
+
+[![ci](https://github.com/jchen0102/cutnow/actions/workflows/ci.yml/badge.svg)](https://github.com/jchen0102/cutnow/actions/workflows/ci.yml)
+[![pypi](https://img.shields.io/pypi/v/cutnow.svg)](https://pypi.org/project/cutnow/)
+[![python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://pypi.org/project/cutnow/)
+[![license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+[中文](README.zh-CN.md) · [Docs](docs/) · [Examples](solutions/)
+
+</div>
+
+![cutnow demo](docs/images/demo.gif)
+
+```bash
+pip install cutnow
+cutnow doctor
+cutnow run sports --source match.mp4 --out highlight.mp4
+```
+
+That is a 10-second vertical-ready highlight cut on the beat, with title and end cards baked in —
+no timeline app, no render queue, no manual keyframes.
+
+---
+
+## Why not "one-click AI video"?
+
+Most tools give you a **finished file**. You cannot change one cut without starting over, and you
+cannot ask *why* that cut is there.
+
+cutnow gives you an **edit decision list (EDL)** — a plain JSON timeline you can read, diff and
+rewrite — plus the engine that turns it into a video, byte-for-byte reproducibly.
+
+| Typical tool | cutnow |
+|---|---|
+| "AI edited your video" | every cut has a score and a reason |
+| change = re-generate everything | change one line, re-render in seconds |
+| one workflow per product | a new recipe is a JSON file, engine untouched |
+| output only | output + EDL + QC report |
+
+## Concepts
+
+```
+Solution (solution.json)   what a recipe does: which ops, in what order, where a human must confirm
+      ↓
+Op     (core/builtin_ops)  one deterministic job: cut, beat-align, score, subtitle, render, QC
+      ↓
+EDL    (out/edl_*.json)    the decision list: source in-point, duration, position, audio, subtitles
+```
+
+Three ideas, and that's the whole system: **solutions are data, ops are code, the EDL is the contract.**
+
+## Built-in solutions
+
+| Solution | Input | Output | Needs |
+|---|---|---|---|
+| `film-montage` | one long video + music | ~20s beat-cut montage with title/end cards | — |
+| `sports-highlight` | match footage | ~12s highlight, cuts land on shot boundaries | CLIP *(optional, degrades gracefully)* |
+| `talk-highlight` | talking-head video | ~15s vertical clip with aligned subtitles | whisper.cpp *(optional)* |
+| `mj-remake` | source video + track | beat-cut re-edit | — |
+
+```bash
+cutnow list                 # solutions + ops
+cutnow run film --source movie.mov --out montage.mp4
+cutnow run talk --source talk.mp4 --out clip.mp4
+```
+
+## How it decides (and shows you)
+
+A real run, 9 stock clips, fully unattended, **0 tokens**:
+
+```
+9 sources → 4 rejected by the pre-check → 5 rendered → 5/5 pass QC → 86s total
+```
+
+The pre-check is not a vibe: it samples frames and asks a CLIP model whether this looks like a
+match at all.
+
+```
+sport_prob 0.994 → keep      (beach volleyball)
+sport_prob 0.093 → reject    (people walking down a street)
+```
+
+Then selection scores every candidate window on **semantic match + motion + audio energy**, keeps
+cuts on shot boundaries, and renders. Finally QC blocks anything that would ship broken:
+
+```
+duration 10.40s ✓   black frames 0 ✓   −12.6 LUFS ✓   subtitle fit 12/16 ✓   sharpness 314 ✓
+```
+
+![timeline](docs/images/timeline.png)
+
+*The optional local workbench (`cutnow serve`): shots, beat grid, versions, and the same EDL the CLI writes.*
+
+## Write your own solution
+
+```bash
+cutnow new my-recipe                      # scaffolds solutions/my-recipe.solution.json
+cutnow solution validate solutions/my-recipe.solution.json
+cutnow run my-recipe --source in.mp4 --out out.mp4
+```
+
+```json
+{
+  "id": "my-recipe",
+  "inputs": { "source": { "type": "video", "required": true } },
+  "steps": [
+    { "op": "analyze.standard", "params": { "features": "auto" } },
+    { "op": "select.action", "gate": "confirm", "params": { "target_seconds": 12 } },
+    { "op": "card.bookends", "params": { "title": "MY FILM", "end": "cutnow" } },
+    { "op": "render.edl", "params": { "out": "out/my-recipe.mp4" } },
+    { "op": "qc.report", "params": {} }
+  ]
+}
+```
+
+Unknown ops and invalid gates are rejected at **validation** time — a solution cannot execute code
+you did not review. `"gate": "confirm"` stops for a human before a costly or irreversible step.
+
+## Ops
+
+| Group | Ops |
+|---|---|
+| Analyze | `analyze.standard` `analyze.media` |
+| Select | `select.shots` `select.auto` `select.action` `select.semantic` |
+| Speech | `transcribe.whisper` `cut.by_sentence` |
+| Audio | `audio.chorus` `audio.from_clips` `audio.normalize` |
+| Text & framing | `subtitle.by_beat` `card.bookends` `frame.vertical` `cleanup.crop` |
+| Output | `render.edl` `qc.report` `qc.source` |
+
+## Install
+
+```bash
+pip install cutnow          # or: pipx install cutnow
+cutnow doctor               # ffmpeg / models / fonts, with what to do about each
+```
+
+ffmpeg ships with the package via `imageio-ffmpeg`, so a fresh install already renders.
+Optional extras:
+
+```bash
+pip install "cutnow[clip]"     # semantic selection (~600MB of ONNX models)
+pip install "cutnow[qc]"       # sharpness metric via OpenCV
+python scripts/fetch_models.py --clip --whisper small
+```
+
+Everything optional degrades: without CLIP, selection falls back to motion + audio rules; without
+whisper, the talk solution reports what is missing instead of producing a broken file.
+
+## CLI
+
+```
+cutnow list                       # solutions and ops
+cutnow run <solution>             # --source, --music, --out, --yes, --json
+cutnow new <name>                 # scaffold a solution
+cutnow solution validate <path>
+cutnow serve [--port 8799]        # local timeline workbench
+cutnow doctor
+```
+
+## Repository layout
+
+```
+cutnow.py        CLI
+core/            engine: ops, solutions, EDL, render, QC, config
+solutions/       built-in recipes (data only)
+recipes/         legacy single-pass recipe format
+workbench/       optional local HTTP timeline (stdlib only)
+contrib/         optional integrations (Harness plugin, …)
+docs/            images and notes
+```
+
+## Limitations
+
+Honest list, so nobody is surprised:
+
+- **No transitions, grading, or multi-track.** Cuts are hard cuts; that is the current engine.
+- **Face swap and face-identity modules are not included** (compliance). Interfaces exist; the
+  implementations are intentionally absent.
+- **Deterministic, not tasteful.** QC guarantees the file is shippable, not that the edit is good.
+- **No cloud APIs.** No keys, no per-call cost, no rate limits — and no generative model either.
+
+## Roadmap
+
+- [x] EDL + deterministic render + QC gate
+- [x] Solution manifests with validation and human gates
+- [x] Semantic source pre-check and shot selection (CLIP)
+- [ ] Proposal layer: `plan → diff → apply` instead of direct edits
+- [ ] Cross-fades and simple grading
+- [ ] Batch runner with a single report (in `contrib/` today)
+
+## Credits
+
+Demo footage: *Tears of Steel* © Blender Foundation, [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/).
+Built on ffmpeg, [CLIP](https://github.com/openai/CLIP) (via ONNX), and
+[whisper.cpp](https://github.com/ggerganov/whisper.cpp).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

cutnow-0.1.0/README.md

@@ -0,0 +1,203 @@
+<div align="center">
+
+# cutnow
+
+**A deterministic editing engine that agents can drive and humans can audit.**
+
+[![ci](https://github.com/jchen0102/cutnow/actions/workflows/ci.yml/badge.svg)](https://github.com/jchen0102/cutnow/actions/workflows/ci.yml)
+[![pypi](https://img.shields.io/pypi/v/cutnow.svg)](https://pypi.org/project/cutnow/)
+[![python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://pypi.org/project/cutnow/)
+[![license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+[中文](README.zh-CN.md) · [Docs](docs/) · [Examples](solutions/)
+
+</div>
+
+![cutnow demo](docs/images/demo.gif)
+
+```bash
+pip install cutnow
+cutnow doctor
+cutnow run sports --source match.mp4 --out highlight.mp4
+```
+
+That is a 10-second vertical-ready highlight cut on the beat, with title and end cards baked in —
+no timeline app, no render queue, no manual keyframes.
+
+---
+
+## Why not "one-click AI video"?
+
+Most tools give you a **finished file**. You cannot change one cut without starting over, and you
+cannot ask *why* that cut is there.
+
+cutnow gives you an **edit decision list (EDL)** — a plain JSON timeline you can read, diff and
+rewrite — plus the engine that turns it into a video, byte-for-byte reproducibly.
+
+| Typical tool | cutnow |
+|---|---|
+| "AI edited your video" | every cut has a score and a reason |
+| change = re-generate everything | change one line, re-render in seconds |
+| one workflow per product | a new recipe is a JSON file, engine untouched |
+| output only | output + EDL + QC report |
+
+## Concepts
+
+```
+Solution (solution.json)   what a recipe does: which ops, in what order, where a human must confirm
+      ↓
+Op     (core/builtin_ops)  one deterministic job: cut, beat-align, score, subtitle, render, QC
+      ↓
+EDL    (out/edl_*.json)    the decision list: source in-point, duration, position, audio, subtitles
+```
+
+Three ideas, and that's the whole system: **solutions are data, ops are code, the EDL is the contract.**
+
+## Built-in solutions
+
+| Solution | Input | Output | Needs |
+|---|---|---|---|
+| `film-montage` | one long video + music | ~20s beat-cut montage with title/end cards | — |
+| `sports-highlight` | match footage | ~12s highlight, cuts land on shot boundaries | CLIP *(optional, degrades gracefully)* |
+| `talk-highlight` | talking-head video | ~15s vertical clip with aligned subtitles | whisper.cpp *(optional)* |
+| `mj-remake` | source video + track | beat-cut re-edit | — |
+
+```bash
+cutnow list                 # solutions + ops
+cutnow run film --source movie.mov --out montage.mp4
+cutnow run talk --source talk.mp4 --out clip.mp4
+```
+
+## How it decides (and shows you)
+
+A real run, 9 stock clips, fully unattended, **0 tokens**:
+
+```
+9 sources → 4 rejected by the pre-check → 5 rendered → 5/5 pass QC → 86s total
+```
+
+The pre-check is not a vibe: it samples frames and asks a CLIP model whether this looks like a
+match at all.
+
+```
+sport_prob 0.994 → keep      (beach volleyball)
+sport_prob 0.093 → reject    (people walking down a street)
+```
+
+Then selection scores every candidate window on **semantic match + motion + audio energy**, keeps
+cuts on shot boundaries, and renders. Finally QC blocks anything that would ship broken:
+
+```
+duration 10.40s ✓   black frames 0 ✓   −12.6 LUFS ✓   subtitle fit 12/16 ✓   sharpness 314 ✓
+```
+
+![timeline](docs/images/timeline.png)
+
+*The optional local workbench (`cutnow serve`): shots, beat grid, versions, and the same EDL the CLI writes.*
+
+## Write your own solution
+
+```bash
+cutnow new my-recipe                      # scaffolds solutions/my-recipe.solution.json
+cutnow solution validate solutions/my-recipe.solution.json
+cutnow run my-recipe --source in.mp4 --out out.mp4
+```
+
+```json
+{
+  "id": "my-recipe",
+  "inputs": { "source": { "type": "video", "required": true } },
+  "steps": [
+    { "op": "analyze.standard", "params": { "features": "auto" } },
+    { "op": "select.action", "gate": "confirm", "params": { "target_seconds": 12 } },
+    { "op": "card.bookends", "params": { "title": "MY FILM", "end": "cutnow" } },
+    { "op": "render.edl", "params": { "out": "out/my-recipe.mp4" } },
+    { "op": "qc.report", "params": {} }
+  ]
+}
+```
+
+Unknown ops and invalid gates are rejected at **validation** time — a solution cannot execute code
+you did not review. `"gate": "confirm"` stops for a human before a costly or irreversible step.
+
+## Ops
+
+| Group | Ops |
+|---|---|
+| Analyze | `analyze.standard` `analyze.media` |
+| Select | `select.shots` `select.auto` `select.action` `select.semantic` |
+| Speech | `transcribe.whisper` `cut.by_sentence` |
+| Audio | `audio.chorus` `audio.from_clips` `audio.normalize` |
+| Text & framing | `subtitle.by_beat` `card.bookends` `frame.vertical` `cleanup.crop` |
+| Output | `render.edl` `qc.report` `qc.source` |
+
+## Install
+
+```bash
+pip install cutnow          # or: pipx install cutnow
+cutnow doctor               # ffmpeg / models / fonts, with what to do about each
+```
+
+ffmpeg ships with the package via `imageio-ffmpeg`, so a fresh install already renders.
+Optional extras:
+
+```bash
+pip install "cutnow[clip]"     # semantic selection (~600MB of ONNX models)
+pip install "cutnow[qc]"       # sharpness metric via OpenCV
+python scripts/fetch_models.py --clip --whisper small
+```
+
+Everything optional degrades: without CLIP, selection falls back to motion + audio rules; without
+whisper, the talk solution reports what is missing instead of producing a broken file.
+
+## CLI
+
+```
+cutnow list                       # solutions and ops
+cutnow run <solution>             # --source, --music, --out, --yes, --json
+cutnow new <name>                 # scaffold a solution
+cutnow solution validate <path>
+cutnow serve [--port 8799]        # local timeline workbench
+cutnow doctor
+```
+
+## Repository layout
+
+```
+cutnow.py        CLI
+core/            engine: ops, solutions, EDL, render, QC, config
+solutions/       built-in recipes (data only)
+recipes/         legacy single-pass recipe format
+workbench/       optional local HTTP timeline (stdlib only)
+contrib/         optional integrations (Harness plugin, …)
+docs/            images and notes
+```
+
+## Limitations
+
+Honest list, so nobody is surprised:
+
+- **No transitions, grading, or multi-track.** Cuts are hard cuts; that is the current engine.
+- **Face swap and face-identity modules are not included** (compliance). Interfaces exist; the
+  implementations are intentionally absent.
+- **Deterministic, not tasteful.** QC guarantees the file is shippable, not that the edit is good.
+- **No cloud APIs.** No keys, no per-call cost, no rate limits — and no generative model either.
+
+## Roadmap
+
+- [x] EDL + deterministic render + QC gate
+- [x] Solution manifests with validation and human gates
+- [x] Semantic source pre-check and shot selection (CLIP)
+- [ ] Proposal layer: `plan → diff → apply` instead of direct edits
+- [ ] Cross-fades and simple grading
+- [ ] Batch runner with a single report (in `contrib/` today)
+
+## Credits
+
+Demo footage: *Tears of Steel* © Blender Foundation, [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/).
+Built on ffmpeg, [CLIP](https://github.com/openai/CLIP) (via ONNX), and
+[whisper.cpp](https://github.com/ggerganov/whisper.cpp).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

cutnow-0.1.0/core/action.py

@@ -0,0 +1,89 @@
+"""运动素材的选段信号：音频能量 + 画面运动 + 主体占比 + 场景对齐。"""
+import numpy as np
+from . import analyze as A
+
+
+def audio_env(path, hop=0.1, sr=22050):
+    """整段音频的短时能量包络（0-1 归一化）。"""
+    x = A.decode_audio(path, sr)
+    if x is None or len(x) == 0:
+        return None, sr
+    n = int(hop * sr)
+    frames = len(x) // n
+    if frames < 2:
+        return None, sr
+    e = np.array([float(np.sqrt(np.mean(x[i * n:(i + 1) * n] ** 2))) for i in range(frames)])
+    hi = np.percentile(e, 95) or 1.0
+    return np.clip(e / hi, 0, 1), hop
+
+
+def env_stats(env, hop, s, e):
+    if env is None:
+        return 0.0, 0.0
+    a, b = int(s / hop), int(e / hop)
+    seg = env[max(0, a):max(1, b)]
+    if len(seg) == 0:
+        return 0.0, 0.0
+    return float(np.mean(seg)), float(np.percentile(seg, 90))
+
+
+def scene_candidates(scenes, rows, env, hop, beat, beats=(4, 8, 12), pad=0.15):
+    """在场景内部平铺开窗：切点对齐镜头边界与前一个窗尾，长镜头也能被多次使用。"""
+    out = []
+    for s, e in scenes:
+        span = e - s
+        if span < 1.2:
+            continue
+        for b in beats:
+            L = b * beat
+            if L > span + 0.45:
+                continue
+            k = 0
+            while True:
+                st = s + pad + k * L
+                if st + L > e + 0.45:
+                    break
+                k += 1
+                rows_in = [r for r in rows if st <= r["t"] < st + L]
+                if len(rows_in) < 2:
+                    continue
+                n = len(rows_in)
+                avg = lambda key: sum(r.get(key, 0) for r in rows_in) / n
+                a_mean, a_p90 = env_stats(env, hop, st, st + L)
+                out.append({"start": round(st, 2), "beats": b, "dur": round(L, 3),
+                            "scene": (s, e),
+                            "motion": avg("motion"),
+                            "motion_min": min(r.get("motion", 0) for r in rows_in),
+                            "human": avg("human_area"), "luma": avg("luma"), "edge": avg("edge"),
+                            "audio": a_mean, "audio_peak": a_p90})
+    return out
+
+
+def score_action(c, clip_p75_motion=20.0, clip_p60_audio=0.3):
+    motion = min(c["motion"] / max(clip_p75_motion * 1.6, 1e-6), 1.0)
+    sustain = min(c["motion_min"] / max(clip_p75_motion * 0.6, 1e-6), 1.0)
+    audio = min(c["audio_peak"] / max(clip_p60_audio * 1.8, 1e-6), 1.0)
+    human = min(c["human"] / 0.10, 1.0)
+    dark = 1.0 if c["luma"] >= 35 else max(0.4, c["luma"] / 35.0)
+    base = 0.34 * motion + 0.16 * sustain + 0.30 * audio + 0.12 * human + 0.08 * min(c["edge"] / 14.0, 1.0)
+    return round(base * dark, 4)
+
+
+def pick_action(cands, target, beat, gap_ratio=1.15):
+    """贪心：分数最高优先，窗口之间至少隔 1.4 个窗长，避免同一段反复用。"""
+    chosen, used = [], 0.0
+    target_beats = max(2, int(round(target / beat)))
+    for c in sorted(cands, key=lambda x: -x.get("score", x.get("action", 0.0))):
+        if used >= target_beats:
+            break
+        if any(abs(c["start"] - o["start"]) < max(c["dur"], o["dur"]) * gap_ratio for o in chosen):
+            continue
+        same = [o for o in chosen if o["scene"] == c["scene"]]
+        span = c["scene"][1] - c["scene"][0]
+        cap = max(2, int(span / max(c["dur"], 0.5)))
+        if len(same) >= cap:
+            continue
+        chosen.append(c)
+        used += c["beats"]
+    chosen.sort(key=lambda c: c["start"])
+    return chosen, used

cutnow-0.1.0/core/analyze.py

@@ -0,0 +1,109 @@
+"""素材分析：镜头切分、音频解码、节拍估计、逐帧特征聚合。"""
+import json, re, subprocess
+import numpy as np
+from . import ffmpeg as F
+
+
+# ---------- 音频 ----------
+
+def decode_audio(path: str, sr: int = 22050) -> np.ndarray:
+    p = subprocess.run([F.ffmpeg(), "-hide_banner", "-nostdin", "-i", path,
+                        "-f", "f32le", "-ac", "1", "-ar", str(sr), "-"],
+                       capture_output=True)
+    if p.returncode != 0:
+        raise RuntimeError(p.stderr.decode("utf-8", "ignore")[-800:])
+    return np.frombuffer(p.stdout, dtype=np.float32)
+
+
+def _stft_mag(x, n_fft=1024, hop=512):
+    if len(x) < n_fft:
+        x = np.pad(x, (0, n_fft - len(x)))
+    n = 1 + (len(x) - n_fft) // hop
+    idx = np.arange(n_fft)[None, :] + hop * np.arange(n)[:, None]
+    frames = x[idx] * np.hanning(n_fft)[None, :]
+    return np.abs(np.fft.rfft(frames, axis=1))
+
+
+def onset_envelope(x, n_fft=1024, hop=512):
+    S = _stft_mag(x, n_fft, hop)
+    d = np.diff(S, axis=0, prepend=S[:1])
+    flux = np.maximum(d, 0).sum(axis=1)
+    flux = flux - flux.mean()
+    flux = np.maximum(flux, 0)
+    return flux / (flux.max() + 1e-9), hop
+
+
+def estimate_beat(x, sr=22050, bpm_range=(70, 190)):
+    """自相关估 tempo + 梳状滤波定相位，返回 (bpm, beat_times_sec)。"""
+    env, hop = onset_envelope(x)
+    fps = sr / hop
+    e = env - env.mean()
+    ac = np.correlate(e, e, "full")[len(e) - 1:]
+    lo = int(fps * 60 / bpm_range[1]); hi = int(fps * 60 / bpm_range[0])
+    lag = lo + int(np.argmax(ac[lo:hi]))
+    bpm = 60 * fps / lag
+
+    # 相位：在 [0, lag) 内找使节拍点能量和最大的偏移
+    best, best_off = -1, 0
+    for off in range(lag):
+        idx = np.arange(off, len(env), lag).astype(int)
+        s = env[idx].sum()
+        if s > best:
+            best, best_off = s, off
+    beats = np.arange(best_off, len(env), lag) / fps
+    return round(bpm, 2), beats
+
+
+def loudest_window(x, sr, dur):
+    """能量最大的 dur 秒窗口起点（用于自动取副歌）。"""
+    win = int(sr * dur)
+    if len(x) <= win:
+        return 0.0
+    step = int(sr * 0.5)
+    frames = 1 + (len(x) - win) // step
+    idx = np.arange(win)[None, :] + step * np.arange(frames)[:, None]
+    energy = (x[idx] ** 2).mean(axis=1)
+    # 平滑，避免选到单次爆炸音
+    k = max(1, int(2 / 0.5))
+    sm = np.convolve(energy, np.ones(k) / k, mode="same")
+    return float(np.argmax(sm) * step / sr)
+
+
+# ---------- 视频 ----------
+
+def scenes(path: str, threshold: float = 0.3):
+    """ffmpeg scene 检测，返回 [(start, end)]。"""
+    p = F.run(["-i", path, "-filter_complex", f"select='gt(scene,{threshold})',showinfo",
+               "-f", "null", "-"])
+    cuts = [float(m) for m in re.findall(r"pts_time:([0-9.]+)", p.stderr)]
+    dur = F.probe(path)["duration"]
+    pts = [0.0] + [c for c in cuts if 0.3 < c < dur - 0.3]
+    out = []
+    for i, s in enumerate(pts):
+        e = pts[i + 1] if i + 1 < len(pts) else dur
+        if e - s >= 0.35:
+            out.append((round(s, 3), round(e, 3)))
+    return out
+
+
+def load_features(path: str):
+    rows = []
+    with open(path) as fh:
+        for line in fh:
+            line = line.strip()
+            if line:
+                rows.append(json.loads(line))
+    return rows
+
+
+def aggregate(rows, start, end):
+    sel = [r for r in rows if start <= r["t"] < end]
+    if not sel:
+        return {"n": 0, "luma": 0, "motion": 0, "face_area": 0, "faces": 0}
+    return {
+        "n": len(sel),
+        "luma": float(np.mean([r["luma"] for r in sel])),
+        "motion": float(np.mean([r["motion"] for r in sel])),
+        "face_area": float(np.max([r["face_area"] for r in sel])),
+        "faces": float(np.mean([r["faces"] for r in sel])),
+    }