@pictor-sdk/video-android 0.1.0

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

@@ -0,0 +1,299 @@
+package dev.pictor.video
+
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * A compiled scene program, validated, with segment selection by binary search.
+ *
+ * **This is the whole of native's timeline knowledge.** Given a presentation
+ * timestamp it finds the half-open interval containing it and executes the
+ * commands stored there. It performs no trim arithmetic, no speed arithmetic,
+ * no overlay-span arithmetic and no playlist placement: the compiler in
+ * TypeScript settled all of that, and any of it here would be the second
+ * interpreter the architecture exists to prevent.
+ *
+ * The transport matters as much as the selection. A timeline resolves to a
+ * different scene at every instant, but its *structure* changes only at clip
+ * placements and overlay boundaries — so a program is as long as the number of
+ * distinct scenes rather than the number of frames, and one document covers a
+ * whole export.
+ */
+internal class SceneProgramNative private constructor(
+    val durationUs: Long,
+    val projectWidth: Int,
+    val projectHeight: Int,
+    private val fromUs: LongArray,
+    private val toUs: LongArray,
+    private val clearColor: IntArray,
+    private val clipIds: Array<String?>,
+    private val windowIndex: IntArray,
+    /**
+     * Six affine values per segment, exactly as `resolveVideoScene` emitted them.
+     *
+     * Native never receives x, y, scale, rotation or flip and never reconstructs
+     * them. Those are the resolver's inputs; the matrix is its output, and
+     * decomposing it here would be a second placement rule that could disagree
+     * with the first.
+     */
+    private val matrices: FloatArray,
+    /** Per-segment clip opacity, exactly as the resolver emitted it. */
+    private val opacities: FloatArray,
+    /** Overlay draws per segment, already in the resolver's z order. */
+    private val overlays: Array<List<Overlay>>,
+) {
+    /**
+     * One overlay draw: a name, a placement and an alpha.
+     *
+     * No extent. The resolver cannot know how big a text block is, so it places
+     * the centre and the backend applies the measured half-extent that arrived
+     * with the resource — the same split preview uses.
+     */
+    class Overlay(
+        val overlayId: String,
+        val resourceId: String,
+        val matrix: FloatArray,
+        val opacity: Float,
+        val z: Int,
+    )
+    val segmentCount: Int get() = fromUs.size
+
+    /**
+     * The segment containing `timeUs`, or `-1`.
+     *
+     * Binary search over sorted, contiguous, half-open intervals — a lookup, and
+     * the only selection rule there is.
+     */
+    fun segmentAt(timeUs: Long): Int {
+        var lo = 0
+        var hi = fromUs.size - 1
+        while (lo <= hi) {
+            val mid = (lo + hi) ushr 1
+            when {
+                timeUs < fromUs[mid] -> hi = mid - 1
+                timeUs >= toUs[mid] -> lo = mid + 1
+                else -> return mid
+            }
+        }
+        return -1
+    }
+
+    fun clearColorAt(index: Int): Int = clearColor[index]
+
+    /** The window this segment's video command names, or -1 when it has none. */
+    fun windowAt(index: Int): Int = windowIndex[index]
+
+    fun clipAt(index: Int): String? = clipIds[index]
+
+    /** Overlay draws for this segment, in z order. */
+    fun overlaysAt(index: Int): List<Overlay> = overlays[index]
+
+    /** Every resource id the program references, for preloading. */
+    fun requiredResourceIds(): Set<String> {
+        val ids = LinkedHashSet<String>()
+        for (list in overlays) for (o in list) ids.add(o.resourceId)
+        return ids
+    }
+
+    /** Clip opacity for this segment, in `[0, 1]`. */
+    fun opacityAt(index: Int): Float = opacities[index]
+
+    /** `[a, b, c, d, tx, ty]` for this segment, in project space. */
+    fun matrixAt(index: Int, out: FloatArray) {
+        System.arraycopy(matrices, index * 6, out, 0, 6)
+    }
+
+    class Invalid(val reason: String)
+
+    companion object {
+        const val SUPPORTED_VERSION = 2
+        const val SUPPORTED_SCENE_VERSION = 2
+        private val SUPPORTED_OPS = setOf("clear", "video", "overlay")
+
+        fun parse(json: String): Pair<SceneProgramNative?, Invalid?> {
+            val root = try {
+                JSONObject(json)
+            } catch (e: Exception) {
+                return null to Invalid("malformed JSON: ${e.message}")
+            }
+            val version = root.optInt("version", -1)
+            if (version != SUPPORTED_VERSION) {
+                return null to Invalid("unsupported program version $version, expected $SUPPORTED_VERSION")
+            }
+            val durationUs = root.optLong("durationUs", -1)
+            if (durationUs <= 0) return null to Invalid("durationUs is not positive")
+            val size = root.optJSONObject("projectSize")
+                ?: return null to Invalid("projectSize is not an object")
+            val width = size.optDouble("width", Double.NaN)
+            val height = size.optDouble("height", Double.NaN)
+            if (width.isNaN() || height.isNaN() || width <= 0 || height <= 0) {
+                return null to Invalid("projectSize is not a positive finite size")
+            }
+            val segments = root.optJSONArray("segments")
+                ?: return null to Invalid("segments is not an array")
+            val count = segments.length()
+            if (count == 0) return null to Invalid("program has no segments")
+
+            val from = LongArray(count)
+            val to = LongArray(count)
+            val clears = IntArray(count)
+            val clips = arrayOfNulls<String>(count)
+            val windows = IntArray(count) { -1 }
+            val opacities = FloatArray(count) { 1f }
+            val overlays = Array(count) { mutableListOf<Overlay>() }
+            val matrices = FloatArray(count * 6)
+            for (i in 0 until count) matrices[i * 6] = 1f
+            for (i in 0 until count) matrices[i * 6 + 3] = 1f
+
+            for (i in 0 until count) {
+                val segment = segments.optJSONObject(i)
+                    ?: return null to Invalid("segment $i is not an object")
+                val f = segment.optLong("fromUs", -1)
+                val t = segment.optLong("toUs", -1)
+                if (f < 0 || t < 0) return null to Invalid("segment $i has no interval")
+                if (t <= f) return null to Invalid("segment $i is empty or inverted")
+                // Sorted, contiguous, gap-free — checked rather than trusted,
+                // because a backend that selects by binary search cannot detect
+                // any of these at execution time. It would simply draw the wrong
+                // scene, or none, and encode that permanently.
+                if (i == 0 && f != 0L) return null to Invalid("first segment starts at $f, not 0")
+                if (i > 0) {
+                    if (f < to[i - 1]) return null to Invalid("segment $i overlaps ${i - 1}")
+                    if (f > to[i - 1]) return null to Invalid("gap between segments ${i - 1} and $i")
+                }
+                if (t > durationUs) return null to Invalid("segment $i ends past the duration")
+                from[i] = f
+                to[i] = t
+
+                val commands = segment.optJSONArray("commands")
+                    ?: return null to Invalid("segment $i has no commands")
+                val problem = readCommands(i, commands, clears, clips, windows, matrices, opacities, overlays[i])
+                if (problem != null) return null to problem
+            }
+            if (to[count - 1] != durationUs) {
+                return null to Invalid("last segment ends at ${to[count - 1]}, not $durationUs")
+            }
+
+            return SceneProgramNative(
+                durationUs, width.toInt(), height.toInt(), from, to, clears, clips, windows, matrices,
+                opacities,
+                Array(count) { overlays[it].sortedBy { o -> o.z } },
+            ) to null
+        }
+
+        private fun readCommands(
+            index: Int,
+            commands: JSONArray,
+            clears: IntArray,
+            clips: Array<String?>,
+            windows: IntArray,
+            matrices: FloatArray,
+            opacities: FloatArray,
+            overlays: MutableList<Overlay>,
+        ): Invalid? {
+            var sawClear = false
+            for (k in 0 until commands.length()) {
+                val command = commands.optJSONObject(k)
+                    ?: return Invalid("segment $index command $k is not an object")
+                val op = command.optString("op", "")
+                if (op !in SUPPORTED_OPS) {
+                    // Refused, never skipped: a dropped command is a frame
+                    // quietly missing something the timeline said was there.
+                    return Invalid("segment $index command $k has unsupported op '$op'")
+                }
+                if (op == "clear") {
+                    if (k != 0) return Invalid("segment $index has clear at $k, not first")
+                    val color = parseColor(command.optString("color", ""))
+                        ?: return Invalid("segment $index has an unparseable clear color")
+                    clears[index] = color
+                    sawClear = true
+                } else if (op == "overlay") {
+                    if (!sawClear) return Invalid("segment $index has an overlay before clear")
+                    val overlayId = command.optString("overlayId", "")
+                    if (overlayId.isEmpty()) return Invalid("segment $index overlay has no overlayId")
+                    val resourceId = command.optString("resourceId", "")
+                    if (resourceId.isEmpty()) return Invalid("segment $index overlay has no resourceId")
+                    val matrix = command.optJSONArray("matrix")
+                        ?: return Invalid("segment $index overlay has no matrix")
+                    if (matrix.length() != 6) return Invalid("segment $index overlay matrix is not six numbers")
+                    val m = FloatArray(6)
+                    for (k in 0 until 6) {
+                        val v = matrix.optDouble(k, Double.NaN)
+                        if (!finite(v)) return Invalid("segment $index overlay matrix[$k] is not finite")
+                        m[k] = v.toFloat()
+                    }
+                    val det = m[0] * m[3] - m[1] * m[2]
+                    if (det == 0f) return Invalid("segment $index overlay matrix is singular")
+                    val alpha = command.optDouble("opacity", Double.NaN)
+                    if (!finite(alpha)) return Invalid("segment $index overlay opacity is not finite")
+                    if (alpha < 0.0 || alpha > 1.0) {
+                        return Invalid("segment $index overlay opacity $alpha is outside [0, 1]")
+                    }
+                    overlays.add(
+                        Overlay(overlayId, resourceId, m, alpha.toFloat(), command.optInt("z", overlays.size)),
+                    )
+                } else {
+                    if (!sawClear) return Invalid("segment $index has video before clear")
+                    if (clips[index] != null) return Invalid("segment $index has two video commands")
+                    val id = command.optString("clipId", "")
+                    if (id.isEmpty()) return Invalid("segment $index video has no clipId")
+                    val window = command.optInt("windowIndex", -1)
+                    if (window < 0) return Invalid("segment $index video has no windowIndex")
+                    val matrix = command.optJSONArray("matrix")
+                        ?: return Invalid("segment $index video has no matrix")
+                    if (matrix.length() != 6) return Invalid("segment $index matrix is not six numbers")
+                    for (m in 0 until 6) {
+                        val value = matrix.optDouble(m, Double.NaN)
+                        if (value.isNaN() || value.isInfinite()) {
+                            return Invalid("segment $index matrix[$m] is not finite")
+                        }
+                    }
+                    /*
+                      Singular matrices are refused before anything starts.
+
+                      A zero determinant collapses the source to a line or a
+                      point. GL will draw it without complaint — a degenerate
+                      quad rasterises to nothing — and the export would succeed
+                      with a clip silently missing. There is no picture that
+                      correctly represents it, so it is not drawn at all.
+                    */
+                    val det = matrix.optDouble(0) * matrix.optDouble(3) -
+                        matrix.optDouble(1) * matrix.optDouble(2)
+                    if (!finite(det) || det == 0.0) {
+                        return Invalid("segment $index has a singular matrix")
+                    }
+                    for (m in 0 until 6) matrices[index * 6 + m] = matrix.optDouble(m).toFloat()
+                    /*
+                      Taken as given, never clamped.
+
+                      The resolver clamps to [0, 1] and substitutes 1 for a
+                      non-finite value; that is the single place the rule lives.
+                      A backend that clamped as well would silently accept a
+                      scene the resolver would have rejected, and the two would
+                      disagree about what a malformed document draws. So anything
+                      outside the range is refused before the export starts.
+                    */
+                    val opacity = command.optDouble("opacity", Double.NaN)
+                    if (!finite(opacity)) return Invalid("segment $index opacity is not finite")
+                    if (opacity < 0.0 || opacity > 1.0) {
+                        return Invalid("segment $index opacity $opacity is outside [0, 1]")
+                    }
+                    opacities[index] = opacity.toFloat()
+                    clips[index] = id
+                    windows[index] = window
+                }
+            }
+            if (!sawClear) return Invalid("segment $index has no clear")
+            return null
+        }
+
+        private fun finite(value: Double) = !value.isNaN() && !value.isInfinite()
+
+        private fun parseColor(hex: String): Int? {
+            val raw = hex.removePrefix("#")
+            if (raw.length != 6 && raw.length != 8) return null
+            val value = raw.toLongOrNull(16) ?: return null
+            return if (raw.length == 8) value.toInt() else (0xff000000L or value).toInt()
+        }
+    }
+}