2.3.0

Resources

• Migration guide
• API Reference

Changelog

Added

Shared

• Extract the raw content (text, images, etc.) of a publication. Take a look at the user guide.
• Add support for unsafe HTTP redirections with DefaultHttpClient.
  • You will need to opt-in explicitly by implementing DefaultHttpClient.Callback.onFollowUnsafeRedirect.

Navigator

• Improved Javascript support in the EPUB navigator:
  • Register custom JavascriptInterface objects to inject native Kotlin code in the EPUB web views.

    EpubNavigatorFragment.createFactory(
        publication = publication,
        …,
        config = EpubNavigatorFragment.Configuration().apply {
            registerJavascriptInterface("customInterface") { link ->
                MyCustomApi(link)
            }
        }
    )
    
    class MyCustomApi(val link: Link) {
        @JavascriptInterface
        fun api(arg: String): String {
            return "API called from the resource ${link.href} with argument $arg")
        }
    }

  • Evaluate JavaScript on the currently visible HTML resource with EpubNavigatorFragment.evaluateJavascript().

    val result = navigator.evaluateJavascript("customInterface.api('argument')")

• New PSPDFKit adapter for rendering PDF documents. Take a look at the user guide.
• A brand new text-to-speech implementation.
• Support for custom fonts with the EPUB navigator.
• New EPUB user preferences, as part of the revamped Settings API:
  • backgroundColor - Default page background color.
  • fontWeight - Base text font weight.
  • textColor - Default page text color.
  • textNormalization - Normalize font style, weight and variants, which improves accessibility.
  • imageFilter - Filter applied to images in dark theme (darken, invert colors)
  • language - Language of the publication content.
  • readingProgression - Direction of the reading progression across resources, e.g. RTL.
  • typeScale - Scale applied to all element font sizes.
  • paragraphIndent - Text indentation for paragraphs.
  • paragraphSpacing - Vertical margins for paragraphs.
  • hyphens - Enable hyphenation.
  • ligatures - Enable ligatures in Arabic.
• Fixed scroll inertia when scrolling an EPUB.
• EPUB decorations can now be attached to Locator objects containing only an HTML ID (locations.fragments) or a CSS selector (locations.cssSelector).

Changed

Shared

• TransformingResource now caches its content by default, as it is the correct behavior in most cases. Set cacheBytes = false explicitly to revert to the previous behavior.
• The previous PDF navigator was extracted in its own package to support third-party PDF engines. This is a breaking change if your app supported PDF, take a look at the migration guide.

Navigator

• The EPUB and PDF user preferences API got revamped. Take a look at the user guide and the migration guide to learn how to use it.
• Decoration.extras is now a Map<String, Any> instead of Bundle. You will need to update your app if you were storing custom data in extras, for example:

  val decoration = Decoration(...,
      extras = mapOf("id" to id)
  )
  
  val id = decoration.extras["id"] as? Long

Deprecated

Streamer

• The local HTTP server is not needed anymore to render EPUB publications. Take a look at the migration guide.

Fixed

Streamer

• Fixed parsing the table of contents of an EPUB 3 using NCX instead of a Navigation Document.

Navigator

• swift-toolkit#61 Fixed serving EPUB resources when the HREF contains an anchor or query parameters.
• Fixed emitting currentLocator with fixed layout EPUBs.
• Prevent refreshing an already loaded EPUB resource when jumping to a Locator in it.
• #86 Fixed page swipes while selecting text in an EPUB resource.
• The onTap event is not sent when an EPUB text selection is active anymore, to prevent showing the app bar while dismissing a selection.
• #76 Fixed EPUB fixed layout font size affected by device settings.
• Decoration objects are now properly comparable with equals().
• #292 Fix broken pagination when an EPUB uses overflow-x: hidden.

2.2.1

Resources

• Migration guide
• API Reference

Changelog

Fixed

Streamer

• #286 Fixed broken dependency to NanoHTTPD.

Migration Guide

This hotfix release fixes an issue pulling a third-party dependency (NanoHTTPD) from JitPack.

After upgrading, make sure to remove the dependency to NanoHTTPD from your app's build.gradle file before building:

-implementation("com.github.edrlab.nanohttpd:nanohttpd:master-SNAPSHOT") {
-    exclude(group = "org.parboiled")
-}
-implementation("com.github.edrlab.nanohttpd:nanohttpd-nanolets:master-SNAPSHOT") {
-    exclude(group = "org.parboiled")
-}

☝️ If you are stuck with an older version of Readium, you can use this workaround in your root build.gradle, as an alternative.

2.2.0

Resources

• Migration guide
• API Reference

Changelog

Added

Shared

• A new Publication.conformsTo() API to identify the profile of a publication.
• Support for the conformsTo RWPM metadata, to identify the profile of a Publication.

Navigator

• The PDF navigator now honors the publication reading progression with support for right-to-left and horizontal scrolling.
  • The default (auto) reading progression for PDF is top-to-bottom, which is vertical scrolling.
• A new convenience utility EdgeTapNavigation to trigger page turns while tapping the screen edges.
  • It takes into account the navigator reading progression to move into the right direction.
  • Call it from the VisualNavigator.Listener.onTap() callback as demonstrated below:

  override fun onTap(point: PointF): Boolean {
      val navigated = edgeTapNavigation.onTap(point, requireView())
      if (!navigated) {
          // Fallback action, for example toggling the app bar.
      }
      return true
  }

