aeneas last shipped 1.7.3 in 2017, and Debian 64bit is the only supported platform
aeneas is a Python/C library and a set of tools to automagically synchronize audio and text (aka forced alignment)
At a glance
- What is it?
- aeneas is an AGPL Python and C library for forced alignment, computing which time interval in an audio file corresponds to each text fragment. Its newest release tag is v1.7.3 from 2017-03-16 while the last push is dated 2026-07-25, its only supported platform is Debian 64bit on Python 2.7 or 3.5, and an entire run is configured by one pipe-delimited string.
- Who is it for?
- aeneas is still the reference implementation to read if you are building an EPUB with SMIL timing, a subtitle pipeline, or an ELAN annotation set from narration, because eleven output formats across five domains is not something most libraries bother with, and the AGPL licence keeps the source reachable. Two things to weigh before you adopt it.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 113 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- readbeyond/aeneas2,876 ★ · +10
| Repository | 2026-09-16 | 2026-11-15 |
|---|---|---|
| readbeyond/aeneas | 2.9k | 2.9k |
10 Stars in the last 60 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The last release is v1.7.3 from 2017 and the last push is 2026-07-25
Two dates in this repository are more than nine years apart. The release history holds v1.7.1 from December 2016, v1.7.2 from early March 2017, and v1.7.3 from 2017-03-16, and the header block of the readme states version 1.7.3 with a date of 2017-03-15. The last push to the default branch is dated 2026-07-25. The repository is not archived. So there is a working tree that has moved and a set of published artifacts that have not, and the readme's own version block agrees with the tags rather than with the code. Anyone installing from the index gets the 2017 build, and anyone reading the repository for guidance is reading text that was written when Python 3.5 was current.
Debian 64bit on Python 2.7 is the only supported platform
The supported platforms section is unusually blunt. The project has been developed and tested on Debian 64bit with Python 2.7 and Python 3.5, and those are described as the only supported platforms at the moment. Other Linux distributions, Mac OS X, and Windows are said to have been confirmed to work, with a linked platforms file for details, but confirmed is not supported. The generic installation procedure then asks for Python 2.7.x as the preferred version. So a reader on a current Linux distribution, on a current macOS, or on Windows is outside the supported set by the project's own statement, and the fallback the readme offers is a companion project that puts aeneas inside a virtualised Debian image under VirtualBox and Vagrant.
An entire run is configured by one pipe-delimited string
Here is the design decision that most affects integration. The command line takes positional paths for the audio, the text, and the output, and then a single string as the third argument that carries every setting. A plain JSON run looks like this:
python -m aeneas.tools.execute_task \
audio.mp3 \
text.txt \
"task_language=eng|os_task_file_format=json|is_text_type=plain" \
map.jsonKeys are separated by pipes, values carry the language, the output format, and the input text format. A SMIL run for EPUB expands the same string with an audio reference, a page reference, an unparsed text type, an identifier pattern, and an identifier sort mode. The readme notes that the command is split across lines with backslashes for legibility and can be a single line in production, which is a hint that quoting is the part to get right.
pip install numpy has to happen before pip install aeneas
Step three of the installation says to install numpy with pip first and then aeneas, and adds that this order is important. That is an unusual instruction to put in a readme and it tells you something about the build. The project ships a compiled extension, and the readme separately lists Python headers for compiling the C and C++ extensions as optional but strongly recommended, plus a shell supporting UTF-8 for the same reason. The pinned requirement list is three packages long and every floor is very old: BeautifulSoup4 at 4.5.1 or later, lxml at 3.6.0 or later, and numpy at 1.9 or later. With no ceilings and a compiled extension built in 2017, the version you get from a fresh resolve is not the version it was linked against.
Three separate dependency checks exist in the repository
The readme tells you to verify an installation by running the diagnostics module. The tree contains, in addition to that module, a standalone setup check script and a separate dependency check script at the repository root. That gives a reader three entry points to try and only one of them documented in the main page. This is not a criticism so much as a shape: the project grew a diagnostics entry point inside the package, then kept root-level scripts that predate or sit beside it. The root-level layout is otherwise busy in the same way, with a virtual environment directory, a vendored third-party directory, a licences directory, a Debian packaging directory, an output directory, and a wiki directory, alongside three PyInstaller build specifications for producing standalone binaries.
Eleven output formats across five application domains
The synchronisation map is the product, and the formats it can be written in are grouped by what you will do with it. For research there are Audacity project files, the ELAN annotation format, and TextGrid. For digital publishing there is SMIL, which is what EPUB 3 timing uses. For closed captioning there are SubRip, SubViewer, TTML, and WebVTT. For the web there is JSON. For further processing there are CSV, SSV, TSV, TXT, and XML. That is eleven formats from one computation, and it is the strongest argument for the library, since a pipeline that ends in an ELAN session or an EPUB validator does not need you to write a converter first. The readme also notes that the format choice is driven from the same configuration string as everything else, so switching between a research annotation and a subtitle file is a matter of changing one key rather than writing anything.
setup.py imports every metadata field from a sibling module
Open setup.py and there is almost no metadata in it. The author, email and copyright are assigned at the top, and then the package name, version, description, long description, author, classifiers, keywords, licence, URL, packages, package data, scripts, install requirements and extras requirements are all imported from a sibling module called setupmeta, one import per field. The metadata is therefore not in the manifest and not in this file but in a second hand-maintained file, which means a packaging change touches two places and neither is the file you would look in first. The licence header in the same file is also unusual: it carries three separate copyright lines, covering an individual developer for 2012 to 2013, a company for 2013 to 2015, and the individual developer again for 2015 to 2017.
The documentation lives on a company domain, not in the repository
The repository is not where you learn how to use this. The readme's quick links point to a home page, documentation, and a tutorial, and all three sit on the company domain rather than on GitHub. Installation and platform details are linked into a wiki directory inside the repository, so those two subjects are split between the tree and the company site. There is also a separate benchmark site published from a different repository, a mailing list on a hosted forum, and a web application on its own domain. So the reference material for a nine-year-old release lives across at least four hosts and two repositories, and the code link is the only one of them you can be sure stays where it is.
Editorial conclusion
aeneas is still the reference implementation to read if you are building an EPUB with SMIL timing, a subtitle pipeline, or an ELAN annotation set from narration, because eleven output formats across five domains is not something most libraries bother with, and the AGPL licence keeps the source reachable. Two things to weigh before you adopt it. The newest tag is from 2017 while the tree has moved since, and the only supported platform is Debian 64bit on Python 2.7 or 3.5, so anything else is your problem. And the run is configured by a single pipe-delimited string rather than flags, which means the one thing most likely to break your integration is shell quoting rather than the alignment itself.
Frequently asked questions
How do you install aeneas?
The generic route asks for Python, FFmpeg, and eSpeak, then requires that espeak, ffmpeg, ffprobe, pip, and python all be callable from your shell. Then pip install numpy first and pip install aeneas second, with the readme stating the order matters. Verify with python -m aeneas.diagnostics. All-in-one installers exist for macOS and Windows, a bash script covers deb-based distributions, and a Vagrant image is offered for anything else.
How do you use aeneas to align a file?
Run the task tool with the audio path, the text path, a configuration string, and an output path. The configuration string is pipe-delimited and carries the task language, the output format, and the text input format, for example task_language=eng|os_task_file_format=json|is_text_type=plain. For batches, run the job tool against a zip container holding a config.txt or config.xml and an output directory. Both tools also accept flags that list runnable examples.
What is aeneas in this repository?
A Python and C library plus a set of tools that automatically generate a synchronisation map between a list of text fragments and an audio file containing the narration. The task is known in computer science as forced alignment. The name also belongs to the figure from the Aeneid, which this repository is not about.
Which platforms does aeneas support?
Debian 64bit with Python 2.7 and Python 3.5 are described as the only supported platforms. Other Linux distributions, macOS, and Windows are said to have been confirmed to work, with details in a linked platforms file, and a companion project offers aeneas inside a virtualised Debian image under VirtualBox and Vagrant for anyone who cannot install it natively.
What output formats can aeneas write?
Eleven, grouped by use. For research: Audacity project files, the ELAN annotation format, and TextGrid. For digital publishing: SMIL for EPUB 3. For closed captioning: SubRip, SubViewer, TTML, and WebVTT. For the web: JSON. For further processing: CSV, SSV, TSV, TXT, and XML.
Is aeneas still being released?
The newest release tag is v1.7.3, published in March 2017, and the readme header states the same version with a March 2017 date. The repository is not archived and the last push to the default branch is dated 2026-07-25, so the working tree has moved since the last tag. A fresh install from the package index gives you the 2017 build.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/readbeyond-aeneas)Star history chart for your README
[](https://hysenlabs.com/projects/readbeyond-aeneas)Was this useful?