Skip to main content
Skip table of contents

Android framework 4

4.6.0 (2025-10-07)

API Docs

New features

  • Added ReaderView.addOnRendererScrollHeightChangedEventListener(listener: OnRendererScrollHeightChangedEventListener) and ReaderView.removeOnRendererScrollHeightChangedEventListener(listener: OnRendererScrollHeightChangedEventListener) to manage listeners notified when a scrolling renderer’s scrollable height changes.

  • Added the option EpubContentProcessingOptions.addTabIndexToMediaElements. When set to true, tabindex="0" is added to non-interactive media elements (e.g., video, audio, img). This improves accessibility for screen reader and keyboard users by enabling focus and interaction with media elements.

Bugfixes

  • Fixed a memory leak that could occur when using ColibrioTtsSynthesizer to play a TTS SyncMediaTimeline.

  • Fixed an issue where certain elements were given tabindex="-1" when calling ReaderView.focusOnReadingPosition, preventing focus via standard keyboard navigation (e.g., Tab).

  • Fixed an issue where publication content that changed overflow-x styling could break reflow due to browsers implicitly setting overflow-y to auto.

  • Fixed an issue where pointer events on a ReaderViewAnnotation rendered in Renderer.SingleDocumentScroll reported an incorrect event.target.frameworkComponent.

  • Fixed an issue where TtsUtteranceData.nodeData referenced the parent element for elements with alt/alttext (e.g., <math> with alttext), instead of the element itself.

4.5.0 (2025-08-29)

API Docs

New features

  • Added two new options, injectionPointStartUnprocessed and injectionPointEndUnprocessed, to EpubReaderPublicationCustomCssOptions.

    • CSS injected using these options is not affected by publicationStyleOptions. This is useful for cases such as customizing the ::selection pseudo-element without being overridden by the palette option, for example.

Bugfixes

  • Fixed an issue where ReaderView did not stay synchronized with SyncMediaPlayer when seeking to the end of the timeline.

  • Fixed an issue where a loader briefly disappeared during navigation.

  • Fixed an issue where SyncMediaPlayer.readerViewSynchronizationWaitBehavior set to WAIT_OUTSIDE_ADJACENT did not always allow playback when the timeline position was within the previous or next spread.

  • Fixed an issue where OnSelectionChangedListener.onSelectionChanged() was not invoked when selecting content in the first reader document.

  • Fixed an issue where ReaderView.focusOnReadingPosition() sometimes focused on the old readingPosition when called right after ReaderView.goTo().

  • Fixed an issue where reflowing EPUB content into pages could result in an error when elements with position: absolute were nested inside inline elements with position: relative.

4.4.2 (2025-07-25)

API Docs

Bugfixes

  • Fixed an issue that prevented EPUB files larger than 4.2 GB from loading correctly.

  • Fixed an issue where audio playback might stop before reaching the end of the timeline when using ColibrioAudioPlayer.

  • Playback is now properly paused when temporarily interrupted by the system (e.g., when audio focus is temporarily lost with "can duck").

4.4.1 (2025-07-04)

API Docs

Bugfixes

  • Fixed a bug where performing a goTo() while using the Renderer.SingleDocumentScroll could result in a readingPosition that differed from the one passed to goTo().

  • Fixed an issue where iframes pointing to http or https URLs would cause the entire content document to become sandboxed, even when EpubReaderPublicationOptions.remoteResourcesNonScriptedDocumentsOptions.policyType was set to ALLOW_ALL or WHITELIST. This prevented embedded YouTube iframes from functioning correctly, for example.

4.4.0 (2025-06-12)

API Docs

New features

  • Added new options under ReaderViewOptions.pageContainerOptions.titleOptions that can be used to configure the title attribute on page container <iframe> elements.

Bugfixes

  • Fixed an issue where the CSS at-rules @container, @layer, and @scope were not processed correctly.

  • Fixed an issue where ContentBlockTarget.getCharLength() could return the wrong length.

  • Fixed an issue where element vertical padding sometimes caused vertical overflow scroll in reflowable EPUBs.

  • Fixed an issue where pages ending with <br> elements somtimes caused vertical overflow scroll in reflowable EPUBs.

  • Fixed issue when using the native ColibroAudioPlayer together with the SyncMediaPlayer for EPUB Media Overlays: in some cases, audio did not pause precisely at the end of the visible range when SyncMediaPlayer.readerViewSynchronizationWaitBehavior was set to WAIT_OUTSIDE_VISIBLE.

  • Fixed an issue where SyncMediaPlayer.waitingForMediaObjectRenderers and SyncMediaPlayer.waitingForViewSynchronization sometimes had wrong values.

