fix(downloads): play every track of server-prepared downloads offline

android-shared/src/androidMain/kotlin/org/siloserver/silo/common/data/db/SiloDatabase.kt

@@ -56,7 +56,7 @@ import org.siloserver.silo.common.data.db.entity.UserItemStateEntity
         MembershipProjectionEntity::class,
         LegacyMembershipQuarantineEntity::class,
     ],
-    version = 12,
+    version = 13,
     exportSchema = true,
     autoMigrations = [
         AutoMigration(from = 1, to = 2),
@@ -69,6 +69,7 @@ import org.siloserver.silo.common.data.db.entity.UserItemStateEntity
         AutoMigration(from = 8, to = 9),
         AutoMigration(from = 10, to = 11),
         AutoMigration(from = 11, to = 12),
+        AutoMigration(from = 12, to = 13),
     ],
 )
 abstract class SiloDatabase : RoomDatabase() {

android-shared/src/androidMain/kotlin/org/siloserver/silo/common/data/db/entity/DownloadEntity.kt

@@ -82,4 +82,8 @@ data class DownloadEntity(
     /** Registry revision whose bytes this row describes. A local completion
      *  only speaks for this revision; null on rows written before v12. */
     val revision: Int? = null,
+    /** Serialized [org.siloserver.silo.model.download.OfflineTrackInfo]: the
+     *  downloaded file's audio tracks and the local subtitle sidecars. Null for
+     *  downloads completed before offline track data was captured. */
+    val offlineTracksJson: String? = null,
 )

android-shared/src/androidMain/kotlin/org/siloserver/silo/common/downloads/DownloadSidecarMapping.kt

@@ -4,6 +4,7 @@ import org.siloserver.silo.common.data.db.entity.DownloadEntity
 import org.siloserver.silo.model.catalog.VersionChapter
 import org.siloserver.silo.model.download.DownloadRecord
 import org.siloserver.silo.model.download.DownloadSidecar
+import org.siloserver.silo.model.download.OfflineTrackInfo
 import kotlinx.serialization.encodeToString
 import kotlinx.serialization.json.Json
 
@@ -58,6 +59,7 @@ fun DownloadSidecar.toEntity(serverId: String, profileId: String): DownloadEntit
         quality = record.quality,
         effectiveQuality = record.effectiveQuality,
         revision = record.revision,
+        offlineTracksJson = offlineTracks?.let { mappingJson.encodeToString(it) },
     )
 
 fun DownloadEntity.toSidecar(): DownloadSidecar =
@@ -97,5 +99,8 @@ fun DownloadEntity.toSidecar(): DownloadSidecar =
         durationSeconds = durationSeconds,
         chapters = chaptersJson?.let { runCatching { mappingJson.decodeFromString<List<VersionChapter>>(it) }.getOrNull() },
         resumeValidator = resumeValidator,
+        offlineTracks = offlineTracksJson?.let {
+            runCatching { mappingJson.decodeFromString<OfflineTrackInfo>(it) }.getOrNull()
+        },
         updatedAtMs = updatedAtMs,
     )

android-shared/src/androidMain/kotlin/org/siloserver/silo/common/downloads/DownloadStorage.kt

