Colibrio Docs

Appearance

Release notes Android Framework 5 release candidate ​

For more information about release candidates, see Release Candidates.

5.0.0-rc.7 2026-09-11 ​

API Docs

Bugfixes ​

  • Fixed an issue where an EPUB content document containing an XML processing instruction, for example <?target data?>, sometimes failed to render on an Android WebView running Chromium 150 or later, leaving the page blank.

5.0.0-rc.6 2026-09-08 ​

API Docs

Breaking changes ​

  • ReaderView.addCustomCss() now returns an Int handle identifying the added CSS block. Pass the handle to the new ReaderView.removeCustomCss() to remove that block.
  • ContentDisplayAreaOptions.insets is no longer optional and defaults to a RectMargins of 0 on all sides. Assigning ReaderView.options without insets now resets them to 0 instead of keeping the previous value. This fixes an issue where insets could not be reset once set.
  • Setting SyncMediaManagedReaderViewSynchronizationOptions.enabled to false now disables all synchronization: the player no longer updates the Reading Position, ReaderView.scrollBy() no longer seeks the player, and ReaderView.setSyncMediaPlayer() no longer performs any initial synchronization, whichever initialSyncMethod is given. Call SyncMediaPlayer.attemptReaderViewSynchronization() from your application instead.
  • Cancelling a coroutine while it awaits one of the framework's suspend methods, including the overloads returning ColibrioResult, now propagates the CancellationException to your caller instead of returning it as a ColibrioResult.Error. If you relied on the error result to detect a cancelled call, catch the exception instead.
  • Ownership of TtsSyncMediaTimelineConfiguration.ttsSynthesizer now returns to you when ReaderPublication.createTtsSyncMediaTimeline() fails or is cancelled. Either pass the synthesizer to another createTtsSyncMediaTimeline() call or call TtsSynthesizer.destroy() yourself, as the reading system no longer destroys it.
  • Added ColibrioAudioPlayerException.PreparationFailed. AudioReadingSystemEngine.createAudioPlayer() now returns it in a ColibrioResult.Error when playback preparation fails, and ColibrioAudioPlayer.reload() now throws a ColibrioException in the same situation instead of leaving the player stuck reloading. Exhaustive when expressions over ColibrioAudioPlayerException must handle the new case.
  • ReadingSystemEngine.createSyncMediaPlayer(ColibrioAudioPlayer) now fails with the new ColibrioPlayerAlreadySyncedException when the audio player is already driven by a SyncMediaPlayer created by the same engine, instead of silently replacing that player. Call destroySyncMediaPlayer() on the existing player first.

New features ​

  • Added the new method ReaderView.removeCustomCss(). It removes a custom CSS block using the handle returned by ReaderView.addCustomCss().
  • Added the new option SyncMediaTtsTimelineContentTransformationOptions.contentBlockAttributeExclusions. It lists the attribute names, and optionally attribute values, that exclude a content block and its descendants from a TTS Sync Media timeline. By default, content blocks with role="presentation", role="none" or aria-hidden="true" are excluded, which matches the previous hard-coded behavior. Setting the option replaces the default list rather than adding to it, and an empty list excludes nothing. Attribute names are matched on the qualified name, so a namespace-prefixed attribute must be listed with its prefix.

Improvements ​

  • <audio>, <video>, <canvas> and <iframe> elements are now always kept indivisible during reflow, whatever EpubReaderPublicationOptions.reflowOptions.plugins.fragmentableElements.blacklistSelectors is set to, so a page break can no longer be placed inside one. <audio> and <video> have therefore been removed from that option's default value, which is now tr, picture and math.
  • In ContinuousScrollRenderer and SingleDocumentScrollRenderer, a settled user scroll now moves the Reading Position reported by ReaderView.readingPosition to the start of the Reading Area, instead of leaving it where it was until it fell outside the visible range. It can still differ from the Reading Area start, for example while a Sync Media player with managed synchronization drives it. See the API documentation for details.
  • Android Studio should now be able to render KDoc for the Colibrio Framework APIs.
  • We have documented that the whole reading system API — ReadingSystemEngine, its ReaderView, the publications it loads, and their timelines and SyncMediaPlayers — must be used from the main thread, including the suspend overloads. See the API documentation for details.
  • We have documented that the whole audio API — AudioReadingSystemEngine, the ColibrioAudioPlayer it creates, that player's media session, and WpAudioPublication.createAudioTimeline — must be used from the main thread, including its suspend functions, and that the playback service must run in the same process as the code creating the player. See the API documentation for details.
  • We have documented that a ColibrioAudioPlayer cannot recover a lost connection to the playback service. When reload() throws PlaybackServiceConnectionFailedException, create a new player with createAudioPlayer() instead. See the API documentation for details.
  • The audio API now logs an error when one of its state-changing members or suspend entry points is called from a thread other than the main thread, so an unsupported call is visible in Logcat instead of failing silently later.

