@pictor-sdk/video-android 0.1.0 → 0.1.3

package/android/src/main/java/dev/pictor/video/GateLadder.kt

@@ -0,0 +1,405 @@
+package dev.pictor.video
+
+import android.content.Context
+import android.os.Handler
+import android.os.HandlerThread
+import android.util.Log
+import androidx.media3.common.C
+import androidx.media3.common.Effect
+import androidx.media3.common.MediaItem
+import androidx.media3.common.audio.SpeedProvider
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.transformer.Composition
+import androidx.media3.transformer.EditedMediaItem
+import androidx.media3.transformer.EditedMediaItemSequence
+import androidx.media3.transformer.ExportException
+import androidx.media3.transformer.ExportResult
+import androidx.media3.transformer.Effects
+import androidx.media3.transformer.Transformer
+import com.google.common.collect.ImmutableList
+import java.io.File
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * The smallest Media3 export that fails, found one stage at a time.
+ *
+ * ## Why this is not `ExportGate`
+ *
+ * `ExportGate.runSequence` can already be told to add or omit each stage, and
+ * using it would have been less code. It would also have kept every one of the
+ * things this is trying to rule out: the run registry, the dedicated
+ * Transformer looper, the heartbeat, the resource ledger, the stall watchdog,
+ * the channel mixer, the forced audio track, the temporary-file bookkeeping and
+ * the concatenation that follows. A reproduction that carries the suspect along
+ * with it is not a reproduction.
+ *
+ * So rung 1 here is a plain `Transformer` over one clipped `MediaItem` with no
+ * effects and no speed — about twenty lines of Media3, and nothing of Pictor's.
+ * Each later rung adds exactly one stage to that, and every rung runs
+ * independently against its own uniquely named output. The first rung that does
+ * not complete is the answer.
+ *
+ * ## Rates and spans are given, never derived
+ *
+ * A slider label is not a rate. The caller passes the configured speed, the
+ * source span in microseconds, and — for the cadence rungs — the emission plan
+ * `resampleClip` compiled in TypeScript, so what runs here is what production
+ * would have run rather than a second opinion about it.
+ *
+ * Diagnostics-only, like the rest of the gate family: the entry point refuses
+ * on its first statement without [Diagnostics.ENABLED].
+ */
+@UnstableApi
+internal object GateLadder {
+
+    /** What one rung is allowed to switch on. Nothing else varies between them. */
+    private class Rung(
+        val name: String,
+        val speed: Boolean,
+        val cadence: Boolean,
+        val skia: Boolean,
+        /**
+         * The audio processors `ExportGate` puts on every shard.
+         *
+         * A channel mixer, so shards can be concatenated by copying samples,
+         * and Sonic with the reciprocal pitch, so a rate change does not turn a
+         * voice into a tape effect. Neither is about the picture, and both sit
+         * on the audio path a sped-up item is re-timed through — which is the
+         * one part of a production shard the rungs above still do not have.
+         */
+        val audioProcessors: String = "none",
+    )
+
+    private val RUNGS = listOf(
+        // The floor: is a plain transcode of this span sound at all?
+        Rung("plain", speed = false, cadence = false, skia = false),
+        // One stage each, against that floor.
+        Rung("speed", speed = true, cadence = false, skia = false),
+        Rung("cadence", speed = false, cadence = true, skia = false),
+        Rung("skia", speed = false, cadence = false, skia = true),
+        // Then the pairs, and finally what production actually builds.
+        Rung("speed+cadence", speed = true, cadence = true, skia = false),
+        Rung("speed+cadence+skia", speed = true, cadence = true, skia = true),
+        // Everything a production shard's Transformer is built with, and then
+        // each of the two audio processors on its own — because "both of them
+        // together" names a pair, not a cause.
+        Rung("production", speed = true, cadence = true, skia = true, audioProcessors = "both"),
+        Rung("prod-mixer", speed = true, cadence = true, skia = true, audioProcessors = "mixer"),
+        Rung("prod-sonic", speed = true, cadence = true, skia = true, audioProcessors = "sonic"),
+    )
+
+    /** A constant rate, exactly as `ExportGate` declares one. */
+    private class ConstantSpeed(private val speed: Float) : SpeedProvider {
+        override fun getSpeed(timeUs: Long): Float = speed
+        override fun getNextSpeedChangeTimeUs(timeUs: Long): Long = C.TIME_UNSET
+    }
+
+    /**
+     * Run the ladder and report every rung.
+     *
+     * `specJson` is `{ uri, startUs, endUs, speed, timeoutSeconds?,
+     * emitsPerInput?: number[], outputPtsUs?: number[], only?: string[] }`.
+     *
+     * Every rung runs even after one fails. "The first failing configuration"
+     * is a claim about an ordering, and stopping at the first failure would
+     * leave no evidence about whether the later ones fail for the same reason
+     * or a different one.
+     */
+    /** The one thread a ladder runs on, so two cannot overlap. */
+    private val worker = java.util.concurrent.Executors.newSingleThreadExecutor { r ->
+        Thread(r, "pictor-ladder").also { it.isDaemon = true }
+    }
+
+    @Volatile
+    private var running = false
+
+    /**
+     * Start a ladder in the background and report the result to logcat.
+     *
+     * Not synchronous, because the caller is the JavaScript thread: six rungs
+     * with a bounded wait each is minutes of it, and a blocked JS thread is an
+     * app that cannot be observed while the thing under investigation runs. The
+     * result arrives as one `PictorLadder` line, which is also how it is read.
+     */
+    fun start(context: Context, specJson: String): String {
+        if (running) {
+            return JSONObject().put("ok", false).put("error", "a ladder is already running")
+                .toString()
+        }
+        running = true
+        worker.execute {
+            val out = try {
+                run(context, specJson)
+            } catch (e: Throwable) {
+                JSONObject().put("ok", false)
+                    .put("error", e.javaClass.simpleName + ": " + e.message).toString()
+            } finally {
+                running = false
+            }
+            Log.i("PictorLadder", out)
+        }
+        return JSONObject().put("ok", true).put("started", true).toString()
+    }
+
+    fun run(context: Context, specJson: String): String {
+        val spec = try {
+            JSONObject(specJson)
+        } catch (e: Exception) {
+            return JSONObject().put("ok", false).put("error", "bad spec: " + e.message).toString()
+        }
+        val uri = spec.optString("uri")
+        if (uri.isEmpty()) {
+            return JSONObject().put("ok", false).put("error", "no uri").toString()
+        }
+        val startUs = spec.optLong("startUs", 0)
+        val endUs = spec.optLong("endUs", 0)
+        val speed = spec.optDouble("speed", 1.0).toFloat()
+        val timeoutSeconds = spec.optLong("timeoutSeconds", 90)
+        val emits = spec.optJSONArray("emitsPerInput")?.let { a ->
+            IntArray(a.length()) { a.getInt(it) }
+        }
+        val pts = spec.optJSONArray("outputPtsUs")?.let { a ->
+            LongArray(a.length()) { a.getLong(it) }
+        }
+        val only = spec.optJSONArray("only")?.let { a ->
+            (0 until a.length()).map { a.getString(it) }.toSet()
+        }
+        /*
+          The two settings a shard is built with, and the reason they are here.
+
+          `ExportGate` forces an audio track onto every shard and drops the
+          source's own, because Media3 drives its speed path through audio and a
+          video-only item at any rate but 1 aborts with "no output sample
+          written". A ladder that omitted them would reproduce *that* known
+          failure and call it the stall. Both default to off — the minimal run
+          is the one with nothing added — and a second run turns them on, so the
+          difference between them is a measurement rather than an assumption.
+        */
+        val forceAudioTrack = spec.optBoolean("forceAudioTrack", false)
+        val removeAudio = spec.optBoolean("removeAudio", false)
+
+        val results = JSONArray()
+        var firstFailure: String? = null
+        for (rung in RUNGS) {
+            if (only != null && !only.contains(rung.name)) continue
+            if (rung.cadence && (emits == null || pts == null)) {
+                results.put(
+                    JSONObject().put("rung", rung.name).put("ok", false)
+                        .put("error", "no emission plan supplied"),
+                )
+                continue
+            }
+            val one = runRung(
+                context, rung, uri, startUs, endUs, speed, emits, pts, timeoutSeconds,
+                forceAudioTrack, removeAudio,
+            )
+            // Per rung, not only at the end: a ladder killed part-way through
+            // still has to have said what it learned before it was.
+            Log.i("PictorLadderRung", one.toString())
+            results.put(one)
+            if (!one.optBoolean("ok") && firstFailure == null) firstFailure = rung.name
+        }
+        return JSONObject()
+            .put("ok", firstFailure == null)
+            .put("speed", speed.toDouble())
+            .put("startUs", startUs)
+            .put("endUs", endUs)
+            .put("firstFailure", firstFailure ?: "")
+            .put("forceAudioTrack", forceAudioTrack)
+            .put("removeAudio", removeAudio)
+            .put("rungs", results)
+            .toString()
+    }
+
+    private fun runRung(
+        context: Context,
+        rung: Rung,
+        uri: String,
+        startUs: Long,
+        endUs: Long,
+        speed: Float,
+        emits: IntArray?,
+        pts: LongArray?,
+        timeoutSeconds: Long,
+        forceAudioTrack: Boolean,
+        removeAudio: Boolean,
+    ): JSONObject {
+        /*
+          A fresh looper per rung, and joined before returning.
+
+          Not for tidiness: a rung that times out leaves a Transformer holding
+          codecs on the thread that built it, and reusing one looper would let
+          the next rung's failure be the previous rung's leftovers. Each rung
+          gets a thread that is only ever used for it, and whether that thread
+          was still alive at the end is reported rather than assumed.
+        */
+        val thread = HandlerThread("pictor-ladder-" + rung.name.replace('+', '-'))
+        thread.start()
+        val handler = Handler(thread.looper)
+
+        /*
+          The app's external files directory, not the cache.
+
+          A rung's output has to be read back off the device, and the build this
+          runs in is a release one — not debuggable, so `run-as` cannot reach
+          internal storage. The external files directory needs no permission,
+          nothing scans it, and `adb pull` can read it. Unique by construction,
+          so an older file can never be read as this run's result.
+        */
+        val dir = File(context.getExternalFilesDir(null) ?: context.cacheDir, "pictor-ladder")
+        dir.mkdirs()
+        val output = File.createTempFile(
+            "ladder-" + rung.name.replace('+', '-') + "-" + System.nanoTime() + "-", ".mp4", dir,
+        )
+
+        val latch = CountDownLatch(1)
+        var result: ExportResult? = null
+        var failure: ExportException? = null
+        var buildError: String? = null
+        val cadenceEffect = if (rung.cadence && emits != null && pts != null) {
+            CadenceEffect(emits, pts)
+        } else {
+            null
+        }
+        val skiaEffect = if (rung.skia) SkiaPassThroughEffect() else null
+
+        val startedNs = System.nanoTime()
+        var transformer: Transformer? = null
+        handler.post {
+            try {
+                val media = MediaItem.Builder()
+                    .setUri(uri)
+                    .setClippingConfiguration(
+                        MediaItem.ClippingConfiguration.Builder()
+                            .setStartPositionUs(startUs)
+                            .setEndPositionUs(endUs)
+                            .build(),
+                    )
+                    .build()
+                val video = ArrayList<Effect>()
+                cadenceEffect?.let { video.add(it) }
+                skiaEffect?.let { video.add(it as Effect) }
+                val audio = ArrayList<androidx.media3.common.audio.AudioProcessor>()
+                if (rung.audioProcessors == "both" || rung.audioProcessors == "mixer") {
+                    val mixer = androidx.media3.common.audio.ChannelMixingAudioProcessor()
+                    for (inChannels in 1..2) {
+                        mixer.putChannelMixingMatrix(
+                            androidx.media3.common.audio.ChannelMixingMatrix
+                                .createForConstantPower(inChannels, 2),
+                        )
+                    }
+                    audio.add(mixer)
+                }
+                if ((rung.audioProcessors == "both" || rung.audioProcessors == "sonic") &&
+                    rung.speed
+                ) {
+                    // The reciprocal, exactly as `ExportGate` composes it: the
+                    // resampling moved tempo and pitch together, and this puts
+                    // the pitch back.
+                    val sonic = androidx.media3.common.audio.SonicAudioProcessor()
+                    sonic.setPitch(1f / speed)
+                    audio.add(sonic)
+                }
+                val edited = EditedMediaItem.Builder(media)
+                    .also { if (removeAudio) it.setRemoveAudio(true) }
+                    .also { if (rung.speed) it.setSpeed(ConstantSpeed(speed)) }
+                    .setEffects(
+                        Effects(ImmutableList.copyOf(audio), ImmutableList.copyOf(video)),
+                    )
+                    .build()
+                val sequence = EditedMediaItemSequence.Builder()
+                    .also { if (forceAudioTrack) it.experimentalSetForceAudioTrack(true) }
+                    .addItem(edited)
+                    .build()
+                val composition = Composition.Builder(sequence).build()
+                val built = Transformer.Builder(context)
+                    .addListener(object : Transformer.Listener {
+                        override fun onCompleted(c: Composition, r: ExportResult) {
+                            result = r
+                            latch.countDown()
+                        }
+
+                        override fun onError(c: Composition, r: ExportResult, e: ExportException) {
+                            failure = e
+                            latch.countDown()
+                        }
+                    })
+                    .build()
+                transformer = built
+                built.start(composition, output.absolutePath)
+            } catch (e: Throwable) {
+                buildError = e.javaClass.simpleName + ": " + e.message
+                latch.countDown()
+            }
+        }
+
+        val finished = latch.await(timeoutSeconds, TimeUnit.SECONDS)
+        val elapsedMs = (System.nanoTime() - startedNs) / 1_000_000
+
+        /*
+          A timed-out rung is cancelled, and the cancel is *not* waited on here.
+
+          `Transformer.cancel()` joins the internal threads and can itself block
+          indefinitely when the encoder never finishes — which is the condition
+          under investigation. Posting it and reporting whether the post was
+          answered distinguishes "cleaned up" from "still wedged" instead of
+          hanging the ladder on the fault it is measuring.
+        */
+        var cancelReturned = false
+        if (!finished) {
+            val cancelled = CountDownLatch(1)
+            handler.post {
+                try {
+                    transformer?.cancel()
+                } catch (_: Throwable) {
+                }
+                cancelled.countDown()
+            }
+            cancelReturned = cancelled.await(10, TimeUnit.SECONDS)
+        }
+
+        val report = JSONObject()
+            .put("rung", rung.name)
+            .put("ok", finished && failure == null && buildError == null)
+            .put("elapsedMs", elapsedMs)
+            .put("timedOut", !finished)
+            .put("cancelReturned", cancelReturned)
+            .put(
+                "error",
+                buildError
+                    ?: failure?.let { it.errorCode.toString() + ": " + (it.cause?.message ?: it.message) }
+                    ?: if (!finished) "timeout after " + timeoutSeconds + "s" else "",
+            )
+            .put("videoFrameCount", result?.videoFrameCount ?: -1)
+            .put("durationMs", result?.durationMs ?: -1)
+            .put("videoEncoder", result?.videoEncoderName ?: "")
+            .put("audioEncoder", result?.audioEncoderName ?: "")
+            .put("outputBytes", if (output.exists()) output.length() else -1)
+            .put("output", output.absolutePath)
+            .put("cadenceTrace", cadenceEffect?.trace() ?: "")
+            .put("skiaFrames", skiaEffect?.framesSeen() ?: -1)
+
+        /*
+          Whether the rung's thread is still occupied is part of the result.
+
+          `quitSafely` returns immediately; the thread only ends once the looper
+          drains. A thread still alive a second later is one still inside
+          something — a blocked `cancel`, an encoder wait — and that is the
+          cleanup evidence a frame count cannot give.
+        */
+        thread.quitSafely()
+        thread.join(1_000)
+        report.put("threadStillAlive", thread.isAlive)
+        if (finished && failure == null && buildError == null) {
+            report.put("keptOutput", true)
+        } else {
+            // A failed rung's partial file is not a result; nothing may read it.
+            output.delete()
+            report.put("keptOutput", false)
+        }
+        return report
+    }
+}

