---
id: aeidon
version: "2.0"
license: GPL-3.0-or-later
license_treatment: copyleft
maintenance: active
---

# aeidon — Reading, writing and manipulating text-based subtitle files

License: copyleft · Maintenance: active · Downloads: 109.7K/mo

## What it is and what it does

aeidon is a Python library for working with text-based subtitle files. It provides a Project-based API for reading and writing subtitles in multiple formats, along with functions to manipulate subtitle timing and text content. The package is part of the Gaupol subtitle editor ecosystem and handles the core subtitle data operations that the editor's GUI layer builds upon.

The library abstracts away format-specific details, allowing you to load a subtitle file in one format, adjust timing or edit content, and save it in a different format. It requires Python 3.10 or later and depends only on charset-normalizer for character encoding handling, making it lightweight to integrate into subtitle processing workflows.

Use it for:

- Convert subtitle files between formats programmatically
- Batch-shift subtitle timings by a fixed offset across multiple files
- Build subtitle editing or validation tools on top of the library's data model
- Automate subtitle file processing in video production pipelines
- Parse and extract subtitle text and timing data for analysis

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

aeidon reads, writes, and manipulates text-based subtitle files in multiple formats, supporting operations like format conversion and timing adjustment.

Yes. aeidon is actively maintained with no known vulnerabilities and low install friction. The GPL-3.0-or-later license is a blocker only for proprietary closed-source use; for open-source or internal projects, it's a straightforward choice.

## Install

pip install aeidon
uv add aeidon
poetry add aeidon

## Installing aeidon

Before you install: Low install friction with a pure-Python wheel and single runtime dependency. Actively maintained with a recent release.

License in practice: GPL-3.0-or-later copyleft license requires derivative works to be licensed under compatible terms; not suitable for proprietary closed-source software.

Quickstart:

pip install aeidon

import aeidon
project = aeidon.Project()
project.open_main("/path/to/file.srt", "utf_8")
project.shift_positions(None, aeidon.as_seconds(-2))
project.save_main()

Requires Python 3.10 or later

Verify before relying:

- Which subtitle formats beyond SubRip and MicroDVD are supported by the library
- Performance characteristics when processing large subtitle files
- Whether the API documentation reflects current version 2.0 behavior

## Package facts

- License: GPL-3.0-or-later (copyleft)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 109.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

subtitle file conversion, read write subtitle formats, subtitle timing adjustment, subtitle manipulation library, subtitle parser, text subtitle processing, srt format conversion, subtitle-processing, format-conversion

[View on SkillFed](https://skillfed.io/packages/aeidon) · [View on PyPI](https://pypi.org/project/aeidon/)