Bugfixes ​

  • Fixed an issue where some errors from the WebView bridge were reported with an errorType of TypeError instead of their intended type, such as READER_PUBLICATION_NOT_FOUND. A bridge request that timed out could also leave its call unresolved.
  • Fixed an issue where <audio>, <video>, <canvas> and <iframe> elements in reflowable publications were left-aligned in paginated renderers instead of being centered by their container's text-align (e.g. figure { text-align: center }).
  • Fixed an issue where an <audio controls> element in a reflowable publication collapsed to zero size, hiding its controls, when the page was narrower than the control's default width.
  • Fixed an issue where an image that a publication sized by height or max-height alone was sometimes rendered at the image file's full width, leaving it stretched or several times larger than intended.
  • Fixed an issue where an SVG image with only a viewBox and no intrinsic width/height no longer filled the available width, and instead collapsed to the WebView's default image size.
  • Fixed an issue where an image in a reflowable publication was resized when the publication's CSS combined box-sizing: border-box with a border or padding on the image.
  • Fixed an issue where an element that set overflow-x through an inline style attribute was measured with a scrollable vertical overflow, which could change layout and pagination.
  • Fixed an issue where readingAreaOffsetTop and readingAreaOffsetBottom on ContinuousScrollRendererOptions and SingleDocumentScrollRendererOptions were not capped to the documented 0-30% of the display area.
  • Fixed several issues where AudioReadingSystemEngine.createAudioPlayer() could crash the application, never return, or leave the audio API unusable so that no later player could be created. Such calls now fail instead. If ColibrioMediaBrowserService is declared in a different android:process than the code using the audio API, the error names both processes.
  • Fixed issues where the media session of a destroyed ColibrioAudioPlayer still received notification controls and media buttons, and reported the values of the player created after it. A seek from the media session that arrived while a new player was still being created could crash the application.
  • Fixed issues in the ColibrioAudioPlayer lifecycle: destroying a player could leave playback and its position updates running until the playback service itself was destroyed, and listeners added to or removed from a player or its media session while reload() was in progress were silently ignored.
  • Fixed an issue where ReadingSystemEngine.createSyncMediaPlayer(ColibrioAudioPlayer) accepted a destroyed or reloading audio player and returned a SyncMediaPlayer whose commands silently did nothing. Such calls now fail.
  • Fixed issues where a failed SyncMediaPlayer command could freeze the reported playback position or leave a playback range that could never be cleared, and where setPlaybackRange() threw on failure instead of returning the documented ColibrioResult.Error.
  • Fixed issues where WpAudioPublication.createAudioTimeline() could stall the UI while an audiobook loaded, and where overlapping or cancelled calls could produce incorrect timelines or an uncatchable exception.
  • Fixed an issue where retrying ReaderPublication.createTtsSyncMediaTimeline() with the same TtsSynthesizer instance always failed once a previous attempt had failed.
  • Fixed issues where pausing TTS playback with ColibrioTtsSynthesizer and resuming could continue at the wrong position, either at the start of the next segment or ahead of what had already been spoken, and where the word boundary positions reported for synchronized highlighting could drift ahead of the spoken text, especially in long segments.
  • Fixed issues where TTS playback with ColibrioTtsSynthesizer could stall permanently, never reporting the segment as finished.
  • Fixed an issue where an error from the device's speech engine left ColibrioTtsSynthesizer re-speaking the failed text forever. Playback now reports the error once and can be resumed from the next segment.
  • Fixed an issue where adding or removing a listener from inside a listener callback could throw a ConcurrentModificationException or skip other listeners. This is now supported; see the API documentation for the ordering.
  • Fixed an issue where a ResourceProvider, TtsSynthesizer, RandomAccessDataSource or EncryptionMethod implementation that threw a CancellationException left the request unresolved with nothing logged. Such a failure is now reported as an error.
  • Fixed an issue where ColibrioException.stack could hold a placeholder instead of the stack trace.

