---
name: "pysubs2"
section: "1"
platform: "linux"
package: "pysubs2"
version: "1.8.0-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/pysubs2"
---

# pysubs2(1)

command-line tool to convert and retime subtitle files

## NAME

pysubs2 - command-line tool to convert and retime subtitle files

## DESCRIPTION

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\] \[--enc-error-handling {strict,surrogateescape}\] \[--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 ...\]

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.

### options:

- **-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.

- **--enc-error-handling** {strict,surrogateescape}

  Character encoding error handling for input and output. Defaults to 'surrogateescape' which passes through unrecognized characters to output unchanged. Use 'strict' if you want the command to fail when encountering a character incompatible with selected input/output encoding.

- **--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

## SEE ALSO

The full documentation for **pysubs2** is maintained as a Texinfo manual.  If the **info** and **pysubs2** programs are properly installed at your site, the command

-

  **info pysubs2**

should give you access to the complete manual.