expo-pro-video-editor 0.1.0

package/android/src/main/java/expo/modules/provideoeditor/src/features/render/helpers/AudioPreRenderer.kt

@@ -0,0 +1,492 @@
+package expo.modules.provideoeditor.src.features.render.helpers
+
+import expo.modules.provideoeditor.src.core.constants.RENDER_TAG
+import android.content.Context
+import android.media.MediaExtractor
+import android.media.MediaFormat
+import androidx.media3.common.util.UnstableApi
+import expo.modules.provideoeditor.src.shared.logging.PluginLog as Log
+import expo.modules.provideoeditor.src.shared.media.PcmRangeDecoder
+import java.io.BufferedOutputStream
+import java.io.File
+import java.io.FileInputStream
+import java.io.FileOutputStream
+import java.io.OutputStream
+import java.io.RandomAccessFile
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+
+/**
+ * Pre-renders a custom audio track into a single, gap-less PCM WAV file
+ * that is ready to be inserted as ONE EditedMediaItem in the Media3
+ * composition.
+ *
+ * This is the core fix for audible clicks/gaps that occurred at every
+ * loop boundary and silence/audio transition with the previous
+ * implementation, where each loop iteration and silence segment was a
+ * separate `EditedMediaItem`. Each item boundary forced AAC encoder
+ * frame realignment, producing audible artifacts.
+ *
+ * The output file contains, in order:
+ *   1. Leading silence (matching `compositionStartUs`)
+ *   2. The trimmed source audio looped (or played once) to cover
+ *      `compositionDurationUs`, with sample-exact tail trimming
+ *   3. Trailing silence (matching `videoDurationUs - compositionStartUs -
+ *      compositionDurationUs`)
+ *
+ * The output sample rate, channel count and bit depth match the decoder
+ * output of the source file. Float PCM is converted to 16-bit signed PCM.
+ * Final resampling/mixing happens later inside Media3's encoder pipeline.
+ */
+@UnstableApi
+object AudioPreRenderer {
+
+    /**
+     * Result of a successful pre-render operation.
+     *
+     * @property outputFile The pre-rendered PCM WAV file (caller is
+     *   responsible for deleting it when no longer needed).
+     * @property sampleRate Sample rate of the WAV body (Hz).
+     * @property channelCount Number of channels in the WAV body.
+     */
+    data class Result(
+        val outputFile: File,
+        val sampleRate: Int,
+        val channelCount: Int
+    )
+
+    /**
+     * Pre-renders the audio track described by the parameters.
+     *
+     * @param context Android context (used for `cacheDir`).
+     * @param audioPath Absolute path to the source audio file.
+     * @param audioStartUs Trim start within the source (microseconds, >=0).
+     * @param audioEndUs Trim end within the source (microseconds, null
+     *   = use full source duration).
+     * @param loop If true, the trimmed window repeats to fill
+     *   `compositionDurationUs`. If false, plays once and any remaining
+     *   composition time is filled with silence.
+     * @param compositionStartUs Where on the composition timeline the
+     *   audio body should start. The output file contains this much
+     *   leading silence.
+     * @param compositionDurationUs How long the audio body should sound
+     *   on the composition timeline.
+     * @param videoDurationUs Total duration of the composition (used to
+     *   determine trailing silence).
+     * @return [Result] on success, null on failure (file missing, decode
+     *   error, invalid parameters).
+     */
+    fun render(
+        context: Context,
+        audioPath: String,
+        audioStartUs: Long,
+        audioEndUs: Long?,
+        loop: Boolean,
+        compositionStartUs: Long,
+        compositionDurationUs: Long,
+        videoDurationUs: Long
+    ): Result? {
+        val sourceFile = File(audioPath)
+        if (!sourceFile.exists()) {
+            Log.e(RENDER_TAG, "AudioPreRenderer: source file not found: $audioPath")
+            return null
+        }
+
+        if (compositionDurationUs <= 0L) {
+            Log.w(RENDER_TAG, "AudioPreRenderer: compositionDurationUs <= 0, skipping")
+            return null
+        }
+
+        // Step 1: Decode the trimmed source range into a scratch PCM file.
+        val decoded = try {
+            decodeRange(
+                context.cacheDir, audioPath, audioStartUs.coerceAtLeast(0L), audioEndUs
+            )
+        } catch (e: Exception) {
+            Log.e(RENDER_TAG, "AudioPreRenderer: decode failed: ${e.message}")
+            return null
+        } ?: return null
+
+        try {
+            return assemble(
+                context = context,
+                decoded = decoded,
+                loop = loop,
+                compositionStartUs = compositionStartUs,
+                compositionDurationUs = compositionDurationUs,
+                videoDurationUs = videoDurationUs
+            )
+        } finally {
+            decoded.pcmFile.delete()
+        }
+    }
+
+    /**
+     * Writes the WAV described by [decoded] and the composition timing, i.e.
+     * everything after the source has been decoded.
+     */
+    private fun assemble(
+        context: Context,
+        decoded: DecodedAudio,
+        loop: Boolean,
+        compositionStartUs: Long,
+        compositionDurationUs: Long,
+        videoDurationUs: Long
+    ): Result? {
+        if (decoded.byteLength <= 0L) {
+            Log.e(RENDER_TAG, "AudioPreRenderer: decoder produced no PCM data")
+            return null
+        }
+
+        val sampleRate = decoded.sampleRate
+        val channelCount = decoded.channelCount
+        val bytesPerFrame = channelCount * 2 // 16-bit PCM
+
+        // Step 2: Compute byte sizes for leading silence, audio body and
+        // trailing silence using the native sample rate.
+        val leadingSilenceBytes = alignToFrame(
+            usToBytes(compositionStartUs, sampleRate, bytesPerFrame),
+            bytesPerFrame
+        )
+        val bodyBytes = alignToFrame(
+            usToBytes(compositionDurationUs, sampleRate, bytesPerFrame),
+            bytesPerFrame
+        )
+        val totalCompositionBytes = leadingSilenceBytes + bodyBytes
+        val totalVideoBytes = alignToFrame(
+            usToBytes(videoDurationUs, sampleRate, bytesPerFrame),
+            bytesPerFrame
+        )
+        val trailingSilenceBytes = (totalVideoBytes - totalCompositionBytes)
+            .coerceAtLeast(0L)
+
+        // Step 3: Open the output WAV file and stream the data.
+        val outputFile = File(
+            context.cacheDir,
+            "prerender_audio_${System.currentTimeMillis()}_${System.nanoTime()}.wav"
+        )
+
+        try {
+            RandomAccessFile(outputFile, "rw").use { raf ->
+                writeWavHeader(raf, sampleRate, channelCount, dataSize = 0)
+
+                writeSilence(raf, leadingSilenceBytes)
+
+                val bodyBytesWritten = writeAudioBody(
+                    raf = raf,
+                    sourcePcm = decoded.pcmFile,
+                    targetBytes = bodyBytes,
+                    loop = loop,
+                    bytesPerFrame = bytesPerFrame
+                )
+
+                writeSilence(raf, trailingSilenceBytes)
+
+                // Update RIFF/data chunk sizes in the header.
+                val totalDataBytes =
+                    leadingSilenceBytes + bodyBytesWritten + trailingSilenceBytes
+                updateWavSizes(raf, totalDataBytes)
+            }
+        } catch (e: Exception) {
+            Log.e(RENDER_TAG, "AudioPreRenderer: write failed: ${e.message}")
+            outputFile.delete()
+            return null
+        }
+
+        Log.d(
+            RENDER_TAG,
+            "AudioPreRenderer: rendered ${outputFile.length()} bytes, " +
+                    "${sampleRate}Hz x ${channelCount}ch, " +
+                    "leadSilence=${compositionStartUs / 1000}ms, " +
+                    "body=${compositionDurationUs / 1000}ms, " +
+                    "loop=$loop"
+        )
+
+        return Result(outputFile, sampleRate, channelCount)
+    }
+
+    // ---------------------------------------------------------------------
+    // Internal: decoding
+    // ---------------------------------------------------------------------
+
+    /**
+     * The decoded source range, spooled to disk.
+     *
+     * @property pcmFile Scratch file holding the raw PCM; the caller deletes it.
+     * @property byteLength How many PCM bytes [pcmFile] holds.
+     */
+    private class DecodedAudio(
+        val pcmFile: File,
+        val byteLength: Long,
+        val sampleRate: Int,
+        val channelCount: Int
+    )
+
+    /**
+     * Decodes the audio range `[startUs, endUs)` from `path` into a scratch file
+     * of 16-bit signed little-endian PCM.
+     *
+     * The PCM goes to disk rather than into a byte array because it is the one
+     * allocation here that grows with the clip: a three-minute stereo track
+     * decodes to ~30 MB, and holding that (plus the copy every array growth
+     * makes) is enough to push an export over Android's managed-heap limit.
+     *
+     * Float PCM is converted to int16. Output sample rate / channel
+     * count match the decoder output.
+     */
+    private fun decodeRange(
+        cacheDir: File,
+        path: String,
+        startUs: Long,
+        endUs: Long?
+    ): DecodedAudio? {
+        val extractor = MediaExtractor()
+        val pcmFile = File(
+            cacheDir,
+            "prerender_pcm_${System.currentTimeMillis()}_${System.nanoTime()}.raw"
+        )
+        var pcmOutput: OutputStream? = null
+        var decodedFully = false
+
+        try {
+            extractor.setDataSource(path)
+
+            var audioTrackIndex = -1
+            var inputFormat: MediaFormat? = null
+            for (i in 0 until extractor.trackCount) {
+                val format = extractor.getTrackFormat(i)
+                val mime = format.getString(MediaFormat.KEY_MIME) ?: continue
+                if (mime.startsWith("audio/")) {
+                    audioTrackIndex = i
+                    inputFormat = format
+                    break
+                }
+            }
+
+            if (audioTrackIndex < 0 || inputFormat == null) {
+                Log.e(RENDER_TAG, "AudioPreRenderer: no audio track in $path")
+                return null
+            }
+
+            val sink = BufferedOutputStream(FileOutputStream(pcmFile))
+            pcmOutput = sink
+
+            val effectiveEndUs = endUs ?: Long.MAX_VALUE
+            var pcmByteLength = 0L
+            var sampleRate = 0
+            var channelCount = 0
+
+            // The extractor seeks to the sync frame at or before `startUs`, so
+            // the first buffer usually begins early. Dropping that lead-in — and
+            // the tail past `endUs` — is what makes the trim sample-exact, which
+            // is what keeps a loop boundary gap-less.
+            var hasCrossedStart = false
+
+            PcmRangeDecoder.decode(
+                extractor = extractor,
+                audioTrackIndex = audioTrackIndex,
+                inputFormat = inputFormat,
+                startUs = startUs,
+                endUs = effectiveEndUs,
+                stopAfterEndUs = true,
+                onFormat = { format ->
+                    sampleRate = format.sampleRate
+                    channelCount = format.channelCount
+                },
+                onPcm = { pcm, bufferStartUs, format ->
+                    val bytesPerFrame = (format.channelCount * 2).coerceAtLeast(1)
+                    val rate = format.sampleRate
+
+                    val skipBytes = if (!hasCrossedStart && rate > 0) {
+                        val deltaUs = (startUs - bufferStartUs).coerceAtLeast(0L)
+                        ((deltaUs * rate / 1_000_000L) * bytesPerFrame)
+                            .coerceAtMost(pcm.size.toLong()).toInt()
+                    } else 0
+
+                    val dropBytes = if (effectiveEndUs != Long.MAX_VALUE && rate > 0) {
+                        val frameDurationUs = 1_000_000.0 / rate
+                        val bufferEndUs = bufferStartUs +
+                                ((pcm.size / bytesPerFrame) * frameDurationUs).toLong()
+                        if (bufferEndUs > effectiveEndUs) {
+                            val overUs = bufferEndUs - effectiveEndUs
+                            ((overUs * rate / 1_000_000L) * bytesPerFrame)
+                                .coerceAtMost((pcm.size - skipBytes).toLong()).toInt()
+                        } else 0
+                    } else 0
+
+                    val writeLen = pcm.size - skipBytes - dropBytes
+                    if (writeLen > 0) {
+                        sink.write(pcm, skipBytes, writeLen)
+                        pcmByteLength += writeLen
+                        hasCrossedStart = true
+                    }
+                },
+            )
+
+            sink.flush()
+
+            if (sampleRate <= 0 || channelCount <= 0) {
+                Log.e(RENDER_TAG, "AudioPreRenderer: decoder reported no usable PCM format")
+                return null
+            }
+
+            decodedFully = true
+            return DecodedAudio(
+                pcmFile = pcmFile,
+                byteLength = pcmByteLength,
+                sampleRate = sampleRate,
+                channelCount = channelCount
+            )
+        } finally {
+            try {
+                pcmOutput?.close()
+            } catch (_: Exception) {
+            }
+            try {
+                extractor.release()
+            } catch (_: Exception) {
+            }
+            // A range that never made it to a DecodedAudio owns no scratch file.
+            if (!decodedFully) pcmFile.delete()
+        }
+    }
+
+    // ---------------------------------------------------------------------
+    // Internal: WAV writing
+    // ---------------------------------------------------------------------
+
+    private fun writeWavHeader(
+        raf: RandomAccessFile,
+        sampleRate: Int,
+        channelCount: Int,
+        dataSize: Int
+    ) {
+        val bitsPerSample = 16
+        val byteRate = sampleRate * channelCount * bitsPerSample / 8
+        val blockAlign = (channelCount * bitsPerSample / 8).toShort()
+
+        val header = ByteBuffer.allocate(44).order(ByteOrder.LITTLE_ENDIAN)
+        header.put("RIFF".toByteArray(Charsets.US_ASCII))
+        header.putInt(36 + dataSize) // RIFF chunk size
+        header.put("WAVE".toByteArray(Charsets.US_ASCII))
+        header.put("fmt ".toByteArray(Charsets.US_ASCII))
+        header.putInt(16)             // fmt subchunk size (PCM)
+        header.putShort(1)            // PCM format
+        header.putShort(channelCount.toShort())
+        header.putInt(sampleRate)
+        header.putInt(byteRate)
+        header.putShort(blockAlign)
+        header.putShort(bitsPerSample.toShort())
+        header.put("data".toByteArray(Charsets.US_ASCII))
+        header.putInt(dataSize)
+
+        raf.seek(0)
+        raf.write(header.array())
+    }
+
+    /**
+     * Writes the measured [dataSize] into the RIFF and data chunk headers.
+     *
+     * RIFF sizes are *unsigned* 32-bit, so they are clamped at `0xFFFFFFFF`
+     * (~4 GB, the format's ceiling) rather than at [Int.MAX_VALUE] — clamping at
+     * half the range would still let `36 + dataSize` wrap negative and write a
+     * size no reader accepts, which is the corrupt-file case the measured byte
+     * count exists to prevent.
+     */
+    internal fun updateWavSizes(raf: RandomAccessFile, dataSize: Long) {
+        val safeDataSize = dataSize.coerceIn(0L, MAX_RIFF_SIZE)
+        val riffSize = (36L + safeDataSize).coerceAtMost(MAX_RIFF_SIZE)
+        // RIFF chunk size at offset 4 (little-endian).
+        raf.seek(4)
+        raf.write(uInt32ToLittleEndian(riffSize))
+        // data chunk size at offset 40 (little-endian).
+        raf.seek(40)
+        raf.write(uInt32ToLittleEndian(safeDataSize))
+        // Move back to end so subsequent writes append correctly.
+        raf.seek(raf.length())
+    }
+
+    private fun writeSilence(raf: RandomAccessFile, byteCount: Long) {
+        if (byteCount <= 0L) return
+        val chunk = ByteArray(8192)
+        var remaining = byteCount
+        while (remaining > 0) {
+            val toWrite = minOf(remaining, chunk.size.toLong()).toInt()
+            raf.write(chunk, 0, toWrite)
+            remaining -= toWrite
+        }
+    }
+
+    /**
+     * Fills [targetBytes] of audio body into [raf]: [sourcePcm] copied in,
+     * replayed from the start as often as needed when [loop] is set, and
+     * whatever the source cannot cover left silent.
+     *
+     * That silence is the documented behavior for a non-looping track shorter
+     * than its slot (see [render]) — and dropping the gap instead would end the
+     * WAV early, finishing the export short of the video. Covering it here
+     * rather than at the call site keeps the two from drifting apart.
+     *
+     * Returns how many bytes were written, which is [targetBytes] rounded down
+     * to a frame boundary. The count is what the WAV header declares, and a
+     * header that disagrees with the body by even one frame makes the file
+     * unreadable.
+     */
+    internal fun writeAudioBody(
+        raf: RandomAccessFile,
+        sourcePcm: File,
+        targetBytes: Long,
+        loop: Boolean,
+        bytesPerFrame: Int
+    ): Long {
+        if (targetBytes <= 0L) return 0L
+
+        // Align targetBytes to frame boundary (defensive).
+        val alignedTarget = (targetBytes / bytesPerFrame) * bytesPerFrame
+        val buffer = ByteArray(1 shl 16)
+        var written = 0L
+
+        while (written < alignedTarget) {
+            val passStart = written
+            FileInputStream(sourcePcm).use { source ->
+                while (written < alignedTarget) {
+                    val wanted = minOf(buffer.size.toLong(), alignedTarget - written).toInt()
+                    val read = source.read(buffer, 0, wanted)
+                    if (read <= 0) break
+                    raf.write(buffer, 0, read)
+                    written += read
+                }
+            }
+            // An empty (or vanished) source would otherwise spin here forever.
+            if (written == passStart || !loop) break
+        }
+
+        writeSilence(raf, alignedTarget - written)
+        return alignedTarget
+    }
+
+    // ---------------------------------------------------------------------
+    // Internal: math helpers
+    // ---------------------------------------------------------------------
+
+    private fun usToBytes(durationUs: Long, sampleRate: Int, bytesPerFrame: Int): Long {
+        if (durationUs <= 0L) return 0L
+        // (durationUs * sampleRate / 1_000_000) frames * bytesPerFrame
+        // Use Math.multiplyExact-style guard via Long multiplication.
+        val frames = (durationUs.toDouble() * sampleRate / 1_000_000.0).toLong()
+        return frames * bytesPerFrame
+    }
+
+    private fun alignToFrame(byteCount: Long, bytesPerFrame: Int): Long {
+        if (bytesPerFrame <= 1) return byteCount
+        return (byteCount / bytesPerFrame) * bytesPerFrame
+    }
+
+    /** [value] as the four little-endian bytes of an unsigned 32-bit field. */
+    private fun uInt32ToLittleEndian(value: Long): ByteArray {
+        return ByteArray(4) { i -> ((value ushr (8 * i)) and 0xFF).toByte() }
+    }
+
+    /** The largest value a RIFF/data chunk size field can hold. */
+    private const val MAX_RIFF_SIZE = 0xFFFFFFFFL
+}

