Release notes iOS Framework 3

WARNING

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

Bugfixes

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

3.12.1 2025-03-06

API Docs

Bugfixes

• 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 with the page shadow animation in the Stack Renderer in iOS 18.3.
• 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 or :after pseudo selectors.
• Fixed issue with FileRandomAccessDataSource that in some rare cases failed to open files.

Improvements

• Improved building TTS SyncMediaTimeline performance.

3.12.0 2024-09-12

Bugfixes

• Fixed an issue that sometimes caused OnVisibleContentChangedListener.onVisiblePagesChanged(visiblePages:) 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.

Bugfixes

• 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.1 2024-03-15

Bugfixes

• Fixed an issue where EPUB MediaOverlays and W3C Audiobooks could not be played on iOS 17.4.

3.10.0 2024-03-07

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.

Bugfixes

• 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(at:completion:) returns data with size different from the range's size.
• Data is now not considered corrupt when RandomAccessDataSource.fetchChunk(at:completion:) returns Data with non-zero startIndex.

Improvements

• Improved load time of reflowable EPUBs with large cover images.

3.9.0 2023-12-08

New features

• 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.

Bugfixes

• 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 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.

3.8.0 2023-10-02

New features

• Added OnSyncMediaPlayerEventListener.onSegmentFinished which is fired when the player finishes playing a SyncMediaSegment.

Bugfixes

• Fixed a bug that prevented Youtube iframes to enter fullscreen.

  Note that on iPadOS, you need to set ReaderView.refreshOnResizeEnabled = false and call ReaderView.refresh() manually whenever needed. Otherwise, the page will reload when the video enters fullscreen, causing the video to unload.

• 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 where large audio files failed to play.

• 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. Specifically, non-english TTS voices on iOS 17.0 may skip segments completely when special quotation mark characters are encountered. This new option defaults to true.

Improvements

• Improved performance when loading reflowable EPUBs with large cover images.

3.7.0 2023-07-07

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 a bundled font file. This is done by using the static method PublicationStyleFontFace.fromAsset(family:fontStretch:fontStyle:fontWeight:mediaType:assetPath:).
• 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

New features

• Added includeContentLocationInPointerMoveEvents in EpubReaderPublicationOptions and PdfReaderPublicationOptions controlling if "pointermove" engine events should include the contentLocation property.
• Added a new function, EpubReaderPublication.fetchContentLocationFromHref(href:baseUrl:completion:). 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.delegate 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(event:), OnPointerEventListener.onPointerDown(event:) and OnPointerEventListener.onPointerUp(event:), 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(range:options:). 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(resourceUrl:completion:), or as the baseUrl with EpubReaderPublication.fetchContentLocationFromHref(href:baseUrl:completion:).
• Added the option highlightFirstWordOnSegmentActive in SyncMediaTtsContentBlockRendererOptions to highlight the first word immediately when a segment becomes active.

Bugfixes

• Scripted EPUBs adding <video> or <audio> elements with <source> child elements should now work correctly.
• Fixed an issue where SyncMediaPlayer.approximateElapsedTimeMs 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.
• Calling collapseToStart(completion:), collapseToEnd(completion:) or createRangeTo(endLocation:completion:) does not require you to hold a reference to the ContentLocation anymore.
• Fixed an issue where in some rare cases AVSpeechUtterance instances were spoken twice.
• 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.

Improvements

• Improved SyncMediaTimeline.fetchTimelinePosition(from:completion:) 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(config:completion:) and ReadingSystemEngine.loadPdf(config:completion:), 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

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 a mouse pointer over the content without pressing any mouse button.

Bugfixes

• 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.
• Fixed a bug causing memory leaks when using the ZipResourceProvider. This also affected calls to ReadingSystemEngine.loadEpub().

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 2022-02-23

New features

• Added a new API located at ContentLocation.contentResolver. Using this API, you can fetch the publication text content targeted by the ContentLocation. 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/https sources for audio and video elements in non-scripted content documents. Use EpubReaderPublicationOptions.remoteResourcesNonScriptedDocumentsOptions to allow these sources in the CSP.

  NOTE: In order to make media elements with http:// URLs work, you may need to edit your project configuration to allow non-secure loads in web content. See NSAppTransportSecurity for more information.

