How to play EPUB with Media Overlays with background audio support

Introduction

The ColibrioReadingSystem allows you to load audiobooks in the EPUB with Media Overlays format and play them in the background. In this guide we explain how a project is set up to use this feature, and how to use it.

How to configure the project

Please refer to Playing an Audiobook for instructions on how to configure your project to use this feature.

How to load the EPUB with MediaOverlays

Loading the EPUB file is done using the ReadingSystemEngine:

1. Create a ZipResourceProvider by calling ZipResourceProvider.create(dataSource: RandomAccessDataSource, zipResourceProviderOptions: ZipResourceProviderOptions).

2. Load the EPUB publication into the engine by calling ReadingSystemEngine.loadEpub(config: EpubResourceProviderLoadConfig). In the EpubResourceProviderLoadConfig, pass your ZipResourceProvider. You will get an instance of EpubReaderPublication.

3. Prepare the ReaderView (which you access via ColibrioReadingSystemEngine.readerView) for rendering the publication. To achieve this you add a renderer on the ReaderView and set the readerDocuments to EpubReaderPublication.spine.

4. Create a SyncMediaTimeline by calling createMediaOverlaySyncMediaTimeline(readerDocuments: List<ReaderDocument>, config: MediaOverlaySyncMediaTimelineConfiguration, progressCallback: (Double) -> Unit) on the EpubReaderPublication.

5. Get an EpubAudioPublication by calling AudioReadingSystemEngine.loadEpubMediaOverlayAudioPublication(config: EpubMediaOverlayLoadConfig). In the EpubMediaOverlayLoadConfig you pass the EpubReaderPublication and the SyncMediaTimeline.

6. Create a ColibrioAudioPlayer using AudioReadingSystemEngine.createAudioPlayer(colibrioAudioPlayerConfig: ColibrioAudioPlayerConfig). You specify a ColibrioAudioPlayerConfig supplying the AudioTimeline which you get from EpubAudioPublication.timeline, ColibrioMediaSessionMetadata and ColibrioMediaCommands.

7. Add event listeners to the player using ColibrioAudioPlayer.addOnMediaPlayerEventListener(listener: OnMediaPlayerEventListener) to get notified about playback state and errors. You can remove your listeners using ColibrioAudioPlayer.removeOnMediaPlayerEventListener(listener: OnMediaPlayerEventListener).

8. Use the functions on the ColibrioAudioPlayer to control playback such as play(), pause() and the seek functions.

How to sync native Audio and The ReaderView with a SyncMediaPlayer

After you have created the ColibrioAudioPlayer, follow these steps to synchronize the ReaderView to the ColibrioAudioPlayer:

1. Create a SyncMediaPlayer by calling ReadingSystemEngine.createSyncMediaPlayer(colibrioAudioPlayer: ColibrioAudioPlayer) using the ColibrioAudioPlayer.

2. Assign the created SyncMediaPlayer to the ReaderView and synchronize against the SyncMediaPlayer's current position by calling ReaderView.setSyncMediaPlayer(syncMediaPlayer: SyncMediaPlayer?, initialSyncMethod: SyncMediaReaderViewSynchronizationMethod) using the SyncMediaPlayer and the "reader view goto" SyncMediaReaderViewSynchronizationMethod.

Supporting audio playback when the ReaderView is no longer active

If you want audio playback to resume in the background when the user puts the app in the background or when they leave the current view and the ReaderView is destroyed, then you need to detach the ReaderView from your ColibrioAudioPlayer.

Just before the ReaderView is destroyed, you can detach the ReaderView from your ColibrioAudioPlayer simply by destroying the SyncMediaPlayer which you do by calling ReadingSystemEngine.destroySyncMediaPlayer(player: SyncMediaPlayer). You can then continue using the ColibrioAudioPlayer for background playback.

When the ReaderView is created and you want to achieve synchronization again, follow the previous steps regarding loading EPUB with MediaOverlays publications. In this case you do not create a new ColibrioAudioPlayer, but move on to creating a SyncMediaPlayer using the existing ColibrioAudioPlayer and assigning it to the ReaderView as explained in the synchronization section above.

How to configure the media session

Please refer to Playing an Audiobook for instructions.

How to control playback

Please refer to Playing an Audiobook for instructions.

Handling playback errors

Please refer to Playing an Audiobook for instructions.