@imgly/editor-react-native 1.80.0-rc.1 → 1.81.0-rc.0

package/android/src/main/kotlin/ly/img/editor/configuration/memories/iconPack/TouchTriple.kt

@@ -0,0 +1,134 @@
+package ly.img.editor.configuration.memories.iconPack
+
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.PathFillType
+import androidx.compose.ui.graphics.SolidColor
+import androidx.compose.ui.graphics.StrokeCap
+import androidx.compose.ui.graphics.StrokeJoin
+import androidx.compose.ui.graphics.vector.ImageVector
+import androidx.compose.ui.graphics.vector.path
+import androidx.compose.ui.unit.dp
+import ly.img.editor.core.iconpack.IconPack
+
+// Material Symbols Rounded "touch_triple" (filled) — used for the multi-select toggle.
+val IconPack.TouchTriple: ImageVector
+    get() {
+        if (touchTriple != null) return touchTriple!!
+        touchTriple = ImageVector.Builder(
+            name = "touch_triple",
+            defaultWidth = 24.dp,
+            defaultHeight = 24.dp,
+            viewportWidth = 24f,
+            viewportHeight = 24f,
+        ).apply {
+            path(
+                fill = SolidColor(Color.Black),
+                fillAlpha = 1f,
+                stroke = null,
+                strokeAlpha = 1f,
+                strokeLineWidth = 1f,
+                strokeLineCap = StrokeCap.Butt,
+                strokeLineJoin = StrokeJoin.Bevel,
+                strokeLineMiter = 1f,
+                pathFillType = PathFillType.NonZero,
+            ) {
+                moveTo(19.95f, 9f)
+                quadTo(19.53f, 9f, 19.25f, 8.71f)
+                quadTo(18.98f, 8.42f, 18.98f, 8f)
+                quadToRelative(0f, -0.1f, 0.13f, -0.5f)
+                quadTo(19.3f, 7.15f, 19.4f, 6.77f)
+                reflectiveQuadTo(19.5f, 6f)
+                quadToRelative(0f, -0.5f, -0.14f, -0.99f)
+                reflectiveQuadTo(18.88f, 4.15f)
+                quadTo(18.73f, 3.97f, 18.63f, 3.76f)
+                quadTo(18.53f, 3.55f, 18.53f, 3.32f)
+                quadToRelative(0f, -0.38f, 0.26f, -0.65f)
+                reflectiveQuadTo(19.43f, 2.4f)
+                quadToRelative(0.32f, 0f, 0.59f, 0.16f)
+                quadToRelative(0.26f, 0.16f, 0.46f, 0.41f)
+                quadToRelative(0.55f, 0.63f, 0.79f, 1.41f)
+                reflectiveQuadTo(21.5f, 6f)
+                quadToRelative(0f, 0.65f, -0.16f, 1.29f)
+                quadTo(21.18f, 7.93f, 20.83f, 8.5f)
+                quadTo(20.7f, 8.73f, 20.46f, 8.86f)
+                reflectiveQuadTo(19.95f, 9f)
+                close()
+                moveToRelative(-4f, 0f)
+                quadTo(15.53f, 9f, 15.25f, 8.71f)
+                reflectiveQuadTo(14.98f, 8f)
+                quadToRelative(0f, -0.1f, 0.13f, -0.5f)
+                quadTo(15.3f, 7.15f, 15.4f, 6.77f)
+                reflectiveQuadTo(15.5f, 6f)
+                quadToRelative(0f, -0.5f, -0.14f, -0.99f)
+                reflectiveQuadTo(14.88f, 4.15f)
+                quadTo(14.73f, 3.97f, 14.63f, 3.76f)
+                quadTo(14.53f, 3.55f, 14.53f, 3.32f)
+                quadToRelative(0f, -0.38f, 0.26f, -0.65f)
+                reflectiveQuadTo(15.43f, 2.4f)
+                quadToRelative(0.32f, 0f, 0.59f, 0.16f)
+                quadToRelative(0.26f, 0.16f, 0.46f, 0.41f)
+                quadToRelative(0.55f, 0.63f, 0.79f, 1.41f)
+                reflectiveQuadTo(17.5f, 6f)
+                quadToRelative(0f, 0.65f, -0.16f, 1.29f)
+                quadTo(17.18f, 7.93f, 16.83f, 8.5f)
+                quadTo(16.7f, 8.73f, 16.46f, 8.86f)
+                reflectiveQuadTo(15.95f, 9f)
+                close()
+                moveTo(10.48f, 22f)
+                quadTo(9.78f, 22f, 9.16f, 21.7f)
+                reflectiveQuadTo(8.13f, 20.85f)
+                lineTo(3.1f, 14.48f)
+                quadTo(2.9f, 14.25f, 2.93f, 13.94f)
+                reflectiveQuadTo(3.15f, 13.43f)
+                quadTo(3.65f, 12.9f, 4.35f, 12.8f)
+                reflectiveQuadToRelative(1.3f, 0.28f)
+                lineTo(7.5f, 14.2f)
+                verticalLineTo(6f)
+                quadTo(7.5f, 5.57f, 7.79f, 5.29f)
+                reflectiveQuadTo(8.5f, 5f)
+                quadTo(8.93f, 5f, 9.23f, 5.29f)
+                quadTo(9.53f, 5.57f, 9.53f, 6f)
+                verticalLineToRelative(5f)
+                horizontalLineTo(17f)
+                quadToRelative(1.25f, 0f, 2.13f, 0.88f)
+                reflectiveQuadTo(20f, 14f)
+                verticalLineToRelative(4f)
+                quadToRelative(0f, 1.65f, -1.18f, 2.82f)
+                reflectiveQuadTo(16f, 22f)
+                horizontalLineTo(10.48f)
+                close()
+                moveTo(11.98f, 9f)
+                quadTo(11.55f, 9f, 11.26f, 8.71f)
+                reflectiveQuadTo(10.98f, 8f)
+                quadToRelative(0f, -0.05f, 0.13f, -0.5f)
+                quadTo(11.3f, 7.15f, 11.4f, 6.79f)
+                quadTo(11.5f, 6.43f, 11.5f, 6f)
+                quadToRelative(0f, -1.25f, -0.88f, -2.13f)
+                reflectiveQuadTo(8.5f, 3f)
+                reflectiveQuadTo(6.38f, 3.88f)
+                reflectiveQuadTo(5.5f, 6f)
+                quadToRelative(0f, 0.43f, 0.1f, 0.79f)
+                reflectiveQuadTo(5.9f, 7.5f)
+                quadTo(5.98f, 7.63f, 6f, 7.75f)
+                reflectiveQuadTo(6.03f, 8f)
+                quadToRelative(0f, 0.42f, -0.28f, 0.71f)
+                reflectiveQuadTo(5.05f, 9f)
+                quadTo(4.78f, 9f, 4.54f, 8.85f)
+                reflectiveQuadTo(4.18f, 8.48f)
+                quadTo(3.85f, 7.93f, 3.68f, 7.3f)
+                reflectiveQuadTo(3.5f, 6f)
+                quadTo(3.5f, 3.92f, 4.96f, 2.46f)
+                reflectiveQuadTo(8.5f, 1f)
+                reflectiveQuadToRelative(3.54f, 1.46f)
+                reflectiveQuadTo(13.5f, 6f)
+                quadToRelative(0f, 0.68f, -0.17f, 1.3f)
+                reflectiveQuadToRelative(-0.5f, 1.17f)
+                quadTo(12.7f, 8.7f, 12.48f, 8.85f)
+                reflectiveQuadTo(11.98f, 9f)
+                close()
+            }
+        }.build()
+        return touchTriple!!
+    }
+
+private var touchTriple: ImageVector? = null