• 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 the reading position would sometimes be slow to update from sync media playback.
• Fixed that ReaderView.fetchRectsForVisibleContent sometimes merged too many lines.
• 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.

• Added ColibrioView.setOnBuildMenuCallback(callback:) allowing you to add custom context menu items on iOS 16.

Bugfixes

• Fixed an issue on iOS 16 causing ColibrioView.setAllowedCalloutActions(_:) to not remove the "Search the internet" item from the context menu when selecting text.
• Fixed an issue where ReaderView.canPerformGoTo incorrectly returned false.
• Due to issues with media streaming in iPadOS, the IEpubReaderPublicationOptions.enableMediaStreaming option is now ignored for that platform.
• 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.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 issues causing text and images to look blurry when zooming into publication content.

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:

let readerDocumentSearch = readingSystemEngine.readerDocumentSearch
let searchQuery = readerDocumentSearch.createTextQuery(queryString:"Paris")
let resultIterator = searchQuery.execute(readerView.readerDocuments)
// Take the next 10 search result items from the iterator.
switch await resultIterator.take(numberOfItems: 10) {
case .success(let firstTenResults):
    break
case .failure(let error):
    break
}
// Take all the remaining search result items from the iterator.
switch await resultIterator.takeRemaining() {
case .success(let remainingResults):
    break
case .failure(let error):
    break
}

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.

// Create the annotation layer used for highlighting search results.
var annotationLayer = readerView.createAnnotationLayer()
annotationLayer.options = ReaderViewAnnotationLayerOptions(layerStyle: ["mix-blend-mode": "multiply"])
annotationLayer.defaultAnnotationOptions = ReaderViewAnnotationOptions(rangeStyle: ["background-color": "#55deff"])
let readerDocumentSearch = readingSystemEngine.readerDocumentSearch
// Create the query
let searchQuery = readerDocumentSearch.createTextQuery(queryString: "Paris")
// Create a search agent that will highlight all matches using the annotation layer.
let searchAgent = readerDocumentSearch.createReaderViewSearchAgent(annotationLayer: annotationLayer)
searchAgent.setSearchQuery(query: 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
• All asynchronous methods that previously took a completion callback have now an async variant for iOS 13 and above.

Breaking changes since 3.0.0-rc.5

• Xcode 14 is now the minimum supported version.
• iOS 11 is now the minimum iOS version.
• 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.

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 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.createSyncMediaPlayer
  • EpubReaderPublication.createContentPositionTimeline
  • Renderer initializers
• TtsSyncMediaTimelineConfiguration.highlightLayer is now optional.

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.
• ReaderViewAnnotationLayer: The event OnAnnotationContextMenuListener.onContextMenuShown now fires as expected.
• 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 issues with ColibrioTtsSynthesizer implementation.
• Fixed an issue where destroying sync media player didn't stop playback.
• Fixed an issue where async methods could execute on the wrong thread and result in an error response.

3.0.0-rc.5 2022-06-27

Breaking changes

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

New features

• All asynchronous methods that previously took a completion callback have now an async variant for iOS 13 and above.

  For example:

  // With completion callback:
  readingSystemEngine.loadEpub(config: config) { result in
      switch result {
      case let .success(publication):
          // ...
      case .failure:
          // ...
      }
  }
  // Using async variant:
  let result = await readingSystemEngine.loadEpub(config: config)
  switch result {
  case let .success(publication):
      // ...
  case .failure:
      // ...
  }

• 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

• Added ColibrioReaderFramework.useTouchEventsInWebView. Set this option to true to force "touch" events to be used on iPhones and iPads instead of "pointer" events. This option should be enabled when integrating the Colibrio Reader Framework with a Flutter app.
• 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.

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.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.

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.
• Added ColibrioReaderFramework.version containing the version of the Colibrio Reader Framework.

Breaking changes

• Deprecated FileHandleRandomAccessDataSource. Please use FileRandomAccessDataSource instead.
• Deprecated ReadingSystemEngine.loadPublication() and the associated parameter types. Please use ReadingSystemEngine.loadEpub() or ReadingSystemEngine.loadPdf() instead.
• 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.
• Removed PublicationType, it was only intended for use internally.
• Closure passed to goTo(), next() and previous() is now optional.

Bugfixes

• Fixed an issue that in some cases caused EPUB Media Overlay playback to stop working on iOS 15.
• 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.