• The new Navigator.Listener.onJumpToLocator() API is called every time the navigator jumps to an explicit location, which might break the linear reading progression.
  • For example, it is called when clicking on internal links or programmatically calling Navigator.go(), but not when turning pages.
  • You can use this callback to implement a navigation history by differentiating between continuous and discontinuous moves.
• You can now disable the display cutouts padding in the EPUB navigator (contributed by @szymn).
  • This is useful when the navigator is not laid out full screen.
• (experimental) A new audiobook navigator based on Jetpack media2.
  • See the pull request #80 for the differences with the previous audiobook navigator.
  • This navigator is located in its own module readium-navigator-media2. You will need to add it to your dependencies to use it.
  • The Test App demonstrates how to use the new audiobook navigator, see MediaService and AudioReaderFragment.
• (experimental) The EPUB navigator now supports overridable drag gestures. See VisualNavigator.Listener.

Deprecated

Shared

• Publication.type is now deprecated in favor of the new Publication.conformsTo() API which is more accurate.
  • For example, replace publication.type == Publication.TYPE.EPUB with publication.conformsTo(Publication.Profile.EPUB) before opening a publication with the EpubNavigatorFragment.
• Link.toLocator() is deprecated as it may create an incorrect Locator if the link type is missing.
  • Use publication.locatorFromLink() instead.

Fixed

• Fix building with Kotlin 1.6.

Streamer

• Fixed the rendering of PDF covers in some edge cases.
• Fixed reading ranges of obfuscated EPUB resources.

Navigator

• Fixed turning pages of an EPUB reflowable resource with an odd number of columns. A virtual blank trailing column is appended to the resource when displayed as two columns.
• EPUB: Fallback on reflowable if the presentation.layout hint is missing from a manifest.
• EPUB: Offset of the current selection's rect to take into account the vertical padding.
• Improve backward compatibility of JavaScript files using Babel.
• #193 Fixed invisible <audio> elements.

2.1.1

Resources

• Migration guide
• API Reference

Changelog

Changed

Navigator

• Improve loading of EPUB reflowable resources.
  • Resources are hidden until fully loaded and positioned.
  • Intermediary locators are not broadcasted as currentLocator anymore while loading a resource.
  • Improved accuracy when jumping to the middle of a large resource.
  • EpubNavigatorFragment.PaginationListener.onPageLoaded() is now called only a single time, for the currently visible page.
  • VisualNavigator.Listener.onTap() is called even when a resource is not fully loaded.

Fixed

Navigator

• EpubNavigatorFragment's goForward() and goBackward() are now jumping to the previous or next pages instead of resources.
• #20 EPUB navigator stuck between two pages with vertical swipes.
• #27 Internal links break the EPUB navigator (contributed by @mihai-wolfpack).

2.1.0

Take a look at the migration guide

Added

Shared

• (alpha) A new Publication SearchService to search through the resources' content, with a default implementation StringSearchService.
• ContentProtection.Scheme can be used to identify protection technologies using unique URI identifiers.
• Link objects from archive-based publication assets (e.g. an EPUB/ZIP) have additional properties for entry metadata.

  "properties" {
      "archive": {
          "entryLength": 8273,
          "isEntryCompressed": true
      }
  }

Streamer

• EPUB publications implement a SearchService to search through the content.
• Known DRM schemes (LCP and Adobe ADEPT) are now sniffed by the Streamer, when no registered ContentProtection supports them.
  • This is helpful to present an error message when the user attempts to open a protected publication not supported by the app.

Navigator

• The EPUB navigator is now able to navigate to a Locator using its text context. This is useful for search results or highlights missing precise locations.
• Get or clear the current user selection of the navigators implementing SelectableNavigator.
• (alpha) Support for the Decorator API to draw user interface elements over a publication's content.
  • This can be used to render highlights over a text selection, for example.
  • For now, only the EPUB navigator implements DecorableNavigator, for reflowable publications. You can implement custom decoration styles with HtmlDecorationTemplate.
• Customize the EPUB selection context menu by providing a custom ActionMode.Callback implementation with EpubNavigatorFragment.Configuration.selectionActionModeCallback.
  • This is an alternative to overriding Activity.onActionModeStarted() which does not seem to work anymore with Android 12.
• (alpha) A new audiobook navigator based on Android's MediaSession.
  • It supports out-of-the-box media style notifications and background playback.
  • ExoPlayer is used by default for the actual playback, but you can use a custom player by implementing MediaPlayer.

OPDS

• New APIs using coroutines and R2's HttpClient instead of Fuel and kovenant (contributed by @stevenzeck).

Changed

• Upgraded to Kotlin 1.5.31 and Gradle 7.1.1

Streamer

• The default EPUB positions service now uses the archive entry length when available. This is similar to how Adobe RMSDK generates page numbers.
  • To use the former strategy, create the Streamer with: Streamer(parsers = listOf(EpubParser(reflowablePositionsStrategy = OriginalLength(pageLength = 1024))))

Navigator

• The order of precedence of Locator locations in the reflowable EPUB navigator is: text, HTML ID, then progression. The navigator will now fallback on less precise locations in case of failure.

LCP

• Migrated to Jetpack Room for the SQLite database storing rights and passphrases (contributed by @stevenzeck).
  • Note that the internal SQL schema changed. You will need to update your app if you were querying the database manually.

Fixed

Shared

• Crash with HttpRequest.setPostForm() on Android 6.
• HREF normalization when a resource path contains special characters.

Streamer

• EPUB style injection when a resource has a <head> tag with attributes.

Navigator

• When restoring a Locator, The PDF navigator now falls back on locations.position if the page= fragment identifier is missing.

OPDS

• Links in an OPDS 2 feed are normalized to the feed base URL.