Rename -Scene parameter to -Level in Create-Scenes.ps1, add -Scenes parameter for automatic level search to detect exact scene count with binary search algorithm, update documentation across Create-Scenes.md, SKILL.md, README.md and index.md to explain search behavior and exit code 1 on failure, fix agent skills directory paths to use Windows environment variables and add VS Code location

video-processing-scripts/Create-Scenes.md

@@ -7,10 +7,11 @@ The clips are saved next to the source video, named from the source filename and
 ## Parameters
 
 - **`-Video`** (required): Path to the input video file. Can be absolute or relative to current directory. If the file does not exist, the script tries appending `.mp4`, `.webm` and `.mkv` in turn, so `P01` resolves to `P01.mp4` when that file exists.
-- **`-Scene`** (optional): Scene-change threshold between `0` and `1.0`. Lower values are more sensitive and produce more scenes. Default: `0.3`.
+- **`-Level`** (optional): Scene-change threshold between `0` and `1.0`, rounded to 2 decimals. Lower values are more sensitive and produce more scenes. Default: `0.3`.
+- **`-Scenes`** (optional): Target number of scenes, a positive integer. The level is searched automatically, starting from `-Level`, until exactly this many scenes are detected. Every attempt is displayed. If the number cannot be reached, the script stops with exit code `1` before any file is deleted or created. See [Automatic Level Search](#automatic-level-search).
 - **`-Suffix`** (optional): Suffix for the clip filenames. Must contain one printf-style number placeholder, which is replaced by the scene number starting at 1. Default: `-Scene-%02d`. See [Suffix Placeholders](#suffix-placeholders).
 - **`-List`** (optional): Only displays the scene list. No clip is created and no existing file is deleted.
-- **Extra parameters**: Any parameter accepted by `Create-Clip.ps1` and `Clone-Video.ps1` (e.g. `-Size`, `-FPS`, `-NoAudio`, `-Audio`, `-CRF`, `-Metadata`, `-Reverse`, `-LTX`) is forwarded to every clip. The parameters `-Video`, `-Frames`, `-Suffix` and `-Target` are managed by this script and must not be repeated.
+- **Extra parameters**: Any parameter accepted by `Create-Clip.ps1` and `Clone-Video.ps1` (e.g. `-Size`, `-FPS`, `-NoAudio`, `-Audio`, `-CRF`, `-Metadata`, `-Reverse`, `-LTX`) is forwarded to every clip. The parameters `-Video`, `-Frames`, `-Suffix`, `-Target`, `-Level` and `-Scenes` are managed by this script and must not be repeated. `-Level` and `-Scenes` are never forwarded to `Create-Clip.ps1`.
 
 Refer to [Clone-Video.ps1](Clone-Video.md) for a full description of the encoding parameters.
 
@@ -21,7 +22,7 @@ Refer to [Clone-Video.ps1](Clone-Video.md) for a full description of the encodin
 
 ## How It Works
 
-1. **Detection**: ffmpeg runs the `scene` score filter with the `-Scene` threshold and reports the timestamp of each detected change.
+1. **Detection**: ffmpeg runs the `scene` score filter with the `-Level` threshold and reports the timestamp of each detected change.
 2. **Frame conversion**: each timestamp becomes a 0-based frame index using the video's frame rate and start time. Indices at or before frame 0, or at or after the last frame, are ignored.
 3. **Scene list**: scene 1 starts at frame 0, and each detected change starts a new scene. Each scene ends one frame before the next change, and the last scene ends at the last frame. With no detected change, the whole video is one scene.
 4. **Scene list display**: the list is always printed, including with `-List`, `-WhatIf` and `-Confirm`.
@@ -40,15 +41,37 @@ Index StartFrame EndFrame Frames StartTime EndTime TotalTime Suffix
 
 `StartTime` and `EndTime` are in seconds, computed as frame index divided by frame rate. `EndTime` is the time of the last frame of the scene, so it is one frame before the next scene starts. `TotalTime` is the scene's duration in seconds: `Frames` divided by frame rate.
 
+After the list, the script prints `Scene level used: <level>`, the threshold that produced the list.
+
 ## Scene Threshold
 
-`-Scene` is passed to ffmpeg's `scene` score. The score measures how much a frame differs from the previous one, from `0` to `1`:
+`-Level` is passed to ffmpeg's `scene` score. The score measures how much a frame differs from the previous one, from `0` to `1`:
 
 - `0.3` (default): a reasonable starting point for ordinary footage.
 - Lower values (e.g. `0.1`) detect gradual changes, such as slow camera moves, and produce more scenes.
 - Higher values (e.g. `0.6`) only detect hard cuts.
 - `1.0`: detects nothing, so the whole video becomes one scene.
 
+## Automatic Level Search
+
+With `-Scenes`, the script searches for a level that gives exactly the requested number of scenes:
+
+1. It starts at `-Level` (rounded to 2 decimals) with a step of `0.1`.
+2. It detects the scenes and displays them, printed as `Pass N: level X -> M scene(s)` followed by the list.
+3. If the count matches `-Scenes`, the search stops.
+4. Too few scenes: the level moves down. Too many scenes: the level moves up. When the direction changes, the step is halved. Each new level is rounded to 2 decimals; the step is not rounded.
+5. The search stops with exit code `1` when the step falls below `0.01`, or when the level would leave the range `0` to `1.0`. Nothing is deleted or created in that case.
+
+There is no limit on the number of passes. Each pass runs a full detection on the video, so long videos take longer. A count can be unreachable for a video: raising the level can skip a scene and jump past the target, so the search fails with exit code `1`.
+
+The level used for the final list is shown on the last line, `Scene level used: <level>`.
+
+**List exactly 4 scenes, starting at level 0.3:**
+
+```powershell
+.\Create-Scenes.ps1 -Video P01.mp4 -Scenes 4 -List
+```
+
 ## Suffix Placeholders
 
 The first printf-style placeholder in `-Suffix` is replaced by the scene number. The number is zero-padded to the width given in the placeholder:
@@ -77,14 +100,14 @@ Matching is case-insensitive. Files that do not match are never touched. Existin
 | `P01.mp4` | `P01-Scene-01.mp4`, `P01-Scene-12.mp4` | `P01-Scene-01.skip.mp4`, `P01-Other.mp4` |
 | `P01.skip.mp4` | `P01-Scene-01.skip.mp4` | `P01-Scene-01.mp4` |
 
-Because the deletion happens before the first clip is created, a second run with a higher `-Scene` value removes the extra clips from the first run.
+Because the deletion happens before the first clip is created, a second run with a higher `-Level` value removes the extra clips from the first run.
 
 ## Examples
 
 **List the scenes without creating anything:**
 
 ```powershell
-.\Create-Scenes.ps1 -Video P01.mp4 -Scene 0.4 -List
+.\Create-Scenes.ps1 -Video P01.mp4 -Level 0.4 -List
 ```
 
 **Create one clip per scene:**
@@ -97,7 +120,7 @@ Because the deletion happens before the first clip is created, a second run with
 **Scale and remove audio from every clip:**
 
 ```powershell
-.\Create-Scenes.ps1 -Video P01 -Scene 0.3 -Size 720p -NoAudio
+.\Create-Scenes.ps1 -Video P01 -Level 0.3 -Size 720p -NoAudio
 ```
 
 **Custom suffix:**
@@ -136,5 +159,5 @@ This script supports `-WhatIf` and `-Confirm`. Both apply to the deletion of old
 - Frame indices are computed as `timestamp * frame rate`. This is exact for constant-frame-rate videos. With variable frame rate, a scene boundary can be off by one frame.
 - Clips are encoded by `Clone-Video.ps1`, so each clip keeps the source's resolution, frame rate and audio unless extra parameters change them.
 - Clips are written next to the source video, not to the current directory.
-- Scene detection is based on visual change only. A cut between two very similar shots may not be detected, and a fast camera move may be detected as a cut. Adjust `-Scene` to suit the footage.
+- Scene detection is based on visual change only. A cut between two very similar shots may not be detected, and a fast camera move may be detected as a cut. Adjust `-Level` to suit the footage, or use `-Scenes` to search for a level that gives a chosen number of scenes.
 - Each clip is created with `Create-Clip.ps1`, so a failed clip is reported as a warning and the other scenes are still created. At the end, the script reports how many scenes failed.