4.3.0 (2025-05-08)

API Docs

New features

  • Added support for dividing AudioTimelines into sections when using the native ColibrioAudioPlayer for playback. This allows you to customize how Audio playback progress is shown in your app and in the media session notification. You can for example show progress per chapter instead of the whole publication. See MediaSessionTimelineMode for more information.

  • Added the new option activeElementStylesOverride to EpubReaderPublicationOptions.mediaOverlayOptions. It allows you to override the CSS for the active element when playing EPUB MediaOverlays, without being affected by publicationStyleOptions such as paletteOptions.

  • Added a new option PdfReaderPublicationOptions.addColibrioSpecificFragmentSelectorData. Setting it to true will add a new Colibrio specific parameter, colibrio-pagerects, to the Locator’s selector. This allows the selector to represent multiple rectangles. This is useful when adding text selection highlights for example.

Deprecations

The following methods have been deprecated. They will be removed in the next major version of the framework.

  • Deprecated ColibrioAudioPlayer.setMediaSessionMetadata. Use ColibrioAudioPlayer.mediaSession.metadata instead.

  • Deprecated ColibrioAudioPlayer.setMediaCommands. Use ColibrioAudioPlayer.mediaSession.mediaCommands instead.

Bugfixes

  • Fixed an issue where PublicationStyleOptions.fontSizeScaleFactor had no effect in some reflowable EPUBs.

  • Fixed an issue where EpubReflowPluginOptions.customForcedPageBreak only worked if all its options was specified.

  • Fixed an issue where the playback cache was not cleaned up when using the native ColibrioAudioPlayer.

Improvements

  • Setting the option PublicationStyleOptions.removePublicationDefinedHorizontalPageMargins to true, will now apply margin removal on more publications where it previously bailed out.

  • Adds tabindex="0" to overflow scroll elements so that they can be scrolled with the keyboard as required by WCAG.

  • Added tabindex="0" to <iframe> elements to allow keyboard navigation to focusable elements inside the iframe in Safari.

  • Added the new property mediaSession: ColibrioMediaSession to the ColibrioAudioPlayer. It allows you to configure which playback controls are available and how metadata information is presented in the media session notification.

4.2.1 (2025-04-07)

API Docs

Bugfixes

  • Fixed an issue introduced in version 4.2.0 where PublicationStyleOptions.fontSizeScaleFactor had no effect in some EPUBs.

4.2.0 (2025-03-26)

API Docs

New features

  • Added a new method setContentSelection to VisiblePage.

  • Added new options, typographyResetOptions.removePublicationDefinedFontSizes and typographyResetOptions.removePublicationDefinedLineHeights to PublicationStyleOptions.

Bugfixes

  • Fixed an issue where paragraph text indendation was sometimes applied on fragmented paragraphs.

  • Fixed an issue where page content with negative margins could appear outside of the page if PublicationStyleOptions.removePublicationDefinedHorizontalPageMargins was true.

Improvements

  • Fixed the event order when navigating in the Renderer.SingleDocumentScroll to make it more consistent with how the other renderers work. The listener method OnReadingPositionChangedListener.onReadingPositionChanged will be called before OnNavigationStateChangedListener.onNavigationEnded is called.

4.1.0 (2025-02-28)

API Docs

New features

  • Added a new option publicationStyleOptions.removePublicationDefinedHorizontalPageMargins. When enabled, it does a best effort try to remove page margins defined in the publication CSS.

  • Added a new method, ReaderPublicationNavigation.getNavigationItemById.

Bugfixes

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

  • Fixed a bug where VisiblePage.boundingClientRect did not update when activeTransform changed, such as while zooming and panning.

  • Fixed a rare crash that could occur when assigning an empty list to ReaderView.readerDocuments.

Improvements

  • Improved building TTS SyncMediaTimeline performance.

4.0.0 (2025-02-04) - Changes since 3.12.0

API Docs

Overview

We are excited to announce native audiobook support.

This version of the framework enables you to load EPUBs with Media Overlays in audio-only mode, with the flexibility to synchronize with the ReaderView at any time. It also supports playback of W3C Audiobooks, whether zipped as an LPF package or "un-packaged" for streaming over HTTP. Additional format support will be added in future releases.

Check out the AudioReadingSystemEngine API documentation for how to configure your app to use the new audio playback capability. Sample applications will be available soon.

