# Create-Clip.ps1

Creates a clipped video file by calling [Clone-Video.ps1](Clone-Video.md) with an automatically derived output filename. The `-Target` path is generated from the `-Video` filename by inserting the `-Suffix` value (default `-Clip`) before the file extension — for example, `P01.mp4` becomes `P01-Clip.mp4` saved alongside the source. Both `-Video` and `-Frames` are required; any additional parameters are forwarded directly to `Clone-Video.ps1`.

Sources carrying a `.skip` marker keep that marker last: `P01.skip.mp4` becomes `P01-Clip.skip.mp4`, so the clip remains excluded from the scripts that ignore `.skip` files.

## Parameters

- **`-Video`** (required): Path to the input video file. Can be absolute or relative to current directory. Accepted containers: `.mp4`, `.webm`, `.mkv`. If the path has no extension the script tries `.mp4`, `.webm`, then `.mkv` in turn and uses the first match to determine the target filename extension.
- **`-Frames`** (required): 0-based frame range to clip. Supported formats:
    - `start-end`: Clip frames from `start` to `end` (e.g., `"100-200"`)
    - `positive_number`: Clip frames from 0 to that number (e.g., `"50"`)
    - `-N`: Clip last N frames (e.g., `"-10"`)
    - `%`: Represents the last frame index; can be used alone or in ranges (e.g., `"%"`, `"10-%"`, `"-%"`)
    - `all`: Clip all frames (same as `"0-%"`)
- **`-Suffix`** (optional): Text inserted into the derived target name before the file extension. Defaults to `-Clip`, so `P01.mp4` becomes `P01-Clip.mp4`. Include any separator you want, such as the leading `-`. Must not be empty, because an empty suffix would produce a target with the same name as the source. For example, `-Suffix "-Clip-Shot-1"` turns `P01.mp4` into `P01-Clip-Shot-1.mp4`.
- **Extra parameters**: Any additional parameters accepted by `Clone-Video.ps1` (e.g. `-Size`, `-FPS`, `-NoAudio`, `-Audio`, `-CRF`, `-Metadata`, `-Reverse`, `-LTX`) are forwarded directly. The parameters `-Video`, `-Frames`, `-Suffix` and `-Target` are handled by this script and must not be repeated.

Refer to [Clone-Video.ps1](Clone-Video.md) for a full description of all supported parameters.

## Target Filename Derivation

The output filename is derived automatically from the resolved source path:

| Source | Target |
| --- | --- |
| `P01.mp4` | `P01-Clip.mp4` |
| `render/shot.webm` | `render/shot-Clip.webm` |
| `C:\Videos\take01.mkv` | `C:\Videos\take01-Clip.mkv` |
| `P01` (no extension, resolves to `P01.mp4`) | `P01-Clip.mp4` |
| `P01.skip.mp4` | `P01-Clip.skip.mp4` |
| `P04.skip.webm` | `P04-Clip.skip.webm` |
| `P01.skip` (no extension, resolves to `P01.skip.mp4`) | `P01-Clip.skip.mp4` |
| `P01.mp4` with `-Suffix "-Shot-1"` | `P01-Shot-1.mp4` |
| `P01.mp4` with `-Suffix "-Clip-Shot-1"` | `P01-Clip-Shot-1.mp4` |
| `P01.skip.mp4` with `-Suffix "-Clip-Shot-1"` | `P01-Clip-Shot-1.skip.mp4` |

### `.skip` sources

Several scripts in this collection ignore files whose name ends with `.skip.<ext>` (for example [Crop-Clips.ps1](Crop-Clips.md)). Inserting `-Clip` before the extension would produce `P01.skip-Clip.mp4`, which loses that meaning, so the marker is kept immediately before the container extension instead:

| Source | Target | |
| --- | --- | --- |
| `P01.skip.mp4` | `P01-Clip.skip.mp4` | correct — still a `.skip` file |
| `P01.skip.mp4` | `P01.skip-Clip.mp4` | not used — marker no longer last |

