Android framework 3

This version is covered by warranty support until 2026-01-31.
It will however not be updated with new features.

3.12.2 (2025-05-16)

API Docs

Bug fixes

Fixed an issue where tables containing <colgroup> could sometimes cause blank pages during reflow.

3.12.1 (2025-03-06)

API Docs

Bug fixes

Fixed an issue where EPUBs missing the unique-identifier in the OPF file could not be loaded.
Fixed an issue where TTS playback could not be resumed after being paused due to interruption from a screen reader.
Fixed a memory leak issue in the Web framework running inside the WebView.
Fixed an issue where ReaderView.visiblePages sometimes did not update correctly.
Fixed a bug where OnSelectionChangedListener.onSelectionChanged wasn’t called if ReaderView.scriptedContentDocumentEventHandlersEnabled had been set to false.
Fixed a bug where CSS background images did not load if the selector for the style rule contained :before of :after pseudo selectors.

Improvements

Improved building TTS SyncMediaTimeline performance.

3.12.0 (2024-09-12)

Bug fixes

Fixed an issue that sometimes caused OnVisibleContentChangedListener.onVisiblePagesChanged to not be called.
Fixed an issue where VoiceOver was able to move focus into offscreen/hidden content on iOS 18.
Setting the option SyncMediaTtsTimelineContentTransformationOptions.normalizeQuotationMarks to true now converts all Unicode single quotation mark characters to the U+0027 Apostrophe (') character, while all Unicode double quotation marks are still converted to the U+0022 Quotation mark (") character.

3.11.0 (2024-05-22)

Important Security Fix

CVE-2024-4367
This release includes a crucial security fix for PDF.js. This vulnerability allowed arbitrary JavaScript execution inside the WebView through malicious PDF files. We strongly advise updating your reader applications as soon as possible to mitigate this issue. For more details, please refer to this article.

If you do not load PDF files with Colibrio, you are not affected by this vulnerability.

Bug fixes

Fixed an issue where CSS @import declarations could cause the framework to get stuck in an infinite recursion if an imported stylesheet contained an @import declaration pointing to itself.
Fixed a bug where the reading position might not be accurate when navigating to a locator range that partially intersected with the visible content.
Fixed an issue where EPUBs with an NCX navigation document would fail to load in some cases.

3.10.0 (2024-03-07)

Bug fixes

When streaming EPUBs over slow connections, initial aspect ratio calculations might take a long time, and led to navigation to wrongfully time out. In this version the engine instead waits for the aspect ratio calculations to finish.
Now an error will be logged when RandomAccessDataSource.fetchChunk returns data with size different from the range's size.

New features

Added a new option, SingleDocumentScrollRendererOptions.scrollBarPosition that allows you to choose if the scroll bar of a Renderer.SingleDocumentScroll should appear right next to the document content or at the edge of the ReaderView.
Added a new option, EpubContentProcessingOptions.skipUnusedImagesInScriptedPublicationCss in EpubReaderPublicationOptions. If set to true, background-images defined in a scripted publication CSS that aren't used by any element in the initial DOM will be skipped. This can significantly reduce load time and memory usage for some publications. This option should be set to false if the publication contains scripted content documents that inserts elements into the document dynamically.
Added a new option, PublicationStyleOptions.disableCssAnimations. If set to true, CSS animations and transitions are disabled in the publication.
Added ColibrioReadingSystemView.setOnStartActionMode which allows to customize the menu shown when text is selected.

Improvements

Improved load time of reflowable EPUBs with large cover images.

3.9.0 (2023-12-08)

Bug fixes

Fixed a memory leak related to resource providers when unloading a publication.
Fixed a bug with incorrect default cache size being used when creating a ZipResourceProvider.
Fixed an issue where floating elements with negative margins could overlap other publication content in reflowable EPUBs.
Fixed an issue where the aspect ratio of a PDF publication could be wrong.
Fixed an issue where the TtsUtteranceData.nodeData pointed to the parent of an <img> node instead of the <img> itself.
Fixed an issue where content documents with media type application/html was parsed as XHTML instead of HTML.
Fixed issue where TTS utterances were not preloaded correctly during playback.

Improvements

Required cache size when creating ZipResourceProvider.
New includePreContentBlocks and includeMathMlContentBlocks options added to EpubContentBlockOptions, accessible through EpubReaderPublicationOptions.contentBlockOptions. This affects how TtsUtteranceData objects are generated.
math element's alttext is now read aloud by the TTS.

3.8.0 (2023-10-02)

Bug fixes

Fixed a bug that could cause the initial ReaderView.goTo() or ReaderView.goToStart() to fail with the error message No renderer has been set using ReaderView.addRenderer() even though a renderer had been added.
Fixed an issue causing ContentLocation.fetchNavigationItemReferences to return an error on very old versions of Android WebView.
Added the option SyncMediaTtsTimelineContentTransformationOptions.normalizeQuotationMarks. If enabled, all special unicode quotation mark characters are replaced with the standard U+0022 Quotation mark ("). This may increase compatibility with some TTS Voices which may not work correctly otherwise. This new option defaults to true.

New features

Added OnSyncMediaPlayerEventListener.onSegmentFinished which is fired when the player finishes playing a SyncMediaSegment.
Exposed a setter (ColibrioReadingSystemView.setWebChromeClient) for WebChromeClient. You can use this to handle showing added custom views such as with Youtube fullscreen view. We show an example of how to handle such a case in this code snippet.

Improvements

Improved performance when loading reflowable EPUBs with large cover images.

3.7.0 (2023-07-07)

Bug fixes

Fixed an issue where scripted documents would not be able to load in very old versions of Android Webview.
Fixed an issues where ReaderViewTransformManager methods zoomToClientPosition and zoomToClientRect did not work in very old versions of Android Webview.

New features

Added a new listener OnSwipeNavigationGestureProgressChangedListener for the ReaderView. This will be triggered during a swipe navigation gesture. The event data SwipeNavigationGestureProgressEngineEventData contains the pending navigation action, i.e. if the outcome of the swipe navigation gesture is next page, previous page or stay on current page. It also contains data representing page swipe animation progress and related pointer movement.
Added support for loading a font from a URL. This is done by specifying srcUrl in PublicationStyleFontFace.
Added support for loading a font from an asset file. This is done by using the static method PublicationStyleFontFace.fromAsset.
Added the option EpubReaderPublicationCustomCssOptions.enableNormalizeCss controlling if the CSS reset/normalizer "normalize.css" should be injected into all reflowable EPUB content documents.

3.6.0 (2023-06-02)

Bug fixes

Scripted EPUBs adding <video> or <audio> elements with <source> child elements should now work correctly.
Fixed an issue where SyncMediaPlayer.approximateElapsedTime in some cases contained an invalid value when at the end of the timeline.
Fixed an issue where the wrong word would be highlighted when playing a TTS SyncMediaTimeline.
Fixed an issue where assigning an empty list to ReaderView.readerDocuments , caused wrong aspect ratio to be used when assigning a non-empty list later.

New features

Added includeContentLocationInPointerMoveEvents in EpubReaderPublicationOptions and PdfReaderPublicationOptions controlling if "pointermove" engine events should include the contentLocation property.
Added a new function, EpubReaderPublication.fetchContentLocationFromHref. This allows you to retrieve a content location for an href like “../chapter2.xhtml#title-2".
Added nodeData to TtsUtteranceData. This lets you investigate the Node data from where the TTS utterance was generated.
Deprecated ColibrioTtsSynthesizer.onBeforeSpeak and introduced ColibrioTtsSynthesizer.setColibrioTtsSynthesizerConfigurationListener in its place. The new ColibrioTtsSynthesizerConfigurationListener allows you to skip utterances in addition to customizing them.
Added support for font variants, i.e. font-weight, font-stretch and font-style, in the PublicationStyleFontFace option.
Added button to MouseEngineEventData. In OnMouseEventListener.onClick, OnPointerEventListener.onPointerDown and OnPointerEventListener.onPointerUp, this property indicates the device button whose state change caused the event to fire.
Added support for tree-structural pseudo-classes in publication css.
Added a new method SyncMediaPlayer.setPlaybackRange(). Use this new method to restrict playback to a specific timeline range. Use OnSyncMediaRangeEventListener to receive events related to playback ranges.
Added subtypes of SyncMediaObjectRef with more information about the data referenced by the SyncMediaSegment. You can access this information through SyncMediaSegmentData.refs.
Added ContentDocumentData.contentUrl which can be used to fetch the source file through ReaderPublication.fetchResourceData, or as the baseUrl with EpubReaderPublication.fetchContentLocationFromHref.
Added the option highlightFirstWordOnSegmentActive in SyncMediaTtsContentBlockRendererOptions to highlight the first word immediately when a segment becomes active.

Improvements

Improved SyncMediaTimeline.fetchTimelinePosition() for pre-paginated EPUBs when there is a media segment matching a parent node of the passed locator.
Clarified the error returned by ReadingSystemEngine.loadEpub and ReadingSystemEngine.loadPdf, with errorType now set to “WEBVIEW_VERSION_OUTDATED", when the WebView component is too old to run the Colibrio Reader Framework.

3.5.0 (2023-04-04)

Bug fixes

Fixed an issue where the OnSyncMediaPlayerEventListener.onSeeked callback would not fire.
Fixed an issue where calling ContentPositionTimeline.fetchContentLocationAsRange(pos, pos + 1) with a position at the start of a ContentDocument would return a collapsed ContentLocation instead of a range.

New features

Added an optional parameter snapToVisiblePagesBoundary for the SyncMediaPlayer methods seekToNextSegment and seekToPreviousSegment. When set to true, the seek operation will snap to visible pages boundary if the segment is partially outside the visible pages.
Added the new option ReaderViewOptions.rendererTransitionAnimationDurationMs. A renderer transition happens when the activeRenderer changes, or a refresh() call requires the activeRenderer to re-layout its content. Normally the renderer transition will start when visible content has finished rendering by fading it in over the old content. This new option controls the duration of the fade-in animation. The default value is null which will use a platform specific duration. Setting this value to 0 disables the animation.
Added the new option ReaderViewOptions.emitPointerMoveEventsOnHover. When set to true, “pointermove” engine events will be emitted when moving the mouse without pressing any button.

Improvements

PageProgressionTimeline now only recalculates on ReaderView and publication layout changes. Calling readerView.refresh(true) will also cause the PageProgressionTimeline to recalculate.

3.4.0 (2023-02-23)

New features

Added a now API located at ContentLocation.contentResolver. Using this API, you can fetch the publication text content targeted by the ContentLocaton. There are also methods for fetching the text immediately before and after the ContentLocation.
EpubContentPositionTimelineOptions has a new option fetchWithLowPriority. If set to true, all async operations in the ContentPositionTimeline will be executed when no other more prioritized tasks, like animation or document rendering, are running.
ISyncMediaTimeline has a new method called fetchTimelineRange() that can be used to fetch the corresponding SyncMediaTimelineRange for a SimpleLocatorData.
VisiblePageData has a new property, bundingClientRect, containing the bounding Rect of a rendered page relative to the ColibrioReadingSystemView.
A new method ReaderViewTransformModel.zoomToPublicationViewportRect translates and scales the publication so that the rectangle is centered in the ReaderView. The method uses the publication viewport as coordinate system.
Added support for remote http sources for audio and video elements in non-scripted content documents. Use EpubReaderPublicationOptions.remoteResourcesNonScriptedDocumentsOptions to allow these sources in the CSP.
NOTE: In order play media elements pointing to http/https URLs, you need to modify your AndroidManifest.xml to allow clear text HTTP traffic. See: https://stackoverflow.com/questions/45940861/android-8-cleartext-http-traffic-not-permitted/50834600#50834600 and https://developer.android.com/guide/topics/manifest/application-element#usesCleartextTraffic .
When an element is fragmented across pages, a new option EpubReflowPluginOptions.removeTopMarginsOnFragmentedElements determines if the top margin of the fragmented element should be carried over to subsequent pages.
Added Engine Events that can be used for tracking the state of <audio> and <video> elements inside publications. See the documentation in OnMediaElementEventListener for more information. You can add a new OnMediaElementEventListener using ReaderView.addOnMediaElementEventListener.
ReaderPublicationOptions has a new option preventDragAndDropActions. If set to true, all drag-and-drop actions originating from the publication content is prevented.

Bugfixes

Fixed a bug where invalid encryption XML files in EPUBs prevented them from loading.
Fixed an issue where scripted content-documents were unable to fetch files from the EPUB using XMLHttpRequest.
Fixed an issue where the reading position would sometimes be slow to update from sync media playback.
Fixed that ReaderView.fetchRectsForVisibleContent sometimes merged too many lines.
A bug in the Android WebView removed whitespace from clipboard data. To work around this, we changed how we get the copied text.
When any of the createSyncMediaTimeline results in a SyncMediaTimeline instance that have no segments, the error callback is called where errorType is set to INVALID_SYNC_MEDIA_TIMELINE. Previously, empty SyncMediaTimelines were allowed but caused various errors later when used with a SyncMediaPlayer.

Improvements

Added the method onlicenseReadingSessionPending() to OnLicenseEventListener, that will be called if there is a problem connecting to the license server. This event allows you to more quickly diagnose issues related to for example CSP policies that block access to the server.

3.3.0 (2022-11-22)

New features

Added a new password option to PdfPublicationOptions. This can be used to load password protected PDF publications.
TransformData now has the properties animating and userGestureActive. This is useful when listening on active transform changes to know if the TransformData represents an intermediate transform state of an ongoing animation, or a user gesture.
Added a new method ReaderView.fetchRectsForVisibleContent. This method returns a result set containing the positions and dimensions for all text line boxes and replaced elements, such as image and video elements. You can pass a locator to the method to only return rects that are inside that location.
This data can be used to implement reading rulers, popovers for a text selection or an element, and more.

Bugfixes

Fixed an issue where ReaderView.canPerformGoTo incorrectly returned false.
Fixed a timing issue where visiblePages were not updated when the visibleRangeChanged event was fired. The visiblePages and visibleRange are now in sync.

3.2.1 (2022-11-01)

Bugfixes

Moved Colibrio WebView asset files to the directory com_colibrio. This is to avoid asset files from Colibrio like index.html to interfere with asset files provided by the app.
Fixed an issue causing the app to crash when the WebView requested an encrypted resource for which no EncryptionMethod implementation was found.

3.2.0 (2022-10-05)

New features

Added EpubReaderPublicationOptions.splitTextOptions. This option object allows you to enable and configure splitting of very large text nodes in EPUB publications. When a single text node contains several thousand characters, enabling this option will reduce the time it takes to reflow such a publication.

Bugfixes

Fixed an issue causing ReaderDocumentSearch to not be exposed in the Android framework.

Improvements

Improved performance when pinch-zooming the ReaderView and when animating the ReaderView using the ReaderViewTransformManager.

3.1.1 (2022-09-16)

This change log describes the changes since 3.0.0-rc.5. Please check all 3.0.0 RC change logs for a complete list of changes since 2.x.

Major new features

ReaderDocumentSearch

This release includes new APIs for text search and highlighting search results in the ReaderView. You can access the new search API through readingSystemEngine.readerDocumentSearch.

This example shows how to search for the string “Paris” in all ReaderDocuments in a publication:

KOTLIN

val readerDocumentSearch = readingSystemEngine.readerDocumentSearch
val searchQuery = readerDocumentSearch.createTextQuery("Paris")
val resultIterator = searchQuery.execute(readerView.readerDocuments)

// Take the next 10 search result items from the iterator.
resultIterator.take(10)
  .onSuccess { firstTenResults ->           
  }

// Take all the remaining search result items from the iterator.
resultIterator.takeRemaining()
  .onSuccess { remainingResults ->
  }

You can now more easily highlight search result items in the ReaderView by using a ReaderViewSearchAgent. A ReaderViewSearchAgent uses a ReaderDocumentSearchQuery to search the visible ReaderDocuments in the ReaderView. For each found search match, the agent creates a ReaderViewAnnotation.

The agent will continue to search, add and remove ReaderViewAnnotations as necessary when the ReaderView is navigated.

KOTLIN

// Create the annotation layer used for highlighting search results.
val annotationLayer = readerView.createAnnotationLayer().also {
    it.options =
        ReaderViewAnnotationLayerOptions(
            layerStyle = mapOf("mix-blend-mode" to "multiply")
        )
    it.defaultAnnotationOptions = ReaderViewAnnotationOptions(
        rangeStyle = mapOf("background-color" to "#55deff")
    )
}

val readerDocumentSearch = readingSystemEngine.readerDocumentSearch

// Create the query
val searchQuery = readerDocumentSearch.createTextQuery("Paris")

// Create a search agent that will highlight all matches using the annotation layer.
val searchAgent = readerDocumentSearch.createReaderViewSearchAgent(annotationLayer)
searchAgent.setSearchQuery(searchQuery)

See the API Docs for ReaderDocumentSearch for more information.

Major new features since 2.x

The following new major features are presented in the 3.0.0-rc.2 change log:

Resource Providers
Suspend functions

Breaking changes since 3.0.0-rc.5

EncryptionMethod.decrypt now takes a third parameter XmlEncryptionEntry containing all information from the EPUB’s encryption.xml file related to the resource being decrypted. This makes it easier to implement support for additional DRM solutions.
The options parameter is no longer nullable in ResourceProvider.fetch and ResourceProvider.fetchMetadata.
ReaderViewAnnotation and ReaderViewAnnotationLayer are no longer generic types.
Including the android.Manifest.permission.INTERNET permission is now required for communication with Colibrio license servers to verify the Colibrio license. Failing to include this permission in your manifest file will result in a thrown exception.

Breaking changes since 2.x

Please see the breaking changes section in the 3.0.0-rc.2 change log.

New features

ReaderViewTransformManager: New methods added:
- zoomToClientRect : Allows you to zoom to a rectangle.
- zoomToPublicationViewportPosition: Allows to you to zoom to a position within the publication viewport. The publication viewport is the rectangle that contains the visible pages.
- zoomToClientPosition: Allows you to zoom to a position in client space, meaning you no longer need a pointer event to zoom. Replaces zoomToPointerEvent which is deprecated.
- removeActiveTransform: Allows you to remove the ReaderView's current active transform.
ReaderViewTransformManager: All transform changes can now be animated by passing a TransformAnimationOptions object to any of the different zoom methods. You can specify your desired easing function and the duration of the animation.
ContentLocation: Added the following new methods:
- createRangeTo
- fetchReaderDocuments
- contains
- equalsLocator
- intersects
- isAfter
- isBefore
It is now optional to specify publicationToken in the ReadingSessionOptions when loading a publication with ReadingSystemEngine.loadEpub or ReadingSystemEngine.loadPdf. If not specified, the framework will calculate an obfuscated publicationToken.
NavigationIntentEngineEventData now contains a readerDocumentIndexInSpine property indicating from where the navigation intent originated.
MouseEngineEventData (and its sub-types) now contains a buttons property that can be used to detect which mouse buttons that are pressed.
When a scripted EPUB content document tries to open a URL using window.open, the reading system will now emit a navigationIntent engine event with that URL.

Improvements

The options parameter is now optional in the following methods:
- ReadingSystemEngine.createZipResourceProvider
- EpubReaderPublication.createContentPositionTimeline
- EpubReaderPublication.createMediaOverlaySyncMediaTimeline
- Renderer constructors
TtsSyncMediaTimelineConfiguration.highlightLayer is now optional.
Update docs for RandomAccessDataSource.fetchChunk regarding thread safety.

Deprecated APIs

The following APIs still work, but will be removed in an upcoming major version of the framework:

ReaderViewOptions.gestureOptions.panZoom: The following options have been deprecated:
- maxPanOffsetVertical
- maxPanOffsetHorizontal
- maxScaleFactor

Please set these options using ReaderViewOptions.transformManagerOptions instead.

ReaderViewTransformManager: zoomToEventPosition has been deprecated. Please use zoomToClientPosition instead.

Bugfixes

ReaderViewAnnotationLayer: Fixed issues causing some ContentLocation to not render correctly.
ReadingSystemEngine: Loading the same publication twice now throws an Error.
<a> tags without href attribute no longer generates navigationIntent events.
ReaderViewOptions: gestureOptions.panZoom.maxPanOffsetHorizontal and gestureOptions.panZoom.maxPanOffsetVertical now works as expected for all paginated renderers.
ReaderViewGestureManager: Programmatically panning and zooming now works without an initial click or tap on the ReaderView.
window.devicePixelRatio is now modified in fixed-layout EPUB content documents so that the scaling applied to the content document within the ReaderView is taken into account. This fixes issues when scripted content documents calculate the width and height to use for <canvas> elements.
Fixed an issue where setting readerView.options in some cases did not work when modifying various gestureOptions.panZoom or gestureOptions.swipeNavigation options.
Fixed several issues with ColibrioTtsSynthesizer implementation.

3.0.0-rc.5 (2022-06-27)

Breaking changes

ResourceRequestOptions.range changed type from ByteRange to ByteRangeRequest, where end property is optional. When omitting the end property, the byte range ends at the end of the resource.

New features

When appending additional ReaderDocuments to the ReaderView using ReaderView.readerDocuments, the ReaderView will now more gracefully append those documents and internally trigger a "refresh" instead of clearing the ReaderView and forcing you to call goTo(). This new behavior allows you to avoid the “flash of white” that would occur otherwise.

Bugfixes

Fixed an issue where customizing the palette of an EPUB publication using PublicStyleOptions.palette could cause text to become transparent if the publication’s CSS contained invalid CSS color values.
ReaderView.readingPosition now returns “resolved” locators for EPUB in cases where ReaderView.goTo() was called with an incomplete EPUB CFI that was resolved using for example XML ID assertions.
Fixed a rare issue with EPUB Media Overlays where a <text> element in a .smil document could contribute to the SyncMediaTimeline for a specific content document, even if that content document’s manifest item in the .opf file did not reference the .smil file with the media-overlay attribute. This was never allowed by the Media Overlay specification and when this is encountered, the <text> element is ignored and an error is logged instead.

3.0.0-rc.4 (2022-05-18)

New features

The TTS SyncMediaTimeline no longer adds the text “Media element” or “Image alt text” when a media element is encountered. Instead, when you call ReaderPublication.createTtsSyncMediaTimeline(), you can set what text to prepend by setting the option contentTransformationOptions.imageAltTextPrefix.
Added the option preventDefaultContextMenu to EpubReaderPublicationOptions and PdfReaderPublicationOptions. If set to true, the reading system will prevent the default "right-click" and "long-press" context menus to be shown for publication content.

Bugfixes

Fixed a bug causing ReaderView.visibleRange to return an incorrect SimpleLocatorData when using FlipbookRenderer or SpreadSwipeRenderer while one of the visible pages was an “intentional empty page”.
The EPUB package meta element attribute rendition:spread now maps the deprecated value portrait to both as specified in the EPUB specification.
Fixed an issue with ContentPositionTimeline.fetchTimelineRange for EPUB. When passing a ContentLocation range that ended just before a media element, the returned result incorrectly included the media element.

3.0.0-rc.3 (2022-05-06)

Bugfixes

Fixed an issue where ReaderPublication.fetchResourceData used the wrong thread for fetching data.
Fixed an issue related to proguard-rules causing EncryptionMethod interface to not be visible.

3.0.0-rc.2

New features

Resource Providers

This release includes the new ResourceProvider interface and the ZipResourceProvider implementation.

The ResourceProvider interface allows you to load EPUBs in other ways than from the EPUB container file format. By creating your own implementation, you can load EPUBs that have already been extracted on the device or on a remote server.

The ZipResourceProvider implementation allows the framework to extract resources from EPUBs without using the Web framework implementation. This allows the framework to load resources more efficiently resulting in faster load times, especially noticeable on slower devices. You don’t need to change your EPUB loading code from using RandomAccessDataSource because the framework will use the new ZipResourceProvider internally.

Create ContentPositionTimeline instances quickly

Creating ContentPositionTimeline instances can take a significant amount of time on large publications. You can now work around this by getting ContentPositionTimeline.serializedData and saving it. The next time you create a ContentPositionTimeline, you can pass that data with EpubContentPositionTimelineOptions.serializedData to create the ContentPositionTimeline almost instantly.

The data in ContentPositionTimeline.serializedData is a base64 encoded string and is usually just a few hundred bytes large. It is unique to one publication and can safely be shared among clients.

When you pass serializedData to readerPublication.createContentPositionTimeline(), it will be validated to ensure it has the correct format and that it was created for the same publication. If validation fails, the serializedData is discarded and recalculated again.

Suspend functions

All asynchronous functions that previously required an onSuccess and onError callback now has a suspend variant as well to be used with coroutines. The suspend function returns a ColibrioResult that is either a Success or Error result.

KOTLIN

val result = readerPublication.createContentPositionTimeline(readerPublication.spine, options)
when (result) {
  is ColibrioResult.Success -> {
    // Do Something with `result.data`
  }
  is ColibrioResult.Error -> {
    // Do Something with `result.exception`
  }
}

// Alternatively
result.onSuccess {
    // Do something with `it: ContentPositionTimeline`
}.onError {
    // Do something with `it: ColibrioException`
}

Other new features

Added SyncMediaAudioRendererOptions.alignedSegmentSeekThresholdMs. This option controls how the SyncMediaAudioRenderer should treat gaps between two consecutive segments. If you hear many clicks, and cutoff words when playing back the audio in the publication, try increasing the value of this option.
Added SyncMediaTimeline.getApproximateOffsetMs(). Use it to get the approximate offset into the timeline in milliseconds from a SyncMediaTimelinePosition.
Added SyncMediaTimeline.getTimelinePositionFromApproximateOffsetMs(). Use it to get the timeline position that most closely matches an offset into the timeline.
You can now disable the pan/zoom reset when navigating a ReaderView by setting ReaderViewOptions.transformManagerOptions.removeTransformOnNavigation to false.
You can now allow non-scripted EPUBs to fetch remote resources such as fonts, videos or images from the Web. To enable this feature, see the option EpubReaderPublicationOptions.remoteResourcesNonScriptedDocumentsOptions

Breaking changes

The method EncryptionMethod.decrypt() is now a synchronous method. This change was needed due to how resources are requested from the Android WebView.
Deprecated ReadingSystemEngine.loadPublication() and the associated parameter types. Please use ReadingSystemEngine.loadEpub() or ReadingSystemEngine.loadPdf() instead.
The ReaderView methods goTo, next, previous without any callbacks arguments now maps to suspend functions. If you want to call these methods outside a Coroutine scope and don’t care about the result, please pass an empty closure like: readerView.next({}).
Removed XmlEncryptionEntry.cipherValueBase64.
Deprecated SyncMediaPlayer.getApproximateElapsedTimeMsForTimelinePosition(). Please use SyncMediaTimeline.getApproximateOffsetMs() instead.
Renamed SyncMediaTimelinePositionData.offsetMs to offsetWithinSegmentMs.
ReaderView.addRenderer() - Responsive view rule behavior has changed. When multiple renderers have been added and the ReaderView automatically picks which renderer to use it will now prioritize renderers that were added with a rule passed to addRenderer(). Note that renderers added without a rule will still be used by the ReaderView if no renderers with matching rules were added.
ReaderPublicationNavigationItemData.isLocatorInPublication has been renamed to isTargetingReaderDocumentInSpine.

Bugfixes

Fixed an issue where PDF pages sometimes rendered as blank pages if the rendering was interrupted by a ReaderView.refresh() or ReaderView.setOptions().
Fixed-layout EPUBs and PDFs are now centered in the ReaderView when ReaderViewOptions.ignoreAspectRatio is true.
Fixed an issue where <video> elements could shrink too much if it was wrapped inside a container element with a fixed height.
The playsinline attribute is now preserved for <video> elements. Previously it was always removed.
Fixed an issue where links in certain PDFs did not work.
Fixed an issue that caused some PDFs to never finish rendering and show a loader indefinitely.
Improved playback of EPUB Media Overlays when there are small seeks between segments.
Fixed an issue where EPUBs rendered with the wrong aspect ratio if document tag <meta name="viewport" ... contained extra spaces inside the content attribute.
Assigning a SyncMediaPlayer to ReaderView.syncMediaPlayer will no longer cause a synchronization event to fire if the ReaderView and the SyncMediaPlayer are already in sync.
Fixed an issue where EPUB Media Overlay playback could stall if there was a segment that did not reference an audio file.
When creating an annotation from a text selection, the annotation will now properly highlight the line boxes instead of the containing element.