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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.