package/android/src/main/kotlin/ly/img/editor/configuration/memories/iconPack/VolumeDown.kt

@@ -0,0 +1,48 @@
+package ly.img.editor.configuration.memories.iconPack
+
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.SolidColor
+import androidx.compose.ui.graphics.vector.ImageVector
+import androidx.compose.ui.graphics.vector.path
+import androidx.compose.ui.unit.dp
+import ly.img.editor.core.iconpack.IconPack
+
+val IconPack.VolumeDown: ImageVector
+    get() {
+        if (_VolumeDown != null) {
+            return _VolumeDown!!
+        }
+        _VolumeDown = ImageVector.Builder(
+            name = "VolumeDown",
+            defaultWidth = 24.dp,
+            defaultHeight = 24.dp,
+            viewportWidth = 24f,
+            viewportHeight = 24f,
+            autoMirror = true,
+        ).apply {
+            path(fill = SolidColor(Color.Black)) {
+                moveTo(18.5f, 12f)
+                arcTo(4.5f, 4.5f, 0f, isMoreThanHalf = false, isPositiveArc = false, 16f, 7.97f)
+                verticalLineToRelative(8.05f)
+                curveToRelative(1.48f, -0.73f, 2.5f, -2.25f, 2.5f, -4.02f)
+                close()
+                moveTo(5f, 10f)
+                verticalLineToRelative(4f)
+                curveToRelative(0f, 0.55f, 0.45f, 1f, 1f, 1f)
+                horizontalLineToRelative(3f)
+                lineToRelative(3.29f, 3.29f)
+                curveToRelative(0.63f, 0.63f, 1.71f, 0.18f, 1.71f, -0.71f)
+                verticalLineTo(6.41f)
+                curveToRelative(0f, -0.89f, -1.08f, -1.34f, -1.71f, -0.71f)
+                lineTo(9f, 9f)
+                horizontalLineTo(6f)
+                curveToRelative(-0.55f, 0f, -1f, 0.45f, -1f, 1f)
+                close()
+            }
+        }.build()
+
+        return _VolumeDown!!
+    }
+
+@Suppress("ObjectPropertyName")
+private var _VolumeDown: ImageVector? = null