@@ -106,8 +106,10 @@ class DownloadStorage(
      * directories are left in place; cleanup at higher granularity goes
      * through [deleteAllForProfile] or [deleteAllForServer].
      */
-    fun delete(serverId: String, profileId: String, fileId: Int): Boolean =
-        publicStore.delete(serverId, profileId, fileId, uriString = null)
+    fun delete(serverId: String, profileId: String, fileId: Int): Boolean {
+        containedSafeChild(offlineAssetsRoot, serverId, profileId, fileId.toString())?.deleteRecursively()
+        return publicStore.delete(serverId, profileId, fileId, uriString = null)
+    }
 
     fun completeWrite(uriString: String): String =
         publicStore.complete(uriString)
@@ -133,12 +135,27 @@ class DownloadStorage(
 
     /** Wipes every downloaded byte under (serverId, profileId). Used on sign-out
      *  and profile switch. Metadata rows are cleared via [DownloadMetadataStore]. */
-    fun deleteAllForProfile(serverId: String, profileId: String): Boolean =
-        publicStore.deleteAllForProfile(serverId, profileId)
+    fun deleteAllForProfile(serverId: String, profileId: String): Boolean {
+        containedSafeChild(offlineAssetsRoot, serverId, profileId)?.deleteRecursively()
+        return publicStore.deleteAllForProfile(serverId, profileId)
+    }
 
     /** Wipes every downloaded byte under (serverId). Used on server delete / re-bind. */
-    fun deleteAllForServer(serverId: String): Boolean =
-        publicStore.deleteAllForServer(serverId)
+    fun deleteAllForServer(serverId: String): Boolean {
+        containedSafeChild(offlineAssetsRoot, serverId)?.deleteRecursively()
+        return publicStore.deleteAllForServer(serverId)
+    }
+
+    /**
+     * Private directory for the offline subtitle sidecars of one download.
+     * Kept in app-internal storage rather than beside the (public, possibly
+     * MediaStore-owned) media file: they are only meaningful to this app, and
+     * a scoped directory is removed with the download by [delete].
+     */
+    fun offlineSubtitleDirectory(serverId: String, profileId: String, fileId: Int): File? =
+        containedSafeChild(offlineAssetsRoot, serverId, profileId, fileId.toString(), SUBTITLES_DIR)
+
+    private val offlineAssetsRoot: File get() = File(baseDir, OFFLINE_ASSETS_DIR)
 
     /** Sum of bytes across every downloaded file under this storage. */
     fun totalBytesUsed(): Long = publicStore.totalBytesUsed()
@@ -170,6 +187,10 @@ class DownloadStorage(
     private fun sanitizeBasename(value: String): String =
         value.replace(Regex("[\\\\/:*?\"<>|]"), "_")
 
+    private companion object {
+        const val OFFLINE_ASSETS_DIR = "download-assets"
+        const val SUBTITLES_DIR = "subtitles"
+    }
 }
 
 data class DownloadTarget(

android-shared/src/androidMain/kotlin/org/siloserver/silo/common/downloads/DownloadWorker.kt

@@ -92,6 +92,7 @@ class DownloadWorker(
 ) : CoroutineWorker(appContext, params) {
 
     private var transferAuthority: DurableLoginAuthority? = null
+    private val offlineTrackFetcher = OfflineTrackAssetFetcher(httpClient, storage)
     private suspend fun requireOwner() {
         if (authorities != null && (transferAuthority == null || transferAuthority != authorities.snapshotDurableLoginAuthority() || inputData.getString(KEY_DEVICE_ID) != devices?.current()?.id)) throw DownloadOwnerChanged()
     }
@@ -144,8 +145,32 @@ class DownloadWorker(
         }.onFailure { Log.w(TAG, "setForeground initial failed", it) }
 
         var activeUri: String? = null
+        // Capture can outlive media publication. A stop then preserves the
+        // completed file and its queued completion report.
+        var mediaPublished = false
+
         try {
             var existing = runCatching { metadataStore.readSidecar(serverId, profileId, fileId) }.getOrNull()
+            // A stopped capture resumes from the completed local file, including
+            // legacy rows whose original transfer revision is unknown.
+            if (existing != null && existing.record.id == downloadId &&
+                existing.record.statusEnum() == DownloadStatus.Completed &&
+                storage.locateLocalMedia(serverId, profileId, fileId) != null
+            ) {
+                mediaPublished = true
+                requireOwner()
+                // Publication and status enqueue are separate durable writes.
+                // Recover a stop between them using the revision of these bytes.
+                reportStatus(
+                    downloadId, DownloadStatus.Completed,
+                    maxOf(System.currentTimeMillis(), existing.updatedAtMs + 1),
+                    existing.record.revision?.takeIf { it > 0 }, serverId, profileId,
+                )
+                if (existing.offlineTracks == null) {
+                    captureOfflineTracks(downloadId, serverId, profileId, fileId, mediaType)
+                }
+                return@withContext Result.success()
+            }
             // Old WorkManager jobs have no revision input. Resolve it as their owner
             // and save it in Room so another attempt does not depend on a UI cache.
             val revision = inputData.getInt(KEY_REVISION, 0).takeIf { it > 0 }
@@ -335,6 +360,7 @@ class DownloadWorker(
                 )
                 true
             }
+            mediaPublished = true
             Log.i(TAG, "doWork success id=$downloadId bytes=$finalBytes")
             DiagnosticsDownloadLogger.event("download completed")
             // Strictly after the `downloading` event: the server ignores an event
@@ -355,6 +381,7 @@ class DownloadWorker(
             }
             // The v2 file route never marks the entry completed; this report does.
             reportStatus(downloadId, DownloadStatus.Completed, completedAtMs, revision, serverId, profileId)
+            captureOfflineTracks(downloadId, serverId, profileId, fileId, mediaType)
             Result.success(workDataOf(KEY_BYTES_WRITTEN to finalBytes, KEY_TOTAL_BYTES to finalBytes))
         } catch (e: DownloadOwnerChanged) {
             // Preserve the original owner's partial; a new login cannot resume it.
@@ -371,7 +398,7 @@ class DownloadWorker(
             // downloads with a red badge and delete-then-fail them.
             Log.i(TAG, "doWork cancelled id=$downloadId")
             DiagnosticsDownloadLogger.event("download cancelled")
-            withContext(NonCancellable) {
+            if (!mediaPublished) withContext(NonCancellable) {
                 // WorkManager's notification action cancels this transfer directly.
                 // Its separate status job must stop before we remove the bytes.
                 runCatching { DownloadStatusWorker.cancel(appContext, downloadId) }
@@ -450,6 +477,43 @@ class DownloadWorker(
         }.onFailure { Log.w(TAG, "status report enqueue failed id=$downloadId status=${status.wire}", it) }
     }
 
+    /**
+     * Fetches the offline manifest's audio tracks and subtitle sidecars for a
+     * published video download and stores them on its metadata row. Best
+     * effort: every failure leaves the download playable the legacy way.
+     */
+    private suspend fun captureOfflineTracks(
+        downloadId: String,
+        serverId: String,
+        profileId: String,
+        fileId: Int,
+        mediaType: String?,
+    ) {
+        if (!OfflineTrackAssetFetcher.appliesTo(mediaType)) return
+        try {
+            requireOwner()
+            val tracks = offlineTrackFetcher.fetch(downloadId, serverId, profileId, fileId) {
+                transferAuthority?.let { managedDownloadAuth(it.scope) }
+            } ?: return
+            ownedWrite {
+                val existing = metadataStore.readSidecar(serverId, profileId, fileId)
+                    ?.takeIf { it.record.id == downloadId }
+                if (existing != null) {
+                    metadataStore.writeSidecar(
+                        serverId, profileId,
+                        existing.copy(offlineTracks = tracks, updatedAtMs = System.currentTimeMillis()),
+                    )
+                }
+                true
+            }
+            Log.i(TAG, "offline tracks captured id=$downloadId audio=${tracks.audioTracks.size} subtitles=${tracks.subtitles.size}")
+        } catch (e: CancellationException) {
+            throw e
+        } catch (e: Exception) {
+            Log.w(TAG, "offline track capture skipped id=$downloadId", e)
+        }
+    }
+
     /** Permanent failure — clean up local file and let the user retry manually. */
     private suspend fun failPermanently(
         e: Throwable,

android-shared/src/androidMain/kotlin/org/siloserver/silo/common/downloads/OfflineTrackAssetFetcher.kt

@@ -0,0 +1,176 @@
+package org.siloserver.silo.common.downloads
+
+import android.util.Log
+import io.ktor.client.HttpClient
+import io.ktor.client.plugins.HttpTimeoutConfig
+import io.ktor.client.plugins.timeout
+import io.ktor.client.request.HttpRequestBuilder
+import io.ktor.client.request.get
+import io.ktor.client.request.prepareGet
+import io.ktor.client.statement.bodyAsChannel
+import io.ktor.client.statement.bodyAsText
+import io.ktor.http.HttpStatusCode
+import io.ktor.http.encodeURLPathPart
+import io.ktor.utils.io.jvm.javaio.toInputStream
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.delay
+import org.siloserver.silo.model.download.DownloadMediaType
+import org.siloserver.silo.model.download.OfflineManifestTracks
+import org.siloserver.silo.model.download.OfflineManifestSubtitle
+import org.siloserver.silo.model.download.OfflineSubtitleFile
+import org.siloserver.silo.model.download.OfflineTrackInfo
+import org.siloserver.silo.model.download.decodeOfflineManifestTracks
+import org.siloserver.silo.model.download.isOfflineSubtitleFetchUrl
+import org.siloserver.silo.model.download.offlineSubtitleExtension
+import org.siloserver.silo.model.download.offlineSubtitleFormat
+import org.siloserver.silo.model.download.toOfflineTrackInfo
+import org.siloserver.silo.playback.orNullIfBlank
+import java.io.File
+import java.io.IOException
+
+/**
+ * Captures what offline video playback needs once the media bytes are down:
+ * the offline manifest's audio tracks (positions inside the delivered file) and
+ * the subtitle sidecars it lists, each fetched once into private storage.
+ *
+ * Everything here is best effort. A missing manifest, an older server, or a
+ * sidecar that fails to fetch never fails the video download; the download
+ * then plays with whatever was captured (or the legacy offline behaviour).
+ */
+internal class OfflineTrackAssetFetcher(
+    private val httpClient: HttpClient,
+    private val storage: DownloadStorage,
+    private val manifestRetryDelayMs: Long = 2_000,
+) {
+    suspend fun fetch(
+        downloadId: String,
+        serverId: String,
+        profileId: String,
+        fileId: Int,
+        configure: HttpRequestBuilder.() -> Unit,
+    ): OfflineTrackInfo? {
+        val manifest = fetchManifest(downloadId, configure) ?: return null
+
+        val directory = storage.offlineSubtitleDirectory(serverId, profileId, fileId)
+        // A replaced download (new revision) must not keep the previous
+        // revision's sidecars around under the same file slot.
+        directory?.deleteRecursively()
+        val saved = if (directory == null || manifest.subtitles.isEmpty()) {
+            emptyList()
+        } else {
+            manifest.subtitles.mapIndexedNotNull { ordinal, subtitle ->
+                fetchSubtitle(downloadId, ordinal, subtitle, directory, configure)
+            }
+        }
+        return manifest.toOfflineTrackInfo(saved)
+    }
+
+    /**
+     * The capture runs once, right after the download completes, so a network
+     * blip or a transient server error is retried briefly here; a missing
+     * manifest (older server) is not.
+     */
+    private suspend fun fetchManifest(
+        downloadId: String,
+        configure: HttpRequestBuilder.() -> Unit,
+    ): OfflineManifestTracks? {
+        repeat(MANIFEST_ATTEMPTS) { attempt ->
+            if (attempt > 0) delay(manifestRetryDelayMs * attempt)
+            try {
+                val response = httpClient.get("/api/v2/downloads/${downloadId.encodeURLPathPart()}/manifest") {
+                    configure()
+                }
+                val status = response.status
+                if (status == HttpStatusCode.OK) return decodeOfflineManifestTracks(response.bodyAsText())
+                Log.i(TAG, "manifest unavailable id=$downloadId status=${status.value}")
+                if (status.value < 500 && status != HttpStatusCode.TooManyRequests) return null
+            } catch (e: CancellationException) {
+                throw e
+            } catch (e: Exception) {
+                Log.w(TAG, "manifest fetch failed id=$downloadId attempt=${attempt + 1}", e)
+            }
+        }
+        return null
+    }
+
+    private suspend fun fetchSubtitle(
+        downloadId: String,
+        ordinal: Int,
+        subtitle: OfflineManifestSubtitle,
+        directory: File,
+        configure: HttpRequestBuilder.() -> Unit,
+    ): OfflineSubtitleFile? {
+        val format = offlineSubtitleFormat(subtitle.format) ?: return null
+        if (!isOfflineSubtitleFetchUrl(subtitle.fetchUrl)) {
+            Log.w(TAG, "skipping subtitle with unexpected reference id=$downloadId ordinal=$ordinal")
+            return null
+        }
+        val target = File(directory, "$ordinal.${offlineSubtitleExtension(format)}")
+        val partial = File(directory, "$ordinal.part")
+        return try {
+            if (!directory.isDirectory && !directory.mkdirs()) throw IOException("could not create $directory")
+            httpClient.prepareGet(subtitle.fetchUrl.trim()) {
+                configure()
+                // Embedded ASS/PGS sidecars are extracted from the source on
+                // demand, so the first byte can take a while; keep only an idle
+                // timeout, like the media transfer itself.
+                timeout {
+                    requestTimeoutMillis = HttpTimeoutConfig.INFINITE_TIMEOUT_MS
+                    socketTimeoutMillis = SUBTITLE_IDLE_TIMEOUT_MS
+                }
+            }.execute { response ->
+                if (response.status != HttpStatusCode.OK) {
+                    throw IOException("HTTP ${response.status.value}")
+                }
+                var written = 0L
+                response.bodyAsChannel().toInputStream().use { input ->
+                    partial.outputStream().use { output ->
+                        val buffer = ByteArray(BUFFER_BYTES)
+                        while (true) {
+                            val read = input.read(buffer)
+                            if (read < 0) break
+                            written += read
+                            if (written > MAX_SUBTITLE_BYTES) throw IOException("subtitle exceeds $MAX_SUBTITLE_BYTES bytes")
+                            output.write(buffer, 0, read)
+                        }
+                    }
+                }
+                if (written == 0L) throw IOException("empty subtitle")
+            }
+            if (!partial.renameTo(target)) throw IOException("could not publish $target")
+            OfflineSubtitleFile(
+                path = target.absolutePath,
+                format = format,
+                language = subtitle.language.orNullIfBlank(),
+                title = subtitle.title.orNullIfBlank(),
+                forced = subtitle.forced,
+                hearingImpaired = subtitle.hearingImpaired,
+            )
+        } catch (e: CancellationException) {
+            partial.delete()
+            throw e
+        } catch (e: Exception) {
+            Log.w(TAG, "subtitle fetch failed id=$downloadId ordinal=$ordinal format=$format", e)
+            partial.delete()
+            target.delete()
+            null
+        }
+    }
+
+    companion object {
+        private const val TAG = "OfflineTrackAssets"
+        private const val MANIFEST_ATTEMPTS = 3
+        private const val BUFFER_BYTES = 64 * 1024
+        private const val SUBTITLE_IDLE_TIMEOUT_MS = 120_000L
+
+        /** PGS tracks for a feature run to tens of MB; text is far smaller. */
+        private const val MAX_SUBTITLE_BYTES = 256L * 1024 * 1024
+
+        /** Only video downloads have tracks to capture. */
+        fun appliesTo(mediaType: String?): Boolean =
+            when (DownloadMediaType.fromWire(mediaType)) {
+                DownloadMediaType.Movie, DownloadMediaType.TvShow, DownloadMediaType.Unknown -> true
+                DownloadMediaType.Audiobook, DownloadMediaType.Ebook -> false
+            }
+    }
+}