# 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`.