package/android/src/main/kotlin/ly/img/editor/configuration/memories/iconPack/VolumeUp.kt

@@ -0,0 +1,60 @@
+package ly.img.editor.configuration.memories.iconPack
+
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.SolidColor
+import androidx.compose.ui.graphics.vector.ImageVector
+import androidx.compose.ui.graphics.vector.path
+import androidx.compose.ui.unit.dp
+import ly.img.editor.core.iconpack.IconPack
+
+val IconPack.VolumeUp: ImageVector
+    get() {
+        if (_VolumeUp != null) {
+            return _VolumeUp!!
+        }
+        _VolumeUp = ImageVector.Builder(
+            name = "VolumeUp",
+            defaultWidth = 24.dp,
+            defaultHeight = 24.dp,
+            viewportWidth = 24f,
+            viewportHeight = 24f,
+            autoMirror = true,
+        ).apply {
+            path(fill = SolidColor(Color.Black)) {
+                moveTo(3f, 10f)
+                verticalLineToRelative(4f)
+                curveToRelative(0f, 0.55f, 0.45f, 1f, 1f, 1f)
+                horizontalLineToRelative(3f)
+                lineToRelative(3.29f, 3.29f)
+                curveToRelative(0.63f, 0.63f, 1.71f, 0.18f, 1.71f, -0.71f)
+                lineTo(12f, 6.41f)
+                curveToRelative(0f, -0.89f, -1.08f, -1.34f, -1.71f, -0.71f)
+                lineTo(7f, 9f)
+                lineTo(4f, 9f)
+                curveToRelative(-0.55f, 0f, -1f, 0.45f, -1f, 1f)
+                close()
+                moveTo(16.5f, 12f)
+                arcTo(4.5f, 4.5f, 0f, isMoreThanHalf = false, isPositiveArc = false, 14f, 7.97f)
+                verticalLineToRelative(8.05f)
+                curveToRelative(1.48f, -0.73f, 2.5f, -2.25f, 2.5f, -4.02f)
+                close()
+                moveTo(14f, 4.45f)
+                verticalLineToRelative(0.2f)
+                curveToRelative(0f, 0.38f, 0.25f, 0.71f, 0.6f, 0.85f)
+                curveTo(17.18f, 6.53f, 19f, 9.06f, 19f, 12f)
+                reflectiveCurveToRelative(-1.82f, 5.47f, -4.4f, 6.5f)
+                curveToRelative(-0.36f, 0.14f, -0.6f, 0.47f, -0.6f, 0.85f)
+                verticalLineToRelative(0.2f)
+                curveToRelative(0f, 0.63f, 0.63f, 1.07f, 1.21f, 0.85f)
+                curveTo(18.6f, 19.11f, 21f, 15.84f, 21f, 12f)
+                reflectiveCurveToRelative(-2.4f, -7.11f, -5.79f, -8.4f)
+                curveToRelative(-0.58f, -0.23f, -1.21f, 0.22f, -1.21f, 0.85f)
+                close()
+            }
+        }.build()
+
+        return _VolumeUp!!
+    }
+
+@Suppress("ObjectPropertyName")
+private var _VolumeUp: ImageVector? = null

