[Feature]: Support parsing/OCR of image-based chapter titles (common in Yen Press EPUBs)

[starpause]

What would you like to see?

I would like to request a feature where Alexandria can automatically parse text from images that serve as chapter headings/titles, using either a local OCR library (e.g., easyocr or tesseract) or a local Multimodal/Vision LLM (e.g., Qwen2-VL, Llama-3.2-Vision) if the user has one configured.

Steps to Reproduce / Test Case

I have generated a minimal, copyright-free sample EPUB that reproduces this exact structure:

sample_image_chapters.zip

EPUB Markup Structure

In this sample, the chapter files (chapter1.xhtml, chapter2.xhtml) contain:

<div class="title-container">
  <!-- The chapter title is represented solely as an image -->
  <img class="title-image" src="images/chapter1-title.png" alt="Chapter Title Image" />
</div>

The actual text rendered in the image is:

• For Chapter 1: "Chapter I: The Awoken Princess"
• For Chapter 2: "Chapter II: The Crimson Nocturne"

Currently, Alexandria imports this chapter structure but does not extract the text from the images, meaning the generated script does not contain the actual chapter names.

Proposed Solution

1. Detection: During EPUB parsing, identify blocks or headings that contain an <img> element but no accompanying text.
2. Text Extraction (OCR/VLM):
   • Option A (Lightweight OCR): Use a Python OCR library like easyocr or pytesseract to extract text from the referenced image.
   • Option B (VLM integration): If the backend has access to a vision-enabled model, send the image to the model with a prompt like: "Extract the text from this chapter title image exactly as written."
3. Replacement: Inject the extracted text back into the internal parsed representation of the chapter title before sending it to the script generation phase.

Use case

Many light novels and manga-adjacent ebooks (especially those published by Yen Press, e.g., The Vexations of a Shut-In Vampire Princess) use stylized images (PNG/JPEG) instead of text for chapter titles.

When Alexandria parses these EPUBs:

1. The parser misses the chapter title text entirely since it only sees an <img> tag (often with blank or generic alt text like "image" or "Chapter Title Image").
2. This leads to missing chapter boundaries or generic labels in the generated script and the final chaptered audio output (e.g., M4B files).
3. The LLM script generator is deprived of the chapter name context, which can affect the flow of script generation.

Publisher with this pattern: Yen Press, J-Novel Club (on certain titles), Kadokawa.

Alternatives considered

Before script generation I could pre-process the epub files myself to strip out chapter title images and replace them with text.

After script generation I could manually search for the first text in each chapter and insert new lines that include the chapter titles, for example by copy pasting from the TOC to each appropriate chapter title placement.

[on22s]

I tested this with several public-domain books from Project Gutenberg, and I think most of the problem can be solved without adding OCR or an image model.

For example:

• In Cranford (https://www.gutenberg.org/ebooks/57539), some chapter headings are images. One of those images has no useful alternative text, but the EPUB’s table of contents still contains the complete title, such as “Chapter 11: Samuel Brown.”

• In The Story of London (https://www.gutenberg.org/ebooks/46618), the table of contents contains complete chapter names such as “Chapter II: The Walled Town and its Streets.” Several chapters are stored in the same HTML file and distinguished by internal links,
  so the importer needs to follow those links rather than matching only filenames.

• In The Book of Trinity College, Dublin (https://www.gutenberg.org/ebooks/61000), some heading images are described only as a “decorative chapter heading.” That description is useless as a chapter title, while the table of contents contains the actual title.

• Gray Days and Gold in England and Scotland (https://www.gutenberg.org/ebooks/56429) provides another example where the table of contents has complete chapter labels and points to specific locations within the book.

I downloaded the official EPUB versions of these books and ran them through the current Alexandria text extractor. The exact titles from their tables of contents were not included in the extracted text.

A better approach would be:

1. Read the EPUB’s built-in table of contents.
2. Match each table-of-contents entry to its location in the book.
3. Insert that title when the chapter begins, but only when the page does not already contain the same heading.
4. Support links to specific locations inside an HTML file, because one file can contain several chapters.
5. Use the older EPUB table-of-contents format as a fallback for EPUB2 books.
6. Consider OCR only as a final fallback when neither the page nor the EPUB metadata provides a usable title.

This should recover chapter titles from many illustrated EPUBs while remaining faster, more accurate, and much lighter than processing every heading image with OCR or a vision model. It also uses information that the publisher already supplied specifically for
identifying chapters.

[starpause]

@on22s great research and suggested direction, I agree your approach would be better and something which could be put in place before any OCR development as the fallback.