Appearance
Release notes Android Framework 2
IMPORTANT
This version of the Colibrio Reader Framework is no longer covered by our warranty support.
2.2.0 2022-05-18
New features
- The TTS
SyncMediaTimelineno longer adds the text "Media element" or "Image alt text" when a media element is encountered. Instead, when you callReaderPublication.createTtsSyncMediaTimeline(), you can set what text to prepend by setting the optioncontentTransformationOptions.imageAltTextPrefix.
Bugfixes
- Fixed an issue where PDF pages sometimes rendered as blank pages if the rendering was interrupted by a
ReaderView.refresh()or when settingReaderView.options. - Fixed an issue with
ContentPositionTimeline.fetchTimelineRangefor EPUB. When passing aContentLocationrange that ended just before a media element, the returned result incorrectly included the media element.
2.1.1 2022-03-25
Bugfixes
- Fixed an issue that caused fixed-layout EPUBs to be rendered with the wrong aspect ratio if a
<meta name="viewport"...element contained extra whitespaces in itscontentattribute.
2.1.0 2022-02-22
New features
- Added a new option
alignedSegmentSeekThresholdMstoSyncMediaAudioRendererOptions. This option controls how theSyncMediaAudioRenderershould 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.
Bugfixes
- Fixed an issue causing some links in PDF files to not work correctly.
- Removed an XML file containing an unused SVG image that caused a
STRING_TOO_LARGEerror when building a project including the framework. (It did not affect the build.)
2.0.2 2022-01-17
New features
- You can now disable the pan/zoom reset when navigating a
ReaderViewby settingIReaderViewOptions.transformManagerOptions.removeTransformOnNavigationto false.
Bugfixes
- Fixed an issue that caused
IEpubReaderPublication.fetchContentLocation()to fail when passing aLocatorselecting a range across multiple documents that started from the firstReaderDocumentin the spine.
2.0.1 2021-12-02
Bugfixes
- EPUB resources using the text encoding UTF-16 is now supported.
2.0.0 2021-11-15
Changes from 2.0.0-rc.6
Bugfixes
- Fixed an issue causing TrueType Collection fonts
.ttcfiles to not work with EPUB Publications. - Fixed an issue causing attribute selectors in CSS files to not work correctly.
Changes from 1.1.4
New features
This release contains the following major new features:
- ContentPositionTimeline API
- SingleDocumentScrollRenderer
- Media Streaming
ContentPositionTimeline API
A ContentPositionTimeline is used for describing positions in ReaderPublication content as integers. The timeline starts at position 0 and its length can be retrieved using ContentPositionTimeline.length.
The ContentPositionTimeline object provides an API for converting integer positions to locators, and vice versa.
The unit of measurement can be configured when creating a ContentPositionTimeline. Which units of measurement that are supported for a ReaderPublication can be retrieved using ReaderPublication.availableContentPositionTimelineUnits().
For example:
- EPUB publications can construct
ContentPositionTimelines withCHARACTERSas the unit of measurement. A position is the character offset from the start of the publication. - PDF publications can construct
ContentPositionTimelines withPAGESas the unit of measurement. A position is the page index from the start of the publication.
See EpubReaderPublication.createContentPositionTimeline(), PdfReaderPublication.createContentPositionTimeline() for how to create a ContentPositionTimeline.
As these timelines are constructed from publication content, a position in the timeline will always map to the same location in the publication content regardless of how the content is rendered. Thus, it is useful for implementing progress bars, reporting reading progression, etc.
SingleDocumentScrollRenderer
A new scrolling renderer is now available. It displays one document at the time and allows the user to scroll its content.
When a SyncMediaPlayer is attached to the ReaderView, the scroll position will automatically synchronize with the SyncMediaPlayer playback position.
Media Streaming
The framework now supports streaming of media resources using the browser's Media Source API. In this release, the framework can stream MP3 audio files. We plan to add support for AAC and MP4 in a future release.
While the <video> and <audio> elements support streaming over HTTP natively, when playing a media resource from an EPUB file, the complete file must first be extracted before playback can start. With media streaming enabled, the playback can start sooner.
Media streaming is an opt-in feature that can be enabled for media elements in EPUB publications, as well as for Media Overlays. It is recommended to enable this feature if you are streaming the EPUB file over the internet.
To enable it for media elements in EPUB publications, set EpubReaderPublicationOptions.enableMediaStreaming to true. To enable it for Media Overlays, add the following option when creating the SyncMediaTimeline:
kotlin
epubReaderPublication.createMediaOverlaySyncMediaTimeline(readerDocuments, {
defaultAudioRendererOptions: {
enableMediaStreaming: true
}
}Keyboard events
You can now add EngineEvent listeners for "keydown" and "keyup" to detect keyboard events when the focus is inside publication content.
Other features
EngineEventobjects for click events, pointer events and keyboard events now have the propertyengineEvent.target.frameworkComponent. This property can be used to detect if the target of the event was inside aReaderDocument, aReaderViewor aReaderViewAnnotation.- Added
ReaderPublicationOptions.clipboardOptionsallowing configuration of copy actions such as Ctrl+C. - Added
minimumTimeToDisplayPagesWithSyncMediatoSyncMediaManagedReaderViewSynchronizationOptions. - Added
alwaysSeekToSegmentStarttoSyncMediaManagedReaderViewSynchronizationOptions. - Added
zipResourceProviderOptionstoPublicationLoadConfiguration.Epubto controlling how chunks will be retrieved from theRandomAccessDataSource. - Added
PageProgressionTimelineOptions.enabledallowing you to disable the feature if you are usingContentPositionTimelineinstead. - Added
ReaderViewGotoOptionsthat can be used to configure howReaderView.goTo()should behave. createContentPositionTimelineandcreateSyncMediaTimelinemethods now accept an optional argumentprogressCallbackwhich can be used for receiving callbacks about the timeline creation progress.
Bugfixes
- Fixed a bug that caused the parsing of locator strings containing a
RangeSelectorto fail. (RangeSelectors are only used by the framework when creating locators across multiple pages in PDFs.) The bug did not affect highlight ranges in PDFs or EPUB CFI ranges. - Fixed several issues related to the locator implementation for PDF.
- Rendering
ReaderViewAnnotations for PDF locators such as#page=2will now render a "position" element at the top-left corner. - Rendering
ReaderViewAnnotations for EPUB CFIs that pointed to the end of a container, i.e. after the last child in the container, will now render a "position" element at the closest point corresponding to the end of that container. - Fixed an issue causing TrueType Collection fonts
.ttcfiles to not work with EPUB Publications. - Fixed an issue causing attribute selectors in CSS files to not work correctly.
Improvements
- Improved performance in
SinglePageSwipeRendererandSpreadSwipeRenderer. - Improved rendering quality in
StackRendererandFlipbookRenderer. (See Breaking changes) - Improved reflow performance.
FlipbookRendererandStackRendererUI has improved and now has more options to control shadows, perspective and rubber band effect when swiping at the beginning or the end of a publication.- The process of creating
SyncMediaTimelineandContentPositionTimelineinstances will now temporarily pause when: theReaderViewis performing a navigation; visible or offscreen content is rendering; the user performs aReaderViewGesturesuch as swiping the page or pan-zooming.
Breaking changes
FlipbookRenderer and StackRenderer
In an earlier version of the framework, a fix was added to workaround a bug on Chrome for Android. The bug causes content to sometimes disappear when performing pan-zoom gestures.
The negative effect of enabling the bugfix was that zoomed-in content appeared blurry. Since the bug has not been observed since Chrome 90, we have now removed it in order to improve rendering quality. If the bug should resurface, you can enable the bugfix again by setting the renderer option fixDisappearingCharactersInChromeForAndroid to true.
Full list of breaking changes
ResourceMetadata:
- Many fields have changed due to a refactor of the
ResourceProviderAPI in the web framework. MediaTypeCategoryenum values have changed. Values now map to the HTTP Accept header.
NavigationAction:
NEXThas been split intoNEXT_CONTENT_RANGEandNEXT_RENDERABLE_PAGE.PREVIOUShas been split intoPREVIOUS_CONTENT_RANGEandPREVIOUS_RENDERABLE_PAGE.
EngineEventMediaResource:
mediaTypehas been removed.
1.1.4 2021-10-21
Bugfixes
- Fixed an issue in
ColibrioTtsSynthesizerthat in rare cases could cause a crash.
1.1.3 2021-09-24
Bugfixes
- Fixed an issue where EPUB
ReaderDocuments failed to render if it had a CSS file that ended with an open comment, i.e. a comment that was not closed with*/.
1.1.1 2021-06-24
Bugfixes
- Fixed an issue that caused
ReaderViewAnnotations to not render if the backing EPUB CFI pointed to the end of an element. - Fixed an issue that caused CSS variables to not be preserved in publication stylesheets.
- Fixed an issue that could cause EPUB Media Overlays to not play correctly if the
srcattribute in a<text>element did not contain a fragment identifier (i.e. it referenced the whole document).
1.1.0 2021-05-27
New features
- The semver version string of the framework can now be retrieved using
ColibrioReaderFramework.versionName.
Bugfixes
- Fixed an issue causing
OnActiveTransformChangedListener.onActiveTransformChangednot being fired correctly. - Fixed an issue that caused
ReaderViewGestures to not work correctly ifReaderView.allowedGestureTypeswas modified while a gesture was active. - Fixed an issue where the
SyncMediaPlayerdid not automatically navigate to next page if the remaining pages in theReaderViewdid not contain sync media. - Fixed an issue where the
ReaderViewdid not remove the active renderer correctly when switching to content set bysetContentOnActiveRendererMissing(). - Fixed an issue where the
ReaderView.focusOnReadingPosition()sometimes could fail with an unexpectedTypeErrorin EPUB publications. - Fixed an issue causing
SyncMediaPlayer.pausednot being updated correctly ifColibrioTtsSynthesizerwas interrupted by the system (such as the TalkBack service).
1.0.1 2021-05-07
Bugfixes
- Fixed an issue when configuring
TextToSpeech.languageinColibrioTtsSynthesizer.
1.0.0 2021-05-06
New features
- TTS
SyncMediaTimelines can now be created usingReaderPublication.createTtsSyncMediaTimeline().
Bugfixes
- Setting
ReaderView.syncMediaPlayerto null will now correctly detach the existing player from theReaderView. - Fixed an issue that could cause EPUB Media Overlays to not work properly when a
<par>node referenced the body element.
0.9.0 2021-04-07
Breaking changes
PublicationLoadConfiguration.Pdf()has changed argument order. It now also takes an optionalpublicationOptions: PdfPublicationOptionsargument.PublicationLoadConfiguration.Epub()has changed argument order.
New features
- Added new options to
PdfPublicationOptionsto enable chunk requests with deterministic sizes.
Bugfixes
- Fixed an issue that could cause the
SyncMediaPlayerto pause in some cases when segment duration was 0.
0.8.3 2021-03-15
Bugfixes
- Fixed an issue causing the
SyncMediaPlayerto fail advancing to next segment sometimes when playing VBR (variable bitrate) audio files like MP3 or AAC, and theMediaOverlayused aclipEndvalue greater than the actual audio file duration.
0.8.2 2021-03-11
Bugfixes
- Fixed an issue where documents with non-standard media type
application/htmlcouldn't be loaded properly. - Fixed an issue causing scripts in scripted content documents to sometimes load in the wrong order if the script was loaded over https.
- Fixed an issue where
SyncMediaPlayersometimes did not play the last seconds of VBR (Variable bitrate) AAC audio files.
0.8.1 2021-03-02
Bugfixes
- Fixed an issue where
FlipbookRendererandSpreadSwipeRendererdid not handle publications with RTL page progression direction correctly.
0.8.0 2021-02-25
New features
OnSyncMediaPlayerEventListenerhas two new methods:onEndReached()which is called when theSyncMediaPlayerhas reached the end of the timeline.onError(event: SyncMediaErrorEngineEventData)which is called when an error occurs in theSyncMediaPlayerthat may cause it to pause. SeeSyncMediaErrorEngineEventDatafor more information.
ColibrioReaderFramework.webViewLogLevelwhich can be used to set which WebView console messages that should be logged to the device log.ReaderView.addCustomCss(css: String)which can be used to add CSS that will affect theReaderViewandReaderViewAnnotationLayers.
Breaking changes
RendererOptions.prerenderOffscreenPageshas been removed. Offscreen pages will now always be pre-rendered.
Bugfixes
- Fixed an issue causing AAC audio files to not work sometimes on iOS and iPadOS.
- Improved EPUB resource streaming to prevent timeout errors when downloading large files over slow internet connections.
- Refreshing the
ReaderViewwhile performing a next/previous animation will now result in the reading position being properly updated to the next/previous page. ReaderView.goTo()navigations to adjacent pages will now use the next/previous animations.- Fixed a memory leak related to doing many
goTos in rapid succession. - Fixed an issue that could cause the
SyncMediaPlayerto start playing from start of the timeline a short period of time while performing the initialReaderView.goTo. ReaderViewAnnotationOptionscan now be used to override positioning and dimensions (width/height, left/top, etc.)- Fixed an issue where large widths specified on elements in EPUB content documents caused font-size to decrease.
0.7.3 2021-02-01
Bugfixes
- Fixed issue where
ColibrioReadingSystemViewwas leaking an instance ofActivityit was attached to, even when callingdestroy()method. - Added a processing step to rewrite large horizontal margins that caused content to overflow horizontally on small screens.
0.7.2 2020-01-14
Bugfixes
- Fixed an issue where converting a
SyncMediaPositionto anIAnnotationTargetsometimes caused EPUB CFI text offsets to be expressed as floating-point numbers. - Fixed an issue when reflowing EPUBs that caused too much content to appear on a single page when a non-empty container element had its height set to 0, but its overflow rule was set to
visible. - Fixed an issue when reflowing EPUBs that in some cases caused too much content to appear on a single page.
0.7.1 2020-12-11
Bugfixes
- Fixed an issue causing pointer events and text selection in PDFs to not work as expected.
- Fixed an issue causing gestures such as swiping between pages to not work if starting the gesture outside page content.
0.7.0 2020-12-04
New features
Sync media
Added SyncMediaPlayer and SyncMediaTimeline. These classes can be used to play synchronized media, such as EPUB Media Overlays.
First, you need to create a SyncMediaTimeline. You can check if it is possible to create a timeline using ReaderPublication.availableSyncMediaFormats. Each sync media format has its own method for creating a SyncMediaTimeline. To create a timeline based on EPUB Media Overlay, use EpubReaderPublication.createMediaOverlaySyncMediaTimeline.
When you have a SyncMediaTimeline instance, you can create a SyncMediaPlayer to play the timeline using ReadingSystemEngine.createSyncMediaPlayer.
Finally, you need to attach the SyncMediaPlayer to the ReaderView so they can synchronize their positions. Use ReaderView.syncMediaPlayer = mySyncMediaPlayer to do this. Navigating the ReaderView or seeking the SyncMediaPlayer, will now automatically handle synchronization between the ReaderView.readingPosition and the SyncMediaPlayer.timelinePosition.
Focus API
Added ReaderView.focusOnReadingPosition. By focusing on publication content, your app gives accessibility technologies such as screen readers an intent where to start reading. Please note that this method only sets focus inside the WebView.
You may need to set focus on the ColibrioReadingSystemView before calling this method. First make sure you have set colibrioReadingSystemView.importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_YES. Then use colibrioReadingSystemView.sendAccessibilityEvent(AccessibilityEvent.TYPE_VIEW_FOCUSED) to set focus on the ColibrioReadingSystemView.
Transform Manager API
Added ReaderView.transformManager. Used for applying transformations such as scaling and translations to a ReaderView. You can for example use this to zoom to a position when a user clicks/taps on the ReaderView.
Other features
- The API reference documentation has been updated across the whole framework and now contains more details.
- Added two new options to
IFlipBookRendererOptions:showPageFoldShadowandpageFoldShadowOpacity. SettingshowPageFoldShadowto true will add a shadow between the left and right page, making it look more like a book. - Added support for CSS declarations
object-fitandobject-positionin reflowable content documents. These allow you to control how to position images that have been scaled. - Added improved support for range locators. Range locators can now point to ranges across multiple documents in a publication.
ReaderViewand Renderers has been reworked to support more advanced presentation modes.- Added
ReaderView.visiblePagescontaining the reader document and range locator for each page. - Added
ReaderView.visibleRangecontaining the locator pointing to the content range visible in theReaderView. - Added
ReaderView.visibleContentRenderingandReaderView.offscreenContentRendering. - Added
ReaderView.activeNavigationActionshowing which type of navigation action that is currently being performed if any. - Added
ReaderView.activeGestureTypeshowing the current active gesture type being performed by the user if any. - Added
ReaderView.allowedGestureTypesallowing you to control which type ofReaderViewgestures the user is allowed to perform. - Added several new listeners to detect changes in
ReaderView.
Bugfixes
- Video elements should now be allowed to play in fullscreen. Caveat: When rotating the screen on iOS,
view.refresh()will exit fullscreen mode. - Ensure that error responses from
RandomAccessDataSourceare not cached by theZipResourceProviderso that they can be retried. - Fixed an issue where Chrome caused reflowable documents containing soft-hyphen characters to page-break at incorrect positions.
- Fixed an issue when reflowing EPUBs that in some cases caused too much content to appear on a single page.
Breaking changes
This release contains all the API changes for the upcoming 1.0 release. We have renamed and reworked several types in the framework. One of the main reasons for the renamings is to make the APIs more consistent and easier to understand. Another is to ensure that the APIs are consistent across all platforms. We have also updated the API documentation across the whole framework which will provide you with more contextual help while you code.
The following classes and interfaces have been renamed:
| Old name | New name |
|---|---|
LicenseOptions | ReadingSessionOptions |
ReaderPublicationLocationTarget | ContentLocation |
PublicationConfiguration | PublicationLoadConfiguration |
ReaderViewModelStateDataPageProgressionDirection | ReaderViewPageProgressionDirection |
OnMouseEngineEventListener | OnMouseEventListener |
OnPointerEngineEventListener | OnPointerEventListener |
OnSelectionChangeListener | OnSelectionChangedListener |
OnViewAnnotationClickListener | OnAnnotationClickListener |
OnViewAnnotationContextMenuListener | OnAnnotationContextMenuListener |
OnViewAnnotationInViewChangedListener | OnAnnotationIntersectsVisibleRangeChangedListener |
PageProgressionTimelineListener | OnPageProgressionTimelineEventListener |
ViewAnnotation | ReaderViewAnnotation |
ViewAnnotationLayer | ReaderViewAnnotationLayer |
ViewEngineEventData | ReaderViewEngineEventData |
ViewAnnotationLayerOptions | ReaderViewAnnotationLayerOptions |
ViewAnnotationOptions | ReaderViewAnnotationOptions |
ViewOptions | ReaderViewOptions |
The following classes have been removed:
Renderer.VerticalScroll: This renderer had many issues and is being replaced by two new renderers in the near future:ContinuousScrollRendererandScrolledDocumentRenderer.VerticalScrollRendererOptionsOnViewStateChangedListener:ReaderView.viewStateno longer exists.
The following properties and methods have changed:
PageProgressionTimeline:
visibleRange→visibleTimelineRange
PublicationLoadConfiguration:
options→readerPublicationOptionsdataSource→publicationDataSourcelicenseOptions→readingSessionOptions
ReaderPublication:
getLocationTarget→getContentLocationhasSyncMediahas been removed. (availableSyncMediaFormatsis now available instead)
ReaderView:
viewStatehas been removed. UseactiveNavigationAction,activeGestureTypeandtransformManager.activeTransforminstead.responsive→responsiveRendererSelectionEnabledisAtFirstPage→isAtStartisAtLastPage→isAtEndcontentDocumentEventHandlersEnabled→scriptedContentDocumentEventHandlersEnabledviewOptions→optionscreateViewAnnotationLayer→createAnnotationLayerdestroyViewAnnotationLayer→destroyAnnotationLayersetOnActiveRendererChangedListener→addOnActiveRendererChangedListenerandremoveOnActiveRendererChangedListenersetOnReadingPositionChangedListener→addOnReadingPositionChangedListenerandremoveOnReadingPositionChangedListenersetOnMouseEngineEventListener→addOnMouseEventListenerandremoveOnMouseEngineEventListenersetOnPointerEngineEventListener→addOnPointerEventListenerandremoveOnPointerEventListenersetPageProgressionTimelineListener→addOnPageProgressionTimelineEventListenerandremoveOnPageProgressionTimelineEventListenersetOnSelectionChangeListener→addOnSelectionChangedListenerandremoveOnSelectionChangedListenersetOnNavigationIntentEventListener→addOnNavigationIntentEventListenerandremoveOnNavigationIntentEventListenersetContentOnOfflineReadingSessionExpired→setContentOnLicenseGracePeriodExpired
ReaderViewAnnotation:
hasCustomizeOptionshas been removed. Checkoptions != nullinstead.inView→intersectsVisibleRange
ReaderViewAnnotationLayer:
createViewAnnotation→createAnnotationcreateViewAnnotations→createAnnotationsdestroyViewAnnotation→destroyAnnotationdestroyAllViewAnnotations→destroyAllAnnotationsdefaultViewAnnotationOptions→defaultAnnotationOptionsviewAnnotations→annotationssetOnViewAnnotationClicklListener→addOnAnnotationClickListenerandremoveOnAnnotationClickListenersetOnViewAnnotationContextMenuListener→addOnAnnotationContextMenuListenerandremoveOnAnnotationContextMenuListenersetOnViewAnnotationInViewLister→addOnAnnotationIntersectsVisibleRangeChangedListenerandremoveOnAnnotationIntersectsVisibleRangeChangedListener
ReadingSystemEngine:
setOnLicenseEventListener→addOnLicenseEventListenerandremoveOnLicenseEventListenerloadPdfPublication→loadPublicationloadEpubPublication→loadPublication
OnAnnotationClickListener:
onViewAnnotationClick→onAnnotationClick
OnAnnotationIntersectsVisibleRangeChangedListener:
onViewAnnotationInViewChanged→onAnnotationIntersectsVisibleRangeChanged
OnPointerEventListener:
onPointerEngineEvent→ Split into:onPointerDown,onPointerMove,onPointerUp,onPointerCancel
OnSelectionChangedListener:
onSelectionChange→onSelectionChanged
OnNavigationIntentEventListener:
onNavigationEvent→onNavigationIntent
PublicationStyleTextAlignmentOptions:
allowed→preserved
ReaderViewAnnotationLayerOptions:
viewAnnotationInputEngineEventsEnabled→annotationInputEngineEventsEnabled
ReaderViewOptions:
enablePointerEventListenerwas removed. UseReaderView.allowedGestureTypesinstead.viewInteractionPointerTypeswas removed. UsegestureOptions.panZoom.pointerTypesandgestureOptions.swipeNavigation.pointerTypesinstead.viewStateOptionswas removed. UsegestureOptionsandtransformManagerOptionsinstead.
0.6.0 2020-10-12
New features
- Publication metadata now available for all publication types.
- You can now override text alignment in reflowable content documents using the
textAlignmentproperty inPublicationStyleOptions.
Improvements
- Prevent loading CSS background-images that are included in the stylesheet but not used in the active content document.
Bugfixes
- Fixed an issue where illegal attribute values for
widthorheighton<img>elements could cause images to appear stretched.
0.5.0 2020-09-14
Breaking changes
- Enum
RendererDirectionhas been replaced with the more genericAxis. This caused changes to the following types:SinglePageSwipeRendererOptionsSpreadSwipeRendererOptions
Improvements
- Allow
data-attributes in EPUB content documents. - Ensure remote images and videos behave correctly when reflowing content.
Bugfixes
- Fixed an issue causing
clickevents to not fire on iOS 12 and earlier in some publications. - Fixed an issue causing
FlipbookRendererandStackRendererto animate incorrectly in some cases. - Fixed an issue where reflowing content-documents containing CSS
position: relativecaused page breaks to occur too early.
0.4.1 2020-08-10
Breaking changes
RandomAccessDataSourcefetchChunkmethod now returns aByteArrayinstead of callingonSuccess/onErrorfunctions.
Improvements
- Added
"object"tag to EPUB html element whitelist in order to support "EPUB3 bindings" fallback content. - Added support for
@importdeclarations in CSS files.
Bugfixes
- Fixed an issue causing the EPUB
FileSizeBasedpage estimation algorithm to report inaccurate results for some EPUBs. - Force video files with the
.m4vextension to use the media-type"video/mp4"in order for playback to work in Safari browsers.