Implement a new audiobook navigator based on Jetpack Media2 (#80)

This new audiobook navigator departs from the previous one in the following way:
- No `MediaController` is used.
- No `Service` provided and no UI-related stuff (including for the notification zone).
- Apps must build a `MediaControllerSession`, use a helper to get a session from it, and connect that session to their media service.

Author: qnga

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to this project will be documented in this file. Take a look at [the migration guide](docs/migration-guide.md) to upgrade between two major versions.
 
-**Warning:** Features marked as *alpha* may change or be removed in a future release without notice. Use with caution.
+**Warning:** Features marked as *experimental* may change or be removed in a future release without notice. Use with caution.
 
 ## [Unreleased]
 
@@ -32,6 +32,10 @@ All notable changes to this project will be documented in this file. Take a look
 * The new `Navigator.Listener.onJumpToLocator()` API is called every time the navigator jumps to an explicit location, which might break the linear reading progression.
     * For example, it is called when clicking on internal links or programmatically calling `Navigator.go()`, but not when turning pages.
     * You can use this callback to implement a navigation history by differentiating between continuous and discontinuous moves.
+* (*experimental*) A new audiobook navigator based on Jetpack `media2`.
+    * See the [pull request #80](https://github.com/readium/kotlin-toolkit/pull/80) for the differences with the previous audiobook navigator.
+    * This navigator is located in its own module `readium-navigator-media2`. You will need to add it to your dependencies to use it.
+    * The Test App demonstrates how to use the new audiobook navigator, see `MediaService` and `AudioReaderFragment`.
 
 ### Deprecated
 
@@ -86,7 +90,7 @@ All notable changes to this project will be documented in this file. Take a look
 
 #### Shared
 
-* (*alpha*) A new Publication `SearchService` to search through the resources' content, with a default implementation `StringSearchService`.
+* (*experimental*) A new Publication `SearchService` to search through the resources' content, with a default implementation `StringSearchService`.
 * `ContentProtection.Scheme` can be used to identify protection technologies using unique URI identifiers.
 * `Link` objects from archive-based publication assets (e.g. an EPUB/ZIP) have additional properties for entry metadata.
     ```json
@@ -108,12 +112,12 @@ All notable changes to this project will be documented in this file. Take a look
 
 * The EPUB navigator is now able to navigate to a `Locator` using its `text` context. This is useful for search results or highlights missing precise locations.
 * Get or clear the current user selection of the navigators implementing `SelectableNavigator`.
-* (*alpha*) Support for the [Decorator API](https://github.com/readium/architecture/pull/160) to draw user interface elements over a publication's content.
+* (*experimental*) Support for the [Decorator API](https://github.com/readium/architecture/pull/160) to draw user interface elements over a publication's content.
     * This can be used to render highlights over a text selection, for example.
     * For now, only the EPUB navigator implements `DecorableNavigator`, for reflowable publications. You can implement custom decoration styles with `HtmlDecorationTemplate`.
 * Customize the EPUB selection context menu by providing a custom `ActionMode.Callback` implementation with `EpubNavigatorFragment.Configuration.selectionActionModeCallback`.
     * This is an alternative to overriding `Activity.onActionModeStarted()` which does not seem to work anymore with Android 12.
-* (*alpha*) A new audiobook navigator based on Android's [`MediaSession`](https://developer.android.com/guide/topics/media-apps/working-with-a-media-session).
+* (*experimental*) A new audiobook navigator based on Android's [`MediaSession`](https://developer.android.com/guide/topics/media-apps/working-with-a-media-session).
     * It supports out-of-the-box media style notifications and background playback.
     * ExoPlayer is used by default for the actual playback, but you can use a custom player by implementing `MediaPlayer`.
 
@@ -327,7 +331,7 @@ progression. Now if no reading progression is set, the `effectiveReadingProgress
 #### Navigator
 
 * Support for the new `Publication` model using the [Content Protection](https://readium.org/architecture/proposals/006-content-protection) for DRM rights and the [Fetcher](https://readium.org/architecture/proposals/002-composite-fetcher-api) for resource access.
-* (*alpha*) New `Fragment` implementations as an alternative to the legacy `Activity` ones (contributed by [@johanpoirier](https://github.com/readium/r2-navigator-kotlin/pull/148)).
+* (*experimental*) New `Fragment` implementations as an alternative to the legacy `Activity` ones (contributed by [@johanpoirier](https://github.com/readium/r2-navigator-kotlin/pull/148)).
   * The fragments are chromeless, to let you customize the reading UX.
   * To create the fragments use the matching factory such as `EpubNavigatorFragment.createFactory()`, as showcased in `R2EpubActivity`.
   * At the moment, highlights and TTS are not yet supported in the new EPUB navigator `Fragment`.
@@ -424,13 +428,13 @@ progression. Now if no reading progression is set, the `effectiveReadingProgress
   * Get the visible position from the current `Locator` with `locations.position`.
   * The total number of positions can be retrieved with `publication.positions().size`. It is a suspending function because computing positions the first time can be expensive. 
 * `ReadiumWebPubParser` to parse all Readium Web Publication profiles, including [Audiobooks](https://readium.org/webpub-manifest/extensions/audiobook.html), [LCP for Audiobooks](https://readium.org/lcp-specs/notes/lcp-for-audiobooks.html) and [LCP for PDF](https://readium.org/lcp-specs/notes/lcp-for-pdf.html). It parses both manifests and packages.
-* (*alpha*) `PDFParser` to parse single PDF documents.
+* (*experimental*) `PDFParser` to parse single PDF documents.
   * The PDF parser is based on [PdfiumAndroid](https://github.com/barteksc/PdfiumAndroid/), which may increase the size of your apps. Please open an issue if this is a problem for you, as we are considering different solutions to fix this in a future release.
 
 #### Navigator
 
 * The [position](https://github.com/readium/architecture/tree/master/models/locators/positions) is now reported in the locators for EPUB, CBZ and PDF.
-* (*alpha*) [PDF navigator](https://github.com/readium/r2-navigator-kotlin/pull/130).
+* (*experimental*) [PDF navigator](https://github.com/readium/r2-navigator-kotlin/pull/130).
   * Supports both single PDF and LCP protected PDF.
   * As a proof of concept, [it is implemented using `Fragment` instead of `Activity`](https://github.com/readium/r2-navigator-kotlin/issues/115). `R2PdfActivity` showcases how to use the `PdfNavigatorFragment` with the new `NavigatorFragmentFactory`.
   * The navigator is based on [AndroidPdfViewer](https://github.com/barteksc/AndroidPdfViewer), which may increase the size of your apps. Please open an issue if this is a problem for you, as we are considering different solutions to fix this in a future release.

readium/navigator-media2/build.gradle.kts

@@ -0,0 +1,79 @@
+/*
+ * Copyright 2022 Readium Foundation. All rights reserved.
+ * Use of this source code is governed by the BSD-style license
+ * available in the top-level LICENSE file of the project.
+ */
+
+plugins {
+    id("com.android.library")
+    id("kotlin-android")
+    id("kotlin-parcelize")
+    id("maven-publish")
+    id("org.jetbrains.dokka")
+}
+
+android {
+   resourcePrefix = "readium_"
+
+    compileSdk = 31
+
+    defaultConfig {
+        minSdk = 21
+        targetSdk = 31
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_1_8
+        targetCompatibility = JavaVersion.VERSION_1_8
+    }
+    kotlinOptions {
+        jvmTarget = "1.8"
+        freeCompilerArgs = freeCompilerArgs + "-Xopt-in=kotlin.RequiresOptIn"
+    }
+    buildTypes {
+        getByName("release") {
+            isMinifyEnabled = false
+            proguardFiles(getDefaultProguardFile("proguard-android.txt"))
+        }
+    }
+    buildFeatures {
+        viewBinding = true
+    }
+}
+
+afterEvaluate {
+    publishing {
+        publications {
+            create<MavenPublication>("release") {
+                from(components.getByName("release"))
+                groupId = "com.github.readium"
+                artifactId = "readium-navigator-media2"
+                artifact(tasks.findByName("sourcesJar"))
+                artifact(tasks.findByName("javadocsJar"))
+            }
+        }
+    }
+}
+
+dependencies {
+    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar"))))
+
+    api(project(":readium:shared"))
+    api(project(":readium:navigator"))
+
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.5.2")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.5.2")
+
+    implementation("com.jakewharton.timber:timber:5.0.1")
+
+    implementation("androidx.media2:media2-session:1.2.0")
+    implementation("androidx.media2:media2-player:1.2.0")
+
+    implementation("com.google.android.exoplayer:exoplayer-core:2.16.1")
+    implementation("com.google.android.exoplayer:extension-media2:2.16.1")
+
+    testImplementation("junit:junit:4.13.2")
+
+    androidTestImplementation("androidx.test.ext:junit:1.1.3")
+    androidTestImplementation("androidx.test.espresso:espresso-core:3.4.0")
+}

readium/navigator-media2/src/main/AndroidManifest.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="org.readium.navigator.media2">
+
+</manifest>

readium/navigator-media2/src/main/java/org/readium/navigator/media2/DefaultMetadataFactory.kt

@@ -0,0 +1,67 @@
+package org.readium.navigator.media2
+
+import android.graphics.Bitmap
+import androidx.media2.common.MediaMetadata
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Deferred
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.async
+import org.readium.r2.shared.publication.Publication
+import org.readium.r2.shared.publication.services.cover
+
+@ExperimentalMedia2
+internal class DefaultMetadataFactory(private val publication: Publication): MediaMetadataFactory {
+
+    private val coroutineScope =
+        CoroutineScope(Dispatchers.Default)
+
+    private val authors: String?
+        get() = publication.metadata.authors
+            .joinToString(", ") { it.name }.takeIf { it.isNotBlank() }
+
+    private val cover: Deferred<Bitmap?> = coroutineScope.async {
+        publication.cover()
+    }
+
+    override suspend fun publicationMetadata(): MediaMetadata {
+        val builder = MediaMetadata.Builder()
+            .putString(MediaMetadata.METADATA_KEY_TITLE, publication.metadata.title)
+            .putString(MediaMetadata.METADATA_KEY_ALBUM, publication.metadata.title)
+            .putLong(MediaMetadata.METADATA_KEY_NUM_TRACKS, publication.readingOrder.size.toLong())
+
+        authors
+            ?.let {
+                builder.putString(MediaMetadata.METADATA_KEY_AUTHOR,  it)
+                builder.putString(MediaMetadata.METADATA_KEY_ARTIST,  it)
+            }
+
+        publication.metadata.duration
+            ?.let { builder.putLong(MediaMetadata.METADATA_KEY_DURATION, it.toLong() * 1000) }
+
+        cover.await()
+            ?.let { builder.putBitmap(MediaMetadata.METADATA_KEY_ART, it)}
+
+        return builder.build()
+    }
+
+    override suspend fun resourceMetadata(index: Int): MediaMetadata {
+        // See the implementation for how each metadata is used in media2:
+        // https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:media2/media2-session/src/main/java/androidx/media2/session/MediaNotificationHandler.java;l=175?q=MediaNotificationHandler
+
+        val builder = MediaMetadata.Builder()
+        val link = publication.readingOrder[index]
+        builder.putLong(MediaMetadata.METADATA_KEY_TRACK_NUMBER, index.toLong())
+        builder.putString(MediaMetadata.METADATA_KEY_MEDIA_URI, link.href)
+        builder.putString(MediaMetadata.METADATA_KEY_TITLE, link.title)
+        builder.putString(MediaMetadata.METADATA_KEY_DISPLAY_SUBTITLE, publication.metadata.title)
+        builder.putString(MediaMetadata.METADATA_KEY_ALBUM, publication.metadata.title)
+        builder.putLong(MediaMetadata.METADATA_KEY_DURATION, (link.duration?.toLong() ?: 0) * 1000)
+
+        authors?.let {
+            builder.putString(MediaMetadata.METADATA_KEY_ARTIST, it)
+            builder.putString(MediaMetadata.METADATA_KEY_AUTHOR, it)
+        }
+        cover.await()?.let { builder.putBitmap(MediaMetadata.METADATA_KEY_ART, it)}
+        return builder.build()
+    }
+}

readium/navigator-media2/src/main/java/org/readium/navigator/media2/ExoPlayerDataSource.kt

@@ -0,0 +1,147 @@
+/*
+ * Copyright 2020 Readium Foundation. All rights reserved.
+ * Use of this source code is governed by the BSD-style license
+ * available in the top-level LICENSE file of the project.
+ */
+
+package org.readium.navigator.media2
+
+import android.net.Uri
+import com.google.android.exoplayer2.C.LENGTH_UNSET
+import com.google.android.exoplayer2.C.RESULT_END_OF_INPUT
+import com.google.android.exoplayer2.upstream.BaseDataSource
+import com.google.android.exoplayer2.upstream.DataSource
+import com.google.android.exoplayer2.upstream.DataSpec
+import com.google.android.exoplayer2.upstream.TransferListener
+import kotlinx.coroutines.runBlocking
+import org.readium.r2.shared.fetcher.Resource
+import org.readium.r2.shared.fetcher.buffered
+import org.readium.r2.shared.publication.Publication
+import java.io.IOException
+
+sealed class ExoPlayerDataSourceException(message: String, cause: Throwable?) : IOException(message, cause) {
+    class NotOpened(message: String) : ExoPlayerDataSourceException(message, null)
+    class NotFound(message: String) : ExoPlayerDataSourceException(message, null)
+    class ReadFailed(uri: Uri, offset: Int, readLength: Int, cause: Throwable) : ExoPlayerDataSourceException("Failed to read $readLength bytes of URI $uri at offset $offset.", cause)
+}
+
+/**
+ * An ExoPlayer's [DataSource] which retrieves resources from a [Publication].
+ */
+class ExoPlayerDataSource internal constructor(private val publication: Publication) : BaseDataSource(/* isNetwork = */ true) {
+
+    class Factory(private val publication: Publication, private val transferListener: TransferListener? = null) : DataSource.Factory {
+
+        override fun createDataSource(): DataSource =
+            ExoPlayerDataSource(publication).apply {
+                if (transferListener != null) {
+                    addTransferListener(transferListener)
+                }
+            }
+
+    }
+
+    private data class OpenedResource(
+        val resource: Resource,
+        val uri: Uri,
+        var position: Long,
+    )
+
+    private var openedResource: OpenedResource? = null
+
+    override fun open(dataSpec: DataSpec): Long {
+        val link = publication.linkWithHref(dataSpec.uri.toString())
+            ?: throw ExoPlayerDataSourceException.NotFound("Can't find a [Link] for URI: ${dataSpec.uri}. Make sure you only request resources declared in the manifest.")
+
+        val resource = publication.get(link)
+            // Significantly improves performances, in particular with deflated ZIP entries.
+            .buffered(resourceLength = cachedLengths[dataSpec.uri.toString()])
+
+        openedResource = OpenedResource(
+            resource = resource,
+            uri = dataSpec.uri,
+            position = dataSpec.position,
+        )
+
+        val bytesToRead =
+            if (dataSpec.length != LENGTH_UNSET.toLong()) {
+                dataSpec.length
+            } else {
+                val contentLength = contentLengthOf(dataSpec.uri, resource)
+                    ?: return dataSpec.length
+                contentLength - dataSpec.position
+            }
+
+        return bytesToRead
+    }
+
+    /** Cached content lengths indexed by their URL. */
+    private var cachedLengths: MutableMap<String, Long> = mutableMapOf()
+
+    private fun contentLengthOf(uri: Uri, resource: Resource): Long? {
+        cachedLengths[uri.toString()]?.let { return it }
+
+        val length = runBlocking { resource.length() }.getOrNull()
+            ?: return null
+
+        cachedLengths[uri.toString()] = length
+        return length
+    }
+
+    override fun read(target: ByteArray, offset: Int, length: Int): Int {
+        if (length <= 0) {
+            return 0
+        }
+
+        val openedResource = openedResource ?: throw ExoPlayerDataSourceException.NotOpened("No opened resource to read from. Did you call open()?")
+
+        try {
+            val data = runBlocking {
+                openedResource.resource
+                    .read(range = openedResource.position until (openedResource.position + length))
+                    .getOrThrow()
+            }
+
+            if (data.isEmpty()) {
+                return RESULT_END_OF_INPUT
+            }
+
+            data.copyInto(
+                destination = target,
+                destinationOffset = offset,
+                startIndex = 0,
+                endIndex = data.size
+            )
+
+            openedResource.position += data.count()
+            return data.count()
+
+        } catch (e: Exception) {
+            if (e is InterruptedException) {
+                return 0
+            }
+            throw ExoPlayerDataSourceException.ReadFailed(
+                uri = openedResource.uri,
+                offset = offset,
+                readLength = length,
+                cause = e
+            )
+        }
+    }
+
+    override fun getUri(): Uri? = openedResource?.uri
+
+    override fun close() {
+        openedResource?.run {
+            try {
+                runBlocking { resource.close() }
+            } catch (e: Exception) {
+                if (e !is InterruptedException) {
+                    throw e
+                }
+            }
+        }
+        openedResource = null
+    }
+
+}