ReadAlong-Studio

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

• ReadAlong-Studio
  • Table of Contents
  • Background
  • Install
    • Dependencies
    • Studio itself
    • Validation
  • Usage
    • CLI
    • Studio
    • Docker
  • Maintainers
  • Contributing
    • Contributors
  • License

See also: ReadAlong-Studio documentation.

Background

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. See also Studio Output Realizations.

Optionally a book can be generated as a standalone HTML page, XHTML, Praat TextGrid, ELAN Eaf file, as well as WebVTT or SRT subitle formats.

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

Install

Installing dependencies

Before you can install the ReadAlong Studio, you will need to install these dependencies:

• Python, version 3.7 or higher,
• FFmpeg,
• a C compiler,
• Git (optional, needed to get the current development version).

Dependencies on MacOS

First install Homebrew, then use it to install FFmpeg with brew install ffmpeg.

The compiler should already be on your machine.

Consider Xcode for your XML and text file editor.

Dependencies on Linux

If FFmpeg is not already installed, <your package manager> install ffmpeg should add it.

The compiler should already be there, but run <your package manager> install gcc if not.

Dependencies on Windows

The easy way, using Anaconda

Anaconda/Miniconda will install Python 3 and the required compiler automatically for you, and simplifies ffmpeg and git installation. We recommend this solution.

Download and install the latest "Miniconda3 Windows 64-bit" installer from https://docs.conda.io/en/latest/miniconda.html. You can accept all the default options suggested by the installer.

Launch an Anaconda Prompt (this should be available from your Start menu after installation) and run:

conda install ffmpeg
conda install git

You can then run the pip install and git commands below, and use readalongs, all from the Anaconda Prompt.

The hard way

If you know what you're doing, you can install the dependencies directly on your machine:

• Install Python3 for Windows.
• Install FFmpeg builds for Windows (alternative instructions).
• Install Visual Studio Build Tools (search for "Build Tools", select C++ when prompted).
• Install Git for Windows (optional).

Installing ReadAlongs Studio itself

To install the latest version of readalongs published to PyPI, you can run a standard pip installation: pip install readalongs. Be warned, however, that this project is still very active so the published version could be out-of-date. Consider installing the current development version instead.

To install the current development version, clone the repo and pip install it locally:

$ git clone https://github.com/ReadAlongs/Studio.git
$ cd Studio
$ pip install -e .

Verifying your installation

Run readalongs -h to confirm that installation was successful.

If you installed the current development version with Git, you can also run the full test suite:

cd Studio/test
python run.py dev

And you can download our open samples on GitHub to run your first alignments.

Usage

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

CLI

This page lists only the most basic commands.

For more information about how the command line interface works:

• Consult the CLI User Guide.
• Consult the CLI Reference.
• Invoke any CLI command with -h or --help for usage information. e.g., readalongs --help, readalongs align --help.

Alignment

Basic alignment is done with the following command.

readalongs align TEXTFILE WAVFILE OUTPUTNAME

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 python3 run.py. A web app will then be available on port 5000.

Docker

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

Working with in a Docker container has the advantage that no matter what your OS is, and what you have installed or configured, you will run on the standard ReadAlong-Studio configuration.

To build the Docker image, run:

docker build . --tag=readalong-studio

To run the Flask web app in a Docker container using that image:

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

To run the Flask web app with real-time update:

docker run -p 5000:5000 -it -v $(pwd):/opt/readalong-studio readalong-studio

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

To run the interactive shell with real-time update:

docker run -p 5000:5000 -it -v $(pwd):/opt/readalong-studio readalong-studio sh

To run an interactive bash shell, using your local user inside Docker:

docker run -p 5000:5000 -it -v $(pwd):/opt/readalong-studio -u $(id -u):$(id -g) readalong-studio bash

Maintainers

@dhdaines. @littell. @roedoejet. @joanise.

Contributing

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

This repo follows the Contributor Covenant Code of Conduct.

Have a look at Contributing.md for help getting started.

Contributors

This project exists thanks to all the people who contribute.

Here is a partial list: @dhdaines. @eddieantonio. @finguist. @joanise. @littell. @roedoejet.

Project web page: ReadAlong Studio: Application for Indigenous audiobooks and videos project

License

MIT © 2019-2021 David Huggins-Daines and National Research Council Canada