Metadata-Version: 2.4
Name: pysrtkit
Version: 0.1.0
Summary: A modern, API-compatible SubRip (.srt) subtitle parser and writer
Author-email: kurianbenoy <kurian.bkk@gmail.com>
Maintainer-email: kurianbenoy <kurian.bkk@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/kurianbenoy/pysrtkit
Project-URL: Repository, https://github.com/kurianbenoy/pysrtkit
Project-URL: Issues, https://github.com/kurianbenoy/pysrtkit/issues
Project-URL: Changelog, https://github.com/kurianbenoy/pysrtkit/blob/main/CHANGELOG.md
Keywords: srt,subrip,subtitles,captions,pysrt
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: chardet>=3.0.2
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# pysrtkit

A modern, API-compatible SubRip (`.srt`) subtitle parser and writer for Python.
It is a drop-in replacement for [pysrt](https://github.com/byroot/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

```sh
pip install pysrtkit
```

From a checkout:

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

## Quick start

```python
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

```python
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

```python
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

```python
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:

```python
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

```python
# 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:

```python
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

```python
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:

```sh
# 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:

```python
- 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

```sh
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:

```sh
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](LICENSE).

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