Skip to main content

pysrtkit

A modern, API-compatible SubRip (.srt) subtitle parser and writer for Python. It is a drop-in replacement for pysrt 1.1.x: open, parse, edit, shift, slice and save subtitle files, or use the srt command line tool.

pysrtkit supports Python 3.11+ only (older versions no longer receive security fixes) and has one small dependency (chardet) for the CLI's encoding detection.

Installation

pip install pysrtkit

From a checkout:

git clone https://github.com/kurianbenoy/pysrtkit.git
cd pysrtkit
pip install -e ".[dev]"

Quick start

import pysrtkit as pysrt

subs = pysrt.open("movie.srt")

for sub in subs:
    print(sub.index, sub.start, sub.end, sub.text)

# Delay every subtitle by 2.5 seconds and save.
subs.shift(seconds=2, milliseconds=500)
subs.save("movie.shifted.srt")

Parsing and serializing strings

from pysrtkit import SubRipFile, SubRipItem

subs = SubRipFile.from_string("""
1
00:00:01,000 --> 00:00:02,500
Hello, world!

2
00:00:03,000 --> 00:00:04,000
<i>Second</i> line.
""")

print(subs[0].text)                 # Hello, world!
print(subs[0].duration)             # SubRipTime(0, 0, 1, 500)
print(str(subs[1]))                 # serialized item

Creating files

from pysrtkit import SubRipFile, SubRipItem, SubRipTime

subs = SubRipFile([
    SubRipItem(1, SubRipTime(0, 0, 1), SubRipTime(0, 0, 2, 500), "Hello!"),
    SubRipItem(2, "00:00:03,000", "00:00:04,000", "Goodbye!"),
])
subs.save("new.srt")

Working with times

from pysrtkit import SubRipTime

start = SubRipTime.from_string("00:01:02,500")
start.shift(seconds=2)              # 00:01:04,500
start *= 1.5                        # scale relative to zero
start.to_time()                     # datetime.time(0, 1, 36, 750000)

SubRipTime coerces strings, integers (milliseconds), datetime.time instances, dictionaries and four-item iterables, including in comparisons:

SubRipTime(0, 0, 1) == "00:00:01,000"      # True
SubRipTime(0, 0, 1) == {"seconds": 1}      # True
SubRipTime(0, 0, 1) < (0, 0, 2, 0)         # True

Slicing and querying

# Subtitles visible at 31 seconds.
visible = subs.at(seconds=31)

# Subtitles starting before 1:02:03.400 and ending after 1:00:00.
part = subs.slice(starts_before="01:02:03,400", ends_after="01:00:00,000")

# Reset numbering after destructive edits.
part.clean_indexes()

Error handling

Malformed blocks are ignored by default. Pass error_handling to log or raise:

import pysrtkit as pysrt

subs = pysrt.open("broken.srt", error_handling=pysrt.ERROR_RAISE)

The available modes are ERROR_PASS (default), ERROR_LOG and ERROR_RAISE.

Encoding and line endings

import pysrtkit as pysrt

subs = pysrt.open("movie.srt", encoding="windows-1252")
subs.save("movie-utf8.srt", encoding="utf-8", eol="\n")

Encoding is detected from UTF-8/16/32 byte-order marks and defaults to UTF-8. Windows-1252 and other legacy encodings must be passed explicitly. The line ending used by the source file is detected and reused when saving.

Command line

Installing pysrtkit provides srt (and pysrtkit) commands:

# Shift forward by 1 minute 12 seconds, in place (creates movie.srt.bak).
srt -i shift 1m12s movie.srt

# Shift backward by 1.5 seconds and write to stdout.
srt shift -1s500ms movie.srt > shifted.srt

# Convert from 23.9 fps to 25 fps.
srt -i rate 23.9 25 movie.srt

# Split into parts.
srt split 48m18s movie.srt

# Wrap lines longer than 42 characters.
srt break 42 movie.srt

python -m pysrtkit runs the same CLI. If the original pysrt is also installed, both packages provide an srt entry point; uninstall one or use python -m pysrtkit to avoid the conflict.

pysrt compatibility

pysrtkit implements the pysrt 1.1.x public API, including:

pysrt pysrtkit
pysrt.open, pysrt.stream, pysrt.from_string same
SubRipFile, SubRipItem, SubRipTime same
ERROR_PASS, ERROR_LOG, ERROR_RAISE same
Error, InvalidItem, InvalidIndex, InvalidTimeString same
srt CLI (shift, rate, split, break) same
pysrt.version.VERSION, VERSION_STRING same
subs.slice, .at, .shift, .clean_indexes, .text same

Swap the import to migrate:

- import pysrt
+ import pysrtkit as pysrt

The internal modules are also arranged like pysrt's: pysrtkit.srttime, pysrtkit.srtitem, pysrtkit.srtfile, pysrtkit.srtexc, pysrtkit.comparablemixin, pysrtkit.compat and pysrtkit.commands.

Development

python -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"
python -m pytest

Lint with ruff check ..

Release

Version numbers live in pysrtkit/version.py. To build and verify artifacts:

python -m build
python -m twine check dist/*

The Release GitHub workflow builds the sdist and wheel, attaches them to a GitHub release when a v* tag is pushed, and publishes to PyPI only when manually dispatched with publish_pypi enabled. PyPI publishing uses trusted publishing, so configure a trusted publisher for the release environment in the PyPI project settings first.

License

Apache-2.0. See LICENSE.

The public API and CLI are modeled on pysrt by Jean Boussier and contributors.

Metadata

Release files for pysrtkit 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pysrtkit 0.1.0
File Size Uploaded Provenance Actions
pysrtkit-0.1.0.tar.gz 27.3 kB Without provenance Details for pysrtkit-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pysrtkit 0.1.0
File Interpreter ABI Platform Actions
pysrtkit-0.1.0-py3-none-any.whl Python 3 none any Details for pysrtkit-0.1.0-py3-none-any.whl

Total release size: 47.6 kB

Release files / pysrtkit-0.1.0.tar.gz

Download URL pysrtkit-0.1.0.tar.gz
Size 27.3 kB
Tags Source
SHA-256 checksum
How to use checksums
42b8e50919a70c55102df3b896562c25b6bc80b1e5a0a6eed880e63894410eef
BLAKE2b-256 checksum
How to use checksums
3013cf8db65260d7798ff6064255ff465dbeb4ada0e7183e7a5f2563ce730b18
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / pysrtkit-0.1.0-py3-none-any.whl

Download URL pysrtkit-0.1.0-py3-none-any.whl
Size 20.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
54c268409a8693c29bcf774b175617d818d11ec02efc040784c18a943115b059
BLAKE2b-256 checksum
How to use checksums
0428469d797aa384b63932d3dfe322cc4226411bc7c6ec89a3592a1e3ea847ed
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for pysrtkit 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page