5.0.0-rc.5 2026-07-21 ​

API Docs

Breaking changes ​

  • The insets option has been moved from the renderer options classes to ReaderViewOptions.contentDisplayAreaOptions. If you previously set insets on a renderer options class, set it via ReaderView.options.contentDisplayAreaOptions.insets instead.

New features ​

  • Added the new option PublicationStyleOptions.hyphens. This option determines how words should be hyphenated when text wraps across multiple lines.
  • Added the new option EpubRemoteResourceOptions.iframeDomainsToRenderAsOverlay that allows embedded iframes to render as an overlay on top of the publication content. This prevents some third-party websites, such as youtube.com, from blocking their content due to missing Referer header.
  • The insets option is now fully supported by all renderers.
  • Added the new method VisiblePage.fetchBoundingClientRectForContentLocation(). It returns a single rectangle that encompasses a given content location, or null when the location targets non-rendered content. Unlike fetchContentRects, which returns one rectangle per rendered leaf, this returns a single combined rectangle.

Deprecations ​

  • Deprecated ReaderView.setMargins(). Please use ReaderView.options.contentDisplayAreaOptions.insets instead.
  • Deprecated VisiblePage.fetchRectsForVisibleContent(). Please use VisiblePage.fetchContentRects() instead.

Improvements ​

  • We have improved the reader view to group and apply all internal state updates simultaneously before dispatching any event notifications. This ensures that the reader always reflects a fully updated, consistent state whenever an event callback is triggered.

Bugfixes ​

  • Fixed an issue where you couldn't pinch zoom if you tried to do it in the margins around the publication.
  • Fixed some corner-case issues where publication content could be cut off at the end in scroll renderers.
  • Fixed an issue where page navigation swipe gestures failed to trigger when initiated over a scrollable container that had reached its scroll limits.
  • Fixed an issue where scripted documents consuming touch events by calling event.preventDefault() did not prevent the swipe navigation gesture in paginated renderers.
  • Fixed a rendering bug where inline MathML was forced onto its own line in paginated renderers instead of remaining inline as in scroll renderers.
  • Fixed an issue where attaching a SyncMediaPlayer to a ReaderView with the SYNC_MEDIA_SEEK method could navigate the view to the player's position instead of seeking the player to the current reading position.
  • Fixed an issue where a <video> element that set only a width or only a height attribute could be rendered with the other dimension as 0. Missing video dimensions are now derived from the video's intrinsic aspect ratio, and videos with no available metadata no longer render at an excessive size in scroll renderers.
  • Fixed an issue where enabling removePublicationDefinedHorizontalPageMargins could leave content left-aligned and narrower than the available width when a publication used a constrained width with auto margins (e.g. max-width with margin: 0 auto) to center its content.
  • Fixed an issue where scripts in sandboxed EPUB content could not resolve relative URLs because Node.baseURI did not reflect the content document's URL.
  • Fixed an issue where audio created with the new Audio() constructor in sandboxed EPUB content failed to load and play.
  • Fixed an issue where reflowable images without explicit width/height attributes could stay locked to the narrower pre-margin width and fail to expand to the full content width after removePublicationDefinedHorizontalPageMargins removed the page margins.
  • Fixed an issue where custom color palettes were not applied to publications that define colors using CSS custom properties (e.g. background-color: var(--x)), which could leave backgrounds transparent and text rendered in an incorrect color.
  • Fixed an issue where an embedded <iframe> (such as a YouTube embed) in a reflowable document could overflow horizontally when the viewport was narrower than the iframe's authored width; the iframe is now scaled down to fit the available width while preserving its aspect ratio.
  • Fixed an issue where ColibrioAudioPlayer did not restore its state after calling reload().
  • Fixed the name of the textToBeSpoken parameter (previously textBeSpoken) on ColibrioTtsSynthesizerConfigurationListener.onBeforeSpeak.

