pysrt

library1.1.2pypypi✓ verified 24d ago

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.

serialization data

pip install pysrt

github ↗package ↗

INSTALL

IMPORT

SIG · PYSRT

pysrt

serializationpythonv1.1.2

Install

2.6s avg

Import

12ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.1.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.012s · 20.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.6s · import 0.012s · 24MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

pysrt

✓ import pysrt

open

✓ pysrt.open('file.srt')

✗ import open_srt

The primary way to open an SRT file is via `pysrt.open()`.

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.

import pysrt import os # Create a dummy SRT file for demonstration dummy_srt_content = '''1 00:00:00,500 --> 00:00:02,500 Hello world! 2 00:00:03,000 --> 00:00:05,000 This is a test subtitle.''' file_path = 'example.srt' with open(file_path, 'w', encoding='utf-8') as f: f.write(dummy_srt_content) # Parse the SRT file try: subs = pysrt.open(file_path) print(f"Loaded {len(subs)} subtitles.") # Access and modify a subtitle item first_sub = subs[0] print(f"Original first subtitle: {first_sub.text}") first_sub.text = "Modified first subtitle!" print(f"Modified first subtitle: {first_sub.text}") # Shift all subtitles by 1 second forward subs.shift(seconds=1) print(f"First subtitle start time after shift: {first_sub.start}") # Save the modified subtitles to a new file output_file_path = 'example_modified.srt' subs.save(output_file_path, encoding='utf-8') print(f"Modified subtitles saved to {output_file_path}") # Clean up dummy files os.remove(file_path) os.remove(output_file_path) except Exception as e: print(f"An error occurred: {e}")

Debug

Known issues

gotchaEncountering `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.

fix

Specify the `encoding` parameter in `pysrt.open()` to match the SRT file's encoding.

affects: All versions

gotchaThe `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.

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.

affects: 1.1.2

gotchaThere 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.

fix

Review GitHub issues for potential workarounds or be cautious when performing complex time shifts. Thoroughly test any operations involving `shift` and `to_time()`.

affects: 1.1.2

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pysrt'

The 'pysrt' package is not installed in the current Python environment or the environment's PYTHONPATH is incorrectly configured.

fix

pip install pysrt

UnicodeDecodeError: 'utf-8' codec can't decode byte 0xXX in position Y: invalid start byte

The SRT file is not encoded in UTF-8, but pysrt.open() defaults to UTF-8, causing a decoding error.

fix

subs = pysrt.open('filename.srt', encoding='latin-1') # Or 'cp1252', 'windows-1250', etc., depending on the file's actual encoding

AttributeError: 'SubRipFile' object has no attribute 'write'

The SubRipFile object does not have a 'write' method; subtitle files are saved using the 'save()' method.

fix

subs.save('output.srt', encoding='utf-8')

AttributeError: 'list' object has no attribute 'shift'

The 'shift' method is available on the SubRipFile object (which is a collection of subtitles), not directly on a standard Python list containing Subtitle objects.

fix

import pysrt

subs = pysrt.open('input.srt')
subs.shift(hours=1, minutes=5, seconds=0)

Upgrade

Version history

1.1.2latest on PyPI · released Jan 20, 2020

Audit

Dependencies

No dependency data recorded yet.

Agent activity

39 hits · last 30 days

node

Resources

githubhttps://github.com/byroot/pysrt ↗

packagehttps://pypi.org/project/pysrt/ ↗