Playing EPUB3 Media Overlays on Android

Short version: a Media Overlay is a real recording synchronized to the text by a SMIL timing file. It is not text-to-speech, and it only exists when a publisher or a tool like Storyteller produced it. Lectern reads the SMIL data automatically and, when it finds it, plays the recording with the current text highlighted instead of generating speech.

What a Media Overlay actually is

EPUB3 Media Overlays are a SMIL file bundled inside the EPUB. Each <par> element pairs a fragment of the book's XHTML (a text reference, usually a paragraph or a sentence the publisher marked with an id) with a clip of an audio file (an audio reference with a clipBegin and clipEnd). Play the clip, and you know exactly which fragment of text it belongs to. Stack a few hundred of those pairs and you get a whole book that a reading app can highlight sentence by sentence, or paragraph by paragraph, while a professional narrator reads it.

It is genuinely optional. Nothing about EPUB3 requires it, and producing it costs real studio time or a forced-alignment pass over an existing audiobook, so most EPUB3 files, including recent ones, do not have it.

How this differs from Lectern's text-to-speech

Lectern already highlights the sentence it is speaking with its own on-device voices (Piper and Kokoro neural voices, plus system voices). See how synchronized highlighting improves reading for that side of it. A Media Overlay is a different source for the same idea, and the two are not interchangeable inside one playback session.

How Lectern plays a Media Overlay

There is no separate mode to turn on. The same Listen control that starts text-to-speech or a linked audiobook checks the book first: if it embeds Media Overlays, Lectern plays those instead of generating speech.

1. Open the book and tap Listen. Lectern reads the book's embedded SMIL data during import and scanning, so it already knows whether narration is built in.
2. Built-in narration plays, and the current text lights up. The Audio tab of the reader settings sheet lists it as "Built-in narration" under "Listening with", alongside text-to-speech and any linked audiobook file, so you can see which source is active.
3. Tap a sentence to jump there. Tapping text seeks the recording to the matching clip, the same way tapping text seeks TTS playback.
4. Lock screen, notification and Bluetooth controls work as usual. Media Overlay playback goes through the same foreground media session as any narration in Lectern: play and pause from the lock screen, headset buttons, and a notification with the book's title.
5. The screen stays on while it plays, if you have that reading setting enabled, exactly like text-to-speech playback.

Because the voice is fixed to the recording, the usual voice and language pickers do not apply here. If you would rather hear a synthetic voice, or a chapter's recording is missing, the Audio tab has an explicit "Use text-to-speech instead" switch, and it also holds the reverse switch, "Use read-along narration", to go back.

When a chapter or a whole book has no overlay

Not every chapter of a narrated edition is guaranteed to have audio; front matter or an appendix is sometimes left unrecorded. If you tap play on a section with no narration, Lectern shows a short "No narration here" notice and offers to read that part aloud with text-to-speech instead, without losing your place.

For a book that has no Media Overlays at all, there is nothing to notice: the Listen control simply starts text-to-speech, the same as any other book in your library.

Fixed-layout EPUB3 books

A fixed-layout EPUB3, one built from full-page images rather than reflowable text, normally opens in Lectern's comic viewer instead of the regular reader. Books with Media Overlays are the exception: Lectern keeps them in the regular reader, so a narrated picture book keeps its built-in narration and highlighting. The price is the original page design, since the text is reflowed instead of shown as fixed pages.

Getting a Storyteller EPUB3 into Lectern

Storyteller is a self-hosted server that aligns a DRM-free ebook with its matching audiobook and exports a standards-based EPUB3 with Media Overlays. It is one of the more practical ways to end up with a real narrated edition of a book you already own. See the full Calibre-Web vs Storyteller comparison if you are deciding whether to run it.

1. Set up Storyteller. The self-host OPDS guide covers the Docker Compose setup. Add a DRM-free ebook and its matching audiobook and let alignment finish; it can take a while, since it is the compute-heavy part of the whole pipeline.
2. Add Storyteller as a catalogue in Lectern. On an empty or existing library, open the add-book flow and choose the Storyteller option among the self-hosted catalogues, rather than the generic OPDS feed entry. Enter the server address and your Storyteller username and password, then connect.
3. Look for the headphones badge. In the catalogue, a small headphones icon on a book's cover means Lectern recognized a working read-along acquisition on that entry. A book without the badge is not necessarily narration-free, since the feed has to advertise it in a way Lectern can recognise reliably; if in doubt, open the book after downloading and check.
4. Download the book. It joins your normal offline library like any other import. From then on Lectern needs no further connection to the Storyteller server; the audio and the SMIL timing travel inside the EPUB file itself.

If you already have an EPUB3 file with Media Overlays from somewhere else, copied over with a file manager or synced through a folder, importing it the normal way is enough. Lectern parses the embedded SMIL during import and scanning, so there is no separate setting to flip.

Troubleshooting

• Listen only offers a synthetic voice, and you expected narration. The file may be a plain EPUB3 with no Media Overlays at all; the feature is optional and most books do not have it. If you believe the file does embed audio and SMIL but Lectern missed it, open the book once: Lectern re-reads its contents on opening and updates the narration marker.
• One chapter is silent. Some narrated editions simply were not recorded end to end. Use the text-to-speech fallback Lectern offers for that section and continue with narration once it resumes.
• The highlight jumps a whole paragraph instead of one sentence. That is expected. Lectern highlights whatever fragment the publisher's SMIL points to, and does not split it further than the recording allows.
• You want a different narrator or another language. Not possible while built-in narration is active, since it plays a fixed recording. Switch to "Use text-to-speech instead" in the Audio tab for any downloaded voice.
• A narrated picture book opens as reflowed text instead of fixed pages. That is deliberate: a fixed-layout EPUB3 with Media Overlays stays in the regular reader so its narration keeps working.
• A Storyteller catalogue entry will not download, or downloads without narration. Alignment may still be running on the server; Lectern only downloads EPUB entries, and it deliberately ignores audio-only entries rather than importing something it cannot open as a book.

Frequently asked