5.0.0-rc.4 2026-04-21 ​

API Docs

Bugfixes ​

  • Fixed an issue where EPUB locators were occasionally inaccurate near focused content when calling ReaderView.focusOnReadingPosition with focusTarget set to NEAREST_SENTENCE, NEAREST_WORD, or NEAREST_CHARACTER.

5.0.0-rc.3 2026-04-02 ​

API Docs

New features ​

  • Added support for publications utilizing CSS nesting.

  • Introduced explicit focus targeting for ReaderView.focusOnReadingPosition. You can now select the nearest element, character, word, or sentence, significantly improving precision for accessibility and reading-position workflows.

  • Added a new insets option to the various renderer options classes. This allows for extra padding inside the renderer's scrolling container, ensuring content can be scrolled comfortably below system UI elements like device notches or status bars.

    Note: This option is currently experimental and its behavior may change prior to the final 5.0.0 release.

  • Upgraded PDF.js to version 5.4.530, delivering enhanced performance and broader document compatibility.

Deprecations ​

  • Deprecated focusNearContentLocation in FocusOnReadingPositionOptions. Please use focusTargetOptions instead.

Improvements ​

  • Changed the default value of EpubSelectorDocumentSectioningAlgorithm.minimumCharactersPerSection from 10000 to 20000.
  • Selectors defined in EpubReflowOptions.plugins.fragmentableElements.blacklistSelectors are now also used when performing document sectioning breaks.
  • Elements that trigger document sectioning breaks are now marked with the attribute data-colibrio-document-sectioning-break. The attribute value is set to either BEFORE or AFTER depending on the rule that triggered the document sectioning break.
  • Improved support for PDF Character Maps (CMap), enabling improved text support for complex scripts and various languages.

Bugfixes ​

  • Fixed an issue that could cause publication content with position: absolute to overflow in paginated renderers without being able to scroll the content.
  • Resolved an issue where :nth- pseudo-class selectors using An+B syntax like :nth-child(2n+1) sometimes were not preserved correctly.
  • Fixed an EPUB rendering issue where overflow mitigations could override publication-defined CSS transforms in reflowable content documents.
  • Fixed several issues where selecting text in PDF documents would fail or behave unexpectedly.
  • Fixed an issue that could cause SearchResultItemIterator.takeRemaining() to fail on a large set of search results.
  • Resolved an issue where methods returning either a success or failure result never completed when encountering an unsupported WebView version. An error result is now returned with errorType set to WEBVIEW_VERSION_OUTDATED.

5.0.0-rc.2 2026-01-23 ​

API Docs

Bugfixes ​

  • Fixed an issue in Renderer.ContinuousScroll where starting your swipe action horizontally before swiping vertically would not let you scroll.
  • Fixed an issue where calling ReaderView.goTo twice in quick succession (causing the first call to be aborted) could leave pages stuck in a "Loading" state or cause rendering glitches.
  • Fixed an issue where nested CSS @import declarations used the wrong base URL. Relative URLs inside imported CSS files located in a different directory than the parent CSS file now resolve correctly.
  • Fixed an issue causing EPUBs with MathML to sometimes fail rendering on Chrome 108 and earlier.

Improvements ​

  • Removed global flags from consumer ProGuard rules that caused gradle warnings.

5.0.0-rc.1 2025-11-14 ​

API Docs

NOTE

These release notes describe the changes since version 4.6.0

