expo-pro-video-editor 0.1.0

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

@@ -0,0 +1,290 @@
+package expo.modules.provideoeditor.src.features.render.helpers
+
+import android.graphics.Bitmap
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.effect.BitmapOverlay
+import androidx.media3.effect.StaticOverlaySettings
+import expo.modules.provideoeditor.src.features.render.models.LayerAnimationConfig
+import kotlin.math.max
+import kotlin.math.min
+import kotlin.math.pow
+import kotlin.math.sin
+
+/**
+ * Applies an easing function to a linear progress value (0..1).
+ */
+internal fun applyEasing(t: Double, curve: String): Double {
+    return when (curve) {
+        "easeIn" -> t * t
+        "easeOut" -> t * (2 - t)
+        "easeInOut" -> if (t < 0.5) 2 * t * t else -1 + (4 - 2 * t) * t
+        "easeInCubic" -> t * t * t
+        "easeOutCubic" -> {
+            val p = 1 - t
+            1 - p * p * p
+        }
+        "easeInOutCubic" -> if (t < 0.5) 4 * t * t * t else 1 - (-2 * t + 2).pow(3) / 2
+        "bounceIn" -> 1 - applyEasing(1 - t, "bounceOut")
+        "bounceOut" -> when {
+            t < 1 / 2.75 -> 7.5625 * t * t
+            t < 2 / 2.75 -> {
+                val t2 = t - 1.5 / 2.75
+                7.5625 * t2 * t2 + 0.75
+            }
+            t < 2.5 / 2.75 -> {
+                val t2 = t - 2.25 / 2.75
+                7.5625 * t2 * t2 + 0.9375
+            }
+            else -> {
+                val t2 = t - 2.625 / 2.75
+                7.5625 * t2 * t2 + 0.984375
+            }
+        }
+        "bounceInOut" -> if (t < 0.5) {
+            (1 - applyEasing(1 - 2 * t, "bounceOut")) / 2
+        } else {
+            (1 + applyEasing(2 * t - 1, "bounceOut")) / 2
+        }
+        "elasticIn" -> 1 - applyEasing(1 - t, "elasticOut")
+        "elasticOut" -> {
+            if (t == 0.0 || t == 1.0) t
+            else 2.0.pow(-10 * t) * sin((t - 0.075) * (2 * Math.PI) / 0.3) + 1
+        }
+        "elasticInOut" -> if (t < 0.5) {
+            (1 - applyEasing(1 - 2 * t, "elasticOut")) / 2
+        } else {
+            (1 + applyEasing(2 * t - 1, "elasticOut")) / 2
+        }
+        else -> t // "linear"
+    }
+}
+
+/**
+ * Normalized slide offset (OpenGL coordinates, [-1, 1], +x right / +y up).
+ */
+internal data class SlideOffset(val x: Float, val y: Float)
+
+/**
+ * Computes the slide translation that moves a layer fully out of the canvas
+ * in [direction], edge-aware rather than layer-size-relative.
+ *
+ * At [invP] == 1 the layer's trailing edge sits exactly on the canvas edge in
+ * the slide direction (so the layer is just completely outside); at [invP] == 0
+ * the offset is zero (layer at rest). The canvas spans [-1, 1] on both axes.
+ *
+ * @param baseNormX Layer center X in [-1, 1] (+x right).
+ * @param baseNormY Layer center Y in [-1, 1] (+y up).
+ * @param halfNormW Layer half-width in [-1, 1] units (imageWidth / videoWidth).
+ * @param halfNormH Layer half-height in [-1, 1] units (imageHeight / videoHeight).
+ */
+internal fun slideOffset(
+    direction: String?,
+    invP: Float,
+    baseNormX: Float,
+    baseNormY: Float,
+    halfNormW: Float,
+    halfNormH: Float,
+): SlideOffset = when (direction) {
+    "left" -> SlideOffset(invP * (-1f - baseNormX - halfNormW), 0f) // right edge → -1
+    "right" -> SlideOffset(invP * (1f - baseNormX + halfNormW), 0f) // left edge → +1
+    "top" -> SlideOffset(0f, invP * (1f - baseNormY + halfNormH)) // bottom edge → +1 (Y up)
+    "bottom" -> SlideOffset(0f, invP * (-1f - baseNormY - halfNormH)) // top edge → -1 (Y up)
+    else -> SlideOffset(0f, 0f)
+}
+
+/**
+ * A background-frame anchor paired with an overlay-frame anchor, both in the
+ * Media3 [-1, 1] range.
+ */
+internal data class OverlayAnchors(
+    val backgroundAnchor: Float,
+    val overlayAnchor: Float,
+)
+
+/**
+ * Splits a desired layer-center position (in [-1, 1] NDC, possibly beyond the
+ * canvas to place the layer off-screen) into the two anchors Media3 accepts.
+ *
+ * Media3 clamps both [StaticOverlaySettings.Builder.setBackgroundFrameAnchor]
+ * and [StaticOverlaySettings.Builder.setOverlayFrameAnchor] to [-1, 1], so a
+ * single background anchor cannot move a layer fully off-screen. The background
+ * anchor covers the on-canvas part; the overlay anchor supplies the remaining
+ * off-canvas shift — its ±1 range maps to ±[halfNorm] of background travel,
+ * which is exactly one layer half-size, enough for an edge-flush slide-out.
+ *
+ * @param targetCenter Desired layer center on this axis (may exceed [-1, 1]).
+ * @param halfNorm Layer half-size on this axis in [-1, 1] units.
+ */
+internal fun resolveAnchor(targetCenter: Float, halfNorm: Float): OverlayAnchors {
+    val background = targetCenter.coerceIn(-1f, 1f)
+    val overflow = targetCenter - background
+    // overlayCenter = background − overlayAnchor * halfNorm  ⇒  solve for anchor.
+    val overlay = if (halfNorm > 0f) (-overflow / halfNorm).coerceIn(-1f, 1f) else 0f
+    return OverlayAnchors(background, overlay)
+}
+
+/**
+ * Custom BitmapOverlay that computes per-frame overlay settings for animations
+ * and, for animated images (GIF), returns the correct frame for the current
+ * presentation time.
+ *
+ * Uses [getOverlaySettings] to dynamically compute alpha, position offsets,
+ * and scale based on the current presentation time and animation configs.
+ *
+ * [frames] holds one bitmap for a static image, or several for an animated
+ * one; [frameDurationsUs] gives each frame's on-screen duration. All frames
+ * must share the same dimensions ([imageWidth] x [imageHeight]).
+ */
+@UnstableApi
+internal class AnimatedBitmapOverlay(
+    private val frames: List<Bitmap>,
+    private val frameDurationsUs: List<Long>,
+    private val baseNormX: Float,
+    private val baseNormY: Float,
+    private val imageWidth: Int,
+    private val imageHeight: Int,
+    private val videoWidth: Int,
+    private val videoHeight: Int,
+    private val layerStartUs: Long,
+    private val layerEndUs: Long,
+    private val loop: Boolean,
+    private val animations: List<LayerAnimationConfig>
+) : BitmapOverlay() {
+
+    /** Convenience constructor for a single static frame. */
+    constructor(
+        bitmap: Bitmap,
+        baseNormX: Float,
+        baseNormY: Float,
+        imageWidth: Int,
+        imageHeight: Int,
+        videoWidth: Int,
+        videoHeight: Int,
+        layerStartUs: Long,
+        layerEndUs: Long,
+        animations: List<LayerAnimationConfig>
+    ) : this(
+        frames = listOf(bitmap),
+        frameDurationsUs = listOf(0L),
+        baseNormX = baseNormX,
+        baseNormY = baseNormY,
+        imageWidth = imageWidth,
+        imageHeight = imageHeight,
+        videoWidth = videoWidth,
+        videoHeight = videoHeight,
+        layerStartUs = layerStartUs,
+        layerEndUs = layerEndUs,
+        loop = false,
+        animations = animations
+    )
+
+    // Cumulative end time of each frame within one playthrough, plus the total.
+    private val frameEndsUs: LongArray = LongArray(frames.size).also { ends ->
+        var acc = 0L
+        for (i in frames.indices) {
+            acc += frameDurationsUs[i]
+            ends[i] = acc
+        }
+    }
+    private val totalDurationUs: Long = frameEndsUs.lastOrNull() ?: 0L
+
+    override fun getBitmap(presentationTimeUs: Long): Bitmap {
+        if (frames.size == 1 || totalDurationUs <= 0L) return frames[0]
+
+        val effectiveStartUs = if (layerStartUs == -1L) 0L else layerStartUs
+        var t = presentationTimeUs - effectiveStartUs
+        if (t < 0L) t = 0L
+        t = if (loop) t % totalDurationUs else t.coerceAtMost(totalDurationUs - 1)
+
+        // frameEndsUs is ascending, so the first end strictly greater than t
+        // identifies the active frame.
+        for (i in frames.indices) {
+            if (t < frameEndsUs[i]) return frames[i]
+        }
+        return frames.last()
+    }
+
+    override fun getOverlaySettings(presentationTimeUs: Long): StaticOverlaySettings {
+        var alpha = 1.0f
+        var offsetX = 0f
+        var offsetY = 0f
+        var scaleVal = 1.0f
+
+        // Layer half-size in [-1, 1] units (canvas spans [-1, 1]).
+        val halfNormW = imageWidth.toFloat() / videoWidth
+        val halfNormH = imageHeight.toFloat() / videoHeight
+
+        val effectiveStartUs = if (layerStartUs == -1L) 0L else layerStartUs
+        val effectiveEndUs = if (layerEndUs == -1L) Long.MAX_VALUE else layerEndUs
+
+        for (anim in animations) {
+            val durationUs = anim.durationUs
+            if (durationUs <= 0) continue
+
+            // Determine progress for animateIn and/or animateOut
+            var inProgress: Double? = null
+            var outProgress: Double? = null
+
+            if (anim.phase == "animateIn" || anim.phase == "animateInOut") {
+                val elapsed = presentationTimeUs - effectiveStartUs
+                if (elapsed < durationUs) {
+                    inProgress = applyEasing(
+                        max(0.0, min(1.0, elapsed.toDouble() / durationUs)),
+                        anim.curve
+                    )
+                }
+            }
+
+            if (anim.phase == "animateOut" || anim.phase == "animateInOut") {
+                val remaining = effectiveEndUs - presentationTimeUs
+                if (remaining < durationUs) {
+                    outProgress = applyEasing(
+                        max(0.0, min(1.0, remaining.toDouble() / durationUs)),
+                        anim.curve
+                    )
+                }
+            }
+
+            // Use the minimum progress (most visible animation effect)
+            val progress: Double? = when {
+                inProgress != null && outProgress != null -> min(inProgress, outProgress)
+                else -> inProgress ?: outProgress
+            }
+
+            if (progress == null) continue
+
+            when (anim.type) {
+                "fade" -> alpha *= progress.toFloat()
+                "slide" -> {
+                    val invP = (1.0 - progress).toFloat()
+                    val off = slideOffset(
+                        anim.slideDirection, invP,
+                        baseNormX, baseNormY, halfNormW, halfNormH
+                    )
+                    offsetX += off.x
+                    offsetY += off.y
+                }
+                "scale" -> {
+                    val scaleFrom = anim.scaleFrom?.toFloat() ?: 0f
+                    scaleVal *= scaleFrom + (1f - scaleFrom) * progress.toFloat()
+                }
+            }
+        }
+
+        // Clamp values — elastic/bounce curves can overshoot [0,1]
+        val clampedAlpha = alpha.coerceIn(0f, 1f)
+        val clampedScale = scaleVal.coerceAtLeast(0f)
+
+        // Media3 clamps each anchor to [-1, 1], so a fully off-screen slide is
+        // split across the background and overlay anchors (see resolveAnchor).
+        val anchorX = resolveAnchor(baseNormX + offsetX, halfNormW)
+        val anchorY = resolveAnchor(baseNormY + offsetY, halfNormH)
+
+        return StaticOverlaySettings.Builder()
+            .setAlphaScale(clampedAlpha)
+            .setBackgroundFrameAnchor(anchorX.backgroundAnchor, anchorY.backgroundAnchor)
+            .setOverlayFrameAnchor(anchorX.overlayAnchor, anchorY.overlayAnchor)
+            .setScale(clampedScale, clampedScale)
+            .build()
+    }
+}

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