package/android/src/main/kotlin/ly/img/editor/configuration/memories/model/ExportStatus.kt

@@ -0,0 +1,20 @@
+package ly.img.editor.configuration.memories.model
+
+import ly.img.engine.MimeType
+import java.io.File
+
+/** The state of the MP4 export, surfaced as a progress overlay. */
+sealed interface ExportStatus {
+    data class Loading(
+        val progress: Float,
+    ) : ExportStatus
+
+    data class Success(
+        val file: File,
+        val mimeType: MimeType = MimeType.MP4,
+    ) : ExportStatus
+
+    data class Error(
+        val exception: Exception,
+    ) : ExportStatus
+}

package/android/src/main/kotlin/ly/img/editor/configuration/memories/model/ImageItem.kt

@@ -0,0 +1,8 @@
+package ly.img.editor.configuration.memories.model
+
+data class ImageItem(
+    val id: Int,
+    val url: String,
+    val creationDate: Long? = null, // Timestamp in milliseconds since epoch, null for stock images
+    val isVideo: Boolean = false, // true when [url] points to a video; placed as a trimmed video clip
+)

package/android/src/main/kotlin/ly/img/editor/configuration/memories/model/TimelineImage.kt

@@ -0,0 +1,18 @@
+package ly.img.editor.configuration.memories.model
+
+/**
+ * An image as it sits on the video timeline, used by the bottom-panel thumbnail strip.
+ *
+ * @param url the image fill URI
+ * @param startTime when the image block starts on the timeline (seconds)
+ * @param endTime when the image block ends (seconds)
+ * @param fullyVisibleTime the moment the image is fully visible — right after its enter
+ *   (Ken Burns) animation completes — which is where tapping the thumbnail seeks to.
+ */
+data class TimelineImage(
+    val url: String,
+    val startTime: Double,
+    val endTime: Double,
+    val fullyVisibleTime: Double,
+    val isVideo: Boolean = false,
+)

package/android/src/main/kotlin/ly/img/editor/configuration/memories/scene/Events.kt