New features ​

  • Added the new renderer ContinuousScroll that shows all documents in a single vertical scrolling view.
  • Added a new event listener for the ReaderView, OnReadingAreaRangeChangedListener, which you can use to get notified when the reading area range changes. You can retrieve the updated value using the new property, ReaderView.readingAreaRange. Note that for paginated renderers the reading area range is the same as the visible range.
    • Note: We have marked ReaderView.readingAreaRange and its corresponding listener OnReadingAreaRangeChangedListener as experimental APIs as we may change the definition of the Reading Area based on your feedback.
  • Added a new ReaderView.goTo() option scrollRendererScrollBehavior to control how scroll renderers behave when the target position is already visible in the ReaderView.
  • Scroll renderers can now smoothly scroll to nearby positions. The duration of the smooth scrolling can be controlled with the renderer options scrollAnimationDurationMs and scrollAnimationMaxDistance. Please refer to the API documentation for more information.
  • Added a new listener method, OnRendererScrollEventListener.onRendererScrollChanged(event: RendererScrollEngineEventData), which is called continuously while scroll renderers are scrolling.
  • Changed the OnRendererScrollEventListener.onRendererScrollStarted(event: RendererScrollEngineEventData) parameter type to RendererScrollEngineEventData. It is now possible to determine whether scrolling was initiated by the user by inspecting the userGenerated property.
  • Added a new renderer option swipeNavigationGestureThreshold. This option can be used to configure the swipe distance required to perform a swipe navigation. Additionally, swipe animations have been refined to start more smoothly.
  • Added a new option to ReaderView.scrollBy() called setReadingPositionToReadingAreaStart. When set to true, the reading position moves to the start of the new Reading Area after scrolling, instead of staying until it leaves the visible range. This is now the default behavior of scrollBy().
  • Added support for EPUB switch/case elements.

Breaking changes ​

  • Upgraded KGP version to 2.1.21, AGP version to 8.7.3 and Gradle version 8.9.

  • Compiling with Java 11:

    • sourceCompatibility: 11
    • targetCompatibility: 11
    • jvmTarget: 11

  • The minimum supported WebView version is now Chrome 64.

  • ColibrioResult.onSuccess has been split into two overloads for better coroutine support:

    • onSuccess(action: (T) -> Unit): ColibrioResult<T> — for regular actions
    • onSuccessSuspend(action: suspend (T) -> Unit): ColibrioResult<T> — for suspending actions

    If you were previously calling onSuccess { someSuspendFunction() }, switch to onSuccessSuspend.

  • ColibrioResult.onError has been split into two overloads for better coroutine support:

    • onError(action: (exception: ColibrioException) -> Unit): ColibrioResult<T> — for regular actions
    • onErrorSuspend(action: suspend (exception: ColibrioException) -> Unit): ColibrioResult<T> — for suspending actions

    If you were previously calling onError { someSuspendFunction() }, switch to onErrorSuspend.

  • Reordered properties alphabetically in all Renderer options:

    • FlipBookRendererOptions
    • SingleDocumentScrollRendererOptions
    • SinglePageSwipeRendererOptions
    • SpreadSwipeRendererOptions
    • StackRendererOptions

  • The ContainerContentBlockType enum entry MATHML_SUB_SUPERSCRIPT was renamed to MATHML_SUBSUP_SCRIPT to be consistent with its value.

Changes to default options

  • EpubReaderPublicationOptions.documentSectioningOptions.enabled has changed from false to true.
  • ReaderViewOptions.pageProgressionTimelineOptions.enabled has changed from true to false.
  • ReaderPublicationOptions.reflowOptions.unforcedTextBreak.widows.minLines has changed from 3 to 2.
  • If you are using PageProgressionTimeline, in addition to enabling it, you must also:
    • Set EpubReaderPublicationOptions.documentSectioningOptions.enabled to false, or
    • Set ReaderViewOptions.pageProgressionTimelineOptions.forceCompleteRendition to true