@@ -0,0 +1,110 @@
+package expo.modules.provideoeditor.src.features.render.helpers
+
+import android.media.MediaCodecInfo
+import android.media.MediaCodecList
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.transformer.DefaultEncoderFactory
+import androidx.media3.transformer.VideoEncoderSettings
+import expo.modules.provideoeditor.src.core.constants.RENDER_TAG
+import expo.modules.provideoeditor.src.shared.logging.PluginLog as Log
+
+/**
+ * An encoder-safe bitrate configuration: a bitrate clamped to the codec's
+ * supported range plus a bitrate mode the codec actually accepts.
+ *
+ * @property bitrate Bitrate in bits per second.
+ * @property bitrateMode One of [MediaCodecInfo.EncoderCapabilities] BITRATE_MODE_*.
+ */
+data class BitrateChoice(val bitrate: Int, val bitrateMode: Int)
+
+/**
+ * Resolves an encoder-safe bitrate configuration for the given MIME type.
+ *
+ * - Clamps the requested bitrate into the codec's supported range
+ * - Uses CBR (Constant Bitrate) for predictable file size when supported and
+ *   the bitrate is not in the upper portion of the range
+ * - Falls back to VBR (Variable Bitrate) when CBR is unsupported or the
+ *   bitrate is high, since high-bitrate CBR is frequently rejected by
+ *   hardware encoders
+ *
+ * @param mimeType Video MIME type (e.g., "video/avc" for H.264)
+ * @param bitrate Target bitrate in bits per second, or null to leave the
+ *  encoder on its default bitrate.
+ * @return The resolved [BitrateChoice], or null when no bitrate was requested or
+ *  no encoder could be found for [mimeType].
+ */
+@UnstableApi
+fun resolveBitrateSettings(mimeType: String?, bitrate: Int?): BitrateChoice? {
+    if (bitrate == null) return null
+    Log.d(RENDER_TAG, "Configuring bitrate: ${bitrate / 1000} kbps")
+
+    val codecInfo = MediaCodecList(MediaCodecList.ALL_CODECS)
+        .codecInfos
+        .firstOrNull { it.isEncoder && it.supportedTypes.contains(mimeType) }
+
+    if (codecInfo == null) {
+        Log.e(RENDER_TAG, "No encoder found for $mimeType")
+        return null
+    }
+
+    val capabilities = codecInfo.getCapabilitiesForType(mimeType)
+    val bitrateRange = capabilities.videoCapabilities.bitrateRange
+    val supportsCBR = capabilities.encoderCapabilities
+        .isBitrateModeSupported(MediaCodecInfo.EncoderCapabilities.BITRATE_MODE_CBR)
+
+    // Clamp the requested bitrate into the supported range instead of bailing
+    // out. Bailing left the encoder on its (often very high) default bitrate,
+    // which is one of the configurations Qualcomm encoders reject outright.
+    val safeBitrate = bitrate.coerceIn(bitrateRange.lower, bitrateRange.upper)
+    if (safeBitrate != bitrate) {
+        Log.w(
+            RENDER_TAG,
+            "Bitrate ${bitrate / 1000} kbps outside supported range " +
+                    "${bitrateRange.lower / 1000}-${bitrateRange.upper / 1000} kbps, " +
+                    "clamping to ${safeBitrate / 1000} kbps"
+        )
+    }
+
+    // CBR at a high bitrate (relative to the codec's max) is the combination
+    // most likely to be rejected by hardware encoders (e.g. Qualcomm AVC at
+    // 1080p with High profile). When the requested bitrate sits in the upper
+    // portion of the supported range, prefer VBR which is far more forgiving.
+    val highBitrateThreshold = (bitrateRange.upper * 0.8).toInt()
+    val useCBR = supportsCBR && safeBitrate <= highBitrateThreshold
+
+    val bitrateMode = if (useCBR) {
+        Log.d(RENDER_TAG, "Using CBR (Constant Bitrate) mode")
+        MediaCodecInfo.EncoderCapabilities.BITRATE_MODE_CBR
+    } else {
+        val reason = if (!supportsCBR) "CBR not supported" else "high bitrate, avoiding CBR"
+        Log.d(RENDER_TAG, "Using VBR (Variable Bitrate) mode ($reason)")
+        MediaCodecInfo.EncoderCapabilities.BITRATE_MODE_VBR
+    }
+
+    return BitrateChoice(safeBitrate, bitrateMode)
+}
+
+/**
+ * Configures video encoder bitrate settings on [encoderFactoryBuilder].
+ *
+ * Thin wrapper around [resolveBitrateSettings] kept for callers that
+ * configure a [DefaultEncoderFactory.Builder] directly.
+ *
+ * @param encoderFactoryBuilder Encoder factory to configure
+ * @param mimeType Video MIME type (e.g., "video/avc" for H.264)
+ * @param bitrate Target bitrate in bits per second
+ */
+@UnstableApi
+fun applyBitrate(
+    encoderFactoryBuilder: DefaultEncoderFactory.Builder,
+    mimeType: String?,
+    bitrate: Int?
+) {
+    val choice = resolveBitrateSettings(mimeType, bitrate) ?: return
+    encoderFactoryBuilder.setRequestedVideoEncoderSettings(
+        VideoEncoderSettings.Builder()
+            .setBitrateMode(choice.bitrateMode)
+            .setBitrate(choice.bitrate)
+            .build()
+    )
+}

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

