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.
-
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
start (
datetime.timedelta
) – The time that the subtitle should start being shownend (
datetime.timedelta
) – The time that the subtitle should stop being shownproprietary (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.
-
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 blocksreindex (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 informationeol (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
-
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
- 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
- Returns
The sorted subtitles
- Return type
-
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
- 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