AudioReadingSystemEngine

This is the entry point for the Colibrio background audio playback services.

To be able to use the AudioReadingSystemEngine, you need to modify your AndroidManifest.xml file: Add the following permissions:

<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:

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

The service must run in the same process as the code that calls createAudioPlayer, or playback cannot start. If you declare the service with android:process, create the player from that same process.

You must call AudioReadingSystemEngine.initialize 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.

Threading

Use the audio API from the main thread, including this engine, the ColibrioAudioPlayer it creates, that player's ColibrioMediaSession, and WpAudioPublication.createAudioTimeline. This includes the suspend functions: call them from a coroutine on the main dispatcher rather than switching dispatchers first. The audio playback service and the players it drives are not thread-safe; their state lives on the main thread.

The same applies to two ReadingSystemEngine members, because they read an audio player's state: ReadingSystemEngine.createSyncMediaPlayer when you pass it a ColibrioAudioPlayer, and ReadingSystemEngine.destroySyncMediaPlayer for the SyncMediaPlayer that call returned.

Calls from another thread are not supported. Where the framework detects one it logs an error naming the call, but detection is not recovery and silence is not a guarantee: an off-main call can lose its result, deadlock against the main thread, or leave the player in an inconsistent state. Property reads are not reported at all, and can still answer stale or throw.