@pictor-sdk/video-android 0.1.0

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

@@ -0,0 +1,1112 @@
+package dev.pictor.video
+
+import android.content.Context
+import android.media.MediaCodec
+import android.media.MediaCodecInfo
+import android.media.MediaExtractor
+import android.media.MediaFormat
+import android.media.MediaMuxer
+import android.net.Uri
+import androidx.media3.common.audio.AudioProcessor
+import androidx.media3.common.audio.SonicAudioProcessor
+import java.io.File
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+import kotlin.math.max
+import kotlin.math.min
+import org.json.JSONObject
+
+/**
+ * The whole timeline's audio, mixed once and encoded once.
+ *
+ * Driven **exclusively by `AudioMixProgram`**. There is no `AudioItem` here, no
+ * `kind`, no duration policy and no notion of what a muted clip is: the plan
+ * carries source windows, sample-accurate placements and gain envelopes, and
+ * this executes them. Anything else would be a second interpreter of the
+ * project.
+ *
+ * ## One output format, chosen rather than inherited
+ *
+ * **48 000 Hz, 2 channels, 32-bit float** while mixing. Sources arrive at
+ * whatever rate and channel count they were recorded at; every one is brought
+ * to this before it is summed, so the mix never has to ask what format it is
+ * working in. Float because summation must be able to exceed full scale before
+ * it is clipped — see below.
+ *
+ * ## Time is integer arithmetic, converted once
+ *
+ * [sampleAt] is the only conversion between timeline microseconds and sample
+ * indices, and it divides rather than accumulates. Advancing a running position
+ * by a rounded microsecond count per buffer loses a fraction of a sample each
+ * time, and over a few minutes that is audible drift — which is exactly the bug
+ * that never reproduces on a short test.
+ *
+ * Every plan boundary becomes a half-open sample range **once**, before mixing,
+ * and gain is evaluated from the absolute sample position. A buffer boundary
+ * therefore cannot change the envelope: the same mix computed with any buffer
+ * size is the same PCM.
+ *
+ * ## Sum, then saturate, once
+ *
+ * Contributions are added at full float precision and clipped to `[-1, 1]`
+ * **after all of them**. Saturating each contribution as it arrives would clip
+ * sounds that the sum never made loud, and would make the result depend on the
+ * order they were mixed in.
+ */
+internal object AudioMixer {
+
+    /**
+     * Checked in every loop that can run for seconds.
+     *
+     * The mix was the last stage with no way to observe a cancellation.
+     * Measured: cancelling 1.5 s into a three-second export settled in 1610 ms,
+     * because the decode, the Sonic stretch and the AAC encode all ran to
+     * completion before the next checkpoint could see the request. At 0.1x that
+     * stage alone is most of the export.
+     */
+    @Volatile var keepGoing: () -> Boolean = { true }
+
+    /**
+     * One mix at a time, process-wide.
+     *
+     * [keepGoing] is a single mutable predicate on a singleton, which was safe
+     * while the exporter was the only caller: it set the flag, mixed, and put
+     * it back. A second caller — preview — makes that a race with two ways to
+     * lose. A preview starting during an export would replace the export's
+     * cancel predicate with its own, leaving the export uninterruptible; and
+     * restoring `{ true }` afterwards would silently un-cancel it.
+     *
+     * Serialising is the honest fix at this size. Mixing is CPU-bound work that
+     * saturates a core anyway, so two at once buys nothing, and a preview job
+     * is cancelled before it ever reaches this lock when it is superseded.
+     */
+    private val mixLock = Any()
+
+    /**
+     * Where a preparation's time went.
+     *
+     * One object rather than a parameter threaded through eight signatures,
+     * which is safe precisely because mixing is serialised under [mixLock] —
+     * there is never a second mix to confuse it.
+     *
+     * It exists because a 22-second preparation is a product problem and the
+     * first thing anyone will want to do about it is guess. Attribution first:
+     * a stage that is 3% of the total is not worth caching however slow it
+     * feels.
+     */
+    class Profile {
+        private val ns = LinkedHashMap<String, Long>()
+        private val counts = LinkedHashMap<String, Long>()
+        private val perSource = LinkedHashMap<String, JSONObject>()
+
+        fun <T> time(stage: String, block: () -> T): T {
+            val at = System.nanoTime()
+            try {
+                return block()
+            } finally {
+                ns[stage] = (ns[stage] ?: 0L) + (System.nanoTime() - at)
+            }
+        }
+
+        fun count(key: String, value: Long) {
+            counts[key] = (counts[key] ?: 0L) + value
+        }
+
+        fun source(id: String, detail: JSONObject) {
+            perSource[id] = detail
+        }
+
+        fun reset() {
+            ns.clear()
+            counts.clear()
+            perSource.clear()
+        }
+
+        fun json(): JSONObject {
+            val stages = JSONObject()
+            for ((k, v) in ns) stages.put(k, v / 1_000_000)
+            val totals = JSONObject()
+            for ((k, v) in counts) totals.put(k, v)
+            val sources = JSONObject()
+            for ((k, v) in perSource) sources.put(k, v)
+            return JSONObject()
+                .put("stageMs", stages)
+                .put("counts", totals)
+                .put("sources", sources)
+        }
+    }
+
+    /** The profile of the mix currently running. */
+    @Volatile var profile = Profile()
+        private set
+
+    /** Raised to unwind the loops without inventing a failure. */
+    internal class Cancelled : RuntimeException("cancelled")
+
+    private fun checkCancelled() {
+        if (!keepGoing()) throw Cancelled()
+    }
+
+    const val SAMPLE_RATE = 48_000
+    const val CHANNELS = 2
+
+    /**
+     * Timeline microseconds to an output sample index.
+     *
+     * Integer division from the absolute time, never an accumulated step.
+     */
+    fun sampleAt(timeUs: Long): Long = Math.floorDiv(timeUs * SAMPLE_RATE.toLong(), 1_000_000L)
+
+    /** The inverse, for evaluating an envelope at a known sample. */
+    fun timeAt(sample: Long): Long = Math.floorDiv(sample * 1_000_000L, SAMPLE_RATE.toLong())
+
+    private class Ramp(val fromUs: Long, val toUs: Long, val fromGain: Double, val toGain: Double)
+
+    private class Span(
+        val id: String,
+        val uri: String?,
+        val startSample: Long,
+        val endSample: Long,
+        val sourceInUs: Long,
+        val sourceOutUs: Long,
+        val speed: Float,
+        val gain: Double,
+        val ramps: List<Ramp>,
+        val silent: Boolean,
+    )
+
+    /**
+     * Mix and encode.
+     *
+     * `urisJson` maps span id to a host-resolved URI; a span whose id is absent
+     * and which is not silent fails the mix rather than being skipped.
+     */
+    fun mix(
+        context: Context,
+        programJson: String,
+        urisJson: String,
+        output: File,
+        /**
+         * Whether to keep going, asked in every loop that can run for seconds.
+         *
+         * Passed rather than assigned, so two callers cannot clobber each
+         * other's cancellation. Installed for the duration of this call under
+         * [mixLock] and restored afterwards.
+         */
+        keepGoing: () -> Boolean = { true },
+        /**
+         * Encoder input buffer size, for proving it does not matter.
+         *
+         * The mix itself cannot depend on it — contributions are accumulated by
+         * absolute sample position, not by walking buffers — so varying it and
+         * getting the same PCM is a check on that claim rather than a knob
+         * anyone should turn.
+         */
+        maxInputSize: Int = 64 * 1024,
+    ): String = synchronized(mixLock) {
+        val previous = this.keepGoing
+        this.keepGoing = keepGoing
+        try {
+            mixLocked(context, programJson, urisJson, output, maxInputSize)
+        } finally {
+            this.keepGoing = previous
+        }
+    }
+
+    private fun mixLocked(
+        context: Context,
+        programJson: String,
+        urisJson: String,
+        output: File,
+        maxInputSize: Int,
+    ): String {
+        val out = JSONObject()
+        profile = Profile()
+        try {
+            val program = JSONObject(programJson)
+            if (program.optInt("version", -1) != 1) {
+                return out.put("ok", false).put("error", "unsupported mix version").toString()
+            }
+            if (program.optString("rule", "") != "sum-then-saturate") {
+                return out.put("ok", false)
+                    .put("error", "unknown mix rule '" + program.optString("rule") + "'").toString()
+            }
+            val durationUs = program.optLong("durationUs", -1)
+            if (durationUs <= 0) return out.put("ok", false).put("error", "no duration").toString()
+            val uris = JSONObject(urisJson)
+
+            val spans = ArrayList<Span>()
+            val array = program.optJSONArray("spans")
+                ?: return out.put("ok", false).put("error", "no spans").toString()
+            for (i in 0 until array.length()) {
+                val s = array.getJSONObject(i)
+                val id = s.getString("id")
+                val silent = s.optBoolean("silent", false)
+                val uri = if (uris.has(id)) uris.getString(id) else null
+                if (!silent && uri == null) {
+                    return out.put("ok", false)
+                        .put("error", "span '" + id + "' has no resolved source").toString()
+                }
+                val ramps = ArrayList<Ramp>()
+                s.optJSONArray("ramps")?.let { r ->
+                    for (k in 0 until r.length()) {
+                        val ramp = r.getJSONObject(k)
+                        ramps.add(
+                            Ramp(
+                                ramp.getLong("fromUs"), ramp.getLong("toUs"),
+                                ramp.getDouble("fromGain"), ramp.getDouble("toGain"),
+                            ),
+                        )
+                    }
+                }
+                // Half-open, converted once. Nothing downstream re-derives it.
+                spans.add(
+                    Span(
+                        id, uri,
+                        sampleAt(s.getLong("startUs")), sampleAt(s.getLong("endUs")),
+                        s.getLong("sourceInUs"), s.getLong("sourceOutUs"),
+                        s.optDouble("speed", 1.0).toFloat(), s.optDouble("gain", 1.0),
+                        ramps, silent,
+                    ),
+                )
+            }
+
+            val totalSamples = sampleAt(durationUs)
+            if (totalSamples <= 0) return out.put("ok", false).put("error", "empty timeline").toString()
+            val mixed = FloatArray((totalSamples * CHANNELS).toInt())
+
+            val contributed = JSONObject()
+            for (span in spans) {
+                if (span.silent) {
+                    // An empty contribution. Nothing is generated and nothing is
+                    // decoded: the accumulator is already zero here.
+                    contributed.put(span.id, 0)
+                    continue
+                }
+                val decoded = profile.time("decode.total") {
+                    decodeToOutputFormat(
+                        context, span.uri!!, span.sourceInUs, span.sourceOutUs, span.speed,
+                    )
+                }
+                profile.source(
+                    span.id,
+                    JSONObject()
+                        .put("decodedFrames", decoded.decodedFrames)
+                        .put("croppedFrames", decoded.croppedFrames)
+                        .put("stretchedFrames", decoded.stretchedFrames)
+                        .put("outputFrames", decoded.outputFrames)
+                        .put("sourceRate", decoded.sourceRate)
+                        .put("sourceChannels", decoded.sourceChannels)
+                        .put("speed", span.speed.toDouble())
+                        .put("windowUs", span.sourceOutUs - span.sourceInUs),
+                )
+                profile.count("decodedFrames", decoded.decodedFrames.toLong())
+                profile.count("outputFrames", decoded.outputFrames.toLong())
+                val pcm = decoded.pcm
+                var written = 0L
+                val mixAt = System.nanoTime()
+                val wanted = span.endSample - span.startSample
+                var i = 0L
+                while (i < wanted) {
+                    val outSample = span.startSample + i
+                    if (outSample >= totalSamples) break
+                    val srcIndex = (i * CHANNELS).toInt()
+                    if (srcIndex + CHANNELS > pcm.size) break
+                    // Absolute position, so a buffer boundary cannot move the
+                    // envelope.
+                    val g = gainAt(span, timeAt(outSample))
+                    val dst = (outSample * CHANNELS).toInt()
+                    for (c in 0 until CHANNELS) {
+                        mixed[dst + c] += (pcm[srcIndex + c] * g).toFloat()
+                    }
+                    written += 1
+                    i += 1
+                }
+                /*
+                  A span that should sound and contributes nothing is an error.
+
+                  Returning a mix that is quietly missing a clip produces a file
+                  nothing downstream can tell from one that never had it — the
+                  same failure mode this pipeline refuses everywhere else. It is
+                  raised here rather than left to a listener to notice.
+                */
+                profile.count("mixNs", System.nanoTime() - mixAt)
+                if (written == 0L) {
+                    return out.put("ok", false)
+                        .put(
+                            "error",
+                            "span '" + span.id + "' contributed no samples " +
+                                "(window " + span.sourceInUs + ".." + span.sourceOutUs +
+                                " at speed " + span.speed + "; decoded " + decoded.decodedFrames +
+                                ", cropped " + decoded.croppedFrames +
+                                ", stretched " + decoded.stretchedFrames +
+                                ", output " + decoded.outputFrames +
+                                ", source " + decoded.sourceRate + "Hz x" + decoded.sourceChannels +
+                                " " + decoded.encoding + ")",
+                        )
+                        .toString()
+                }
+                // Recorded against what was asked for: a decoder can only start
+                // on a frame boundary, so a window may be short by part of one.
+                contributed.put(
+                    span.id,
+                    written.toString() + "/" + wanted.toString() +
+                        " preroll=" + decoded.prerollUs + " retries=" + decoded.retries +
+                        (if (decoded.primingGapFrames > 0) " priming=" + decoded.primingGapFrames else ""),
+                )
+            }
+
+            // Saturated once, after every contribution.
+            profile.time("saturate") {
+                for (i in mixed.indices) {
+                    mixed[i] = max(-1f, min(1f, mixed[i]))
+                }
+            }
+
+            /*
+              Retained only while an attribution run asks for it.
+
+              This kept a full copy of the mixed timeline — 12.7 MB for the
+              33-second acceptance project, on top of the working array — for
+              the life of the process, in every diagnostics build. It exists for
+              one experiment and was costing every run that followed.
+            */
+            if (Diagnostics.ENABLED && PreviewConfig.retainMixedPcm) lastMixedPcm = mixed.copyOf()
+            val encoded = profile.time("encode") { encode(mixed, output, maxInputSize) }
+            if (!encoded.optBoolean("ok", false)) return encoded.toString()
+
+            out.put("ok", true)
+                .put("uri", output.absolutePath)
+                .put("sampleRate", SAMPLE_RATE)
+                .put("channels", CHANNELS)
+                .put("totalSamples", totalSamples)
+                .put("contributed", contributed)
+                .put("encodedSamples", encoded.optInt("samples"))
+                .put("profile", profile.json())
+        } catch (e: Exception) {
+            out.put("ok", false).put("error", e.javaClass.simpleName + ": " + e.message)
+        }
+        return out.toString()
+    }
+
+    /**
+     * Decode one window and report every stage, without mixing.
+     *
+     * The point is to run the identical window at 1x and at another rate: if
+     * the cropped frame counts match and only the stretched count differs, the
+     * stretch is responsible; if the cropped counts differ, the decode is.
+     */
+    /** Decode one window under a simulated decoder warm-up requirement. */
+    fun probePreroll(context: Context, uri: String, fromUs: Long, toUs: Long, warmupUs: Long): String {
+        warmupSimUs = warmupUs
+        try {
+            val out = JSONObject().put("warmupUs", warmupUs)
+            return try {
+                val d = decodeToOutputFormat(context, uri, fromUs, toUs, 1f)
+                out.put("ok", true).put("prerollUs", d.prerollUs).put("retries", d.retries)
+                    .put("priming", d.primingGapFrames).put("croppedFrames", d.croppedFrames).put("outputFrames", d.outputFrames).toString()
+            } catch (e: DecodeFailure) {
+                out.put("ok", false).put("stage", e.stage).put("error", e.message).toString()
+            } catch (e: Exception) {
+                out.put("ok", false).put("stage", "unexpected")
+                    .put("error", e.javaClass.simpleName + ": " + e.message).toString()
+            }
+        } finally {
+            warmupSimUs = 0
+        }
+    }
+
+    fun probeDecode(context: Context, uri: String, fromUs: Long, toUs: Long, speed: Float): String {
+        val out = JSONObject()
+        return try {
+            val d = decodeToOutputFormat(context, uri, fromUs, toUs, speed)
+            out.put("ok", true).put("stage", "complete")
+                .put("prerollUs", d.prerollUs).put("retries", d.retries)
+                .put("decodedFrames", d.decodedFrames)
+                .put("croppedFrames", d.croppedFrames)
+                .put("stretchedFrames", d.stretchedFrames)
+                .put("outputFrames", d.outputFrames)
+                .put("sourceRate", d.sourceRate)
+                .put("sourceChannels", d.sourceChannels)
+                .put("encoding", d.encoding)
+                .toString()
+        } catch (e: DecodeFailure) {
+            out.put("ok", false).put("stage", e.stage).put("error", e.message).toString()
+        } catch (e: Exception) {
+            out.put("ok", false).put("stage", "unexpected")
+                .put("error", e.javaClass.simpleName + ": " + e.message).toString()
+        }
+    }
+
+    /**
+     * Run [stretch] alone on synthetic PCM.
+     *
+     * No decoder, no file: a tone generated in memory, so a wrong answer here
+     * cannot be blamed on a source.
+     */
+    fun probeStretch(rate: Int, channels: Int, frames: Int, speed: Float): String {
+        val out = JSONObject()
+        return try {
+            val pcm = ShortArray(frames * channels)
+            for (f in 0 until frames) {
+                val v = (Math.sin(2.0 * Math.PI * 440.0 * f / rate) * 16000).toInt().toShort()
+                for (c in 0 until channels) pcm[f * channels + c] = v
+            }
+            val stretched = stretch(pcm, rate, channels, speed)
+            out.put("ok", true)
+                .put("inFrames", frames)
+                .put("outFrames", if (channels > 0) stretched.size / channels else 0)
+                .put("expected", (frames / speed).toInt())
+                .toString()
+        } catch (e: Exception) {
+            out.put("ok", false).put("error", e.javaClass.simpleName + ": " + e.message).toString()
+        }
+    }
+
+    /** The plan's envelope, evaluated at an absolute instant. */
+    private fun gainAt(span: Span, timeUs: Long): Double {
+        var factor = span.gain
+        for (ramp in span.ramps) {
+            factor *= when {
+                timeUs <= ramp.fromUs -> ramp.fromGain
+                timeUs >= ramp.toUs -> ramp.toGain
+                else -> {
+                    val t = (timeUs - ramp.fromUs).toDouble() / (ramp.toUs - ramp.fromUs).toDouble()
+                    ramp.fromGain + (ramp.toGain - ramp.fromGain) * t
+                }
+            }
+        }
+        return factor
+    }
+
+    /** What each stage produced, so a failure names the stage that caused it. */
+    class Decoded(
+        val pcm: FloatArray,
+        val decodedFrames: Int,
+        val croppedFrames: Int,
+        val stretchedFrames: Int,
+        val outputFrames: Int,
+        val sourceRate: Int,
+        val sourceChannels: Int,
+        val encoding: String,
+        /** How far before `sourceIn` the decode finally started. */
+        val prerollUs: Long,
+        /** How many attempts it took to cover the window. Zero means the first worked. */
+        val retries: Int,
+        /** Source frames at the head of the window the codec could not produce. */
+        val primingGapFrames: Long,
+    )
+
+    /** A stage failed. Never converted to silence. */
+    class DecodeFailure(val stage: String, message: String) : Exception(message)
+
+    /**
+     * Decode one source window into the fixed output format.
+     *
+     * **Nothing here turns an exception into empty PCM.** The previous version
+     * caught everything and returned a zero-length array, so a decode that never
+     * ran and a window that was genuinely silent looked identical — and a clip
+     * whose audio vanished reported success. Each stage now records what it
+     * produced and a failure names the stage.
+     *
+     * The window is intersected with `[sourceIn, sourceOut)` in **source frame
+     * indices**, computed rationally from each buffer's own timestamp. Both ends
+     * are cropped: the earlier code trimmed only the front, so the final buffer
+     * ran past `sourceOut` by up to one decoder frame.
+     *
+     * The decoder's **actual output format** is used, not the compressed input
+     * format. A decoder may resample, downmix, or emit float; assuming the
+     * compressed header describes the decoded buffers is how a correct decode
+     * gets read at the wrong stride.
+     */
+    private fun decodeToOutputFormat(
+        context: Context,
+        uri: String,
+        fromUs: Long,
+        toUs: Long,
+        speed: Float,
+    ): Decoded {
+        /*
+          Preroll is discovered, not assumed.
+
+          A decoder discards some number of output frames after a seek as
+          priming, and that number is the decoder's business: it varies by codec,
+          by device, and by whether the seek landed on a sync sample. A fixed
+          250 ms run-up was a guess that happened to fit one AAC decoder on one
+          phone. Too small and the head of the window is silently missing -- the
+          failure this replaces, which read as clips ending early rather than as
+          an error. Too large and every span pays for the worst case.
+
+          So each attempt reports the first source frame it actually covered, and
+          the run-up expands backward until that frame is at or before the window
+          start. Attempts stop at the source's own beginning: if decoding from
+          zero still cannot reach `sourceIn`, that is a failure named by span,
+          because padding an audible span with silence is the class of quiet
+          wrongness this whole path exists to eliminate.
+        */
+        var preroll = 0L
+        var retries = 0
+        while (true) {
+            val attempt = decodeAttempt(context, uri, fromUs, toUs, preroll)
+            val covered = attempt.firstCoveredFrame <= attempt.windowStartFrame &&
+                attempt.firstCoveredFrame != Long.MAX_VALUE
+            if (covered) return finish(attempt, speed, preroll, retries, 0)
+            if (preroll >= fromUs) {
+                /*
+                  At the very start of a file there is nowhere earlier to seek.
+
+                  A lossy encoder prepends priming samples, so the first frames a
+                  decoder emits are delay rather than content and the head of a
+                  window at source zero is genuinely not in the file. That is a
+                  property of the format, not a decode that went wrong -- but it
+                  is only that when the missing part is priming-sized. So the
+                  shortfall is checked against the encoder's declared delay
+                  (falling back to two decoder frames when it declares none), and
+                  represented as silence *at its own position* so nothing after
+                  it shifts earlier. Anything larger is a failure named by span,
+                  because a hole in the middle of a clip's audio and a codec's
+                  priming are not the same thing and must not be treated alike.
+                */
+                if (attempt.croppedFrames == 0) {
+                    throw DecodeFailure(
+                        "preroll",
+                        "decoding from source start produced nothing for [" + fromUs + ", " + toUs + ")",
+                    )
+                }
+                val gap = attempt.firstCoveredFrame - attempt.windowStartFrame
+                if (gap > attempt.primingAllowanceFrames) {
+                    throw DecodeFailure(
+                        "preroll",
+                        "window [" + fromUs + ", " + toUs + ") is missing " + gap +
+                            " frames at its head, beyond the codec priming allowance of " +
+                            attempt.primingAllowanceFrames,
+                    )
+                }
+                return finish(attempt, speed, preroll, retries, gap)
+            }
+            retries += 1
+            // Geometric, from nothing: a decoder needing no warm-up pays no cost,
+            // and one needing a lot reaches it in a few attempts rather than many.
+            preroll = if (preroll == 0L) 40_000L else preroll * 4
+            if (preroll > fromUs) preroll = fromUs
+        }
+    }
+
+    /** One decode attempt at a chosen run-up. */
+    private class Attempt(
+        val raw: ShortArray,
+        val decodedFrames: Int,
+        val croppedFrames: Int,
+        val rate: Int,
+        val channels: Int,
+        val encoding: Int,
+        /** First source frame index actually captured, or MAX_VALUE if none. */
+        val firstCoveredFrame: Long,
+        val windowStartFrame: Long,
+        /** How much head loss this codec's declared priming can explain. */
+        val primingAllowanceFrames: Long,
+    )
+
+    /** Stretch and resample an attempt into the mixer's format. */
+    private fun finish(
+        attempt: Attempt,
+        speed: Float,
+        prerollUs: Long,
+        retries: Int,
+        primingGapFrames: Long,
+    ): Decoded {
+        /*
+          The gap is restored as silence before the stretch, not after.
+
+          Its position is what matters: dropping it would move every later sample
+          of the span earlier by the gap, which is an A/V sync error that grows
+          with nothing and is invisible in a sample count. Prepending it here
+          lets the stretch and resample carry it to the right place by the same
+          arithmetic as the real samples.
+        */
+        val raw = if (primingGapFrames > 0) {
+            val pad = (primingGapFrames * attempt.channels).toInt()
+            ShortArray(pad + attempt.raw.size).also { attempt.raw.copyInto(it, pad) }
+        } else attempt.raw
+        val stretched =
+            if (speed != 1f) {
+                profile.time("stretch") { stretch(raw, attempt.rate, attempt.channels, speed) }
+            } else raw
+        val stretchedFrames = if (attempt.channels > 0) stretched.size / attempt.channels else 0
+        val out = profile.time("resample") {
+            toOutputFormat(stretched, attempt.rate, attempt.channels)
+        }
+        return Decoded(
+            out, attempt.decodedFrames, if (attempt.channels > 0) raw.size / attempt.channels else 0,
+            stretchedFrames, out.size / CHANNELS,
+            attempt.rate, attempt.channels,
+            if (attempt.encoding == android.media.AudioFormat.ENCODING_PCM_FLOAT) "float" else "pcm16",
+            prerollUs, retries, primingGapFrames,
+        )
+    }
+
+    @Volatile private var warmupSimUs: Long = 0
+
+    private fun decodeAttempt(
+        context: Context,
+        uri: String,
+        fromUs: Long,
+        toUs: Long,
+        prerollUs: Long,
+    ): Attempt {
+        /*
+          `warmupSimUs` models a decoder that needs more run-up than this one.
+
+          Real decoders differ in how much output they discard after a seek, and
+          the adaptive search has to be correct for a decoder we do not have.
+          Setting this drops output covering the first N microseconds after the
+          seek point, which is exactly what a longer-priming decoder does. It is
+          zero everywhere except the probe.
+        */
+        val beatEpoch = ExportHeartbeat.currentEpoch()
+        val extractor = MediaExtractor()
+        var codec: MediaCodec? = null
+        // Declared out here because the `finally` below records the other end
+        // of this codec's life, and a value scoped to the `try` is not visible
+        // from the block that has to prove it was released.
+        var ledgerEntry: CodecLedger.Entry? = null
+        try {
+            profile.time("open") {
+                if (uri.startsWith("/")) extractor.setDataSource(uri)
+                else extractor.setDataSource(context, Uri.parse(uri), null)
+            }
+            var track = -1
+            var inputFormat: MediaFormat? = null
+            for (i in 0 until extractor.trackCount) {
+                val f = extractor.getTrackFormat(i)
+                if ((f.getString(MediaFormat.KEY_MIME) ?: "").startsWith("audio/")) {
+                    track = i; inputFormat = f; break
+                }
+            }
+            if (track < 0 || inputFormat == null) {
+                throw DecodeFailure("find-track", "no audio track in $uri")
+            }
+            extractor.selectTrack(track)
+            val seekUs = maxOf(0L, fromUs - prerollUs)
+            extractor.seekTo(seekUs, MediaExtractor.SEEK_TO_PREVIOUS_SYNC)
+            val warmUntilUs = if (warmupSimUs > 0) seekUs + warmupSimUs else Long.MIN_VALUE
+
+            ledgerEntry = CodecLedger.open("mix.decoder")
+            codec = MediaCodec.createDecoderByType(inputFormat.getString(MediaFormat.KEY_MIME)!!)
+            codec.configure(inputFormat, null, null, 0)
+            codec.start()
+
+            // Replaced the moment the decoder announces its real output format.
+            var rate = inputFormat.getInteger(MediaFormat.KEY_SAMPLE_RATE)
+            var channels = inputFormat.getInteger(MediaFormat.KEY_CHANNEL_COUNT)
+            var encoding = android.media.AudioFormat.ENCODING_PCM_16BIT
+
+            val raw = ArrayList<Short>()
+            var decodedFrames = 0
+            var firstCovered = Long.MAX_VALUE
+            var observedWindowStart = 0L
+            val info = MediaCodec.BufferInfo()
+            var inputDone = false
+            var outputDone = false
+            var iterations = 0
+            while (!outputDone) {
+                iterations += 1
+                if (iterations > 1_000_000) {
+                    // A guard that is hit is a failure, not a result.
+                    throw DecodeFailure("decode-loop", "decoder did not finish within 1e6 iterations")
+                }
+                if (!inputDone) {
+                    val index = codec.dequeueInputBuffer(10_000)
+                    if (index >= 0) {
+                        val buffer = codec.getInputBuffer(index)!!
+                        val size = extractor.readSampleData(buffer, 0)
+                        val time = extractor.sampleTime
+                        // A sample *at* sourceOut is outside a half-open window.
+                        if (size < 0 || time >= toUs) {
+                            codec.queueInputBuffer(index, 0, 0, 0, MediaCodec.BUFFER_FLAG_END_OF_STREAM)
+                            inputDone = true
+                        } else {
+                            codec.queueInputBuffer(index, 0, size, time, 0)
+                            extractor.advance()
+                        }
+                    }
+                }
+                val index = codec.dequeueOutputBuffer(info, 10_000)
+                if (index == MediaCodec.INFO_OUTPUT_FORMAT_CHANGED) {
+                    val actual = codec.outputFormat
+                    rate = actual.getInteger(MediaFormat.KEY_SAMPLE_RATE)
+                    channels = actual.getInteger(MediaFormat.KEY_CHANNEL_COUNT)
+                    if (actual.containsKey(MediaFormat.KEY_PCM_ENCODING)) {
+                        encoding = actual.getInteger(MediaFormat.KEY_PCM_ENCODING)
+                    }
+                    if (encoding != android.media.AudioFormat.ENCODING_PCM_16BIT &&
+                        encoding != android.media.AudioFormat.ENCODING_PCM_FLOAT
+                    ) {
+                        throw DecodeFailure("pcm-encoding", "unsupported PCM encoding $encoding")
+                    }
+                } else if (index >= 0) {
+                    if (info.size > 0 && info.presentationTimeUs >= warmUntilUs) {
+                        val buffer = codec.getOutputBuffer(index)!!
+                        buffer.position(info.offset)
+                        buffer.limit(info.offset + info.size)
+                        val bytesPerSample = if (encoding == android.media.AudioFormat.ENCODING_PCM_FLOAT) 4 else 2
+                        val frames = info.size / (bytesPerSample * channels)
+                        decodedFrames += frames
+                        // One decoded buffer is liveness, whatever it does to
+                        // the visible percentage.
+                        checkCancelled()
+                        ExportHeartbeat.beat("audioBlock", beatEpoch)
+                        /*
+                          Intersected in source frame indices, from this buffer's
+                          own timestamp. Rational, not accumulated, so a long
+                          window cannot drift away from the plan.
+                        */
+                        val bufferStart = Math.floorDiv(info.presentationTimeUs * rate, 1_000_000L)
+                        val windowStart = Math.floorDiv(fromUs * rate, 1_000_000L)
+                        val windowEnd = Math.floorDiv(toUs * rate, 1_000_000L)
+                        val take0 = max(bufferStart, windowStart)
+                        val take1 = min(bufferStart + frames, windowEnd)
+                        if (take1 > take0) {
+                            if (firstCovered == Long.MAX_VALUE) firstCovered = take0
+                            observedWindowStart = windowStart
+                            val ordered = buffer.order(ByteOrder.nativeOrder())
+                            if (encoding == android.media.AudioFormat.ENCODING_PCM_FLOAT) {
+                                val floats = ordered.asFloatBuffer()
+                                for (f in take0 until take1) {
+                                    val local = (f - bufferStart).toInt()
+                                    for (c in 0 until channels) {
+                                        val v = floats.get(local * channels + c)
+                                        raw.add((max(-1f, min(1f, v)) * 32767f).toInt().toShort())
+                                    }
+                                }
+                            } else {
+                                val shorts = ordered.asShortBuffer()
+                                for (f in take0 until take1) {
+                                    val local = (f - bufferStart).toInt()
+                                    for (c in 0 until channels) raw.add(shorts.get(local * channels + c))
+                                }
+                            }
+                        }
+                    }
+                    codec.releaseOutputBuffer(index, false)
+                    if ((info.flags and MediaCodec.BUFFER_FLAG_END_OF_STREAM) != 0) outputDone = true
+                }
+            }
+
+            val cropped = ShortArray(raw.size) { raw[it] }
+            val declaredDelay =
+                if (inputFormat.containsKey("encoder-delay")) inputFormat.getInteger("encoder-delay").toLong()
+                else 0L
+            return Attempt(
+                cropped, decodedFrames, if (channels > 0) cropped.size / channels else 0,
+                rate, channels, encoding, firstCovered,
+                if (firstCovered == Long.MAX_VALUE) Math.floorDiv(fromUs * rate, 1_000_000L)
+                else observedWindowStart,
+                /*
+                    Never stricter for declaring than for saying nothing.
+
+                    This was `declaredDelay` when one was present and 2048
+                    otherwise, which made an honest file harder to decode than a
+                    silent one. Measured: a LAME MP3 declares 576 frames of
+                    encoder delay and its first covered frame arrives 622 in, so
+                    the window failed — while the same file with no tag would
+                    have been accepted comfortably.
+
+                    A declared delay is a lower bound on what the decoder
+                    withholds, not the whole of it: output is emitted in whole
+                    frames and this path also resamples to 48 kHz, so the first
+                    sample that actually covers the window can land later than
+                    the tag alone predicts. Taking the larger of the two keeps
+                    the tag useful for files that declare more than the fallback
+                    and stops it being a penalty for the rest.
+                */
+                maxOf(declaredDelay, 2048L),
+            )
+        } finally {
+            /*
+              Both ends recorded, not just the call.
+
+              `release()` returning is what frees the hardware instance; a
+              `runCatching` that swallowed a throw would otherwise look
+              identical to a clean teardown, and the whole question here is
+              whether these give the resource back.
+            */
+            ledgerEntry?.stoppedNs = System.nanoTime()
+            runCatching { codec?.stop() }
+                .onFailure { ledgerEntry?.failure = "stop: " + it.javaClass.simpleName }
+            ledgerEntry?.releaseCalledNs = System.nanoTime()
+            runCatching { codec?.release() }
+                .onFailure { ledgerEntry?.failure = "release: " + it.javaClass.simpleName }
+            ledgerEntry?.releasedNs = System.nanoTime()
+            runCatching { extractor.release() }
+        }
+    }
+
+    /**
+     * Time-stretch without moving pitch, via Sonic on raw PCM.
+     *
+     * Sonic buffers: `queueInput` may consume only part of a buffer, and output
+     * keeps arriving after end-of-stream. Reading it once and stopping at the
+     * first empty buffer returns almost nothing — which showed up as a
+     * speed-changed clip contributing an rms of 0.042 while every clip at rate 1
+     * was fine.
+     */
+    private fun stretch(pcm: ShortArray, rate: Int, channels: Int, speed: Float): ShortArray {
+        val sonic = SonicAudioProcessor()
+        sonic.setSpeed(speed)
+        val format = AudioProcessor.AudioFormat(rate, channels, android.media.AudioFormat.ENCODING_PCM_16BIT)
+        sonic.configure(format)
+        /*
+          The overload that exists, not the one that reads better.
+
+          `AudioProcessor.flush()` is a `default` method that throws
+          "AudioProcessor must implement at least one #flush() overload" — so
+          every rate change failed here, at every sample rate, channel count and
+          input size. The old code caught that and returned empty PCM, which is
+          how a clip's audio disappeared while the export reported success.
+        */
+        sonic.flush(AudioProcessor.StreamMetadata.DEFAULT)
+        val input = ByteBuffer.allocateDirect(pcm.size * 2).order(ByteOrder.nativeOrder())
+        input.asShortBuffer().put(pcm)
+        input.limit(pcm.size * 2)
+        val collected = ArrayList<Short>(pcm.size)
+
+        val stretchEpoch = ExportHeartbeat.currentEpoch()
+        fun drain() {
+            while (true) {
+                // Sonic's drain is where a 0.1x export spends seconds in
+                // silence, stretching one second of source into ten.
+                checkCancelled()
+                ExportHeartbeat.beat("audioBlock", stretchEpoch)
+                val output = sonic.getOutput()
+                if (!output.hasRemaining()) return
+                val shorts = output.order(ByteOrder.nativeOrder()).asShortBuffer()
+                while (shorts.hasRemaining()) collected.add(shorts.get())
+            }
+        }
+
+        var guard = 0
+        while (input.hasRemaining() && guard < 100_000) {
+            guard += 1
+            sonic.queueInput(input)
+            drain()
+        }
+        sonic.queueEndOfStream()
+        guard = 0
+        while (!sonic.isEnded && guard < 100_000) {
+            guard += 1
+            drain()
+        }
+        drain()
+        runCatching { sonic.reset() }
+        return ShortArray(collected.size) { collected[it] }
+    }
+
+    /** Linear resample and channel map into 48 kHz stereo float. */
+    private fun toOutputFormat(pcm: ShortArray, rate: Int, channels: Int): FloatArray {
+        if (pcm.isEmpty() || channels <= 0) return FloatArray(0)
+        val frames = pcm.size / channels
+        val outFrames = ((frames.toLong() * SAMPLE_RATE) / rate).toInt()
+        val out = FloatArray(outFrames * CHANNELS)
+        for (i in 0 until outFrames) {
+            // Position in source frames, as a rational rather than an
+            // accumulated step, so a long span cannot drift.
+            val pos = (i.toDouble() * rate) / SAMPLE_RATE
+            val i0 = pos.toInt()
+            val i1 = min(frames - 1, i0 + 1)
+            val t = pos - i0
+            for (c in 0 until CHANNELS) {
+                // Mono duplicates into both channels; anything wider takes the
+                // matching channel.
+                val sc = if (channels == 1) 0 else min(channels - 1, c)
+                val a = pcm[i0 * channels + sc] / 32768f
+                val b = pcm[i1 * channels + sc] / 32768f
+                out[i * CHANNELS + c] = (a + (b - a) * t).toFloat()
+            }
+        }
+        return out
+    }
+
+    /**
+     * Gate-only: the mixed PCM, exactly as the encoder received it.
+     *
+     * The attribution experiment has to separate loss in the mix from loss in
+     * the encode, and the only way to do that is to look at the samples between
+     * them. Captured under [Diagnostics] and overwritten every mix, so it never
+     * accumulates and never exists in a release build.
+     */
+    @Volatile var lastMixedPcm: FloatArray? = null
+        private set
+
+    /** Gate-only door to [encode], so a baseline runs the production loop. */
+    internal fun encodeForGate(mixed: FloatArray, output: File, maxInputSize: Int): JSONObject =
+        encode(mixed, output, maxInputSize)
+
+    /** Encode the finished timeline to AAC, once. */
+    private fun encode(mixed: FloatArray, output: File, maxInputSize: Int): JSONObject {
+        val encodeEpoch = ExportHeartbeat.currentEpoch()
+        val result = JSONObject()
+        var codec: MediaCodec? = null
+        var muxer: MediaMuxer? = null
+        var encoderEntry: CodecLedger.Entry? = null
+        try {
+            val format = MediaFormat.createAudioFormat(MediaFormat.MIMETYPE_AUDIO_AAC, SAMPLE_RATE, CHANNELS)
+            format.setInteger(MediaFormat.KEY_AAC_PROFILE, MediaCodecInfo.CodecProfileLevel.AACObjectLC)
+            format.setInteger(MediaFormat.KEY_BIT_RATE, 128_000)
+            format.setInteger(MediaFormat.KEY_MAX_INPUT_SIZE, maxInputSize)
+            encoderEntry = CodecLedger.open("mix.encoder")
+            codec = MediaCodec.createEncoderByType(MediaFormat.MIMETYPE_AUDIO_AAC)
+            codec.configure(format, null, null, MediaCodec.CONFIGURE_FLAG_ENCODE)
+            codec.start()
+            muxer = MediaMuxer(output.absolutePath, MediaMuxer.OutputFormat.MUXER_OUTPUT_MPEG_4)
+
+            var track = -1
+            var started = false
+            val info = MediaCodec.BufferInfo()
+            var written = 0
+            var offset = 0
+            var inputDone = false
+            var outputDone = false
+            var guard = 0
+
+            /*
+              Feed and drain, rather than one of each per turn with a wait
+              between them.
+
+              The previous loop queued at most one input buffer and then called
+              `dequeueOutputBuffer` with a 10 ms timeout, every iteration. An AAC
+              encoder hands back input buffers of about a frame — 2048 samples,
+              not the 32768 `KEY_MAX_INPUT_SIZE` suggests — so a 33-second
+              timeline is around 1550 turns, each of them waiting on an encoder
+              that had nothing to say yet. Measured on a Pixel 7: encode time
+              tracked `units x 10 ms` almost exactly, 20.3 s of a 23.8 s
+              preparation.
+
+              So: take every input buffer that is ready, then take every output
+              buffer that is ready, both without waiting. Only when neither side
+              can move does this block, and then once, briefly — that is the
+              case where the encoder genuinely has work in progress.
+            */
+            var blockedNs = 0L
+            var iterations = 0L
+            var waits = 0L
+
+            while (!outputDone && guard < 5_000_000) {
+                guard += 1
+                iterations += 1
+                var progressed = false
+
+                // Feed: everything available, without waiting.
+                while (!inputDone) {
+                    val index = codec.dequeueInputBuffer(0)
+                    if (index < 0) break
+                    val buffer = codec.getInputBuffer(index)!!
+                    buffer.clear()
+                    val capacity = buffer.remaining() / 2
+                    val count = min(capacity, mixed.size - offset)
+                    if (count <= 0) {
+                        codec.queueInputBuffer(
+                            index, 0, 0, presentationOf(offset), MediaCodec.BUFFER_FLAG_END_OF_STREAM,
+                        )
+                        inputDone = true
+                    } else {
+                        val shorts = buffer.order(ByteOrder.nativeOrder()).asShortBuffer()
+                        for (i in 0 until count) {
+                            shorts.put((mixed[offset + i] * 32767f).toInt().toShort())
+                        }
+                        codec.queueInputBuffer(index, 0, count * 2, presentationOf(offset), 0)
+                        offset += count
+                        // Interleaved samples handed to the encoder. The planned
+                        // total travels with it, because the mix's rate and
+                        // channel count are settled here and the JavaScript plan
+                        // must not restate them.
+                        ExportProgress.audio(offset.toLong(), mixed.size.toLong(), encodeEpoch)
+                    }
+                    progressed = true
+                    // Checked inside the feed loop too: this can now run for many
+                    // buffers in a row, and a cancel must not wait out all of them.
+                    checkCancelled()
+                }
+
+                // Drain: everything available, without waiting.
+                while (true) {
+                    val index = codec.dequeueOutputBuffer(info, 0)
+                    if (index == MediaCodec.INFO_OUTPUT_FORMAT_CHANGED) {
+                        track = muxer.addTrack(codec.outputFormat)
+                        muxer.start()
+                        started = true
+                        progressed = true
+                        continue
+                    }
+                    if (index < 0) break
+                    if (info.size > 0 && started &&
+                        (info.flags and MediaCodec.BUFFER_FLAG_CODEC_CONFIG) == 0
+                    ) {
+                        val buffer = codec.getOutputBuffer(index)!!
+                        muxer.writeSampleData(track, buffer, info)
+                        written += 1
+                    }
+                    codec.releaseOutputBuffer(index, false)
+                    progressed = true
+                    if ((info.flags and MediaCodec.BUFFER_FLAG_END_OF_STREAM) != 0) {
+                        outputDone = true
+                        break
+                    }
+                }
+
+                checkCancelled()
+                ExportHeartbeat.beat("audioBlock", encodeEpoch)
+                if (outputDone) break
+
+                if (!progressed) {
+                    /*
+                      Neither side could move, so the encoder is working. One
+                      bounded wait on output — not a spin, and not a wait taken
+                      after every buffer.
+                    */
+                    waits += 1
+                    val at = System.nanoTime()
+                    val index = codec.dequeueOutputBuffer(info, 5_000)
+                    blockedNs += System.nanoTime() - at
+                    if (index == MediaCodec.INFO_OUTPUT_FORMAT_CHANGED) {
+                        track = muxer.addTrack(codec.outputFormat)
+                        muxer.start()
+                        started = true
+                    } else if (index >= 0) {
+                        if (info.size > 0 && started &&
+                            (info.flags and MediaCodec.BUFFER_FLAG_CODEC_CONFIG) == 0
+                        ) {
+                            val buffer = codec.getOutputBuffer(index)!!
+                            muxer.writeSampleData(track, buffer, info)
+                            written += 1
+                        }
+                        codec.releaseOutputBuffer(index, false)
+                        if ((info.flags and MediaCodec.BUFFER_FLAG_END_OF_STREAM) != 0) outputDone = true
+                    }
+                }
+            }
+
+            profile.count("encodeIterations", iterations)
+            profile.count("encodeWaits", waits)
+            profile.count("encodeBlockedNs", blockedNs)
+
+            result.put("ok", true).put("samples", written)
+        } catch (e: Exception) {
+            result.put("ok", false).put("error", "encode: " + e.javaClass.simpleName + ": " + e.message)
+        } finally {
+            encoderEntry?.stoppedNs = System.nanoTime()
+            runCatching { codec?.stop() }
+                .onFailure { encoderEntry?.failure = "stop: " + it.javaClass.simpleName }
+            encoderEntry?.releaseCalledNs = System.nanoTime()
+            runCatching { codec?.release() }
+                .onFailure { encoderEntry?.failure = "release: " + it.javaClass.simpleName }
+            encoderEntry?.releasedNs = System.nanoTime()
+            runCatching { muxer?.stop() }
+            runCatching { muxer?.release() }
+        }
+        return result
+    }
+
+    private fun presentationOf(interleavedOffset: Int): Long =
+        timeAt((interleavedOffset / CHANNELS).toLong())
+}