cutpoint 0.1.0__tar.gz

cutpoint-0.1.0/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Runtime data (lives in CUTPOINT_HOME, default %LOCALAPPDATA%\cutpoint)
+cache/
+models/
+tools/llama.cpp/
+stage/
+projects/
+
+# Local, personal config and learned styles (old repo-root layout; now in CUTPOINT_HOME,
+# keys documented in config.example.json)
+config.json
+styles_learned/
+EDIT_NOTES.md
+
+# Media
+*.mp4
+*.mov
+*.mkv
+*.insv
+*.lrv
+*.wav
+*.npy
+*.npz
+
+# OS / editors
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+
+# Insta360 SDK (under NDA): never commit SDK files; keep them outside the repo,
+# e.g. in <CUTPOINT_HOME>/sdk/insta360/
+sdk/
+**/insta360/
+MediaSDK*
+RealTimeStitcherSDKTest*
+*CameraSDK*
+*InsMetaDataSDK*
+*.deb
+ins_stitcher.h
+ins_common.h
+ins_realtime_stitcher.h

cutpoint-0.1.0/AGENTS.md

@@ -0,0 +1,139 @@
+# Cutpoint for AI agents
+
+You are an AI agent asked to edit video with Cutpoint. This file is what you need. Read this any
+time with `cutpoint guide`. If you are instead changing this repository's code, read
+[CONTRIBUTING.md](https://github.com/FerventOrange/cutpoint/blob/main/CONTRIBUTING.md).
+
+Cutpoint finds the best moments in long recordings, exports them as numbered clips and
+assembles a finished video. It runs locally, never modifies source videos, and writes
+everything into a project folder.
+
+## Status: what you can rely on
+
+| Available now | Planned (do not call; it does not exist yet) |
+|---|---|
+| CLI `cutpoint` with the commands below | `cutpoint edit`, `cutpoint init` |
+| Result files in the project folder (JSON and text) | JSON on stdout for every command |
+| Activity profiles for crash detection: `cutpoint profile`, `--context` on `profile` and `crashes` | Agent skill, profiles for the other layers and for games |
+
+If the user asks for "edit this video and make it a montage" in one step, do it with the loop
+below.
+
+## Calling the CLI
+
+- If installed as a tool (`uv tool install cutpoint`), run `cutpoint <command> ...`; from a
+  clone, `uv run cutpoint <command> ...`. The examples below use `uv run cutpoint`; with a tool
+  install, drop `uv run`. First-time setup is in
+  [docs/getting-started.md](https://github.com/FerventOrange/cutpoint/blob/main/docs/getting-started.md).
+  Check it works with `cutpoint paths` (or `uv run cutpoint paths`).
+- Exit codes: `0` success, `1` error, `130` interrupted, `2` bad arguments.
+- Logs and errors go to stderr as `HH:MM:SS LEVEL message`; errors are `ERROR` lines. Use
+  `cutpoint -v <command>` (flag before the command) for debug output and tracebacks.
+- Paths inside a project must start with `projects\<name>\...` or be absolute; a bare name means
+  the project itself.
+- Results are files, not stdout. Read the JSON files below instead of parsing logs.
+- Commands are re-runnable. Per-source results are cached (path, size, modification time).
+  `clips` refuses a non-empty output folder without `--force`.
+- Transcription, `events` and export can take minutes to hours. Run them in the background or
+  with a long timeout.
+- Never modify or delete the user's source videos. You may delete or rename clips in a project's
+  `clips` folder during review.
+- Use the real options: `cutpoint <command> --help` is authoritative;
+  [docs/commands.md](https://github.com/FerventOrange/cutpoint/blob/main/docs/commands.md)
+  explains them.
+
+## The full edit
+
+Given a request such as "edit D:\Videos\clip.mp4 into a funny-moments montage":
+
+1. **Pick a style** from the request: `funny`, `gaming`, `action`, `sport`, `commentary`
+   (long talk), `ski` (action-cam with telemetry). Footage that is not any of these: use `action`
+   or `gaming`.
+2. **Analyze.**
+
+   ```powershell
+   uv run cutpoint analyze D:\Videos\clip.mp4 --style funny --out clip-edit
+   ```
+
+   Writes `highlights.json` and `transcript.txt` into the project folder (`<projects>\clip-edit`, see
+   `cutpoint paths`).
+3. **Optional, game footage or when a model-based pass is requested:**
+   `uv run cutpoint events clip-edit` (needs the `events` extra and `cutpoint setup`). It
+   re-ranks `highlights.json` and writes `events.json` and `events.txt`. If it reports a missing
+   module, tell the user how to add the extra (see [When something fails](#when-something-fails)).
+4. **Choose moments.** Read `highlights.json` (`candidates` with `id`, `source`, `start`, `end`,
+   `score` 0-100, `label`, `transcript`; `suggested_top`) and, for banter and funny moments,
+   `transcript.txt` (`[file.mp4 00:12:31.4-00:12:38.9] text`). Then either:
+   - take the top N: `uv run cutpoint clips clip-edit --top 8` (or `--max-total 60` for a
+     length cap, `--ids h001 h004`), or
+   - export your own picks with a segments file:
+
+     ```json
+     [
+       {"source": "D:/Videos/clip.mp4", "start": 312.4, "end": 330.0, "label": "intro"},
+       {"source": "D:/Videos/clip.mp4", "start": 1204.0, "end": 1219.5, "label": "joke"}
+     ]
+     ```
+
+     `uv run cutpoint clips clip-edit --segments segments.json`
+5. **Review.** Clips are `clips\001_<label>.mp4`, `002_...`, and `clips\manifest.json` maps each
+   to its source and times. Tell the user what was exported. Delete clips the user rejects and
+   rename to reorder (for example `005_x.mp4` to `001b_x.mp4`).
+6. **Assemble.**
+
+   ```powershell
+   uv run cutpoint assemble projects\clip-edit\clips --transition fade --loudnorm
+   ```
+
+   Writes `final.mp4`, `final.fcpxml` and `final.otio` in the project folder.
+7. **Report** the paths of `final.mp4` and the clips folder.
+
+Variants:
+
+| Request | Do |
+|---|---|
+| Short clip or reel for social media | `clips <project> --vertical --max-total 60`, then `assemble projects\<project>\clips_vertical --captions` |
+| Highlights of a specific length | `clips <project> --max-total <seconds>` |
+| "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 |
+| 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`. Use `--activity NAME` only when the user names a sport that has a profile. Do not edit profile files |
+| Room to trim in an editor | `clips ... --extend 1.5` or `extend <clips_dir> --seconds 2` |
+| 360 (Insta360 X3) footage | [docs/workflows/360.md](https://github.com/FerventOrange/cutpoint/blob/main/docs/workflows/360.md) |
+| Action-cam with telemetry | [docs/workflows/action-cam.md](https://github.com/FerventOrange/cutpoint/blob/main/docs/workflows/action-cam.md) |
+| Gameplay with kill feeds | [docs/workflows/game-streams.md](https://github.com/FerventOrange/cutpoint/blob/main/docs/workflows/game-streams.md) |
+
+## Project files
+
+| File | Written by | Content |
+|---|---|---|
+| `highlights.json` | `analyze`, `events` | Ranked candidates and settings |
+| `transcript.txt` | `analyze` | Time-stamped transcript |
+| `events.json`, `events.txt` | `events` | Detected sounds, HUD events, model descriptions |
+| `clips/manifest.json` | `clips`, `extend` | Per clip: source, start, end, score, label, tail, crop |
+| `final.mp4`, `final.fcpxml`, `final.otio` | `assemble` | Result and timelines |
+| `crashes.json`, `telemetry.json`, `mix_segments.json` | action-cam commands | See the action-cam page |
+| `activity.json` | `profile`, `crashes` | Activity profile in use: `name`, `source`, `profile` |
+
+## When something fails
+
+Read the `ERROR` line, then
+[docs/troubleshooting/README.md](https://github.com/FerventOrange/cutpoint/blob/main/docs/troubleshooting/README.md).
+The usual causes: ffmpeg not on `PATH`, a missing optional extra, Ollama not reachable (only
+affects `--vision`), a non-empty output folder.
+
+A missing extra `X` (for example `events`) is added differently per install. Tell the user the
+command for theirs:
+
+- From a clone: `uv sync --extra X`, listing every other extra in use too (the error prints this
+  form).
+- Tool install: `uv tool install "cutpoint[X]" --reinstall`, listing every extra in use. With an
+  NVIDIA GPU and the `events` extra, add
+  `--index https://download.pytorch.org/whl/cu126 --index-strategy unsafe-best-match` so torch
+  uses CUDA ([getting started](https://github.com/FerventOrange/cutpoint/blob/main/docs/getting-started.md#install-as-a-tool-optional)).
+
+## Rules
+
+- Ask the user before running `cutpoint setup` (about 8 GB of downloads), `cutpoint stage`
+  (copies footage to local disk) or `clips --force` over an existing folder.
+- Do not paste Insta360 SDK files, documentation or output into any file or message, other than
+  `error:` lines.
+- Do not invent options. Check `--help`.

cutpoint-0.1.0/LICENSE

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

cutpoint-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.5
+Name: cutpoint
+Version: 0.1.0
+Summary: Local, agent-driven AI video editor: finds highlights, cuts clips, builds montages, handles 360 video.
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: <3.13,>=3.12
+Requires-Dist: faster-whisper>=1.2.1
+Requires-Dist: numpy<3,>=2.5.4
+Requires-Dist: nvidia-cublas-cu12>=12.4; sys_platform == 'linux'
+Requires-Dist: nvidia-cublas-cu12>=12.9.2.10; sys_platform == 'win32'
+Requires-Dist: nvidia-cudnn-cu12>=9.1; sys_platform == 'linux'
+Requires-Dist: nvidia-cudnn-cu12>=9.27.0.42; sys_platform == 'win32'
+Requires-Dist: opencv-python>=5.0.0.93
+Requires-Dist: opentimelineio>=0.18.1
+Requires-Dist: requests>=2.34.2
+Requires-Dist: scenedetect>=0.7.2
+Provides-Extra: all
+Requires-Dist: onnxruntime>=1.31.0; extra == 'all'
+Requires-Dist: open-clip-torch>=3.3.0; extra == 'all'
+Requires-Dist: panns-inference>=0.1.1; extra == 'all'
+Requires-Dist: rapidocr-onnxruntime>=1.4.4; extra == 'all'
+Requires-Dist: scikit-learn>=1.9.1; extra == 'all'
+Requires-Dist: scipy>=1.18.1; extra == 'all'
+Requires-Dist: telemetry-parser>=0.3.0; extra == 'all'
+Requires-Dist: torch==2.14.1; extra == 'all'
+Requires-Dist: torchlibrosa>=0.1.0; extra == 'all'
+Requires-Dist: torchvision==0.29.1; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff==0.17.1; extra == 'dev'
+Provides-Extra: events
+Requires-Dist: onnxruntime>=1.31.0; extra == 'events'
+Requires-Dist: open-clip-torch>=3.3.0; extra == 'events'
+Requires-Dist: panns-inference>=0.1.1; extra == 'events'
+Requires-Dist: rapidocr-onnxruntime>=1.4.4; extra == 'events'
+Requires-Dist: scikit-learn>=1.9.1; extra == 'events'
+Requires-Dist: scipy>=1.18.1; extra == 'events'
+Requires-Dist: torch==2.14.1; extra == 'events'
+Requires-Dist: torchlibrosa>=0.1.0; extra == 'events'
+Requires-Dist: torchvision==0.29.1; extra == 'events'
+Provides-Extra: gpu
+Provides-Extra: ski
+Requires-Dist: telemetry-parser>=0.3.0; extra == 'ski'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/FerventOrange/cutpoint/main/docs/assets/logo-256.png" alt="Cutpoint logo: a clapperboard with three characters peeking out" width="200">
+</p>
+
+# Cutpoint
+
+Cutpoint is an AI video editor that your coding agent drives. Tell the agent to edit a video and
+it finds the best moments, cuts them into clips and assembles the result. All analysis runs on
+your own computer, so your agent does not spend API credits on video, and your original files
+are never changed.
+
+[Are you an AI agent? Start here](https://github.com/FerventOrange/cutpoint/blob/main/AGENTS.md)
+
+(Installed from PyPI? Run `cutpoint guide`.)
+
+## What you get
+
+- Trimmed, numbered clips of the best moments
+- A transcript of the video with timestamps
+- A finished video, `final.mp4`, plus timelines you can open in DaVinci Resolve
+- Vertical (9:16) versions for shorts and reels
+- Works on gameplay, action-cam, sport, funny moments, commentary and 360 video
+
+## Use it
+
+1. Install Cutpoint (below).
+2. Open your agent (Claude Code, Codex, Grok CLI or any CLI agent) in the Cutpoint folder, or
+   tell it where Cutpoint is.
+3. Ask it to edit your video:
+
+   > Edit D:\Videos\clip.mp4 into a 60 second highlights video with Cutpoint.
+
+   > Find the funniest moments in ~/Videos/stream.mp4 and show me the clips before you
+   > assemble them.
+
+   > Make a vertical montage from ~/Videos/ride.mp4.
+
+The agent runs Cutpoint, shows you the clips and writes the result into a project folder.
+Delete or rename clips to change the cut, then ask the agent to assemble again.
+
+One-command editing (`cutpoint edit`), a first-run setup wizard and an agent skill are
+planned. Today the agent runs the steps itself using [AGENTS.md](https://github.com/FerventOrange/cutpoint/blob/main/AGENTS.md).
+
+## Requirements
+
+- Windows or Linux
+- Python 3.12 and [uv](https://docs.astral.sh/uv/)
+- ffmpeg
+- An NVIDIA GPU is recommended. Without one, everything still runs but slower.
+- Optional: Ollama for AI frame rating, extra downloads (about 8 GB) for sound, on-screen text
+  and scene-description features
+
+## Install
+
+```powershell
+winget install --id Gyan.FFmpeg -e
+winget install --id astral-sh.uv -e
+git clone https://github.com/FerventOrange/cutpoint.git
+cd cutpoint
+uv sync
+uv run cutpoint paths
+```
+
+To get a global `cutpoint` command instead, run `uv tool install cutpoint` (from PyPI) after
+installing ffmpeg and uv.
+
+On Linux, install ffmpeg and uv with your package manager or their installers, then run the
+last four commands. The optional extras and model downloads are explained in
+[Getting started](https://github.com/FerventOrange/cutpoint/blob/main/docs/getting-started.md).
+
+## Documentation
+
+- [Getting started](https://github.com/FerventOrange/cutpoint/blob/main/docs/getting-started.md): install, first run, where data is stored, models
+- [Using Cutpoint from an agent](https://github.com/FerventOrange/cutpoint/blob/main/docs/agents.md): set up Claude Code, Codex, Grok or another agent
+- [Workflows](https://github.com/FerventOrange/cutpoint/blob/main/docs/workflows/README.md): montages, game streams, action-cam, 360 video, vertical output
+- [Command reference](https://github.com/FerventOrange/cutpoint/blob/main/docs/commands.md)
+- [Configuration](https://github.com/FerventOrange/cutpoint/blob/main/docs/configuration.md)
+- [Troubleshooting](https://github.com/FerventOrange/cutpoint/blob/main/docs/troubleshooting/README.md)
+- [FAQ](https://github.com/FerventOrange/cutpoint/blob/main/docs/faq.md)
+- [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)
+- [Insta360 SDK](https://github.com/FerventOrange/cutpoint/blob/main/docs/insta360-sdk.md): optional, for high-quality 360 stitching
+
+## License
+
+Cutpoint is released under the [MIT License](https://github.com/FerventOrange/cutpoint/blob/main/LICENSE).

cutpoint-0.1.0/README.md

@@ -0,0 +1,85 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/FerventOrange/cutpoint/main/docs/assets/logo-256.png" alt="Cutpoint logo: a clapperboard with three characters peeking out" width="200">
+</p>
+
+# Cutpoint
+
+Cutpoint is an AI video editor that your coding agent drives. Tell the agent to edit a video and
+it finds the best moments, cuts them into clips and assembles the result. All analysis runs on
+your own computer, so your agent does not spend API credits on video, and your original files
+are never changed.
+
+[Are you an AI agent? Start here](https://github.com/FerventOrange/cutpoint/blob/main/AGENTS.md)
+
+(Installed from PyPI? Run `cutpoint guide`.)
+
+## What you get
+
+- Trimmed, numbered clips of the best moments
+- A transcript of the video with timestamps
+- A finished video, `final.mp4`, plus timelines you can open in DaVinci Resolve
+- Vertical (9:16) versions for shorts and reels
+- Works on gameplay, action-cam, sport, funny moments, commentary and 360 video
+
+## Use it
+
+1. Install Cutpoint (below).
+2. Open your agent (Claude Code, Codex, Grok CLI or any CLI agent) in the Cutpoint folder, or
+   tell it where Cutpoint is.
+3. Ask it to edit your video:
+
+   > Edit D:\Videos\clip.mp4 into a 60 second highlights video with Cutpoint.
+
+   > Find the funniest moments in ~/Videos/stream.mp4 and show me the clips before you
+   > assemble them.
+
+   > Make a vertical montage from ~/Videos/ride.mp4.
+
+The agent runs Cutpoint, shows you the clips and writes the result into a project folder.
+Delete or rename clips to change the cut, then ask the agent to assemble again.
+
+One-command editing (`cutpoint edit`), a first-run setup wizard and an agent skill are
+planned. Today the agent runs the steps itself using [AGENTS.md](https://github.com/FerventOrange/cutpoint/blob/main/AGENTS.md).
+
+## Requirements
+
+- Windows or Linux
+- Python 3.12 and [uv](https://docs.astral.sh/uv/)
+- ffmpeg
+- An NVIDIA GPU is recommended. Without one, everything still runs but slower.
+- Optional: Ollama for AI frame rating, extra downloads (about 8 GB) for sound, on-screen text
+  and scene-description features
+
+## Install
+
+```powershell
+winget install --id Gyan.FFmpeg -e
+winget install --id astral-sh.uv -e
+git clone https://github.com/FerventOrange/cutpoint.git
+cd cutpoint
+uv sync
+uv run cutpoint paths
+```
+
+To get a global `cutpoint` command instead, run `uv tool install cutpoint` (from PyPI) after
+installing ffmpeg and uv.
+
+On Linux, install ffmpeg and uv with your package manager or their installers, then run the
+last four commands. The optional extras and model downloads are explained in
+[Getting started](https://github.com/FerventOrange/cutpoint/blob/main/docs/getting-started.md).
+
+## Documentation
+
+- [Getting started](https://github.com/FerventOrange/cutpoint/blob/main/docs/getting-started.md): install, first run, where data is stored, models
+- [Using Cutpoint from an agent](https://github.com/FerventOrange/cutpoint/blob/main/docs/agents.md): set up Claude Code, Codex, Grok or another agent
+- [Workflows](https://github.com/FerventOrange/cutpoint/blob/main/docs/workflows/README.md): montages, game streams, action-cam, 360 video, vertical output
+- [Command reference](https://github.com/FerventOrange/cutpoint/blob/main/docs/commands.md)
+- [Configuration](https://github.com/FerventOrange/cutpoint/blob/main/docs/configuration.md)
+- [Troubleshooting](https://github.com/FerventOrange/cutpoint/blob/main/docs/troubleshooting/README.md)
+- [FAQ](https://github.com/FerventOrange/cutpoint/blob/main/docs/faq.md)
+- [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)
+- [Insta360 SDK](https://github.com/FerventOrange/cutpoint/blob/main/docs/insta360-sdk.md): optional, for high-quality 360 stitching
+
+## License
+
+Cutpoint is released under the [MIT License](https://github.com/FerventOrange/cutpoint/blob/main/LICENSE).

cutpoint-0.1.0/config.example.json

@@ -0,0 +1,46 @@
+{
+  "_doc": {
+    "about": "Example Cutpoint settings. Copy to <CUTPOINT_HOME>\\config.json (run `cutpoint paths` to see where that is) and keep only the keys you need; every key is optional. Keys starting with '_' are ignored.",
+    "projects_dir": "Folder for project folders. A bare project name (my-trip) or projects\\<name> argument is placed here. Env CUTPOINT_PROJECTS_DIR overrides it. Default: <CUTPOINT_HOME>\\projects.",
+    "source_remap": "{old prefix: new prefix}. Point old paths at a new location when footage moves (another drive, a backup copy): a source under an old prefix is read from the new prefix when the file exists there. Projects and cache keys keep the original path, so nothing has to be re-analysed.",
+    "source_remap_exclude": "File-name or full-path globs that are never remapped (e.g. a copy that is not verified yet).",
+    "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.",
+    "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.",
+    "ollama_url": "Ollama base URL for `analyze --vision` and the VLM layers of `cutpoint events`. Env OLLAMA_HOST overrides it. Default: http://localhost:11434.",
+    "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).",
+    "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 (llama-server.exe), CUTPOINT_VISION_MODEL (Ollama model for `analyze --vision`, default qwen3-vl:8b) and OLLAMA_HOST (overrides ollama_url)."
+  },
+  "projects_dir": "D:\\Footage\\cutpoint-projects",
+  "source_remap": {
+    "D:\\Footage": "E:\\Footage-copy"
+  },
+  "source_remap_exclude": [
+    "*unverified*"
+  ],
+  "stage_dir": "C:\\Cutpoint\\stage",
+  "player_tags": [
+    "YourGameName"
+  ],
+  "pano": {
+    "sdk_exe": "<CUTPOINT_HOME>\\sdk\\insta360\\MediaSDK-<version>-win64\\bin\\MediaSDKTest.exe",
+    "stitched_dir": "D:\\Footage\\360-stitched",
+    "stitch_timeout_s": 7200,
+    "studio_dirs": [
+      "D:\\Footage\\360-studio"
+    ],
+    "stitch_args": [
+      "-stitch_type", "optflow",
+      "-output_size", "5760x2880",
+      "-enable_h265_encoder",
+      "-bitrate", "100000000",
+      "-enable_flowstate",
+      "-enable_stitchfusion"
+    ],
+    "cmd_every": 1,
+    "level_strength": 0.7,
+    "tilt_follow_s": 0.5,
+    "imu_offset_s": 0.0,
+    "equirect_yaw_offset": 0.0,
+    "default_style": "ski"
+  }
+}

cutpoint-0.1.0/docs/troubleshooting/README.md

@@ -0,0 +1,36 @@
+# Troubleshooting
+
+Start with `cutpoint -v <command> ...`: `-v` turns on debug logging and prints tracebacks. Errors
+are logged as `ERROR` lines and the command exits with status 1.
+
+| Symptom | Page |
+|---|---|
+| ffmpeg not found, NVENC errors, slow encoding, CUDA or cuDNN errors, out of GPU memory | [ffmpeg and GPU](ffmpeg-gpu.md) |
+| Ollama not reachable, model downloads fail, missing module, `setup` problems | [Models and Ollama](models.md) |
+| Disk full, slow or network drives, read errors, damaged files | [Storage](storage.md) |
+| 360 clips, SDK not found, stitching fails | [360 and the Insta360 SDK](360.md) |
+
+## Quick checks
+
+```powershell
+cutpoint paths                  # where Cutpoint looks for data
+ffmpeg -version                 # ffmpeg is installed and on PATH
+nvidia-smi                      # driver and GPU are visible (NVIDIA)
+```
+
+## Common messages
+
+| Message or symptom | Fix |
+|---|---|
+| `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 |
+| 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` |
+| PowerShell refuses to run `cutpoint.ps1` | Use `.\cutpoint.cmd`, or `uv run cutpoint` |
+| `clips` refuses to write | The output folder is not empty. Use another `--out`, or `--force` to replace it |
+| `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 |
+| 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` |
+| 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` |
+| Whisper hallucinated text such as "Yeah. Yeah. Yeah." | Obvious repeats are filtered. Delete `cache\<source>\transcript-*.json` to re-transcribe with the full filter |
+
+If none of this helps, open an issue with the command, the log lines around the error, your OS
+and GPU, and the output of `cutpoint paths`. Remove private paths first. Do not paste Insta360
+SDK files, documentation or output.

cutpoint-0.1.0/docs/workflows/README.md

@@ -0,0 +1,94 @@
+# Workflows
+
+All examples use `cutpoint` for `uv run cutpoint`. Paths are examples; use your own.
+
+| Page | Use it for |
+|---|---|
+| This page | Montage and highlights from any video, vertical output, importing into Resolve |
+| [Game streams](game-streams.md) | Gameplay and stream recordings, HUD OCR, boxed stream layouts |
+| [Action-cam](action-cam.md) | GoPro-style footage with telemetry: jumps, crashes, a varied mix |
+| [360 video](360.md) | Insta360 X3: mix, director, QA, repair, clips, assemble |
+| [360 director](360-director.md) | How the 360 virtual-camera director works |
+
+## Montage or highlights from one or more videos
+
+```powershell
+# 1. Find and rank moments. Writes projects\my-edit\highlights.json and transcript.txt
+cutpoint analyze D:\Videos\clip.mp4 --style gaming --out my-edit
+
+# Several files and folders at once, skipping some by glob:
+cutpoint analyze D:\Videos\session1 D:\Videos\extra.mp4 --exclude "*DVR*" --style gaming --out my-edit
+
+# 2. Optional: detect what happens (sounds, HUD text, model descriptions).
+#    Needs the `events` extra and `cutpoint setup`. Re-ranks highlights.json.
+cutpoint events my-edit
+
+# 3. Export the best moments as 001_<label>.mp4, 002_<label>.mp4, ...
+cutpoint clips my-edit --top 8
+
+# 4. Review projects\my-edit\clips. Delete clips you do not want; rename to reorder.
+
+# 5. Build the video from whatever is in the folder, in filename order.
+cutpoint assemble projects\my-edit\clips --transition fade --loudnorm
+```
+
+Output: `projects\my-edit\final.mp4`, `final.fcpxml` and `final.otio`.
+
+Choose the style by content: `funny` for banter and laughter, `gaming` or `action` for fast
+footage, `sport` for crowd-driven events, `commentary` for long talk (clips of 20-120 s, in
+chronological order).
+
+### Pick moments yourself
+
+Read `transcript.txt` (or `events.txt` after `events`), then write the ranges you want:
+
+```json
+[
+  {"source": "D:/Videos/clip.mp4", "start": 312.4, "end": 330.0, "label": "intro"},
+  {"source": "D:/Videos/clip.mp4", "start": 1204.0, "end": 1219.5, "label": "joke"}
+]
+```
+
+```powershell
+cutpoint clips my-edit --segments segments.json
+```
+
+You can mix hand-picked segments with auto-scored ones by exporting both and joining the clips.
+Per-segment options (tails, crop, padding) are in the [command reference](../commands.md#clips).
+
+### More room for trimming
+
+If you will trim in an editor, export handles:
+
+```powershell
+cutpoint clips my-edit --top 8 --extend 1.5         # padding at export
+cutpoint extend projects\my-edit\clips --seconds 2            # or re-export an existing folder
+```
+
+## Vertical (9:16) output
+
+```powershell
+cutpoint clips my-edit --vertical --max-total 60      # projects\my-edit\clips_vertical, 1080x1920
+cutpoint assemble projects\my-edit\clips_vertical --captions   # projects\my-edit\final_vertical.mp4
+```
+
+`--vertical` is a fixed centre crop with no subject tracking. For 360 footage the renderer
+frames the shot itself (see [360 video](360.md)).
+
+## Importing into DaVinci Resolve (Free)
+
+Resolve Free has no Python API, so the hand-off is through files.
+
+1. Open your project and choose File > Import > Timeline (Ctrl+Shift+I).
+2. Pick `final.fcpxml`. `final.otio` also works.
+3. Leave "Automatically import source clips into media pool" checked and click OK.
+
+The timeline places the clips back to back in filename order at their frame rate. It uses hard
+cuts even if the MP4 was built with `--transition fade`, so you can add transitions in Resolve.
+Audio fades are baked into the clip files. If you move the clips folder, relink the media in
+Resolve or run `assemble` again.
+
+## Reading slow or network sources once
+
+Copy sources to a local disk first with `cutpoint stage`; see
+[slow storage](../troubleshooting/storage.md).