Skip to content
Audiobook alignment for North American indigenous languages
CSS Python HTML Other
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs added autodocumentation to cli Aug 12, 2019
readalongs specified version of g2p Sep 6, 2019
.gitattributes Create .gitattributes Aug 16, 2019
.readthedocs.yml added autodocumentation to cli Aug 12, 2019
Dockerfile Optimization so installed requirements are cached by docker Jul 8, 2019
LICENSE Initial commit Jan 21, 2019 Update Aug 2, 2019
requirements.txt specified version of g2p Sep 6, 2019


Coverage Status Build Status PyPI package license standard-readme compliant

Audiobook alignment for Indigenous languages!

This library is an end-to-end audio/text aligner. It is meant to be used together with the ReadAlong-Web-Component to interactively visualize the alignment.

Table of Contents


The concept is a web application with a series of stages of processing, which ultimately leads to a time-aligned audiobook - i.e. a package of:

  • SMIL file describing time alignments
  • TEI file describing text
  • Audio file (WAV or MP3)

Which can be loaded using the read-along web component.

Optionally a book can be generated as a standalone HTML page or as an ePub file.

  1. (optional) Pre-segment inputs, consisting of:
    • Single audio file
    • Text with page markings (assume paragraph breaks = pages)
  2. Input pages: each page consists of
    • Image file
    • Audio file
    • Text
  3. Run alignment
  4. View output and download components


The best thing to do is install with pip pip install readalongs.

Otherwise, clone the repo and pip install it locally.

$ git clone
$ cd ReadAlong-Studio
$ pip install -e .


ReadAlong-Studio can be used either through the command line, a distributed web application or Docker.


Below shows some basic commands. For more information about how the command line interface works, please check the documentation. Additionally, you can add the --help flag to any command for more information.


Basic alignment is done with the following command.



In order to generate an ePub, there are two steps:

  1. readalongs align --output-xhtml TEXTFILE WAVFILE OUTPUTNAME
  2. readalongs epub OUTPUTNAME.smil OUTPUTNAME.epub

Studio web application

ReadAlong-Studio has a web interface for creating interactive audiobooks. The web app can be served by first installing ReadAlong-Studio and then running readalongs run. A web app will then be available on port 5000.


If you are having trouble installing the package, you can also clone the repo and run the studio using Docker.

To build the Docker container, run:

docker build . --tag=readalong-studio

To run the Flask web app from the Docker container:

docker run -p 5000:5000 -it readalong-studio

Then you should be able to visit http://localhost:5000/.


@dhdaines. @littell. @roedoejet.


Feel free to dive in! Open an issue or submit PRs.

This repo follows the Contributor Covenant Code of Conduct.


This project exists thanks to all the people who contribute.

@dhdaines. @eddieantonio. @finguist. @joanise. @littell. @roedoejet.


MIT © David Daines, Patrick Littell, Aidan Pine

You can’t perform that action at this time.