@@ -0,0 +1,59 @@
+package ly.img.editor.configuration.memories.scene
+
+import android.util.Log
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.launch
+import ly.img.editor.configuration.memories.MemoriesViewModel
+import ly.img.editor.core.EditorContext
+import ly.img.engine.DesignBlockEvent
+import ly.img.engine.Engine
+
+private const val TAG = "MemoriesEvents"
+
+private const val AUDIO_TYPE = "//ly.img.ubq/audio"
+private const val MIN_LOAD_MILLIS = 2000L
+
+internal fun setupEventSubscriptions(
+    engine: Engine,
+    editorContext: EditorContext,
+    viewModel: MemoriesViewModel,
+) {
+    subscribeMinimumLoad(editorContext, viewModel)
+    subscribeSingleAudioTrack(engine, editorContext)
+}
+
+/** Hold the loading screen for a minimum time so it doesn't flash. */
+private fun subscribeMinimumLoad(
+    editorContext: EditorContext,
+    viewModel: MemoriesViewModel,
+) {
+    editorContext.coroutineScope.launch {
+        val elapsed = System.currentTimeMillis() - viewModel.loadingStartTime.first()
+        if (elapsed < MIN_LOAD_MILLIS) delay(MIN_LOAD_MILLIS - elapsed)
+        viewModel.setEditorLoading(false)
+    }
+}
+
+/** Keep a single audio track: destroy older audio blocks when a new one is added. */
+private fun subscribeSingleAudioTrack(
+    engine: Engine,
+    editorContext: EditorContext,
+) {
+    editorContext.coroutineScope.launch {
+        engine.event.subscribe(listOf()).collect { events ->
+            events.filter { it.type == DesignBlockEvent.Type.CREATED }
+                .filter { runCatching { engine.block.getType(it.block) == AUDIO_TYPE }.getOrDefault(false) }
+                .forEach { event ->
+                    try {
+                        val parent = engine.block.getParent(event.block) ?: return@forEach
+                        engine.block.getChildren(parent)
+                            .filter { it != event.block && engine.block.getType(it) == AUDIO_TYPE }
+                            .forEach { engine.block.destroy(it) }
+                    } catch (e: Exception) {
+                        Log.w(TAG, "Could not enforce single audio track", e)
+                    }
+                }
+        }
+    }
+}

package/android/src/main/kotlin/ly/img/editor/configuration/memories/scene/Playback.kt

@@ -0,0 +1,29 @@
+package ly.img.editor.configuration.memories.scene
+
+import ly.img.engine.Engine
+
+/** Playback engine ops on the slideshow page. The ViewModel holds the matching UI state. */
+
+/** Flip the page's loop setting and return the new value (null if there's no page yet). */
+internal fun togglePageLoop(engine: Engine): Boolean? {
+    val page = engine.scene.getCurrentPage() ?: return null
+    val next = !engine.block.isLooping(page)
+    engine.block.setLooping(page, next)
+    return next
+}
+
+internal fun setPageLooping(
+    engine: Engine,
+    looping: Boolean,
+) {
+    engine.scene.getCurrentPage()?.let { engine.block.setLooping(it, looping) }
+}
+
+internal fun setPageVolume(
+    engine: Engine,
+    volume: Float,
+) {
+    engine.scene.getCurrentPage()?.let { engine.block.setVolume(it, volume) }
+}
+
+internal fun getPageVolume(engine: Engine): Float? = engine.scene.getCurrentPage()?.let { engine.block.getVolume(it) }

package/android/src/main/kotlin/ly/img/editor/configuration/memories/scene/SceneSetup.kt

