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.
Files changed (125) hide show
  1. {cutpoint-0.2.0 → cutpoint-0.3.0}/.gitignore +2 -0
  2. cutpoint-0.3.0/AGENTS.md +206 -0
  3. {cutpoint-0.2.0 → cutpoint-0.3.0}/PKG-INFO +12 -13
  4. {cutpoint-0.2.0 → cutpoint-0.3.0}/README.md +9 -5
  5. {cutpoint-0.2.0 → cutpoint-0.3.0}/config.example.json +8 -0
  6. {cutpoint-0.2.0 → cutpoint-0.3.0}/docs/troubleshooting/README.md +9 -3
  7. {cutpoint-0.2.0 → cutpoint-0.3.0}/docs/workflows/README.md +3 -3
  8. {cutpoint-0.2.0 → cutpoint-0.3.0}/pyproject.toml +14 -2
  9. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/activity.py +32 -25
  10. cutpoint-0.3.0/src/cutpoint/analyze.py +2025 -0
  11. cutpoint-0.3.0/src/cutpoint/assemble.py +800 -0
  12. cutpoint-0.3.0/src/cutpoint/audio_tracks.py +238 -0
  13. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/boundaries.py +14 -28
  14. cutpoint-0.3.0/src/cutpoint/cache.py +396 -0
  15. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/capabilities.py +135 -5
  16. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/cli.py +666 -133
  17. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/clips.py +522 -133
  18. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/config.py +229 -29
  19. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/crash.py +181 -68
  20. cutpoint-0.3.0/src/cutpoint/dsp.py +38 -0
  21. cutpoint-0.3.0/src/cutpoint/edit.py +250 -0
  22. cutpoint-0.3.0/src/cutpoint/encode.py +838 -0
  23. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/audio_events.py +8 -2
  24. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/cli.py +55 -4
  25. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/common.py +78 -16
  26. cutpoint-0.3.0/src/cutpoint/events/discover.py +1473 -0
  27. cutpoint-0.3.0/src/cutpoint/events/eventtypes.py +309 -0
  28. cutpoint-0.3.0/src/cutpoint/events/game_profile.py +727 -0
  29. cutpoint-0.3.0/src/cutpoint/events/killfeed.py +2505 -0
  30. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/llama_server.py +16 -84
  31. cutpoint-0.3.0/src/cutpoint/events/ocr_prefetch.py +461 -0
  32. cutpoint-0.3.0/src/cutpoint/events/ocr_raw.py +260 -0
  33. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/paths.py +8 -18
  34. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/pipeline.py +286 -100
  35. cutpoint-0.3.0/src/cutpoint/events/presets/.gitkeep +0 -0
  36. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/regions.py +114 -82
  37. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/report.py +19 -19
  38. cutpoint-0.3.0/src/cutpoint/events/scoring.py +227 -0
  39. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/setup.py +11 -9
  40. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/tails.py +21 -28
  41. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/visual.py +138 -24
  42. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/vlm_windows.py +107 -63
  43. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/voice.py +19 -4
  44. cutpoint-0.3.0/src/cutpoint/extend.py +639 -0
  45. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/extras.py +104 -3
  46. cutpoint-0.3.0/src/cutpoint/ffmpeg_utils.py +2669 -0
  47. cutpoint-0.3.0/src/cutpoint/jsonout.py +242 -0
  48. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/mix.py +116 -49
  49. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/check.py +5 -5
  50. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/cli.py +337 -90
  51. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/director.py +144 -36
  52. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/geometry.py +61 -104
  53. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/qa.py +168 -72
  54. cutpoint-0.3.0/src/cutpoint/pano/qa_horizon.py +134 -0
  55. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/qa_paths.py +44 -44
  56. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/render.py +132 -47
  57. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/repair.py +203 -67
  58. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/stitch.py +72 -55
  59. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/views.py +92 -32
  60. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/vlcheck.py +12 -10
  61. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/x3.py +21 -10
  62. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/paths.py +2 -3
  63. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/planning.py +163 -17
  64. cutpoint-0.3.0/src/cutpoint/progress.py +290 -0
  65. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/refmatch.py +93 -71
  66. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/ski.py +66 -32
  67. cutpoint-0.3.0/src/cutpoint/skill/SKILL.md +91 -0
  68. cutpoint-0.3.0/src/cutpoint/skill/__init__.py +49 -0
  69. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/sources.py +69 -22
  70. cutpoint-0.3.0/src/cutpoint/srt.py +330 -0
  71. cutpoint-0.3.0/src/cutpoint/stage.py +644 -0
  72. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/state.py +21 -8
  73. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/styles.py +9 -10
  74. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/telemetry.py +74 -48
  75. cutpoint-0.3.0/src/cutpoint/timeline.py +217 -0
  76. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/transcribe.py +48 -9
  77. cutpoint-0.3.0/src/cutpoint/ui.py +2826 -0
  78. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/utils.py +99 -3
  79. cutpoint-0.3.0/src/cutpoint/vision.py +374 -0
  80. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/web/api.js +21 -1
  81. cutpoint-0.3.0/src/cutpoint/web/app.css +550 -0
  82. cutpoint-0.3.0/src/cutpoint/web/app.js +2951 -0
  83. cutpoint-0.3.0/src/cutpoint/web/index.html +277 -0
  84. cutpoint-0.3.0/src/cutpoint/web/picker.js +96 -0
  85. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/web/util.js +14 -0
  86. cutpoint-0.3.0/src/cutpoint/winjob.py +84 -0
  87. cutpoint-0.2.0/AGENTS.md +0 -145
  88. cutpoint-0.2.0/src/cutpoint/analyze.py +0 -1261
  89. cutpoint-0.2.0/src/cutpoint/assemble.py +0 -489
  90. cutpoint-0.2.0/src/cutpoint/cache.py +0 -145
  91. cutpoint-0.2.0/src/cutpoint/dsp.py +0 -16
  92. cutpoint-0.2.0/src/cutpoint/encode.py +0 -215
  93. cutpoint-0.2.0/src/cutpoint/events/discover.py +0 -570
  94. cutpoint-0.2.0/src/cutpoint/events/killfeed.py +0 -1366
  95. cutpoint-0.2.0/src/cutpoint/events/presets/wt.json +0 -90
  96. cutpoint-0.2.0/src/cutpoint/events/scoring.py +0 -138
  97. cutpoint-0.2.0/src/cutpoint/extend.py +0 -461
  98. cutpoint-0.2.0/src/cutpoint/ffmpeg_utils.py +0 -1152
  99. cutpoint-0.2.0/src/cutpoint/stage.py +0 -374
  100. cutpoint-0.2.0/src/cutpoint/timeline.py +0 -140
  101. cutpoint-0.2.0/src/cutpoint/ui.py +0 -895
  102. cutpoint-0.2.0/src/cutpoint/vision.py +0 -215
  103. cutpoint-0.2.0/src/cutpoint/web/app.css +0 -242
  104. cutpoint-0.2.0/src/cutpoint/web/app.js +0 -813
  105. cutpoint-0.2.0/src/cutpoint/web/index.html +0 -162
  106. cutpoint-0.2.0/src/cutpoint/web/picker.js +0 -107
  107. {cutpoint-0.2.0 → cutpoint-0.3.0}/LICENSE +0 -0
  108. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/__init__.py +0 -0
  109. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/__main__.py +0 -0
  110. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/backends.py +0 -0
  111. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/crop.py +0 -0
  112. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/__init__.py +0 -0
  113. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/events/sheets.py +0 -0
  114. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/__init__.py +0 -0
  115. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/pano/project.py +0 -0
  116. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/presets/activities/base.json +0 -0
  117. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/presets/activities/generic.json +0 -0
  118. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/presets/activities/hike.json +0 -0
  119. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/presets/activities/moto.json +0 -0
  120. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/presets/activities/mtb.json +0 -0
  121. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/presets/activities/skate.json +0 -0
  122. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/presets/activities/ski.json +0 -0
  123. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/presets/activities/snowboard.json +0 -0
  124. {cutpoint-0.2.0 → cutpoint-0.3.0}/src/cutpoint/presets/activities/surf.json +0 -0
  125. {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)
