cutpoint 0.2.0__tar.gz → 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {cutpoint-0.2.0 → cutpoint-0.3.0}/.gitignore +2 -0
- cutpoint-0.3.0/AGENTS.md +206 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/PKG-INFO +12 -13
- {cutpoint-0.2.0 → cutpoint-0.3.0}/README.md +9 -5
- {cutpoint-0.2.0 → cutpoint-0.3.0}/config.example.json +8 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/docs/troubleshooting/README.md +9 -3
- {cutpoint-0.2.0 → cutpoint-0.3.0}/docs/workflows/README.md +3 -3
- {cutpoint-0.2.0 → cutpoint-0.3.0}/pyproject.toml +14 -2
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/activity.py +32 -25
- cutpoint-0.3.0/src/cutpoint/analyze.py +2025 -0
- cutpoint-0.3.0/src/cutpoint/assemble.py +800 -0
- cutpoint-0.3.0/src/cutpoint/audio_tracks.py +238 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/boundaries.py +14 -28
- cutpoint-0.3.0/src/cutpoint/cache.py +396 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/capabilities.py +135 -5
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/cli.py +666 -133
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/clips.py +522 -133
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/config.py +229 -29
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/crash.py +181 -68
- cutpoint-0.3.0/src/cutpoint/dsp.py +38 -0
- cutpoint-0.3.0/src/cutpoint/edit.py +250 -0
- cutpoint-0.3.0/src/cutpoint/encode.py +838 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/audio_events.py +8 -2
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/cli.py +55 -4
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/common.py +78 -16
- cutpoint-0.3.0/src/cutpoint/events/discover.py +1473 -0
- cutpoint-0.3.0/src/cutpoint/events/eventtypes.py +309 -0
- cutpoint-0.3.0/src/cutpoint/events/game_profile.py +727 -0
- cutpoint-0.3.0/src/cutpoint/events/killfeed.py +2505 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/llama_server.py +16 -84
- cutpoint-0.3.0/src/cutpoint/events/ocr_prefetch.py +461 -0
- cutpoint-0.3.0/src/cutpoint/events/ocr_raw.py +260 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/paths.py +8 -18
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/pipeline.py +286 -100
- cutpoint-0.3.0/src/cutpoint/events/presets/.gitkeep +0 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/regions.py +114 -82
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/report.py +19 -19
- cutpoint-0.3.0/src/cutpoint/events/scoring.py +227 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/setup.py +11 -9
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/tails.py +21 -28
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/visual.py +138 -24
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/vlm_windows.py +107 -63
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/voice.py +19 -4
- cutpoint-0.3.0/src/cutpoint/extend.py +639 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/extras.py +104 -3
- cutpoint-0.3.0/src/cutpoint/ffmpeg_utils.py +2669 -0
- cutpoint-0.3.0/src/cutpoint/jsonout.py +242 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/mix.py +116 -49
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/check.py +5 -5
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/cli.py +337 -90
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/director.py +144 -36
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/geometry.py +61 -104
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/qa.py +168 -72
- cutpoint-0.3.0/src/cutpoint/pano/qa_horizon.py +134 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/qa_paths.py +44 -44
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/render.py +132 -47
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/repair.py +203 -67
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/stitch.py +72 -55
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/views.py +92 -32
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/vlcheck.py +12 -10
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/x3.py +21 -10
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/paths.py +2 -3
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/planning.py +163 -17
- cutpoint-0.3.0/src/cutpoint/progress.py +290 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/refmatch.py +93 -71
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/ski.py +66 -32
- cutpoint-0.3.0/src/cutpoint/skill/SKILL.md +91 -0
- cutpoint-0.3.0/src/cutpoint/skill/__init__.py +49 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/sources.py +69 -22
- cutpoint-0.3.0/src/cutpoint/srt.py +330 -0
- cutpoint-0.3.0/src/cutpoint/stage.py +644 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/state.py +21 -8
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/styles.py +9 -10
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/telemetry.py +74 -48
- cutpoint-0.3.0/src/cutpoint/timeline.py +217 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/transcribe.py +48 -9
- cutpoint-0.3.0/src/cutpoint/ui.py +2826 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/utils.py +99 -3
- cutpoint-0.3.0/src/cutpoint/vision.py +374 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/web/api.js +21 -1
- cutpoint-0.3.0/src/cutpoint/web/app.css +550 -0
- cutpoint-0.3.0/src/cutpoint/web/app.js +2951 -0
- cutpoint-0.3.0/src/cutpoint/web/index.html +277 -0
- cutpoint-0.3.0/src/cutpoint/web/picker.js +96 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/web/util.js +14 -0
- cutpoint-0.3.0/src/cutpoint/winjob.py +84 -0
- cutpoint-0.2.0/AGENTS.md +0 -145
- cutpoint-0.2.0/src/cutpoint/analyze.py +0 -1261
- cutpoint-0.2.0/src/cutpoint/assemble.py +0 -489
- cutpoint-0.2.0/src/cutpoint/cache.py +0 -145
- cutpoint-0.2.0/src/cutpoint/dsp.py +0 -16
- cutpoint-0.2.0/src/cutpoint/encode.py +0 -215
- cutpoint-0.2.0/src/cutpoint/events/discover.py +0 -570
- cutpoint-0.2.0/src/cutpoint/events/killfeed.py +0 -1366
- cutpoint-0.2.0/src/cutpoint/events/presets/wt.json +0 -90
- cutpoint-0.2.0/src/cutpoint/events/scoring.py +0 -138
- cutpoint-0.2.0/src/cutpoint/extend.py +0 -461
- cutpoint-0.2.0/src/cutpoint/ffmpeg_utils.py +0 -1152
- cutpoint-0.2.0/src/cutpoint/stage.py +0 -374
- cutpoint-0.2.0/src/cutpoint/timeline.py +0 -140
- cutpoint-0.2.0/src/cutpoint/ui.py +0 -895
- cutpoint-0.2.0/src/cutpoint/vision.py +0 -215
- cutpoint-0.2.0/src/cutpoint/web/app.css +0 -242
- cutpoint-0.2.0/src/cutpoint/web/app.js +0 -813
- cutpoint-0.2.0/src/cutpoint/web/index.html +0 -162
- cutpoint-0.2.0/src/cutpoint/web/picker.js +0 -107
- {cutpoint-0.2.0 → cutpoint-0.3.0}/LICENSE +0 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/__init__.py +0 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/__main__.py +0 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/backends.py +0 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/crop.py +0 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/__init__.py +0 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/sheets.py +0 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/__init__.py +0 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/project.py +0 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/presets/activities/base.json +0 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/presets/activities/generic.json +0 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/presets/activities/hike.json +0 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/presets/activities/moto.json +0 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/presets/activities/mtb.json +0 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/presets/activities/skate.json +0 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/presets/activities/ski.json +0 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/presets/activities/snowboard.json +0 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/presets/activities/surf.json +0 -0
- {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/tail.py +0 -0
|
@@ -16,6 +16,8 @@ models/
|
|
|
16
16
|
tools/llama.cpp/
|
|
17
17
|
stage/
|
|
18
18
|
projects/
|
|
19
|
+
# raw OCR cache (OCR text of the footage): normally under cache/, ignored anywhere
|
|
20
|
+
ocr-raw-*/
|
|
19
21
|
|
|
20
22
|
# Local, personal config and learned styles (old repo-root layout; now in CUTPOINT_HOME,
|
|
21
23
|
# keys documented in config.example.json)
|
cutpoint-0.3.0/AGENTS.md
ADDED
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
# Cutpoint for AI agents
|
|
2
|
+
|
|
3
|
+
You are an AI agent asked to edit video with Cutpoint. This file is what you need. Read this any
|
|
4
|
+
time with `cutpoint guide`. If you are instead changing this repository's code, read
|
|
5
|
+
[CONTRIBUTING.md](https://github.com/FerventOrange/cutpoint/blob/main/CONTRIBUTING.md).
|
|
6
|
+
|
|
7
|
+
Cutpoint finds the best moments in long recordings, exports them as numbered clips and
|
|
8
|
+
assembles a finished video. It runs locally, never modifies source videos, and writes
|
|
9
|
+
everything into a project folder.
|
|
10
|
+
|
|
11
|
+
## Status: what you can rely on
|
|
12
|
+
|
|
13
|
+
| Available now | Planned (do not call; it does not exist yet) |
|
|
14
|
+
|---|---|
|
|
15
|
+
| CLI `cutpoint` with the commands below | `--context` on `edit`, clip order chosen by a local model |
|
|
16
|
+
| `cutpoint edit`: analyze, clips and assemble in one command; `analyze` includes the reaction, keyframe and crash steps | |
|
|
17
|
+
| Result files in the project folder (JSON and text), `.srt` subtitles next to clips and finals | Profiles for the other layers and for games |
|
|
18
|
+
| Activity profiles for crash detection: `cutpoint profile`, `--context` on `profile` and `crashes` | |
|
|
19
|
+
| `--json` result envelope on stdout: `paths`, `analyze`, `clips`, `assemble`, `edit`, `extend`, `capabilities`, `mix`, `stage`, `setup`, `crashes`, `profile`, `events`, `360 ...` | |
|
|
20
|
+
| Agent skill: `cutpoint skill install` (Claude Code), `cutpoint skill print` | |
|
|
21
|
+
| Color grade with a 3D LUT the user supplies: `--lut FILE` and `--lut-strength` on `clips` and `edit` | Automatic color correction and matching between clips |
|
|
22
|
+
|
|
23
|
+
If the user asks for "edit this video and make it a montage" in one step, use
|
|
24
|
+
[One command](#one-command); to choose the moments yourself, use the loop below it.
|
|
25
|
+
|
|
26
|
+
To let Claude Code find Cutpoint on its own, install the skill with `cutpoint skill install`
|
|
27
|
+
(writes `~/.claude/skills/cutpoint/SKILL.md`; `--dir DIR` for a project's `.claude/skills` or
|
|
28
|
+
another agent's folder). Ask the user first: it writes to their Claude Code settings folder.
|
|
29
|
+
`cutpoint skill print` prints it for agents without a skills folder.
|
|
30
|
+
|
|
31
|
+
## Calling the CLI
|
|
32
|
+
|
|
33
|
+
- If installed as a tool (`uv tool install cutpoint`), run `cutpoint <command> ...`; from a
|
|
34
|
+
clone, `uv run cutpoint <command> ...`. The examples below use `uv run cutpoint`; with a tool
|
|
35
|
+
install, drop `uv run`. First-time setup is in
|
|
36
|
+
[docs/getting-started.md](https://github.com/FerventOrange/cutpoint/blob/main/docs/getting-started.md).
|
|
37
|
+
Check it works with `cutpoint paths` (or `uv run cutpoint paths`).
|
|
38
|
+
- Exit codes: `0` success, `1` error, `130` interrupted, `2` bad arguments.
|
|
39
|
+
On Windows, Ctrl+C or Ctrl+Break gives `130` and removes partial files; from a program, start
|
|
40
|
+
Cutpoint with `CREATE_NEW_PROCESS_GROUP` and send `CTRL_BREAK_EVENT` (`CTRL_C_EVENT` to a
|
|
41
|
+
process id is not delivered). To get `130`, run `.venv\Scripts\cutpoint.exe` (or the
|
|
42
|
+
tool-installed `cutpoint`) directly: under `uv run`, Cutpoint still cleans up but uv exits
|
|
43
|
+
`0xC000013A`. `taskkill /F`, `Stop-Process` and `Popen.terminate()`/`kill()`
|
|
44
|
+
stop it without cleanup (exit `1`; `-1` from `Stop-Process`).
|
|
45
|
+
- Logs and errors go to stderr as `HH:MM:SS LEVEL message`; errors are `ERROR` lines. Use
|
|
46
|
+
`cutpoint -v <command>` (flag before the command) for debug output and tracebacks.
|
|
47
|
+
- Paths inside a project must start with `projects/<name>/...` (forward slashes work on every OS; do not use backslashes in bash) or be absolute; a bare name means
|
|
48
|
+
the project itself.
|
|
49
|
+
- Results are files. Read the JSON files below instead of parsing logs. `--json` (on the commands in
|
|
50
|
+
the Status table) also writes one JSON object to stdout, with the file paths and warnings:
|
|
51
|
+
`ok`, `command`, `schema`, `project`, `outputs`, `warnings` (`code`, `message`, `files`) and
|
|
52
|
+
`error` (`code`, `message`, or `null`). `error.code` is `bad_args` (exit 2 for the command
|
|
53
|
+
line, 1 when a command rejects an option value itself, such as a `--lut` file or
|
|
54
|
+
`--clip-override`), `not_found`,
|
|
55
|
+
`ffmpeg_missing`, `missing_extra`, `output_not_empty`, `folder_busy` (another run holds the folder's lock: wait or retry),
|
|
56
|
+
`interrupted` (130) or `error`.
|
|
57
|
+
Read `warnings` such as `kept_clips`, `kept_sources` and `step_failed` and tell the user. With `CUTPOINT_PROGRESS=1`, stderr also has `PROGRESS {...}` lines per step ([docs/commands.md](https://github.com/FerventOrange/cutpoint/blob/main/docs/commands.md#progress-output)). Keys:
|
|
58
|
+
[docs/commands.md](https://github.com/FerventOrange/cutpoint/blob/main/docs/commands.md#json-output).
|
|
59
|
+
- Commands are re-runnable. Per-source results are cached (path, size, modification time).
|
|
60
|
+
`clips` refuses a non-empty output folder without `--force`, which replaces only the clips its
|
|
61
|
+
`manifest.json` lists, once every new clip is exported (other files, sources included, stay;
|
|
62
|
+
clips renamed or added by hand stay and are assembled; a WARNING names them, so tell the
|
|
63
|
+
user, and move them out only if they are clips you exported, never delete a file you did not
|
|
64
|
+
export). If such a clip has the name of a new clip, the run stops before exporting with an
|
|
65
|
+
`ERROR` naming it; tell the user to move or rename it.
|
|
66
|
+
- One run at a time works on a clips folder (lock file `.<folder>.cutpoint-lock`). If `clips`,
|
|
67
|
+
`extend` or `assemble` stops with an `ERROR` that another run holds the lock, wait for it;
|
|
68
|
+
delete the lock file only if you are sure no run is active. If `clips --force` or `extend`
|
|
69
|
+
refuses a `manifest.json` Cutpoint did not write (or cannot read), tell the user; never delete
|
|
70
|
+
or overwrite their manifest.
|
|
71
|
+
- Transcription, `analyze` steps, `events` and export can take minutes to hours. Run them in the background or
|
|
72
|
+
with a long timeout.
|
|
73
|
+
- Never modify or delete the user's source videos. You may delete or rename clips in a project's
|
|
74
|
+
`clips` folder during review.
|
|
75
|
+
- Use the real options: `cutpoint <command> --help` is authoritative;
|
|
76
|
+
[docs/commands.md](https://github.com/FerventOrange/cutpoint/blob/main/docs/commands.md)
|
|
77
|
+
explains them.
|
|
78
|
+
|
|
79
|
+
## One command
|
|
80
|
+
|
|
81
|
+
```powershell
|
|
82
|
+
uv run cutpoint edit D:\Videos\clip.mp4 --kind funny-moments
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
`--kind` is `highlights` (default; up to 3 min, chronological, crossfades), `montage` (up to
|
|
86
|
+
60 s, best first, crossfades), `clips` (the 10 best; the clips are the deliverable) or
|
|
87
|
+
`funny-moments` (funny style, 8 moments, chronological, burned-in captions). `--style`, `--top`,
|
|
88
|
+
`--max-total`, `--vertical`, `--force` and `--events` override the kind; `--vision` adds the
|
|
89
|
+
optional Ollama frame rating (off for every style unless `"vision": true` in the user's
|
|
90
|
+
`config.json` turns it on by default; `--no-vision` then skips it), and `--vision-top`, `--ollama-url` and `--ollama-model` work as on `analyze`. It writes the project
|
|
91
|
+
`<projects>\clip` (`--out NAME` to change it) with the clips, `final.mp4` and
|
|
92
|
+
`clip-final.mp4` plus `.srt` subtitles; the last log lines name the final video, its subtitles
|
|
93
|
+
and the clips folder. A non-empty clips folder needs `--force` (ask the user first, as for
|
|
94
|
+
`clips --force`). To change the cut, review and re-assemble as in steps 5-7 below; that
|
|
95
|
+
updates `final.mp4` and `final.srt`, not the `clip-final` copies.
|
|
96
|
+
|
|
97
|
+
## The full edit
|
|
98
|
+
|
|
99
|
+
Given a request such as "edit D:\Videos\clip.mp4 into a funny-moments montage":
|
|
100
|
+
|
|
101
|
+
1. **Pick a style** from the request: `funny`, `gaming`, `action`, `sport`, `commentary`
|
|
102
|
+
(long talk), `ski` (action-cam with telemetry). Footage that is not any of these: use `action`
|
|
103
|
+
or `gaming`.
|
|
104
|
+
2. **Analyze.**
|
|
105
|
+
|
|
106
|
+
```powershell
|
|
107
|
+
uv run cutpoint analyze D:\Videos\clip.mp4 --style funny --out clip-edit
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
On Linux: `uv run cutpoint analyze ~/Videos/clip.mp4 --style funny --out clip-edit`.
|
|
111
|
+
|
|
112
|
+
Writes `highlights.json` and `transcript.txt` into the project folder (`<projects>\clip-edit`, see
|
|
113
|
+
`cutpoint paths`).
|
|
114
|
+
3. **Optional, for the VLM layer or to force layers:**
|
|
115
|
+
`uv run cutpoint events clip-edit` (needs the `events` extra and `cutpoint setup`).
|
|
116
|
+
`analyze` already ran the reaction, keyframe and crash steps it can (steps are skipped with
|
|
117
|
+
an INFO line when the extra or model files are missing; `--skip reactions keyframes crashes`, given after the paths,
|
|
118
|
+
leaves them out) and wrote `events.json` and `events.txt`. `events` adds the VLM layer,
|
|
119
|
+
re-ranks `highlights.json` and rewrites those files. If it reports a missing
|
|
120
|
+
module, tell the user how to add the extra (see [When something fails](#when-something-fails)).
|
|
121
|
+
4. **Choose moments.** Read `highlights.json` (`candidates` with `id`, `source`, `start`, `end`,
|
|
122
|
+
`score` 0-100, `label`, `transcript`; `suggested_top`) and, for banter and funny moments,
|
|
123
|
+
`transcript.txt` (`[file.mp4 00:12:31.4-00:12:38.9] text`). Then either:
|
|
124
|
+
- take the top N: `uv run cutpoint clips clip-edit --top 8` (or `--max-total 60` for a
|
|
125
|
+
length cap, `--ids h001 h004`), or
|
|
126
|
+
- export your own picks with a segments file:
|
|
127
|
+
|
|
128
|
+
```json
|
|
129
|
+
[
|
|
130
|
+
{"source": "D:/Videos/clip.mp4", "start": 312.4, "end": 330.0, "label": "intro"},
|
|
131
|
+
{"source": "D:/Videos/clip.mp4", "start": 1204.0, "end": 1219.5, "label": "joke"}
|
|
132
|
+
]
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
`uv run cutpoint clips clip-edit --segments segments.json`
|
|
136
|
+
5. **Review.** Clips are `clips\001_<label>.mp4`, `002_...`, and `clips\manifest.json` maps each
|
|
137
|
+
to its source and times. Tell the user what was exported. Delete clips the user rejects and
|
|
138
|
+
rename to reorder (for example `005_x.mp4` to `001b_x.mp4`, and its `005_x.srt` to
|
|
139
|
+
`001b_x.srt`, so `final.srt` keeps its subtitles).
|
|
140
|
+
6. **Assemble.**
|
|
141
|
+
|
|
142
|
+
```powershell
|
|
143
|
+
uv run cutpoint assemble projects/clip-edit/clips --transition fade --loudnorm
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Writes `final.mp4`, `final.fcpxml` and `final.otio` in the project folder.
|
|
147
|
+
7. **Report** the paths of `final.mp4` and the clips folder.
|
|
148
|
+
|
|
149
|
+
Variants:
|
|
150
|
+
|
|
151
|
+
| Request | Do |
|
|
152
|
+
|---|---|
|
|
153
|
+
| Short clip or reel for social media | `clips <project> --vertical --max-total 60`, then `assemble projects/<project>/clips_vertical --captions` |
|
|
154
|
+
| Highlights of a specific length | `clips <project> --max-total <seconds>` |
|
|
155
|
+
| "Extra" instruction such as "only funny moments" or "keep the speech intact" | Choose `--style`, filter candidates by `transcript`/`label`, use `--segments`. The CLI does not parse these instructions |
|
|
156
|
+
| The user says what the footage is ("downhill mtb, chest mount, muddy lens") | Before `crashes`, run `profile <project> --context "<the user's words>"`; check the choice with `profile <project> --json` (`outputs.name` and `outputs.source`; a `context_not_applied` warning means the user's words were not used). Use `--activity NAME` only when the user names a sport that has a profile. Do not edit profile files |
|
|
157
|
+
| Room to trim in an editor | `clips ... --extend 1.5` or `extend <clips_dir> --seconds 2` |
|
|
158
|
+
| The user gives a LUT for log or flat footage ("use my GoPro Flat LUT") | `clips <project> --lut <file>.cube` (or on `edit`); `--lut-strength 0.5` for half the grade. Only with a LUT the user names; never pick one for them |
|
|
159
|
+
| 360 (Insta360 X3) footage | [docs/workflows/360.md](https://github.com/FerventOrange/cutpoint/blob/main/docs/workflows/360.md) |
|
|
160
|
+
| Action-cam with telemetry | [docs/workflows/action-cam.md](https://github.com/FerventOrange/cutpoint/blob/main/docs/workflows/action-cam.md) |
|
|
161
|
+
| Gameplay with kill feeds | [docs/workflows/game-streams.md](https://github.com/FerventOrange/cutpoint/blob/main/docs/workflows/game-streams.md) |
|
|
162
|
+
|
|
163
|
+
## Project files
|
|
164
|
+
|
|
165
|
+
| File | Written by | Content |
|
|
166
|
+
|---|---|---|
|
|
167
|
+
| `highlights.json` | `analyze` (written once, at the end), `events` | Ranked candidates and settings |
|
|
168
|
+
| `transcript.txt` | `analyze` | Time-stamped transcript |
|
|
169
|
+
| `events.json`, `events.txt` | `analyze`, `events` | Detected sounds, HUD events, model descriptions |
|
|
170
|
+
| `clips/manifest.json` | `clips`, `extend` | Per clip: source, start, end, score, label, tail, crop, lut, srt |
|
|
171
|
+
| `clips/001_<label>.srt`, ... | `clips`, `extend` | Subtitles of each clip, from the cached transcript |
|
|
172
|
+
| `final.mp4`, `final.fcpxml`, `final.otio`, `final.srt` | `assemble` | Result, timelines and subtitles |
|
|
173
|
+
| `<name>-final.mp4`, `<name>-final.srt` | `edit` | Copy of the final video and its subtitles; `<name>` is the first input's name (a file's name without extension, or the folder's name) |
|
|
174
|
+
| `crashes.json`, `telemetry.json`, `mix_segments.json` | action-cam commands; `crashes.json` also `analyze` (action footage) | See the action-cam page |
|
|
175
|
+
| `activity.json` | `profile`, `crashes` | Activity profile in use: `name`, `source`, `profile` |
|
|
176
|
+
|
|
177
|
+
## When something fails
|
|
178
|
+
|
|
179
|
+
Read the `ERROR` line, then
|
|
180
|
+
[docs/troubleshooting/README.md](https://github.com/FerventOrange/cutpoint/blob/main/docs/troubleshooting/README.md).
|
|
181
|
+
The usual causes: ffmpeg not on `PATH`, a missing optional extra, Ollama not reachable (only
|
|
182
|
+
affects `--vision`), a non-empty output folder.
|
|
183
|
+
|
|
184
|
+
Whisper runs on the CPU unless the `gpu` extra is installed; if the user has an NVIDIA GPU and
|
|
185
|
+
`transcribe` logs an INFO line about missing CUDA libraries, add `gpu` the same way as below.
|
|
186
|
+
|
|
187
|
+
A missing extra `X` (for example `events`) is added differently per install. Tell the user the
|
|
188
|
+
command for theirs:
|
|
189
|
+
|
|
190
|
+
- From a clone: `uv sync --extra X`, listing every other extra in use too (the error prints this
|
|
191
|
+
form), or `uv sync --extra all` for every extra (`ski`, `events`, `gpu`, `ui`; a large
|
|
192
|
+
download with torch and CUDA).
|
|
193
|
+
- Tool install: `uv tool install "cutpoint[X]" --reinstall`, listing every extra in use. For a
|
|
194
|
+
PyPI or wheel install (not one from a clone directory or git URL, with `uv tool` or `uv pip`) with an NVIDIA GPU and the
|
|
195
|
+
`events` extra, add
|
|
196
|
+
`--index https://download.pytorch.org/whl/cu126 --index-strategy unsafe-best-match` so torch
|
|
197
|
+
uses CUDA ([getting started](https://github.com/FerventOrange/cutpoint/blob/main/docs/getting-started.md#install-as-a-tool-optional)).
|
|
198
|
+
|
|
199
|
+
## Rules
|
|
200
|
+
|
|
201
|
+
- Ask the user before running `cutpoint setup` (about 8 GB of downloads), `cutpoint stage`
|
|
202
|
+
(copies footage to local disk), `clips --force` over an existing folder or
|
|
203
|
+
`cutpoint skill install` (writes to their Claude Code settings folder).
|
|
204
|
+
- Do not paste Insta360 SDK files, documentation or output into any file or message, other than
|
|
205
|
+
`error:` lines.
|
|
206
|
+
- Do not invent options. Check `--help`.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: cutpoint
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.3.0
|
|
4
4
|
Summary: Local, agent-driven AI video editor: finds highlights, cuts clips, builds montages, handles 360 video.
|
|
5
5
|
License-Expression: MIT
|
|
6
6
|
License-File: LICENSE
|
|
@@ -17,6 +17,7 @@ Requires-Dist: opentimelineio>=0.18.1
|
|
|
17
17
|
Requires-Dist: requests>=2.34.2
|
|
18
18
|
Requires-Dist: scenedetect>=0.7.2
|
|
19
19
|
Provides-Extra: all
|
|
20
|
+
Requires-Dist: fastapi>=0.116; extra == 'all'
|
|
20
21
|
Requires-Dist: nvidia-cublas-cu12>=12.4; (sys_platform == 'linux') and extra == 'all'
|
|
21
22
|
Requires-Dist: nvidia-cublas-cu12>=12.9.2.10; (sys_platform == 'win32') and extra == 'all'
|
|
22
23
|
Requires-Dist: nvidia-cudnn-cu12>=9.1; (sys_platform == 'linux') and extra == 'all'
|
|
@@ -31,13 +32,7 @@ Requires-Dist: telemetry-parser>=0.3.0; extra == 'all'
|
|
|
31
32
|
Requires-Dist: torch==2.14.1; extra == 'all'
|
|
32
33
|
Requires-Dist: torchlibrosa>=0.1.0; extra == 'all'
|
|
33
34
|
Requires-Dist: torchvision==0.29.1; extra == 'all'
|
|
34
|
-
|
|
35
|
-
Requires-Dist: fastapi>=0.116; extra == 'dev'
|
|
36
|
-
Requires-Dist: httpx>=0.27; extra == 'dev'
|
|
37
|
-
Requires-Dist: pre-commit>=3.7; extra == 'dev'
|
|
38
|
-
Requires-Dist: pytest>=8; extra == 'dev'
|
|
39
|
-
Requires-Dist: ruff==0.17.1; extra == 'dev'
|
|
40
|
-
Requires-Dist: uvicorn>=0.30; extra == 'dev'
|
|
35
|
+
Requires-Dist: uvicorn>=0.30; extra == 'all'
|
|
41
36
|
Provides-Extra: events
|
|
42
37
|
Requires-Dist: onnxruntime>=1.31.0; extra == 'events'
|
|
43
38
|
Requires-Dist: open-clip-torch>=3.3.0; extra == 'events'
|
|
@@ -100,8 +95,10 @@ are never changed.
|
|
|
100
95
|
The agent runs Cutpoint, shows you the clips and writes the result into a project folder.
|
|
101
96
|
Delete or rename clips to change the cut, then ask the agent to assemble again.
|
|
102
97
|
|
|
103
|
-
|
|
104
|
-
|
|
98
|
+
Without an agent, `cutpoint edit D:\Videos\clip.mp4 --kind montage` does it in one command
|
|
99
|
+
(see [commands](docs/commands.md#edit)). The agent works from
|
|
100
|
+
[AGENTS.md](https://github.com/FerventOrange/cutpoint/blob/main/AGENTS.md); `cutpoint skill install`
|
|
101
|
+
adds a Claude Code skill so it finds Cutpoint without being pointed at it.
|
|
105
102
|
|
|
106
103
|
### Local browser workspace
|
|
107
104
|
|
|
@@ -114,8 +111,9 @@ uv run --extra ui cutpoint ui
|
|
|
114
111
|
Open the complete URL printed in the terminal (including its session token). Pick a source
|
|
115
112
|
file or folder, analyze it, trim and reorder moments, export clips, then assemble and preview
|
|
116
113
|
the final video. Footage stays on your
|
|
117
|
-
computer; each export gets a new folder so previous exports are retained. The UI
|
|
118
|
-
|
|
114
|
+
computer; each export gets a new folder so previous exports are retained. The UI also makes
|
|
115
|
+
360 projects from Insta360 X3 footage ([360 video](docs/workflows/360.md#in-the-ui)) but does not
|
|
116
|
+
expose the action-cam workflows.
|
|
119
117
|
|
|
120
118
|
For a tool install, use `uv tool install "cutpoint[ui]" --reinstall`, then `cutpoint ui`.
|
|
121
119
|
See the [command reference](docs/commands.md#ui) for details.
|
|
@@ -124,7 +122,7 @@ See the [command reference](docs/commands.md#ui) for details.
|
|
|
124
122
|
|
|
125
123
|
- Windows or Linux
|
|
126
124
|
- Python 3.12 and [uv](https://docs.astral.sh/uv/)
|
|
127
|
-
- ffmpeg
|
|
125
|
+
- ffmpeg 5.1 or newer
|
|
128
126
|
- An NVIDIA GPU is recommended (add the `gpu` extra for GPU Whisper). Without one, everything
|
|
129
127
|
still runs but slower.
|
|
130
128
|
- Optional: Ollama for AI frame rating, extra downloads (about 8 GB) for sound, on-screen text
|
|
@@ -175,6 +173,7 @@ GPU vendors from working encoders and see the selected backend. Use `video_encod
|
|
|
175
173
|
- [Troubleshooting](https://github.com/FerventOrange/cutpoint/blob/main/docs/troubleshooting/README.md)
|
|
176
174
|
- [FAQ](https://github.com/FerventOrange/cutpoint/blob/main/docs/faq.md)
|
|
177
175
|
- [Architecture](https://github.com/FerventOrange/cutpoint/blob/main/docs/architecture.md), [Contributing](https://github.com/FerventOrange/cutpoint/blob/main/CONTRIBUTING.md), [Security](https://github.com/FerventOrange/cutpoint/blob/main/SECURITY.md)
|
|
176
|
+
- [Pipeline](https://github.com/FerventOrange/cutpoint/blob/main/docs/pipeline.md): diagrams of the analyze, clips and assemble flow
|
|
178
177
|
- [Insta360 SDK](https://github.com/FerventOrange/cutpoint/blob/main/docs/insta360-sdk.md): optional, for high-quality 360 stitching
|
|
179
178
|
|
|
180
179
|
## License
|
|
@@ -38,8 +38,10 @@ are never changed.
|
|
|
38
38
|
The agent runs Cutpoint, shows you the clips and writes the result into a project folder.
|
|
39
39
|
Delete or rename clips to change the cut, then ask the agent to assemble again.
|
|
40
40
|
|
|
41
|
-
|
|
42
|
-
|
|
41
|
+
Without an agent, `cutpoint edit D:\Videos\clip.mp4 --kind montage` does it in one command
|
|
42
|
+
(see [commands](docs/commands.md#edit)). The agent works from
|
|
43
|
+
[AGENTS.md](https://github.com/FerventOrange/cutpoint/blob/main/AGENTS.md); `cutpoint skill install`
|
|
44
|
+
adds a Claude Code skill so it finds Cutpoint without being pointed at it.
|
|
43
45
|
|
|
44
46
|
### Local browser workspace
|
|
45
47
|
|
|
@@ -52,8 +54,9 @@ uv run --extra ui cutpoint ui
|
|
|
52
54
|
Open the complete URL printed in the terminal (including its session token). Pick a source
|
|
53
55
|
file or folder, analyze it, trim and reorder moments, export clips, then assemble and preview
|
|
54
56
|
the final video. Footage stays on your
|
|
55
|
-
computer; each export gets a new folder so previous exports are retained. The UI
|
|
56
|
-
|
|
57
|
+
computer; each export gets a new folder so previous exports are retained. The UI also makes
|
|
58
|
+
360 projects from Insta360 X3 footage ([360 video](docs/workflows/360.md#in-the-ui)) but does not
|
|
59
|
+
expose the action-cam workflows.
|
|
57
60
|
|
|
58
61
|
For a tool install, use `uv tool install "cutpoint[ui]" --reinstall`, then `cutpoint ui`.
|
|
59
62
|
See the [command reference](docs/commands.md#ui) for details.
|
|
@@ -62,7 +65,7 @@ See the [command reference](docs/commands.md#ui) for details.
|
|
|
62
65
|
|
|
63
66
|
- Windows or Linux
|
|
64
67
|
- Python 3.12 and [uv](https://docs.astral.sh/uv/)
|
|
65
|
-
- ffmpeg
|
|
68
|
+
- ffmpeg 5.1 or newer
|
|
66
69
|
- An NVIDIA GPU is recommended (add the `gpu` extra for GPU Whisper). Without one, everything
|
|
67
70
|
still runs but slower.
|
|
68
71
|
- Optional: Ollama for AI frame rating, extra downloads (about 8 GB) for sound, on-screen text
|
|
@@ -113,6 +116,7 @@ GPU vendors from working encoders and see the selected backend. Use `video_encod
|
|
|
113
116
|
- [Troubleshooting](https://github.com/FerventOrange/cutpoint/blob/main/docs/troubleshooting/README.md)
|
|
114
117
|
- [FAQ](https://github.com/FerventOrange/cutpoint/blob/main/docs/faq.md)
|
|
115
118
|
- [Architecture](https://github.com/FerventOrange/cutpoint/blob/main/docs/architecture.md), [Contributing](https://github.com/FerventOrange/cutpoint/blob/main/CONTRIBUTING.md), [Security](https://github.com/FerventOrange/cutpoint/blob/main/SECURITY.md)
|
|
119
|
+
- [Pipeline](https://github.com/FerventOrange/cutpoint/blob/main/docs/pipeline.md): diagrams of the analyze, clips and assemble flow
|
|
116
120
|
- [Insta360 SDK](https://github.com/FerventOrange/cutpoint/blob/main/docs/insta360-sdk.md): optional, for high-quality 360 stitching
|
|
117
121
|
|
|
118
122
|
## License
|
|
@@ -7,6 +7,9 @@
|
|
|
7
7
|
"stage_dir": "Local folder for `cutpoint stage` copies of sources on slow or network storage (NAS, USB, cloud-synced folder). Env CUTPOINT_STAGE_DIR overrides it. Default: <CUTPOINT_HOME>\\stage.",
|
|
8
8
|
"player_tags": "Your in-game name(s) for the optional game-HUD OCR in `cutpoint events` (who killed whom). Fuzzy match, ignores _ . - and spaces. `cutpoint events --player NAME` overrides it per run. Default: none.",
|
|
9
9
|
"ollama_url": "Ollama base URL for `analyze --vision` and the VLM layers of `cutpoint events`. Env OLLAMA_HOST overrides it. Default: http://127.0.0.1:11434.",
|
|
10
|
+
"vision": "true or false (default). true: `cutpoint analyze` and `cutpoint edit` rate the top candidates with the local Ollama vision model unless --no-vision is given (slower; uses several GB of GPU memory). false: only --vision turns it on for one run. The UI's Settings dialog writes it, and the UI's vision checkboxes start from it.",
|
|
11
|
+
"compress_peaks": "off (default), light or strong: peak compression and clip leveling of `cutpoint clips`, `assemble` and `edit` when --compress-peaks is not given (see docs/commands.md#peak-compression).",
|
|
12
|
+
"analysis": "{\"skip\": [...]}: analysis steps `cutpoint analyze` and `cutpoint edit` leave out by default; any of reactions, keyframes and crashes. --skip overrides it per run. Default: none.",
|
|
10
13
|
"video_encoder": "auto, nvenc, amf, vaapi or cpu (libx264). Env CUTPOINT_VIDEO_ENCODER overrides it. auto really encodes a short test clip with each GPU encoder and uses the first that works, else libx264; a named GPU encoder that does not work is an error. `cutpoint capabilities` shows what works. Default: auto.",
|
|
11
14
|
"pano": "Optional 360-camera (Insta360) module: sdk_exe = MediaSDKTest.exe of the Insta360 Media SDK, which you apply for yourself (see docs/insta360-sdk.md; env CUTPOINT_INSTA360_SDK overrides; default: auto-detected under <CUTPOINT_HOME>\\sdk\\insta360\\); stitch_timeout_s = kill one clip's stitch after this many seconds (default: no limit); stitched_dir = where `cutpoint 360 stitch` writes equirects (default <CUTPOINT_HOME>\\360-stitched; about 54 GB per hour of footage); studio_dirs = folders with Insta360 Studio equirect exports (default <CUTPOINT_HOME>\\360-studio); stitch_args = MediaSDKTest arguments; cmd_every = update the virtual camera every N frames (default 1; 2 halves the commands but leaves shake on every other frame); level_strength = horizon lock when stabilising, 1 = always level, 0 = follow the camera's own tilt (default 0.7); tilt_follow_s = smoothing (s) of the followed tilt (default 0.5); imu_offset_s = IMU-to-video time offset in seconds (default 0); equirect_yaw_offset = yaw correction in degrees for Studio exports (default 0); default_style = --style of `cutpoint 360 analyze` when none is given (default ski).",
|
|
12
15
|
"environment": "Not set here: CUTPOINT_HOME (data root), CUTPOINT_CONFIG (this file), CUTPOINT_CACHE_DIR, CUTPOINT_MODELS_DIR, CUTPOINT_TOOLS_DIR, CUTPOINT_STYLES_DIR, CUTPOINT_FFMPEG / CUTPOINT_FFPROBE, CUTPOINT_LLAMA_SERVER (path to llama-server; llama-server.exe on Windows), CUTPOINT_LLAMA_BACKEND (llama.cpp build `cutpoint setup` downloads: auto, cuda, vulkan or cpu; default auto), CUTPOINT_VISION_MODEL (Ollama model for `analyze --vision`, default qwen3-vl:8b) and OLLAMA_HOST (overrides ollama_url)."
|
|
@@ -23,6 +26,11 @@
|
|
|
23
26
|
"YourGameName"
|
|
24
27
|
],
|
|
25
28
|
"video_encoder": "auto",
|
|
29
|
+
"vision": false,
|
|
30
|
+
"compress_peaks": "off",
|
|
31
|
+
"analysis": {
|
|
32
|
+
"skip": []
|
|
33
|
+
},
|
|
26
34
|
"pano": {
|
|
27
35
|
"sdk_exe": "<CUTPOINT_HOME>\\sdk\\insta360\\MediaSDK-<version>-win64\\bin\\MediaSDKTest.exe",
|
|
28
36
|
"stitched_dir": "D:\\Footage\\360-stitched",
|
|
@@ -5,7 +5,7 @@ are logged as `ERROR` lines and the command exits with status 1.
|
|
|
5
5
|
|
|
6
6
|
| Symptom | Page |
|
|
7
7
|
|---|---|
|
|
8
|
-
| ffmpeg not found, GPU encoder issues (NVENC, AMF, VAAPI), slow encoding, CUDA or cuDNN errors, out of GPU memory | [ffmpeg and GPU](ffmpeg-gpu.md) |
|
|
8
|
+
| ffmpeg not found, GPU encoder issues (NVENC, AMF, VAAPI), slow encoding, CUDA or cuDNN errors, out of GPU memory, CPU-only torch on an NVIDIA machine (`capabilities` warning) | [ffmpeg and GPU](ffmpeg-gpu.md) |
|
|
9
9
|
| Ollama not reachable, model downloads fail, missing module, `setup` problems | [Models and Ollama](models.md) |
|
|
10
10
|
| Disk full, slow or network drives, read errors, damaged files | [Storage](storage.md) |
|
|
11
11
|
| 360 clips, SDK not found, stitching fails | [360 and the Insta360 SDK](360.md) |
|
|
@@ -21,14 +21,20 @@ nvidia-smi # driver and GPU are visible (NVIDIA)
|
|
|
21
21
|
|
|
22
22
|
| Message or symptom | Fix |
|
|
23
23
|
|---|---|
|
|
24
|
-
| `No module named ...` followed by an install command | An optional extra is missing. Run the printed
|
|
24
|
+
| `No module named ...` followed by an install command | An optional extra is missing. Run the printed command, listing every extra you use ([Optional extras](../getting-started.md#optional-extras)) |
|
|
25
25
|
| A command works in `uv run` but not as plain `cutpoint` | The tool is not on `PATH`. Use `uv run cutpoint`, install with `uv tool install cutpoint` (or `uv tool install .` from a clone), or use the wrappers `.\cutpoint.cmd` / `.\cutpoint.ps1` (Windows) or `./cutpoint` (Linux, needs `uv sync`) |
|
|
26
26
|
| PowerShell refuses to run `cutpoint.ps1` | Use `.\cutpoint.cmd`, or `uv run cutpoint` |
|
|
27
|
-
| `clips` refuses to write | The output folder is not empty. Use another `--out`, or `--force` to replace
|
|
27
|
+
| `clips` refuses to write | The output folder is not empty. Use another `--out`, or `--force` to replace its clips (they are replaced only when the new export succeeds) |
|
|
28
|
+
| `clips` or `extend` says `<folder> is a drive root`, `is a mount point` or `is on another file system than its parent folder` | The new clips are staged next to the folder and moved in, which cannot work at a drive root or across a mount. Nothing was exported or changed. Re-run with `--out` pointing at a folder on that drive |
|
|
29
|
+
| `clips`, `extend` or `assemble` stops with an ERROR naming `.<folder>.cutpoint-bak` | An earlier replace was cut short (for example a power loss) and its record in that hidden folder cannot be read. Nothing is deleted. Move the files from the backup folder back into the clips folder, delete the backup folder, and re-run |
|
|
30
|
+
| `Another cutpoint run ... is using <folder>` or `Another cutpoint run is starting on <folder>` (an empty or unreadable lock file; `folder_busy` with `--json`) | Another run holds the folder's lock. Wait for it or stop it, then re-run. Delete `.<folder>.cutpoint-lock` only if no run is active (for example after a crash, or a run on another computer) |
|
|
31
|
+
| `manifest.json may not be one cutpoint wrote` | `clips --force` and `extend` do not replace a manifest cutpoint did not write. Move or rename it, or use `--out`. An unreadable manifest is refused too (it used to be replaced) |
|
|
28
32
|
| `assemble` joined the wrong clips or order | It uses the `.mp4` files in the folder now, in natural filename order. Rename or delete files and run it again |
|
|
33
|
+
| `analyze` on `gaming` or `funny` runs out of GPU memory during `transcribe` or `reactions`, or the PC is sluggish then | The HUD OCR runs in the background during those steps ([analysis steps](../commands.md#analysis-steps)). Set `CUTPOINT_ANALYZE_OVERLAP=0` to run it in its turn; the results are the same |
|
|
29
34
|
| Results look stale after a code or setting change | Analysis is cached per source file in `<CUTPOINT_HOME>\cache`. The cache is safe to delete, or recompute layers with `events --force LAYER` |
|
|
30
35
|
| Wrong clips in `highlights.json` for silent footage | Scoring is heuristic and works best with voice or mic audio. Silent gameplay relies on loudness, scene cuts and vision only. Pick segments yourself with `clips --segments` |
|
|
31
36
|
| Whisper hallucinated text such as "Yeah. Yeah. Yeah." | Obvious repeats are filtered. Delete `cache\<source>\transcript-*.json` to re-transcribe with the full filter |
|
|
37
|
+
| `--vision` ratings stay the same on every rerun | Ratings are cached per source and per frame times, model and prompt, and the cache records the Ollama model's digest: a model pulled again under the same tag is rated again, and with Ollama down the cached ratings for the tag are used. Delete `cache\<source>\vision-ratings.json` to ask Ollama again |
|
|
32
38
|
|
|
33
39
|
If none of this helps, open an issue with the command, the log lines around the error, your OS
|
|
34
40
|
and GPU, and the output of `cutpoint paths`. Remove private paths first. Do not paste Insta360
|
|
@@ -83,9 +83,9 @@ Resolve Free has no Python API, so the hand-off is through files.
|
|
|
83
83
|
2. Pick `final.fcpxml`. `final.otio` also works.
|
|
84
84
|
3. Leave "Automatically import source clips into media pool" checked and click OK.
|
|
85
85
|
|
|
86
|
-
The timeline places the clips
|
|
87
|
-
|
|
88
|
-
Audio fades are baked into the clip files. If you move the clips folder, relink the media in
|
|
86
|
+
The timeline places the clips in filename order at their frame rate. With `--transition fade` it
|
|
87
|
+
holds a cross-dissolve at each join, starting on the edit, matching `final.mp4`; with cuts the
|
|
88
|
+
clips sit back to back. Audio fades are baked into the clip files. If you move the clips folder, relink the media in
|
|
89
89
|
Resolve or run `assemble` again.
|
|
90
90
|
|
|
91
91
|
## Reading slow or network sources once
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "cutpoint"
|
|
3
|
-
version = "0.
|
|
3
|
+
version = "0.3.0"
|
|
4
4
|
description = "Local, agent-driven AI video editor: finds highlights, cuts clips, builds montages, handles 360 video."
|
|
5
5
|
license = "MIT"
|
|
6
6
|
license-files = ["LICENSE"]
|
|
@@ -54,8 +54,13 @@ events = [
|
|
|
54
54
|
]
|
|
55
55
|
# `cutpoint ui`: local browser workspace for the standard-video highlight workflow.
|
|
56
56
|
ui = ["fastapi>=0.116", "uvicorn>=0.30"]
|
|
57
|
+
all = ["cutpoint[ski,events,gpu,ui]"]
|
|
58
|
+
|
|
59
|
+
[dependency-groups]
|
|
60
|
+
# Installed by default by `uv sync` / `uv run`; not part of the published wheel.
|
|
57
61
|
dev = ["pytest>=8", "ruff==0.17.1", "pre-commit>=3.7", "cutpoint[ui]", "httpx>=0.27"]
|
|
58
|
-
|
|
62
|
+
# Opt-in (`--group ocr-test`): CPU OCR for the slow discovery e2e test; CI syncs it, no torch.
|
|
63
|
+
ocr-test = ["rapidocr-onnxruntime>=1.4.4", "onnxruntime>=1.31.0"]
|
|
59
64
|
|
|
60
65
|
[project.scripts]
|
|
61
66
|
cutpoint = "cutpoint.cli:main"
|
|
@@ -97,6 +102,13 @@ explicit = true
|
|
|
97
102
|
|
|
98
103
|
[tool.pytest.ini_options]
|
|
99
104
|
testpaths = ["tests"]
|
|
105
|
+
# Only `hardware` is deselected by default; CI runs everything else (slow and ffmpeg included).
|
|
106
|
+
addopts = "-m \"not hardware\" --strict-markers"
|
|
107
|
+
markers = [
|
|
108
|
+
"slow: real subprocess or interpreter spawns, process trees, or over about 2 s",
|
|
109
|
+
"ffmpeg: runs the real ffmpeg or ffprobe",
|
|
110
|
+
"hardware: needs real GPU hardware (for example a VAAPI device), which CI does not have",
|
|
111
|
+
]
|
|
100
112
|
|
|
101
113
|
[tool.ruff]
|
|
102
114
|
target-version = "py312"
|
|
@@ -40,7 +40,6 @@ output is added on top of that profile. Built-in profiles live in
|
|
|
40
40
|
|
|
41
41
|
from __future__ import annotations
|
|
42
42
|
|
|
43
|
-
import importlib.util
|
|
44
43
|
import json
|
|
45
44
|
import logging
|
|
46
45
|
import re
|
|
@@ -50,9 +49,9 @@ from typing import Any
|
|
|
50
49
|
|
|
51
50
|
import numpy as np
|
|
52
51
|
|
|
53
|
-
from cutpoint import cache, paths, state
|
|
52
|
+
from cutpoint import cache, jsonout, paths, state
|
|
54
53
|
from cutpoint.config import remap_source
|
|
55
|
-
from cutpoint.events.common import load_highlights
|
|
54
|
+
from cutpoint.events.common import load_highlights
|
|
56
55
|
from cutpoint.events.visual import load_visual, text_embeddings
|
|
57
56
|
from cutpoint.ffmpeg_utils import FFmpegError, grab_frame_jpeg
|
|
58
57
|
from cutpoint.utils import slugify
|
|
@@ -237,12 +236,27 @@ def _text_emb(prompts: tuple[str, ...]) -> np.ndarray:
|
|
|
237
236
|
return text_embeddings(prompts)
|
|
238
237
|
|
|
239
238
|
|
|
240
|
-
def keyframes(
|
|
239
|
+
def keyframes(
|
|
240
|
+
project: Path, n: int = 240, warn_unreachable: bool = True
|
|
241
|
+
) -> tuple[np.ndarray, list[tuple[Path, float]]]:
|
|
241
242
|
"""Up to ``n`` cached keyframe embeddings ``(N, 768)`` spread over the project's
|
|
242
|
-
sources (visual layer), with their ``(source, time)``.
|
|
243
|
+
sources (visual layer), with their ``(source, time)``. An unreachable source is
|
|
244
|
+
skipped with one WARNING line and one ``footage_unreachable`` JSON warning, or at
|
|
245
|
+
DEBUG without ``warn_unreachable`` (the caller already warned)."""
|
|
243
246
|
|
|
244
247
|
embs, refs = [], []
|
|
245
248
|
for src in dict.fromkeys(s["path"] for s in load_highlights(project)["sources"]):
|
|
249
|
+
try:
|
|
250
|
+
cache.source_dir(Path(src)) # the visual cache key needs the file's size and mtime
|
|
251
|
+
except OSError as err:
|
|
252
|
+
if not warn_unreachable:
|
|
253
|
+
logger.debug("%s: footage not reachable (%s); no keyframes from it", src, err)
|
|
254
|
+
continue
|
|
255
|
+
logger.warning("%s: footage not reachable (%s); skipped", src, err)
|
|
256
|
+
jsonout.warn(
|
|
257
|
+
"footage_unreachable", f"{src}: footage not reachable ({err}); skipped", [src]
|
|
258
|
+
)
|
|
259
|
+
continue
|
|
246
260
|
vd = load_visual(Path(src))
|
|
247
261
|
if vd is not None and len(vd.t):
|
|
248
262
|
embs.append(vd.mean_emb)
|
|
@@ -381,17 +395,6 @@ def synthesize(
|
|
|
381
395
|
return prof
|
|
382
396
|
|
|
383
397
|
|
|
384
|
-
def _clip_installed() -> bool:
|
|
385
|
-
"""True if the CLIP steps after the LLM (crash prompts, dense check) can run.
|
|
386
|
-
|
|
387
|
-
Otherwise unloading Ollama frees VRAM for nothing (the events extra is missing).
|
|
388
|
-
"""
|
|
389
|
-
missing = [m for m in ("torch", "open_clip") if importlib.util.find_spec(m) is None]
|
|
390
|
-
if missing:
|
|
391
|
-
logger.info("activity: %s not installed; Ollama models stay loaded", ", ".join(missing))
|
|
392
|
-
return not missing
|
|
393
|
-
|
|
394
|
-
|
|
395
398
|
def _named_profile(context: str, lib: dict[str, dict[str, Any]]) -> str | None:
|
|
396
399
|
"""The library profile named as a word of ``context`` (``"downhill mtb"`` -> mtb).
|
|
397
400
|
|
|
@@ -417,6 +420,7 @@ def resolve(
|
|
|
417
420
|
refresh: bool = False,
|
|
418
421
|
ask: Ask | None = None,
|
|
419
422
|
llm: bool = True,
|
|
423
|
+
warn_unreachable: bool = True,
|
|
420
424
|
) -> dict[str, Any]:
|
|
421
425
|
"""Profile of a project, cached in ``<project>/activity.json`` (see the module doc).
|
|
422
426
|
|
|
@@ -427,6 +431,8 @@ def resolve(
|
|
|
427
431
|
refresh: Ignore activity.json.
|
|
428
432
|
ask: Vision / text model (default: local Ollama when ``llm``).
|
|
429
433
|
llm: Allow the local models (False: library and generic only).
|
|
434
|
+
warn_unreachable: Warn about each unreachable source when the footage is read
|
|
435
|
+
(:func:`keyframes`); False when the caller already did.
|
|
430
436
|
|
|
431
437
|
Returns:
|
|
432
438
|
The activity.json record; ``record["profile"]`` is the full profile.
|
|
@@ -441,7 +447,9 @@ def resolve(
|
|
|
441
447
|
activity, context = req.get("activity"), req.get("context")
|
|
442
448
|
lib = library()
|
|
443
449
|
if activity and activity not in lib:
|
|
444
|
-
raise
|
|
450
|
+
raise jsonout.ArgumentError(
|
|
451
|
+
f"unknown activity {activity!r}; known: {', '.join(sorted(lib))}"
|
|
452
|
+
)
|
|
445
453
|
context = " ".join(context.split())[:MAX_CONTEXT_CHARS] if context else None
|
|
446
454
|
request = {"activity": activity, "context": context}
|
|
447
455
|
if (
|
|
@@ -455,7 +463,7 @@ def resolve(
|
|
|
455
463
|
if activity:
|
|
456
464
|
seed, rec["source"] = activity, "flag"
|
|
457
465
|
else:
|
|
458
|
-
emb, refs = keyframes(project)
|
|
466
|
+
emb, refs = keyframes(project, warn_unreachable=warn_unreachable)
|
|
459
467
|
rec["scores"] = match_scores(emb, lib)
|
|
460
468
|
seed = pick(rec["scores"])
|
|
461
469
|
rec["source"] = "library" if seed else "fallback"
|
|
@@ -481,8 +489,8 @@ def resolve(
|
|
|
481
489
|
examples = [lib[seed]] if seed else [lib[k] for k in dict.fromkeys(near[:2])]
|
|
482
490
|
new = synthesize(desc, context, ask, examples) if desc or context else None
|
|
483
491
|
rec.update(description=desc, described_by=how, model=model)
|
|
484
|
-
if
|
|
485
|
-
|
|
492
|
+
if isinstance(rater := getattr(ask, "__self__", None), VisionRater):
|
|
493
|
+
rater.unload() # done with it: VRAM for the CLIP steps, other models stay
|
|
486
494
|
if new is not None: # LLM words add phrases, never re-weight known ones
|
|
487
495
|
known = (profile if seed else base())["incident"]["words"]
|
|
488
496
|
new["incident"]["words"] = {
|
|
@@ -501,11 +509,10 @@ def resolve(
|
|
|
501
509
|
named = _named_profile(context, lib) if seed is None else None
|
|
502
510
|
if named:
|
|
503
511
|
profile = full(lib[named])
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
)
|
|
512
|
+
used = f"; using the library profile {named!r} named in it" if named else ""
|
|
513
|
+
message = f"activity: --context not applied: {why}{used}"
|
|
514
|
+
logger.warning("%s", message)
|
|
515
|
+
jsonout.warn("context_not_applied", message)
|
|
509
516
|
rec["name"] = profile["name"]
|
|
510
517
|
rec["profile"] = profile
|
|
511
518
|
cache.save_json(path, rec)
|