@@ -0,0 +1,79 @@
+package ly.img.editor.configuration.memories.scene
+
+import ly.img.editor.configuration.memories.util.PAGE_HEIGHT
+import ly.img.editor.configuration.memories.util.PAGE_WIDTH
+import ly.img.engine.Color
+import ly.img.engine.DesignBlock
+import ly.img.engine.DesignBlockType
+import ly.img.engine.Engine
+import ly.img.engine.FillType
+import ly.img.engine.ShapeType
+
+/** Build the slideshow scene in code (no serialized blob): a video scene with one sized page. */
+internal fun createSlideshowScene(engine: Engine): DesignBlock {
+    val scene = engine.scene.createForVideo()
+    val page = engine.block.create(DesignBlockType.Page)
+    engine.block.appendChild(parent = scene, child = page)
+    engine.block.setWidth(page, PAGE_WIDTH)
+    engine.block.setHeight(page, PAGE_HEIGHT)
+
+    val fill = engine.block.createFill(FillType.Color)
+    engine.block.setColor(fill, "fill/color/value", Color.fromRGBA(0f, 0f, 0f, 1f))
+    engine.block.setFill(page, fill)
+    return page
+}
+
+/**
+ * The persistent, single-purpose tracks of the slideshow, bottom-to-top in render order. The per-
+ * slide media tracks are created later (in [createMainImageSequence]) and stack on top of these.
+ */
+internal data class TrackReferences(
+    val textTrack: DesignBlock,
+    val backgroundTrack: DesignBlock,
+    val backgroundBlock: DesignBlock,
+    val matteTrack: DesignBlock,
+    val matteBlock: DesignBlock,
+)
+
+internal fun setupTracks(
+    engine: Engine,
+    page: DesignBlock,
+): TrackReferences {
+    // background = per-style backdrop (hidden by default); matte = black rectangle so a crossfade
+    // fades to black instead of revealing the backdrop. Appended first → they render behind the
+    // media. The text (title) track sits just above them; the media tracks are appended on top later.
+    val backgroundTrack = engine.block.create(DesignBlockType.Track)
+    val matteTrack = engine.block.create(DesignBlockType.Track)
+    val textTrack = engine.block.create(DesignBlockType.Track)
+
+    // Tags let the rest of the kit re-locate tracks by role instead of retaining stale block ids.
+    tagSlideshowTracks(engine, textTrack = textTrack, backgroundTrack = backgroundTrack, matteTrack = matteTrack)
+
+    engine.block.appendChild(parent = page, child = backgroundTrack)
+    engine.block.appendChild(parent = page, child = matteTrack)
+    engine.block.appendChild(parent = page, child = textTrack)
+
+    val backgroundBlock = fullPageBlock(engine, page)
+    engine.block.setVisible(backgroundBlock, false)
+    engine.block.appendChild(parent = backgroundTrack, child = backgroundBlock)
+
+    val matteBlock = fullPageBlock(engine, page)
+    val matteFill = engine.block.createFill(FillType.Color)
+    engine.block.setColor(matteFill, "fill/color/value", Color.fromRGBA(0f, 0f, 0f, 1f))
+    engine.block.setFill(matteBlock, matteFill)
+    engine.block.appendChild(parent = matteTrack, child = matteBlock)
+
+    return TrackReferences(textTrack, backgroundTrack, backgroundBlock, matteTrack, matteBlock)
+}
+
+private fun fullPageBlock(
+    engine: Engine,
+    page: DesignBlock,
+): DesignBlock {
+    val block = engine.block.create(DesignBlockType.Graphic)
+    engine.block.setScopeEnabled(block, "editor/select", false)
+    engine.block.setShape(block, engine.block.createShape(ShapeType.Rect))
+    engine.block.setWidth(block, engine.block.getWidth(page))
+    engine.block.setHeight(block, engine.block.getHeight(page))
+    return block
+}

package/android/src/main/kotlin/ly/img/editor/configuration/memories/scene/Timeline.kt

@@ -0,0 +1,27 @@
+package ly.img.editor.configuration.memories.scene
+
+import ly.img.editor.configuration.memories.model.ImageItem
+import ly.img.editor.configuration.memories.util.AnimationPair
+import ly.img.engine.Engine
+
+/**
+ * Lay the photos/clips out, one per track. Each track is appended on top of the previous one so a
+ * later slide always renders above the earlier one; the clips (videos included) are created first so
+ * their final durations are known, then every track is positioned in time by [repositionTracks] —
+ * consecutive slides overlap for the crossfade, a short video takes up only its own length, and
+ * photos next to a video hard-cut on that side (handled per-clip in [createMediaBlock]). Returns the
+ * per-slot durations so the caller can size the page and backdrops to match.
+ */
+internal suspend fun createMainImageSequence(
+    engine: Engine,
+    page: Int,
+    images: List<ImageItem>,
+    hasTitle: Boolean,
+    animationPairs: List<AnimationPair>,
+): List<Double> {
+    images.forEachIndexed { index, _ ->
+        val track = createMediaTrack(engine, page, startTime = 0.0)
+        engine.block.appendChild(parent = track, child = createMediaBlock(engine, page, index, images, animationPairs))
+    }
+    return repositionTracks(engine, page, images, hasTitle)
+}

