Advanced subtitle converter and processor.

WebVTT, DFXP/TTML/TTML2/SMPTE, SAMI, WVTT (WebVTT in MP4), STPP/ISMT (DFXP in MP4), JSON (Bilibili)

• converts supported input format to SRT
• retains select formatting tags (italics, basic \an8 positioning)
• corrects often found flaws in subtitles
• opinionated timing and formatting improvements

git clone https://github.com/vevv/subby
cd subby
pip install .

CommonIssuesFixer should be ran both after conversion and SDH stripping as it's designed to fix source issues, including ones which can cause playback problems.

CommonIssuesFixer removes short gaps (2 frames) by default. This can be disabled by setting CommonIssuesFixer.remove_gaps to False before running.

subby.SubRipFile accepts similar methods to pysrt.SubRipFile, but isn't a fully compatible replacement. Only from_string, clean_indexes, export, save are guaranteed to work.

This object is otherwise just a list storing srt.Subtitle elements.

As of 0.3.6, both CommonIssuesFixer and SDHStripper support a language parameter, which accepts a BCP47 language code.

This is currently used only in CommonIssuesFixer, to enable correct alignment of text in right-to-left languages, and to enable unicode normalization on English subtitles only.

It is highly recommended for every script to pass it for future use.

Usage: subby [OPTIONS] COMMAND [ARGS]...

  Subby—Advanced Subtitle Converter and Processor.

Options:
  -d, --debug  Enable DEBUG level logs.
  --help       Show this message and exit.

Commands:
  convert  Convert a Subtitle to SubRip (SRT).
  process  SubRip (SRT) post-processing.
  version  Print version information.

Example

subby process /path/to/subs/subs.srt strip-sdh 

from subby import WebVTTConverter
from pathlib import Path

converter = WebVTTConverter()
file = Path('test.vtt')

# All statements below are equivalent
srt = converter.from_file(file)
srt = converter.from_string(file.read_text())
srt = converter.from_bytes(file.read_bytes())

# srt is subby.SubRipFile

output = Path('file.srt')
srt.save(output)
# saved to file.srt

Processor returns a bool indicating success - whether any changes were made, useful for determining if SDH subtitles should be saved.

from subby import CommonIssuesFixer
from pathlib import Path

processor = CommonIssuesFixer()
file = Path('test.vtt')

# All statements below are equivalent
srt, status = processor.from_file(file)
srt, status = processor.from_string(file.read_text())
srt, status = processor.from_bytes(file.read_bytes())

# srt is subby.SubRipFile, status is bool

output = Path('test_fixed.srt')
srt.save(output)
# saved to test_fixed.srt

The following example will convert a VTT file, attempt to strip SDH, and then save the result.

from subby import WebVTTConverter, CommonIssuesFixer, SDHStripper
from pathlib import Path

converter = WebVTTConverter()
fixer = CommonIssuesFixer()
stripper = SDHStripper()

file = Path('file.vtt')
file_sdh = Path('file_sdh.srt')
file_stripped = Path('file_stripped.srt')
srt, _ = fixer.from_srt(converter.from_file(file))

srt.save(file_sdh)
# saved to file_sdh.srt

stripped, status = stripper.from_srt(srt)
if status is True:
    print('stripping successful')
    stripped.save(file_stripped)
    # saved to file_stripped.srt

To run tests, go to the "tests" directory and run pytest.