@@ -0,0 +1,27 @@
+package expo.modules.provideoeditor.src.features.render.helpers
+
+import androidx.media3.common.Effect
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.effect.GaussianBlur
+import expo.modules.provideoeditor.src.core.constants.RENDER_TAG
+import expo.modules.provideoeditor.src.shared.logging.PluginLog as Log
+
+/**
+ * Applies Gaussian blur effect to video.
+ *
+ * Uses GaussianBlur with sigma multiplied by 2.5 for visual consistency.
+ * No effect if blur value is null or <= 0.
+ *
+ * @param videoEffects List to add blur effect to
+ * @param blur Blur intensity (higher = more blur)
+ */
+@UnstableApi
+fun applyBlur(videoEffects: MutableList<Effect>, blur: Double?) {
+    if (blur == null || blur <= 0.0) return
+
+    val actualSigma = blur.toFloat() * 2.5f
+    Log.d(RENDER_TAG, "Applying Gaussian blur: intensity=$blur, sigma=$actualSigma")
+
+    val blurEffect = GaussianBlur(blur.toFloat() * 2.5f)
+    videoEffects += blurEffect
+}

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

@@ -0,0 +1,58 @@
+package expo.modules.provideoeditor.src.features.render.helpers
+
+import androidx.media3.common.Effect
+import androidx.media3.common.util.UnstableApi
+import expo.modules.provideoeditor.src.core.constants.RENDER_TAG
+import expo.modules.provideoeditor.src.features.render.models.ChromaKeyConfig
+import expo.modules.provideoeditor.src.shared.logging.PluginLog as Log
+
+/**
+ * Adds a chroma key ("green screen" removal) to a clip's effect chain.
+ *
+ * Must be added **before** rotation, flip, the color LUT and blur, so the key
+ * sees the original decoded colors. Media3's LUT shader preserves alpha
+ * (`gl_FragColor.a = inputColor.a`), so a color filter after the key is safe.
+ *
+ * @param videoEffects List to add the effect to
+ * @param config The resolved key (clip ?: layer ?: global), or null for none
+ * @param flattenTransparency Whether a key without a background should be
+ *  filled with opaque black instead of left transparent. True on the
+ *  single-track path — see below.
+ */
+@UnstableApi
+fun applyChromaKey(
+    videoEffects: MutableList<Effect>,
+    config: ChromaKeyConfig?,
+    flattenTransparency: Boolean = false,
+) {
+    if (config == null) return
+
+    // H.264/HEVC carry no alpha channel, and the single-track path has no layer
+    // underneath to blend into, so "transparent" has no meaning there. Left
+    // alone the two platforms would disagree visibly: Apple's premultiplied
+    // color cube writes rgb*0 and the area comes out black, while this shader
+    // writes straight alpha and leaves the RGB untouched, so the screen would
+    // simply stay green — "nothing happened". Substituting opaque black makes
+    // both platforms produce the documented result.
+    val effective = if (flattenTransparency && config.isTransparent) {
+        config.copy(backgroundColor = OPAQUE_BLACK)
+    } else {
+        config
+    }
+
+    val background = when {
+        effective.backgroundImage != null -> "image"
+        effective.backgroundColor != null -> "color"
+        else -> "transparent"
+    }
+    Log.d(
+        RENDER_TAG,
+        "Applying chroma key: similarity=${effective.similarity} " +
+            "smoothness=${effective.smoothness} spill=${effective.spill} " +
+            "background=$background"
+    )
+
+    videoEffects += ChromaKeyEffect(effective)
+}
+
+private const val OPAQUE_BLACK = 0xFF000000.toInt()

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

