116 lines
3.9 KiB
Markdown
116 lines
3.9 KiB
Markdown
# Get-Frame.ps1
|
||
|
||
Extracts a specific frame of a video file to a PNG image by calling [Get-LastFrame.ps1](Get-LastFrame.md) with an automatically derived output filename. The image path is generated from the `-Video` filename by appending a dash and the resolved frame index zero-padded to at least four digits — for example, `P01.mp4` at frame 10 becomes `P01-0010.png` saved alongside the source video.
|
||
|
||
## Parameters
|
||
|
||
- **`-Video`** (required): Path to the input video file. Can be absolute or relative to current directory.
|
||
- **`-Frame`** (required): 0-based frame index to extract.
|
||
- Positive values: Direct frame index (e.g., `0` = first frame, `100` = frame 100)
|
||
- Negative values: Count from the end (e.g., `-1` = last frame, `-2` = second-to-last)
|
||
- Values are automatically clamped to the valid range (0 to total frames − 1): a positive value past the last frame gives the last frame, and a negative value before the first frame gives frame 0
|
||
|
||
## Image Filename Derivation
|
||
|
||
The output filename is derived from the resolved (always positive) frame index:
|
||
|
||
| Video | `-Frame` | Total frames | Output image |
|
||
| --- | --- | --- | --- |
|
||
| `P01.mp4` | `10` | any | `P01-0010.png` |
|
||
| `P01.mp4` | `0` | any | `P01-0000.png` |
|
||
| `P01.mp4` | `-1` | 300 | `P01-0299.png` |
|
||
| `P01.mp4` | `-2` | 300 | `P01-0298.png` |
|
||
| `render/shot.mp4` | `42` | any | `render/shot-0042.png` |
|
||
| `C:\Videos\take01.mp4` | `100` | any | `C:\Videos\take01-0100.png` |
|
||
|
||
Negative indices are resolved to the actual frame index before building the filename, so the output always reflects the exact frame that was extracted.
|
||
|
||
## Output Name Digits
|
||
|
||
The frame index is padded with zeros to **at least** four digits. Frames `0` to `9999` give exactly four digits (`0010`). Larger numbers are written in full: frame `12345` gives `P01-12345.png`.
|
||
|
||
## Existing Files
|
||
|
||
An existing PNG with the same name is **replaced**. The image is written by [Get-LastFrame.ps1](Get-LastFrame.md), which overwrites its output.
|
||
|
||
## Command Wrapper
|
||
|
||
`Get-Frame.cmd` takes the video and the frame as **positional** arguments. It calls `Get-Frame.ps1` found on `PATH`, so the script folder must be on `PATH`. Arguments after the frame are passed to `Get-Frame.ps1` unchanged. Only `-WhatIf` and `-Confirm` are accepted there. Other options are rejected.
|
||
|
||
```cmd
|
||
Get-Frame.cmd "P01.mp4" 10
|
||
```
|
||
|
||
This is the same call as `.\Get-Frame.ps1 -Video P01.mp4 -Frame 10`.
|
||
|
||
## Limitations
|
||
|
||
- `-Image` is not a parameter of `Get-Frame.ps1`, so it cannot choose the output name. To use a custom name or a numbering pattern, call [Get-LastFrame.ps1](Get-LastFrame.md) with `-Image`:
|
||
|
||
```powershell
|
||
.\Get-LastFrame.ps1 -Video P01.mp4 -Frame 10 -Image "P01-%04d.png"
|
||
```
|
||
|
||
## Examples
|
||
|
||
**Extract a specific frame:**
|
||
|
||
```powershell
|
||
.\Get-Frame.ps1 -Video P01.mp4 -Frame 10
|
||
# Creates: P01-0010.png
|
||
```
|
||
|
||
**Extract the first frame:**
|
||
|
||
```powershell
|
||
.\Get-Frame.ps1 -Video P01.mp4 -Frame 0
|
||
# Creates: P01-0000.png
|
||
```
|
||
|
||
**Extract the last frame:**
|
||
|
||
```powershell
|
||
.\Get-Frame.ps1 -Video P01.mp4 -Frame -1
|
||
# If video has 300 frames, creates: P01-0299.png
|
||
```
|
||
|
||
**Extract the second-to-last frame:**
|
||
|
||
```powershell
|
||
.\Get-Frame.ps1 -Video P01.mp4 -Frame -2
|
||
# If video has 300 frames, creates: P01-0298.png
|
||
```
|
||
|
||
**Extract the 10th frame from the end:**
|
||
|
||
```powershell
|
||
.\Get-Frame.ps1 -Video P01.mp4 -Frame -10
|
||
# If video has 300 frames, creates: P01-0290.png
|
||
```
|
||
|
||
**Using absolute paths:**
|
||
|
||
```powershell
|
||
.\Get-Frame.ps1 -Video "C:\Videos\P01.mp4" -Frame 50
|
||
# Creates: C:\Videos\P01-0050.png
|
||
```
|
||
|
||
## Safe Execution
|
||
|
||
This script supports `-WhatIf` and `-Confirm` for safe execution (forwarded to `Get-LastFrame.ps1`):
|
||
|
||
- **`-WhatIf`**: Simulate the operation without extracting the frame. Shows what would be done.
|
||
- **`-Confirm`**: Prompt for confirmation before extracting the frame.
|
||
|
||
**Simulate without extracting:**
|
||
|
||
```powershell
|
||
.\Get-Frame.ps1 -Video P01.mp4 -Frame 10 -WhatIf
|
||
```
|
||
|
||
**Prompt before extraction:**
|
||
|
||
```powershell
|
||
.\Get-Frame.ps1 -Video P01.mp4 -Frame 10 -Confirm
|
||
```
|