98 lines
3.7 KiB
Markdown
98 lines
3.7 KiB
Markdown
# 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`.
|