Document Get-VideoSubtitles.ps1 in README.md, index.md and SKILL.md, describing subtitle extraction and -List behavior, supported text and Blu-ray PGS formats, unsupported DVD and DVB bitmap tracks, and replacement of same-named output files in the current directory

video-processing-scripts/Get-VideoSubtitles.md

@@ -0,0 +1,97 @@
+# Get-VideoSubtitles.ps1
+
+Extracts the embedded subtitle tracks of a video file into the current directory, or lists them with `-List`.
+
+## Parameters
+
+- **`-Video`** (required): Path to input video file (absolute or relative)
+- **`-List`**: List the subtitle tracks (index, codec and output name) instead of extracting them. Creates no files
+
+## Supported Formats
+
+ffmpeg can copy text subtitles out of a container, and can copy Blu-ray bitmap subtitles to a `.sup` file. It cannot write DVD or DVB bitmap subtitles as a standalone file, and it cannot turn bitmaps into text without OCR.
+
+| Container | Subtitle codec | Output | Notes |
+| --- | --- | --- | --- |
+| MKV | SubRip (`subrip`) | `.srt` | |
+| MKV, WebM | WebVTT (`webvtt`) | `.srt` | Converted to SubRip |
+| MP4, MOV, M4V | mov_text (`mov_text`) | `.srt` | Converted to SubRip |
+| MKV | ASS / SSA (`ass`) | `.ass` | Copied unchanged, styling is kept |
+| MKV, M2TS, TS | Blu-ray PGS (`hdmv_pgs_subtitle`) | `.sup` | Copied unchanged. Bitmap, not text |
+| MKV, VOB | DVD (`dvd_subtitle`) | not extracted | Listed as not supported |
+| TS | DVB (`dvb_subtitle`) | not extracted | Listed as not supported |
+| AVI | none | not extracted | AVI has no standard subtitle track |
+
+Any other subtitle codec is listed as not supported and skipped with a warning.
+
+## Output Names
+
+Each extracted file is saved in the current directory, not next to the video. The name is built from the video name and the track language:
+
+- `<video>.<language>.<extension>`, for example `movie.en.srt` for an English track
+- The language is the 2-letter ISO 639-1 code when one exists (`eng` becomes `en`, `fra` becomes `fr`). Otherwise it is the 3-letter code from the file (for example `fre`), or `und` when the track has no language tag
+- When two tracks produce the same name, the second and later ones get a counter: `movie.en.2.srt`, `movie.en.3.srt`
+
+## Examples
+
+**List the subtitle tracks without creating files:**
+
+```powershell
+.\Get-VideoSubtitles.ps1 -Video video.mkv -List
+```
+
+**Extract all subtitle tracks to the current directory:**
+
+```powershell
+.\Get-VideoSubtitles.ps1 -Video video.mkv
+# Creates video.en.srt, video.fr.ass, ... in the current directory
+```
+
+**Using absolute paths:**
+
+```powershell
+.\Get-VideoSubtitles.ps1 -Video "C:\Videos\movie.mkv"
+```
+
+**Using relative paths:**
+
+```powershell
+.\Get-VideoSubtitles.ps1 -Video ..\videos\clip.mp4
+```
+
+## Behavior
+
+- If the video has no subtitle stream, the script displays a message and exits successfully. It creates no file
+- Each track is copied with ffmpeg in its own pass. Text tracks are written as SubRip (`.srt`), ASS tracks as `.ass`, and PGS tracks as `.sup`
+- Unsupported tracks produce a warning and the other tracks are still extracted
+- The video file itself is never changed
+
+## Existing Files
+
+- An existing file with the same name in the current directory is **replaced** without a prompt. ffmpeg runs with `-y`, so the old file is lost. Use `-WhatIf` first, or run from a different folder
+- If ffmpeg fails, or an expected output file is not created, the script stops with an error
+- `-List` creates and replaces nothing
+
+## Safe Execution
+
+This script supports `-WhatIf` and `-Confirm` for safe execution:
+
+- **`-WhatIf`**: Simulate the operation without creating files. Shows which files would be written.
+- **`-Confirm`**: Prompt for confirmation before each subtitle file is written.
+
+**Simulate without making changes:**
+
+```powershell
+.\Get-VideoSubtitles.ps1 -Video video.mkv -WhatIf
+```
+
+**Prompt before each file is written:**
+
+```powershell
+.\Get-VideoSubtitles.ps1 -Video video.mkv -Confirm
+```
+
+## Notes
+
+- Requires `ffmpeg` and `ffprobe` to be installed and available in the system PATH.
+- Language codes come from the file's language tags. Tracks without a tag are named with `und`.