Using pysubs2 from the Command Line
Do you want to convert subtitle files from one format to another, or do simple retiming?
You can use pysubs2 CLI, which is accessible through the pysubs2
command installed
along with the library. Alternatively, the CLI can also be invoked by executing the pysubs2 module:
python -m pysubs2
.
See pysubs2 --help
for usage. Here are some examples:
pysubs2 --to srt *.ass
pysubs2 --to srt --clean *.ass
pysubs2 --to microdvd --fps 23.976 *.ass
pysubs2 --shift 0.3s *.srt
pysubs2 --shift 0.3s <my_file.srt >retimed_file.srt
pysubs2 --shift-back 0.3s --output-dir retimed *.srt
pysubs2 --transform-framerate 25 23.976 *.srt
For formats other than SubStation, comment and drawing lines will be skipped. If you’d like a bit more
aggressive skipping, try the --clean
option, which will also try to skip karaoke and duplicated lines.
To handle SRT files with mixed HTML <tags>
and SubStation {\tags}
, you can use these options:
--srt-keep-html-tags --srt-keep-ssa-tags
.
Warning
By default, the script works in-place; original files are overwritten. You can use the -o/--output-dir
option to specify output directory or process files in UNIX pipe fashion (pysubs2 <infile >outfile
).
CLI parameters
usage: pysubs2 [-h] [-v] [-f {srt,ass,ssa,microdvd,json,mpl2,tmp,vtt}] [-t {srt,ass,ssa,microdvd,json,mpl2,tmp,vtt}] [--input-enc ENCODING] [--output-enc ENCODING] [--fps FPS] [-o DIR] [--clean] [--verbose]
[--shift TIME | --shift-back TIME | --transform-framerate FPS1 FPS2] [--srt-keep-unknown-html-tags] [--srt-keep-html-tags] [--srt-keep-ssa-tags] [--sub-no-write-fps-declaration]
[FILE [FILE ...]]
The pysubs2 CLI for processing subtitle files.
https://github.com/tkarabela/pysubs2
positional arguments:
FILE Input subtitle files. Can be in SubStation Alpha (*.ass, *.ssa), SubRip (*.srt), MicroDVD (*.sub) or other supported format. When no files are specified, pysubs2 will work as a pipe, reading from
standard input and writing to standard output.
optional arguments:
-h, --help show this help message and exit
-v, --version show program's version number and exit
-f {srt,ass,ssa,microdvd,json,mpl2,tmp,vtt}, --from {srt,ass,ssa,microdvd,json,mpl2,tmp,vtt}
By default, subtitle format is detected from the file. This option can be used to skip autodetection and force specific format. Generally, it should never be needed.
-t {srt,ass,ssa,microdvd,json,mpl2,tmp,vtt}, --to {srt,ass,ssa,microdvd,json,mpl2,tmp,vtt}
Convert subtitle files to given format. By default, each file is saved in its original format.
--input-enc ENCODING Character encoding for input files. By default, UTF-8 is used for both input and output.
--output-enc ENCODING
Character encoding for output files. By default, it is the same as input encoding. If you wish to convert between encodings, make sure --input-enc is set correctly! Otherwise, your output files will
probably be corrupted. It's a good idea to back up your files or use the -o option.
--fps FPS This argument specifies framerate for MicroDVD files. By default, framerate is detected from the file. Use this when framerate specification is missing or to force different framerate.
-o DIR, --output-dir DIR
Use this to save all files to given directory. By default, every file is saved to its parent directory, ie. unless it's being saved in different subtitle format (and thus with different file
extension), it overwrites the original file.
--clean Attempt to remove non-essential subtitles (eg. karaoke, SSA drawing tags), strip styling information when saving to non-SSA formats
--verbose Print misc logging
--shift TIME Delay all subtitles by given time amount. Time is specified like this: '1m30s', '0.5s', ...
--shift-back TIME The opposite of --shift (subtitles will appear sooner).
--transform-framerate FPS1 FPS2
Multiply all timestamps by FPS1/FPS2 ratio.
optional arguments (SRT):
--srt-keep-unknown-html-tags
(input) do not strip unrecognized HTML tags
--srt-keep-html-tags (input) do not convert HTML tags to SubStation internally, this implies --srt-keep-unknown-html-tags
--srt-keep-ssa-tags (output) do not convert/strip SubStation tags for output
optional arguments (MicroDVD):
--sub-no-write-fps-declaration
(output) omit writing FPS as first zero-length subtitle
usage examples:
python -m pysubs2 --to srt *.ass
python -m pysubs2 --to srt --clean *.ass
python -m pysubs2 --to microdvd --fps 23.976 *.ass
python -m pysubs2 --shift 0.3s *.srt
python -m pysubs2 --shift 0.3s <my_file.srt >retimed_file.srt
python -m pysubs2 --shift-back 0.3s --output-dir retimed *.srt
python -m pysubs2 --transform-framerate 25 23.976 *.srt