# Get-FramesRange.ps1

Extracts a specific range of frames from a video file to PNG images.

## Parameters

- **`-Video`** (required): Path to input video file
- **`-Images`** (optional): Path to output PNG images file pattern. Can be absolute or relative to current directory. If not provided, the output files will be in subdirectory 'Frames' and named as the video file with a frame number suffix padded with zeros to 4 digits.
- **`-Frames`** (required): Frame range specification (see formats below)

## Frame Range Formats

- **`start-end`**: Extract frames from start to end index (e.g., `100-200`). Both ends must lie inside the video, and `start` must not be greater than `end`. Otherwise the script stops with exit code `1`.
- **`positive_number`**: Extract frames from 0 to that number (e.g., `50` extracts frames 0-50). A single number past the last frame is clamped to the last frame (`150` on a 100-frame video gives frames 0 to 99).
- **`-negative_number`**: Extract the last N frames (e.g., `-10` extracts frames 90 to 99 of a 100-frame video; `-1` extracts the last frame only)
- **`%`**: The last frame index. Alone (`%`) it extracts only the last frame. In a range it is the end of the range:
    - `%` - Extract only the last frame
    - `10-%` - Extract from frame 10 to the last frame
- `-%` is not supported and is rejected with exit code `1`
- **`all`**: Extract all frames (same as `0-%`)

## Examples

**Extract specific range:**

```powershell
.\Get-FramesRange.ps1 -Video video.mp4 -Frames "100-200"
# Creates: Frames/video_0100.png, Frames/video_0101.png, ..., Frames/video_0200.png
```

**Extract first 50 frames:**

```powershell
.\Get-FramesRange.ps1 -Video video.mp4 -Frames "50"
# Creates: Frames/video_0000.png through Frames/video_0050.png
```

**Extract last 10 frames:**

```powershell
.\Get-FramesRange.ps1 -Video video.mp4 -Frames "-10"
# If video has 500 frames, creates: Frames/video_0490.png through Frames/video_0499.png
```

**Extract only the last frame:**

```powershell
.\Get-FramesRange.ps1 -Video video.mp4 -Frames "%"
# If video has 500 frames, creates: Frames/video_0499.png
```

**Extract from frame 10 to the last frame:**

```powershell
.\Get-FramesRange.ps1 -Video video.mp4 -Frames "10-%"
# If video has 500 frames, creates: Frames/video_0010.png through Frames/video_0499.png
```

**Extract all frames:**

```powershell
.\Get-FramesRange.ps1 -Video video.mp4 -Frames "all"
# If video has 500 frames, creates: Frames/video_0000.png through Frames/video_0499.png
```

**Custom output pattern:**

```powershell
.\Get-FramesRange.ps1 -Video video.mp4 -Frames "0-100" -Images "output_frame"
# Creates: output_frame_0000.png through output_frame_0100.png
```

**Full output path:**

```powershell
.\Get-FramesRange.ps1 -Video video.mp4 -Frames "50-150" -Images "C:\Output\frame_%04d.png"
```

**Note:** Frame numbers in output filenames reflect the actual video frame index (0-based).

## Existing Files

An existing PNG with the same name is **replaced**. Use `-WhatIf` to check the output names first.

## Safe Execution

This script supports `-WhatIf` and `-Confirm` for safe execution:

- **`-WhatIf`**: Simulate the operation without actually extracting frames. Shows which frames would be extracted.
- **`-Confirm`**: Prompt for confirmation before extracting each frame.

**Simulate without extracting:**

```powershell
.\Get-FramesRange.ps1 -Video video.mp4 -Frames "100-200" -WhatIf
```

**Prompt before each frame:**

```powershell
.\Get-FramesRange.ps1 -Video video.mp4 -Frames "0-10" -Confirm
```