package/android/src/main/java/expo/modules/provideoeditor/src/features/render/helpers/AudioSequenceBuilder.kt

@@ -0,0 +1,144 @@
+package expo.modules.provideoeditor.src.features.render.helpers
+
+import expo.modules.provideoeditor.src.core.constants.RENDER_TAG
+import android.content.Context
+import android.net.Uri
+import androidx.media3.common.MediaItem
+import androidx.media3.common.audio.AudioProcessor
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.transformer.EditedMediaItem
+import androidx.media3.transformer.EditedMediaItemSequence
+import androidx.media3.transformer.Effects
+import expo.modules.provideoeditor.src.shared.logging.PluginLog as Log
+import java.io.File
+
+/**
+ * Builder class for creating custom audio sequences in video compositions.
+ *
+ * Pre-renders the entire audio track (leading silence + looped/clipped
+ * source + trailing silence) into a single PCM WAV file via
+ * [AudioPreRenderer], then exposes it as ONE [EditedMediaItem] inside an
+ * [EditedMediaItemSequence].
+ *
+ * Using a single item per audio track removes the AAC frame realignment
+ * artifacts (clicks/gaps) that previously occurred at every loop boundary
+ * and silence/audio transition when the sequence contained multiple
+ * items.
+ *
+ * The generated WAV file path is returned from [build] alongside the
+ * sequence so the caller can register it for cleanup once the
+ * Transformer export finishes.
+ */
+@UnstableApi
+class AudioSequenceBuilder(
+    private val context: Context,
+    private val audioPath: String,
+    private val videoDurationUs: Long
+) {
+    /**
+     * The result of a successful [build]: the audio sequence ready to be
+     * added to the composition, plus the temporary WAV file that must be
+     * deleted by the caller after rendering completes.
+     */
+    data class BuildResult(
+        val sequence: EditedMediaItemSequence,
+        val temporaryFile: File
+    )
+
+    private var loopAudio: Boolean = true
+    private var startTimeUs: Long = 0
+    private var audioEndTimeUs: Long? = null
+    private var compositionStartTimeUs: Long? = null
+    private var compositionEndTimeUs: Long? = null
+
+    /**
+     * Sets whether the audio should loop to fill the play range.
+     */
+    fun setLoop(loop: Boolean): AudioSequenceBuilder {
+        this.loopAudio = loop
+        return this
+    }
+
+    /**
+     * Sets the start time offset within the source audio file.
+     */
+    fun setStartTime(startTimeUs: Long?): AudioSequenceBuilder {
+        this.startTimeUs = (startTimeUs ?: 0L).coerceAtLeast(0L)
+        return this
+    }
+
+    /**
+     * Sets the end time within the source audio file.
+     */
+    fun setAudioEndTime(endTimeUs: Long?): AudioSequenceBuilder {
+        this.audioEndTimeUs = endTimeUs
+        return this
+    }
+
+    /**
+     * Sets when this audio track should start playing on the composition
+     * timeline.
+     */
+    fun setCompositionStartTime(startTimeUs: Long?): AudioSequenceBuilder {
+        this.compositionStartTimeUs = startTimeUs
+        return this
+    }
+
+    /**
+     * Sets when this audio track should stop playing on the composition
+     * timeline.
+     */
+    fun setCompositionEndTime(endTimeUs: Long?): AudioSequenceBuilder {
+        this.compositionEndTimeUs = endTimeUs
+        return this
+    }
+
+    /**
+     * Builds the audio sequence by pre-rendering the source into a single
+     * gap-less PCM WAV file.
+     *
+     * @return [BuildResult] with the sequence and the temporary file to
+     *   delete after export, or null if the audio could not be prepared.
+     */
+    fun build(): BuildResult? {
+        val sourceFile = File(audioPath)
+        if (!sourceFile.exists()) {
+            Log.e(RENDER_TAG, "Custom audio file not found: $audioPath")
+            return null
+        }
+
+        val compStart = (compositionStartTimeUs ?: 0L).coerceAtLeast(0L)
+        val compEnd = (compositionEndTimeUs ?: videoDurationUs)
+            .coerceAtMost(videoDurationUs)
+        val playDurationUs = (compEnd - compStart).coerceAtLeast(0L)
+
+        if (playDurationUs <= 0L) {
+            Log.w(RENDER_TAG, "Custom audio play duration <= 0, skipping track")
+            return null
+        }
+
+        val preRender = AudioPreRenderer.render(
+            context = context,
+            audioPath = audioPath,
+            audioStartUs = startTimeUs,
+            audioEndUs = audioEndTimeUs,
+            loop = loopAudio,
+            compositionStartUs = compStart,
+            compositionDurationUs = playDurationUs,
+            videoDurationUs = videoDurationUs
+        ) ?: return null
+
+        val mediaItem = MediaItem.Builder()
+            .setUri(Uri.fromFile(preRender.outputFile))
+            .build()
+
+        val editedItem = EditedMediaItem.Builder(mediaItem)
+            .setRemoveVideo(true)
+            .setEffects(Effects(emptyList<AudioProcessor>(), emptyList()))
+            .build()
+
+        val sequence = EditedMediaItemSequence.Builder(editedItem).build()
+
+        return BuildResult(sequence, preRender.outputFile)
+    }
+}