package/android/src/main/java/dev/pictor/video/MediaStoreSave.kt

@@ -1,17 +1,26 @@
 package dev.pictor.video
 
+import android.Manifest
 import android.content.ContentValues
 import android.content.Context
+import android.content.pm.PackageManager
 import android.media.MediaExtractor
 import android.media.MediaFormat
+import android.media.MediaScannerConnection
 import android.net.Uri
+import android.os.Build
+import android.os.Environment
 import android.provider.MediaStore
+import androidx.annotation.RequiresApi
 import org.json.JSONObject
 import java.io.File
 import java.io.FileInputStream
+import java.io.FileOutputStream
 import java.text.SimpleDateFormat
 import java.util.Date
 import java.util.Locale
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
 import java.util.concurrent.atomic.AtomicBoolean
 
 /**
@@ -29,15 +38,23 @@ import java.util.concurrent.atomic.AtomicBoolean
  * Every unsuccessful path deletes the row. A pending row nobody deletes is
  * invisible and still occupies storage, which is the worst of both.
  *
- * ## There is no legacy branch, and that is a decision
+ * ## Two paths, because `IS_PENDING` arrived in API 29
  *
- * `IS_PENDING` and `RELATIVE_PATH` arrived in API 29, and this module's
- * `minSdk` is 29 — checked, not assumed. So the pre-scoped-storage path
- * (`WRITE_EXTERNAL_STORAGE`, a real path under `Environment`, a scanner poke)
- * is not a branch this can reach on any supported device. It is **rejected
- * rather than written**: an untestable branch guarding a version nobody runs is
- * a liability, and lowering `minSdk` to make it reachable would be changing the
- * module's support claim to justify code.
+ * On 29 and above the pending row above is the whole story. Below it there is no
+ * `IS_PENDING` and no `RELATIVE_PATH`, so the same guarantee is built out of the
+ * filesystem: the bytes stream into a **dot-prefixed** file, which the media
+ * scanner ignores, and only a completed, verified file is renamed into place and
+ * handed to the scanner. Nothing partial is ever visible on either path, which is
+ * the property that matters — the mechanism differs because the platform does.
+ *
+ * The legacy path needs `WRITE_EXTERNAL_STORAGE`, which is why this module's
+ * manifest declares it with `maxSdkVersion="28"`. It disappears on every device
+ * that has scoped storage, and the save reports a specific, actionable error
+ * rather than throwing when a host has not asked for it.
+ *
+ * This branch exists on paper until an API 24..28 device or emulator runs it.
+ * Until then `minSdk 24` is a *build* claim, not a verified one — see
+ * `docs/research/min-sdk-24.md`.
  *
  * ## What it will not do
  *
@@ -59,6 +76,19 @@ internal object MediaStoreSave {
      */
     private const val RELATIVE_PATH_STORED = "Movies/Pictor/"
 