@@ -0,0 +1,88 @@
+package expo.modules.provideoeditor.src.features.render.helpers
+
+import android.graphics.Bitmap
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.effect.BitmapOverlay
+import androidx.media3.effect.StaticOverlaySettings
+import kotlin.math.max
+
+/**
+ * Full-frame solid-color overlay used to implement "dip" clip transitions
+ * (fade-to-black / fade-to-white).
+ *
+ * A single instance is attached to a clip's effect pipeline. The overlay alpha
+ * is computed per frame from the clip-local presentation time:
+ * - [fadeInUs]  > 0: the clip fades **in from the dip color** over its first
+ *   window (alpha 1 → 0).
+ * - [fadeOutUs] > 0: the clip fades **out to the dip color** over its last
+ *   window (alpha 0 → 1).
+ *
+ * Timestamps are clip-local (each [androidx.media3.transformer.EditedMediaItem]
+ * in a sequence is processed with its own timeline), and the overlay is added
+ * **after** any per-clip [androidx.media3.effect.SpeedChangeEffect] so the
+ * windows are expressed in output-local time via [clipDurationUs].
+ *
+ * @param dipColor ARGB color the clip dips to/from (e.g. black or white).
+ */
+@UnstableApi
+internal class ClipFadeOverlay(
+    videoWidth: Int,
+    videoHeight: Int,
+    dipColor: Int,
+    private val clipDurationUs: Long,
+    private val fadeInUs: Long,
+    private val fadeOutUs: Long,
+    private val curve: String,
+) : BitmapOverlay() {
+
+    private val dipBitmap: Bitmap =
+        Bitmap.createBitmap(
+            max(1, videoWidth),
+            max(1, videoHeight),
+            Bitmap.Config.ARGB_8888,
+        ).apply { eraseColor(dipColor) }
+
+    private val settingsBuilder = StaticOverlaySettings.Builder()
+        .setOverlayFrameAnchor(0f, 0f)
+        .setBackgroundFrameAnchor(0f, 0f)
+
+    /**
+     * Smallest presentation timestamp seen so far. Media3 does **not** present
+     * clip-local 0-based timestamps to per-clip effects (a trimmed/non-first
+     * clip starts at its own offset), so we normalize against the first frame
+     * the overlay sees. This makes the windows clip-relative regardless of the
+     * underlying timestamp domain (source-based or cumulative).
+     */
+    private var firstTimeUs = Long.MIN_VALUE
+
+    override fun getBitmap(presentationTimeUs: Long): Bitmap = dipBitmap
+
+    override fun getOverlaySettings(presentationTimeUs: Long): StaticOverlaySettings {
+        if (firstTimeUs == Long.MIN_VALUE || presentationTimeUs < firstTimeUs) {
+            firstTimeUs = presentationTimeUs
+        }
+        val localUs = (presentationTimeUs - firstTimeUs).coerceAtLeast(0L)
+
+        var alpha = 0f
+
+        if (fadeInUs > 0 && localUs < fadeInUs) {
+            val p = (localUs.toDouble() / fadeInUs).coerceIn(0.0, 1.0)
+            // Fade in from black: opaque at start, transparent at the window end.
+            alpha = (1.0 - applyEasing(p, curve)).toFloat()
+        }
+
+        if (fadeOutUs > 0) {
+            val outStart = clipDurationUs - fadeOutUs
+            if (localUs > outStart) {
+                val p = ((localUs - outStart).toDouble() / fadeOutUs)
+                    .coerceIn(0.0, 1.0)
+                // Fade out to black: transparent at the window start, opaque at end.
+                alpha = max(alpha, applyEasing(p, curve).toFloat())
+            }
+        }
+
+        return settingsBuilder
+            .setAlphaScale(alpha.coerceIn(0f, 1f))
+            .build()
+    }
+}