package/android/src/main/java/expo/modules/provideoeditor/src/features/render/helpers/BitrateCapPolicy.kt

@@ -0,0 +1,45 @@
+package expo.modules.provideoeditor.src.features.render.helpers
+
+/**
+ * Decides whether a requested bitrate cap forces the video track through the
+ * encoder instead of Media3's lossless transmux fast path.
+ *
+ * The requested bitrate is a guaranteed *maximum* for the rendered output.
+ * Transmuxing copies the source samples verbatim, so it is only allowed when
+ * every source video track already fits the cap (within [TOLERANCE], so
+ * compliant sources keep the near-instant lossless path).
+ *
+ * Kept free of Android framework dependencies so it is unit-testable; the
+ * actual source bitrates are probed by `MediaInfoExtractor.getVideoBitrate`.
+ */
+object BitrateCapPolicy {
+
+    /**
+     * Sources up to cap × tolerance keep the lossless fast path. The headroom
+     * absorbs probe inaccuracy (the container-level fallback includes audio
+     * and muxer overhead) and encoder rate-control drift around the target.
+     */
+    const val TOLERANCE = 1.2
+
+    /**
+     * Returns true when the video track must be re-encoded to honor the cap.
+     *
+     * @param requestedBitrate Requested maximum in bits per second, or null
+     *  when no cap was requested (never forces encoding).
+     * @param sourceBitrates Probed bitrate of each source video, in bits per
+     *  second. A null entry means the bitrate could not be determined — the
+     *  cap cannot be proven, so encoding is forced.
+     * @param tolerance Multiplier on the cap below which a source counts as
+     *  compliant.
+     */
+    fun shouldForceEncode(
+        requestedBitrate: Int?,
+        sourceBitrates: List<Long?>,
+        tolerance: Double = TOLERANCE,
+    ): Boolean {
+        if (requestedBitrate == null) return false
+        if (sourceBitrates.isEmpty()) return false
+        val budget = requestedBitrate.toDouble() * tolerance
+        return sourceBitrates.any { it == null || it.toDouble() > budget }
+    }
+}