📖🎧 A tool for creating ebooks with synchronized text and audio (EPUB3 with Media Overlays)
syncabook is a set of tools for creating ebooks with synchronized text and audio (a.k.a. read along, read aloud; like Amazon's Whispersync). You start with a list of text files (plaintext or XTML) and a list of audio files (.wav or .mp3) and get an ebook in the open EPUB3 with Media Overlays format. Here is a video that demonstrates what reading an ebook produced with syncabook looks like.
The synchronization is done automatically using the afaligner library. It is a forced aligner that works by synthesizing text and then aligning synthesized and recorded audio using a variation of the DTW (Dynamic Time Warping) algorithm. For alignment details, please refer to the afaligner repository.
beautifulsoup4
, Jinja2
, lxml
, progressbar2
Get the source code:
git clone https://github.com/r4victor/syncabook/ && cd syncabook
Install syncabook:
pip install .
Now you can run syncabook from the command line:
syncabook -h
Installing afaligner with all its dependencies may seem tedious. In that case, consider using syncabook as a Docker container.
Get the source code::
git clone https://github.com/r4victor/syncabook/ && cd syncabook
Create a Docker image:
docker build -t syncabook .
Now you can run syncabook as a Docker container. The only difference with the native installation is that you have to mount the book's directory as a volume with the -v
option. So if you're currently in the book's directory, then the command will look like this:
docker run -v "$(PWD)":/books/mybook syncabook sync /books/mybook
Install pytest
and epubcheck
:
pip install pytest epubcheck
Run tests:
python -m pytest -s tests/
The ebook is assembled from source files in the book's root directory that includes:
audio/
directory containing a list of audiobook's audio files.sync_text/
directory containing a list of XHTML files synchronized with audio files.no_sync_text/
directory containing a list of XHTML files NOT synchronized with audio files (table of contents, colophon and any other files).smil/
directory containing SMIL files (synchronization info).metadata.json
file which contains information about the book such as title, author, narrator, etc.In order to prepare such a structure syncabook provides a set of tools. Here's a brief outline of a typical usage; see a concrete example below.
Initially we have an empty directory named ebooks/my_ebook/
. Then we somehow get the audio files and save them to ebooks/my_ebook/audio/
. Next we get the text and save it, for example, as ebooks/my_ebook/text.txt
. Now we need to convert this plain text to a list of XHTML files. We use the split_text
and to_xhtml
commands. The split_text
command splits one plain text file into a list of plain text files, and the to_xhtml
command converts a list of plain text files to a list of XHTML files. What's left is to synchronize the text and the audio. We may use the sync
command that performs the synchronization and produces a list of SMIL files, or we may just use the create
command that performs the synchronization and then creates an ebook. The create
command automatically creates a nav.xhtml
file containing a table of contents and a colophon.xhtml
file to credit contributors. It ask us for all the necessary information in the process and saves it as ebooks/my_ebook/metadata.json
.
If you want to create an ebook for a LibriVox recording, the download_files
command lets you automatically download the audio files from librivox.org and the transcribed text from gutenberg.org. Moreover, if someone has produced an ebook for that recording and contributed the prepared XHTML and SMIL files to the
synclibrivox repository, the download_files
command gets them as well and all you are left to do is to run the create
command.
We will create an ebook for On the Duty of Civil Disobedience by Henry David Thoreau based on the LibriVox recording by Bob Neufeld.
Download the text and the audio:
syncabook download_files https://librivox.org/civil-disobedience-by-henry-david-thoreau/ civil_disobedience
The audio is recorded in two parts, thus we create two files in civil_disobedience/plaintext/
in which we respectively copy the contents of the first and second parts. This is a little bit of manual labor. If a book is long and recording is made in units like chapters, the split_text
command can help you automate this process.
Convert the plain text files into the XHTML files:
syncabook to_xhtml civil_disobedience/plaintext/ civil_disobedience/sync_text/
Sync the text and the audio to produce the SMIL files:
syncabook sync civil_disobedience/
Create the EPUB3 ebook:
syncabook create civil_disobedience/
It asks us for the book's title, book's author and other information. Then it generates the nav.xhtml
file containing a table of contents and the colophon.xhtml
file to credit contributors and places them in civil_disobedience/no_sync_text/
. We make some changes in nav.xhtml
and proceed. Congrats! Our ebook is created and saved in civil_disobedience/out/
.
See the synclibrivox repository for this and other ebooks.
cover.jpg
in the images/
directory before running syncabook create
.The ebooks produced are in the EPUB3 format and can be opened in any EPUB3 reader. Unfortunately, the Read Aloud feature is not well supported. Here's a list of apps, which I know of, that support it:
Readium (Chrome App) – great read & listen experience. Unfortunately, Google is going to deprecate Chrome Apps.
Thorium Reader (Windows, MacOS and Linux) – Readium's successor, a desktop app in active development.
Adobe Digital Editions (Windows, MacOS, iOS, Android) – fully supports EPUB3 standard. Not the best reading experience, though: text and audio seem out of sync.
Menestrello (iOS, Android) – the best app to read & listen that was developed for this specific purpose. Unfortunately, no longer maintained and not even available on AppStore or Google Play. Still, .apk can be installed on Android.
There is also a page on epubtest.org that compares Media Overlays support across EPUB3 readers.
Please let me know if you know of other apps that support EPUB3 with Media Overlays.
id="f[0-9]+"
(see an example). If you use the to_xhtml
command to produce XHTML files from plaintext, they will contain the proper tags automatically. If you use your own XHTML files, you'll need to modify them to contain the tags with id
attributes.