https://github.com/tkarabela/pysubs2

A Python library for editing subtitle files
https://github.com/tkarabela/pysubs2

closed-captions microdvd mpl2 openai-whisper python sami srt substation-alpha subtitles subtitles-parsing ttml webvtt

Last synced: 4 months ago
JSON representation

A Python library for editing subtitle files

• Host: GitHub
• URL: https://github.com/tkarabela/pysubs2
• Owner: tkarabela
• License: mit
• Created: 2014-08-06T00:01:40.000Z (almost 12 years ago)
• Default Branch: master
• Last Pushed: 2025-11-16T18:26:23.000Z (7 months ago)
• Last Synced: 2026-02-16T21:30:20.079Z (4 months ago)
• Topics: closed-captions, microdvd, mpl2, openai-whisper, python, sami, srt, substation-alpha, subtitles, subtitles-parsing, ttml, webvtt
• Language: Python
• Homepage: http://pysubs2.readthedocs.io
• Size: 2.61 MB
• Stars: 416
• Watchers: 11
• Forks: 50
• Open Issues: 19
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE.txt
  • Support: docs/supported-formats.rst

Awesome Lists containing this project

• awesome-video - pysubs2 - A Python library for editing subtitle files, supporting various formats including SubRip (SRT), SubStation Alpha (SSA), and Advanced SubStation Alpha (ASS). It allows for reading, writing, and modifying subtitle files, making it a versatile tool for developers working with subtitles in Python. (Media Tools / Independent & Hobbyist Projects)

README

          
pysubs2

=======

[![pysubs2 build master branch](https://img.shields.io/github/actions/workflow/status/tkarabela/pysubs2/main.yml?branch=master)](https://github.com/tkarabela/pysubs2/actions)

[![pysubs2 test code coverage](https://img.shields.io/codecov/c/github/tkarabela/pysubs2)](https://app.codecov.io/github/tkarabela/pysubs2)

[![Static Badge](https://img.shields.io/badge/MyPy%20%26%20Ruffle-checked-blue?style=flat)](https://github.com/tkarabela/pysubs2/actions)

[![PyPI - Version](https://img.shields.io/pypi/v/pysubs2.svg?style=flat)](https://pypi.org/project/pysubs2/)

[![PyPI - Status](https://img.shields.io/pypi/status/pysubs2.svg?style=flat)](https://pypi.org/project/pysubs2/)

[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pysubs2.svg?style=flat)](https://pypi.org/project/pysubs2/)

[![PyPI - License](https://img.shields.io/pypi/l/pysubs2.svg?style=flat)](LICENSE.txt)

[![GitHub Repo stars](https://img.shields.io/github/stars/tkarabela/pysubs2?style=flat&label=GitHub%20stars)](https://github.com/tkarabela/pysubs2)

pysubs2 is a Python library for editing subtitle files.

It’s based on *SubStation Alpha*, the native format of

[Aegisub](http://www.aegisub.org/); it also supports *SubRip (SRT)*,

*MicroDVD*, *MPL2*, *TMP*, *WebVTT*, *TTML* and *SAMI* formats and *OpenAI Whisper* captions.

There is a small CLI tool for batch conversion and retiming.

```bash

pip install pysubs2

pysubs2 --shift 0.3s *.srt

pysubs2 --to srt *.ass

```

```python

import pysubs2

subs = pysubs2.load("my_subtitles.ass", encoding="utf-8")

subs.shift(s=2.5)

for line in subs:

    line.text = "{\\be1}" + line.text

subs.save("my_subtitles_edited.ass")

```

To learn more, please [see the documentation](http://pysubs2.readthedocs.io).

If you'd like to contribute, see [CONTRIBUTING.md](CONTRIBUTING.md).

pysubs2 is licensed under the MIT license (see [LICENSE.txt](LICENSE.txt)).