Major new features

  • New AudioReadingSystemEngine and ColibrioAudioPlayer class that handles playback of audio using the ExoPlayer library.

    • Support for audio playback of W3C Audiobooks and EPUB with Media Overlays.

    • Audio playback is managed in a service, allowing it to continue in the background.

    • Full integration with the Android’s MediaSession features. Provides playback control from any connected device that supports MediaSession controls, such as Android Auto, Wear OS and more.

  • The Content Block API is now available. This new API provides programmatic access to a simplified representation of a publication's structure, such as the HTML elements in an EPUB.

  • Document Sectioning for reflowable EPUB content-documents. When enabled, reflowable documents can be split into sections prior to reflowing. This can greatly increase performance for publications with long content documents. You can control where and how often these breaks occur using options of course. We recommend that you enable Document Sectioning as a default.

  • New mitigation options for horizontally overflowing table and math elements let you wrap these elements in scroll containers. Previously these would have been shrunken to fit the page width, affecting legibility and accessibility. Note that we have changed the default behaviour to scroll instead of shrink. Read more in the Breaking Changes section below.

New features

  • Added the new option EpubContentProcessingOptions.horizontalOverflowMitigationMinFontSize. When a word is too wide to fit on the page, it can either be broken into multiple lines or scaled down. This option sets the minimum font size to scale down to. If scaling is not enough to fit the word, the style overflow-wrap: break-word; will also be applied, allowing the word to be broken up over more than one line.

  • Added the new option EpubContentProcessingOptions.horizontalOverflowMathMLStrategy controlling if <math> elements too wide to fit in the page should be scaled down to fit, or horizontally scrollable.

  • Added the new option EpubContentProcessingOptions.horizontalOverflowTableStrategy controlling if table elements too wide to fit in the page should be scaled down to fit, or horizontally scrollable.

  • Added the new option EpubContentProcessingOptions.verticalOverflowMitigationStrategy controlling if a reflowed page should be allowed to vertically scroll if all content does not fit.

  • Added the new option EpubReflowOptions.removeBottomMarginsOnFragmentedElements controlling if the bottom margin on fragmented elements should be removed or kept.

  • Added support for iframes added by scripts in content documents.

  • Added a new option TextSearchQueryOptions.ignoreDiacritics, allowing searches to match text with or without diacritics.

  • Added PdfReaderPublicationOptions.textLayerOptions.customCss, which allows injecting custom CSS into the text layer of PDF pages.

  • Added two new options: EpubReaderPublicationOptions.allowAudioElementAutoplay and EpubReaderPublicationOptions.allowVideoElementAutoplay.

  • Added ReaderViewAnnotationLayer.refreshAnnotations(), allowing annotations to be refreshed programmatically.

  • Introduced OnClipboardEventListener, with the onCopy event firing when a user copies content from a publication to their clipboard. Use ReaderView.addOnClipboardEventListener to receive this event.

  • Added ReaderDocument.fetchLocatorForEntireDocument().

  • The following options in ReaderViewAnnotationOptions now supports space-separated class names:

    • containerClassName

    • positionClassName

    • rangeClassName

  • Added the new option PublicationStyleOptions.wordSpacing, allowing modification of word spacing in reflowable EPUB documents.

  • Added the new option PublicationStyleOptions.letterSpacing, allowing modification of letter spacing in reflowable EPUB documents.

  • Renderer.SpreadSwipe now supports switching from two-page spreads to a single centered page when the EPUB author has configured the document with rendition:page-spread-center or spread-none.

  • Added the new option ReaderViewOptions.contentDisplayAreaOptions, controlling how the available display area is utilized by publication content.

  • Added ContentPositionTimeline.fetchTimelinePositions and ContentPositionTimeline.fetchTimelinePositionsForNavigationItems which can be used to fetch multiple positions in one call.

  • You can now manage ReaderPublication's storage state, such as localStorageand sessionStorage for scripted EPUB content documents. Use EpubReaderPublication.readerPublicationStorage.getStorageArea() to get a ReaderPublicationStorageArea that can be used for adding, updating and removing items from storages.

Known issues

The ColibrioNotificationManager posts media notifications. These notifications are exempt from the requirement (introduced in Android 13) to get the user’s permission. If you do not declare the android.permission.POST_NOTIFICATIONS permission in your app and get this lint error

CODE 
Error: When targeting Android 13 or higher, 
posting a permission requires holding the POST_NOTIFICATIONS permission 
(usage from com.colibrio.readingsystem.audio.service.ColibrioNotificationManager) 
[NotificationPermission]

then add this rule to your lint configuration file:

CODE 
<?xml version="1.0" encoding="UTF-8"?>
<lint>
   <issue id="NotificationPermission">
        <ignore regexp="com.colibrio.readingsystem.audio.service.ColibrioNotificationManager" />
    </issue>
