SRT (Subtitle Parsing)

Warnings

• gotcha When reading SRT content from a file, ensure correct file encoding (e.g., UTF-8, latin-1). While the library is Unicode compliant, `srt.parse()` expects a Python string, so incorrect file reading can lead to `UnicodeDecodeError` or garbled text if not handled at the file reading stage.
  Fix: Specify the `encoding` when opening the file, e.g., `with open('file.srt', 'r', encoding='utf-8') as f: srt_data = f.read()`.
• breaking The `srt.parse()` function will raise an `srt.SRTParseError` if it encounters malformed SRT data and `ignore_errors` is `False` (which is the default behavior).
  Fix: Handle `SRTParseError` with a `try...except` block, or set `ignore_errors=True` in `srt.parse()` to skip invalid blocks and continue parsing, though this might result in incomplete subtitle data. For example: `subs = list(srt.parse(srt_content, ignore_errors=True))`.
• gotcha By default, `srt.compose()` operates in `strict=True` mode, which disallows blank lines within a subtitle's content. Including blank lines in strict mode violates the SRT standard and can lead to issues with media players.
  Fix: Avoid blank lines in subtitle content when composing SRTs. If you absolutely need to compose an SRT with blank lines (not recommended), you can set `strict=False`: `srt.compose(subtitles, strict=False)`.
• gotcha The `srt.sort_and_reindex()` function has an `in_place` parameter. If `in_place=True`, it modifies the input list of subtitles directly rather than returning a new sorted list. This can lead to unexpected side effects if you expect the original list to remain unchanged.
  Fix: If you want a new, sorted, and reindexed list without modifying the original, ensure you pass a copy or explicitly handle the return value. For example, `new_sorted_subs = srt.sort_and_reindex(list(original_subs))` if `in_place` is True, or simply `new_sorted_subs = srt.sort_and_reindex(original_subs, in_place=False)` if the function supports `in_place=False` (which it does not directly, but the default behavior is to create a new list if `in_place` is not specified as True. Always check the function signature). Note: for `srt.sort_and_reindex`, the default behavior implicitly returns a new list if `in_place` is not explicitly set to `True` for older versions, for newer versions the parameter is `skip` and `in_place` is not present, so clarification on its usage is key in current documentation. Current `srt.sort_and_reindex` function takes `subtitles`, `start_index`, and `skip`. The function returns a new list without modifying the original, so `in_place` is not a concern for the current API. Rephrasing this warning for current version: The *returned* list from `srt.sort_and_reindex` should be used as it will contain the sorted and re-indexed subtitles. If you're appending this back to an existing list, be careful to replace or extend, not just append.

Install

• pip install srt Install stable version

Imports

• srt

  import srt

• parse

  srt.parse(...)

  The parse function is directly accessible via `srt.parse` after importing the module, not as a separate named import.
• compose

  srt.compose(...)

• Subtitle

  from srt import Subtitle

  While `srt.Subtitle` is available, it's more idiomatic to import `Subtitle` directly for object creation.

Quickstart

This quickstart demonstrates how to parse an SRT string into a list of `Subtitle` objects, access and modify their properties, and then compose them back into an SRT formatted string. It also shows how to create a new `Subtitle` object and use `srt.sort_and_reindex`.

import srt

srt_content = '''\
1
00:01:00,000 --> 00:01:03,000
Hello, world!

2
00:01:04,000 --> 00:01:07,000
This is a test subtitle.
'''

# Parse an SRT string into Subtitle objects
subtitle_generator = srt.parse(srt_content)
subtitles = list(subtitle_generator)

print(f"Parsed {len(subtitles)} subtitles.")
for sub in subtitles:
    print(f"Index: {sub.index}, Start: {sub.start}, End: {sub.end}, Content: {sub.content}")

# Modify a subtitle
if subtitles:
    subtitles[0].content = "Modified content!"
    subtitles[0].start.seconds = 5

# Compose Subtitle objects back into an SRT string
composed_srt = srt.compose(subtitles)
print("\n--- Composed SRT ---")
print(composed_srt)

# Example of creating a new subtitle
new_sub = srt.Subtitle(index=3, start=srt.timedelta(seconds=10), end=srt.timedelta(seconds=12), content='A brand new subtitle.')
subtitles.append(new_sub)
composed_with_new = srt.compose(srt.sort_and_reindex(subtitles))
print("\n--- Composed with new and reindexed ---")
print(composed_with_new)