@pictor-sdk/video-android 0.1.0

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

@@ -0,0 +1,185 @@
+package dev.pictor.video
+
+import android.content.Context
+import android.media.MediaCodec
+import android.media.MediaExtractor
+import android.media.MediaFormat
+import android.media.MediaMuxer
+import android.net.Uri
+import java.io.File
+import java.nio.ByteBuffer
+import org.json.JSONObject
+
+/**
+ * One finished video file plus one finished audio file, into one MP4.
+ *
+ * **Encoded samples are copied, never decoded.** Transformer re-encodes audio
+ * when it combines inputs — measured: 180 shard samples became 175, of which
+ * only 120 were byte-identical, even with `setTransmuxAudio(true)` and a uniform
+ * channel layout. A second generation of lossy audio on every export is not
+ * something to accept because the API that caused it is the convenient one.
+ *
+ * `MediaMuxer` has no encoder. It writes the sample bytes it is given, so both
+ * payloads survive by construction rather than by a flag being honoured.
+ */
+internal object GateMux {
+
+    /** Copy every sample of `videoUri`'s video track and `audioUri`'s audio track. */
+    fun mux(
+        context: Context,
+        videoUri: String,
+        audioUri: String,
+        output: File,
+        /** Drop audio samples starting at or after this, or 0 to keep them all. */
+        audioLimitUs: Long = 0,
+        /** Encoder priming to remove, in output frames. Measured, never assumed. */
+        audioPrimingFrames: Int = 0,
+        /**
+         * Checked between samples, so a cancel does not wait out the copy.
+         *
+         * Measured: cancelling during the mux settled in 3316 ms against a 2 s
+         * target, because the only thing that could observe the request was the
+         * checkpoint *after* the whole copy had finished.
+         */
+        keepGoing: () -> Boolean = { true },
+    ): String {
+        val out = JSONObject()
+        val beatEpoch = ExportHeartbeat.currentEpoch()
+        val video = MediaExtractor()
+        val audio = MediaExtractor()
+        var muxer: MediaMuxer? = null
+        try {
+            /*
+              Beats through the silent stretch.
+
+              Measured: the longest legitimate heartbeat gap in a whole export
+              was 5.7 s, and every instance of it was here — between the last
+              encoded frame and the first muxed batch, while extractors open,
+              tracks are added and the muxer starts. Nothing was beating, so the
+              watchdog would have had to tolerate six seconds of real silence
+              and would then have been slower than the platform it exists to
+              beat. Instrumenting the gap is the fix; widening the threshold
+              would have been the symptom's.
+            */
+            ExportHeartbeat.beat("muxBatch", beatEpoch)
+            open(context, video, videoUri)
+            ExportHeartbeat.beat("muxBatch", beatEpoch)
+            open(context, audio, audioUri)
+            ExportHeartbeat.beat("muxBatch", beatEpoch)
+
+            val videoTrack = findTrack(video, "video/")
+            if (videoTrack < 0) return out.put("ok", false).put("error", "no video track").toString()
+            val audioTrack = findTrack(audio, "audio/")
+            if (audioTrack < 0) return out.put("ok", false).put("error", "no audio track").toString()
+
+            video.selectTrack(videoTrack)
+            audio.selectTrack(audioTrack)
+            val videoFormat = video.getTrackFormat(videoTrack)
+            val audioFormat = audio.getTrackFormat(audioTrack)
+
+            muxer = MediaMuxer(output.absolutePath, MediaMuxer.OutputFormat.MUXER_OUTPUT_MPEG_4)
+            /*
+              Carry the rotation across, or the video comes out sideways.
+
+              Transformer rotates a portrait composition into a landscape coded
+              frame when the encoder prefers one, and records the correction as
+              an orientation hint on *its* container. Re-muxing into a fresh
+              `MediaMuxer` starts from nothing, so the hint is lost and the file
+              is coded landscape with no instruction to turn it back.
+
+              Measured on a 1080x1920 project: the output was coded 1920x1080
+              with no rotation metadata and no side data, and its pixels matched
+              the source rotated 90 degrees counter-clockwise — mean absolute
+              difference 2.30, against 12.49 for the unrotated source. Nothing
+              downstream could have known: the frame is landscape and says so.
+
+              `KEY_ROTATION` is what the extractor reports for the intermediate;
+              it is absent when there is nothing to correct, and a hint of zero
+              is the same as no hint.
+            */
+            val rotation =
+                if (videoFormat.containsKey(MediaFormat.KEY_ROTATION)) {
+                    videoFormat.getInteger(MediaFormat.KEY_ROTATION)
+                } else {
+                    0
+                }
+            if (rotation != 0) muxer.setOrientationHint(rotation)
+            out.put("orientationHint", rotation)
+            val outVideo = muxer.addTrack(videoFormat)
+            val outAudio = muxer.addTrack(audioFormat)
+            muxer.start()
+            ExportHeartbeat.beat("muxBatch", beatEpoch)
+
+            /*
+              Priming removal lives in `PrimingTrim`, shared with preview
+              publication.
+
+              It used to live here, and only here, which is exactly why a
+              preview played about 43 ms behind its picture while an export of
+              the same project was aligned: two paths publishing audio and only
+              one of them correcting. See that file for why whole access units
+              are the only granularity available without decoding, and why the
+              residual is reported rather than absorbed.
+            */
+            val audioRate =
+                if (audioFormat.containsKey(MediaFormat.KEY_SAMPLE_RATE))
+                    audioFormat.getInteger(MediaFormat.KEY_SAMPLE_RATE)
+                else 48_000
+            val plan = PrimingTrim.plan(audioPrimingFrames, audioRate)
+            plan.into(out)
+
+            // Video carries no priming: an empty plan, through the same copy.
+            val videoSamples = PrimingTrim.copyTrack(
+                video, muxer, outVideo, 0, PrimingTrim.plan(0, 0), beatEpoch, keepGoing,
+            )
+            /*
+              The AAC tail is dropped rather than carried.
+
+              An encoder emits whole frames, so the last one runs past the end of
+              the timeline -- measured, 74 ms past a compiled 4.5 s, which makes
+              the container longer than the project and every duration a caller
+              reads slightly wrong. Samples starting at or after the compiled end
+              are entirely after the last visible frame, so dropping them removes
+              the overhang without removing anything audible.
+            */
+            // Skipped entirely if the video copy stopped: there is nothing to
+            // finish, and copying an audio track into a file nobody will keep is
+            // the wait a cancel exists to avoid.
+            val audioSamples =
+                if (videoSamples < 0) -1
+                else PrimingTrim.copyTrack(
+                    audio, muxer, outAudio, audioLimitUs, plan, beatEpoch, keepGoing,
+                )
+
+            if (videoSamples < 0 || audioSamples < 0) {
+                out.put("ok", false).put("cancelled", true).put("error", "cancelled during mux")
+            } else {
+                out.put("ok", true)
+                    .put("videoSamples", videoSamples)
+                    .put("audioSamples", audioSamples)
+                    .put("uri", output.absolutePath)
+            }
+        } catch (e: Exception) {
+            out.put("ok", false).put("error", e.javaClass.simpleName + ": " + e.message)
+        } finally {
+            runCatching { muxer?.stop() }
+            runCatching { muxer?.release() }
+            runCatching { video.release() }
+            runCatching { audio.release() }
+        }
+        return out.toString()
+    }
+
+    private fun open(context: Context, extractor: MediaExtractor, uri: String) {
+        if (uri.startsWith("/")) extractor.setDataSource(uri)
+        else extractor.setDataSource(context, Uri.parse(uri), null)
+    }
+
+    private fun findTrack(extractor: MediaExtractor, prefix: String): Int {
+        for (i in 0 until extractor.trackCount) {
+            val mime = extractor.getTrackFormat(i).getString(MediaFormat.KEY_MIME) ?: ""
+            if (mime.startsWith(prefix)) return i
+        }
+        return -1
+    }
+}

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

