Aeidon Subtitle Library

1.16 verified Fri Apr 17 auth: no python

Aeidon is a library designed for reading, writing, and manipulating text-based subtitle files (e.g., SRT, ASS, SUB). It is primarily developed as a core component for the Gaupol subtitle editor. The current version is 1.16, and releases occur infrequently, typically 1-3 times per year, focusing on Python compatibility and bug fixes.

pip install aeidon

Common errors

error ModuleNotFoundError: No module named 'distutils.version' ↓

cause This error occurs on Python 3.12+ because the `distutils` package was removed from the standard library. Older versions of Aeidon (pre-1.14) did not correctly handle this change.

fix

Upgrade Aeidon to version 1.14 or newer: pip install --upgrade aeidon.

error SyntaxError: invalid syntax (on old Python versions) ↓

cause Aeidon 1.15 and later require Python 3.5 or newer. Running it on older Python versions (e.g., 3.4) will result in syntax errors due to modern Python features.

fix

Upgrade your Python environment to version 3.5 or higher. A virtual environment is recommended for managing different Python versions.

error ModuleNotFoundError: No module named 'charset_normalizer' ↓

cause Since Aeidon 1.15, the `chardet` dependency was replaced with `charset-normalizer`. If `charset-normalizer` is not installed, Aeidon will fail to import or run.

fix

Ensure charset-normalizer is installed: pip install aeidon (which should pull it in automatically) or explicitly pip install charset-normalizer.

error ImportError: cannot import name 'load_module' from 'importlib' (or similar errors related to locale.getdefaultlocale) ↓

cause This issue points to an older Aeidon version (<1.16) being run on a future Python version (e.g., 3.15+) where certain deprecated functions (like `importlib.load_module` or `locale.getdefaultlocale`) have been removed.

fix

Upgrade Aeidon to version 1.16 or newer: pip install --upgrade aeidon.

Warnings

breaking Aeidon dropped support for Python versions older than 3.5 starting with version 1.15. Attempting to install or run Aeidon 1.15+ on Python < 3.5 will result in installation errors or runtime `SyntaxError`. ↓

fix Upgrade your Python environment to 3.5 or newer. The latest stable Python is recommended for best compatibility.

gotcha On Python 3.12 and newer, `distutils` was removed from the standard library. Aeidon (versions < 1.14) may fail to install or run due to missing `distutils` modules. Version 1.14 fixed this by leveraging `setuptools` to provide `distutils` compatibility. ↓

fix Upgrade Aeidon to version 1.14 or newer (`pip install --upgrade aeidon`). Ensure `setuptools` is installed and up-to-date (`pip install --upgrade setuptools`).

deprecated Aeidon versions older than 1.16 may encounter deprecation warnings or runtime issues on future Python versions (e.g., Python 3.15+) due to its use of `locale.getdefaultlocale` and `importlib.load_module`, which are being removed. While Aeidon 1.16 addresses these, using older versions with cutting-edge Python may lead to errors. ↓

fix Upgrade Aeidon to version 1.16 or newer (`pip install --upgrade aeidon`) to ensure forward compatibility with upcoming Python releases.

gotcha Version 1.15 removed the dependency on `chardet` and introduced `charset-normalizer`. While this is an internal change, if you had custom environments relying on `chardet` for some reason (e.g., indirect dependency resolution), this change might affect your setup or cause `ModuleNotFoundError` if `charset-normalizer` is not installed. ↓

fix Ensure `charset-normalizer` is installed in your environment. It should be automatically installed by `pip` when installing Aeidon 1.15+.

Imports

File
```
from aeidon.files import File
```
SrtFormat
```
from aeidon.formats import SrtFormat
```
Other formats like `SubFormat`, `AssFormat` are also available in `aeidon.formats`.
Cue
```
from aeidon.cues import Cue
```
Time
```
from aeidon.cues import Time
```
Line
```
from aeidon.cues import Line
```

Quickstart

This quickstart demonstrates how to load SRT subtitle content from a string, manipulate cues (add, shift times), and then save the modified content back to a string using Aeidon's `File` and `SrtFormat` classes.

import io
from aeidon.files import File
from aeidon.formats import SrtFormat
from aeidon.cues import Cue, Time, Line

# Simulate an existing SRT file content
srt_content = """
1
00:00:01,000 --> 00:00:03,000
Hello World!

2
00:00:04,500 --> 00:00:06,500
This is a test.
"""

# Create an Aeidon File object
subtitle_file = File()

# Load subtitle content from a string (can be a file path too)
sio_input = io.StringIO(srt_content)
SrtFormat.read(sio_input, subtitle_file)

print("--- Original Cues ---")
for cue in subtitle_file.cues:
    print(f"  {cue.start_time} --> {cue.end_time}: {[line.text for line in cue.lines]}")

# Add a new cue
new_cue = Cue()
new_cue.start_time = Time(milliseconds=8000)
new_cue.end_time = Time(milliseconds=10000)
new_cue.lines.append(Line("A new cue added by Aeidon!"))
subtitle_file.cues.append(new_cue)

# Shift all cues by 2 seconds forward
for cue in subtitle_file.cues:
    cue.start_time = cue.start_time.shift_milliseconds(2000)
    cue.end_time = cue.end_time.shift_milliseconds(2000)

print("\n--- Modified Cues (shifted and new cue) ---")
for cue in subtitle_file.cues:
    print(f"  {cue.start_time} --> {cue.end_time}: {[line.text for line in cue.lines]}")

# Save the modified subtitle content to a string
sio_output = io.StringIO()
SrtFormat.write(sio_output, subtitle_file)

print("\n--- Saved SRT Content ---")
print(sio_output.getvalue())

sio_input.close()
sio_output.close()