</lint>

Breaking changes

  • Minimum supported Android WebView version is now Chrome 62.

  • Minimum supported Android version is now 7, (Android SDK 24).

  • Upgraded Android Gradle Plugin to 8.3.2, and Kotlin Gradle Plugin to 1.9.25.

  • ResourceProvider interface changes:

    • Introduced new baseUrl property

    • fetch and fetchMetadata now takes a URL instead of a path.

    • Error handling updated to distinguish between recoverable and non-recoverable errors.

  • ReaderView.visiblePages now returns List<VisiblePage> instead of List<VisiblePageData>

  • SyncMediaPlayer.approximateElapsedTime has been renamed to SyncMediaPlayer.approximateElapsedTimeMs.

  • ContentLocation.fetchNavigationItemReferences onSuccess callback is now called with FetchNavigationItemReferencesResult instead of FetchNavigationItemReferencesResultData. Properties in FetchNavigationItemReferencesResult return List<ReaderPublicationNavigationItemReference> instead of List<ReaderPublicationNavigationItemReferenceData>.

  • The following suspend functions now return a ColibrioResult object:

    • ContentLocationContentResolver.fetchTextContent

    • ContentLocationContentResolver.fetchTextContentAfter

    • ContentLocationContentResolver.fetchTextContentBefore

  • Removed deprecated property ColibrioTtsSynthesizer.onBeforeSpeak

  • The new options EpubReflowOptions.removeBottomMarginsOnFragmentedElements and EpubReflowOptions.removeTopMarginsOnFragmentedElements default to true. This may cause content to appear closer to the top and bottom edge of the page compared to previous Colibrio Reader Framework versions. Set these options to false to keep the old behavior.

  • The new options EpubContentProcessingOptions.horizontalOverflowMathMLStrategy and EpubContentProcessingOptions.horizontalOverflowTableStrategy default to EpubContentOverflowStrategy.SCROLL in order to improve legibility and accessibility. This will introduce horizontal scrolling within the page when the table or math elements do not fit horizontally. Set this option to EpubContentOverflowStrategy.SCALE to keep the old behavior.

  • The new option EpubContentProcessingOptions.horizontalOverflowMitigationMinFontSize defaults to 16 pixels in order to improve accessibility. This may cause long words be broken up over more than one line. Set this option to 0 to keep the old behavior.

  • The new option EpubContentProcessingOptions.verticalOverflowMitigationStrategy defaults to EpubContentOverflowStrategy.SCROLL in order to improve accessibility. This will introduce vertical scrolling within a page if not all content fits. Set this option to EpubContentOverflowStrategy.SCALE to keep the old behavior.

  • In ReaderViewOptions, forcePageAspectRatio and defaultPageAspectRatio have been removed. Use ReaderViewOptions.contentDisplayAreaOptions instead.

  • Subtypes of the sealed classes EpubPageCountEstimationAlgorithm and EpubDocumentSectioningAlgorithm are now declared as data class, or data object instead of class.

Deprecations

The following methods and properties have been deprecated. They will continue to work in all 4.x.x versions

  • ReaderPublicationNavigationData is deprecated. Replaced by ReaderPublicationNavigation.

  • ReaderPublicationNavigationCollectionData is deprecated. Replaced by ReaderPublicationNavigationCollection.

  • ReaderPublicationNavigationItemData is deprecated. Replaced by ReaderPublicationNavigationItem.

  • locator in ReaderPublicationNavigationItem is deprecated. Instead, use the ReaderPublicationNavigationItem directly with methods that support locator.

  • VisiblePageData is deprecated. Replaced by VisiblePage.

  • ReaderView.fetchRectsForVisibleContent is deprecated. Replaced by VisiblePage.fetchRectsForVisibleContent.

  • Setter for ReaderView.syncMediaPlayer is deprecated. Use setSyncMediaPlayer(SyncMediaPlayer, SyncMediaReaderViewSynchronizationMethod) instead.

  • SyncMediaPlayer.playing is deprecated. Use !paused && ready instead.

  • SyncMediaPlayer.approximateElapsedTime is deprecated. Replaced by SyncMediaPlayer.approximateElapsedTimeMs.

  • FetchNavigationItemReferencesResultData is deprecated. Replaced by FetchNavigationItemReferencesResult.

  • ReaderPublicationNavigationItemReferenceData is deprecated. Replaced by ReaderPublicationNavigationItemReference.

  • VisiblePageData is deprecated. Replaced by VisiblePage.

  • The renderer option ignoreAspectRatio has been deprecated. It will continue to work until its removal in version 5.0.0 of the framework. Please use ReaderViewOptions.contentDisplayAreaOptions with type set to FILL instead.

  • ReadingSystemEngine.createZipResourceProvider is now deprecated. Use ZipResourceProvider.create(dataSource: RandomAccessDataSource, zipResourceProviderOptions: ZipResourceProviderOptions) instead.

  • ZipResourceProvider.create(dataSource: RandomAccessDataSource, serializedZipArchiveInformation: ByteArray, chunkCacheSize: Int) is now deprecated. Use ZipResourceProvider.create(dataSource: RandomAccessDataSource, zipResourceProviderOptions: ZipResourceProviderOptions) instead.