@@ -0,0 +1,333 @@
+package dev.pictor.video
+
+import android.content.Context
+import android.net.Uri
+import java.io.File
+import java.io.FileOutputStream
+import java.security.MessageDigest
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * Media the app owns, copied out of wherever it was picked from.
+ *
+ * ## Why a copy at all
+ *
+ * A picker hands back a reference, not a file. `content://` grants are scoped
+ * to the activity result that produced them and stop resolving once the process
+ * dies; `expo-document-picker`'s `copyToCacheDirectory` improves on that by
+ * writing into **cache**, which Android reclaims whenever it wants storage
+ * back. Both are fine until the moment someone reopens a project, and then the
+ * song is simply gone — with no error until an export fails.
+ *
+ * So an accepted source is copied into `filesDir`, which is app-owned and
+ * durable, and the project stores *that* URI. Nothing a picker returned is ever
+ * persisted.
+ *
+ * ## Content-addressed, deliberately
+ *
+ * The name is the SHA-256 of the bytes, never the user's filename. Three things
+ * fall out of that and all three are required:
+ *
+ * - the filename cannot leak what the file was called, or anything else about
+ *   the person who chose it;
+ * - adding the same song twice stores it once, so duplicated items share a
+ *   source instead of doubling the storage;
+ * - a partially written copy can never be mistaken for a complete one, because
+ *   its name is only assigned after the last byte is hashed.
+ *
+ * ## Written whole or not at all
+ *
+ * Bytes go to `<random>.part`, are flushed and fsynced, and only then renamed
+ * to `<sha256>.bin`. A kill mid-copy leaves a `.part` that no project can refer
+ * to and that [sweep] removes. There is no window in which a truncated file
+ * carries a name something else is pointing at.
+ *
+ * ## Deletion is never implicit
+ *
+ * Nothing here is reference-counted, and Undo removes no files. An Undo that
+ * deleted the source would make Redo restore an item pointing at nothing —
+ * the edit history would be intact and the media gone. Sources are removed only
+ * by an explicit [sweep] against the set of tokens a project still names.
+ */
+object ManagedSources {
+
+    private const val DIR = "pictor-sources"
+    private const val SUFFIX = ".bin"
+    private const val PART_SUFFIX = ".part"
+
+    /** Refuse absurd inputs rather than filling the user's storage. */
+    private const val MAX_BYTES = 512L * 1024L * 1024L
+
+    private fun dir(context: Context): File {
+        // `filesDir`, not `cacheDir`. The whole point is surviving the cleanup
+        // that cache exists to permit.
+        val d = File(context.filesDir, DIR)
+        if (!d.exists()) d.mkdirs()
+        return d
+    }
+
+    /**
+     * Copy [uri] into app-owned storage and return where it went.
+     *
+     * `{ok, uri, token, byteLength, sha256, created}` or `{ok:false, reason}`.
+     * `created` is false when the bytes were already stored — the caller must
+     * not release a source it did not bring into existence, because something
+     * else is using it.
+     */
+    fun ingest(context: Context, uri: String): JSONObject {
+        val out = JSONObject()
+        val parsed =
+            try {
+                Uri.parse(uri)
+            } catch (e: Exception) {
+                return out.put("ok", false).put("reason", "unparseable uri")
+            }
+
+        val directory = dir(context)
+        // The temporary name is random and carries nothing: it exists only long
+        // enough to be renamed to the digest of what it holds.
+        val part = File(directory, "ingest-${System.nanoTime()}-${(0..0xFFFFFF).random()}$PART_SUFFIX")
+
+        var total = 0L
+        val digest = MessageDigest.getInstance("SHA-256")
+
+        try {
+            val input =
+                context.contentResolver.openInputStream(parsed)
+                    ?: return out.put("ok", false).put("reason", "source could not be opened")
+
+            input.use { stream ->
+                FileOutputStream(part).use { output ->
+                    val buffer = ByteArray(256 * 1024)
+                    while (true) {
+                        val read = stream.read(buffer)
+                        if (read <= 0) break
+                        total += read
+                        if (total > MAX_BYTES) {
+                            throw IllegalStateException("source exceeds $MAX_BYTES bytes")
+                        }
+                        digest.update(buffer, 0, read)
+                        output.write(buffer, 0, read)
+                    }
+                    output.flush()
+                    // Durable before the rename, so the name never appears over
+                    // bytes the platform has not committed.
+                    output.fd.sync()
+                }
+            }
+
+            if (total <= 0L) {
+                part.delete()
+                return out.put("ok", false).put("reason", "source was empty")
+            }
+
+            val hex = digest.digest().joinToString("") { "%02x".format(it) }
+            val target = File(directory, hex + SUFFIX)
+
+            if (target.exists() && target.length() == total) {
+                /*
+                    Already stored. The copy just made is redundant, and the
+                    existing one is what everything else already points at, so
+                    the new bytes go and the old name is returned.
+                */
+                part.delete()
+                return out
+                    .put("ok", true)
+                    .put("uri", Uri.fromFile(target).toString())
+                    .put("token", hex)
+                    .put("byteLength", target.length())
+                    .put("sha256", hex)
+                    .put("created", false)
+            }
+
+            if (!part.renameTo(target)) {
+                part.delete()
+                return out.put("ok", false).put("reason", "could not commit the copy")
+            }
+
+            return out
+                .put("ok", true)
+                .put("uri", Uri.fromFile(target).toString())
+                .put("token", hex)
+                .put("byteLength", total)
+                .put("sha256", hex)
+                .put("created", true)
+        } catch (e: Exception) {
+            // Every failure path takes its partial with it. A `.part` left
+            // behind is storage nobody can account for.
+            try {
+                part.delete()
+            } catch (ignored: Exception) {
+                // Reporting the delete over the failure that caused it would
+                // bury the useful half of the message.
+            }
+            return out.put("ok", false).put("reason", e.javaClass.simpleName + (e.message?.let { ": $it" } ?: ""))
+        }
+    }
+
+    /** Drop one managed source. Returns whether a file went away. */
+    fun release(context: Context, token: String): Boolean {
+        if (!safeToken(token)) return false
+        val file = File(dir(context), token + SUFFIX)
+        return file.exists() && file.delete()
+    }
+
+    /**
+     * Remove every managed source whose token is not in [keep], and every
+     * `.part` left by a killed process.
+     *
+     * The keep list is the project's, so this is the only thing that deletes
+     * media and it is always given the full set of what is still referenced.
+     */
+    fun sweep(context: Context, keep: JSONArray): JSONObject {
+        val keepSet = HashSet<String>(keep.length())
+        for (i in 0 until keep.length()) keepSet.add(keep.optString(i))
+
+        var removed = 0
+        var kept = 0
+        var partials = 0
+        var skipped = 0
+        val files = dir(context).listFiles() ?: emptyArray()
+        for (file in files) {
+            val name = file.name
+            when {
+                name.endsWith(PART_SUFFIX) -> {
+                    // Nothing can be pointing at one: names are only assigned
+                    // after the last byte is written.
+                    if (file.delete()) partials += 1
+                }
+                name.endsWith(SUFFIX) && safeToken(name.removeSuffix(SUFFIX)) -> {
+                    /*
+                        Ours only if the stem is a real token.
+
+                        The suffix alone is not identification. A gate seeded
+                        `zzz-not-a-hash.bin` and this deleted it, because the
+                        rule was "ends in .bin and is not in the keep list" —
+                        which is every `.bin` anyone else ever puts here. The
+                        directory being ours is not a licence to delete files we
+                        did not write; a managed source is one whose name we
+                        could have produced, and nothing else.
+                    */
+                    val token = name.removeSuffix(SUFFIX)
+                    if (keepSet.contains(token)) kept += 1 else if (file.delete()) removed += 1
+                }
+                else -> {
+                    /*
+                        Not ours, and therefore not ours to delete.
+
+                        Counted rather than ignored so the accounting adds up to
+                        what the directory actually holds: a sweep that reported
+                        only what it touched could not be checked against a
+                        listing, and "I deleted nothing unexpected" is precisely
+                        the claim worth checking.
+                    */
+                    skipped += 1
+                }
+            }
+        }
+        return JSONObject()
+            .put("ok", true)
+            .put("removed", removed)
+            .put("kept", kept)
+            .put("partials", partials)
+            .put("skipped", skipped)
+    }
+
+    /** What is stored, for assertions. Tokens and sizes, never names. */
+    fun ledger(context: Context): JSONObject {
+        val items = JSONArray()
+        var bytes = 0L
+        val files = dir(context).listFiles() ?: emptyArray()
+        for (file in files) {
+            if (!file.name.endsWith(SUFFIX)) continue
+            bytes += file.length()
+            items.put(
+                JSONObject()
+                    .put("token", file.name.removeSuffix(SUFFIX))
+                    .put("byteLength", file.length()),
+            )
+        }
+        return JSONObject().put("ok", true).put("count", items.length()).put("bytes", bytes).put("items", items)
+    }
+
+    /**
+     * What is actually in the directory, name by name.
+     *
+     * Read-only accounting, so it stays available in release for the same
+     * reason the ledgers do: it is how a sweep is *proven* rather than
+     * asserted. [ledger] reports only well-formed sources, which is exactly the
+     * wrong instrument for checking what a sweep left behind — a partial or a
+     * stray file is invisible to it.
+     */
+    fun list(context: Context): JSONObject {
+        val items = JSONArray()
+        val files = dir(context).listFiles() ?: emptyArray()
+        for (file in files.sortedBy { it.name }) {
+            items.put(JSONObject().put("name", file.name).put("byteLength", file.length()))
+        }
+        return JSONObject().put("ok", true).put("count", items.length()).put("items", items)
+    }
+
+    /**
+     * Gate-only: sweep with a keep list exactly as given, unparsed.
+     *
+     * [sweep] takes a `JSONArray`, so the module builds one and an unparseable
+     * keep list never reaches it. That is the right shape for production and
+     * the wrong one for proving the claim that matters — that a keep list which
+     * cannot be read deletes nothing. This lets a gate hand over the raw text.
+     */
+    fun gateSweepRaw(context: Context, raw: String): JSONObject {
+        if (!Diagnostics.ENABLED) return JSONObject(Diagnostics.unavailable())
+        return try {
+            sweep(context, JSONArray(raw))
+        } catch (e: Exception) {
+            // The production path returns exactly this, and returns it *before*
+            // reaching `sweep`, so nothing is enumerated and nothing deleted.
+            JSONObject().put("ok", false).put("reason", "unparseable keep list")
+        }
+    }
+
+    /**
+     * Gate-only: put a file in the directory with an exact name.
+     *
+     * The sweep's enumeration and matching cannot be exercised through the
+     * normal API — ingestion only ever produces well-formed, referenced
+     * sources, so the cases that matter (an orphan, a stale `.part`, a file
+     * that is not ours at all) are unreachable without this.
+     *
+     * Mutating, so [Diagnostics.ENABLED] guards it and a release build refuses
+     * at the first line. The name is rejected if it contains a separator or a
+     * traversal segment: a seeding helper that could write outside its own
+     * directory would be a worse hole than the one it exists to test.
+     */
+    fun gateSeed(context: Context, name: String, bytes: Int): JSONObject {
+        if (!Diagnostics.ENABLED) return JSONObject(Diagnostics.unavailable())
+        if (name.isEmpty() || name.contains('/') || name.contains('\\') || name == "." || name == "..") {
+            return JSONObject().put("ok", false).put("reason", "unsafe name")
+        }
+        return try {
+            val file = File(dir(context), name)
+            // Deterministic content, so a later read can prove the bytes are the
+            // ones written rather than merely the right length.
+            val payload = ByteArray(bytes.coerceIn(0, 1 shl 20)) { (it % 251).toByte() }
+            FileOutputStream(file).use {
+                it.write(payload)
+                it.flush()
+                it.fd.sync()
+            }
+            JSONObject().put("ok", true).put("name", name).put("byteLength", file.length())
+        } catch (e: Exception) {
+            JSONObject().put("ok", false).put("reason", e.javaClass.simpleName)
+        }
+    }
+
+    /**
+     * A token is 64 lowercase hex characters and nothing else.
+     *
+     * Checked before it reaches a path so that a token from anywhere cannot
+     * name a file outside the directory.
+     */
+    private fun safeToken(token: String): Boolean =
+        token.length == 64 && token.all { it in '0'..'9' || it in 'a'..'f' }
+}