Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

A tiny library for parsing, modifying, and composing SRT files.

Project description

Tests LGTM Coverage Dependencies

srt is a tiny but featureful Python library for parsing, modifying, and composing SRT files. Take a look at the quickstart for a basic overview of the library. Detailed API documentation is also available.

Want to see some examples of its use? Take a look at the tools shipped with the library. This library is also used internally by projects like subsync, bw_plex, and many more.

Why choose this library?

  • Can parse many broken SRT files which other SRT libraries cannot, and fix them
  • Extremely lightweight, ~150 lines of code excluding docstrings
  • Simple, intuitive API
  • High quality test suite using Hypothesis
  • 100% test coverage (including branches)
  • Well documented API, at both a high and low level
  • ~30% faster than pysrt on typical workloads
  • Full support for PyPy
  • No dependencies outside of the standard library
  • Tolerant of many common errors found in real-world SRT files
  • Support for Asian-style SRT formats (ie. “fullwidth” SRT format)
  • Completely Unicode compliant
  • Released under a highly permissive license (MIT)
  • Real world tested — used in production to process thousands of SRT files every day
  • Portable — runs on Linux, OSX, and Windows
  • Tools included — contains lightweight tools to perform generic tasks with the library



There are a number of tools shipped with the library to manipulate, process, and fix SRT files. Here’s an example using hanzidentifier to strip out non-Chinese lines:

$ cat
00:00:33,843 --> 00:00:38,097
Only 3% of the water on our planet is fresh.

00:00:40,641 --> 00:00:44,687
Yet, these precious waters are rich with surprise.

$ srt lines-matching -m hanzidentifier -f hanzidentifier.has_chinese -i
00:00:33,843 --> 00:00:38,097

00:00:40,641 --> 00:00:44,687

These tools are easy to chain together, for example, say you have one subtitle with Chinese and English, and other with French, but you want Chinese and French only. Oh, and the Chinese one is 5 seconds later than it should be. That’s easy enough to sort out:

$ srt lines-matching -m hanzidentifier -f hanzidentifier.has_chinese -i |
>     srt fixed-timeshift --seconds -5 |
>     srt mux --input - --input

See the srt_tools/ directory for more information.


Detailed API documentation is available, but here are the basics:

>>> # list() is needed as srt.parse creates a generator
>>> subs = list(srt.parse('''\
... 1
... 00:00:33,843 --> 00:00:38,097
... 地球上只有3%的水是淡水
... 2
... 00:00:40,641 --> 00:00:44,687
... 可是这些珍贵的淡水中却充满了惊奇
... 3
... 00:00:57,908 --> 00:01:03,414
... 所有陆地生命归根结底都依赖於淡水
... '''))
>>> subs
[Subtitle(index=1, start=datetime.timedelta(0, 33, 843000), end=datetime.timedelta(0, 38, 97000), content='地球上只有3%的水是淡水', proprietary=''),
 Subtitle(index=2, start=datetime.timedelta(0, 40, 641000), end=datetime.timedelta(0, 44, 687000), content='可是这些珍贵的淡水中却充满了惊奇', proprietary=''),
 Subtitle(index=3, start=datetime.timedelta(0, 57, 908000), end=datetime.timedelta(0, 63, 414000), content='所有陆地生命归根结底都依赖於淡水', proprietary='')]
>>> print(srt.compose(subs))
00:00:33,843 --> 00:00:38,097

00:00:40,641 --> 00:00:44,687

00:00:57,908 --> 00:01:03,414


To install the latest stable version from PyPi:

pip install -U srt

To install the latest development version directly from GitHub:

pip install -U git+



Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for srt, version 3.4.1
Filename, size File type Python version Upload date Hashes
Filename, size srt-3.4.1.tar.gz (23.7 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page