Bug fixes

  • Fixed an issue that sometimes caused OnVisibleContentChangedListener.onVisiblePagesChanged to not be called.

  • Fixed an issue where publicationHashSignature was calculated differently compared to the Web framework.

  • Improvements and bugfixes when applying page-breaks inside tables.

  • Fixed an issue where the reflow engine would fail to properly measure elements that had a transform applied to them, causing inaccurate page-breaks.

  • Fixed an issue where page-breaks were not applied correctly for pre-formatted text, like code examples.

  • Fixed an issue where reflow engine did not calculate margin-collapse rules correctly.

  • Fixed Reflow Engine issues that in some cases caused page breaks to be applied at wrong positions.

  • Annotation’s rendered positions now updates correctly inside scrolling containers.

  • Fixed issues that could cause images to get incorrect aspect ratios.

  • Fixed a bug where reading position might not be accurate when navigating to an annotation spanning two pages.

  • Fixed a bug where the “keydown” engine event’s modifiers.shift was false, even if shift was pressed.

  • Fixed an issue where calling ReaderView.focusOnReadingPosition() sometimes had no effect.

  • Fixed an issue where TTS playback could not be resumed after being paused due to an interruption from the system.

  • ContentLocation.contentResolver methods now works correctly for ranges spanning multiple EPUB documents.

  • ContentLocation.fetchNavigationItemReferences now functions correctly for locator ranges spanning multiple EPUB documents.

  • Fixed an issue where EPUBs missing the unique-identifier in the OPF file could not be loaded.

  • Fixed an issue where ReaderView.visiblePages sometimes did not update correctly.

Improvements

  • Renderer.SpreadSwipe and Renderer.SinglePageSwipe are now able to use all available display area when displaying publications containing fixed-layout documents with varying dimensions, such as mixed portrait and landscape documents.

  • ContentPositionTimeline methods are now many times faster.

  • Updated PDF.js to version 4.8.73.

4.0.0 (2025-02-04) - Changes since 4.0.0-rc.5

API Docs

New features

  • Added ContentPositionTimeline.fetchTimelinePositions and ContentPositionTimeline.fetchTimelinePositionsForNavigationItems

  • You can now manage ReaderPublication's storage state, such as localStorageand sessionStorage for scripted EPUB content documents. Use EpubReaderPublication.readerPublicationStorage.getStorageArea() to get a ReaderPublicationStorageArea that can be used for adding, updating and removing items from storages.

  • Loading audiobooks with a ZipResourceProvider does not require the ReadingSystemEngine anymore. You can now create a ZipResourceProvider using ZipResourceProvider.create(dataSource: RandomAccessDataSource, zipResourceProviderOptions: ZipResourceProviderOptions).

Breaking changes

  • Minimum supported Android WebView version is now Chrome 62.

  • Minimum supported Android version is now 7, (Android SDK 24).

  • Changed the file you need to reference in your lint.xml file to ignore the missing notification lint error. You need to replace ColibrioMediaBrowserService with ColibrioNotificationManager. The new script looks like this:

    CODE 
    <?xml version="1.0" encoding="UTF-8"?>
<lint>
   <issue id="NotificationPermission">
        <ignore regexp="com.colibrio.readingsystem.audio.service.ColibrioNotificationManager" />
    </issue>
</lint>

Deprecations

  • ReadingSystemEngine.createZipResourceProvider is now deprecated. Use ZipResourceProvider.create(dataSource: RandomAccessDataSource, zipResourceProviderOptions: ZipResourceProviderOptions) instead.

  • ZipResourceProvider.create(dataSource: RandomAccessDataSource, serializedZipArchiveInformation: ByteArray, chunkCacheSize: Int) is now deprecated. Use ZipResourceProvider.create(dataSource: RandomAccessDataSource, zipResourceProviderOptions: ZipResourceProviderOptions) instead.

