@pictor-sdk/video-android 0.1.0

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

@@ -0,0 +1,181 @@
+package dev.pictor.video
+
+import java.util.concurrent.atomic.AtomicLong
+
+/**
+ * Whether a frame is waiting to be latched, as a level rather than an edge.
+ *
+ * `onFrameAvailable` is an edge: it fires once, and whoever was not listening at
+ * that instant never learns it happened. The consumer stops when the app
+ * backgrounds for the system picker, so every frame that arrives in that window
+ * is announced to nobody — and on return the consumer waits for the *next*
+ * edge. A paused player produces no next edge, so the preview stays black
+ * forever with no error anywhere and the producer's counters all healthy.
+ *
+ * Two monotonic counters instead. Availability is a level — `available >
+ * consumed` — which is true whenever there is something to take, however long
+ * ago it arrived and whoever was or was not listening at the time.
+ *
+ * ## Coalescing is the point, not a side effect
+ *
+ * A `SurfaceTexture` holds one buffer: `updateTexImage` latches the *newest*
+ * frame and drops whatever it skipped. So a successful latch sets `consumed` to
+ * whatever `available` had reached, which is the honest accounting — thirty
+ * frames arrived while backgrounded and exactly one of them can ever be shown.
+ * Incrementing `consumed` by one per latch would leave the difference positive
+ * forever and the consumer spinning on frames that no longer exist.
+ *
+ * ## A latch accounts for what it saw, never for what arrived meanwhile
+ *
+ * `updateTexImage` takes the newest buffer *as of the call*, so a latch may
+ * legitimately account for many announcements at once. It may not account for
+ * one that arrived while it was running: that frame was not taken, and setting
+ * `consumed` to the count as it stands afterwards would erase its only
+ * announcement — the edge has already been delivered and no second one is
+ * coming for the same buffer.
+ *
+ * So the mark is read *before* the acquisition and consumed *up to* that mark.
+ * Measured on the device, the erasing form left `announced` one ahead of every
+ * successful latch with nothing pending: a frame delivered, dropped, and no
+ * longer recorded as either.
+ *
+ * ## A failed latch restores nothing, because it took nothing
+ *
+ * `consumed` only moves on success. `updateTexImage` returns quietly when the
+ * GL context is not current, so a failure means the buffer is still there —
+ * leaving the counter alone *is* the restore, and there is no window in which a
+ * frame is neither pending nor latched.
+ *
+ * ## Generations
+ *
+ * Availability is tagged with the surface generation it arrived for. A frame
+ * pending against a retired surface is not a frame: the texture it belongs to is
+ * gone, and latching it would pull from a texture nobody is drawing. Retirement
+ * is the **only** thing that discards a pending frame; disarming the consumer
+ * must not, which is the whole reason this type exists.
+ *
+ * Free of Android types so the orderings are testable on the JVM without a
+ * device, a codec or a surface.
+ */
+internal class FramePending {
+
+    /** Frames announced, ever. Only increases within a generation. */
+    private val available = AtomicLong(0)
+
+    /** Frames accounted for by a successful latch. */
+    private val consumed = AtomicLong(0)
+
+    /** The generation the counts above belong to. */
+    @Volatile
+    var generation: Int = SurfaceAttachment.NONE
+        private set
+
+    /** Availability signals that arrived for a generation already retired. */
+    @Volatile
+    var rejected: Long = 0
+        private set
+
+    /** Total announcements, for the overlay. Survives generation changes. */
+    @Volatile
+    var announced: Long = 0
+        private set
+
+    /** Begin counting for a live surface. Discards anything the old one had. */
+    fun adopt(generation: Int) {
+        if (this.generation == generation) return
+        this.generation = generation
+        available.set(0)
+        consumed.set(0)
+    }
+
+    /**
+     * A frame arrived.
+     *
+     * Takes the generation it arrived for: a listener detached late can fire
+     * after its surface is gone, and that frame belongs to a texture that no
+     * longer exists.
+     */
+    fun mark(generation: Int) {
+        if (generation != this.generation || generation == SurfaceAttachment.NONE) {
+            rejected += 1
+            return
+        }
+        announced += 1
+        available.incrementAndGet()
+    }
+
+    /** Whether a frame is waiting for [generation] right now. */
+    fun pending(generation: Int): Boolean =
+        generation == this.generation &&
+            generation != SurfaceAttachment.NONE &&
+            available.get() > consumed.get()
+
+    /**
+     * Pending-ness, depth and generation as **one** reading.
+     *
+     * Three separate calls are three separate instants. A consumer that asked
+     * "is anything pending" (no), then "how deep is it" (one, because a frame
+     * arrived in between), concluded the two halves disagreed — when in fact
+     * both answers were true when given. That is a sampling artefact, and
+     * suppressing the counter would have hidden a check that has real work to
+     * do.
+     *
+     * Packed rather than returned as an object so it crosses JNI as one value
+     * and cannot be torn: depth in the high bits, generation in the middle, and
+     * pending in the low bit.
+     */
+    fun snapshot(generation: Int): Long {
+        val available = this.available.get()
+        val consumed = this.consumed.get()
+        val current = this.generation
+        val matches = generation == current && generation != SurfaceAttachment.NONE
+        val depth = (available - consumed).coerceAtLeast(0).coerceAtMost(0xffff)
+        val pending = if (matches && available > consumed) 1L else 0L
+        return (depth shl 32) or ((current.toLong() and 0xffff) shl 1) or pending
+    }
+
+    /**
+     * The announcement count right now, for a latch that is about to begin.
+     *
+     * [SurfaceAttachment.NONE] generations and stale ones get -1, which
+     * [consumeUpTo] refuses — so a mark taken against a surface that is retired
+     * mid-latch cannot be applied to its replacement's counters.
+     */
+    fun observe(generation: Int): Long =
+        if (generation != this.generation || generation == SurfaceAttachment.NONE) -1
+        else available.get()
+
+    /**
+     * A latch succeeded: everything announced *as of [mark]* is accounted for.
+     *
+     * Coalesced to the newest the latch could have seen, deliberately — see the
+     * note above. Never past [mark], which is what keeps a frame announced
+     * during the acquisition pending for the next tick instead of vanishing.
+     */
+    fun consumeUpTo(generation: Int, mark: Long) {
+        if (generation != this.generation || mark < 0) return
+        while (true) {
+            val current = consumed.get()
+            // Monotonic: a late mark from an overlapping latch must not move
+            // `consumed` backwards and re-announce frames already shown.
+            if (current >= mark) return
+            if (consumed.compareAndSet(current, mark)) return
+        }
+    }
+
+    /**
+     * The surface is gone.
+     *
+     * The only thing that may discard a pending frame, because it is the only
+     * thing that makes one meaningless.
+     */
+    fun retire(generation: Int) {
+        if (generation != this.generation) return
+        this.generation = SurfaceAttachment.NONE
+        available.set(0)
+        consumed.set(0)
+    }
+
+    /** How many frames are outstanding. Diagnostics; usually 0 or 1. */
+    fun depth(): Long = (available.get() - consumed.get()).coerceAtLeast(0)
+}

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