Removed old deprecated types and members

  • Removed ColibrioAudioPlayer.setMediaSessoinMetaData(mediaSessionMetadata: ColibrioMediaSessionMetadata). Please use the setter for ColibrioAudioPlayer.mediaSession.metaData instead.
  • Removed ColibrioAudioPlayer.setMediaCommands(mediaCommands: ColibrioMediaCommands). Please use the setter for ColibrioAudioPlayer.mediaSession.mediaCommands instead.
  • Removed FetchNavigationItemReferencesResultData. Please use FetchNavigationItemReferencesResult instead.
  • Removed ReaderPublicationNavigationData. Please use ReaderPublicationNavigation instead.
  • Removed ReaderPublicationNavigationCollectionData. Please use ReaderPublicationNavigationCollection instead.
  • Removed ReaderPublicationNavigationItemData. Please use ReaderPublicationNavigationItem instead.
  • Removed ReaderPublicationNavigationItemReferenceData. Please use ReaderPublicationNavigationItemReference instead.
  • Removed SyncMediaPlayer.approximateElapsedTime. Please use SyncMediaPlayer.approximateElapsedTimeMs instead.
  • Removed SyncMediaPlayer.playing. Please use !(SyncMediaPlayer.paused) && (SyncMediaPlayer.ready) instead.
  • Removed VisiblePageData. Please use VisiblePage instead.
  • Removed ReaderView.fetchRectsForVisibleContent(visiblePage: VisiblePageData, locator: SimpleLocatorData?, options: VisibleContentRectsOptions, onSuccess: (VisibleContentRectsResultData) -> Unit, onError: (ColibrioException) -> Unit). Please use VisiblePage.fetchRectsForVisibleContent(locator: SimpleLocatorData?, options: VisibleContentRectsOptions, onSuccess: (VisibleContentRectsResultData) -> Unit, onError: (ColibrioException) -> Unit) instead.
  • Removed ReaderView.fetchRectsForVisibleContent(visiblePage: VisiblePageData, locator: SimpleLocatorData?, options: VisibleContentRectsOptions): ColibrioResult<VisibleContentRectsResultData>. Please use VisiblePage.fetchRectsForVisibleContent(locator: SimpleLocatorData?, options: VisibleContentRectsOptions): ColibrioResult<VisibleContentRectsResultData> instead.
  • Removed setter for ReaderView.syncMediaPlayer. Please use ReaderView.setSyncMediaPlayer(syncMediaPlayer: SyncMediaPlayer?, initialSyncMethod: SyncMediaReaderViewSynchronizationMethod) instead.
  • Removed ReadingSystemEngine.addOnLicenseEventListener(listener: OnLicenseEventListener). Please use ColibrioReaderFramework.addOnLicenseEventListener(listener: OnLicenseEventListener) instead.
  • Removed ReadingSystemEngine.removeOnLicenseEventListener(listener: OnLicenseEventListener). Please use ColibrioReaderFramework.removeOnLicenseEventListener(listener: OnLicenseEventListener) instead.
  • Removed ReadingSystemEngine.createZipResourceProvider(dataSource: RandomAccessDataSource, zipResourceProviderOptions: ZipResourceProviderOptions, onSuccess: (ZipResourceProvider) -> Unit, onError: (ColibrioException) -> Unit). Please use ZipResourceProvider.create(dataSource: RandomAccessDataSource, zipResourceProviderOptions: ZipResourceProviderOptions): ColibrioResult<ZipResourceProvider> instead.
  • Removed ReadingSystemEngine.createZipResourceProvider(dataSource: RandomAccessDataSource, zipResourceProviderOptions: ZipResourceProviderOptions). Please use ZipResourceProvider.create(dataSource: RandomAccessDataSource, zipResourceProviderOptions: ZipResourceProviderOptions): ColibrioResult<ZipResourceProvider> instead.
  • Removed ZipResourceProvider.create(dataSource: RandomAccessDataSource, serializedZipArchiveInformation: ByteArray, chunkCacheSize: Int, onSuccess: (ZipResourceProvider) -> Unit, onError: (ColibrioException) -> Unit). Please use ZipResourceProvider.create(dataSource: RandomAccessDataSource, zipResourceProviderOptions: ZipResourceProviderOptions): ColibrioResult<ZipResourceProvider> instead.
  • Removed ZipResourceProvider.create(dataSource: RandomAccessDataSource, serializedZipArchiveInformation: ByteArray, chunkCacheSize: Int): ColibrioResult<ZipResourceProvider>. Please use ZipResourceProvider.create(dataSource: RandomAccessDataSource, zipResourceProviderOptions: ZipResourceProviderOptions): ColibrioResult<ZipResourceProvider> instead.

Deprecations ​

  • The renderer option ignoreAspectRatio has been deprecated in all Renderer options. Please use ReaderViewOptions.contentDisplayAreaOptions instead.

Bugfixes ​

  • Fixed issue with native audio playback not responding to next and previous buttons on headphones for example.
  • Fixed issue with parsing WP manifest.
  • Fixed an issue with pinch-zooming in PDFs containing many links. Previously, if one finger was on a link, pinch-zooming failed.

Copyright © 2026 Colibrio Software AB