@@ -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.2.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
- Provides-Extra: dev
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
- One-command editing (`cutpoint edit`), a first-run setup wizard and an agent skill are
104
- planned. Today the agent runs the steps itself using [AGENTS.md](https://github.com/FerventOrange/cutpoint/blob/main/AGENTS.md).
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 does not
118
- expose the specialized action-cam or 360 workflows.
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
- One-command editing (`cutpoint edit`), a first-run setup wizard and an agent skill are
42
- planned. Today the agent runs the steps itself using [AGENTS.md](https://github.com/FerventOrange/cutpoint/blob/main/AGENTS.md).
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 does not
56
- expose the specialized action-cam or 360 workflows.
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 `uv sync --extra ...` command and list every extra you use, because `uv sync` removes the packages of extras you leave out |
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 it |
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 back to back in filename order at their frame rate. It uses hard
87
- cuts even if the MP4 was built with `--transition fade`, so you can add transitions in Resolve.
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.2.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
- all = ["cutpoint[ski,events,gpu]"]
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, unload_ollama
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(project: Path, n: int = 240) -> tuple[np.ndarray, list[tuple[Path, float]]]:
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 ValueError(f"unknown activity {activity!r}; known: {', '.join(sorted(lib))}")
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 model is not None and _clip_installed(): # free its VRAM for the CLIP steps
485
- unload_ollama()
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
- logger.warning(
505
- "activity: --context not applied: %s%s",
506
- why,
507
- f"; using the library profile {named!r} named in it" if named else "",
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)