Bug fixes

  • Fixed issues where synchronization didn’t work in some books.

  • Fixed issue with maintaining audio focus properly.

  • Fixed an issue where EPUBs missing the unique-identifier in the OPF file could not be loaded.

  • Fixed issue with updating media session metadata and commands.

  • Fixed an issue where ReaderView.visiblePages sometimes did not update correctly.

Improvements

  • ContentPositionTimeline methods are now many times faster.

  • Updated PDF.js to version 4.8.73.

4.0.0-rc.5 (2024-11-19)

API Docs

Breaking changes

  • In ReaderViewOptions, forcePageAspectRatio and defaultPageAspectRatio have been removed. Use ReaderViewOptions.contentDisplayAreaOptions instead.

  • ContentLocation.fetchContentBlockTargets returns a list of ContentBlockTarget now instead of a list of ContentBlockTargetData. ContentBlockTarget allows you direct access to the target ContentBlock.

  • Subtypes of the sealed classes EpubPageCountEstimationAlgorithm and EpubDocumentSectioningAlgorithm are now declared as data class, or data object instead of class.

Deprecations

  • The renderer option ignoreAspectRatio has been deprecated. It will continue to work until its removal in version 5.0.0 of the framework. Please use ReaderViewOptions.contentDisplayAreaOptions with type set to FILL instead.

Improvements

  • Renderer.SpreadSwipe and Renderer.SinglePageSwipe are now able to use all available display area when displaying publications containing fixed-layout documents with varying dimensions, such as mixed portrait and landscape documents.

New features

  • Added the new option PublicationStyleOptions.wordSpacing, allowing modification of word spacing in reflowable EPUB documents.

  • Added the new option PublicationStyleOptions.letterSpacing, allowing modification of letter spacing in reflowable EPUB documents.

  • Renderer.SpreadSwipe now supports switching from two-page spreads to a single centered page when the EPUB author has configured the document with rendition:page-spread-center or spread-none.

  • Added the new option ReaderViewOptions.contentDisplayAreaOptions, controlling how the available display area is utilized by publication content.

Bugfixes

  • ContentLocation.fetchNavigationItemReferences now functions correctly for locator ranges spanning multiple EPUB documents.

  • Fixed a memory leak issue in the Web framework running inside the WebView.

4.0.0-rc.4 (2024-10-17)

API Docs

New features

  • Added ReaderDocument.fetchLocatorForEntireDocument().

  • The following options in ReaderViewAnnotationOptions now supports space-separated class names:

    • containerClassName

    • positionClassName

    • rangeClassName

Bugfixes

  • Fixed an issue introduced in 4.0.0-rc.2 where several ContentLocation methods returned incorrect results.

  • Fixed an issue where TTS playback could not be resumed after being paused due to an interruption from the system.

  • ContentLocation.contentResolver methods now works correctly for ranges spanning multiple EPUB documents.

4.0.0-rc.3 (2024-10-11)

API Docs

Major New Features

  • The Content Block API is now available. This new API provides programmatic access to a simplified representation of a publication's structure, such as the HTML elements in an EPUB. This flexible API is used internally for features like ReaderDocumentSearch and TtsSyncMediaTimeline.

Breaking Changes

  • Upgraded Android Gradle Plugin to 8.3.2, and Kotlin Gradle Plugin to 1.9.25.

New Features

  • Added a new option TextSearchQueryOptions.ignoreDiacritics, allowing searches to match text with or without diacritics.

  • Added PdfReaderPublicationOptions.textLayerOptions.customCss, which allows injecting custom CSS into the text layer of PDF pages.

  • Added two new options: EpubReaderPublicationOptions.allowAudioElementAutoplay and EpubReaderPublicationOptions.allowVideoElementAutoplay.

  • Added ReaderViewAnnotationLayer.refreshAnnotations(), allowing annotations to be refreshed programmatically.

  • Added the new option ColibrioMediaCommands.seekBarEnabled to enable or disable seeking in the media notification.

  • Introduced OnClipboardEventListener, with the onCopy event firing when a user copies content from a publication to their clipboard. Use ReaderView.addOnClipboardEventListener to receive this event.

Bug Fixes

  • Fixed a bug where the “keydown” engine event’s modifiers.shift was false, even if shift was pressed.

  • Fixed an issue where calling ReaderView.focusOnReadingPosition() sometimes had no effect.

4.0.0-rc.2 (2024-08-29)

API Docs

These release notes describes the changes since version 3.11.0

Overview

We are excited to announce native audiobook support.

This version of the framework enables you to load EPUBs with Media Overlays in audio-only mode, with the flexibility to synchronize with the ReaderView at any time. It also supports playback of W3C Audiobooks, whether zipped as an LPF package or "un-packaged" for streaming over HTTP. Additional format support will be added in future releases.

