{"id":5421,"library":"pysrt","title":"SubRip Subtitle Parser and Writer","description":"pysrt is a Python library for parsing, modifying, and composing SubRip (.srt) subtitle files. It allows developers to read SRT files, manipulate subtitle text and timing, and save changes. The current version is 1.1.2. The library appears to have a slow release cadence, with the last release being seven years ago and minimal recent development activity on its GitHub repository.","status":"maintenance","version":"1.1.2","language":"en","source_language":"en","source_url":"https://github.com/byroot/pysrt","tags":["subtitle","srt","parser","video"],"install":[{"cmd":"pip install pysrt","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"symbol":"pysrt","correct":"import pysrt"},{"note":"The primary way to open an SRT file is via `pysrt.open()`.","wrong":"import open_srt","symbol":"open","correct":"pysrt.open('file.srt')"}],"quickstart":{"code":"import pysrt\nimport os\n\n# Create a dummy SRT file for demonstration\ndummy_srt_content = '''1\n00:00:00,500 --> 00:00:02,500\nHello world!\n\n2\n00:00:03,000 --> 00:00:05,000\nThis is a test subtitle.'''\n\nfile_path = 'example.srt'\nwith open(file_path, 'w', encoding='utf-8') as f:\n    f.write(dummy_srt_content)\n\n# Parse the SRT file\ntry:\n    subs = pysrt.open(file_path)\n    print(f\"Loaded {len(subs)} subtitles.\")\n\n    # Access and modify a subtitle item\n    first_sub = subs[0]\n    print(f\"Original first subtitle: {first_sub.text}\")\n    first_sub.text = \"Modified first subtitle!\"\n    print(f\"Modified first subtitle: {first_sub.text}\")\n\n    # Shift all subtitles by 1 second forward\n    subs.shift(seconds=1)\n    print(f\"First subtitle start time after shift: {first_sub.start}\")\n\n    # Save the modified subtitles to a new file\n    output_file_path = 'example_modified.srt'\n    subs.save(output_file_path, encoding='utf-8')\n    print(f\"Modified subtitles saved to {output_file_path}\")\n\n    # Clean up dummy files\n    os.remove(file_path)\n    os.remove(output_file_path)\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to open an SRT file, access and modify individual subtitle items, shift the timings of all subtitles, and save the changes to a new file. It includes a basic example of creating a dummy SRT file and then cleaning it up."},"warnings":[{"fix":"Specify the `encoding` parameter in `pysrt.open()` to match the SRT file's encoding.","message":"Encountering `UnicodeDecodeError` is common when opening SRT files due to varying encodings. If you face this, try specifying the encoding explicitly, for example, `pysrt.open('file.srt', encoding='iso-8859-1')` or `encoding='utf-8'` if known.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For new projects or if encountering unaddressed issues, consider evaluating alternative, more actively maintained subtitle parsing libraries like the `srt` library (pypi-slug: `srt`), which is reported to be faster and more robust.","message":"The `pysrt` library appears to be minimally maintained, with the last release seven years ago and limited recent activity on its GitHub repository. This may lead to unaddressed bugs or compatibility issues with newer Python versions or complex SRT formats.","severity":"gotcha","affected_versions":"1.1.2"},{"fix":"Review GitHub issues for potential workarounds or be cautious when performing complex time shifts. Thoroughly test any operations involving `shift` and `to_time()`.","message":"There is an open issue on the GitHub repository related to problems with the `shift` method and `to_time()` functionality, which could affect precise time manipulations.","severity":"gotcha","affected_versions":"1.1.2"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}