This applies to every accepted container (`.mp4`, `.webm`, `.mkv`), matching is case-insensitive, and the marker's original casing is preserved (`P03.SKIP.mkv` → `P03-Clip.SKIP.mkv`).

## Examples

**Clip a specific frame range:**

```powershell
.\Create-Clip.ps1 -Video P01.mp4 -Frames "100-200"
# Creates: P01-Clip.mp4 (frames 100 to 200)
```

**Clip from frame 0 to frame 50:**

```powershell
.\Create-Clip.ps1 -Video P01.mp4 -Frames "50"
# Creates: P01-Clip.mp4 (frames 0 to 50)
```

**Clip last 10 frames:**

```powershell
.\Create-Clip.ps1 -Video P01.mp4 -Frames "-10"
# Creates: P01-Clip.mp4 (last 10 frames)
```

**Clip from frame 10 to last frame:**

```powershell
.\Create-Clip.ps1 -Video P01.mp4 -Frames "10-%"
# Creates: P01-Clip.mp4 (frames 10 to end)
```

**Clip with resized output:**

```powershell
.\Create-Clip.ps1 -Video P01.mp4 -Frames "100-200" -Size 720p
# Creates: P01-Clip.mp4 (frames 100-200 scaled to 720p)
```

**Clip without audio:**

```powershell
.\Create-Clip.ps1 -Video P01.mp4 -Frames "100-200" -NoAudio
```

**Clip with alternate audio:**

```powershell
.\Create-Clip.ps1 -Video P01.mp4 -Frames "50-150" -Audio music.mp3
```

**Clip with custom CRF:**

```powershell
.\Create-Clip.ps1 -Video P01.mp4 -Frames "100-500" -CRF 18
# Uses CRF 18 instead of default CRF 8 or source bitrate
```

**Clip a reversed segment:**

```powershell
.\Create-Clip.ps1 -Video P01.mp4 -Frames "100-200" -Reverse
# Creates: P01-Clip.mp4 playing frames 200 down to 100
```

**Clip using the closest LTX-2 720p bucket:**

```powershell
.\Create-Clip.ps1 -Video P01.mp4 -Frames "100-200" -Size 720p -LTX
```

**Source without extension:**

```powershell
.\Create-Clip.ps1 -Video P01 -Frames "100-200"
# Resolves P01 -> P01.mp4 (or .webm / .mkv, whichever exists first)
# Creates: P01-Clip.mp4
```

**Replace the default `-Clip` suffix:**

```powershell
.\Create-Clip.ps1 -Video P01.mp4 -Frames "100-200" -Suffix "-Clip-Shot-1"
# Creates: P01-Clip-Shot-1.mp4 (frames 100 to 200)
```

**Using absolute paths:**

```powershell
.\Create-Clip.ps1 -Video "C:\Videos\P01.mp4" -Frames "100-200"
# Creates: C:\Videos\P01-Clip.mp4
```

**Clip a `.skip` source:**

```powershell
.\Create-Clip.ps1 -Video P01.skip.mp4 -Frames "100-200"
# Creates: P01-Clip.skip.mp4 (the .skip marker stays before the extension)
```

**Clip a `.skip` source with extra parameters:**

```powershell
.\Create-Clip.ps1 -Video P01.skip.mp4 -Frames "5-10" -Size 480p
# Creates: P01-Clip.skip.mp4 scaled to 480p
```

## Safe Execution

This script supports `-WhatIf` and `-Confirm` for safe execution (forwarded to `Clone-Video.ps1`):

- **`-WhatIf`**: Simulate the operation without creating files. Shows what `Clone-Video.ps1` would do.
- **`-Confirm`**: Prompt for confirmation before each state-changing operation.

**Simulate without making changes:**

```powershell
.\Create-Clip.ps1 -Video P01.mp4 -Frames "100-200" -WhatIf
```

**Prompt before creating files:**

```powershell
.\Create-Clip.ps1 -Video P01.mp4 -Frames "100-200" -Confirm
```