Check out the AudioReadingSystemEngine API documentation for how to configure your app to use the new audio playback capability. Sample applications will be available soon.

Major new features

  • New AudioReadingSystemEngine and ColibrioAudioPlayer class that handles playback of audio using the ExoPlayer library.

    • Support for audio playback of W3C Audiobooks and EPUB with Media Overlays.

    • Audio playback is managed in a service, allowing it to continue in the background.

    • Full integration with the Android’s MediaSession features. Provides playback control from any connected device that supports MediaSession controls, such as Android Auto, Wear OS and more.

  • Document Sectioning for reflowable EPUB content-documents. When enabled, reflowable documents can be split into sections prior to reflowing. This can greatly increase performance for publications with long content documents. You can control where and how often these breaks occur using options of course. We recommend that you enable Document Sectioning as a default.

  • New mitigation options for horizontally overflowing table and math elements let you wrap these elements in scroll containers. Previously these would have been shrunken to fit the page width, affecting legibility and accessibility. Note that we have changed the default behaviour to scroll instead of shrink. Read more in the Breaking Changes section below.

New features

  • Added the new option EpubContentProcessingOptions.horizontalOverflowMitigationMinFontSize. When a word is too wide to fit on the page, it can either be broken into multiple lines or scaled down. This option sets the minimum font size to scale down to. If scaling is not enough to fit the word, the style overflow-wrap: break-word; will also be applied, allowing the word to be broken up over more than one line.

  • Added the new option EpubContentProcessingOptions.horizontalOverflowMathMLStrategy controlling if <math> elements too wide to fit in the page should be scaled down to fit, or horizontally scrollable.

  • Added the new option EpubContentProcessingOptions.horizontalOverflowTableStrategy controlling if table elements too wide to fit in the page should be scaled down to fit, or horizontally scrollable.

  • Added the new option EpubContentProcessingOptions.verticalOverflowMitigationStrategy controlling if a reflowed page should be allowed to vertically scroll if all content does not fit.

  • Added the new option EpubReflowOptions.removeBottomMarginsOnFragmentedElements controlling if the bottom margin on fragmented elements should be removed or kept.

  • Added support for iframes added by scripts in content documents.

Known issues

The ColibrioMediaBrowserService posts media notifications. These notifications are exempt from the requirement (introduced in Android 13) to get the user’s permission. If you do not declare the android.permission.POST_NOTIFICATIONS permission in your app and get this lint error

CODE 
Error: When targeting Android 13 or higher, 
posting a permission requires holding the POST_NOTIFICATIONS permission 
(usage from com.colibrio.readingsystem.audio.service.ColibrioMediaBrowserService) 
[NotificationPermission]

then add this rule to your lint configuration file:

CODE 
<?xml version="1.0" encoding="UTF-8"?>
<lint>
   <issue id="NotificationPermission">
        <ignore regexp="com.colibrio.readingsystem.audio.service.ColibrioMediaBrowserService" />
    </issue>
</lint>

Breaking changes

  • Changed minimum Android version to 6.

  • Update Kotlin Gradle Plugin to 1.7.22 and Android Gradle Plugin to 7.4.2.

  • ResourceProvider interface changes:

    • Introduced new baseUrl property

    • fetch and fetchMetadata now takes a URL instead of a path.

    • Error handling updated to distinguish between recoverable and non-recoverable errors.

  • ReaderView.visiblePages now returns List<VisiblePage> instead of List<VisiblePageData>

  • SyncMediaPlayer.approximateElapsedTime has been renamed to SyncMediaPlayer.approximateElapsedTimeMs.

  • ContentLocation.fetchNavigationItemReferences onSuccess callback is now called with FetchNavigationItemReferencesResult instead of FetchNavigationItemReferencesResultData. Properties in FetchNavigationItemReferencesResult return List<ReaderPublicationNavigationItemReference> instead of List<ReaderPublicationNavigationItemReferenceData>.

  • The following suspend functions now return a ColibrioResult object:

    • ContentLocationContentResolver.fetchTextContent

    • ContentLocationContentResolver.fetchTextContentAfter

    • ContentLocationContentResolver.fetchTextContentBefore

  • Removed deprecated property ColibrioTtsSynthesizer.onBeforeSpeak

  • The new options EpubReflowOptions.removeBottomMarginsOnFragmentedElements and EpubReflowOptions.removeTopMarginsOnFragmentedElements default to true. This may cause content to appear closer to the top and bottom edge of the page compared to previous Colibrio Reader Framework versions. Set these options to false to keep the old behavior.

  • The new options EpubContentProcessingOptions.horizontalOverflowMathMLStrategy and EpubContentProcessingOptions.horizontalOverflowTableStrategy default to EpubContentOverflowStrategy.SCROLL in order to improve legibility and accessibility. This will introduce horizontal scrolling within the page when the table or math elements do not fit horizontally. Set this option to EpubContentOverflowStrategy.SCALE to keep the old behavior.

  • The new option EpubContentProcessingOptions.horizontalOverflowMitigationMinFontSize defaults to 16 pixels in order to improve accessibility. This may cause long words be broken up over more than one line. Set this option to 0 to keep the old behavior.

  • The new option EpubContentProcessingOptions.verticalOverflowMitigationStrategy defaults to EpubContentOverflowStrategy.SCROLL in order to improve accessibility. This will introduce vertical scrolling within a page if not all content fits. Set this option to EpubContentOverflowStrategy.SCALE to keep the old behavior.