package/android/src/main/kotlin/ly/img/editor/configuration/memories/scene/Title.kt

@@ -0,0 +1,162 @@
+package ly.img.editor.configuration.memories.scene
+
+import android.content.Context
+import android.util.Log
+import ly.img.editor.configuration.memories.model.ImageItem
+import ly.img.editor.configuration.memories.style.VideoStyles
+import ly.img.editor.configuration.memories.util.BURST_IMAGE_COUNT
+import ly.img.editor.configuration.memories.util.BURST_TITLE_FRACTION
+import ly.img.editor.configuration.memories.util.TITLE_DURATION
+import ly.img.editor.configuration.memories.util.TITLE_FONT_SIZE
+import ly.img.editor.configuration.memories.widget.videoThumbnailFileUri
+import ly.img.engine.AnimationType
+import ly.img.engine.Color
+import ly.img.engine.DesignBlockType
+import ly.img.engine.Engine
+import ly.img.engine.FillType
+import ly.img.engine.FindAssetsQuery
+import ly.img.engine.ShapeType
+import kotlin.random.Random
+
+private const val TAG = "MemoriesTitle"
+
+/** Create the centered, blur-animated title card on [textTrack]. Returns whether a title was added. */
+internal suspend fun createTitleBlock(
+    engine: Engine,
+    page: Int,
+    title: String,
+    textTrack: Int,
+): Boolean {
+    if (title.isEmpty()) return false
+
+    val textBlock = engine.block.create(DesignBlockType.Text)
+    engine.block.replaceText(textBlock, title)
+    engine.block.setDuration(textBlock, TITLE_DURATION)
+    engine.block.setTextColor(textBlock, Color.fromRGBA(1f, 1f, 1f, 1f))
+    engine.block.setTextFontSize(textBlock, fontSize = TITLE_FONT_SIZE, from = 0, to = title.length)
+    engine.block.setMetadata(textBlock, "blockType", "title")
+
+    applyTitleTypeface(engine, textBlock, VideoStyles.DEFAULT.typeface)
+
+    engine.block.setInAnimation(textBlock, blurAnimation(engine, 0.8))
+    engine.block.setOutAnimation(textBlock, blurAnimation(engine, 0.6))
+
+    engine.block.appendChild(parent = textTrack, child = textBlock)
+    engine.block.setEnum(textBlock, "text/horizontalAlignment", "Center")
+    engine.block.setEnum(textBlock, "text/verticalAlignment", "Center")
+    return true
+}
+
+private fun blurAnimation(
+    engine: Engine,
+    duration: Double,
+): Int {
+    val animation = engine.block.createAnimation(AnimationType.Blur)
+    engine.block.setDuration(animation, duration)
+    engine.block.setEnum(animation, "textAnimationWritingStyle", "Character")
+    return animation
+}
+
+private suspend fun applyTitleTypeface(
+    engine: Engine,
+    textBlock: Int,
+    typefaceName: String,
+) {
+    try {
+        val assets = engine.asset.findAssets(
+            sourceId = "ly.img.typeface",
+            query = FindAssetsQuery(query = typefaceName, page = 0, perPage = 100),
+        )
+        val typeface = assets.assets.firstOrNull()?.payload?.typeface ?: return
+        // Match the weight preference the default style applies (see StyleApplier.resolveFont), so
+        // the first style application doesn't visibly re-weight the title from a different initial pick.
+        val font = VideoStyles.DEFAULT.fontWeights
+            .firstNotNullOfOrNull { weight -> typeface.fonts.firstOrNull { it.subFamily == weight } }
+            ?: typeface.fonts.firstOrNull()
+            ?: return
+        engine.block.setFont(textBlock, font.uri, typeface)
+    } catch (e: Exception) {
+        Log.w(TAG, "Could not load title typeface '$typefaceName'", e)
+    }
+}
+
+/**
+ * Flash a handful of random photos behind the title for a lively opening. Videos can't be shown
+ * through an image fill, so each picked video is flashed as its extracted thumbnail instead (skipped
+ * if a frame can't be decoded, or if [context] is unavailable).
+ */
+internal suspend fun createBurstImages(
+    engine: Engine,
+    page: Int,
+    context: Context?,
+    images: List<ImageItem>,
+    hasTitle: Boolean,
+) {
+    if (images.isEmpty() || !hasTitle) return
+
+    // Resolve each picked item to a renderable image URI: photos use their url, videos a thumbnail.
+    val urls = pickBurstImages(images, BURST_IMAGE_COUNT).mapNotNull { item ->
+        when {
+            !item.isVideo -> item.url
+            context != null -> videoThumbnailFileUri(context, item.url)
+            else -> null
+        }
+    }
+    if (urls.isEmpty()) return
+
+    val burstTracks = List(urls.size) {
+        engine.block.create(DesignBlockType.Track).also { engine.block.appendChild(page, it) }
+    }
+
+    val burstDuration = TITLE_DURATION * BURST_TITLE_FRACTION
+    val flashDuration = burstDuration / 6.0
+    val pageWidth = engine.block.getWidth(page)
+    val pageHeight = engine.block.getHeight(page)
+    val imageSize = minOf(pageWidth, pageHeight) * 0.6f
+
+    urls.forEachIndexed { index, url ->
+        val block = engine.block.create(DesignBlockType.Graphic)
+        engine.block.setScopeEnabled(block, "editor/select", false)
+        engine.block.setWidth(block, imageSize)
+        engine.block.setHeight(block, imageSize)
+        engine.block.setPositionX(block, randomIn(-imageSize / 2f, pageWidth - imageSize / 2f))
+        engine.block.setPositionY(block, randomIn(-imageSize / 2f, pageHeight - imageSize / 2f))
+
+        val fill = engine.block.createFill(FillType.Image)
+        engine.block.setFill(block, fill)
+        engine.block.setString(fill, "fill/image/imageFileURI", url)
+        engine.block.setShape(block, engine.block.createShape(ShapeType.Rect))
+        engine.block.setDuration(block, flashDuration)
+        engine.block.setInAnimation(block, fadeAnimation(engine, 0.1))
+        engine.block.setOutAnimation(block, fadeAnimation(engine, 0.15))
+
+        val startDelay = index * (flashDuration * 0.25)
+        if (startDelay > 0) {
+            engine.block.appendChild(burstTracks[index], createSpacerBlock(engine, page, startDelay))
+        }
+        engine.block.appendChild(burstTracks[index], block)
+        val remaining = TITLE_DURATION - (startDelay + flashDuration)
+        if (remaining > 0) {
+            engine.block.appendChild(burstTracks[index], createSpacerBlock(engine, page, remaining))
+        }
+    }
+}
+
+private fun pickBurstImages(
+    images: List<ImageItem>,
+    count: Int,
+): List<ImageItem> {
+    val shuffled = images.shuffled(Random(System.currentTimeMillis()))
+    if (shuffled.size >= count) return shuffled.take(count)
+    return generateSequence { shuffled }.flatten().take(count).toList()
+}
+
+private fun fadeAnimation(
+    engine: Engine,
+    duration: Double,
+): Int = engine.block.createAnimation(AnimationType.Fade).also { engine.block.setDuration(it, duration) }
+
+private fun randomIn(
+    min: Float,
+    max: Float,
+): Float = min + Random.nextFloat() * (max - min)