{"id":9443,"library":"aeidon","title":"Aeidon Subtitle Library","description":"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.","status":"active","version":"1.16","language":"en","source_language":"en","source_url":"https://github.com/otsaloma/gaupol","tags":["subtitle","video","text processing","SRT","ASS","VTT"],"install":[{"cmd":"pip install aeidon","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Used for robust character encoding detection when reading subtitle files. Required since version 1.15.","package":"charset-normalizer","optional":false},{"reason":"Required on Python 3.12+ for `distutils` compatibility, which Aeidon uses internally. Included as an indirect dependency.","package":"setuptools","optional":false}],"imports":[{"symbol":"File","correct":"from aeidon.files import File"},{"note":"Other formats like `SubFormat`, `AssFormat` are also available in `aeidon.formats`.","symbol":"SrtFormat","correct":"from aeidon.formats import SrtFormat"},{"symbol":"Cue","correct":"from aeidon.cues import Cue"},{"symbol":"Time","correct":"from aeidon.cues import Time"},{"symbol":"Line","correct":"from aeidon.cues import Line"}],"quickstart":{"code":"import io\nfrom aeidon.files import File\nfrom aeidon.formats import SrtFormat\nfrom aeidon.cues import Cue, Time, Line\n\n# Simulate an existing SRT file content\nsrt_content = \"\"\"\n1\n00:00:01,000 --> 00:00:03,000\nHello World!\n\n2\n00:00:04,500 --> 00:00:06,500\nThis is a test.\n\"\"\"\n\n# Create an Aeidon File object\nsubtitle_file = File()\n\n# Load subtitle content from a string (can be a file path too)\nsio_input = io.StringIO(srt_content)\nSrtFormat.read(sio_input, subtitle_file)\n\nprint(\"--- Original Cues ---\")\nfor cue in subtitle_file.cues:\n    print(f\"  {cue.start_time} --> {cue.end_time}: {[line.text for line in cue.lines]}\")\n\n# Add a new cue\nnew_cue = Cue()\nnew_cue.start_time = Time(milliseconds=8000)\nnew_cue.end_time = Time(milliseconds=10000)\nnew_cue.lines.append(Line(\"A new cue added by Aeidon!\"))\nsubtitle_file.cues.append(new_cue)\n\n# Shift all cues by 2 seconds forward\nfor cue in subtitle_file.cues:\n    cue.start_time = cue.start_time.shift_milliseconds(2000)\n    cue.end_time = cue.end_time.shift_milliseconds(2000)\n\nprint(\"\\n--- Modified Cues (shifted and new cue) ---\")\nfor cue in subtitle_file.cues:\n    print(f\"  {cue.start_time} --> {cue.end_time}: {[line.text for line in cue.lines]}\")\n\n# Save the modified subtitle content to a string\nsio_output = io.StringIO()\nSrtFormat.write(sio_output, subtitle_file)\n\nprint(\"\\n--- Saved SRT Content ---\")\nprint(sio_output.getvalue())\n\nsio_input.close()\nsio_output.close()\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.5 or newer. The latest stable Python is recommended for best compatibility.","message":"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`.","severity":"breaking","affected_versions":">=1.15"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"<1.14 on Python >=3.12"},{"fix":"Upgrade Aeidon to version 1.16 or newer (`pip install --upgrade aeidon`) to ensure forward compatibility with upcoming Python releases.","message":"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.","severity":"deprecated","affected_versions":"<1.16 with Python >=3.15"},{"fix":"Ensure `charset-normalizer` is installed in your environment. It should be automatically installed by `pip` when installing Aeidon 1.15+.","message":"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.","severity":"gotcha","affected_versions":">=1.15"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Upgrade Aeidon to version 1.14 or newer: `pip install --upgrade aeidon`.","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.","error":"ModuleNotFoundError: No module named 'distutils.version'"},{"fix":"Upgrade your Python environment to version 3.5 or higher. A virtual environment is recommended for managing different 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.","error":"SyntaxError: invalid syntax (on old Python versions)"},{"fix":"Ensure `charset-normalizer` is installed: `pip install aeidon` (which should pull it in automatically) or explicitly `pip install 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.","error":"ModuleNotFoundError: No module named 'charset_normalizer'"},{"fix":"Upgrade Aeidon to version 1.16 or newer: `pip install --upgrade aeidon`.","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.","error":"ImportError: cannot import name 'load_module' from 'importlib' (or similar errors related to locale.getdefaultlocale)"}]}