Subby

Advanced subtitle converter and processor.

Supported formats

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

Functionality

• 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

Installation

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

Usage notes

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.

Language specific fixing

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.

Command line usage

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 

Library usage

Converter

fromsubbyimportWebVTTConverterfrompathlibimportPathconverter=WebVTTConverter()
file=Path('test.vtt')
# All statements below are equivalentsrt=converter.from_file(file)
srt=converter.from_string(file.read_text())
# srt is subby.SubRipFileoutput=Path('file.srt')
srt.save(output)
# saved to file.srt

Processor

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

fromsubbyimportCommonIssuesFixerfrompathlibimportPathprocessor=CommonIssuesFixer()
file=Path('test.vtt')
# All statements below are equivalentsrt, status=processor.from_file(file)
srt, status=processor.from_string(file.read_text())
# srt is subby.SubRipFile, status is booloutput=Path('test_fixed.srt')
srt.save(output)
# saved to test_fixed.srt

Chaining

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

fromsubbyimportWebVTTConverter, CommonIssuesFixer, SDHStripperfrompathlibimportPathconverter=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.srtstripped, status=stripper.from_srt(srt)
ifstatusisTrue:
print('stripping successful')
stripped.save(file_stripped)
# saved to file_stripped.srt

Tests

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