Deprecations

The following methods and properties have been deprecated. They will continue to work in all 4.x.x versions

  • ReaderPublicationNavigationData is deprecated. Replaced by ReaderPublicationNavigation.

  • ReaderPublicationNavigationCollectionData is deprecated. Replaced by ReaderPublicationNavigationCollection.

  • ReaderPublicationNavigationItemData is deprecated. Replaced by ReaderPublicationNavigationItem.

  • locator in ReaderPublicationNavigationItem is deprecated. Instead, use the ReaderPublicationNavigationItem directly with methods that support locator.

  • VisiblePageData is deprecated. Replaced by VisiblePage.

  • ReaderView.fetchRectsForVisibleContent is deprecated. Replaced by VisiblePage.fetchRectsForVisibleContent.

  • Setter for ReaderView.syncMediaPlayer is deprecated. Use setSyncMediaPlayer(SyncMediaPlayer, SyncMediaReaderViewSynchronizationMethod) instead.

  • SyncMediaPlayer.playing is deprecated. Use !paused && ready instead.

  • SyncMediaPlayer.approximateElapsedTime is deprecated. Replaced by SyncMediaPlayer.approximateElapsedTimeMs.

  • FetchNavigationItemReferencesResultData is deprecated. Replaced by FetchNavigationItemReferencesResult.

  • ReaderPublicationNavigationItemReferenceData is deprecated. Replaced by ReaderPublicationNavigationItemReference.

  • VisiblePageData is deprecated. Replaced by VisiblePage.

Bug fixes

  • Fixed an issue that sometimes caused OnVisibleContentChangedListener.onVisiblePagesChanged to not be called.

  • Fixed an issue where publicationHashSignature was calculated differently compared to the Web framework.

  • Improvements and bugfixes when applying page-breaks inside tables.

  • Fixed an issue where the reflow engine would fail to properly measure elements that had a transform applied to them, causing inaccurate page-breaks.

  • Fixed an issue where page-breaks were not applied correctly for pre-formatted text, like code examples.

  • Fixed an issue where reflow engine did not calculate margin-collapse rules correctly.

  • Fixed Reflow Engine issues that in some cases caused page breaks to be applied at wrong positions.

  • Annotation’s rendered positions now updates correctly inside scrolling containers.

  • Fixed issues that could cause images to get incorrect aspect ratios.

  • Fixed a bug where reading position might not be accurate when navigating to an annotation spanning two pages.

Changes from 4.0.0-experimental.2

  • ColibrioMediaService is now AudioReadingSystemEngine.

  • ColibrioMediaSessionMetadata.smallIconResId is now mandatory. It cannot be set to null.

  • LPF and EPUB Media Overlay “audio-only” publications are now loaded from the AudioReadingSystemEngine.

  • A SyncMediaPlayer using the ColibrioAudioPlayer for audio playback can now only be created using ReadingSystemEngine.createSyncMediaPlayer(audioPlayer).

  • Added ColibrioAudioPlayer.reload function which allows you to recover from an error state and retry without losing playback position.

  • Fixed several issues where the playback state was not synced correctly when creating a SyncMediaPlayer from a ColibrioAudioPlayer for synchronization with a ReaderView.

  • Fixed several issues where the playback state was not synced correctly when destroying a SyncMediaPlayer that was synchronized with a ReaderView.

  • Fixed an issue where ColibrioAudioPlayer.approximateElapsedTimeMs did not update immediately when seeking.

  • Fixed an issue where ColibrioAudioPlayer.totalDurationMs returned 0 for a short amount of time when the ColibrioAudioPlayer was created.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close