API documentation

A tiny library for parsing, modifying, and composing SRT files.

exception srt.SRTParseError(expected_start, actual_start, unmatched_content)

Raised when part of an SRT block could not be parsed.

Parameters:

  • expected_start (int) – The expected contiguous start index

  • actual_start (int) – The actual non-contiguous start index

  • unmatched_content (str) – The content between the expected start index and the actual start index

class srt.Subtitle(index, start, end, content, proprietary='')

The metadata relating to a single subtitle. Subtitles are sorted by start time by default. If no index was provided, index 0 will be used on writing an SRT block.

Parameters:

  • index (int or None) – The SRT index for this subtitle

  • start (datetime.timedelta) – The time that the subtitle should start being shown

  • end (datetime.timedelta) – The time that the subtitle should stop being shown

  • proprietary (str) – Proprietary metadata for this subtitle

  • content (str) – The subtitle content. Should not contain OS-specific line separators, only \n. This is taken care of already if you use srt.parse() to generate Subtitle objects.

to_srt(strict=True, eol='\n')

Convert the current Subtitle to an SRT block.

Parameters:

  • strict (bool) – If disabled, will allow blank lines in the content of the SRT block, which is a violation of the SRT standard and may cause your media player to explode

  • eol (str) – The end of line string to use (default “\n”)

Returns:

The metadata of the current Subtitle object as an SRT formatted subtitle block

Return type:

str

exception srt.TimestampParseError

Raised when an SRT timestamp could not be parsed.

srt.compose(subtitles, reindex=True, start_index=1, strict=True, eol=None, in_place=False)

Convert an iterator of Subtitle objects to a string of joined SRT blocks.

>>> from datetime import timedelta
>>> start = timedelta(seconds=1)
>>> end = timedelta(seconds=2)
>>> subs = [
...     Subtitle(index=1, start=start, end=end, content='x'),
...     Subtitle(index=2, start=start, end=end, content='y'),
... ]
>>> compose(subs)  
'1\n00:00:01,000 --> 00:00:02,000\nx\n\n2\n00:00:01,000 --> ...'
Parameters:

  • subtitles (iterator of Subtitle objects) – The subtitles to convert to SRT blocks

  • reindex (bool) – Whether to reindex subtitles based on start time

  • start_index (int) – If reindexing, the index to start reindexing from

  • strict (bool) – Whether to enable strict mode, see Subtitle.to_srt() for more information

  • eol (str) – The end of line string to use (default “\n”)

  • in_place (bool) – Whether to reindex subs in-place for performance (version <=1.0.0 behaviour)

Returns:

A single SRT formatted string, with each input Subtitle represented as an SRT block

Return type:

str

srt.make_legal_content(content)

Remove illegal content from a content block. Illegal content includes:

  • Blank lines

  • Starting or ending with a blank line

>>> make_legal_content('\nfoo\n\nbar\n')
'foo\nbar'
Parameters:

content (str) – The content to make legal

Returns:

The legalised content

Return type:

srt

srt.parse(srt, ignore_errors=False)

Convert an SRT formatted string (in Python 2, a unicode object) to a generator of Subtitle objects.

This function works around bugs present in many SRT files, most notably that it is designed to not bork when presented with a blank line as part of a subtitle’s content.

>>> subs = parse("""\
... 422
... 00:31:39,931 --> 00:31:41,931
... Using mainly spoons,
...
... 423
... 00:31:41,933 --> 00:31:43,435
... we dig a tunnel under the city and release it into the wild.
...
... """)
>>> list(subs)  
[Subtitle(...index=422...), Subtitle(...index=423...)]
Parameters:

  • srt (str or a file-like object) – Subtitles in SRT format

  • ignore_errors – If True, garbled SRT data will be ignored, and we’ll continue trying to parse the rest of the file, instead of raising SRTParseError and stopping execution.

Returns:

The subtitles contained in the SRT file as Subtitle objects

Return type:

generator of Subtitle objects

Raises:

SRTParseError – If the matches are not contiguous and ignore_errors is False.

srt.sort_and_reindex(subtitles, start_index=1, in_place=False, skip=True)

Reorder subtitles to be sorted by start time order, and rewrite the indexes to be in that same order. This ensures that the SRT file will play in an expected fashion after, for example, times were changed in some subtitles and they may need to be resorted.

If skip=True, subtitles will also be skipped if they are considered not to be useful. Currently, the conditions to be considered “not useful” are as follows:

  • Content is empty, or only whitespace

  • The start time is negative

  • The start time is equal to or later than the end time

>>> from datetime import timedelta
>>> one = timedelta(seconds=1)
>>> two = timedelta(seconds=2)
>>> three = timedelta(seconds=3)
>>> subs = [
...     Subtitle(index=999, start=one, end=two, content='1'),
...     Subtitle(index=0, start=two, end=three, content='2'),
... ]
>>> list(sort_and_reindex(subs))  
[Subtitle(...index=1...), Subtitle(...index=2...)]
Parameters:

  • subtitles – Subtitle objects in any order

  • start_index (int) – The index to start from

  • in_place (bool) – Whether to modify subs in-place for performance (version <=1.0.0 behaviour)

  • skip (bool) – Whether to skip subtitles considered not useful (see above for rules)

Returns:

The sorted subtitles

Return type:

generator of Subtitle objects

srt.srt_timestamp_to_timedelta(timestamp)

Convert an SRT timestamp to a timedelta.

>>> srt_timestamp_to_timedelta('01:23:04,000')
datetime.timedelta(seconds=4984)
Parameters:

timestamp (str) – A timestamp in SRT format

Returns:

The timestamp as a timedelta

Return type:

datetime.timedelta

Raises:

TimestampParseError – If the timestamp is not parseable

srt.timedelta_to_srt_timestamp(timedelta_timestamp)

Convert a timedelta to an SRT timestamp.

>>> import datetime
>>> delta = datetime.timedelta(hours=1, minutes=23, seconds=4)
>>> timedelta_to_srt_timestamp(delta)
'01:23:04,000'
Parameters:

timedelta_timestamp (datetime.timedelta) – A datetime to convert to an SRT timestamp

Returns:

The timestamp in SRT format

Return type:

str