Playing an Audiobook

Introduction

The Colibrio Reader Framework enables you to load and play audiobooks. In this guide, we will explain how to configure your project to use the ColibrioAudioPlayer, and then how to load and play W3C Audiobooks packaged as LPF files.

How to configure the project

Android

Open AndroidManifest.xml and add the following permissions:

XML

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />

Inside the <application> tag, add the following:

XML

<receiver
     android:name="androidx.media.session.MediaButtonReceiver"
     android:exported="true">
     <intent-filter>
         <action android:name="android.intent.action.MEDIA_BUTTON" />
     </intent-filter>
</receiver>
<service
    android:name="com.colibrio.readingsystem.audio.service.ColibrioMediaBrowserService"
    android:enabled="true"
    android:exported="true"
    android:foregroundServiceType="mediaPlayback"
    tools:ignore="ExportedService">
    <intent-filter>
        <action android:name="android.media.browse.MediaBrowserService" />
    </intent-filter>
</service>

You must call AudioReadingSystemEngine.initialize(context: Context) before using the engine to create your audio player. We recommend that you call it in onCreate in your application class or your main activity.

Handling the notification permission lint warning

The ColibrioMediaBrowserService posts media notifications. These notifications are exempt from the runtime notification permission requirement introduced in Android 13 (API 33).If your app does not declare the android.permission.POST_NOTIFICATIONS permission, you may encounter the following Lint error:

CODE

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

Since this service is covered by the exemption, you can safely suppress this warning by adding the following rule to your Lint configuration file:

XML

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

iOS

To enable background audio, select your app target, go to Signing & Capabilities and check Audio, Airplay and Picture in Picture under Background Modes.

How to load the Audiobook file (LPF)

LPF (Lightweight Packaging Format) is a common format for packaged W3C Audiobooks. To open an LPF file, follow these steps:

Create a ZipResourceProvider by calling ZipResourceProvider.create(dataSource: RandomAccessDataSource, zipResourceProviderOptions: ZipResourceProviderOptions) for the LPF file.
Create a WpAudioPublication by calling AudioReadingSystemEngine.loadWpAudioPublication(config: WpAudioPublicationLoadConfig). In the WpAudioPublicationLoadConfig, pass your ZipResourceProvider and set the entryPoint to WpAudioPublicationEntryPoint.Lpf.
Create an AudioTimeline by calling createAudioTimeline(audioDocuments: List<WpAudioDocument>) on the WpAudioPublication you get from the previous step.
Create a ColibrioAudioPlayer using AudioReadingSystemEngine.createAudioPlayer(colibrioAudioPlayerConfig: ColibrioAudioPlayerConfig). You provide a ColibrioAudioPlayerConfig supplying the AudioTimeline, ColibrioMediaSessionMetadata and ColibrioMediaCommands.
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).
Use the functions on the ColibrioAudioPlayer to control playback such as play(), pause() and the seek functions.

How to configure the media session

When creating the ColibrioAudioPlayer you supply ColibrioMediaSessionMetadata and ColibrioMediaCommands. You can modify those later using ColibrioAudioPlayer.mediaSession.metadata and ColibrioAudioPlayer.mediaSession.mediaCommands.

ColibrioMediaSessionMetadata

Used to configure the metadata of the media session, such as book title and artwork.

On Android, you must also specify the PendingIntent for launching UI for the media session. This applies to the case when the notification is tapped. You can use this to launch your app into the playback view for the book for example.

ColibrioMediaCommands

Used for configuring media commands available for your media session.

Note that on iOS, the media commands will only be active if you have Now Playing Info enabled.

You can achieve the following:

Configure play and pause commands (Android only).
Enable/disable rewind and fast-forward commands and configure them.
Enable/disable skip forward and backward commands and configure them.
Enable/disable seeking in the media notification.

How to control playback

Using the ColibrioAudioPlayer you can control playback in a variety of ways:

Call play() and pause() to start and stop playback.
Call seekToApproximateTimeMs(timeInMs: Int), seekToTimelinePosition(position: SyncMediaTimelinePositionData), seekToNextSegment() and seekToPreviousSegment() to seek within the timeline.
Use paused, ready, buffering, seeking, atStart, atEnd, totalDurationMs, timelinePosition and approximateElapsedTimeMs to get the current playback state.
Set playback rate using the playbackRate property.
Set the volume using the volume property.
Mute/unmute playback using the muted property.
Call destroy() when done with the player to clears up used resources. You can check if the player is destroyed using the destroyed property.

Handling playback errors

Errors will be reported using the onError(event: SyncMediaErrorEngineEventData) method in the OnMediaPlayerEventListener you provide using ColibrioAudioPlayer.addOnMediaPlayerEventListener(listener: OnMediaPlayerEventListener). You will get information about the error in the provided SyncMediaErrorEngineEventData object.

After fixing the cause of the error, you can use ColibrioAudioPlayer.reload() to reload the player keeping current position. You need to call ColibrioAudioPlayer.play() to continue playback after reloading.