# sub-batch
Match and rename subtitles to videos and perform other batch operations on subtitles.
## Install
### Precompiled binaries (Linux and Windows)
https://github.com/kl/sub-batch/releases
### Nix package (credit to: https://github.com/erictapen)
https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/video/sub-batch/default.nix
### Cargo
```cargo install sub-batch```
## Usage
To see all subcommands and options, run ``sub-batch help``.
### Problem: I want to rename subtitle files to match their corresponding video file
---
Use the ```sub-batch rename``` command to match and rename subtitles to videos.
It works by scanning the subtitle and video file names for numbers, and renaming the subtitle to the
video file that contains the same number. For example, if we have the following files in a directory:
```
NameOfSeries_E01.srt
NameOfSeries_E02.srt
NameOfSeries_E03.srt
1_NameOfSeries.mkv
2_NameOfSeries.mkv
3_NameOfSeries.mkv
```
run ``sub-batch rename``:
```
> sub-batch rename
NameOfSeries_E01.srt -> 1_NameOfSeries.mkv
NameOfSeries_E02.srt -> 2_NameOfSeries.mkv
NameOfSeries_E03.srt -> 3_NameOfSeries.mkv
```
### Renaming when numbers are in different positions
Running ``sub-batch rename`` on the following files will fail.
```
1337_NameOfSeries_E01.srt
1337_NameOfSeries_E02.srt
1337_NameOfSeries_E03.srt
1_NameOfSeries.mkv
2_NameOfSeries.mkv
3_NameOfSeries.mkv
```
This is because the first number in each sub (1337) is not present in the video files, so no match can be made.
The easiest way to solve this is to pass the ``--rev`` flag:
```
> sub-batch rename --rev
1337_NameOfSeries_E01.srt -> 1_NameOfSeries.mkv
1337_NameOfSeries_E02.srt -> 2_NameOfSeries.mkv
1337_NameOfSeries_E03.srt -> 3_NameOfSeries.mkv
```
by default, ``sub-batch`` looks for the first number form left-to-right in the file name,
but ``--rev`` changes the scan direction to right-to-left.
You can also use the ``--rs`` (reverse sub) and ``--rv`` (reverse video) flags to only change
the direction of sub or video files.
When the episode number isn't the first or last number in the file name, you can define a
subsection of the file name and ``sub-batch`` will only look for numbers in this area.
This is done with the ``--subarea`` and ``--videoarea`` options, which take a regular expression that defines
the area to scan for numbers in. For example, if you have the following files:
```
1sub_file_08_xx2.srt
video8.mp4
```
run:
```
> sub-batch rename --subarea "file.*"
1sub_file_08_xx2.srt -> video8.mp4
```
Note that the regex does not have to match
a number, it just defines the sub area in the file
name where the number scan starts at.
### Problem: I want to change subtitle timings
---
To change the subtitle timings __for all subtitles in the directory__ use the `time` subcommand, for example:
```
sub-batch time 100
```
which moves all timings forward by 100 ms, or:
```
sub-batch time -50
```
which moves all timings back by 50 ms.
### Adjusting subtitle timings with `alass`
alass (https://github.com/kaegi/alass) can automatically adjust timings of a subtitle file and fix things such as gaps for commercial breaks
given the video file of the subtitle. To run `alass-cli` on all subtitle/video matches in parallel, run:
```
sub-batch alass
```
Arguments to `alass-cli` can be given by putting them after the alass subcommand in quotes:
```
sub-batch alass "--split-penalty 10"
```
### Adjusting subtitle timings interactively with `mpv`
If mpv (https://mpv.io) is installed sub-batch can use `mpv` to adjust timings interactively and have the updated subtitles auto-refresh in mpv. To enter this mode run:
```
sub-batch time-mpv
```
and follow the on-screen instructions to adjust the timings.
Note that at least one matched (same name except for extension) video file/subtilte file pair must exist in the target directory.
``sub-batch`` will only use the first matched pair it finds when adjusting,
but the timing adjustment is applied to __all subtitle files in the directory__, same as ```sub-batch time``` command.
### Problem: I want to target only certain subtitle/video files
---
You can give a regular expression to filter the subs/videos that should be included when running any of the subcommands.
For example, to only change timings of subtitles with the ``.srt`` extension in the target directory, run:
```
sub-batch --filter-sub "\.srt" time -50
```
Any other subtile files in the target directory are ignored. Video files can be filtered the same way with the ```--filter-video``` option.
### Problem: I want to match more than one subtitle to a single video file using secondary extensions
---
Let's say we have the following files:
```
NameOfSeries_E01.srt
NameOfSeries_E01.jp.srt
NameOfSeries_E01.en.srt
1_NameOfSeries.mkv
```
Running ``sub-batch rename`` will match all three subtitle files:
```
> sub-batch rename
NameOfSeries_E01.en.srt -> 1_NameOfSeries.mkv
NameOfSeries_E01.jp.srt -> 1_NameOfSeries.mkv
NameOfSeries_E01.srt -> 1_NameOfSeries.mkv
```
and after renaming the secondary extensions are not deleted:
```
1_NameOfSeries.en.srt
1_NameOfSeries.jp.srt
1_NameOfSeries.mkv
1_NameOfSeries.srt
```
Secondary extensions are treated as part of the file extension only if the
following __two conditions are true__:
1. The secondary extension is no longer than 3 characters long.
2. The secondary extension doesn't contain a number.
The length check exists because mpv (by default) doesn't recognize secondary extensions longer than 3 characters,
and the number check exists because a number in the secondary extension could be used as the match number.
If any of the above conditions are false, the secondary extension is treated as part of the file stem
which means that the subtitle can only be uniquely matched to a single video.
You can change this default behavior with the ``--sec-always`` and ``--sec-never`` flags which can be
given to the ``rename`` and ``alass`` subcommands. ``--sec-always`` unconditionally enables secondary
extensions no matter how long or what characters they contain, while ```--sec-never``` disables handling of secondary
extensions completely.