{"id":4777,"library":"srt","title":"SRT (Subtitle Parsing)","description":"SRT is a tiny, yet featureful Python library designed for robust parsing, modification, and composition of SRT subtitle files. It can handle many broken SRT files and has no dependencies beyond the Python Standard Library. The current version is 3.5.3, with an active, though not rapid, release cadence.","status":"active","version":"3.5.3","language":"en","source_language":"en","source_url":"https://github.com/cdown/srt","tags":["subtitle","srt","video","parsing","text-processing","media"],"install":[{"cmd":"pip install srt","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"srt","correct":"import srt"},{"note":"The parse function is directly accessible via `srt.parse` after importing the module, not as a separate named import.","wrong":"from srt import srt_parse","symbol":"parse","correct":"srt.parse(...)"},{"symbol":"compose","correct":"srt.compose(...)"},{"note":"While `srt.Subtitle` is available, it's more idiomatic to import `Subtitle` directly for object creation.","wrong":"srt.Subtitle()","symbol":"Subtitle","correct":"from srt import Subtitle"}],"quickstart":{"code":"import srt\n\nsrt_content = '''\\\n1\n00:01:00,000 --> 00:01:03,000\nHello, world!\n\n2\n00:01:04,000 --> 00:01:07,000\nThis is a test subtitle.\n'''\n\n# Parse an SRT string into Subtitle objects\nsubtitle_generator = srt.parse(srt_content)\nsubtitles = list(subtitle_generator)\n\nprint(f\"Parsed {len(subtitles)} subtitles.\")\nfor sub in subtitles:\n    print(f\"Index: {sub.index}, Start: {sub.start}, End: {sub.end}, Content: {sub.content}\")\n\n# Modify a subtitle\nif subtitles:\n    subtitles[0].content = \"Modified content!\"\n    subtitles[0].start.seconds = 5\n\n# Compose Subtitle objects back into an SRT string\ncomposed_srt = srt.compose(subtitles)\nprint(\"\\n--- Composed SRT ---\")\nprint(composed_srt)\n\n# Example of creating a new subtitle\nnew_sub = srt.Subtitle(index=3, start=srt.timedelta(seconds=10), end=srt.timedelta(seconds=12), content='A brand new subtitle.')\nsubtitles.append(new_sub)\ncomposed_with_new = srt.compose(srt.sort_and_reindex(subtitles))\nprint(\"\\n--- Composed with new and reindexed ---\")\nprint(composed_with_new)","lang":"python","description":"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`."},"warnings":[{"fix":"Specify the `encoding` when opening the file, e.g., `with open('file.srt', 'r', encoding='utf-8') as f: srt_data = f.read()`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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))`.","message":"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).","severity":"breaking","affected_versions":"All versions"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}