+    /** The same folder as {@link RELATIVE_PATH}, as a name under `Movies`. */
+    private const val LEGACY_FOLDER = "Pictor"
+
+    /**
+     * What an unfinished legacy save is called.
+     *
+     * The leading dot is what hides it — the media scanner skips dot-prefixed
+     * files — and the suffix is what a sweep matches on. Both are needed: the dot
+     * keeps it out of the gallery, the suffix keeps the sweep from deleting
+     * something a person put there.
+     */
+    private const val LEGACY_PENDING_SUFFIX = ".part"
+
     /**
      * The names this writes, and only those.
      *
@@ -120,6 +150,9 @@ internal object MediaStoreSave {
             // Named, not pathed: the caller knows what it asked to save.
             return out.put("ok", false).put("error", "the export file is no longer available").toString()
         }
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.Q) {
+            return saveLegacy(context, jobId, source, cancelled, out)
+        }
 
         val name = displayName()
         val values = ContentValues().apply {
@@ -199,6 +232,144 @@ internal object MediaStoreSave {
         }
     }
 
+    /**
+     * The same guarantee without `IS_PENDING`, for API 24..28.
+     *
+     * A dot-prefixed file is skipped by the media scanner, so it stands in for
+     * the pending row: the bytes stream into `.Pictor-….mp4.part`, the result is
+     * verified, and only then is it renamed to its real name and scanned. A
+     * half-written video is never in the gallery, and a failed or cancelled save
+     * leaves nothing behind — the same two properties the 29+ path has, built
+     * out of what the platform offered at the time.
+     *
+     * The order matters. Renaming before verifying would make a truncated file
+     * visible for as long as the check took, and scanning before renaming would
+     * index the temporary name.
+     */
+    private fun saveLegacy(
+        context: Context,
+        jobId: String,
+        source: File,
+        cancelled: AtomicBoolean,
+        out: JSONObject,
+    ): String {
+        /*
+          Asked for, not assumed.
+
+          Writing to shared storage below API 29 needs WRITE_EXTERNAL_STORAGE,
+          and a host that has not requested it gets a sentence it can act on
+          rather than a SecurityException from inside a copy loop. The adapter
+          declares the permission (capped at 28); asking the user for it is the
+          host's, because the host owns the moment to ask.
+        */
+        if (
+            context.checkSelfPermission(Manifest.permission.WRITE_EXTERNAL_STORAGE) !=
+            PackageManager.PERMISSION_GRANTED
+        ) {
+            forget(jobId)
+            return out
+                .put("ok", false)
+                .put("needsPermission", Manifest.permission.WRITE_EXTERNAL_STORAGE)
+                .put("error", "saving to the gallery on this Android version needs storage permission")
+                .toString()
+        }
+
+        val folder = File(
+            Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_MOVIES),
+            LEGACY_FOLDER,
+        )
+        if (!folder.exists() && !folder.mkdirs()) {
+            forget(jobId)
+            return out.put("ok", false).put("error", "the gallery folder could not be created").toString()
+        }
+
+        val name = displayName()
+        val pending = File(folder, ".$name$LEGACY_PENDING_SUFFIX")
+        val target = File(folder, name)
+
+        /** Nothing partial survives: the temporary, and the target if we got that far. */
+        fun abandon(reason: String): String {
+            runCatching { if (pending.exists()) pending.delete() }
+            runCatching { if (target.exists()) target.delete() }
+            forget(jobId)
+            return out
+                .put("ok", false)
+                .put("cancelled", reason == "cancelled")
+                .put("error", reason)
+                .toString()
+        }
+
+        try {
+            if (cancelled.get()) return abandon("cancelled")
+
+            var copied = 0L
+            FileOutputStream(pending).use { output ->
+                FileInputStream(source).use { input ->
+                    val buffer = ByteArray(256 * 1024)
+                    while (true) {
+                        if (cancelled.get()) return abandon("cancelled")
+                        val read = input.read(buffer)
+                        if (read <= 0) break
+                        output.write(buffer, 0, read)
+                        copied += read
+                    }
+                    output.flush()
+                    output.fd.sync()
+                }
+            }
+
+            if (copied != source.length()) {
+                // A full disk ends a stream without throwing, and the result
+                // would play as a truncated video.
+                return abandon("the file could not be written completely")
+            }
+            if (cancelled.get()) return abandon("cancelled")
+
+            val probe = probe(context, Uri.fromFile(pending))
+            if (!probe.optBoolean("readable", false)) {
+                return abandon("the saved file could not be read back")
+            }
+            if (cancelled.get()) return abandon("cancelled")
+
+            if (!pending.renameTo(target)) return abandon("the saved file could not be published")
+
+            /*
+              The scanner's uri, or the file's.
+
+              `scanFile` is asynchronous and the caller wants something to hand
+              back, so this waits briefly for the row. A scan that is slow is not
+              a failed save: the bytes are in place and the scanner will get to
+              them, so a timeout still reports success, with the `file:` uri.
+            */
+            val scanned = arrayOfNulls<Uri>(1)
+            val latch = CountDownLatch(1)
+            MediaScannerConnection.scanFile(
+                context,
+                arrayOf(target.absolutePath),
+                arrayOf(MIME),
+            ) { _, uri ->
+                scanned[0] = uri
+                latch.countDown()
+            }
+            runCatching { latch.await(5, TimeUnit.SECONDS) }
+
+            forget(jobId)
+            return out
+                .put("ok", true)
+                .put("uri", (scanned[0] ?: Uri.fromFile(target)).toString())
+                .put("displayName", name)
+                .put("location", RELATIVE_PATH)
+                .put("bytes", copied)
+                .put("legacy", true)
+                .put("durationUs", probe.optLong("durationUs"))
+                .put("hasVideo", probe.optBoolean("hasVideo"))
+                .put("hasAudio", probe.optBoolean("hasAudio"))
+                .toString()
+        } catch (e: Exception) {
+            return abandon(describe(e))
+        }
+    }
+
     /** Delete the pending row, then report. Never reached for a published one. */
     private fun cleanup(
         resolver: android.content.ContentResolver,
@@ -281,7 +452,43 @@ internal object MediaStoreSave {
      * platform behaviour rather than state it. A row in this folder, with this
      * name, that somebody else wrote is still not this app's to remove.
      */
-    fun sweepPending(context: Context): String {
+    fun sweepPending(context: Context): String =
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.Q) sweepLegacy()
+        else sweepPendingRows(context)
+
+    /**
+     * The legacy sweep: unfinished files, not rows.
+     *
+     * Same predicate in spirit as the row sweep — this app's folder, this code's
+     * name shape — because this deletes things. A file without the suffix is
+     * somebody's saved video and is never touched, including one that a person
+     * renamed into the folder themselves.
+     */
+    private fun sweepLegacy(): String {
+        val out = JSONObject()
+        val folder = File(
+            Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_MOVIES),
+            LEGACY_FOLDER,
+        )
+        var swept = 0
+        var inspected = 0
+        runCatching {
+            for (file in folder.listFiles().orEmpty()) {
+                inspected += 1
+                if (!file.name.startsWith(".") || !file.name.endsWith(LEGACY_PENDING_SUFFIX)) continue
+                if (file.delete()) swept += 1
+            }
+        }
+        return out
+            .put("ok", true)
+            .put("legacy", true)
+            .put("inspected", inspected)
+            .put("swept", swept)
+            .toString()
+    }
+
+    @RequiresApi(Build.VERSION_CODES.Q)
+    private fun sweepPendingRows(context: Context): String {
         val resolver = context.contentResolver
         val collection = MediaStore.Video.Media.getContentUri(MediaStore.VOLUME_EXTERNAL_PRIMARY)
         var swept = 0