I am trying to create an ebook with a media overlay (read aloud feature). Once created, I would like to use the ebook to play audio and highlight the text in the book at the appropriate time in the audio.

I understand that SMIL has to be used and this site details it well.

The manual process is quite laborious especially when I have a large content. I am looking for an application that could help me to mark the section of the content (could be at a low level as a word/character to a line or even paragraph) and ask it to play a section of an audio file.

I tried PubCoder but in the trial version, it automatically picks the section for the audio overlay and does not permit me to do so at a granular level. The documentation says:

Sometimes you may want to split a read aloud block at a certain, specific position. You can achieve this by inserting a Read Aloud Splitter in your text. Just edit the text in your text box and choose Insert Read Aloud Splitter in the advanced functionalities menu in the text editor toolbar. Restart the read aloud wizard to see the changes.

I could not find any option to insert "Read aloud splitter" in the user interface and I presume it is not available in the trial version.

My question is whether any such tool other than PubCoder allows me to define the media overlay graphically and allow me to create epub3 ebooks?

I had tried Sigil, BlueGriffon and Calibre and to my knowledge, they do not have a user interface (menu) to select the text and its corresponding segment in an audio file.

  • Did you find any useful tools for doing media overlays on EPUB3? Do you mind to share if there is any?
    – CK Tan
    Nov 19, 2022 at 16:56
  • Nope. I dropped the idea of creating the Ebook as I could not find any tool.
    – Narayanan
    Feb 13, 2023 at 13:50

2 Answers 2


I haven't found a graphical way to create read-aloud ebooks, but here's my python-scripts-based way of making read-aloud ebooks:


  • Python 3.6 or later.
  • FFmpeg
  • syncabook
  • aeneas
  • eSpeak
  • BeautifulSoup4, Jinja2, lxml, progressbar2, and numpy.


On Arch-based distros.

sudo pacman -S python ffmpeg espeak

Install aeneas using pip.

pip install BeautifulSoup4 Jinja2 lxml progressbar2 numpy aeneas

Install syncabook by cloning the repo and running setup.py

git clone https://github.com/r4victor/syncabook && cd syncabook
python setup.py sdist && pip install dist/syncabook*.tar.gz

Verify installations:

python -m aeneas.diagnostics
syncabook -h

To create an ebook with Media Overlays, we will be using syncabook. It uses three necessary components to create the e-book:

  • audio files (the audiobook) split into chapters
  • text files split into chapters and converted to XHTML.
  • SMIL files that sync the audio with the text.
  • (Optional) JPG image for the ebook cover

The first three components MUST be included inside these directories in our root directory:

├── audio        (required -- audio files)
├── smil         (required -- SMIL files)
├── plaintext    (temporary -- plain text files)
├── images       (optional -- holds the epub cover as cover.jpg)
└── sync_text    (required -- XHTML text files)

Therefor, you need to create a directory for your book and these three subdirectories.

cd my-new-book
mkdir -p audio plaintext smil sync_text images

Inside plaintext, you need to put the book split into chapters in plain text format (.txt files).

One way to do this would be to convert a book from its original format (epub) to plain text, and use syncabook split_text utility to split it into multiple chapters:

I put a plaintext.txt at the root directory and add a delimiter -------- before the start of each chapter except the first one (using sed or manually in Vim. AI chatbots should help here.) Then, run the following command:

syncabook split_text --m opening --p '\-\-\-\-\-\-\-\-' book.txt plaintext

This will spit out the chapters into individual files inside the plaintext directory. The text files are named numerically. You can rename them to have a proper table of content in your ebook later on. (Important: you'll need to rename the audio files the same way as well.)

Now, you need to convert the text files into XHTML files. Unlike plain text, XHTML files are split into sentences and given id to be used inside the SMIL files. Run the following:

syncabook to_xhtml plaintext sync_text

Now that our text files are ready, next, we will prepare our audio files. Unfortunately, unlike text files, there isn't an easy way to split audiobooks into chapters. You'll need them split already.

Put the audio files inside the audio directory and be sure to name them the exact names you've given the XHTML text files inside sync_text.

├── audio
│   ├── 01.mp3
│   ├── 02.mp3
│   ├── 03.mp3
│   └── 04.mp3
├── plaintext
│   ├── 01.txt
│   ├── 02.txt
│   ├── 03.txt
│   └── 04.txt
├── sync_text
│   ├── 01.xhtml
│   ├── 02.txt
│   ├── 03.txt
│   └── 04.txt
├── images
│   └── cover.jpg
└── smil (empty)

To generate the SMIL files, we will be using aeneas. syncabook can generate them using a tool called afaligner, but it only supports .wav audio files which are quite large compared to .mp3s.

Using the following shell command, we will iterate through all .mp3 and generate .smil files inside the smil directory. (If you're working with another audio format, tweak the command accordingly.)

⚠️ ⚠️ Make sure that the smil directory exists beforehand and that the XHTML chapters file names match those of the audiobook file names.

for i in audio/*.mp3; do i=`basename -s '.mp3' $i`; python -m aeneas.tools.execute_task "audio/$i.mp3" "sync_text/$i.xhtml" "task_language=eng|os_task_file_format=smil|os_task_file_smil_audio_ref=../audio/$i.mp3|os_task_file_smil_page_ref=../text/$i.xhtml|is_text_type=unparsed|is_text_unparsed_id_regex=f[0-9]+|is_text_unparsed_id_sort=numeric" "smil/$i.smil" --skip-validator; done

Once this task finishes, we can use syncabook to create an .epub file out of the three pieces.

Inside the root directory, run:

syncabook create .

After asking for some metadata such as your ebook title, author, description and so on. You can modify the TOC before the final ebook generation. It will output some directories among which is the out directory holding our .epub file.

You can play the file using:

  • Thanks, looks promising, but now I don't have the resources to try and confirm.
    – Narayanan
    Oct 12, 2023 at 12:48

This must be done in code. It is possible to edit .smil files and everything else in Sigil.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.