EPub Reader

A library that loads and renders ePub documents in the browser.

It provides support for:

• Media Overlays - if the ePub has smil files the library plays the narration and highlights the corresponding html element. The client can also obtain the current time of the audio book and the total duration.
• Navigation
  • For EPub 3.0 the manifest <item properties="nav" /> element is parsed and provided in the form of a Table of contents (page list is also included).
  • Support for EPub 2.0 <item media-type="application/x-dtbncx+xml" /> is not yet implemented.
• Cover image
  • For EPub 3.0 a manfiest <item properties="cover-image" /> element is checked.
  • For EPub 2.0 <meta name="cover" /> is not yet implemented.
• Metadata
  • Identifier (<dc:identifier>)
  • Title (<dc:title>)
  • Language (<dc:language>)
  • Author (<dc:creator>)

Getting started

Installation

npm i @asteasolutions/epub-reader

Usage

First you need an HTML element where the content will be rendered

<div id="epub-reader"></div>

Then you need to pass the epub document. The library provides two loaders which you can use depending on the source of the epub:

• ZipLoader - use this when you have a Blob/File (e.g. selected by the user from the file system or downloaded from a url) or a url to an epub file. In the case of a url the epub is streamed instead of being downloaded in its entirety.
• AJAXUnpackedLoader - use this when the epub is extracted and served statically from a url.

You can also use the createLoader function which will create a loader for you based on the parameters passed.

// This expects the epub files to be statically served on the corresponding path appended to the url - e.g. https://example-epub-library.com/awesome-epub/META-INF/container.xml
createLoader('https://example-epub-library.com/awesome-epub')

// This will create a ZipLoader
createLoader('https://example-epub-library.com/awesome-zipped-epub', { isZipURL: true })
// same as this
createLoader(file)

Putting it all together

import { createLoader, Book, Reader } from '@asteasolutions/reader-core'

const container = document.getElementById('epub-reader')

const loader = await createLoader(source: Blob | string)
Book.open(loader).subscribe({
  next: book => {
    const reader = new Reader(container, book)

    reader.loadContent().subscribe(() => {
      // EPub is now rendered
    })
  }
})

Events

Once initialized you can listen to the following Reader events: | Property | Description | | -------- | ----------- | | audioEvents.onPlaybackStateChanged | Fired with a single argument playing: boolean | | audioEvents.onAudioEnded | Fired when an audio file reached its end | | audioEvents.onPositionChanged | Fired every 200 ms while a media overlay is playing. It is passed a single argument currentTime: number, indicating the current time (in seconds) within the audio file | | events.pageChange | Fired when the reader navigates to a new page | | events.chapterChange | Fired when a new chapter is loaded (new html from the epub is rendered) | | events.textSelected | Fired when the user selects something in the epub's html. Passed a range: DOMRange argument | | mediaOverlayEvents.onGlobalPositionChanged | Similar to the audioEvents.onPositionChanged but in the context of the entire book. Also the argument is in milliseconds |

API

| Object | Property | Description | | ------ | -------- | ----------- | | Reader | currentChapterIndex | The index of the current chapter as defined in the epub's <spine> tag | | | totalChapters | The number of chapters in the epub | | | currentPage | The index of the current page within the chapter. Note: Since only a paginated layout is currently supported, the page properties are referring to the currently dispalyed pages and not the page list of the navigation document. This means that resizing the container holding the epub will cause the pages to be recalculated. | | | totalPages | The number of pages within the chapter | | | playing | Whether or not a media overlay is being played | | | togglePlayback() | Turns the media overlay playback on/off | | | goToHref(href: string).subscribe() | Navigates to an anchor within the epub. For example passing the href property from a TocEntry | | | previousChapter(goToEnd?: boolean) | Navigates to the previous chapter. In case true is passed the epub will be navigated to the last page of the previous chapter, otherwise it will go to the beginning | | | previousPage() | Navigates to the previous page in the chapter. If the user is on the first page of a chapter the epub is navigated to the last page of the previous chapter | | | nextPage() | Navigates to the first page of the next chapter | | | nextPage() | Navigates to the next page in the chapter. If the user is on the last page it will navigate to the first page of the next chapter | | Book | metadata | The Metadata object for the epub | | | nav | The Navigation object for the epub | | | cover | The cover image url | | | overlayMetadata | The OverlayMetadata object for the epub. Contains the total duration of the epub and the durations for each smil file | | | open(loader: BookLoader) static | Creates the book object with the given loader |

Rendering

Currently on a paginated layout is supported.