@@ -0,0 +1,456 @@
+package dev.pictor.video
+
+import android.content.Context
+import android.media.MediaCodec
+import android.media.MediaExtractor
+import android.media.MediaFormat
+import android.net.Uri
+import java.nio.ByteBuffer
+import kotlin.math.abs
+import kotlin.math.cos
+import kotlin.math.ln
+import kotlin.math.sin
+import kotlin.math.sqrt
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * Decoded audio, measured — the gate's ear.
+ *
+ * A speed change that shifts pitch and one that preserves it produce files whose
+ * duration, frame count and sample count are identical. Only the spectrum tells
+ * them apart, so the gate has to listen rather than count.
+ *
+ * Reports numbers and draws no conclusion. What counts as "near enough to 440"
+ * or "quiet enough to be silence" is the caller's predeclared business.
+ */
+internal object GateAudio {
+
+    /**
+     * A dominant-frequency trajectory and harmonic band energies, per window.
+     *
+     * A single window over a whole section answers "what note is this" and
+     * nothing else: a steady 434 Hz and a 434 Hz wobbling by fifteen either way
+     * both report 434. Modulation only exists between windows, so this reports
+     * the sequence and lets the caller decide what its spread means.
+     *
+     * The peak is refined by parabolic interpolation, because the raw bin
+     * spacing at a window short enough to see modulation is wider than the
+     * modulation being looked for -- 11.7 Hz bins cannot resolve a few Hz of
+     * wander, and a trajectory quantised to the bin grid would report a flat
+     * line for any wobble smaller than one bin.
+     *
+     * Reports numbers only. Nothing here decides what is natural.
+     */
+    fun trajectory(context: Context, uri: String, specJson: String): String {
+        val out = JSONObject()
+        val extractor = MediaExtractor()
+        var codec: MediaCodec? = null
+        try {
+            if (uri.startsWith("/")) extractor.setDataSource(uri)
+            else extractor.setDataSource(context, Uri.parse(uri), null)
+            var track = -1
+            var format: MediaFormat? = null
+            for (i in 0 until extractor.trackCount) {
+                val f = extractor.getTrackFormat(i)
+                if ((f.getString(MediaFormat.KEY_MIME) ?: "").startsWith("audio/")) {
+                    track = i; format = f; break
+                }
+            }
+            if (track < 0 || format == null) {
+                return out.put("ok", false).put("error", "no audio track").toString()
+            }
+            extractor.selectTrack(track)
+            val mime = format.getString(MediaFormat.KEY_MIME)!!
+            val rate = format.getInteger(MediaFormat.KEY_SAMPLE_RATE)
+            val channels = format.getInteger(MediaFormat.KEY_CHANNEL_COUNT)
+            codec = MediaCodec.createDecoderByType(mime)
+            codec.configure(format, null, null, 0)
+            codec.start()
+            val pcm = ArrayList<Float>(rate * 12)
+            val info = MediaCodec.BufferInfo()
+            var inputDone = false
+            var outputDone = false
+            var guard = 0
+            while (!outputDone && guard < 100_000) {
+                guard += 1
+                if (!inputDone) {
+                    val index = codec.dequeueInputBuffer(10_000)
+                    if (index >= 0) {
+                        val buffer = codec.getInputBuffer(index)!!
+                        val size = extractor.readSampleData(buffer, 0)
+                        if (size < 0) {
+                            codec.queueInputBuffer(index, 0, 0, 0, MediaCodec.BUFFER_FLAG_END_OF_STREAM)
+                            inputDone = true
+                        } else {
+                            codec.queueInputBuffer(index, 0, size, extractor.sampleTime, 0)
+                            extractor.advance()
+                        }
+                    }
+                }
+                val index = codec.dequeueOutputBuffer(info, 10_000)
+                if (index >= 0) {
+                    if (info.size > 0) {
+                        val buffer = codec.getOutputBuffer(index)!!
+                        buffer.position(info.offset)
+                        buffer.limit(info.offset + info.size)
+                        val shorts = buffer.asShortBuffer()
+                        var i = 0
+                        while (i + channels <= shorts.limit()) {
+                            var sum = 0f
+                            for (c in 0 until channels) sum += shorts.get(i + c) / 32768f
+                            pcm.add(sum / channels)
+                            i += channels
+                        }
+                    }
+                    codec.releaseOutputBuffer(index, false)
+                    if ((info.flags and MediaCodec.BUFFER_FLAG_END_OF_STREAM) != 0) outputDone = true
+                }
+            }
+
+            val spec = JSONObject(specJson)
+            val n = spec.optInt("windowFrames", 4096)
+            val hop = spec.optInt("hopFrames", 1024)
+            val loHz = spec.optDouble("searchLoHz", 300.0)
+            val hiHz = spec.optDouble("searchHiHz", 600.0)
+            val bandHz = spec.optDouble("bandHz", 40.0)
+            val harmonics = spec.optJSONArray("harmonicsHz") ?: JSONArray()
+            val exclude = spec.optJSONArray("excludeUs") ?: JSONArray()
+            val from = ((spec.getLong("startUs") * rate) / 1_000_000L).toInt().coerceAtLeast(0)
+            val to = ((spec.getLong("endUs") * rate) / 1_000_000L).toInt().coerceAtMost(pcm.size)
+
+            val f0s = JSONArray()
+            val times = JSONArray()
+            val harmDb = Array(harmonics.length()) { ArrayList<Double>() }
+            var skipped = 0
+            var start = from
+            while (start + n <= to) {
+                val centreUs = (start + n / 2).toLong() * 1_000_000L / rate
+                var excluded = false
+                for (e in 0 until exclude.length()) {
+                    val pair = exclude.getJSONArray(e)
+                    if (centreUs >= pair.getLong(0) && centreUs <= pair.getLong(1)) { excluded = true; break }
+                }
+                if (excluded) { skipped += 1; start += hop; continue }
+
+                val w = DoubleArray(n)
+                for (i in 0 until n) {
+                    val hann = 0.5 - 0.5 * cos(2.0 * Math.PI * i / (n - 1))
+                    w[i] = pcm[start + i].toDouble() * hann
+                }
+                fun power(k: Int): Double {
+                    var re = 0.0; var im = 0.0
+                    val step = 2.0 * Math.PI * k / n
+                    for (i in 0 until n) { re += w[i] * cos(step * i); im += w[i] * sin(step * i) }
+                    return re * re + im * im
+                }
+                val kLo = (loHz * n / rate).toInt().coerceAtLeast(1)
+                val kHi = (hiHz * n / rate).toInt().coerceAtMost(n / 2 - 2)
+                var bestK = kLo; var bestP = -1.0
+                for (k in kLo..kHi) { val p = power(k); if (p > bestP) { bestP = p; bestK = k } }
+                // Parabolic on the log spectrum: sub-bin, which is the only way a
+                // window short enough to show modulation can measure it.
+                val pm = ln(power(bestK - 1) + 1e-30)
+                val p0 = ln(bestP + 1e-30)
+                val pp = ln(power(bestK + 1) + 1e-30)
+                val denom = pm - 2 * p0 + pp
+                val delta = if (denom != 0.0) 0.5 * (pm - pp) / denom else 0.0
+                val f0 = (bestK + delta.coerceIn(-1.0, 1.0)) * rate / n
+                f0s.put(Math.round(f0 * 100.0) / 100.0)
+                times.put(centreUs)
+
+                fun bandPower(centre: Double): Double {
+                    val a = ((centre - bandHz) * n / rate).toInt().coerceAtLeast(1)
+                    val b = ((centre + bandHz) * n / rate).toInt().coerceAtMost(n / 2 - 1)
+                    var sum = 0.0
+                    for (k in a..b) sum += power(k)
+                    return sum
+                }
+                val fund = bandPower(f0)
+                for (h in 0 until harmonics.length()) {
+                    val hz = harmonics.getDouble(h)
+                    val p = bandPower(hz)
+                    harmDb[h].add(10.0 * kotlin.math.log10((p + 1e-30) / (fund + 1e-30)))
+                }
+                start += hop
+            }
+
+            fun stats(v: List<Double>): JSONObject {
+                if (v.isEmpty()) return JSONObject().put("count", 0)
+                val sorted = v.sorted()
+                val median = sorted[sorted.size / 2]
+                val mean = v.sum() / v.size
+                var s2 = 0.0
+                for (x in v) s2 += (x - mean) * (x - mean)
+                val sd = sqrt(s2 / v.size)
+                var outliers = 0
+                for (x in v) if (sd > 0 && abs(x - median) > 3 * sd) outliers += 1
+                return JSONObject()
+                    .put("count", v.size)
+                    .put("median", Math.round(median * 100.0) / 100.0)
+                    .put("sd", Math.round(sd * 1000.0) / 1000.0)
+                    .put("peakToPeak", Math.round((sorted.last() - sorted.first()) * 100.0) / 100.0)
+                    .put("outliers", outliers)
+            }
+            val f0List = ArrayList<Double>()
+            for (i in 0 until f0s.length()) f0List.add(f0s.getDouble(i))
+            val harmonicStats = JSONArray()
+            for (h in 0 until harmonics.length()) {
+                harmonicStats.put(
+                    JSONObject().put("hz", harmonics.getDouble(h)).put("db", stats(harmDb[h])),
+                )
+            }
+            out.put("ok", true).put("sampleRate", rate).put("windows", f0s.length())
+                .put("skipped", skipped).put("f0", stats(f0List))
+                .put("harmonics", harmonicStats)
+        } catch (e: Exception) {
+            out.put("ok", false).put("error", e.javaClass.simpleName + ": " + e.message)
+        } finally {
+            runCatching { codec?.stop() }
+            runCatching { codec?.release() }
+            runCatching { extractor.release() }
+        }
+        return out.toString()
+    }
+
+    /** Bins are 44100/4096 ≈ 10.8 Hz apart, which resolves 440 from 220 and 880. */
+    private const val WINDOW = 4096
+
+    /**
+     * Per-window loudness and spectrum, plus the timing metadata a seam check
+     * needs: AAC carries encoder delay and trailing padding, and its first
+     * sample often has a negative timestamp. Aligning a click to a video frame
+     * without those is off by a couple of thousand samples for reasons that look
+     * like a sync bug.
+     */
+    fun analyse(context: Context, uri: String, windowsJson: String): String {
+        val out = JSONObject()
+        val extractor = MediaExtractor()
+        var codec: MediaCodec? = null
+        try {
+            if (uri.startsWith("/")) extractor.setDataSource(uri)
+            else extractor.setDataSource(context, Uri.parse(uri), null)
+
+            var track = -1
+            var format: MediaFormat? = null
+            for (i in 0 until extractor.trackCount) {
+                val f = extractor.getTrackFormat(i)
+                if ((f.getString(MediaFormat.KEY_MIME) ?: "").startsWith("audio/")) {
+                    track = i; format = f; break
+                }
+            }
+            if (track < 0 || format == null) {
+                return out.put("ok", false).put("error", "no audio track").toString()
+            }
+            extractor.selectTrack(track)
+
+            val mime = format.getString(MediaFormat.KEY_MIME)!!
+            val sampleRate = format.getInteger(MediaFormat.KEY_SAMPLE_RATE)
+            val channels = format.getInteger(MediaFormat.KEY_CHANNEL_COUNT)
+            out.put("sampleRate", sampleRate).put("channels", channels).put("mime", mime)
+            out.put(
+                "encoderDelay",
+                if (format.containsKey("encoder-delay")) format.getInteger("encoder-delay") else -1,
+            )
+            out.put(
+                "encoderPadding",
+                if (format.containsKey("encoder-padding")) format.getInteger("encoder-padding") else -1,
+            )
+            out.put(
+                "formatDurationUs",
+                if (format.containsKey(MediaFormat.KEY_DURATION)) format.getLong(MediaFormat.KEY_DURATION) else -1L,
+            )
+
+            codec = MediaCodec.createDecoderByType(mime)
+            codec.configure(format, null, null, 0)
+            codec.start()
+
+            // Mono mixdown: the fixtures are mono and a stereo file's channels
+            // would otherwise interleave into the spectrum as noise.
+            val pcm = ArrayList<Float>(sampleRate * 12)
+            var firstPtsUs = Long.MIN_VALUE
+            val info = MediaCodec.BufferInfo()
+            var sawInputEos = false
+            var sawOutputEos = false
+            var guard = 0
+            while (!sawOutputEos && guard < 100_000) {
+                guard += 1
+                if (!sawInputEos) {
+                    val index = codec.dequeueInputBuffer(10_000)
+                    if (index >= 0) {
+                        val buffer = codec.getInputBuffer(index)!!
+                        val size = extractor.readSampleData(buffer, 0)
+                        if (size < 0) {
+                            codec.queueInputBuffer(index, 0, 0, 0, MediaCodec.BUFFER_FLAG_END_OF_STREAM)
+                            sawInputEos = true
+                        } else {
+                            codec.queueInputBuffer(index, 0, size, extractor.sampleTime, 0)
+                            extractor.advance()
+                        }
+                    }
+                }
+                val index = codec.dequeueOutputBuffer(info, 10_000)
+                if (index >= 0) {
+                    if (info.size > 0) {
+                        if (firstPtsUs == Long.MIN_VALUE) firstPtsUs = info.presentationTimeUs
+                        val buffer: ByteBuffer = codec.getOutputBuffer(index)!!
+                        buffer.position(info.offset)
+                        buffer.limit(info.offset + info.size)
+                        val shorts = buffer.asShortBuffer()
+                        var i = 0
+                        while (i + channels <= shorts.limit()) {
+                            var sum = 0f
+                            for (c in 0 until channels) sum += shorts.get(i + c) / 32768f
+                            pcm.add(sum / channels)
+                            i += channels
+                        }
+                    }
+                    codec.releaseOutputBuffer(index, false)
+                    if ((info.flags and MediaCodec.BUFFER_FLAG_END_OF_STREAM) != 0) sawOutputEos = true
+                }
+            }
+
+            out.put("firstPtsUs", if (firstPtsUs == Long.MIN_VALUE) 0 else firstPtsUs)
+            out.put("decodedSamples", pcm.size)
+            out.put("decodedDurationUs", pcm.size.toLong() * 1_000_000L / sampleRate)
+
+            val windows = JSONArray(windowsJson)
+            val results = JSONArray()
+            for (w in 0 until windows.length()) {
+                val spec = windows.getJSONObject(w)
+                val startUs = spec.getLong("startUs")
+                val endUs = spec.getLong("endUs")
+                val from = ((startUs * sampleRate) / 1_000_000L).toInt().coerceAtLeast(0)
+                val to = ((endUs * sampleRate) / 1_000_000L).toInt().coerceAtMost(pcm.size)
+                val entry = JSONObject().put("startUs", startUs).put("endUs", endUs)
+                if (to - from < 16) {
+                    results.put(entry.put("error", "window has ${to - from} samples"))
+                    continue
+                }
+                var peak = 0f
+                var energy = 0.0
+                for (i in from until to) {
+                    val v = pcm[i]
+                    if (abs(v) > peak) peak = abs(v)
+                    energy += v.toDouble() * v.toDouble()
+                }
+                entry.put("samples", to - from)
+                entry.put("rms", sqrt(energy / (to - from)))
+                entry.put("peak", peak.toDouble())
+
+                /*
+                  The largest sample-to-sample step in the window.
+
+                  A seam click is a discontinuity, and a discontinuity is not
+                  visible in rms or in a spectrum peak -- a window containing a
+                  hard splice and one containing a clean tone can have the same
+                  loudness and the same dominant frequency. A tone of amplitude a
+                  at frequency f steps by at most 2*pi*f*a/rate between samples,
+                  so a step far above that is a splice rather than a signal.
+                */
+                var maxStep = 0f
+                for (i in from + 1 until to) {
+                    val step = abs(pcm[i] - pcm[i - 1])
+                    if (step > maxStep) maxStep = step
+                }
+                entry.put("maxStep", maxStep.toDouble())
+                if (spec.optBoolean("stepAt")) {
+                    // Where the largest step is, in microseconds: one splice and
+                    // a rough passage look the same in a maximum alone.
+                    var at = from
+                    var best = 0f
+                    for (i in from + 1 until to) {
+                        val step = abs(pcm[i] - pcm[i - 1])
+                        if (step > best) { best = step; at = i }
+                    }
+                    entry.put("stepAtUs", at.toLong() * 1_000_000L / sampleRate)
+                }
+
+                /*
+                  Energy in a narrow band, when the caller names one.
+
+                  Alignment is measured by asking which frame carries the marker
+                  burst, and "which frame is loudest at 2 kHz" is a different
+                  question from "what is the dominant frequency" -- under a music
+                  bed the burst can be present and clearly located without ever
+                  being dominant.
+                */
+                if (spec.has("bandHz")) {
+                    val target = spec.getDouble("bandHz")
+                    val n2 = minOf(WINDOW, to - from)
+                    var band = 0.0
+                    if (n2 >= 128) {
+                        val half = (100.0 * n2 / sampleRate).toInt().coerceAtLeast(1)
+                        val centre = (target * n2 / sampleRate).toInt()
+                        for (k in (centre - half).coerceAtLeast(1)..(centre + half).coerceAtMost(n2 / 2 - 1)) {
+                            var re = 0.0
+                            var im = 0.0
+                            val step = 2.0 * Math.PI * k / n2
+                            for (i in 0 until n2) {
+                                val hann = 0.5 - 0.5 * cos(2.0 * Math.PI * i / (n2 - 1))
+                                re += pcm[from + i] * hann * cos(step * i)
+                                im += pcm[from + i] * hann * sin(step * i)
+                            }
+                            band += re * re + im * im
+                        }
+                    }
+                    entry.put("bandEnergy", band)
+                }
+
+                val n = minOf(WINDOW, to - from)
+                if (n >= 256) {
+                    // Hann, so a tone that does not fit a whole number of cycles
+                    // does not smear across every bin and drown its own peak.
+                    val windowed = DoubleArray(n)
+                    for (i in 0 until n) {
+                        val hann = 0.5 - 0.5 * cos(2.0 * Math.PI * i / (n - 1))
+                        windowed[i] = pcm[from + i].toDouble() * hann
+                    }
+                    var bestMag = 0.0
+                    var bestBin = 0
+                    val minBin = (50.0 * n / sampleRate).toInt().coerceAtLeast(1)
+                    val maxBin = (5000.0 * n / sampleRate).toInt().coerceAtMost(n / 2 - 1)
+                    val mags = DoubleArray(maxBin + 1)
+                    for (k in minBin..maxBin) {
+                        var re = 0.0
+                        var im = 0.0
+                        val step = 2.0 * Math.PI * k / n
+                        for (i in 0 until n) {
+                            re += windowed[i] * cos(step * i)
+                            im += windowed[i] * sin(step * i)
+                        }
+                        val mag = re * re + im * im
+                        mags[k] = mag
+                        if (mag > bestMag) { bestMag = mag; bestBin = k }
+                    }
+                    var total = 0.0
+                    for (k in minBin..maxBin) total += mags[k]
+                    var nearPeak = 0.0
+                    for (k in (bestBin - 2).coerceAtLeast(minBin)..(bestBin + 2).coerceAtMost(maxBin)) {
+                        nearPeak += mags[k]
+                    }
+                    entry.put("dominantHz", bestBin.toDouble() * sampleRate / n)
+                    entry.put("binHz", sampleRate.toDouble() / n)
+                    /*
+                      How much of the energy is the tone itself.
+
+                      Reported beside the pitch, never folded into it: a
+                      time-stretch can hold the fundamental exactly and still
+                      sound wrong, so "the frequency is right" is not a claim
+                      about quality.
+                    */
+                    entry.put("peakEnergyFraction", if (total > 0) nearPeak / total else 0.0)
+                }
+                results.put(entry)
+            }
+            out.put("windows", results).put("ok", true)
+        } catch (e: Exception) {
+            out.put("ok", false).put("error", e.javaClass.simpleName + ": " + e.message)
+        } finally {
+            runCatching { codec?.stop() }
+            runCatching { codec?.release() }
+            runCatching { extractor.release() }
+        }
+        return out.toString()
+    }
+}