Package: readalongs
ReadAlong-StudioAudiobook alignment for Indigenous languages!This library is an end-to-end audio/text aligner. It is meant to be used together with theReadAlong-Web-Componentto interactively visualize the alignment.Table of ContentsReadAlong-StudioTable of ContentsBackgroundInstallDependenciesStudio itselfValidationUsageCLIWeb APIStudioDockerMaintainersContributingContributorsLicenseSee also:ReadAlong-Studio documentation.BackgroundThe 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:ReadAlong XML file describing textAudio file (WAV or MP3)Which can be loaded using the read-alongweb component. See alsoStudio 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.(optional) Pre-segment inputs, consisting of:Single audio fileText with page markings (assume paragraph breaks = pages)Input pages: each page consists ofImage fileAudio fileTextRun alignmentView output and download componentsInstallInstalling dependenciesBefore 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 MacOSFirst install Homebrew, then use it to install FFmpeg withbrew install ffmpeg.The compiler should already be on your machine.Consider Xcode for your XML and text file editor.Dependencies on LinuxIf FFmpeg is not already installed,<your package manager> install ffmpegshould add it.The compiler should already be there, but run<your package manager> install gccif not.Dependencies on WindowsThe easy way, using AnacondaAnaconda/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 fromhttps://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 gitYou can then run the pip install and git commands below, and use readalongs, all from the Anaconda
Prompt.The hard wayIf you know what you're doing, you can install the dependencies directly on your machine:Install Python3 for Windows.InstallFFmpeg builds for Windows(alternative instructions).InstallVisual Studio Build Tools(search for "Build Tools", select C++ when prompted).Install Git for Windows (optional).Installing ReadAlongs Studio itselfTo 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:$gitclonehttps://github.com/ReadAlongs/Studio.git
$cdStudio
$pipinstall-e.Verifying your installationRunreadalongs -hto 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 devAnd you can download ouropen samples on GitHubto run your first alignments.UsageReadAlong-Studio can be used either through the command line, a distributed web application or Docker.CLIThis page lists only the most basic commands.For more information about how the command line interface works:Consult theCLI User Guide.Consult theCLI Reference.Invoke any CLI command with-hor--helpfor usage information. e.g.,readalongs --help,readalongs align --help.AlignmentBasic alignment is done with the following command.readalongs align TEXTFILE WAVFILE OUTPUTNAMEWeb APIThis page lists only the most basic commands.For more information about how the command line interface works consult the interactiveAPI Documentation.For information on spinning up your own dev Web API server locally, have a look atweb_api.py, but briefly, if you are running it locally for development, use:DEVELOPMENT=1 uvicorn readalongs.web_api:web_api_app --reload/langsTo query a list of available languages in the ReadAlong Studio API, send a GET request tohttps://readalongs-studio.herokuapp.com/api/v1/langs/assembleThis endpoint is a remote procedural call that assembles the data needed to build a readalong using the JavaScript-basedSoundSwallower decoder. It is an endpoint that accepts POST requests with either plaintext or XML input. Please see thedocumentationfor more information.Studio web applicationThe ReadAlong-Studio web interface is available athttps://readalong-studio.mothertongues.org/and the source code is available here:https://github.com/ReadAlongs/Web-ComponentDockerIf 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-studioTo run the Flask web app in a Docker container using that image:docker run -p 5000:5000 -it readalong-studioTo run the Flask web app with real-time update:docker run -p 5000:5000 -it -v $(pwd):/opt/readalong-studio readalong-studioThen you should be able to visithttp://localhost:5000/.To run the interactive shell with real-time update:docker run -p 5000:5000 -it -v $(pwd):/opt/readalong-studio readalong-studio shTo 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 bashMaintainers@dhdaines.@littell.@roedoejet.@joanise.ContributingFeel free to dive in!Open an issueor submit PRs.This repo follows theContributor CovenantCode of Conduct.You can install our standard Git hooks by running these commands in your sandbox:pipinstall-rrequirements.dev.txt
pre-commitinstall
gitlintinstall-hookHave a look atContributing.mdfor the full details on the
Conventional Commit messages we prefer, our code formatting conventions, and
our Git hooks.ContributorsThis 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 projectCitationif you use this software in a project of yours and write about it, please cite
us using the following:@inproceedings{Littell_ReadAlong_Studio_Practical_2022,
  author = {Littell, Patrick and Joanis, Eric and Pine, Aidan and Tessier, Marc and Huggins-Daines, David and Torkornoo, Delasie},
  booktitle = {Proceedings of SIGUL2022 @LREC2022},
  title = {{ReadAlong Studio: Practical Zero-Shot Text-Speech Alignment for Indigenous Language Audiobooks}},
  year = {2022},
  month = {6},
  pages = {23--32},
  publisher = {European Language Resources Assiciation (ELRA)},
  url = {http://www.lrec-conf.org/proceedings/lrec2022/workshops/SIGUL/pdf/2022.sigul-1.4.pdf}
}LicenseMIT© 2019-2022 David Huggins-Daines and National Research Council Canada