--- title: "Animation" description: "Add motion to designs with support for keyframes, timeline editing, and programmatic animation control." platform: android url: "https://img.ly/docs/cesdk/android/animation-ce900c/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Animation](https://img.ly/docs/cesdk/android/animation-ce900c/) --- --- ## Related Pages - [Overview](https://img.ly/docs/cesdk/android/animation/overview-6a2ef2/) - Add motion to designs with support for keyframes, timeline editing, and programmatic animation control. - [Supported Animation Types](https://img.ly/docs/cesdk/android/animation/types-4e5f41/) - Explore the types of animations supported by CE.SDK, including object, text, and transition effects. - [Create Animations](https://img.ly/docs/cesdk/android/animation/create-15cf50/) - Build animations manually or with presets to animate objects, text, and scenes within your design. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Create Animations" description: "Build animations manually or with presets to animate objects, text, and scenes within your design." platform: android url: "https://img.ly/docs/cesdk/android/animation/create-15cf50/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Animation](https://img.ly/docs/cesdk/android/animation-ce900c/) > [Create Animations](https://img.ly/docs/cesdk/android/animation/create-15cf50/) --- --- ## Related Pages - [Base Animations](https://img.ly/docs/cesdk/android/animation/create/base-0fc5c4/) - Apply movement, scaling, rotation, or opacity changes to elements using timeline-based keyframes. - [Text Animations](https://img.ly/docs/cesdk/android/animation/create/text-d6f4aa/) - Animate text elements with effects like fade, typewriter, and bounce for dynamic visual presentation. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Base Animations" description: "Apply movement, scaling, rotation, or opacity changes to elements using timeline-based keyframes." platform: android url: "https://img.ly/docs/cesdk/android/animation/create/base-0fc5c4/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Animation](https://img.ly/docs/cesdk/android/animation-ce900c/) > [Create Animations](https://img.ly/docs/cesdk/android/animation/create-15cf50/) > [Base Animations](https://img.ly/docs/cesdk/android/animation/create/base-0fc5c4/) --- ```kotlin file=@cesdk_android_examples/engine-guides-using-animations/UsingAnimations.kt reference-only import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.AnimationType import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType import ly.img.engine.SizeMode fun usingAnimations( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val scene = engine.scene.createForVideo() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) engine.scene.zoomToBlock( page, paddingLeft = 40F, paddingTop = 40F, paddingRight = 40F, paddingBottom = 40F, ) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setPositionX(block, value = 100F) engine.block.setPositionY(block, value = 50F) engine.block.setWidth(block, value = 300F) engine.block.setHeight(block, value = 300F) engine.block.appendChild(parent = page, child = block) val fill = engine.block.createFill(FillType.Image) engine.block.setString( block = fill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg", ) engine.block.setFill(block, fill = fill) if (!engine.block.supportsAnimation(block)) { engine.stop() return@launch } val slideInAnimation = engine.block.createAnimation(AnimationType.Slide) val breathingLoopAnimation = engine.block.createAnimation(AnimationType.BreathingLoop) val fadeOutAnimation = engine.block.createAnimation(AnimationType.Fade) engine.block.setInAnimation(block, slideInAnimation) engine.block.setLoopAnimation(block, breathingLoopAnimation) engine.block.setOutAnimation(block, fadeOutAnimation) val animation = engine.block.getLoopAnimation(block) val animationType = engine.block.getType(animation) val squeezeLoopAnimation = engine.block.createAnimation(AnimationType.SqueezeLoop) engine.block.destroy(engine.block.getLoopAnimation(block)) engine.block.setLoopAnimation(block, squeezeLoopAnimation) // The following line would also destroy all currently attached animations // engine.block.destroy(block) val allAnimationProperties = engine.block.findAllProperties(slideInAnimation) engine.block.setFloat(slideInAnimation, "animation/slide/direction", 0.5F * Math.PI.toFloat()) engine.block.setDuration(slideInAnimation, 0.6) engine.block.setEnum(slideInAnimation, "animationEasing", "EaseOut") println("Available easing options: ${engine.block.getEnumValues("animationEasing")}") val text = engine.block.create(DesignBlockType.Text) val textAnimation = engine.block.createAnimation(AnimationType.Baseline) engine.block.setInAnimation(text, textAnimation) engine.block.appendChild(page, text) engine.block.setPositionX(text, 100F) engine.block.setPositionY(text, 100F) engine.block.setWidthMode(text, SizeMode.AUTO) engine.block.setHeightMode(text, SizeMode.AUTO) engine.block.replaceText(text, "You can animate text\nline by line,\nword by word,\nor character by character\nwith CE.SDK") engine.block.setEnum(textAnimation, "textAnimationWritingStyle", "Word") engine.block.setDuration(textAnimation, 2.0) engine.block.setEnum(textAnimation, "animationEasing", "EaseOut") val text2 = engine.block.create(DesignBlockType.Text) val textAnimation2 = engine.block.createAnimation(AnimationType.Pan) engine.block.setInAnimation(text2, textAnimation2) engine.block.appendChild(page, text2) engine.block.setPositionX(text2, 100F) engine.block.setPositionY(text2, 500F) engine.block.setWidth(text2, 500F) engine.block.setHeightMode(text2, SizeMode.AUTO) engine.block.replaceText(text2, "You can use the textAnimationOverlap property to control the overlap between text animation segments.") engine.block.setFloat(textAnimation2, "textAnimationOverlap", 0.4F) engine.block.setDuration(textAnimation2, 1.0) engine.block.setEnum(textAnimation2, "animationEasing", "EaseOut") engine.stop() } ``` CreativeEditor SDK supports many different types of configurable animations for animating the appearance of design blocks in video scenes. Similarly to blocks, each animation object has a numeric id which can be used to query and [modify its properties](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/). ## Accessing Animation APIs In order to query whether a block supports animations, you should call the `fun supportsAnimation(block: DesignBlock): Boolean` API. ```kotlin highlight-supportsAnimation if (!engine.block.supportsAnimation(block)) { engine.stop() return@launch } ``` ## Animation Categories There are three different categories of animations: *In*, *Out* and *Loop* animations. ### In Animations *In* animations animate a block for a specified duration after the block first appears in the scene. For example, if a block has a time offset of 4s in the scene and it has an *In* animation with a duration of 1s, then the appearance of the block will be animated between 4s and 5s with the *In* animation. ### Out Animations *Out* animations animate a block for a specified duration before the block disappears from the scene. For example, if a block has a time offset of 4s in the scene and a duration of 5s and it has an *Out* animation with a duration of 1s, then the appearance of the block will be animated between 8s and 9s with the *Out* animation. ### Loop Animations *Loop* animations animate a block for the total duration that the block is visible in the scene. *Loop* animations also run simultaneously with *In* and *Out* animations, if those are present. ## Creating Animations In order to create a new animation, we must call the `fun createAnimation(type: AnimationType): DesignBlock` API. All `AnimationType` implementations below are nested in `AnimationType` sealed class. We currently support the following *In* and *Out* animation types: - `Slide - "//ly.img.ubq/animation/slide"` - `Pan - "//ly.img.ubq/animation/pan"` - `Fade - "//ly.img.ubq/animation/fade"` - `Blur - "//ly.img.ubq/animation/blur"` - `Grow - "//ly.img.ubq/animation/grow"` - `Zoom - "//ly.img.ubq/animation/zoom"` - `Pop - "//ly.img.ubq/animation/pop"` - `Wipe - "//ly.img.ubq/animation/wipe"` - `Baseline - "//ly.img.ubq/animation/baseline"` - `CropZoom - "//ly.img.ubq/animation/crop_zoom"` - `Spin - "//ly.img.ubq/animation/spin"` - `KenBurns - "//ly.img.ubq/animation/ken_burns"` - `TypewriterText - "//ly.img.ubq/animation/typewriter_text"` // text-ony - `BlockSwipeText - "//ly.img.ubq/animation/block_swipe_text"` // text-ony - `SpreadText - "//ly.img.ubq/animation/spread_text"` // text-only - `MergeText - "//ly.img.ubq/animation/merge_text"` // text-only and the following *Loop* animation types: - `SpinLoop - "//ly.img.ubq/animation/spin_loop"` - `FadeLoop - "//ly.img.ubq/animation/fade_loop"` - `BlurLoop - "//ly.img.ubq/animation/blur_loop"` - `PulsatingLoop - "//ly.img.ubq/animation/pulsating_loop"` - `BreathingLoop - "//ly.img.ubq/animation/breathing_loop"` - `JumpLoop - "//ly.img.ubq/animation/jump_loop"` - `SqueezeLoop - "//ly.img.ubq/animation/squeeze_loop"` - `SwayLoop - "//ly.img.ubq/animation/sway_loop"` ```kotlin highlight-createAnimation val slideInAnimation = engine.block.createAnimation(AnimationType.Slide) val breathingLoopAnimation = engine.block.createAnimation(AnimationType.BreathingLoop) val fadeOutAnimation = engine.block.createAnimation(AnimationType.Fade) ``` ## Assigning Animations In order to assign an *In* animation to the block, call the `fun setInAnimation(block: DesignBlock, animation: DesignBlock)` API. ```kotlin highlight-setInAnimation engine.block.setInAnimation(block, slideInAnimation) ``` In order to assign a *Loop* animation to the block, call the `fun setLoopAnimation(block: DesignBlock, animation: DesignBlock)` API. ```kotlin highlight-setLoopAnimation engine.block.setLoopAnimation(block, breathingLoopAnimation) ``` In order to assign an *Out* animation to the block, call the `fun setOutAnimation(block: DesignBlock, animation: DesignBlock)` API. ```kotlin highlight-setOutAnimation engine.block.setOutAnimation(block, fadeOutAnimation) ``` To query the current animation ids of a design block, call the `fun getInAnimation(block: DesignBlock): DesignBlock`, `fun getLoopAnimation(block: DesignBlock): DesignBlock` or `fun getInAnimation(block: DesignBlock): DesignBlock` API. You can now pass the returned animation `DesignBlock` into other APIs in order to query more information about the animation, e.g. its type via the `fun getType(block: DesignBlock): String` API. In case the design block does not have animation, query will return an invalid design block. Make sure to check for `fun isValid(block: DesignBlock): Boolean` before running any API's on the animation design block. ```kotlin highlight-getAnimation val animation = engine.block.getLoopAnimation(block) val animationType = engine.block.getType(animation) ``` When replacing the animation of a design block, remember to destroy the previous animation object if you don't intend to use it any further. Animation objects that are not attached to a design block will never be automatically destroyed. Destroying a design block will also destroy all of its attached animations. ```kotlin highlight-replaceAnimation val squeezeLoopAnimation = engine.block.createAnimation(AnimationType.SqueezeLoop) engine.block.destroy(engine.block.getLoopAnimation(block)) engine.block.setLoopAnimation(block, squeezeLoopAnimation) // The following line would also destroy all currently attached animations // engine.block.destroy(block) ``` ## Animation Properties Just like design blocks, animations with different types have different properties that you can query and modify via the API. Use `fun findAllProperties(block: DesignBlock): List` in order to get a list of all properties of a given animation. For the slide animation in this example, the call would return `["name", "animation/slide/direction", "animationEasing", "includedInExport", "playback/duration", "type", "uuid"]`. Please refer to the [API docs](https://img.ly/docs/cesdk/android/animation/types-4e5f41/) for a complete list of all available properties for each type of animation. ```kotlin highlight-getProperties val allAnimationProperties = engine.block.findAllProperties(slideInAnimation) ``` Once we know the property keys of an animation, we can use the same APIs as for design blocks in order to modify those properties. For example, we can use `fun setFloat(block: DesignBlock, property: String, value: Float)` in order to change the direction of the slide animation to make our block slide in from the top. ```kotlin highlight-modifyProperties engine.block.setFloat(slideInAnimation, "animation/slide/direction", 0.5F * Math.PI.toFloat()) ``` All animations have a duration. For *In* and *Out* animations, the duration defines the total length of the animation as described above. For *Loop* animations, the duration defines the length of each loop cycle. We can use the `fun setDuration(block: DesignBlock, duration: Double)` API in order to change the animation duration. Note that changing the duration of an *In* animation will automatically adjust the duration of the *Out* animation (and vice versa) in order to avoid overlaps between the two animations. ```kotlin highlight-changeDuration engine.block.setDuration(slideInAnimation, 0.6) ``` Some animations allow you to configure their easing behavior by choosing from a list of common easing curves. The easing controls the acceleration throughout the animation. We can use the `fun setEnum(block: DesignBlock, property: String, value: String)` API in order to change the easing curve. Call `engine.block.getEnumValues("animationEasing")` in order to get a list of currently supported easing options. In this example, we set the easing to `EaseOut` so that the animation starts fast and then slows down towards the end. An `EaseIn` easing would start slow and then speed up, while `EaseInOut` starts slow, speeds up towards the middle of the animation and then slows down towards the end again. ```kotlin highlight-changeEasing engine.block.setEnum(slideInAnimation, "animationEasing", "EaseOut") println("Available easing options: ${engine.block.getEnumValues("animationEasing")}") ``` ## Full Code Here's the full code: ```kotlin import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.AnimationType import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType import ly.img.engine.SizeMode fun usingAnimations( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val scene = engine.scene.createForVideo() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) engine.scene.zoomToBlock( page, paddingLeft = 40F, paddingTop = 40F, paddingRight = 40F, paddingBottom = 40F, ) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setPositionX(block, value = 100F) engine.block.setPositionY(block, value = 50F) engine.block.setWidth(block, value = 300F) engine.block.setHeight(block, value = 300F) engine.block.appendChild(parent = page, child = block) val fill = engine.block.createFill(FillType.Image) engine.block.setString( block = fill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg", ) engine.block.setFill(block, fill = fill) if (!engine.block.supportsAnimation(block)) { engine.stop() return@launch } val slideInAnimation = engine.block.createAnimation(AnimationType.Slide) val breathingLoopAnimation = engine.block.createAnimation(AnimationType.BreathingLoop) val fadeOutAnimation = engine.block.createAnimation(AnimationType.Fade) engine.block.setInAnimation(block, slideInAnimation) engine.block.setLoopAnimation(block, breathingLoopAnimation) engine.block.setOutAnimation(block, fadeOutAnimation) val animation = engine.block.getLoopAnimation(block) val animationType = engine.block.getType(animation) val squeezeLoopAnimation = engine.block.createAnimation(AnimationType.SqueezeLoop) engine.block.destroy(engine.block.getLoopAnimation(block)) engine.block.setLoopAnimation(block, squeezeLoopAnimation) // The following line would also destroy all currently attached animations // engine.block.destroy(block) val allAnimationProperties = engine.block.findAllProperties(slideInAnimation) engine.block.setFloat(slideInAnimation, "animation/slide/direction", 0.5F * Math.PI.toFloat()) engine.block.setDuration(slideInAnimation, 0.6) engine.block.setEnum(slideInAnimation, "animationEasing", "EaseOut") println("Available easing options: ${engine.block.getEnumValues("animationEasing")}") engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Text Animations" description: "Animate text elements with effects like fade, typewriter, and bounce for dynamic visual presentation." platform: android url: "https://img.ly/docs/cesdk/android/animation/create/text-d6f4aa/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Animation](https://img.ly/docs/cesdk/android/animation-ce900c/) > [Create Animations](https://img.ly/docs/cesdk/android/animation/create-15cf50/) > [Text Animations](https://img.ly/docs/cesdk/android/animation/create/text-d6f4aa/) --- ```kotlin file=@cesdk_android_examples/engine-guides-using-animations/UsingAnimations.kt reference-only import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.AnimationType import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType import ly.img.engine.SizeMode fun usingAnimations( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val scene = engine.scene.createForVideo() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) engine.scene.zoomToBlock( page, paddingLeft = 40F, paddingTop = 40F, paddingRight = 40F, paddingBottom = 40F, ) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setPositionX(block, value = 100F) engine.block.setPositionY(block, value = 50F) engine.block.setWidth(block, value = 300F) engine.block.setHeight(block, value = 300F) engine.block.appendChild(parent = page, child = block) val fill = engine.block.createFill(FillType.Image) engine.block.setString( block = fill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg", ) engine.block.setFill(block, fill = fill) if (!engine.block.supportsAnimation(block)) { engine.stop() return@launch } val slideInAnimation = engine.block.createAnimation(AnimationType.Slide) val breathingLoopAnimation = engine.block.createAnimation(AnimationType.BreathingLoop) val fadeOutAnimation = engine.block.createAnimation(AnimationType.Fade) engine.block.setInAnimation(block, slideInAnimation) engine.block.setLoopAnimation(block, breathingLoopAnimation) engine.block.setOutAnimation(block, fadeOutAnimation) val animation = engine.block.getLoopAnimation(block) val animationType = engine.block.getType(animation) val squeezeLoopAnimation = engine.block.createAnimation(AnimationType.SqueezeLoop) engine.block.destroy(engine.block.getLoopAnimation(block)) engine.block.setLoopAnimation(block, squeezeLoopAnimation) // The following line would also destroy all currently attached animations // engine.block.destroy(block) val allAnimationProperties = engine.block.findAllProperties(slideInAnimation) engine.block.setFloat(slideInAnimation, "animation/slide/direction", 0.5F * Math.PI.toFloat()) engine.block.setDuration(slideInAnimation, 0.6) engine.block.setEnum(slideInAnimation, "animationEasing", "EaseOut") println("Available easing options: ${engine.block.getEnumValues("animationEasing")}") val text = engine.block.create(DesignBlockType.Text) val textAnimation = engine.block.createAnimation(AnimationType.Baseline) engine.block.setInAnimation(text, textAnimation) engine.block.appendChild(page, text) engine.block.setPositionX(text, 100F) engine.block.setPositionY(text, 100F) engine.block.setWidthMode(text, SizeMode.AUTO) engine.block.setHeightMode(text, SizeMode.AUTO) engine.block.replaceText(text, "You can animate text\nline by line,\nword by word,\nor character by character\nwith CE.SDK") engine.block.setEnum(textAnimation, "textAnimationWritingStyle", "Word") engine.block.setDuration(textAnimation, 2.0) engine.block.setEnum(textAnimation, "animationEasing", "EaseOut") val text2 = engine.block.create(DesignBlockType.Text) val textAnimation2 = engine.block.createAnimation(AnimationType.Pan) engine.block.setInAnimation(text2, textAnimation2) engine.block.appendChild(page, text2) engine.block.setPositionX(text2, 100F) engine.block.setPositionY(text2, 500F) engine.block.setWidth(text2, 500F) engine.block.setHeightMode(text2, SizeMode.AUTO) engine.block.replaceText(text2, "You can use the textAnimationOverlap property to control the overlap between text animation segments.") engine.block.setFloat(textAnimation2, "textAnimationOverlap", 0.4F) engine.block.setDuration(textAnimation2, 1.0) engine.block.setEnum(textAnimation2, "animationEasing", "EaseOut") engine.stop() } ``` When applied to text blocks, some animations allow you to control whether the animation should be applied to the entire text at once, line by line, word by word or character by character. We can use the `fun setEnum(block: DesignBlock, property: String, value: String)` API in order to change the text writing style. Call `engine.block.getEnumValues("textAnimationWritingStyle")` in order to get a list of currently supported text writing style options. The default writing style is `Line`. In this example, we set the easing to `Word` so that the text animates in one word at a time. ```kotlin highlight-textAnimationWritingStyle val text = engine.block.create(DesignBlockType.Text) val textAnimation = engine.block.createAnimation(AnimationType.Baseline) engine.block.setInAnimation(text, textAnimation) engine.block.appendChild(page, text) engine.block.setPositionX(text, 100F) engine.block.setPositionY(text, 100F) engine.block.setWidthMode(text, SizeMode.AUTO) engine.block.setHeightMode(text, SizeMode.AUTO) engine.block.replaceText(text, "You can animate text\nline by line,\nword by word,\nor character by character\nwith CE.SDK") engine.block.setEnum(textAnimation, "textAnimationWritingStyle", "Word") engine.block.setDuration(textAnimation, 2.0) engine.block.setEnum(textAnimation, "animationEasing", "EaseOut") ``` Together with the writing style, you can also configure the overlap between the individual segments of a text animation using the `textAnimationOverlap` property. With an overlap value of `0`, the next segment only starts its animation once the previous segment's animation has finished. With an overlap value of `1`, all segments animate at the same time. ```kotlin highlight-textAnimationOverlap val text2 = engine.block.create(DesignBlockType.Text) val textAnimation2 = engine.block.createAnimation(AnimationType.Pan) engine.block.setInAnimation(text2, textAnimation2) engine.block.appendChild(page, text2) engine.block.setPositionX(text2, 100F) engine.block.setPositionY(text2, 500F) engine.block.setWidth(text2, 500F) engine.block.setHeightMode(text2, SizeMode.AUTO) engine.block.replaceText(text2, "You can use the textAnimationOverlap property to control the overlap between text animation segments.") engine.block.setFloat(textAnimation2, "textAnimationOverlap", 0.4F) engine.block.setDuration(textAnimation2, 1.0) engine.block.setEnum(textAnimation2, "animationEasing", "EaseOut") ``` ## Full Code Here's the full code: ```kotlin import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.AnimationType import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType import ly.img.engine.SizeMode fun usingAnimations( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val scene = engine.scene.createForVideo() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) engine.scene.zoomToBlock( page, paddingLeft = 40F, paddingTop = 40F, paddingRight = 40F, paddingBottom = 40F, ) val text = engine.block.create(DesignBlockType.Text) val textAnimation = engine.block.createAnimation(AnimationType.Baseline) engine.block.setInAnimation(text, textAnimation) engine.block.appendChild(page, text) engine.block.setPositionX(text, 100F) engine.block.setPositionY(text, 100F) engine.block.setWidthMode(text, SizeMode.AUTO) engine.block.setHeightMode(text, SizeMode.AUTO) engine.block.replaceText(text, "You can animate text\nline by line,\nword by word,\nor character by character\nwith CE.SDK") engine.block.setEnum(textAnimation, "textAnimationWritingStyle", "Word") engine.block.setDuration(textAnimation, 2.0) engine.block.setEnum(textAnimation, "animationEasing", "EaseOut") val text2 = engine.block.create(DesignBlockType.Text) val textAnimation2 = engine.block.createAnimation(AnimationType.Pan) engine.block.setInAnimation(text2, textAnimation2) engine.block.appendChild(page, text2) engine.block.setPositionX(text2, 100F) engine.block.setPositionY(text2, 500F) engine.block.setWidth(text2, 500F) engine.block.setHeightMode(text2, SizeMode.AUTO) engine.block.replaceText(text2, "You can use the textAnimationOverlap property to control the overlap between text animation segments.") engine.block.setFloat(textAnimation2, "textAnimationOverlap", 0.4F) engine.block.setDuration(textAnimation2, 1.0) engine.block.setEnum(textAnimation2, "animationEasing", "EaseOut") engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Overview" description: "Add motion to designs with support for keyframes, timeline editing, and programmatic animation control." platform: android url: "https://img.ly/docs/cesdk/android/animation/overview-6a2ef2/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Animation](https://img.ly/docs/cesdk/android/animation-ce900c/) > [Overview](https://img.ly/docs/cesdk/android/animation/overview-6a2ef2/) --- Animations in CreativeEditor SDK (CE.SDK) bring your designs to life by adding motion to images, text, and design elements. Whether you're creating a dynamic social media post, a video ad, or an engaging product demo, animations help capture attention and communicate ideas more effectively. With CE.SDK, you can create and edit animations either through the built-in UI timeline or programmatically using the CreativeEngine API. Animated designs can be exported as MP4 videos, allowing you to deliver polished, motion-rich content entirely client-side. [Explore Demos](https://img.ly/showcases/cesdk?tags=android) [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Supported Animation Types" description: "Explore the types of animations supported by CE.SDK, including object, text, and transition effects." platform: android url: "https://img.ly/docs/cesdk/android/animation/types-4e5f41/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Animation](https://img.ly/docs/cesdk/android/animation-ce900c/) > [Supported Animation Types](https://img.ly/docs/cesdk/android/animation/types-4e5f41/) --- ## Animation Categories There are three different categories of animations: *In*, *Out* and *Loop* animations. ### In Animations *In* animations animate a block for a specified duration after the block first appears in the scene. For example, if a block has a time offset of 4s in the scene and it has an *In* animation with a duration of 1s, then the appearance of the block will be animated between 4s and 5s with the *In* animation. ### Out Animations *Out* animations animate a block for a specified duration before the block disappears from the scene. For example, if a block has a time offset of 4s in the scene and a duration of 5s and it has an *Out* animation with a duration of 1s, then the appearance of the block will be animated between 8s and 9s with the *Out* animation. ### Loop Animations *Loop* animations animate a block for the total duration that the block is visible in the scene. *Loop* animations also run simultaneously with *In* and *Out* animations, if those are present. ## Animation Presets We currently support the following *In* and *Out* animation presets: - `'//ly.img.ubq/animation/slide'` - `'//ly.img.ubq/animation/pan'` - `'//ly.img.ubq/animation/fade'` - `'//ly.img.ubq/animation/blur'` - `'//ly.img.ubq/animation/grow'` - `'//ly.img.ubq/animation/zoom'` - `'//ly.img.ubq/animation/pop'` - `'//ly.img.ubq/animation/wipe'` - `'//ly.img.ubq/animation/baseline'` - `'//ly.img.ubq/animation/crop_zoom'` - `'//ly.img.ubq/animation/spin'` - `'//ly.img.ubq/animation/ken_burns'` - `'//ly.img.ubq/animation/typewriter_text'` (text-only) - `'//ly.img.ubq/animation/block_swipe_text'` (text-only) - `'//ly.img.ubq/animation/merge_text'` (text-only) - `'//ly.img.ubq/animation/spread_text'` (text-only) and the following *Loop* animation types: - `'//ly.img.ubq/animation/spin_loop'` - `'//ly.img.ubq/animation/fade_loop'` - `'//ly.img.ubq/animation/blur_loop'` - `'//ly.img.ubq/animation/pulsating_loop'` - `'//ly.img.ubq/animation/breathing_loop'` - `'//ly.img.ubq/animation/jump_loop'` - `'//ly.img.ubq/animation/squeeze_loop'` - `'//ly.img.ubq/animation/sway_loop'` ## Animation Type Properties ## Baseline Type A text animation that slides text in along its baseline. This section describes the properties available for the **Baseline Type** (`//ly.img.ubq/animation/baseline`) block type. | Property | Type | Default | Description | | ------------------------------ | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `animation/baseline/direction` | `Enum` | `"Up"` | The direction of the wipe animation., Possible values: `"Up"`, `"Right"`, `"Down"`, `"Left"` | | `animationEasing` | `Enum` | `"Linear"` | The easing function to apply to the animation., Possible values: `"Linear"`, `"EaseIn"`, `"EaseOut"`, `"EaseInOut"`, `"EaseInQuart"`, `"EaseOutQuart"`, `"EaseInOutQuart"`, `"EaseInQuint"`, `"EaseOutQuint"`, `"EaseInOutQuint"`, `"EaseInBack"`, `"EaseOutBack"`, `"EaseInOutBack"`, `"EaseInSpring"`, `"EaseOutSpring"`, `"EaseInOutSpring"` | | `playback/duration` | `Double` | `0.6` | The duration in seconds for which this block should be visible. | | `textAnimationOverlap` | `Float` | `0.35` | The overlap factor for text animations. | | `textAnimationWritingStyle` | `Enum` | `"Line"` | The writing style for text animations (e.g., by character, by word)., Possible values: `"Block"`, `"Line"`, `"Character"`, `"Word"` | ## Block Swipe Text Type A text animation that reveals text with a colored block swiping across. This section describes the properties available for the **Block Swipe Text Type** (`//ly.img.ubq/animation/block_swipe_text`) block type. | Property | Type | Default | Description | | ----------------------------------------- | -------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `animation/block_swipe_text/blockColor` | `Color` | `{"r":0,"g":0,"b":0,"a":1}` | The overlay block color. | | `animation/block_swipe_text/direction` | `Enum` | `"Right"` | The direction of the block swipe animation., Possible values: `"Up"`, `"Right"`, `"Down"`, `"Left"` | | `animation/block_swipe_text/useTextColor` | `Bool` | `true` | Whether the overlay block should use the text color. | | `playback/duration` | `Double` | `1.2` | The duration in seconds for which this block should be visible. | | `textAnimationOverlap` | `Float` | `0.35` | The overlap factor for text animations. | | `textAnimationWritingStyle` | `Enum` | `"Line"` | The writing style for text animations (e.g., by character, by word)., Possible values: `"Block"`, `"Line"`, `"Character"`, `"Word"` | ## Blur Type An animation that applies a blur effect over time. This section describes the properties available for the **Blur Type** (`//ly.img.ubq/animation/blur`) block type. | Property | Type | Default | Description | | --------------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `animation/blur/fade` | `Bool` | `true` | Whether an opacity fade animation should be applied during the blur animation. | | `animation/blur/intensity` | `Float` | `1` | The maximum intensity of the blur. | | `animationEasing` | `Enum` | `"Linear"` | The easing function to apply to the animation., Possible values: `"Linear"`, `"EaseIn"`, `"EaseOut"`, `"EaseInOut"`, `"EaseInQuart"`, `"EaseOutQuart"`, `"EaseInOutQuart"`, `"EaseInQuint"`, `"EaseOutQuint"`, `"EaseInOutQuint"`, `"EaseInBack"`, `"EaseOutBack"`, `"EaseInOutBack"`, `"EaseInSpring"`, `"EaseOutSpring"`, `"EaseInOutSpring"` | | `playback/duration` | `Double` | `0.6` | The duration in seconds for which this block should be visible. | | `textAnimationOverlap` | `Float` | `0.35` | The overlap factor for text animations. | | `textAnimationWritingStyle` | `Enum` | `"Line"` | The writing style for text animations (e.g., by character, by word)., Possible values: `"Block"`, `"Line"`, `"Character"`, `"Word"` | ## Blur Loop Type A looping animation that continuously applies a blur effect. This section describes the properties available for the **Blur Loop Type** (`//ly.img.ubq/animation/blur_loop`) block type. | Property | Type | Default | Description | | ------------------------------- | -------- | ------- | --------------------------------------------------------------- | | `animation/blur_loop/intensity` | `Float` | `1` | The maximum blur intensity of this effect. | | `playback/duration` | `Double` | `1.2` | The duration in seconds for which this block should be visible. | ## Breathing Loop Type A looping animation with a slow, breathing-like scale effect. This section describes the properties available for the **Breathing Loop Type** (`//ly.img.ubq/animation/breathing_loop`) block type. | Property | Type | Default | Description | | ------------------------------------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `animation/breathing_loop/intensity` | `Float` | `0` | Controls the intensity of the scaling. A value of 0 results in a maximum scale of 1.25. A value of 1 results in a maximum scale of 2.5. | | `playback/duration` | `Double` | `1.2` | The duration in seconds for which this block should be visible. | ## Crop Zoom Type An animation that zooms the content within the block's frame. This section describes the properties available for the **Crop Zoom Type** (`//ly.img.ubq/animation/crop_zoom`) block type. | Property | Type | Default | Description | | --------------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `animation/crop_zoom/fade` | `Bool` | `true` | Whether an opacity fade animation should be applied during the crop zoom animation. | | `animation/crop_zoom/scale` | `Float` | `1.25` | The maximum crop scale value. | | `animationEasing` | `Enum` | `"Linear"` | The easing function to apply to the animation., Possible values: `"Linear"`, `"EaseIn"`, `"EaseOut"`, `"EaseInOut"`, `"EaseInQuart"`, `"EaseOutQuart"`, `"EaseInOutQuart"`, `"EaseInQuint"`, `"EaseOutQuint"`, `"EaseInOutQuint"`, `"EaseInBack"`, `"EaseOutBack"`, `"EaseInOutBack"`, `"EaseInSpring"`, `"EaseOutSpring"`, `"EaseInOutSpring"` | | `playback/duration` | `Double` | `1.2` | The duration in seconds for which this block should be visible. | ## Fade Type An animation that fades the block in or out. This section describes the properties available for the **Fade Type** (`//ly.img.ubq/animation/fade`) block type. | Property | Type | Default | Description | | --------------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `animationEasing` | `Enum` | `"Linear"` | The easing function to apply to the animation., Possible values: `"Linear"`, `"EaseIn"`, `"EaseOut"`, `"EaseInOut"`, `"EaseInQuart"`, `"EaseOutQuart"`, `"EaseInOutQuart"`, `"EaseInQuint"`, `"EaseOutQuint"`, `"EaseInOutQuint"`, `"EaseInBack"`, `"EaseOutBack"`, `"EaseInOutBack"`, `"EaseInSpring"`, `"EaseOutSpring"`, `"EaseInOutSpring"` | | `playback/duration` | `Double` | `0.6` | The duration in seconds for which this block should be visible. | | `textAnimationOverlap` | `Float` | `0.35` | The overlap factor for text animations. | | `textAnimationWritingStyle` | `Enum` | `"Line"` | The writing style for text animations (e.g., by character, by word)., Possible values: `"Block"`, `"Line"`, `"Character"`, `"Word"` | ## Fade Loop Type A looping animation that continuously fades the block in and out. This section describes the properties available for the **Fade Loop Type** (`//ly.img.ubq/animation/fade_loop`) block type. | Property | Type | Default | Description | | ------------------- | -------- | ------- | --------------------------------------------------------------- | | `playback/duration` | `Double` | `1.2` | The duration in seconds for which this block should be visible. | ## Grow Type An animation that scales the block up from a point. This section describes the properties available for the **Grow Type** (`//ly.img.ubq/animation/grow`) block type. | Property | Type | Default | Description | | --------------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `animation/grow/direction` | `Enum` | `"All"` | The direction from which the grow animation originates. Can be horizontal only, vertical only, from the center (all), or from any of the four corners (top-left, top-right, bottom-left, bottom-right)., Possible values: `"Horizontal"`, `"Vertical"`, `"All"` | | `animationEasing` | `Enum` | `"Linear"` | The easing function to apply to the animation., Possible values: `"Linear"`, `"EaseIn"`, `"EaseOut"`, `"EaseInOut"`, `"EaseInQuart"`, `"EaseOutQuart"`, `"EaseInOutQuart"`, `"EaseInQuint"`, `"EaseOutQuint"`, `"EaseInOutQuint"`, `"EaseInBack"`, `"EaseOutBack"`, `"EaseInOutBack"`, `"EaseInSpring"`, `"EaseOutSpring"`, `"EaseInOutSpring"` | | `playback/duration` | `Double` | `0.6` | The duration in seconds for which this block should be visible. | | `textAnimationOverlap` | `Float` | `0.35` | The overlap factor for text animations. | | `textAnimationWritingStyle` | `Enum` | `"Line"` | The writing style for text animations (e.g., by character, by word)., Possible values: `"Block"`, `"Line"`, `"Character"`, `"Word"` | ## Jump Loop Type A looping animation with a jumping motion. This section describes the properties available for the **Jump Loop Type** (`//ly.img.ubq/animation/jump_loop`) block type. | Property | Type | Default | Description | | ------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------- | | `animation/jump_loop/direction` | `Enum` | `"Up"` | The direction of the jump animation., Possible values: `"Up"`, `"Right"`, `"Down"`, `"Left"` | | `animation/jump_loop/intensity` | `Float` | `0.5` | Controls how far the block should move as a percentage of its width or height. | | `playback/duration` | `Double` | `1.2` | The duration in seconds for which this block should be visible. | ## Ken Burns Type An animation that simulates the Ken Burns effect by panning and zooming on content. This section describes the properties available for the **Ken Burns Type** (`//ly.img.ubq/animation/ken_burns`) block type. | Property | Type | Default | Description | | ----------------------------------------- | -------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `animation/ken_burns/direction` | `Enum` | `"Right"` | The direction of the pan travel., Possible values: `"Up"`, `"Right"`, `"Down"`, `"Left"` | | `animation/ken_burns/fade` | `Bool` | `false` | Whether an opacity fade animation should be applied during the animation. | | `animation/ken_burns/travelDistanceRatio` | `Float` | `1` | The movement distance relative to the length of the crop. | | `animation/ken_burns/zoomIntensity` | `Float` | `0.5` | The factor by which to zoom in or out. | | `animationEasing` | `Enum` | `"EaseOutQuint"` | The easing function to apply to the animation., Possible values: `"Linear"`, `"EaseIn"`, `"EaseOut"`, `"EaseInOut"`, `"EaseInQuart"`, `"EaseOutQuart"`, `"EaseInOutQuart"`, `"EaseInQuint"`, `"EaseOutQuint"`, `"EaseInOutQuint"`, `"EaseInBack"`, `"EaseOutBack"`, `"EaseInOutBack"`, `"EaseInSpring"`, `"EaseOutSpring"`, `"EaseInOutSpring"` | | `playback/duration` | `Double` | `2.4` | The duration in seconds for which this block should be visible. | ## Merge Text Type A text animation where lines of text merge from opposite directions. This section describes the properties available for the **Merge Text Type** (`//ly.img.ubq/animation/merge_text`) block type. | Property | Type | Default | Description | | -------------------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `animation/merge_text/direction` | `Enum` | `"Left"` | The in-animation direction of the first line of text., Possible values: `"Right"`, `"Left"` | | `animation/merge_text/intensity` | `Float` | `0.5` | The intensity of the pan. | | `animationEasing` | `Enum` | `"Linear"` | The easing function to apply to the animation., Possible values: `"Linear"`, `"EaseIn"`, `"EaseOut"`, `"EaseInOut"`, `"EaseInQuart"`, `"EaseOutQuart"`, `"EaseInOutQuart"`, `"EaseInQuint"`, `"EaseOutQuint"`, `"EaseInOutQuint"`, `"EaseInBack"`, `"EaseOutBack"`, `"EaseInOutBack"`, `"EaseInSpring"`, `"EaseOutSpring"`, `"EaseInOutSpring"` | | `playback/duration` | `Double` | `1.2` | The duration in seconds for which this block should be visible. | ## Pan Type An animation that pans the block across the view. This section describes the properties available for the **Pan Type** (`//ly.img.ubq/animation/pan`) block type. | Property | Type | Default | Description | | --------------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `animation/pan/direction` | `Float` | `0` | The movement direction of the animation in radians. | | `animation/pan/distance` | `Float` | `0.1` | The movement distance relative to the longer side of the page. | | `animation/pan/fade` | `Bool` | `true` | Whether an opacity fade animation should be applied during the pan animation. | | `animationEasing` | `Enum` | `"Linear"` | The easing function to apply to the animation., Possible values: `"Linear"`, `"EaseIn"`, `"EaseOut"`, `"EaseInOut"`, `"EaseInQuart"`, `"EaseOutQuart"`, `"EaseInOutQuart"`, `"EaseInQuint"`, `"EaseOutQuint"`, `"EaseInOutQuint"`, `"EaseInBack"`, `"EaseOutBack"`, `"EaseInOutBack"`, `"EaseInSpring"`, `"EaseOutSpring"`, `"EaseInOutSpring"` | | `playback/duration` | `Double` | `0.6` | The duration in seconds for which this block should be visible. | | `textAnimationOverlap` | `Float` | `0.35` | The overlap factor for text animations. | | `textAnimationWritingStyle` | `Enum` | `"Line"` | The writing style for text animations (e.g., by character, by word)., Possible values: `"Block"`, `"Line"`, `"Character"`, `"Word"` | ## Pop Type An animation that quickly scales the block up and down. This section describes the properties available for the **Pop Type** (`//ly.img.ubq/animation/pop`) block type. | Property | Type | Default | Description | | --------------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `playback/duration` | `Double` | `0.6` | The duration in seconds for which this block should be visible. | | `textAnimationOverlap` | `Float` | `0.35` | The overlap factor for text animations. | | `textAnimationWritingStyle` | `Enum` | `"Line"` | The writing style for text animations (e.g., by character, by word)., Possible values: `"Block"`, `"Line"`, `"Character"`, `"Word"` | ## Pulsating Loop Type A looping animation with a pulsating scale effect. This section describes the properties available for the **Pulsating Loop Type** (`//ly.img.ubq/animation/pulsating_loop`) block type. | Property | Type | Default | Description | | ------------------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `animation/pulsating_loop/intensity` | `Float` | `0` | Controls the intensity of the pulsating effect. A value of 0 results in a maximum scale of 1.25. A value of 1 results in a maximum scale of 2.5. | | `playback/duration` | `Double` | `0.6` | The duration in seconds for which this block should be visible. | ## Slide Type An animation that slides the block into or out of view. This section describes the properties available for the **Slide Type** (`//ly.img.ubq/animation/slide`) block type. | Property | Type | Default | Description | | --------------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `animation/slide/direction` | `Float` | `0` | The movement direction angle of the slide animation in radians. | | `animation/slide/fade` | `Bool` | `false` | Whether an opacity fade animation should be applied during the slide animation. | | `animationEasing` | `Enum` | `"Linear"` | The easing function to apply to the animation., Possible values: `"Linear"`, `"EaseIn"`, `"EaseOut"`, `"EaseInOut"`, `"EaseInQuart"`, `"EaseOutQuart"`, `"EaseInOutQuart"`, `"EaseInQuint"`, `"EaseOutQuint"`, `"EaseInOutQuint"`, `"EaseInBack"`, `"EaseOutBack"`, `"EaseInOutBack"`, `"EaseInSpring"`, `"EaseOutSpring"`, `"EaseInOutSpring"` | | `playback/duration` | `Double` | `0.6` | The duration in seconds for which this block should be visible. | | `textAnimationOverlap` | `Float` | `0.35` | The overlap factor for text animations. | | `textAnimationWritingStyle` | `Enum` | `"Line"` | The writing style for text animations (e.g., by character, by word)., Possible values: `"Block"`, `"Line"`, `"Character"`, `"Word"` | ## Spin Type An animation that rotates the block. This section describes the properties available for the **Spin Type** (`//ly.img.ubq/animation/spin`) block type. | Property | Type | Default | Description | | --------------------------- | -------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `animation/spin/direction` | `Enum` | `"Clockwise"` | The direction of the spin animation., Possible values: `"Clockwise"`, `"CounterClockwise"` | | `animation/spin/fade` | `Bool` | `true` | Whether an opacity fade animation should be applied during the spin animation. | | `animation/spin/intensity` | `Float` | `1` | How far the animation should spin the block. 1.0 is a full rotation (360°). | | `animationEasing` | `Enum` | `"Linear"` | The easing function to apply to the animation., Possible values: `"Linear"`, `"EaseIn"`, `"EaseOut"`, `"EaseInOut"`, `"EaseInQuart"`, `"EaseOutQuart"`, `"EaseInOutQuart"`, `"EaseInQuint"`, `"EaseOutQuint"`, `"EaseInOutQuint"`, `"EaseInBack"`, `"EaseOutBack"`, `"EaseInOutBack"`, `"EaseInSpring"`, `"EaseOutSpring"`, `"EaseInOutSpring"` | | `playback/duration` | `Double` | `0.6` | The duration in seconds for which this block should be visible. | | `textAnimationOverlap` | `Float` | `0.35` | The overlap factor for text animations. | | `textAnimationWritingStyle` | `Enum` | `"Line"` | The writing style for text animations (e.g., by character, by word)., Possible values: `"Block"`, `"Line"`, `"Character"`, `"Word"` | ## Spin Loop Type A looping animation that continuously rotates the block. This section describes the properties available for the **Spin Loop Type** (`//ly.img.ubq/animation/spin_loop`) block type. | Property | Type | Default | Description | | ------------------------------- | -------- | ------------- | ------------------------------------------------------------------------------------------ | | `animation/spin_loop/direction` | `Enum` | `"Clockwise"` | The direction of the spin animation., Possible values: `"Clockwise"`, `"CounterClockwise"` | | `playback/duration` | `Double` | `1.2` | The duration in seconds for which this block should be visible. | ## Spread Text Type A text animation where letters spread apart or come together. This section describes the properties available for the **Spread Text Type** (`//ly.img.ubq/animation/spread_text`) block type. | Property | Type | Default | Description | | --------------------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `animation/spread_text/fade` | `Bool` | `true` | Whether the text should fade in / out during the spread animation. | | `animation/spread_text/intensity` | `Float` | `0.5` | The intensity of the spread. | | `animationEasing` | `Enum` | `"Linear"` | The easing function to apply to the animation., Possible values: `"Linear"`, `"EaseIn"`, `"EaseOut"`, `"EaseInOut"`, `"EaseInQuart"`, `"EaseOutQuart"`, `"EaseInOutQuart"`, `"EaseInQuint"`, `"EaseOutQuint"`, `"EaseInOutQuint"`, `"EaseInBack"`, `"EaseOutBack"`, `"EaseInOutBack"`, `"EaseInSpring"`, `"EaseOutSpring"`, `"EaseInOutSpring"` | | `playback/duration` | `Double` | `0.6` | The duration in seconds for which this block should be visible. | ## Squeeze Loop Type A looping animation with a squeezing effect. This section describes the properties available for the **Squeeze Loop Type** (`//ly.img.ubq/animation/squeeze_loop`) block type. | Property | Type | Default | Description | | ------------------- | -------- | ------- | --------------------------------------------------------------- | | `playback/duration` | `Double` | `1.2` | The duration in seconds for which this block should be visible. | ## Sway Loop Type A looping animation with a swaying rotational motion. This section describes the properties available for the **Sway Loop Type** (`//ly.img.ubq/animation/sway_loop`) block type. | Property | Type | Default | Description | | ------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------- | | `animation/sway_loop/intensity` | `Float` | `1` | The intensity of the animation. Defines the maximum sway angle between 15° and 45°. | | `playback/duration` | `Double` | `1.2` | The duration in seconds for which this block should be visible. | ## Typewriter Text Type A text animation that reveals text as if it's being typed. This section describes the properties available for the **Typewriter Text Type** (`//ly.img.ubq/animation/typewriter_text`) block type. | Property | Type | Default | Description | | ---------------------------------------- | -------- | ------------- | ------------------------------------------------------------------------------------------------------------- | | `animation/typewriter_text/writingStyle` | `Enum` | `"Character"` | Whether the text should appear one character or one word at a time., Possible values: `"Character"`, `"Word"` | | `playback/duration` | `Double` | `0.6` | The duration in seconds for which this block should be visible. | ## Wipe Type An animation that reveals or hides the block with a wipe transition. This section describes the properties available for the **Wipe Type** (`//ly.img.ubq/animation/wipe`) block type. | Property | Type | Default | Description | | --------------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `animation/wipe/direction` | `Enum` | `"Right"` | The direction of the wipe animation., Possible values: `"Up"`, `"Right"`, `"Down"`, `"Left"` | | `animationEasing` | `Enum` | `"Linear"` | The easing function to apply to the animation., Possible values: `"Linear"`, `"EaseIn"`, `"EaseOut"`, `"EaseInOut"`, `"EaseInQuart"`, `"EaseOutQuart"`, `"EaseInOutQuart"`, `"EaseInQuint"`, `"EaseOutQuint"`, `"EaseInOutQuint"`, `"EaseInBack"`, `"EaseOutBack"`, `"EaseInOutBack"`, `"EaseInSpring"`, `"EaseOutSpring"`, `"EaseInOutSpring"` | | `playback/duration` | `Double` | `0.6` | The duration in seconds for which this block should be visible. | | `textAnimationOverlap` | `Float` | `0.35` | The overlap factor for text animations. | | `textAnimationWritingStyle` | `Enum` | `"Line"` | The writing style for text animations (e.g., by character, by word)., Possible values: `"Block"`, `"Line"`, `"Character"`, `"Word"` | ## Zoom Type An animation that scales the entire block. This section describes the properties available for the **Zoom Type** (`//ly.img.ubq/animation/zoom`) block type. | Property | Type | Default | Description | | --------------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `animation/zoom/fade` | `Bool` | `true` | Whether an opacity fade animation should be applied during the zoom animation. | | `animationEasing` | `Enum` | `"Linear"` | The easing function to apply to the animation., Possible values: `"Linear"`, `"EaseIn"`, `"EaseOut"`, `"EaseInOut"`, `"EaseInQuart"`, `"EaseOutQuart"`, `"EaseInOutQuart"`, `"EaseInQuint"`, `"EaseOutQuint"`, `"EaseInOutQuint"`, `"EaseInBack"`, `"EaseOutBack"`, `"EaseInOutBack"`, `"EaseInSpring"`, `"EaseOutSpring"`, `"EaseInOutSpring"` | | `playback/duration` | `Double` | `0.6` | The duration in seconds for which this block should be visible. | | `textAnimationOverlap` | `Float` | `0.35` | The overlap factor for text animations. | | `textAnimationWritingStyle` | `Enum` | `"Line"` | The writing style for text animations (e.g., by character, by word)., Possible values: `"Block"`, `"Line"`, `"Character"`, `"Word"` | --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "API Reference" description: "Find out how to use the API of the CESDK." platform: android url: "https://img.ly/docs/cesdk/android/api-reference/overview-8f24e1/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [API Reference](https://img.ly/docs/cesdk/android/api-reference/overview-8f24e1/) --- For Android, the following packages are available: - [ly.img:engine](`$\{props.platform.slug}/api-reference/engine/ly.img[58]engine/ly.img.engine`) - [ly.img:engine-camera](`$\{props.platform.slug}/api-reference/engine-camera/ly.img[58]engine-camera/ly.img.engine.camera`) - [ly.img:editor](`$\{props.platform.slug}/api-reference/editor/ly.img[58]editor/ly.img.editor`) - [ly.img:editor-core](`$\{props.platform.slug}/api-reference/editor-core`) - [ly.img:camera](`$\{props.platform.slug}/api-reference/camera/ly.img[58]camera/ly.img.camera`) - [ly.img:camera-core](`$\{props.platform.slug}/api-reference/camera-core/ly.img[58]camera-core/ly.img.camera.core`) --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Automate Workflows" description: "Automate repetitive editing tasks using CE.SDK’s headless APIs to generate assets at scale." platform: android url: "https://img.ly/docs/cesdk/android/automation-715209/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Automate Workflows](https://img.ly/docs/cesdk/android/automation-715209/) --- --- ## Related Pages - [Overview](https://img.ly/docs/cesdk/android/automation/overview-34d971/) - Automate repetitive editing tasks using CE.SDK’s headless APIs to generate assets at scale. - [Batch Processing](https://img.ly/docs/cesdk/android/automation/batch-processing-ab2d18/) - Documentation for Batch Processing - [Auto-Resize Blocks (Fill Parent & Percent Sizing) in Android (Kotlin)](https://img.ly/docs/cesdk/android/automation/auto-resize-4c2d58/) - Make blocks automatically fill their parent or resize proportionally using percent-based sizing in Android. Learn when to use absolute vs. percent sizing, and how to build predictable, responsive layouts for automation. - [Multiple Image Generation](https://img.ly/docs/cesdk/android/automation/multi-image-generation-2a0de4/) - Create many image variants from structured data by interpolating content into reusable design templates. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Auto-Resize Blocks (Fill Parent & Percent Sizing) in Android (Kotlin)" description: "Make blocks automatically fill their parent or resize proportionally using percent-based sizing in Android. Learn when to use absolute vs. percent sizing, and how to build predictable, responsive layouts for automation." platform: android url: "https://img.ly/docs/cesdk/android/automation/auto-resize-4c2d58/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Automate Workflows](https://img.ly/docs/cesdk/android/automation-715209/) > [Auto-Resize](https://img.ly/docs/cesdk/android/automation/auto-resize-4c2d58/) --- Sometimes you don't want to hard-code widths and heights. You want elements that *just fit*. You need a background that always covers the page, an overlay that scales with its container, or a column that takes up exactly half the parent. CE.SDK supports this through **size modes** and **percent-based sizing**, plus a one-liner convenience API that makes a block **fill its parent**. You set size modes per axis and use `0.0…1.0` values to express percentages; you can then query **computed dimensions** once layout stabilizes. ### Why It Matters for Automation When you generate designs in bulk, you can't manually correct layout differences for each image. **Percentage-based sizing** and `fillParent()` guarantee that every inserted asset or background automatically scales to the right dimensions, regardless of its original size or aspect ratio. This ensures **reliable layouts** and **predictable exports** in automated pipelines. ## What You'll Learn - Make a block **fill its parent** in one line. This is perfect for backgrounds and overlays. - Use **percent size modes** for responsive, predictable layouts. - Read **computed** width and height after layout to verify results. - Switch between **absolute** and **percent** sizing modes at runtime. - Build a **responsive background** that always fits the page. ## When You'll Use It - Full-bleed **background images** that cover the page. - **Responsive overlays** and watermarks that track the parent's size. - **Adaptive layouts** across different screen sizes and orientations. - **Automation workflows** that replace assets of different sizes without breaking layout consistency. ## Fill the Parent (One-Liner) The simplest way to auto-resize is to ask the engine to make a block fill its parent: ```kotlin import ly.img.engine.Engine // Make 'block' fill its parent container (resizes & positions). engine.block.fillParent(block) ``` CE.SDK resizes and positions the block, resets crop values if applicable, and switches content fill mode to `.cover` if needed to avoid invalid crops. **Good for:** Page backgrounds, edge-to-edge color panels, full-page masks. ## Percent-Based Sizing (Responsive Layouts) For finer control, switch size modes for width and height to `SizeMode.PERCENT`, then assign values from `0.0 ... 1.0`: ```kotlin import ly.img.engine.Engine import ly.img.engine.SizeMode // 100% width & height (fill parent) engine.block.setWidthMode(block, mode = SizeMode.PERCENT) engine.block.setHeightMode(block, mode = SizeMode.PERCENT) engine.block.setWidth(block, value = 1.0F) engine.block.setHeight(block, value = 1.0F) ``` In percent mode, `1.0` means 100% of the parent. Use: - `SizeMode.ABSOLUTE` for fixed-size elements. - `SizeMode.AUTO` when the content determines its own size. ## Partial Fill Examples ```kotlin import ly.img.engine.Engine import ly.img.engine.SizeMode // 50% width, 100% height (e.g., a left column) engine.block.setWidthMode(block, mode = SizeMode.PERCENT) engine.block.setHeightMode(block, mode = SizeMode.PERCENT) engine.block.setWidth(block, value = 0.5F) engine.block.setHeight(block, value = 1.0F) ``` Great for split layouts, sidebars, or variable-width panels. ## Reading Computed Dimensions After the engine completes a layout pass, you can read **computed** dimensions with the standard accessors: ```kotlin import ly.img.engine.Engine val width = engine.block.getWidth(block) val height = engine.block.getHeight(block) ``` These values are available **after** layout updates. If you query immediately after changes, you might see stale values. Use coroutines to yield or defer the read before querying. > **Note:** In Kotlin coroutines, using `yield()` or deferring the read to the next frame often suffices for demos. ## Switching Between Absolute & Percent You can toggle sizing modes at runtime to move between fixed and responsive layouts: ```kotlin import ly.img.engine.Engine import ly.img.engine.SizeMode // Fixed (absolute) sizing engine.block.setWidthMode(block, mode = SizeMode.ABSOLUTE) engine.block.setHeightMode(block, mode = SizeMode.ABSOLUTE) engine.block.setWidth(block, value = 400.0F) engine.block.setHeight(block, value = 300.0F) // Back to responsive sizing engine.block.setWidthMode(block, mode = SizeMode.PERCENT) engine.block.setHeightMode(block, mode = SizeMode.PERCENT) engine.block.setWidth(block, value = 0.75F) // 75% width engine.block.setHeight(block, value = 1.0F) // 100% height ``` Use **absolute** for fixed-size exports or print layouts, and **percent** for responsive layouts or template-based automation. ## Practical Example: Responsive Background Here's a common pattern. Create a background that always fills the page: ```kotlin import ly.img.engine.Color import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType import ly.img.engine.SizeMode // 1) Create a graphic block and set its fill val bg = engine.block.create(DesignBlockType.Graphic) val shape = engine.block.createShape(ShapeType.Rect) engine.block.setShape(bg, shape = shape) val solidColor = engine.block.createFill(FillType.Color) val rgbaGreen = Color.fromRGBA(r = 0.5F, g = 1.0F, b = 0.5F, a = 1.0F) engine.block.setColor(solidColor, property = "fill/color/value", color = rgbaGreen) engine.block.setFill(bg, fill = solidColor) // 2) Append to the page and send behind other content engine.block.appendChild(parent = page, child = bg) engine.block.sendToBack(bg) // 3) Either the one-liner: engine.block.fillParent(bg) // 4) Or, percent-based equivalent: engine.block.setWidthMode(bg, mode = SizeMode.PERCENT) engine.block.setHeightMode(bg, mode = SizeMode.PERCENT) engine.block.setWidth(bg, value = 1.0F) engine.block.setHeight(bg, value = 1.0F) ``` The percent-based alternative mirrors the behavior of `fillParent` if your content and crop are already valid. The `fillParent` method guarantees coverage and sets a safe fill mode automatically. ## Automation Example: Batch Image Replacement This automation scenario generates name tags: - Each tag has a dedicated container that: - Is called hero-frame. - Displays the person's photo. - The code prepares hero-frame **once** so it always fills its parent. - It replaces the image fill inside hero-frame during batch generation. - Layout stays stable regardless of the photo's size and aspect. ### Prepare Once ```kotlin import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType // One‑time setup when building the template/scene val heroFrame = engine.block.create(DesignBlockType.Graphic) val rect = engine.block.createShape(ShapeType.Rect) engine.block.setShape(heroFrame, shape = rect) // Give it a name for easy lookup in later steps / debugging engine.block.setString(heroFrame, property = "name", value = "hero-frame") // Attach an image fill now (can be a placeholder) val heroFrameImageFill = engine.block.createFill(FillType.Image) engine.block.setFill(heroFrame, fill = heroFrameImageFill) // Place it in the nametag layout once (e.g., inside a card group or page) engine.block.appendChild(parent = faceGroup, child = heroFrame) // Make the container auto‑resize to its parent so the photo always fits engine.block.fillParent(heroFrame) ``` ### Update During the Batch At a later time, when the batch runs, it: - Gets a reference to the `heroFrame` block - Calls a function to update the image fill during each pass. ```kotlin import ly.img.engine.Engine import ly.img.engine.FillType fun replaceHeroPhotoURL(engine: Engine, hero: Int, url: String) { try { // Try to get the current fill and swap the image on the same object val fill = engine.block.getFill(hero) engine.block.setString( fill, property = "fill/image/imageFileURI", value = url ) } catch (e: Exception) { // If no fill exists yet, create and attach one println("No fill found on hero-frame; creating new fill.") try { val newFill = engine.block.createFill(FillType.Image) engine.block.setString( newFill, property = "fill/image/imageFileURI", value = url ) engine.block.setFill(hero, fill = newFill) } catch (e: Exception) { println("Failed to attach new fill: ${e.message}") } } } ``` Because `heroFrame` used `fillParent`, every image conforms to its parent's size, ensuring layouts remain consistent. This approach is ideal for: - Product catalogs - User-generated templates - Any workflow where image dimensions vary widely.  In the preceding diagram, three input images are of **different sizes**. The engine **crops and resizes** them to fill the placeholder during the batch. ## Complete Example Here's a complete example demonstrating auto-resize in a template-based workflow: ```kotlin import android.content.Context import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.Color import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType import ly.img.engine.SizeMode fun autoResizeExample( context: Context, license: String, userId: String ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.autoresize") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) try { // Create scene and page val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) engine.block.setWidth(page, value = 1080F) engine.block.setHeight(page, value = 1920F) // Create a full-bleed background using fillParent val background = engine.block.create(DesignBlockType.Graphic) val bgShape = engine.block.createShape(ShapeType.Rect) engine.block.setShape(background, shape = bgShape) val bgFill = engine.block.createFill(FillType.Color) val bgColor = Color.fromRGBA(r = 0.2F, g = 0.4F, b = 0.8F, a = 1.0F) engine.block.setColor(bgFill, property = "fill/color/value", color = bgColor) engine.block.setFill(background, fill = bgFill) engine.block.appendChild(parent = page, child = background) engine.block.sendToBack(background) engine.block.fillParent(background) // Create a 50% width left column using percent sizing val leftColumn = engine.block.create(DesignBlockType.Graphic) val leftShape = engine.block.createShape(ShapeType.Rect) engine.block.setShape(leftColumn, shape = leftShape) val leftFill = engine.block.createFill(FillType.Color) val leftColor = Color.fromRGBA(r = 1.0F, g = 0.8F, b = 0.2F, a = 0.8F) engine.block.setColor(leftFill, property = "fill/color/value", color = leftColor) engine.block.setFill(leftColumn, fill = leftFill) engine.block.appendChild(parent = page, child = leftColumn) // Set to 50% width, 100% height engine.block.setWidthMode(leftColumn, mode = SizeMode.PERCENT) engine.block.setHeightMode(leftColumn, mode = SizeMode.PERCENT) engine.block.setWidth(leftColumn, value = 0.5F) engine.block.setHeight(leftColumn, value = 1.0F) engine.block.setPositionX(leftColumn, value = 0F) engine.block.setPositionY(leftColumn, value = 0F) // Create a 50% width right column val rightColumn = engine.block.create(DesignBlockType.Graphic) val rightShape = engine.block.createShape(ShapeType.Rect) engine.block.setShape(rightColumn, shape = rightShape) val rightFill = engine.block.createFill(FillType.Color) val rightColor = Color.fromRGBA(r = 0.2F, g = 1.0F, b = 0.4F, a = 0.8F) engine.block.setColor(rightFill, property = "fill/color/value", color = rightColor) engine.block.setFill(rightColumn, fill = rightFill) engine.block.appendChild(parent = page, child = rightColumn) // Set to 50% width, 100% height, positioned on the right engine.block.setWidthMode(rightColumn, mode = SizeMode.PERCENT) engine.block.setHeightMode(rightColumn, mode = SizeMode.PERCENT) engine.block.setWidth(rightColumn, value = 0.5F) engine.block.setHeight(rightColumn, value = 1.0F) engine.block.setPositionX(rightColumn, value = 540F) // 50% of 1080 engine.block.setPositionY(rightColumn, value = 0F) // Read computed dimensions val leftWidth = engine.block.getWidth(leftColumn) val leftHeight = engine.block.getHeight(leftColumn) val rightWidth = engine.block.getWidth(rightColumn) val rightHeight = engine.block.getHeight(rightColumn) println("Left column: ${leftWidth}x${leftHeight}") println("Right column: ${rightWidth}x${rightHeight}") // Switch left column to absolute sizing engine.block.setWidthMode(leftColumn, mode = SizeMode.ABSOLUTE) engine.block.setHeightMode(leftColumn, mode = SizeMode.ABSOLUTE) engine.block.setWidth(leftColumn, value = 400F) engine.block.setHeight(leftColumn, value = 800F) println("Left column after switching to absolute: ${engine.block.getWidth(leftColumn)}x${engine.block.getHeight(leftColumn)}") } finally { // Note: Don't stop the engine here if you want to keep using it // engine.stop() } } ``` ## Platform Notes & Limitations - **Computed dimensions are asynchronous.** Read them after a layout cycle. If you set percent sizing and immediately call `getWidth`, you may get the previous value. - **Groups vs. children.** Percent sizing relates a child to *its direct parent*. Ensure your block is appended where you expect before reading dimensions. - **Fills and crops.** `fillParent` may reset crop values and/or set fill mode to cover to avoid invalid states. ## Troubleshooting | Symptom | Likely Cause | Fix | |---|---|---| | Block doesn't resize with parent | Width/height modes aren't set to `SizeMode.PERCENT` | Set `setWidthMode(SizeMode.PERCENT)` / `setHeightMode(SizeMode.PERCENT)` and assign `0…1` values. | | Computed width/height are `0` or stale | Reading before layout settled | Defer reads; yield before `getWidth/Height`. | | Only one axis resizes | Only one axis set to `SizeMode.PERCENT` | Set both axes to `SizeMode.PERCENT` (or use `fillParent`). | | Unexpected crop after fill | `fillParent` adjusted crop/fill mode | Use percent sizing manually if you need to preserve a crop. | | Child ignores parent size | Wrong parent in hierarchy | Verify `appendChild` target and recheck computed dimensions after update. | ## Next Steps You can use auto-resize as you create compositions and make responsive designs. Here are some other guides to explore to deepen your understanding. - [Resize blocks (manual)](https://img.ly/docs/cesdk/android/edit-image/transform/resize-407242/) — control dimensions interactively. - [Batch Processing](https://img.ly/docs/cesdk/android/automation/batch-processing-ab2d18/) — automate design generation at scale. - [Multi-Image Generation](https://img.ly/docs/cesdk/android/automation/multi-image-generation-2a0de4/) — generate multiple variants from templates. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Batch Processing" description: "Documentation for Batch Processing" platform: android url: "https://img.ly/docs/cesdk/android/automation/batch-processing-ab2d18/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Automate Workflows](https://img.ly/docs/cesdk/android/automation-715209/) > [Batch Processing](https://img.ly/docs/cesdk/android/automation/batch-processing-ab2d18/) --- Batch processing lets your app automatically generate scores of assets from a single design template. For example, you might create 100 personalized posters or social posts from a JSON file of names and photos, without opening the editor for each one. CE.SDK's headless engine makes this possible entirely in Kotlin. This guide shows you how to do that in Kotlin for Android. You'll learn how to load a saved design, substitute text and images, and export each variation as an asset file. The same techniques apply to more complex outputs like PDFs or videos. ## What You'll Learn - How to start CE.SDK's **headless engine** without a UI editor. - How to **load a template** from an archive or URL and attach it to a new scene. - How to **replace variables and images** for each record in your data. - How to **export** each generated design as a common format like PNG, JPEG or PDF. ## When You'll Use This Headless batch generation is ideal for tasks that need automation, not user interaction. Use it to mass-produce: - Branded materials - Social media graphics - Dynamic thumbnails - Personalized certificates - Product cards at scale Because you're not displaying the editor UI, it works well for background processing and server-side workflows. ## Headless Engine At the center of CE.SDK is the `Engine`, a lightweight rendering system you can use without the prebuilt editors. It can run in the background, respond to coroutines, and render scenes directly to image data. ```kotlin import ly.img.engine.Engine import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch fun startHeadlessEngine(license: String, userId: String) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.batch") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) } ``` For automation, you'll typically create one `Engine` instance for the full batch run. - **On mobile**, a single-engine, sequential approach is safest. - **On more powerful hardware or servers**, you can explore modest parallelism, as each instance of `Engine` is independent. ## Loading Templates The template defines the design you'll use for all generated images. You can: 1. Create a template in the CE.SDK editor. 2. Save it as an archive or scene file. 3. Bundle that file with your app in the assets folder or host it at a URL for the batch to use. ```kotlin import android.net.Uri val templateUri = Uri.parse("file:///android_asset/templates/badge_template.scene") ``` **Archives** are self-contained ZIP files that include: - Your layout - Text - All linked assets They're ideal for predictable batch exports. You can also save templates as scene JSON files, but in those cases, the URI of every asset must resolve correctly at runtime. Once loaded, always validate the structure before using it. ```kotlin import android.net.Uri import ly.img.engine.DesignBlock import ly.img.engine.Engine suspend fun loadTemplate(engine: Engine, uri: Uri): DesignBlock { val scene = engine.scene.load(sceneUri = uri) return scene } ``` This ensures that missing or corrupt templates don't interrupt your batch. `engine.scene.load()` loads the template and returns the scene root block, which you can then render, modify, and export. ## Supplying Data from JSON Every batch needs a list of records. Each record holds the values to apply to the template. A common pattern is: 1. Store them as a JSON array. 2. Decode them during the batch. A record might have these properties: ```kotlin import kotlinx.serialization.Serializable @Serializable data class Record( val id: String, val variables: Map, val outputFileName: String, val images: Map? = null // optional blockName → image URI ) ``` Then decode any JSON using kotlinx.serialization or Gson: ```kotlin import android.content.Context import kotlinx.serialization.json.Json import kotlinx.serialization.decodeFromString import java.io.IOException fun loadRecords(context: Context): List { return try { val jsonString = context.assets.open("records.json") .bufferedReader() .use { it.readText() } Json.decodeFromString>(jsonString) } catch (e: IOException) { emptyList() } } ``` Example `records.json`: ```json [ { "id": "001", "variables": { "name": "Ruth", "tagline": "Ship great apps" }, "outputFileName": "badge-ruth" }, { "id": "002", "variables": { "name": "Chris", "tagline": "Move fast, polish later" }, "outputFileName": "badge-chris" } ] ``` In a production environment, you'll load data from an API or database instead of bundled assets. If your dataset is large, consider streaming it in chunks instead of loading everything at once. ## Templates and Variables Templates often include placeholders, or variables, that you can update with real data at runtime. In CE.SDK (Android), template variables follow a key/value pattern and are **always stored as strings**. Your app can convert them into types like numbers or colors when needed. For text blocks, CE.SDK automatically matches placeholders in the template with variable names. Displaying `\{\{username\}\}` as the text in a text box becomes the variable `username` you can replace with a person's name before exporting. ```kotlin import ly.img.engine.Engine // All variables are set via (key:String, value:String) engine.variable.set(key = "name", value = "Chris") // text engine.variable.set(key = "price", value = "9.99") // number encoded as string engine.variable.set(key = "brandColor", value = "#FFD60A") // color as hex string engine.variable.set(key = "isFeatured", value = "true") // boolean as "true" / "false" engine.variable.set(key = "imageURL", value = "https://example.com/image.jpg") // URL as string ``` Discover the available variable keys at runtime to validate a template using: ```kotlin val keys = engine.variable.findAll() // assert or log missing keys before a long batch run ``` ## Applying Data to the Template Once the engine loads the template, you can fill in variables. These correspond to the placeholders you set in your CE.SDK scene, like `\{\{name\}\}` or `\{\{tagline\}\}`. ```kotlin import ly.img.engine.Engine fun applyVariables(engine: Engine, values: Map) { for ((key, value) in values) { engine.variable.set(key = key, value = value) } } ``` You can also swap out placeholder images at runtime. The simplest method is to find the block by its name and update its image fill. ```kotlin import ly.img.engine.Engine fun replaceNamedImage(engine: Engine, blockName: String, imageUri: String) { val matches = engine.block.findByName(blockName) if (matches.isNotEmpty()) { val imageBlock = matches.first() val fill = engine.block.getFill(imageBlock) engine.block.setString(fill, property = "fill/image/imageFileURI", value = imageUri) engine.block.setFill(imageBlock, fill = fill) engine.block.setKind(imageBlock, kind = "image") } } ``` This snippet looks up a block named `productImage` and replaces its image fill with the URI of the new image. > **Note:** Using block names keeps your automation readable and less fragile than referencing IDs. ## Create Thumbnails You can generate previews by exporting a scaled version of each result: ```kotlin import android.content.Context import kotlinx.coroutines.withContext import kotlinx.coroutines.Dispatchers import ly.img.engine.Engine import ly.img.engine.ExportOptions import ly.img.engine.MimeType import java.io.File suspend fun exportThumbnail( engine: Engine, context: Context, fileName: String, scale: Float = 0.25f ): File { val scene = requireNotNull(engine.scene.get()) { "No scene loaded" } val width = engine.block.getFrameWidth(scene) * scale val height = engine.block.getFrameHeight(scene) * scale val options = ExportOptions( jpegQuality = 0.7f, targetWidth = width, targetHeight = height ) val exportData = engine.block.export(scene, mimeType = MimeType.JPEG, options = options) val outputDir = context.filesDir val thumbFile = File(outputDir, "thumb_$fileName.jpg") withContext(Dispatchers.IO) { thumbFile.outputStream().channel.use { channel -> channel.write(exportData) } } return thumbFile } ``` ## Exporting to Multiple Formats Exports can target different output types. Just switch the mime type you pass: ```kotlin import ly.img.engine.ExportOptions import ly.img.engine.MimeType val pngData = engine.block.export(scene, mimeType = MimeType.PNG, options = ExportOptions(targetHeight = 1080f)) val pdfData = engine.block.export(scene, mimeType = MimeType.PDF) ``` |Format|MimeType|Typical Use| |---|---|---| |PNG|`MimeType.PNG`|Lossless images with transparency| |JPEG|`MimeType.JPEG`|Photos and smaller files| |PDF|`MimeType.PDF`|Printable designs| |MP4|`MimeType.MP4`|Animated or timed templates| Use an `ExportOptions` instance to tune output quality, size and other properties of the export. You can get the details in the [Export](https://img.ly/docs/cesdk/android/export-save-publish/export-82f968/) guides. If you need multiple formats at once, run several export calls back-to-back using the same engine and scene. ## Managing Memory and Resources Each export involves GPU textures, image buffers, and temporary files. To keep your app responsive: - Reuse a single engine for sequential jobs. - Clean up temporary directories between batches. - Call `engine.stop()` when completely done to free resources. ## Performance Tuning Checklist - Use JPEG quality 0.8–0.9 to balance file size and speed. - Keep templates simple. Avoid unnecessary effects or large images. - Chunk data into smaller groups for large datasets. - Limit concurrency to 2–3 parallel tasks if attempting parallel processing. - Profile on the lowest device you support. ## Error Handling and Retries Batch jobs can fail for network hiccups or invalid data. Use Kotlin's try/catch blocks to retry a few times before giving up. ```kotlin import kotlinx.coroutines.delay suspend fun processRecordWithRetry(record: Record, maxAttempts: Int = 3) { var attempts = 0 while (attempts < maxAttempts) { try { exportRecord(record) break } catch (e: Exception) { attempts++ if (attempts >= maxAttempts) { throw e } delay((attempts * 500L)) // exponential backoff } } } ``` You can also log each attempt for easier debugging. ## Logging and Monitoring Progress Adding logging helps track how long each export takes: ```kotlin import android.util.Log const val TAG = "BatchProcessing" Log.i(TAG, "Starting batch processing for ${records.size} records") records.forEachIndexed { index, record -> val startTime = System.currentTimeMillis() try { processRecord(record) val duration = System.currentTimeMillis() - startTime Log.i(TAG, "Exported ${record.outputFileName} in ${duration}ms [${index + 1}/${records.size}]") } catch (e: Exception) { Log.e(TAG, "Failed to export ${record.outputFileName}", e) } } ``` Wrap your entire run in timestamps to measure throughput and display progress in your UI. ## Batch Workflow Batch processing isn't limited to mobile apps. The same logic can run on backends or web services using CE.SDK for Web or Node. If your workload scales beyond device limits, consider: 1. Migrating automation to a server workflow. 2. Sending results back to the app. An example batch process, below, calls `processRecord()` for each record in the dataset. The record is processed by: 1. Loading the template 2. Setting variables 3. Replacing images 4. Exporting the result ```kotlin import android.content.Context import android.net.Uri import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import ly.img.engine.DesignBlock import ly.img.engine.Engine import ly.img.engine.ExportOptions import ly.img.engine.MimeType import java.io.File suspend fun processRecord( engine: Engine, context: Context, record: Record, templateUri: Uri ): File { // Load the template val scene = engine.scene.load(sceneUri = templateUri) // Apply variables applyVariables(engine, record.variables) // Replace images if specified record.images?.forEach { (blockName, imageUri) -> replaceNamedImage(engine, blockName, imageUri) } // Export the result val exportData = engine.block.export( scene, mimeType = MimeType.JPEG, options = ExportOptions(jpegQuality = 0.9f) ) // Save to file val outputDir = context.filesDir val outputFile = File(outputDir, "${record.outputFileName}.jpg") withContext(Dispatchers.IO) { outputFile.outputStream().channel.use { channel -> channel.write(exportData) } } return outputFile } suspend fun runBatch( context: Context, license: String, userId: String, records: List ) { val engine = Engine.getInstance(id = "ly.img.engine.batch") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val templateUri = Uri.parse("file:///android_asset/templates/badge_template.scene") for (record in records) { try { processRecord(engine, context, record, templateUri) } catch (e: Exception) { Log.e("Batch", "Failed to process ${record.id}", e) } } engine.stop() } ``` Use modest parallelism for faster processing on capable devices: ```kotlin import kotlinx.coroutines.async import kotlinx.coroutines.awaitAll import kotlinx.coroutines.coroutineScope suspend fun runBatchParallel( context: Context, license: String, userId: String, records: List, maxConcurrent: Int = 3 ) = coroutineScope { val templateUri = Uri.parse("file:///android_asset/templates/badge_template.scene") records.chunked(maxConcurrent).forEach { chunk -> chunk.map { record -> async(Dispatchers.Main) { // Create a separate engine instance for each parallel task val engine = Engine.getInstance(id = "ly.img.engine.batch.${record.id}") try { engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) processRecord(engine, context, record, templateUri) } finally { engine.stop() } } }.awaitAll() } } ``` ## Troubleshooting **❌ Your exports appear blank**: - Verify that the scene loaded successfully with `engine.scene.get()`. - Check that all asset URIs are reachable (network or local). - Ensure the page has content before exporting. **❌ Text variables don't update**: - Confirm variable names match the template's tokens exactly (case-sensitive). - Use `engine.variable.findAll()` to see what variables exist in the template. - Verify that `engine.variable.set()` is called with the correct key. **❌ Your image placeholder doesn't update**: - Ensure you're setting the image URI on an image fill. - Verify that the fill is applied to the target block with `engine.block.setFill()`. - Check that the URI is valid and reachable (add INTERNET permission for remote URLs). - Confirm the block's kind is set to `"image"` after applying the new fill. **❌ The batch job becomes sluggish**: - Performance issues are rare in sequential runs, but if you attempt parallel exports: - Limit concurrency to a few simultaneous tasks (2-3 on mobile). - Ensure each engine instance is properly stopped after use. - Monitor memory usage and reduce batch size if needed. **❌ Network errors when loading remote templates or images**: - Add `` to AndroidManifest.xml. - Verify URLs are using HTTPS. - Test URLs in a browser to confirm they're accessible. ## Next Steps Continue learning about automation and export workflows with these related guides: - Use Templates to [generate content](https://img.ly/docs/cesdk/android/use-templates/generate-334e15/). - [Text Variables](https://img.ly/docs/cesdk/android/create-templates/add-dynamic-content/text-variables-7ecb50/) & [Placeholders](https://img.ly/docs/cesdk/android/create-templates/add-dynamic-content/placeholders-d9ba8a/) for dynamic content. - [Export assets](https://img.ly/docs/cesdk/android/export-save-publish/export-82f968/) in different formats. - Generate [multiple assets](https://img.ly/docs/cesdk/android/automation/multi-image-generation-2a0de4/) from a single record. - Create [Preview Thumbnails](https://img.ly/docs/cesdk/android/export-save-publish/create-thumbnail-749be1/). These guides expand on how to prepare templates, manage variable data, and optimize export pipelines for larger-scale automation. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Multiple Image Generation" description: "Create many image variants from structured data by interpolating content into reusable design templates." platform: android url: "https://img.ly/docs/cesdk/android/automation/multi-image-generation-2a0de4/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Automate Workflows](https://img.ly/docs/cesdk/android/automation-715209/) > [Multiple Image Generation](https://img.ly/docs/cesdk/android/automation/multi-image-generation-2a0de4/) --- Generate image variants, such as square, portrait, or landscape layouts, from a single data record using the CreativeEditor SDK's Engine API. This pattern lets you populate templates programmatically with text, images, and colors to create consistent, on-brand designs across all formats. ## What You'll Learn - Load multiple templates into CE.SDK and populate them with structured data. - Replace text and image placeholders dynamically using variables and named blocks. - Apply consistent brand color themes across scenes. - Export each variant as PNG, JPEG, or PDF. - Build efficient workflows for generating multiple format variations. ## When to Use It Use multi-image generation when a single record (like a restaurant listing or product) needs to produce multiple layout variants. For larger datasets with many records generating many images, refer to the [Batch Processing](https://img.ly/docs/cesdk/android/automation/batch-processing-ab2d18/) guide. ## Core Concepts **Templates and Instances**: Templates define reusable layout and placeholders. An instance is a populated version with specific data. Use `engine.scene.saveToString()` to serialize a template and `engine.scene.load(scene =)` to load it for processing. **Variables for Dynamic Text**: Define variables in your templates for fields like `RestaurantName` or `Rating`. Set them at runtime with `engine.variable.set(key =, value =)`. Use `engine.variable.findAll()` to verify available variable names. **Named Blocks for Image Replacement**: Name your image placeholders (for example, `RestaurantImage`, `Logo`). Retrieve them with `engine.block.findByName()`, access the fill with `getFill()`, then update its source URI using `setString(..., property = "fill/image/imageFileURI")`. Always reset the crop after replacing an image fill for proper framing. **Brand and Conditional Styling**: Use predictable block naming for elements such as star ratings. Apply color changes programmatically with `setColor` to visualize rating or brand status. **Sequential Template Processing**: Process each variant one at a time to reduce memory pressure and simplify export tracking. ## Prerequisites - CE.SDK for Android integrated through Gradle. - A valid license key. - Templates saved as `.scene` files in assets or available via URLs. - Template variables and named blocks prepared for population. ## Initialize the Engine ```kotlin import ly.img.engine.Engine import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch fun makeEngine(license: String, userId: String) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.multiimage") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) engine.addDefaultAssetSources() } ``` ## Define Your Data Model Your data model can use proper typing for variables. When you insert values into the templates, you will often need to convert them to strings. ```kotlin import java.util.UUID data class Restaurant( val id: UUID = UUID.randomUUID(), val name: String, val rating: Double, val reviewCount: Int, val imageURL: String, val logoURL: String, val brandPrimary: String, val brandSecondary: String ) ``` This model provides a data record for the example code below. ## Populate Templates and Export Variants Use one template per format such as: - square - portrait - landscape Populate the templates sequentially. ```kotlin import android.content.Context import android.net.Uri import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.MimeType import java.io.File suspend fun generateVariants( engine: Engine, context: Context, restaurant: Restaurant ): List { val templates = listOf( "restaurant_square.scene", "restaurant_portrait.scene", "restaurant_landscape.scene" ) val results = mutableListOf() for (template in templates) { val templateUri = Uri.parse("file:///android_asset/templates/$template") val scene = engine.scene.load(sceneUri = templateUri) // Set text variables engine.variable.set(key = "RestaurantName", value = restaurant.name) engine.variable.set(key = "Rating", value = String.format("%.1f ★", restaurant.rating)) engine.variable.set(key = "ReviewCount", value = "${restaurant.reviewCount}") // Replace images replaceImage(engine, name = "RestaurantImage", uri = restaurant.imageURL) replaceImage(engine, name = "Logo", uri = restaurant.logoURL) // Apply brand theme applyBrandTheme( engine = engine, primary = parseColor(restaurant.brandPrimary), secondary = parseColor(restaurant.brandSecondary) ) // Export variant val output = exportJPEG(engine, context, outputName(restaurant, template)) results.add(output) } return results } fun outputName(restaurant: Restaurant, template: String): String { val format = template.substringAfter("restaurant_").substringBefore(".scene") return "${restaurant.name.replace(" ", "_")}_$format" } ``` **Helper Functions**: The preceding code example uses some helper functions. These aren't part of the CE.SDK. Possible implementations of the functions follow. ```kotlin import android.content.Context import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import ly.img.engine.Color import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.MimeType import java.io.File fun replaceImage(engine: Engine, name: String, uri: String) { val matches = engine.block.findByName(name) if (matches.isNotEmpty()) { val block = matches.first() val fill = engine.block.getFill(block) engine.block.setString(fill, property = "fill/image/imageFileURI", value = uri) engine.block.resetCrop(block) } } fun applyBrandTheme(engine: Engine, primary: Color, secondary: Color) { val allBlocks = engine.block.findAll() for (block in allBlocks) { when (engine.block.getType(block)) { "//ly.img.ubq/text" -> { engine.block.setTextColor(block, color = primary) } "//ly.img.ubq/graphic" -> { runCatching { val fill = engine.block.getFill(block) engine.block.setColor(fill, property = "fill/color/value", color = secondary) } } } } } suspend fun exportJPEG(engine: Engine, context: Context, name: String): File { val page = engine.block.findByType(DesignBlockType.Page).firstOrNull() ?: throw IllegalStateException("No page found") val data = engine.block.export(page, mimeType = MimeType.JPEG) val dir = context.filesDir val file = File(dir, "$name.jpg") withContext(Dispatchers.IO) { file.outputStream().channel.use { channel -> channel.write(data) } } return file } ``` ## Color Utility Add this helper to convert hex strings into CE.SDK `Color` values. ```kotlin import ly.img.engine.Color fun parseColor(hex: String): Color { var hexString = hex.trim().removePrefix("#") // Add alpha if missing if (hexString.length == 6) { hexString += "FF" } val hexValue = hexString.toLongOrNull(16) ?: 0L val r = ((hexValue and 0xFF000000) shr 24).toFloat() / 255f val g = ((hexValue and 0x00FF0000) shr 16).toFloat() / 255f val b = ((hexValue and 0x0000FF00) shr 8).toFloat() / 255f val a = (hexValue and 0x000000FF).toFloat() / 255f return Color(r = r, g = g, b = b, a = a) } ``` ## Preview the Generated Variants Use Jetpack Compose to display and share generated images. ```kotlin import androidx.compose.foundation.Image import androidx.compose.foundation.clickable import androidx.compose.foundation.layout.* import androidx.compose.foundation.lazy.grid.GridCells import androidx.compose.foundation.lazy.grid.LazyVerticalGrid import androidx.compose.foundation.lazy.grid.items import androidx.compose.foundation.shape.RoundedCornerShape import androidx.compose.material3.Card import androidx.compose.runtime.* import androidx.compose.ui.Modifier import androidx.compose.ui.draw.shadow import androidx.compose.ui.layout.ContentScale import androidx.compose.ui.unit.dp import coil.compose.rememberAsyncImagePainter import java.io.File @Composable fun VariantsGrid(files: List) { var selectedFile by remember { mutableStateOf(null) } LazyVerticalGrid( columns = GridCells.Adaptive(minSize = 160.dp), contentPadding = PaddingValues(12.dp), horizontalArrangement = Arrangement.spacedBy(12.dp), verticalArrangement = Arrangement.spacedBy(12.dp) ) { items(files) { file -> Card( modifier = Modifier .aspectRatio(1f) .shadow(elevation = 2.dp, shape = RoundedCornerShape(10.dp)) .clickable { selectedFile = file }, shape = RoundedCornerShape(10.dp) ) { Image( painter = rememberAsyncImagePainter(file), contentDescription = file.name, contentScale = ContentScale.Crop, modifier = Modifier.fillMaxSize() ) } } } // Handle share dialog for selectedFile if needed } ``` ## Advanced Use Cases **Conditional Content**: Show or hide elements based on data values—for example, color stars according to the rating. ```kotlin import ly.img.engine.Color import ly.img.engine.Engine fun colorStars(engine: Engine, rating: Int, baseName: String = "Rating") { for (index in 1..5) { val starBlocks = engine.block.findByName("$baseName$index") if (starBlocks.isEmpty()) continue val star = starBlocks.first() runCatching { val fill = engine.block.getFill(star) val color = if (index <= rating) { parseColor("#FFD60A") } else { parseColor("#CCCCCC") } engine.block.setColor(fill, property = "fill/color/value", color = color) } } } ``` **Custom Assets**: Add your own logos or fonts by registering a custom asset source. See the [Custom Asset Sources](https://img.ly/docs/cesdk/android/import-media/asset-library-65d6c4/) guide for setup examples. **Adopter Mode Editing**: Allow users to open the generated design in the editor UI for minor edits. Serialize the populated scene with `engine.scene.saveToString()` and load it into the Design Editor configured for [restricted content](https://img.ly/docs/cesdk/android/create-templates/lock-131489/) editing. ## Troubleshooting **❌ Variables not updating**: - Verify variable names in both template and code using `engine.variable.findAll()`. - Variable names are case-sensitive. - Ensure `engine.variable.set()` is called with the correct key. **❌ Images missing**: - Confirm local path or remote URL points to a valid image. - For remote images, add `` to AndroidManifest.xml. - Verify CORS settings for remote images. **❌ Colors incorrect**: - Check block type before applying color with `engine.block.getType()`. - Ensure color values are in range 0-1 (not 0-255). - Use `runCatching` to handle blocks that don't support fills. **❌ Memory spikes**: - Process templates sequentially, not in parallel. - Call `engine.stop()` when completely done. - Clean up temporary files after export. **❌ Export size unexpected**: - Confirm consistent page dimensions across templates. - Verify `engine.block.getFrameWidth()` and `engine.block.getFrameHeight()` values. - Check template design settings. **Debugging Tips**: - Print variable names using `engine.variable.findAll()` - Log block names with `engine.block.getName(id)` - Test with one minimal template before expanding - Use Android Logcat to track processing flow ## Next Steps Multi-image generation is one way to automate your workflow. Some other ways the CE.SDK can automate are in these guides: - [Batch Processing](https://img.ly/docs/cesdk/android/automation/batch-processing-ab2d18/) lets you process many data records at once. - Adapt layouts across aspect ratios using [auto resize](https://img.ly/docs/cesdk/android/automation/auto-resize-4c2d58/). - Explore [export formats](https://img.ly/docs/cesdk/android/export-save-publish/export-82f968/) and settings. - Add branded fonts, logos, and graphics by creating [custom asset sources](https://img.ly/docs/cesdk/android/import-media/overview-84bb23/). --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Overview" description: "Automate repetitive editing tasks using CE.SDK’s headless APIs to generate assets at scale." platform: android url: "https://img.ly/docs/cesdk/android/automation/overview-34d971/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Automate Workflows](https://img.ly/docs/cesdk/android/automation-715209/) > [Overview](https://img.ly/docs/cesdk/android/automation/overview-34d971/) --- Workflow automation with CreativeEditor SDK (CE.SDK) enables you to programmatically generate, manipulate, and export creative assets—at scale. Whether you're creating thousands of localized ads, preparing platform-specific variants of a campaign, or populating print-ready templates with dynamic data, CE.SDK provides a flexible foundation for automation. You can run automation entirely on the client, integrate it with your backend, or build hybrid “human-in-the-loop” workflows where users interact with partially automated scenes before export. The automation engine supports static pipelines, making it suitable for a wide range of publishing, e-commerce, and marketing applications. Video support will follow soon. [Explore Demos](https://img.ly/showcases/cesdk?tags=android) [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) ### Output Formats --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Bundle Size" description: "Understand CE.SDK’s engine and editor bundle sizes and how they affect your mobile app’s download footprint." platform: android url: "https://img.ly/docs/cesdk/android/bundle-size-df9210/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Compatibility & Security](https://img.ly/docs/cesdk/android/compatibility-fef719/) > [Bundle Size](https://img.ly/docs/cesdk/android/bundle-size-df9210/) --- ## Engine Download Size When included in your app, the download size of the engine is different depending on the architecture: - arm64-v8a ~ 14.9MB - armeabi-v7a ~ 13.7MB - x86\_64 ~ 14.9MB - x86 ~ 14.9MB This means that the download size from Play Store will be increased by the amount mentioned above. ## Mobile Editor Download Size In order to use the mobile editor, you either have to use the gradle dependency, or directly copy the solutions from our [repository](https://github.com/imgly/cesdk-android-examples). No matter which approach you choose, you can expect the download size of the mobile editor to be around the size of the engine plus a few additional megabytes. The precise size may depend on the bundled assets (scene files, images, stickers), however, with the default resources you can expect it to be around **3 MB** plus the size of the engine. Note that this does not include the size of the Jetpack Compose library. Also note that this is measured without R8 optimizations. Enabling it in your project will shrink it further. For more information on R8, follow this [link](https://developer.android.com/build/shrink-code). ## Including as a Dynamic Feature If you want to include the engine or the mobile editor via dependency as a dynamic feature, create an android module, add the dependency of the engine/mobile editor to that module and make that module dynamic. Here is the [link](https://developer.android.com/guide/playcore/feature-delivery) on how to create a dynamic module and load it. If you want to include the mobile editor by copying our repository, you do not need to create an extra module. Simply declare the `:editor` module as dynamic when you copy that module to your project. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Colors" description: "Manage color usage in your designs, from applying brand palettes to handling print and screen formats." platform: android url: "https://img.ly/docs/cesdk/android/colors-a9b79c/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Colors](https://img.ly/docs/cesdk/android/colors-a9b79c/) --- --- ## Related Pages - [Overview](https://img.ly/docs/cesdk/android/colors/overview-16a177/) - Manage color usage in your designs, from applying brand palettes to handling print and screen formats. - [Basics](https://img.ly/docs/cesdk/android/colors/basics-307115/) - Learn how color is handled in CE.SDK and how to apply, modify, and manage it across elements. - [For Print](https://img.ly/docs/cesdk/android/colors/for-print-59bc05/) - Use print-ready color models and settings for professional-quality, production-ready exports. - [For Screen](https://img.ly/docs/cesdk/android/colors/for-screen-1911f8/) - Documentation for For Screen - [Apply Colors](https://img.ly/docs/cesdk/android/colors/apply-2211e3/) - Apply solid colors to shapes, backgrounds, and other design elements. - [Create a Color Palette](https://img.ly/docs/cesdk/android/colors/create-color-palette-7012e0/) - Build reusable color palettes to maintain consistency and streamline user choices. - [Color Conversion](https://img.ly/docs/cesdk/android/colors/conversion-bcd82b/) - Convert between RGB, CMYK, and other color formats based on your project’s output requirements. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Apply Colors" description: "Apply solid colors to shapes, backgrounds, and other design elements." platform: android url: "https://img.ly/docs/cesdk/android/colors/apply-2211e3/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Colors](https://img.ly/docs/cesdk/android/colors-a9b79c/) > [Apply Color](https://img.ly/docs/cesdk/android/colors/apply-2211e3/) --- ```kotlin file=@cesdk_android_examples/engine-guides-colors/Colors.kt reference-only import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.Color import ly.img.engine.ColorSpace import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun colors( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setPositionX(block, value = 350F) engine.block.setPositionY(block, value = 400F) engine.block.setWidth(block, value = 100F) engine.block.setHeight(block, value = 100F) val fill = engine.block.createFill(FillType.Color) engine.block.setFill(block, fill = fill) val rgbaBlue = Color.fromRGBA(r = 0F, g = 0F, b = 1F, a = 1F) val cmykRed = Color.fromCMYK(c = 0F, m = 1F, y = 1F, k = 0F, tint = 1F) val cmykPartialRed = Color.fromCMYK(c = 0F, m = 1F, y = 1F, k = 0F, tint = 0.5F) engine.editor.setSpotColor( name = "Pink-Flamingo", Color.fromRGBA(r = 0.988F, g = 0.455F, b = 0.992F), ) engine.editor.setSpotColor(name = "Yellow", Color.fromCMYK(c = 0F, m = 0F, y = 1F, k = 0F)) val spotPinkFlamingo = Color.fromSpotColor( name = "Pink-Flamingo", tint = 1F, externalReference = "Crayola", ) val spotPartialYellow = Color.fromSpotColor(name = "Yellow", tint = 0.3F) engine.block.setColor(fill, property = "fill/color/value", value = rgbaBlue) engine.block.setColor(fill, property = "fill/color/value", value = cmykRed) engine.block.setColor(block, property = "stroke/color", value = cmykPartialRed) engine.block.setColor(fill, property = "fill/color/value", value = spotPinkFlamingo) engine.block.setColor(block, property = "dropShadow/color", value = spotPartialYellow) val cmykBlueConverted = engine.editor.convertColorToColorSpace( rgbaBlue, colorSpace = ColorSpace.CMYK, ) val rgbaPinkFlamingoConverted = engine.editor.convertColorToColorSpace( spotPinkFlamingo, colorSpace = ColorSpace.SRGB, ) engine.editor.findAllSpotColors() // ["Crayola-Pink-Flamingo", "Yellow"] engine.editor.setSpotColor("Yellow", Color.fromCMYK(c = 0.2F, m = 0F, y = 1F, k = 0F)) engine.editor.removeSpotColor("Yellow") engine.stop() } ``` ## Setup the scene We first create a new scene with a graphic block that has color fill. ```kotlin highlight-setup val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setPositionX(block, value = 350F) engine.block.setPositionY(block, value = 400F) engine.block.setWidth(block, value = 100F) engine.block.setHeight(block, value = 100F) val fill = engine.block.createFill(FillType.Color) engine.block.setFill(block, fill = fill) ``` ## Create colors Here we instantiate a few colors with RGB and CMYK color spaces. We also define two spot colors, one with an RGB approximation and another with a CMYK approximation. Note that a spot colors can have both color space approximations. ```kotlin highlight-create-colors val rgbaBlue = Color.fromRGBA(r = 0F, g = 0F, b = 1F, a = 1F) val cmykRed = Color.fromCMYK(c = 0F, m = 1F, y = 1F, k = 0F, tint = 1F) val cmykPartialRed = Color.fromCMYK(c = 0F, m = 1F, y = 1F, k = 0F, tint = 0.5F) engine.editor.setSpotColor( name = "Pink-Flamingo", Color.fromRGBA(r = 0.988F, g = 0.455F, b = 0.992F), ) engine.editor.setSpotColor(name = "Yellow", Color.fromCMYK(c = 0F, m = 0F, y = 1F, k = 0F)) val spotPinkFlamingo = Color.fromSpotColor( name = "Pink-Flamingo", tint = 1F, externalReference = "Crayola", ) val spotPartialYellow = Color.fromSpotColor(name = "Yellow", tint = 0.3F) ``` ## Applying colors to a block We can use the defined colors to modify certain properties of a fill or properties of a shape. Here we apply it to `'fill/color/value'`, `'stroke/color'` and `'dropShadow/color'`. ```kotlin highlight-apply-colors engine.block.setColor(fill, property = "fill/color/value", value = rgbaBlue) engine.block.setColor(fill, property = "fill/color/value", value = cmykRed) engine.block.setColor(block, property = "stroke/color", value = cmykPartialRed) engine.block.setColor(fill, property = "fill/color/value", value = spotPinkFlamingo) engine.block.setColor(block, property = "dropShadow/color", value = spotPartialYellow) ``` ## Converting colors Using the utility function `convertColorToColorSpace` we create a new color in the CMYK color space by converting the `rgbaBlue` color to the CMYK color space. We also create a new color in the RGB color space by converting the `spotPinkFlamingo` color to the RGB color space. ```kotlin highlight-convert-color val cmykBlueConverted = engine.editor.convertColorToColorSpace( rgbaBlue, colorSpace = ColorSpace.CMYK, ) val rgbaPinkFlamingoConverted = engine.editor.convertColorToColorSpace( spotPinkFlamingo, colorSpace = ColorSpace.SRGB, ) ``` ## Listing spot colors This function returns the list of currently defined spot colors. ```kotlin highlight-find-spot engine.editor.findAllSpotColors() // ["Crayola-Pink-Flamingo", "Yellow"] ``` ## Redefine a spot color We can re-define the RGB and CMYK approximations of an already defined spot color. Doing so will change the rendered color of the blocks. We change it for the CMYK approximation of `'Yellow'` and make it a bit greenish. The properties that have `'Yellow'` as their spot color will change when re-rendered. ```kotlin highlight-change-spot engine.editor.setSpotColor("Yellow", Color.fromCMYK(c = 0.2F, m = 0F, y = 1F, k = 0F)) ``` ## Removing the definition of a spot color We can undefine a spot color. Doing so will make all the properties still referring to that spot color (`'Yellow'` in this case) use the default magenta RGB approximation. ```kotlin highlight-undefine-spot engine.editor.removeSpotColor("Yellow") ``` ## Full Code Here's the full code: ```kotlin import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.Color import ly.img.engine.ColorSpace import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun colors( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setPositionX(block, value = 350F) engine.block.setPositionY(block, value = 400F) engine.block.setWidth(block, value = 100F) engine.block.setHeight(block, value = 100F) val fill = engine.block.createFill(FillType.Color) engine.block.setFill(block, fill = fill) val rgbaBlue = Color.fromRGBA(r = 0F, g = 0F, b = 1F, a = 1F) val cmykRed = Color.fromCMYK(c = 0F, m = 1F, y = 1F, k = 0F, tint = 1F) val cmykPartialRed = Color.fromCMYK(c = 0F, m = 1F, y = 1F, k = 0F, tint = 0.5F) engine.editor.setSpotColor( name = "Pink-Flamingo", Color.fromRGBA(r = 0.988F, g = 0.455F, b = 0.992F), ) engine.editor.setSpotColor(name = "Yellow", Color.fromCMYK(c = 0F, m = 0F, y = 1F, k = 0F)) val spotPinkFlamingo = Color.fromSpotColor( name = "Pink-Flamingo", tint = 1F, externalReference = "Crayola", ) val spotPartialYellow = Color.fromSpotColor(name = "Yellow", tint = 0.3F) engine.block.setColor(fill, property = "fill/color/value", value = rgbaBlue) engine.block.setColor(fill, property = "fill/color/value", value = cmykRed) engine.block.setColor(block, property = "stroke/color", value = cmykPartialRed) engine.block.setColor(fill, property = "fill/color/value", value = spotPinkFlamingo) engine.block.setColor(block, property = "dropShadow/color", value = spotPartialYellow) val cmykBlueConverted = engine.editor.convertColorToColorSpace( rgbaBlue, colorSpace = ColorSpace.CMYK, ) val rgbaPinkFlamingoConverted = engine.editor.convertColorToColorSpace( spotPinkFlamingo, colorSpace = ColorSpace.SRGB, ) engine.editor.findAllSpotColors() // ["Crayola-Pink-Flamingo", "Yellow"] engine.editor.setSpotColor("Yellow", Color.fromCMYK(c = 0.2F, m = 0F, y = 1F, k = 0F)) engine.editor.removeSpotColor("Yellow") engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Basics" description: "Learn how color is handled in CE.SDK and how to apply, modify, and manage it across elements." platform: android url: "https://img.ly/docs/cesdk/android/colors/basics-307115/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Colors](https://img.ly/docs/cesdk/android/colors-a9b79c/) > [Basics](https://img.ly/docs/cesdk/android/colors/basics-307115/) --- When specifying a color property, you can use one of three color spaces: [RGB](https://en.wikipedia.org/wiki/RGB_color_model), [CMYK](https://en.wikipedia.org/wiki/CMYK_color_model) and [spot color](https://en.wikipedia.org/wiki/Spot_color). > **Note:** During export, only RGB and spot color values will be inserted into the > resulting PDF. Any color specified in CMYK values will be converted to RGB > using the standard conversion. Tint values will be retained in the alpha > channel. The following properties can be set with the function `setColor` and support all three color spaces: - `'backgroundColor/color'` - `'camera/clearColor'` - `'dropShadow/color'` - `'fill/color/value'` - `'stroke/color'` ## RGB RGB is the color space used when rendering a color to a screen. All values of `R`, `G`, `B`must be between `0.0` and `1.0` When using RGB, you typically also specify opacity or alpha as a value between `0.0` and `1.0` and is then referred to as `RGBA`. When a RGB color has an alpha value that is not `1.0`, it will be rendered to screen with corresponding transparency. ## CMYK CMYK is the color space used when color printing. All values of `C`, `M`, `Y`, and `K` must be between `0.0` and `1.0` When using CMYK, you can also specify a tint value between `0.0` and `1.0`. When a CMYK color has a tint value that is not `1.0`, it will be rendered to screen as if transparent over a white background. When rendering to screen, CMYK colors are first converted to RGB using a simple mathematical conversion. Currently, the same conversion happens when exporting a scene to a PDF file. ## Spot Color Spot colors are typically used for special printers or other devices that understand how to use them. Spot colors are defined primarily by their name as that is the information that the device will use to render. For the purpose of rendering a spot color to screen, it must be given either an RGB or CMYK color approximation or both. These approximations adhere to the same restrictions respectively described above. You can specify a tint as a value between `0.0` and `1.0` which will be interpreted as opacity when rendering to screen. It is up to the special printer or device how to interpret the tint value. You can also specify an external reference, a string describing the origin of this spot color. When rendering to screen, the spot color's RGB or CMYK approximation will be used, in that order of preference. When exporting a scene to a PDF file, spot colors will be saved as a [Separation Color Space](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/pdfreference1.6.pdf#G9.1850648). Using a spot color is a two step process: 1. you define a spot color with its name and color approximation(s) in the spot color registry. 2. you instantiate a spot color with its name, a tint and an external reference. The spot color registry allows you to: - list the defined spot colors - define a new a spot color with a name and its RGB or CMYK approximation - re-define an existing spot color's RGB or CMYK approximation - retrieve the RGB or CMYK approximation of an already defined spot color - remove a spot color from the list of defined spot colors Multiple blocks and their properties can refer to the same spot color and each can have a different tint and external reference. > **Note:** **Warning** If a block's color property refers to an undefined spot color, the > default color magenta with an RGB approximation of (1, 0, 1) will be used. ## Converting between colors A utility function `convertColorToColorSpace` is provided to create a new color from an existing color and a new color space. RGB and CMYK colors can be converted between each other and is done so using a simple mathematical conversion. Spot colors can be converted to RGB and CMYK simply by using the corresponding approximation. RGB and CMYK colors cannot be converted to spot colors. ## Custom Color Libraries You can configure CE.SDK with custom color libraries. More information is found [here](https://img.ly/docs/cesdk/android/colors/create-color-palette-7012e0/). --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Color Conversion" description: "Convert between RGB, CMYK, and other color formats based on your project’s output requirements." platform: android url: "https://img.ly/docs/cesdk/android/colors/conversion-bcd82b/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Colors](https://img.ly/docs/cesdk/android/colors-a9b79c/) > [Color Conversion](https://img.ly/docs/cesdk/android/colors/conversion-bcd82b/) --- To ease implementing advanced color interfaces, you may rely on the engine to perform color conversions. Converts a color to the given color space. - `color`: The color to convert. - `colorSpace`: The color space to convert to. - Returns The converted color. ```kotlin // Convert a color val rgbaGreen = Color.fromRGBA(r = 0F, g = 1F, b = 0F, a = 0F) val cmykGreen = engine.editor.convertColorToColorSpace(color = rgbaGreen, colorSpace = ColorSpace.CMYK) ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Create a Color Palette" description: "Build reusable color palettes to maintain consistency and streamline user choices." platform: android url: "https://img.ly/docs/cesdk/android/colors/create-color-palette-7012e0/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Colors](https://img.ly/docs/cesdk/android/colors-a9b79c/) > [Create a Color Palette](https://img.ly/docs/cesdk/android/colors/create-color-palette-7012e0/) --- ```kotlin file=@cesdk_android_examples/editor-guides-configuration-color-palette/ColorPaletteEditorSolution.kt reference-only import androidx.compose.runtime.Composable import androidx.compose.runtime.remember import androidx.compose.ui.graphics.Color import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EngineConfiguration import ly.img.editor.rememberForDesign // Add this composable to your NavHost @Composable fun ColorPaletteEditorSolution(navController: NavHostController) { val engineConfiguration = EngineConfiguration.rememberForDesign( license = "", // pass null or empty for evaluation mode with watermark ) val editorConfiguration = EditorConfiguration.rememberForDesign( colorPalette = remember { listOf( Color(0xFF4A67FF), Color(0xFFFFD333), Color(0xFFC41230), Color(0xFF000000), Color(0xFFFFFFFF), ) }, ) DesignEditor( engineConfiguration = engineConfiguration, editorConfiguration = editorConfiguration, ) { // You can set result here navController.popBackStack() } } ``` In this example, we will show you how to make color palette configurations for the mobile editor. The example is based on the `Design Editor`, however, it is exactly the same for all the other [solutions](https://img.ly/docs/cesdk/android/prebuilt-solutions-d0ed07/). ## Configuration Color palette configuration is part of the `EditorConfiguration` class. Use the `EditorConfiguration.getDefault` helper function to make color palette configurations. - `colorPalette` - the color palette used for UI elements that contain predefined color options, e.g., for "Fill Color" or "Stroke Color". ```kotlin highlight-configuration-colorPalette colorPalette = remember { listOf( Color(0xFF4A67FF), Color(0xFFFFD333), Color(0xFFC41230), Color(0xFF000000), Color(0xFFFFFFFF), ) }, ``` ## Full Code Here's the full code: ```kotlin import androidx.compose.runtime.Composable import androidx.compose.runtime.remember import androidx.compose.ui.graphics.Color import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EngineConfiguration import ly.img.editor.rememberForDesign // Add this composable to your NavHost @Composable fun ColorPaletteEditorSolution(navController: NavHostController) { val engineConfiguration = EngineConfiguration.rememberForDesign( license = "", ) val editorConfiguration = EditorConfiguration.rememberForDesign( colorPalette = remember { listOf( Color(0xFF4A67FF), Color(0xFFFFD333), Color(0xFFC41230), Color(0xFF000000), Color(0xFFFFFFFF), ) }, ) DesignEditor( engineConfiguration = engineConfiguration, editorConfiguration = editorConfiguration, ) { // You can set result here navController.popBackStack() } } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "For Print" description: "Use print-ready color models and settings for professional-quality, production-ready exports." platform: android url: "https://img.ly/docs/cesdk/android/colors/for-print-59bc05/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Colors](https://img.ly/docs/cesdk/android/colors-a9b79c/) > [For Print](https://img.ly/docs/cesdk/android/colors/for-print-59bc05/) --- --- ## Related Pages - [Spot Colors](https://img.ly/docs/cesdk/android/colors/for-print/spot-c3a150/) - Learn how to define spot colors and set their color approximation in the CreativeEditor SDK. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Spot Colors" description: "Learn how to define spot colors and set their color approximation in the CreativeEditor SDK." platform: android url: "https://img.ly/docs/cesdk/android/colors/for-print/spot-c3a150/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Colors](https://img.ly/docs/cesdk/android/colors-a9b79c/) > [For Print](https://img.ly/docs/cesdk/android/colors/for-print-59bc05/) > [Spot Colors](https://img.ly/docs/cesdk/android/colors/for-print/spot-c3a150/) --- ```kotlin reference-only // Create a spot color with an RGB color approximation. engine.editor.setSpotColor("Red", Color.fromRGBA(r = 1F, g = 0F, b = 0F, a = 1F)) // Create a spot color with a CMYK color approximation. // Add a CMYK approximation to the already defined 'Red' spot color. engine.editor.setSpotColor("Yellow", Color.fromCMYK(c = 0F, m = 0F, y = 1F, k = 0F)) engine.editor.setSpotColor("Red", Color.fromCMYK(c = 0F, m = 1F, y = 1F, k = 0F)) // List all defined spot colors. engine.editor.findAllSpotColors() // ['Red', 'Yellow'] // Retrieve the RGB color approximation for a defined color. // The alpha value will always be 1.0. val rgbaSpotRed = engine.editor.getSpotColorRGB("Red") // Retrieve the CMYK color approximation for a defined color. val cmykSpotRed = engine.editor.getSpotColorCMYK("Red") // Retrieving the approximation of an undefined spot color returns magenta. val cmykSpotUnknown = engine.editor.getSpotColorCMYK("Unknown") // Returns CMYK values for magenta. // Removes a spot color from the list of defined spot colors. engine.editor.removeSpotColor("Red") ``` In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/creative-sdk)'s CreativeEngine to manage spot colors in the `editor` API. ## Functions ```kotlin fun findAllSpotColors(): List ``` Queries the names of currently set spot colors previously set with \`setSpotColor\`\`. - Returns the names of set spot colors. ```kotlin fun getSpotColorRGB(name: String): RGBAColor ``` Queries the RGB representation set for a spot color. If the value of the queried spot color has not been set yet, returns the default RGB representation (of magenta). The alpha value is always 1.0. - `name`: the name of a spot color. - Returns the RGB representation of a spot color. ```kotlin fun getSpotColorCMYK(name: String): CMYKColor ``` Queries the CMYK representation set for a spot color. If the value of the queried spot color has not been set yet, returns the default RGB representation (of magenta). - `name`: the name of a spot color. - Returns the CMYK representation of a spot color. ```kotlin fun setSpotColor( name: String, color: RGBAColor, ) ``` Sets the RGB representation of a spot color. Use this function to both create a new spot color or update an existing spot color. Note: The alpha value is ignored. - `name`: the name of a spot color. - `color`: the RGB spot color. ```kotlin fun setSpotColor( name: String, color: CMYKColor, ) ``` Sets the CMYK representation of a spot color. Use this function to both create a new spot color or update an existing spot color. - `name`: the name of a spot color. - `color`: the CMYK spot color. ```kotlin fun removeSpotColor(name: String) ``` Removes a spot color from the list of set spot colors. - `name`: the name of a spot color. ## Full Code Here's the full code: ```kotlin // Create a spot color with an RGB color approximation. engine.editor.setSpotColor("Red", Color.fromRGBA(r = 1F, g = 0F, b = 0F, a = 1F)) // Create a spot color with a CMYK color approximation. // Add a CMYK approximation to the already defined 'Red' spot color. engine.editor.setSpotColor("Yellow", Color.fromCMYK(c = 0F, m = 0F, y = 1F, k = 0F)) engine.editor.setSpotColor("Red", Color.fromCMYK(c = 0F, m = 1F, y = 1F, k = 0F)) // List all defined spot colors. engine.editor.findAllSpotColors() // ['Red', 'Yellow'] // Retrieve the RGB color approximation for a defined color. // The alpha value will always be 1.0. val rgbaSpotRed = engine.editor.getSpotColorRGB("Red") // Retrieve the CMYK color approximation for a defined color. val cmykSpotRed = engine.editor.getSpotColorCMYK("Red") // Retrieving the approximation of an undefined spot color returns magenta. val cmykSpotUnknown = engine.editor.getSpotColorCMYK("Unknown") // Returns CMYK values for magenta. // Removes a spot color from the list of defined spot colors. engine.editor.removeSpotColor("Red") ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "For Screen" description: "Documentation for For Screen" platform: android url: "https://img.ly/docs/cesdk/android/colors/for-screen-1911f8/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Colors](https://img.ly/docs/cesdk/android/colors-a9b79c/) > [For Screen](https://img.ly/docs/cesdk/android/colors/for-screen-1911f8/) --- --- ## Related Pages - [P3 Colors](https://img.ly/docs/cesdk/android/colors/for-screen/p3-706127/) - Documentation for P3 Colors --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "P3 Colors" description: "Documentation for P3 Colors" platform: android url: "https://img.ly/docs/cesdk/android/colors/for-screen/p3-706127/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Colors](https://img.ly/docs/cesdk/android/colors-a9b79c/) > [For Screen](https://img.ly/docs/cesdk/android/colors/for-screen-1911f8/) > [P3 Colors](https://img.ly/docs/cesdk/android/colors/for-screen/p3-706127/) --- This guide explains how to check whether the P3 color space is supported on a given device using the `supportsP3()` function and how to handle scenarios where P3 is unavailable. `supportsP3` returns whether the engine supports displaying and working in the P3 color space on the current device. Otherwise, this function throws an error with a description of why the P3 color space is not supported. If supported, the engine can be switched to a P3 color space using the "features/p3WorkingColorSpace" setting. `checkP3Support` throws an error if the engine does not support working in the P3 color space. ```kotlin // Check whether the current device supports working in the P3 color space val p3IsSupported = engine.editor.supportsP3() try { engine.editor.checkP3Support() } catch (ex: Exception) { // P3 is not supported on the current device } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Overview" description: "Manage color usage in your designs, from applying brand palettes to handling print and screen formats." platform: android url: "https://img.ly/docs/cesdk/android/colors/overview-16a177/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Colors](https://img.ly/docs/cesdk/android/colors-a9b79c/) > [Overview](https://img.ly/docs/cesdk/android/colors/overview-16a177/) --- Colors are a fundamental part of design in the CreativeEditor SDK (CE.SDK). Whether you're designing for digital screens or printed materials, consistent color management ensures your creations look the way you intend. CE.SDK offers flexible tools for working with colors through both the user interface and programmatically, making it easy to manage color workflows at any scale. [Explore Demos](https://img.ly/showcases/cesdk?tags=android) [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "System Compatibility" description: "Learn how device performance and hardware limits affect CE.SDK editing, rendering, and export capabilities." platform: android url: "https://img.ly/docs/cesdk/android/compatibility-139ef9/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Compatibility & Security](https://img.ly/docs/cesdk/android/compatibility-fef719/) > [System Compatibility](https://img.ly/docs/cesdk/android/compatibility-139ef9/) --- ## Targets On Android, CE.SDK makes use of system-frameworks to benefit from hardware acceleration and platform native performance. The following targets are supported: - Android 7 or later (`minSdk 24`) ## Recommended Hardware Android phones released in the last 5 years, e.g. Asus Zenfone 3, Samsung M31s, or Google Pixel 5. Video capabilities directly depend on the video capabilities of the individual phone. ## Video Playback and exporting is **supported for all codecs** mentioned in the general section. However, mobile devices have stricter limits around the number of parallel encoders and decoders compared to fully fledged desktop machines. This means, that very large scenes with more than 10 videos shown in parallel may fail to play all videos at the same time. ## Export Limitations The export size is limited by the hardware capabilities of the device, e.g., due to the maximum texture size that can be allocated. The maximum possible export size can be queried via API, see [export guide](https://img.ly/docs/cesdk/android/export-save-publish/export/overview-9ed3a8/). --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Compatibility & Security" description: "Learn about CE.SDK's compatibility and security features." platform: android url: "https://img.ly/docs/cesdk/android/compatibility-fef719/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Compatibility & Security](https://img.ly/docs/cesdk/android/compatibility-fef719/) --- CE.SDK provides robust compatibility and security features across platforms. Learn about supported browsers, frameworks, file formats, language support, and how CE.SDK ensures secure operation in your applications. --- ## Related Pages - [Bundle Size](https://img.ly/docs/cesdk/android/bundle-size-df9210/) - Understand CE.SDK’s engine and editor bundle sizes and how they affect your mobile app’s download footprint. - [System Compatibility](https://img.ly/docs/cesdk/android/compatibility-139ef9/) - Learn how device performance and hardware limits affect CE.SDK editing, rendering, and export capabilities. - [File Format Support](https://img.ly/docs/cesdk/android/file-format-support-3c4b2a/) - See which image, video, audio, font, and template formats CE.SDK supports for import and export. - [Security](https://img.ly/docs/cesdk/android/security-777bfd/) - Learn how CE.SDK keeps your data private with client-side processing, secure licensing, and GDPR-compliant practices. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Concepts" description: "Key concepts and principles of CE.SDK" platform: android url: "https://img.ly/docs/cesdk/android/concepts-c9ff51/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Concepts](https://img.ly/docs/cesdk/android/concepts-c9ff51/) --- Key Concepts and principles of CE.SDK. --- ## Related Pages - [Key Concepts](https://img.ly/docs/cesdk/android/key-concepts-21a270/) - Explore CE.SDK’s key features—manual editing, automation, templates, AI tools, and full UI and API control. - [Key Capabilities](https://img.ly/docs/cesdk/android/key-capabilities-dbb5b1/) - Explore CE.SDK’s key features—manual editing, automation, templates, AI tools, and full UI and API control. - [Editing Workflow](https://img.ly/docs/cesdk/android/concepts/editing-workflow-032d27/) - Control editing access with Creator and Adopter roles, each offering tailored permissions and UI constraints. - [Blocks](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/) - Learn how blocks define elements in a scene and how to structure them for rendering in CE.SDK. - [Scenes](https://img.ly/docs/cesdk/android/concepts/scenes-e8596d/) - Scenes act as the root container for blocks and define the full design structure in CE.SDK. - [Editor State](https://img.ly/docs/cesdk/android/concepts/edit-modes-1f5b6c/) - Control how users interact with content by switching between edit modes like transform, crop, and text. - [Events](https://img.ly/docs/cesdk/android/concepts/events-353f97/) - Subscribe to block creation, update, and deletion events to track changes in your CE.SDK scene. - [Buffers](https://img.ly/docs/cesdk/android/concepts/buffers-9c565b/) - Use buffers to store temporary, non-serializable data in CE.SDK via the CreativeEngine API. - [Working With Resources](https://img.ly/docs/cesdk/android/concepts/resources-a58d71/) - Preload all resources for blocks or scenes in CE.SDK to improve performance and avoid runtime delays. - [Undo and History](https://img.ly/docs/cesdk/android/concepts/undo-and-history-99479d/) - Manage undo and redo stacks in CE.SDK using multiple histories, callbacks, and API-based controls. - [Headless](https://img.ly/docs/cesdk/android/concepts/headless-mode-24ab98/) - Use the engine directly, without any prebuilt UI. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Blocks" description: "Learn how blocks define elements in a scene and how to structure them for rendering in CE.SDK." platform: android url: "https://img.ly/docs/cesdk/android/concepts/blocks-90241e/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Concepts](https://img.ly/docs/cesdk/android/concepts-c9ff51/) > [Blocks](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/) --- ## Lifecycle Only blocks that are direct or indirect children of a `page` block are rendered. Scenes without any `page` child may not be properly displayed by the CE.SDK editor. ### Functions ```kotlin fun create(blockType: DesignBlockType): DesignBlock ``` Create a new block. - `blockType`: the type of the block that shall be created. - Returns the created blocks handle. To create a scene, use [](https://img.ly/docs/cesdk/android/open-the-editor-23a1db/) instead. ```kotlin suspend fun saveToString( blocks: List, allowedResourceSchemes: List = listOf("bundle", "file", "http", "https"), ): String ``` Saves the given blocks to a proprietary string. If a resource uri has a scheme that is not in `allowedResourceSchemes`, an exception will be thrown. Note: All given block handles must be valid, otherwise an exception will be thrown. - `blocks`: the blocks to save. - `allowedResourceSchemes`: the list of allowed resource schemes in the scene. - Returns a string representation of the blocks. ```kotlin suspend fun saveToArchive(blocks: List): ByteBuffer ``` Saves the given blocks to an archive. Note: All given block handles must be valid, otherwise this call returns an error. - `blocks`: the blocks to save. - Returns a string representation of the blocks. ```kotlin suspend fun loadFromString(block: String): List ``` Loads existing blocks from the given string. The blocks are not attached by default and won't be visible until attached to a page or the scene. The UUID of the loaded blocks is replaced with a new one. - `block`: a string representing the given blocks. - Returns a list of loaded blocks. ```kotlin suspend fun loadFromURL(url: Uri): List ``` Loads existing blocks from a URL. The URL should point to a blocks file within an unzipped archive directory previously saved with `saveToArchive`. The blocks are not attached by default and won't be visible until attached to a page or the scene. The UUID of the loaded blocks is replaced with a new one. - `url`: the URL to the blocks.blocks file. - Returns a list of loaded blocks. ```kotlin suspend fun loadFromArchive(archiveUri: Uri): List ``` Loads existing blocks from an archive. The blocks are not attached by default and won't be visible until attached to a page or the scene. The UUID of the loaded blocks is replaced with a new one. - `archiveUri`: the uri of the blocks archive file. - Returns a list of loaded blocks. ```kotlin fun getType(block: DesignBlock): String ``` Get the type of the given block, fails if the block is invalid. - `block`: the block to query. - Returns the block type. ```kotlin fun setName( block: DesignBlock, name: String, ) ``` Update a block's name. - `block`: the block to update. - `name`: the name to set. ```kotlin fun getName(block: DesignBlock): String ``` Get a block's name. - `block:`: The block to query. - Returns The block's name. ```kotlin fun duplicate(block: DesignBlock): DesignBlock ``` Duplicates a block including its children. Required scope: "lifecycle/duplicate" If the block is parented to a track that is set always-on-bottom, the duplicate is inserted in the same track immediately after the block. Otherwise, the duplicate is moved up in the hierarchy. - `block`: the block to duplicate. - Returns the handle of the duplicate. ```kotlin fun destroy(block: DesignBlock) ``` Destroys a block. Required scope: "lifecycle/destroy" - `block`: the block to destroy. ```kotlin fun isValid(block: DesignBlock): Boolean ``` Check if a block is valid. A block becomes invalid once it has been destroyed. - `block`: the block to query. - Returns true if the block is valid, false otherwise. ### Full Code In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to modify scenes through the `block` Api. ```kotlin // Create, save and load blocks val block = engine.block.create(DesignBlockType.Graphic) val savedBlocksString = engine.block.saveToString(blocks = listOf(block)) val loadedBlocksString = engine.block.loadFromString(savedBlocksString) val savedBlocksArchive = engine.block.saveToArchive(blocks = listOf(block)) val loadedBlocksArchive = engine.block.loadFromArchive(blocksUri = Uri.parse("https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1_blocks.zip")) // Load blocks from an extracted zip file created with block.saveToArchive val loadedBlocksURL = engine.block.loadFromURL(url = Uri.parse("https://cdn.img.ly/assets/v6/ly.img.text.components/box/blocks.blocks")) // Check a blocks type val blockType = engine.block.getType(block) // Alter a blocks name engine.block.setName(block, name = "someName") val name = engine.block.getName(block) // You may duplicate or destroy blocks val duplicate = engine.block.duplicate(block) engine.block.destroy(duplicate) engine.block.isValid(duplicate) // false ``` ## Properties ### UUID A universally unique identifier (UUID) is assigned to each block upon creation and can be queried. This is stable across save & load and may be used to reference blocks. ```kotlin fun getUUID(block: DesignBlock): String ``` Get a block's unique identifier. - `block:`: The block to query. - Returns The block's UUID. ### Reflection For every block, you can get a list of all its properties by calling `findAllProperties`. Properties specific to a block are prefixed with the block's type followed by a forward slash. There are also common properties shared between blocks which are prefixed by their respective type. A list of all properties can be found in the [Blocks Overview](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/). ```kotlin fun findAllProperties(block: DesignBlock): List ``` Get all available properties of a block. - `block`: the block whose properties should be queried. - Returns a list of the property names. Given a property you can query its type using `getPropertyType`. ```kotlin fun getPropertyType(property: String): PropertyType ``` Get the type of a property given its name. - `property`: the name of the property whose type should be queried. - Returns the property type. To get a list of possible values for an enum property call `getEnumValues(enumProperty: string): string[]`. ```kotlin fun getEnumValues(enumProperty: String): List ``` Get all the possible values of an enum given an enum property. - `enumProperty`: the name of the property whose enum values should be queried. - Returns a list of the enum value names as string. Some properties can only be written to or only be read. To find out what is possible with a property, you can use the `isPropertyReadable` and `isPropertyWritable` methods. ```kotlin fun isPropertyReadable(property: String): Boolean ``` Check if a property with a given name is readable. - `property`: the name of the property whose type should be queried. - Returns whether the property is readable or not. Will return false for unknown properties. ```kotlin fun isPropertyWritable(property: String): Boolean ``` Check if a property with a given name is writeable. - `property`: the name of the property whose type should be queried. - Returns whether the property is writeable or not. Will return false for unknown properties. ### Generic Properties There are dedicated setter and getter functions for each property type. You have to provide a block and the property path. Use `findAllProperties` to get a list of all the available properties a block has. > **Note:** Please make sure you call the setter and getter function matching the type of > the property you want to set or query or else you will get an error. Use > `getType` to figure out the pair of functions you need to use. ```kotlin fun findAllProperties(block: DesignBlock): List ``` Get all available properties of a block. - `block`: the block whose properties should be queried. - Returns a list of the property names. ```kotlin fun setBoolean( block: DesignBlock, property: String, value: Boolean, ) ``` Set a boolean property of the given design block to the given value. - `block`: the block whose property should be set. - `property`: the name of the property to set. - `value`: the value to set. ```kotlin fun getBoolean( block: DesignBlock, property: String, ): Boolean ``` Get the value of a boolean property of the given design block. - `block`: the block whose property should be queried. - `property`: the name of the property to set. - Returns the value of the property. ```kotlin fun setInt( block: DesignBlock, property: String, value: Int, ) ``` Set an int property of the given design block to the given value. - `block`: the block whose property should be set. - `property`: the name of the property to set. - `value`: the value to set. ```kotlin fun getInt( block: DesignBlock, property: String, ): Int ``` Get the value of an int property of the given design block. - `block`: the block whose property should be queried. - `property`: the name of the property to set. - Returns the value of the property. ```kotlin fun setFloat( block: DesignBlock, property: String, value: Float, ) ``` Set a float property of the given design block to the given value. - `block`: the block whose property should be set. - `property`: the name of the property to set. - `value`: the value to set. ```kotlin fun getFloat( block: DesignBlock, property: String, ): Float ``` Get the value of a float property of the given design block. - `block`: the block whose property should be queried. - `property`: the name of the property to set. - Returns the value of the property. ```kotlin fun setDouble( block: DesignBlock, property: String, value: Double, ) ``` Set a double property of the given design block to the given value. - `block`: the block whose property should be set. - `property`: the name of the property to set. - `value`: the value to set. ```kotlin fun getDouble( block: DesignBlock, property: String, ): Double ``` Get the value of a double property of the given design block. - `block`: the block whose property should be queried. - `property`: the name of the property to set. - Returns the value of the property. ```kotlin fun setString( block: DesignBlock, property: String, value: String, ) ``` Set a string property of the given design block to the given value. - `block`: the block whose property should be set. - `property`: the name of the property to set. - `value`: the value to set. ```kotlin fun getString( block: DesignBlock, property: String, ): String ``` Get the value of a string property of the given design block. - `block`: the block whose property should be queried. - `property`: the name of the property to set. - Returns the value of the property. ```kotlin fun setColor( block: DesignBlock, property: String, value: Color, ) ``` Set a color property of the given design block to the given value. - `block`: the block whose property should be set. - `property`: the name of the property to set. - `value`: the value to set. ```kotlin fun getColor( block: DesignBlock, property: String, ): Color ``` Get the value of a color property of the given design block. - `block`: the block whose property should be queried. - `property`: the name of the property to set. - Returns the value of the property. ```kotlin fun setEnum( block: DesignBlock, property: String, value: String, ) ``` Set an enum property of the given design block to the given value. - `block`: the block whose property should be set. - `property`: the name of the property to set. - `value`: the value to set. ```kotlin fun getEnum( block: DesignBlock, property: String, ): String ``` Get the value of an enum property of the given design block. - `block`: the block whose property should be queried. - `property`: the name of the property to get. - Returns the value of the property. ```kotlin fun setGradientColorStops( block: DesignBlock, property: String, colorStops: List, ) ``` Set a gradient color stops property of the given design block. - `block`: the block whose property should be set. - `property`: the name of the property to set. - `colorStops`: the list of color stops. ```kotlin fun getGradientColorStops( block: DesignBlock, property: String, ): List ``` Get the gradient color stops property of the given design block. - `block`: the block whose property should be queried. - `property`: the name of the property to query. - Returns the list of gradient color stops. ```kotlin fun setSourceSet( block: DesignBlock, property: String, sourceSet: List, ) ``` Set the source set of a source set property of the given block. The crop and content fill mode of the associated block will be set to the default values. - `block`: the block whose source set should be set. - `property`: the name of the property to set. - `sourceSet`: the new source set. ```kotlin fun getSourceSet( block: DesignBlock, property: String, ): List ``` Returns the source set of a source set property of the given block. - `block`: the block whose property should be queried. - `property`: the name of the property to get. - Returns the source set of the given block. ```kotlin suspend fun addImageFileUriToSourceSet( block: DesignBlock, property: String, uri: String, ) ``` Add a source to the `sourceSet` property of the given block. If there already exists in source set an image with the same width, that existing image will be replaced. If the source set is or gets empty, the crop and content fill mode of the associated block will be set to the default values. Note: This fetches the resource from the given URI to obtain the image dimensions. It is recommended to use setSourceSet if the dimension is known. - `block`: the block to update. - `property`: the name of the property to modify. - `uri`: the source to add to the source set. ```kotlin suspend fun addVideoFileUriToSourceSet( block: DesignBlock, property: String, uri: String, ) ``` Add a source to the `sourceSet` property of the given block. If there already exists in source set a video with the same width, that existing video will be replaced. If the source set is or gets empty, the crop and content fill mode of the associated block will be set to the default values. Note: This fetches the resource from the given URI to obtain the video dimensions. It is recommended to use setSourceSet if the dimension is known. - `block`: the block to update. - `property`: the name of the property to modify. - `uri`: the source to add to the source set. ### Modifying Properties Here’s the full code snippet for modifying a block’s properties: ```kotlin val uuid = engine.block.getUUID(block) val propertyNamesStar = engine.block .findAllProperties(starShape) // List [ "shape/star/innerDiameter", "shape/star/points", "opacity/value", ... ] val propertyNamesImage = engine.block .findAllProperties(imageFill) // List [ "fill/image/imageFileURI", "fill/image/previewFileURI", "fill/image/externalReference", ... ] val propertyNamesText = engine.block .findAllProperties(text) // List [ "text/text", "text/fontFileUri", "text/externalReference", "text/fontSize", "text/horizontalAlignment", ... ] val pointsType = engine.block.getPropertyType(property = "shape/star/points") // "Int" val alignmentType = engine.block.getPropertyType(property = "text/horizontalAlignment") // "Enum" engine.block.getEnumValues(enumProperty = "text/horizontalAlignment") val readable = engine.block.isPropertyReadable("shape/star/points") val writable = engine.block.isPropertyWritable("shape/star/points") // Generic Properties engine.block.setBoolean(scene, property = "scene/aspectRatioLock", value = false) engine.block.getBoolean(scene, property = "scene/aspectRatioLock") engine.block.setInt(star, property = "shape/star/points", value = points + 2) val points = engine.block.getInt(star, property = "shape/star/points") engine.block.setFloat(star, property = "shape/star/innerDiameter", value = 0.75F) engine.block.getFloat(star, property = "shape/star/innerDiameter") val audio = engine.block.create(DesignBlockType.Audio) engine.block.appendChild(scene, audio) engine.block.setDouble(audio, property = "playback/duration", value = 1.0) engine.block.getDouble(audio, property = "playback/duration") engine.block.setString(text, property = "text/text", value = "*o*") engine.block.setString( imageFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_4.jpg" ) engine.block.getString(text, property = "text/text") engine.block.getString(imageFill, property = "fill/image/imageFileURI") engine.block.setColor( colorFill, property = "fill/color/value", value = Color.fromString("#FFFFFFFF") ) // White engine.block.getColor(colorFill, property = "fill/color/value") engine.block.setEnum(text, property = "text/horizontalAlignment", value = "Center") engine.block.setEnum(text, property = "text/verticalAlignment", value = "Center") engine.block.getEnum(text, property = "text/horizontalAlignment") engine.block.getEnum(text, property = "text/verticalAlignment") engine.block.setGradientColorStops( block = gradientFill, property = "fill/gradient/colors", colorStops = listOf( GradientColorStop(stop = 0F, color = Color.fromRGBA(r = 0.1F, g = 0.2F, b = 0.3F, a = 0.4F)), GradientColorStop(stop = 1F, color = Color.fromSpotColor("test")) ) ) engine.block.getGradientColorStops(block = gradientFill, property = "fill/gradient/colors") val imageFill = engine.block.createFill(FillType.Image) engine.block.setSourceSet( block = imageFill, property = "fill/image/sourceSet", sourceSet = listOf( Source( uri = Uri.parse("http://img.ly/my-image.png"), width = 800, height = 600 ) ) ) engine.block.getSourceSet(block = imageFill, property = "fill/image/sourceSet") engine.block.addImageFileUriToSourceSet(block = imageFill, property = "fill/image/sourceSet", uri = "https://img.ly/static/ubq_samples/sample_1.jpg"); val videoFill = engine.block.createFill(FillType.Video) engine.block.addVideoFileUriToSourceSet(block = videoFill, property = "fill/video/sourceSet", uri = "https://img.ly/static/example-assets/sourceset/1x.mp4"); ``` ### Kind Property The `kind` of a design block is a custom string that can be assigned to a block in order to categorize it and distinguish it from other blocks that have the same type. The user interface can then customize its appearance based on the kind of the selected blocks. It can also be used for automation use cases in order to process blocks in a different way based on their kind. ```kotlin fun setKind( block: DesignBlock, kind: String, ) ``` Set the kind of the given block, fails if the block is invalid. - `block`: the block to modify. - `kind`: the block kind. ```kotlin fun getKind(block: DesignBlock): String ``` Get the kind of the given block, fails if the block is invalid. - `block`: the block to query. - Returns the block kind. ```kotlin fun findByKind(blockKind: String): List ``` Finds all blocks with the given kind. - `blockKind`: the kind to search for. - Returns a list of block ids. #### Full Code In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to modify a and query the kind property of design blocks through the `block` API. ```kotlin engine.block.setKind(text, kind = "title") val kind = engine.block.getKind(text) val allTitles = engine.block.findByKind(blockKind = "title") ``` ## Selection & Visibility A block can potentially be *invisible* (in the sense that you can't see it), even though `isVisible()` returns true. This could be the case when a block has not been added to a parent, the parent itself is not visible, or the block is obscured by another block on top of it. ### Select blocks and change their visibility ```kotlin fun setSelected( block: DesignBlock, selected: Boolean, ) ``` Update the selection state of a block. Fails for invalid blocks. Note: Previously selected blocks remain selected. Required scope: "editor/select" - `block`: the block to query. - `selected`: whether or not the block should be selected. ```kotlin fun isSelected(block: DesignBlock): Boolean ``` Get the selected state of a block. - `block`: the block to query. - Returns true if the block is selected, false otherwise. ```kotlin fun select(block: DesignBlock) ``` Selects the given block and deselects all other blocks. - `block`: the block to be selected. ```kotlin fun findAllSelected(): List ``` Get all currently selected blocks. - Returns An array of block ids. ```kotlin fun setVisible( block: DesignBlock, visible: Boolean, ) ``` Update a block's visibility. Required scope: "layer/visibility" - `block`: the block to update. - `visible`: whether the block shall be visible. ```kotlin fun isVisible(block: DesignBlock): Boolean ``` Query a block's visibility. - `block`: the block to query. - Returns true if visible, false otherwise. ```kotlin fun setClipped( block: DesignBlock, clipped: Boolean, ) ``` Update a block's clipped state. Required scope: "layer/clipping" - `block`: the block to update. - `clipped`: whether the block should clips its contents to its frame. ```kotlin fun isClipped(block: DesignBlock): Boolean ``` Query a block's clipped state. If `true`, the block should clip - `block`: the block to query. - Returns true if clipped, false otherwise. ```kotlin fun onSelectionChanged(): Flow ``` Subscribe to changes in the current set of selected blocks. - Returns flow of selected block change events. ```kotlin fun onClicked(): Flow ``` Subscribe to block click events. Note: `DesignBlock` is emitted at the end of the engine update if it has been clicked. - Returns flow of block click events. ```kotlin fun isIncludedInExport(block: DesignBlock): Boolean ``` Query if the given block is included on the exported result. - `block`: the block to query if it's included on the exported result. - Returns true, if the block is included on the exported result, false otherwise. ```kotlin fun setIncludedInExport( block: DesignBlock, enabled: Boolean, ) ``` Set if you want the given design block to be included in exported result. - `block`: the block whose exportable state should be set. - `enabled`: if true, the block will be included on the exported result. ### Full Code In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to modify scenes through the `block` API. ```kotlin engine.block.setSelected(block, selected = true) val isSelected = engine.block.isSelected(block) engine.block.select(block) val selectedIds = engine.block.findAllSelected() val isVisible = engine.block.isVisible(block) engine.block.setVisible(block, visible = true) val isClipped = engine.block.isClipped(page) engine.block.setClipped(page, clipped = true) val coroutineScope = CoroutineScope(Dispatchers.Main) engine.block.onSelectionChanged() .onEach { println("Change in the set of selected blocks") } .launchIn(coroutineScope) engine.block.onClicked() .onEach { println("Block $it was clicked") } .launchIn(coroutineScope) val isIncludedInExport = engine.block.isIncludedInExport(block) engine.block.setIncludedInExport(block, enabled = true) ``` ## State Blocks can perform operations that take some time or that can end in bad results. When that happens, blocks put themselves in a pending state or an error state and visual feedback is shown pertaining to the state. When an external operation is done to blocks, for example with a plugin, you may want to manually set the block's state to pending (if that external operation takes time) or to error (if that operation resulted in an error). The possible states of a block are: ``` data object Ready : BlockState data class Pending( @FloatRange(from = 0.0, to = 1.0) val progress: Float ) : BlockState data class Error(val type: Type) : BlockState { enum class Type { AUDIO_DECODING, // Failed to decode the block's audio stream. IMAGE_DECODING, // Failed to decode the block's image stream. FILE_FETCH, // Failed to retrieve the block's remote content. UNKNOWN, // An unknown error occurred. VIDEO_DECODING // Failed to decode the block's video stream. } } ``` When calling `getState`, the returned state reflects the combined state of a block, the block's fill, the block's shape and the block's effects. If any of these blocks is in an `Error` state, the returned state will reflect that error. If none of these blocks is in error state but any is in `Pending` state, the returned state will reflect the aggregate progress of the block's progress. If none of the blocks are in error state or pending state, the returned state is `Ready`. ```kotlin fun getState(block: DesignBlock): BlockState ``` Get the current state of a block. Note If this block is in error state or this block has a `Shape` block, `Fill` block or `Effect` block(s), that is in error state, the returned state will be `BlockState.Error`. Else, if this block is in pending state or this block has a `Shape` block, `Fill` block or `Effect` block(s), that is in pending state, the returned state will be `BlockState.Pending`. Else, the returned state will be `BlockState.Ready`. - `block`: the block whose state should be queried. - Returns the state of the block. ```kotlin fun setState( block: DesignBlock, state: BlockState, ) ``` Set the state of a block. - `block`: the block whose state should be set. - `state`: the new state to set. ```kotlin fun onStateChanged(blocks: List): Flow> ``` Subscribe to changes to the state of a block. Like `getState`, the state of a block is determined by the state of itself and its `Shape`, `Fill` and `Effect` block(s). - `blocks`: a list of blocks to filter events by. If the list is empty, events for every block are sent. - Returns flow of block state change events. ### Full Code In this example, we will show you how to use [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to retrieve's a block's state and to manually set a block in a pending state, an error state or back to a ready state. ```kotlin engine.block.onStateChanged(listOf(block)) .onEach { println("State of blocks $it is updated.") } .launchIn(CoroutineScope(Dispatchers.Main)) val state = engine.block.getState(block) engine.block.setState(block, state = BlockState.Pending(progress = 0.5F)) engine.block.setState(block, state = BlockState.Ready) engine.block.setState(block, state = BlockState.Error(BlockState.Error.Type.IMAGE_DECODING)) ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Buffers" description: "Use buffers to store temporary, non-serializable data in CE.SDK via the CreativeEngine API." platform: android url: "https://img.ly/docs/cesdk/android/concepts/buffers-9c565b/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Concepts](https://img.ly/docs/cesdk/android/concepts-c9ff51/) > [Buffers](https://img.ly/docs/cesdk/android/concepts/buffers-9c565b/) --- ```kotlin reference-only // Create an audio block and append it to the page val audioBlock = engine.block.create(DesignBlockType.Audio) engine.block.appendChild(parent = page, child = audioBlock) // Create a buffer val audioBuffer = engine.editor.createBuffer() // Reference the audio buffer resource from the audio block engine.block.setUri( block = audioBlock, property = "audio/fileURI", value = audioBuffer ) // Generate 10 seconds of stereo 48 kHz audio data val sampleCount = 10 * 48000 val byteBuffer = ByteBuffer.allocate(2 * 4 * sampleCount) //2 channels, each 4 bytes repeat(sampleCount) { val sample = sin((440 * it * 2 * PI) / 48000).toFloat() byteBuffer.putFloat(sample) byteBuffer.putFloat(sample) } // Assign the audio data to the buffer val data = ByteArray(byteBuffer.capacity()) byteBuffer.position(0) byteBuffer.get(data) engine.editor.setBufferData(uri = audioBuffer, offset = 0, data = data) // We can get subranges of the buffer data val chunk = engine.editor.getBufferData(uri = audioBuffer, offset = 0, length = 4096) // Get current length of the buffer in bytes val length = engine.editor.getBufferLength(uri = audioBuffer) // Reduce the buffer to half its length, leading to 5 seconds worth of audio engine.editor.setBufferLength(uri = audioBuffer, length = data.size / 2) // Free data engine.editor.destroyBuffer(uri = audioBuffer) ``` In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to create buffers through the `editor` API. Buffers can hold arbitrary data. > **Note:** **Limitations**Buffers are intended for temporary data only.* Buffer data is not part of the [scene serialization](https://img.ly/docs/cesdk/android/concepts/scenes-e8596d/) > * Changes to buffers can't be undone using the [history system](https://img.ly/docs/cesdk/android/concepts/undo-and-history-99479d/) ```kotlin fun createBuffer(): Uri ``` Create a resizable buffer that can hold arbitrary data. - Returns a uri to identify the buffer. ```kotlin fun destroyBuffer(uri: Uri) ``` Destroy a buffer and free its resources. - `uri`: the uri of the buffer to destroy. ```kotlin fun setBufferData( uri: Uri, offset: Int, data: ByteBuffer, ) ``` Set the data of a buffer. - `uri`: the uri of the buffer. - `offset`: the offset in bytes at which to start writing. - `data`: the data to write. Note that it has to be a direct `ByteBuffer`, created either via `ByteBuffer.allocateDirect` or via JNI NewDirectByteBuffer API. ```kotlin fun getBufferData( uri: Uri, offset: Int, length: Int, ): ByteBuffer ``` Get the data of a buffer. - `uri`: the uri of the buffer. - `offset`: the offset in bytes at which to start reading. - `length`: the number of bytes to read. - Returns the data read from the buffer or an error. ```kotlin fun setBufferLength( uri: Uri, length: Int, ) ``` Set the length of a buffer. - `uri`: the uri of the buffer. - `length`: the new length of the buffer in bytes. ```kotlin fun getBufferLength(uri: Uri): Int ``` Get the length of a buffer. - `uri`: the uri of the buffer. - Returns the length of the buffer in bytes. ## Full Code Here's the full code: ```kotlin // Create an audio block and append it to the page val audioBlock = engine.block.create(DesignBlockType.Audio) engine.block.appendChild(parent = page, child = audioBlock) // Create a buffer val audioBuffer = engine.editor.createBuffer() // Reference the audio buffer resource from the audio block engine.block.setUri( block = audioBlock, property = "audio/fileURI", value = audioBuffer ) // Generate 10 seconds of stereo 48 kHz audio data val sampleCount = 10 * 48000 val byteBuffer = ByteBuffer.allocate(2 * 4 * sampleCount) //2 channels, each 4 bytes repeat(sampleCount) { val sample = sin((440 * it * 2 * PI) / 48000).toFloat() byteBuffer.putFloat(sample) byteBuffer.putFloat(sample) } // Assign the audio data to the buffer val data = ByteArray(byteBuffer.capacity()) byteBuffer.position(0) byteBuffer.get(data) engine.editor.setBufferData(uri = audioBuffer, offset = 0, data = data) // We can get subranges of the buffer data val chunk = engine.editor.getBufferData(uri = audioBuffer, offset = 0, length = 4096) // Get current length of the buffer in bytes val length = engine.editor.getBufferLength(uri = audioBuffer) // Reduce the buffer to half its length, leading to 5 seconds worth of audio engine.editor.setBufferLength(uri = audioBuffer, length = data.size / 2) // Free data engine.editor.destroyBuffer(uri = audioBuffer) ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Editor State" description: "Control how users interact with content by switching between edit modes like transform, crop, and text." platform: android url: "https://img.ly/docs/cesdk/android/concepts/edit-modes-1f5b6c/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Concepts](https://img.ly/docs/cesdk/android/concepts-c9ff51/) > [Editor State](https://img.ly/docs/cesdk/android/concepts/edit-modes-1f5b6c/) --- ```kotlin reference-only engine.editor.onStateChanged() .onEach { println("Editor history has changed") } .launchIn(CoroutineScope(Dispatchers.Main)) // Native modes: "Transform", "Crop", "Text" engine.editor.setEditMode("Crop") engine.editor.getEditMode() // "Crop" engine.editor.isInteractionHappening() // Query information about the text cursor position engine.editor.getTextCursorPositionInScreenSpaceX() engine.editor.getTextCursorPositionInScreenSpaceY() ``` The CreativeEditor SDK operates in different states called **Edit Modes**, each designed for a specific type of interaction on the canvas: - `Transform`: this is the default mode which allow to move, resize and manipulate things on the canvas - `Text`: Allows to edit the text elements on the canvas - `Crop`: Allow to Crop media blocks (images, videos, etc...) - `Trim`: Trim the clips in video mode - `Playback`: Play the media (mostly video) in video mode While users typically interact with these modes through the UI (e.g., showing or hiding specific controls based on the active mode), it’s also possible to manage them programmatically via the engine’s API, though this isn’t always required. In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to set and query the editor state in the `editor` API, i.e., what type of content the user is currently able to edit. ## State The editor state consists of the current edit mode, which informs what type of content the user is currently able to edit. The edit mode can be set to either `Transform`, `Crop`, `Text`, or a custom user-defined one. You can also query the intended mouse cursor and the location of the text cursor while editing text. Instead of having to constantly query the state in a loop, you can also be notified when the state has changed to then act on these changes in a callback. ```kotlin fun onStateChanged(): Flow ``` Subscribe to changes to the editor state. - Returns flow of editor state change events. ```kotlin fun setEditMode(editMode: String) ``` Set the edit mode of the editor. An edit mode defines what type of content can currently be edited by the user. Note: The initial edit mode is "Transform". - `editMode`: "Transform", "Crop", "Text", "Playback", "Trim" or a custom value. ```kotlin fun getEditMode(): String ``` Get the current edit mode of the editor. An edit mode defines what type of content can currently be edited by the user. - Returns "Transform", "Crop", "Text", "Playback", "Trim" or a custom value. ```kotlin @UnstableEngineApi fun isInteractionHappening(): Boolean ``` If an user interaction is happening, e.g., a resize edit with a drag handle or a touch gesture. - Returns true if an interaction is happening. ## Cursor ```kotlin fun getTextCursorPositionInScreenSpaceX(): Float ``` Get the current text cursor's x position in screen space. - Returns the text cursor's x position in screen space. ```kotlin fun getTextCursorPositionInScreenSpaceY(): Float ``` Get the current text cursor's y position in screen space. - Returns the text cursor's y position in screen space. ## Full Code Here's the full code: ```kotlin engine.editor.onStateChanged() .onEach { println("Editor history has changed") } .launchIn(CoroutineScope(Dispatchers.Main)) // Native modes: "Transform", "Crop", "Text" engine.editor.setEditMode("Crop") engine.editor.getEditMode() // "Crop" engine.editor.isInteractionHappening() // Query information about the text cursor position engine.editor.getTextCursorPositionInScreenSpaceX() engine.editor.getTextCursorPositionInScreenSpaceY() ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Editing Workflow" description: "Control editing access with Creator and Adopter roles, each offering tailored permissions and UI constraints." platform: android url: "https://img.ly/docs/cesdk/android/concepts/editing-workflow-032d27/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Concepts](https://img.ly/docs/cesdk/android/concepts-c9ff51/) > [Editing Workflow](https://img.ly/docs/cesdk/android/concepts/editing-workflow-032d27/) --- ## Roles User roles allow the CE.SDK to change and adapt its UI layout and functionality to provide the optimal editing experience for a specific purpose. ### Creator The `Creator` role is the most powerful and least restrictive role that is offered by the CE.SDK. Running the editor with this role means that there are no limits to what the user can do with the loaded scene. Elements can be added, moved, deleted, and modified. All types of controls for modifying the selected elements are shown inside of the inspector. ### Adopter The `Adopter` role allows new elements to be added and modified. Existing elements of a scene are only modifiable based on the set of constraints that the `Creator` has manually enabled. This provides the `Adopter` with a simpler interface that is reduced to only the properties that they should be able to change and prevents them from accidentally changing or deleting parts of a design that should not be modified. An example use case for how such a distinction between `Creator` and `Adopter` roles can provide a lot of value is the process of designing business cards. A professional designer (using the `Creator` role) can create a template design of the business card with the company name, logo, colors, etc. They can then use the constraints to make only the name text editable for non-creators. Non-designers (either the employees themselves or the HR department) can then easily open the design in a CE.SDK instance with the `Adopter` role and are able to quickly change the name on the business card and export it for printing, without a designer having to get involved. ### Role customization Roles in the CE.SDK are sets of global scopes and settings. When changing the role via the `setRole` command in the EditorAPI, the internal defaults for that role are applied as described in the previous sections. The CE.SDK and Engine provide a `onRoleChanged` callback subscription on the EditorAPI. Callbacks registered here are invoked whenever the role changes and can be used to configure additional settings or adjust the default scopes and settings. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Events" description: "Subscribe to block creation, update, and deletion events to track changes in your CE.SDK scene." platform: android url: "https://img.ly/docs/cesdk/android/concepts/events-353f97/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Concepts](https://img.ly/docs/cesdk/android/concepts-c9ff51/) > [Events](https://img.ly/docs/cesdk/android/concepts/events-353f97/) --- ```kotlin reference-only val coroutineScope = CoroutineScope(Dispatchers.Main) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Star)) engine.block.setFill(block, fill = engine.block.createFill(FillType.Color)) engine.block.appendChild(parent = page, child = block) engine.event.subscribe(listOf(block)) .onEach { events -> events.forEach { event -> println("Event: ${event.type} ${event.block}") if (engine.block.isValid(event.block)) { val type = engine.block.getType(event.block) println("Block type: $type") } } } .launchIn(coroutineScope) coroutineScope.launch { delay(1000) engine.block.setRotation(block, radians = 0.5F * PI.toFloat()) delay(1000) engine.block.destroy(block) delay(1000) } ``` In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to subscribe to creation, update, and destruction events of design blocks. ## Subscribing to Events The event API provides a single function to subscribe to design block events. The types of events are: - `Created`: The design block was just created. - `Updated`: A property of the design block was updated. - `Destroyed`: The design block was destroyed. Note that a destroyed block will have become invalid and trying to use Block API functions on it will result in an exception. You can always use the Block API's `isValid` function to verify whether a block is valid before use. All events that occur during an engine update are batched, deduplicated, and always delivered at the very end of the engine update. Deduplication means you will receive at most one `Updated` event per block per subscription, even though there could potentially be multiple updates to a block during the engine update. To be clear, this also means the order of the event list provided to your event callback won't reflect the actual order of events within an engine update. ```kotlin fun subscribe(blocks: List = emptyList()): Flow> ``` Subscribe to block life-cycle events - `blocks`: a list of blocks to filter events by. If the list is empty, events for every block are sent. ## Full Code Here's the full code: ```kotlin val coroutineScope = CoroutineScope(Dispatchers.Main) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Star)) engine.block.setFill(block, fill = engine.block.createFill(FillType.Color)) engine.block.appendChild(parent = page, child = block) engine.event.subscribe(listOf(block)) .onEach { events -> events.forEach { event -> println("Event: ${event.type} ${event.block}") if (engine.block.isValid(event.block)) { val type = engine.block.getType(event.block) println("Block type: $type") } } } .launchIn(coroutineScope) coroutineScope.launch { delay(1000) engine.block.setRotation(block, radians = 0.5F * PI.toFloat()) delay(1000) engine.block.destroy(block) delay(1000) } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Headless" description: "Use the engine directly, without any prebuilt UI." platform: android url: "https://img.ly/docs/cesdk/android/concepts/headless-mode-24ab98/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Concepts](https://img.ly/docs/cesdk/android/concepts-c9ff51/) > [Headless Mode](https://img.ly/docs/cesdk/android/concepts/headless-mode-24ab98/) --- ```kotlin file=@cesdk_android_examples/engine-guides-create-scene-from-scratch/CreateSceneFromScratch.kt reference-only import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun createSceneFromScratch( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope( Dispatchers.Main, ).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block = block, shape = engine.block.createShape(ShapeType.Star)) engine.block.setFill(block = block, fill = engine.block.createFill(FillType.Color)) engine.block.appendChild(parent = page, child = block) engine.stop() } ``` Headless Mode lets you use the CreativeEditor SDK's Engine directly. No prebuilt editor UI required. You initialize the Engine, load or build scenes programmatically, and export to images/PDF/video entirely in code. This is ideal for custom UIs, automation, server-triggered rendering, or batch exports. ## What You'll Learn - What "Headless / Engine-only" means and how it differs from the UI editor. - When to choose Headless Mode (and when not to). - How to initialize the Engine for headless use in Kotlin. - How to load/build a scene and modify blocks programmatically. - How to export (PNG/JPEG/PDF, and notes on video) without launching the UI. ## When to Use It **Pick Headless Mode when you need:** - A fully custom UI: You're building your own editing interface or integrating into an existing app layout. - Programmatic rendering: Generate images/PDFs from templates or data—no user interaction. - Automation & batch work: Merge data at scale, pre-render previews, or run background exports. - Export-only flows: Quickly render a scene without ever opening the editor. **Avoid Headless Mode when:** - You want turnkey editing UX out of the box (use the standard Editor for that). - You don't want to create selection, gestures, or tool panels yourself. ### Quick Comparison |Scenario | Headless (Engine-only) | Standard UI Editor | |---|---|---| |Automate design generation from code|✅|❌| |Export scenes without user interaction|✅|❌| |Let users visually edit with ready-made panels|❌|✅| |Build a custom editor interface|✅|⭘ (extend via config)| ### How Headless Mode Works With the prebuilt editors, user actions call the **Engine** API through the UI. In Headless Mode, you start the Engine and work entirely in Kotlin to: - Scene management: create/load scenes; add pages; read/write properties - Blocks: create text/graphics/shapes; set fills, sizes, transforms; append to parents - Assets: register sources, resolve URIs, add media programmatically - Templates & data: load scene archives/JSON, update text variables, swap images - Export: render blocks or pages to PNG/JPEG/PDF (and trigger video exports where appropriate) ### Initialize the Engine in Headless Mode (Kotlin) ```kotlin import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.Engine class HeadlessRenderer { private lateinit var engine: Engine fun startEngine(license: String, userId: String) = CoroutineScope(Dispatchers.Main).launch { engine = Engine.getInstance(id = "ly.img.engine.example") engine.start( license = license, userId = userId ) // Bind offscreen for headless rendering (no UI needed) engine.bindOffscreen(width = 1080, height = 1920) } } ``` This is "headless" because you never instantiate or present the editor UI. You only create an Engine and use its APIs. The `bindOffscreen` method creates an offscreen rendering surface—perfect for headless scenarios where no visible View is needed. ### Create and Export a Scene (Kotlin) Below is a minimal, end-to-end example that works with the preceding class to: - Create a scene with a single page. - Add a rectangle filled with a remote image. - Add a text block. - Export the page as PNG data. ```kotlin import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import ly.img.engine.DesignBlockType import ly.img.engine.FillType import ly.img.engine.MimeType import ly.img.engine.ShapeType import ly.img.engine.SizeMode import java.nio.ByteBuffer data class ExportResult( val pngData: ByteBuffer, val suggestedFilename: String ) suspend fun HeadlessRenderer.buildAndExport(): ExportResult = withContext(Dispatchers.Main) { // 1) Create an empty scene and a page val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) // Set page size engine.block.setWidth(page, value = 800f) engine.block.setHeight(page, value = 600f) // Attach page to scene root engine.block.appendChild(parent = scene, child = page) // 2) Add an image rectangle val rect = engine.block.create(DesignBlockType.Graphic) val shape = engine.block.createShape(ShapeType.Rect) engine.block.setShape(rect, shape = shape) val imageFill = engine.block.createFill(FillType.Image) engine.block.setString( block = imageFill, property = "fill/image/imageFileURI", // Use your own asset URL or registered source URI value = "https://img.ly/static/ubq_samples/sample_1.jpg" ) engine.block.setFill(rect, fill = imageFill) // Position & size the rect engine.block.setPositionX(rect, value = 100f) engine.block.setPositionY(rect, value = 100f) engine.block.setWidth(rect, value = 400f) engine.block.setHeight(rect, value = 300f) engine.block.appendChild(parent = page, child = rect) // 3) Add text val text = engine.block.create(DesignBlockType.Text) engine.block.replaceText(text, text = "Hello, From Headless Mode!") engine.block.setPositionX(text, value = 100f) engine.block.setPositionY(text, value = 450f) engine.block.setWidthMode(text, mode = SizeMode.AUTO) engine.block.appendChild(parent = page, child = text) // 4) Export the page to PNG val pngData = engine.block.export(page, mimeType = MimeType.PNG) ExportResult(pngData = pngData, suggestedFilename = "headless-output.png") } ``` ### Saving the File (optional) After creating the image, you may want to save it. Here is a minimal code example to save the file to the app's files directory and return the file path. ```kotlin import android.content.Context import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import java.io.File suspend fun savePNG(context: Context, result: ExportResult): File = withContext(Dispatchers.IO) { val outputDir = context.filesDir val destinationFile = File(outputDir, result.suggestedFilename) destinationFile.outputStream().channel.use { channel -> channel.write(result.pngData) } destinationFile } ```  The example code creates this `.png` image. Some variations to the preceding code depending on your workflow might be: - Export as different file format such as `.jpeg` or `.pdf` by changing the `mimeType` argument. - Export a sub-tree instead of the entire page. Passing a block's ID exports just that block and its children. ### Working with Assets (Headless) - Default sources: `engine.addDefaultAssetSources()` wires up built-in sources so URIs like `"fill/image/imageFileURI"` can resolve to remote/local assets. - Your own sources: In production, you'll typically register a custom source (from your server, local storage, or device gallery) and then set block properties to URIs your source resolves. - Local files: Use `file://` URLs or Android content URIs that your asset source understands. - Fonts: Bundle or register your fonts the same way. The Engine needs them available for text layout before export. ### Templates & Data-Driven Generation Headless Mode pairs well with: - Scene templates (ZIP/JSON): load and then swap images or set text (update `text/text` or variable placeholders). - Text variables / placeholders: bind your app's data model to text fields and render many variants in a loop. - Batching: loop through data rows → set properties → export → repeat. > **Note:** Keep content keys ("text/text", "fill/image/imageFileURI", etc.) stable across templates or use helper methods, so your code doesn't change when designers iterate. ## Troubleshooting **❌ I'm getting nothing on export (empty data or errors)**: - Verify you export a renderable block (the page or scene root's child). - Ensure remote image URIs are reachable and network permissions are set in AndroidManifest.xml. - For debugging, try a known good URL, then swap. **❌ Images don't load or are missing in output**: - Confirm your asset source can resolve the URI you set. - If using remote URLs, ensure INTERNET permission is declared in AndroidManifest.xml. - Check CORS/network security configuration if using custom domains. **❌ Text looks wrong or uses fallback fonts**: - The Engine needs the exact font used by the text style. Register/bundle the font and ensure it's discoverable before export. **❌ Memory spikes on big batches**: - Reuse a single Engine instance when possible. - Export, write to disk, and release large buffers before rendering the next item. - Call `engine.stop()` when completely done to free resources. ## Next Steps Now that you understand the basics of headless mode, below are some topics to help you expand your knowledge: - [Templates & Variables](https://img.ly/docs/cesdk/android/create-templates/overview-4ebe30/) – Design tokenized templates and drive them from data. - [Exporting](https://img.ly/docs/cesdk/android/export-save-publish/export-82f968/) – PNG/JPEG/PDF exports, plus format options and best practices. - [Standard Editor vs Headless](https://img.ly/docs/cesdk/android/engine-interface-6fb7cf/) – If you need turnkey UI, start here and decide whether to drop to headless for specific flows. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Working With Resources" description: "Preload all resources for blocks or scenes in CE.SDK to improve performance and avoid runtime delays." platform: android url: "https://img.ly/docs/cesdk/android/concepts/resources-a58d71/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Concepts](https://img.ly/docs/cesdk/android/concepts-c9ff51/) > [Resources](https://img.ly/docs/cesdk/android/concepts/resources-a58d71/) --- By default, a scene's resources are loaded on-demand. You can manually trigger the loading of all resources in a scene of for specific blocks by calling `forceLoadResources`. Any set of blocks can be passed as argument and whatever resources these blocks require will be loaded. In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to forcibly pre-load all resources contained in a scene. ```kotlin suspend fun forceLoadResources(blocks: List) ``` Begins loading the resources of the given blocks and their children. If the resource had been loaded earlier and resulted in an error, it will be reloaded. Note: This function is useful for preloading resources before they are needed. Warning: For elements with a source set, all elements in the source set will be loaded. - `blocks`: the blocks whose resources should be loaded. The given blocks don't require to have resources and can have children blocks (e.g. a scene block or a page block). ### Full Code Here's the full code: ```kotlin val scene = requireNotNull(engine.scene.get()) // Forcing all resources of all the blocks in a scene or the resources of graphic block to load engine.block.forceLoadResources(listOf(scene)) val graphics = engine.block.findByType(DesignBlockType) engine.block.forceLoadResources(graphics) ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Scenes" description: "Scenes act as the root container for blocks and define the full design structure in CE.SDK." platform: android url: "https://img.ly/docs/cesdk/android/concepts/scenes-e8596d/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Concepts](https://img.ly/docs/cesdk/android/concepts-c9ff51/) > [Scenes](https://img.ly/docs/cesdk/android/concepts/scenes-e8596d/) --- ```kotlin file=@cesdk_android_examples/engine-guides-modifying-scenes/ModifyingScenes.kt reference-only import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun modifyingScenes( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) // In engine only mode we have to create our own scene and page. if (engine.scene.get() == null) { val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) } // Find all pages in our scene. val pages = engine.block.findByType(DesignBlockType.Page) // Use the first page we found. val page = pages.first() // Create a graphic block and add it to the scene's page. val block = engine.block.create(DesignBlockType.Graphic) val fill = engine.block.createFill(FillType.Image) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setFill(block = block, fill = fill) engine.block.setString( block = fill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/imgly_logo.jpg", ) // The content fill mode 'Contain' ensures the entire image is visible. engine.block.setEnum( block = block, property = "contentFill/mode", value = "Contain", ) engine.block.appendChild(parent = page, child = block) // Zoom the scene's camera on our page. engine.scene.zoomToBlock(page) engine.stop() } ``` Commonly, a scene contains several pages which in turn contain any other blocks such as images and texts. A block (or design block) is the main building unit in CE.SDK. Blocks are organized in a hierarchy through parent-child relationships. A scene is a specialized block that acts as the root of this hierarchy. At any time, the engine holds only a single scene. Loading or creating a scene will replace the current one. ## Interacting With The Scene ### Creating or Using an Existing Scene When using the Engine's API in the context of the CE.SDK editor, there's already an existing scene. You can obtain a handle to this scene by calling the [SceneAPI](https://img.ly/docs/cesdk/android/concepts/scenes-e8596d/)'s `fun get(): DesignBlock?` method. However, when using the Engine on its own you first have to create a scene, e.g. using `fun create(): DesignBlock`. See the [Creating Scenes](https://img.ly/docs/cesdk/android/open-the-editor-23a1db/) guide for more details and options. ```kotlin // In engine only mode we have to create our own scene and page. if (engine.scene.get() == null) { val scene = engine.scene.create() ``` Next, we need a page to place our blocks on. The scene automatically arranges its pages either in a vertical (the default) or horizontal layout. Again in the context of the editor, there's already an existing page. To fetch that page call the [BlockAPI](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/)'s `fun findByType(blockType: DesignBlockType): List` method and use the first element of the returned list. When only using the engine, you have to create a page yourself and append it to the scene. To do that create the page using `fun fun create(): DesignBlock` and append it to the scene with `fun appendChild(parent: DesignBlock, child: DesignBlock)`. ```kotlin val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) } // Find all pages in our scene. val pages = engine.block.findByType(DesignBlockType.Page) // Use the first page we found. val page = pages.first() ``` At this point, you should have a handle to an existing scene as well as a handle to its page. Now it gets interesting when we start to add different types of blocks to the scene's page. ### Modifying the Scene As an example, we create a graphic block using the [BlockAPI](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/)'s `create()` method which we already used for creating our page. Then we set a rect shape and an image fill to this newly created block to give it a visual representation. To see what other kinds of blocks are available see the [Block Types](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/) in the API Reference. ```kotlin // Create a graphic block and add it to the scene's page. val block = engine.block.create(DesignBlockType.Graphic) val fill = engine.block.createFill(FillType.Image) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setFill(block = block, fill = fill) ``` We set a property of our newly created image fill by giving it a URL to reference an image file from. We also make sure the entire image stays visible by setting the block's content fill mode to `'Contain'`. To learn more about block properties check out the [Block Properties](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/) API Reference. ```kotlin engine.block.setString( block = fill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/imgly_logo.jpg", ) // The content fill mode 'Contain' ensures the entire image is visible. engine.block.setEnum( block = block, property = "contentFill/mode", value = "Contain", ) ``` And finally, for our image to be visible we have to add it to our page using `appendChild`. ```kotlin engine.block.appendChild(parent = page, child = block) ``` To frame everything nicely and put it into view we direct the scene's camera to zoom on our page. ```kotlin // Zoom the scene's camera on our page. engine.scene.zoomToBlock(page) ``` ### Full Code Here's the full code snippet for interacting with the scene: ```kotlin import kotlinx.coroutines.* import ly.img.engine.* fun modifyingScenes( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) // In engine only mode we have to create our own scene and page. if (engine.scene.get() == null) { val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) } // Find all pages in our scene. val pages = engine.block.findByType(DesignBlockType.Page) // Use the first page we found. val page = pages.first() // Create a graphic block and add it to the scene's page. val block = engine.block.create(DesignBlockType.Graphic) val fill = engine.block.createFill(FillType.Image) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setFill(block = block, fill = fill) engine.block.setString( block = fill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/imgly_logo.jpg", ) // The content fill mode 'Contain' ensures the entire image is visible. engine.block.setEnum( block = block, property = "contentFill/mode", value = "Contain", ) engine.block.appendChild(parent = page, child = block) // Zoom the scene's camera on our page. engine.scene.zoomToBlock(page) engine.stop() } ``` ## Exploring Scene Contents Using The Scene API Learn how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to explore scene contents through the `scene` API. ```kotlin fun getPages(): List ``` Get the sorted list of pages in the scene. - Returns the sorted list of pages in the scene. ```kotlin fun getCurrentPage(): DesignBlock? ``` Get the current page, i.e., the page of the first selected element if this page is at least 25% visible or, otherwise, the page nearest to the viewport center. - Returns the current page in the scene or null. ```kotlin fun findNearestToViewPortCenterByType(blockType: DesignBlockType): List ``` Finds all blocks with the given type sorted by distance to viewport center. - `blockType`: the type to search for. - Returns a list of block ids sorted by distance to viewport center. ```kotlin fun findNearestToViewPortCenterByKind(blockKind: String): List ``` Finds all blocks with the given kind sorted by distance to viewport center. - `blockKind`: the kind to search for. - Returns a list of block ids sorted by distance to viewport center. ```kotlin fun setDesignUnit(designUnit: DesignUnit) ``` Converts all values of the current scene into the given design unit. - `designUnit`: the new design unit of the scene. ```kotlin fun getDesignUnit(): DesignUnit ``` Returns the design unit of the current scene. - Returns The current design unit. ### Full Code Here's the full code snippet for exploring a scene's contents using the `scene` API: ```kotlin val pages = engine.scene.getPages() val currentPage = engine.scene.getCurrentPage(); val nearestPageByType = engine.scene.findNearestToViewPortCenterByType(DesignBlockType.Page).first(); val nearestImageByKind = engine.sce.findNearestToViewPortCenterByKind("image").first(); engine.scene.setDesignUnit(DesignUnit.PIXEL) /* Now returns DesignUnit.PIXEL */ engine.scene.getDesignUnit() ``` ## Exploring Scene Contents Using The Block API Learn how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to explore scenes through the `block` API. ### Functions ```kotlin fun findAll(): List ``` Return all blocks currently known to the engine. - Returns a list of block ids. ```kotlin fun findAllPlaceholders(): List ``` Return all placeholder blocks in the current scene. - Returns a list of block ids. ```kotlin fun findByType(type: DesignBlockType): List ``` Finds all design blocks with the given type. - `type`: the type to search for. - Returns a list of block ids. ```kotlin fun findByType(type: ShapeType): List ``` Finds all shape blocks with the given type. - `type`: the type to search for. - Returns a list of block ids. ```kotlin fun findByType(type: EffectType): List ``` Finds all effect blocks with the given type. - `type`: the type to search for. - Returns a list of block ids. ```kotlin fun findByType(type: BlurType): List ``` Finds all blur blocks with the given type. - `type`: the type to search for. - Returns a list of block ids. ```kotlin fun findByKind(blockKind: String): List ``` Finds all blocks with the given kind. - `blockKind`: the kind to search for. - Returns a list of block ids. ```kotlin fun findByName(name: String): List ``` Finds all blocks with the given name. - `name`: the name to search for. - Returns a list of block ids. ### Full Code Here's the full code snippet for exploring a scene's contents using the `block` API: ```kotlin val allIds = engine.block.findAll() val allPlaceholderIds = engine.block.findAllPlaceholders() val allPages = engine.block.findByType(DesignBlockType.Page) val allImageFills = engine.block.findByType(FillType.Image) val allStarShapes = engine.block.findByType(ShapeType.Star) val allHalfToneEffects = engine.block.findByType(EffectType.HalfTone) val allUniformBlurs = engine.block.findByType(BlurType.Uniform) val allStickers = engine.block.findByKind("sticker") val ids = engine.block.findByName("someName") ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Undo and History" description: "Manage undo and redo stacks in CE.SDK using multiple histories, callbacks, and API-based controls." platform: android url: "https://img.ly/docs/cesdk/android/concepts/undo-and-history-99479d/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Concepts](https://img.ly/docs/cesdk/android/concepts-c9ff51/) > [Undo and History](https://img.ly/docs/cesdk/android/concepts/undo-and-history-99479d/) --- ```kotlin reference-only // Manage history stacks val newHistory = engine.editor.createHistory() val oldHistory = engine.editor.getActiveHistory() engine.editor.setActiveHistory(newHistory) engine.editor.destroyHistory(oldHistory) engine.editor.onHistoryUpdated() .onEach { println("Editor history updated") } .launchIn(CoroutineScope(Dispatchers.Main)) // Push a new state to the undo stack engine.editor.addUndoStep() // Perform an undo, if possible. if (engine.editor.canUndo()) { engine.editor.undo() } // Perform a redo, if possible. if (engine.editor.canRedo()) { engine.editor.redo() } ``` In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to undo and redo steps in the `editor` API. ## Functions ```kotlin fun createHistory(): History ``` - Brief: Create a history which consists of an undo/redo stack for editing operations. There can be multiple. But only one can be active at a time. - Returns the handle to the created history. ```kotlin fun destroyHistory(history: History) ``` Destroy the given history, returns an error if the handle doesn't refer to a history. - `history`: the history to be destroyed. ```kotlin fun setActiveHistory(history: History) ``` Mark the given history as active, returns an error if the handle doesn't refer to a history. All other histories get cleared from the active state. Undo/redo operations only apply to the active history. - `history`: the history to be marked as active. ```kotlin fun getActiveHistory(): History ``` Get the handle to the currently active history. If there's none it will be created. - Returns the handle to the active history. ```kotlin fun addUndoStep() ``` Adds a new history state to the stack, if undoable changes were made. ```kotlin fun undo() ``` Undo one step in the history if an undo step is available. ```kotlin fun canUndo(): Boolean ``` If an undo step is available. - Returns true if an undo step is available. ```kotlin fun redo() ``` Redo one step in the history if a redo step is available. ```kotlin fun canRedo(): Boolean ``` If a redo step is available. - Returns true if a redo step is available. ```kotlin fun onHistoryUpdated(): Flow ``` Subscribe to changes to the undo/redo history. - Returns flow of history updates. ## Full Code Here's the full code: ```kotlin // Manage history stacks val newHistory = engine.editor.createHistory() val oldHistory = engine.editor.getActiveHistory() engine.editor.setActiveHistory(newHistory) engine.editor.destroyHistory(oldHistory) engine.editor.onHistoryUpdated() .onEach { println("Editor history updated") } .launchIn(CoroutineScope(Dispatchers.Main)) // Push a new state to the undo stack engine.editor.addUndoStep() // Perform an undo, if possible. if (engine.editor.canUndo()) { engine.editor.undo() } // Perform a redo, if possible. if (engine.editor.canRedo()) { engine.editor.redo() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Configuration" description: "Learn how to configure CE.SDK to match your application's functional, visual, and performance requirements." platform: android url: "https://img.ly/docs/cesdk/android/configuration-2c1c3d/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Configuration](https://img.ly/docs/cesdk/android/configuration-2c1c3d/) --- ```kotlin file=@cesdk_android_examples/editor-guides-configuration-basics/BasicEditorSolution.kt reference-only import android.net.Uri import androidx.compose.runtime.Composable import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EngineConfiguration import ly.img.editor.core.engine.EngineRenderTarget import ly.img.editor.rememberForDesign // Add this composable to your NavHost @Composable fun BasicEditorSolution(navController: NavHostController) { val engineConfiguration = EngineConfiguration.rememberForDesign( license = "", // pass null or empty for evaluation mode with watermark userId = "", baseUri = Uri.parse("file:///android_asset/"), sceneUri = EngineConfiguration.defaultDesignSceneUri, renderTarget = EngineRenderTarget.SURFACE_VIEW, ) DesignEditor(engineConfiguration = engineConfiguration) { // You can set result here navController.popBackStack() } } ``` In this example, we will show you how to make basic configurations for the mobile editor. The example is based on the `Design Editor`, however, it is exactly the same for all the other [solutions](https://img.ly/docs/cesdk/android/prebuilt-solutions-d0ed07/). ## Configuration All the basic configuration settings are part of the `EngineConfiguration`. - `license` - the license to activate the [Engine](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) with. ```kotlin highlight-configuration-license license = "", // pass null or empty for evaluation mode with watermark ``` - `userId` - an optional unique ID tied to your application's user. This helps us accurately calculate monthly active users (MAU). Especially useful when one person uses the app on multiple devices with a sign-in feature, ensuring they're counted once. Providing this aids in better data accuracy. The default value is `null`. ```kotlin highlight-configuration-userId userId = "", ``` - `baseUri` - is used to initialize the engine's [setting](https://img.ly/docs/cesdk/android/settings-970c98/) before the editor's [callback](https://img.ly/docs/cesdk/android/user-interface/events-514b70/) is run. It is the foundational URI for constructing absolute paths from relative ones. For example, setting it to the Android assets directory allows loading resources directly from there: `file:///android_asset/`. This URI enables the loading of specific scenes or assets using their relative paths. The default value is pointing at the versioned IMG.LY CDN but it should be changed in production environments. ```kotlin highlight-configuration-baseUri baseUri = Uri.parse("file:///android_asset/"), ``` - `sceneUri` - the [scene](https://img.ly/docs/cesdk/android/open-the-editor/blank-canvas-18ff05/) URI to load content within the editor. Note that this configuration is only available in `EngineConfiguration.rememberFor{solution-name}` helper functions. This URI is used to load the scene in `EdiorConfiguration.onCreate`, therefore, you can configure the scene you load without helper functions too: simply invoke `EditorDefaults.onCreate(engine, sceneUri, eventHandler)` in `EdiorConfiguration.onCreate`. By default, helper functions load the scenes that are available at `EdiorConfiguration.default{solution-name}Scene`. Normally, you should not modify the `sceneUri`, however, you may want to save/restore the editing progress for your customers. If that is the case, you should [save the scene](https://img.ly/docs/cesdk/android/export-save-publish/save-c8b124/) in one of the [callbacks](https://img.ly/docs/cesdk/android/user-interface/events-514b70/), then provide the URI of the newly saved scene when your customer opens the editor next time. ```kotlin highlight-configuration-sceneUri sceneUri = EngineConfiguration.defaultDesignSceneUri, ``` - `renderTarget` - the target which should be used by the [Engine](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) to render. The engine is able to render on both [SurfaceView](https://developer.android.com/reference/android/view/SurfaceView) and [TextureView](https://developer.android.com/reference/android/view/TextureView). The default value is `EngineRenderTarget.SURFACE_VIEW`. ```kotlin highlight-configuration-renderTarget renderTarget = EngineRenderTarget.SURFACE_VIEW, ``` ## Full Code Here's the full code: ```kotlin import android.net.Uri import androidx.compose.runtime.Composable import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EngineConfiguration import ly.img.editor.core.engine.EngineRenderTarget import ly.img.editor.rememberForDesign // Add this composable to your NavHost @Composable fun BasicEditorSolution(navController: NavHostController) { val engineConfiguration = EngineConfiguration.rememberForDesign( license = "", userId = "", baseUri = Uri.parse("file:///android_asset/"), sceneUri = EngineConfiguration.defaultDesignSceneUri, renderTarget = EngineRenderTarget.SURFACE_VIEW, ) DesignEditor(engineConfiguration = engineConfiguration) { // You can set result here navController.popBackStack() } } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Conversion" description: "Convert designs into different formats such as PDF, PNG, MP4, and more using CE.SDK tools." platform: android url: "https://img.ly/docs/cesdk/android/conversion-c3fbb3/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Conversion](https://img.ly/docs/cesdk/android/conversion-c3fbb3/) --- --- ## Related Pages - [Overview](https://img.ly/docs/cesdk/android/conversion/overview-44dc58/) - Convert designs into different formats such as PDF, PNG, MP4, and more using CE.SDK tools. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Overview" description: "Convert designs into different formats such as PDF, PNG, MP4, and more using CE.SDK tools." platform: android url: "https://img.ly/docs/cesdk/android/conversion/overview-44dc58/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Conversion](https://img.ly/docs/cesdk/android/conversion-c3fbb3/) > [Overview](https://img.ly/docs/cesdk/android/conversion/overview-44dc58/) --- CreativeEditor SDK (CE.SDK) allows you to export designs into a variety of formats, making it easy to prepare assets for web publishing, printing, storage, and other workflows. You can trigger conversions either programmatically through the SDK’s API or manually using the built-in export options available in the UI. [Explore Demos](https://img.ly/showcases/cesdk?tags=android) [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) ## Supported Input and Output Formats CE.SDK accepts a range of input formats when working with designs, including: When it comes to exporting or converting designs, the SDK supports the following output formats: Each format serves different use cases, giving you the flexibility to adapt designs for your application’s needs. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Create Compositions" description: "Combine and arrange multiple elements to create complex, multi-page, or layered design compositions." platform: android url: "https://img.ly/docs/cesdk/android/create-composition-db709c/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Compositions](https://img.ly/docs/cesdk/android/create-composition-db709c/) --- --- ## Related Pages - [Overview](https://img.ly/docs/cesdk/android/create-composition/overview-5b19c5/) - Combine and arrange multiple elements to create complex, multi-page, or layered design compositions. - [Positioning and Alignment](https://img.ly/docs/cesdk/android/insert-media/position-and-align-cc6b6a/) - Precisely position, align, and distribute objects using guides, snapping, and alignment tools. - [Group and Ungroup Objects](https://img.ly/docs/cesdk/android/create-composition/group-and-ungroup-62565a/) - Group multiple elements to move or transform them together; ungroup to edit them individually. - [Layer Management](https://img.ly/docs/cesdk/android/create-composition/layer-management-18f07a/) - Organize design elements using a layer stack for precise control over stacking and visibility. - [Blend Modes](https://img.ly/docs/cesdk/android/create-composition/blend-modes-ad3519/) - Apply blend modes to elements to control how colors and layers interact visually. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Blend Modes" description: "Apply blend modes to elements to control how colors and layers interact visually." platform: android url: "https://img.ly/docs/cesdk/android/create-composition/blend-modes-ad3519/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Compositions](https://img.ly/docs/cesdk/android/create-composition-db709c/) > [Blend Modes](https://img.ly/docs/cesdk/android/create-composition/blend-modes-ad3519/) --- ```kotlin reference-only engine.block.supportsOpacity(image) engine.block.setOpacity(image, value = 0.5F) engine.block.getOpacity(image) engine.block.supportsBlendMode(image) engine.block.setBlendMode(image, blendMode = BlendMode.MULTIPLY) engine.block.getBlendMode(image) if (engine.block.supportsBackgroundColor(image)) { engine.block.setBackgroundColor(page, Color.fromRGBA(r = 1F, g = 0F, b = 0F, a = 1F) // Red engine.block.getBackgroundColor(page) engine.block.setBackgroundColorEnabled(page, enabled = true) engine.block.isBackgroundColorEnabled(page) } ``` In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to modify a blocks appearance through the `block` API. ## Common Properties Common properties are properties that occur on multiple block types. For instance, fill color properties are available for all the shape blocks and the text block. That's why we built convenient setter and getter functions for these properties. So you don't have to use the generic setters and getters and don't have to provide a specific property path. There are also `has*` functions to query if a block supports a set of common properties. ### Opacity Set the translucency of the entire block. ```kotlin fun supportsOpacity(block: DesignBlock): Boolean ``` Query if the given block has an opacity. - `block`: the block to query. - Returns true if the block has an opacity, false otherwise. ```kotlin fun setOpacity( block: DesignBlock, @FloatRange(from = 0.0, to = 1.0) value: Float, ) ``` Set the opacity of the given design block. Required scope: "layer/opacity" - `block`: the block whose opacity should be set. - `value`: the opacity to be set. The valid range is 0 to 1. ```kotlin @FloatRange(from = 0.0, to = 1.0) fun getOpacity(block: DesignBlock): Float ``` Get the opacity of the given design block. - `block`: the block whose opacity should be queried. - Returns the opacity. ### Blend Mode Define the blending behaviour of a block. ```kotlin fun supportsBlendMode(block: DesignBlock): Boolean ``` Query if the given block has a blend mode. - `block`: the block to query. - Returns true if the block has a blend mode, false otherwise. ```kotlin fun setBlendMode( block: DesignBlock, blendMode: BlendMode, ) ``` Set the blend mode of the given design block. Required scope: "layer/blendMode" - `block`: the block whose blend mode should be set. - `blendMode`: the blend mode to be set. ```kotlin fun getBlendMode(block: DesignBlock): BlendMode ``` Get the blend mode of the given design block. - `block`: the block whose blend mode should be queried. - Returns the blend mode. ### Background Color Manipulate the background of a block. To understand the difference between fill and background color take the text block. The glyphs of the text itself are colored by the fill color. The rectangular background given by the bounds of the block on which the text is drawn is colored by the background color. ```kotlin fun supportsBackgroundColor(block: DesignBlock): Boolean ``` Query if the given block has background color properties. - `block`: the block to query. - Returns true if the block has background color properties, false otherwise. ```kotlin fun setBackgroundColor( block: DesignBlock, color: RGBAColor, ) ``` Set the background color of the given design block. Required scope: "fill/change" - `block`: the block whose background color should be set. - `color`: the color to set. ```kotlin fun getBackgroundColor(block: DesignBlock): RGBAColor ``` Get the background color of the given design block. - `block`: the block whose background color should be queried. - Returns the background color. ```kotlin fun setBackgroundColorEnabled( block: DesignBlock, enabled: Boolean, ) ``` Enable or disable the background of the given design block. Required scope: "fill/change" - `block`: the block whose background should be enabled or disabled. - `enabled`: if true, the background will be enabled. ```kotlin fun isBackgroundColorEnabled(block: DesignBlock): Boolean ``` Query if the background of the given design block is enabled. - `block`: the block whose background state should be queried. - Returns true if background is enabled, false otherwise. ## Full Code Here's the full code: ```kotlin engine.block.supportsOpacity(image) engine.block.setOpacity(image, value = 0.5F) engine.block.getOpacity(image) engine.block.supportsBlendMode(image) engine.block.setBlendMode(image, blendMode = BlendMode.MULTIPLY) engine.block.getBlendMode(image) if (engine.block.supportsBackgroundColor(image)) { engine.block.setBackgroundColor(page, Color.fromRGBA(r = 1F, g = 0F, b = 0F, a = 1F) // Red engine.block.getBackgroundColor(page) engine.block.setBackgroundColorEnabled(page, enabled = true) engine.block.isBackgroundColorEnabled(page) } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Group and Ungroup Objects" description: "Group multiple elements to move or transform them together; ungroup to edit them individually." platform: android url: "https://img.ly/docs/cesdk/android/create-composition/group-and-ungroup-62565a/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Compositions](https://img.ly/docs/cesdk/android/create-composition-db709c/) > [Group and Ungroup Objects](https://img.ly/docs/cesdk/android/create-composition/group-and-ungroup-62565a/) --- ```kotlin reference-only // Create blocks and append to scene val member1 = engine.block.create(DesignBlockType.Graphic) val member2 = engine.block.create(DesignBlockType.Graphic) engine.block.appendChild(scene, child = member1) engine.block.appendChild(scene, child = member2) // Check whether the blocks may be grouped if (engine.block.isGroupable(listOf(member1, member2))) { val group = engine.block.group(listOf(member1, member2)) engine.block.setSelected(group, selected = true) engine.block.enterGroup(group) engine.block.setSelected(member1, selected = true) engine.block.exitGroup(member1) engine.block.ungroup(group) } ``` In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to group blocks through the `block` API. Groups form a cohesive unit. ## Grouping Multiple blocks can be grouped together to form a cohesive unit. A group being a block, it can itself be part of a group. > **Note:** **What cannot be grouped*** A scene > * A block that already is part of a group ```kotlin fun isGroupable(blocks: List): Boolean ``` Confirms that a given set of blocks can be grouped together. - `blocks`: a non-empty array of block ids. - Returns whether the blocks can be grouped together. ```kotlin fun group(blocks: List): DesignBlock ``` Group blocks together. - `blocks`: a non-empty array of block ids. - Returns the block id of the created group. ```kotlin fun ungroup(block: DesignBlock) ``` Ungroups a group. - `block`: the group id from a previous call to `group`. ```kotlin fun enterGroup(block: DesignBlock) ``` Changes selection from selected group to a block within that group. Nothing happens if `block` is not a group. Required scope: "editor/select" - `block`: the group id from a previous call to `group`. ```kotlin fun exitGroup(block: DesignBlock) ``` Changes selection from a group's selected block to that group. Nothing happens if `block` is not a group. Required scope: "editor/select" - `block`: a block id. ## Full Code Here's the full code: ```kotlin // Create blocks and append to scene val member1 = engine.block.create(DesignBlockType.Graphic) val member2 = engine.block.create(DesignBlockType.Graphic) engine.block.appendChild(scene, child = member1) engine.block.appendChild(scene, child = member2) // Check whether the blocks may be grouped if (engine.block.isGroupable(listOf(member1, member2))) { val group = engine.block.group(listOf(member1, member2)) engine.block.setSelected(group, selected = true) engine.block.enterGroup(group) engine.block.setSelected(member1, selected = true) engine.block.exitGroup(member1) engine.block.ungroup(group) } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Layer Management" description: "Organize design elements using a layer stack for precise control over stacking and visibility." platform: android url: "https://img.ly/docs/cesdk/android/create-composition/layer-management-18f07a/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Compositions](https://img.ly/docs/cesdk/android/create-composition-db709c/) > [Layers](https://img.ly/docs/cesdk/android/create-composition/layer-management-18f07a/) --- ```kotlin reference-only engine.block.insertChild(parent = page, child = block, index = 0) val parent = engine.block.getParent(block) val childIds = engine.block.getChildren(block) engine.block.appendChild(parent = parent, child = block) ``` In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to modify the hierarchy of blocks through the `block` API. ## Manipulate the hierarchy of blocks > **Note:** Only blocks that are direct or indirect children of a `page` block are > rendered. Scenes without any `page` child may not be properly displayed by the > CE.SDK editor. ```kotlin fun getParent(block: DesignBlock): DesignBlock? ``` Query a block's parent. - `block`: the block to query. - Returns the parent's handle or null if the block has no parent. ```kotlin fun getChildren(block: DesignBlock): List ``` Get all children of the given block. Children are sorted in their rendering order: Last child is rendered in front of other children. - `block`: the block to query. - Returns a list of block ids. ```kotlin fun insertChild( parent: DesignBlock, child: DesignBlock, index: Int, ) ``` Insert a new or existing child at a certain position in the parent's children. Required scope: "editor/add" - `parent`: the block to update. - `child`: the child to insert. Can be an existing child of `parent`. - `index`: the index to insert or move to. ```kotlin fun appendChild( parent: DesignBlock, child: DesignBlock, ) ``` Appends a new or existing child to a block's children. Required scope: "editor/add" - `parent`: the block to update. - `child`: the child to insert. Can be an existing child of `parent`. When adding a block to a new parent, it is automatically removed from its previous parent. ## Full Code Here's the full code: ```kotlin engine.block.insertChild(parent = page, child = block, index = 0) val parent = engine.block.getParent(block) val childIds = engine.block.getChildren(block) engine.block.appendChild(parent = parent, child = block) ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Overview" description: "Combine and arrange multiple elements to create complex, multi-page, or layered design compositions." platform: android url: "https://img.ly/docs/cesdk/android/create-composition/overview-5b19c5/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Compositions](https://img.ly/docs/cesdk/android/create-composition-db709c/) > [Overview](https://img.ly/docs/cesdk/android/create-composition/overview-5b19c5/) --- In CreativeEditor SDK (CE.SDK), a *composition* is an arrangement of multiple design elements—such as images, text, shapes, graphics, and effects—combined into a single, cohesive visual layout. Unlike working with isolated elements, compositions allow you to design complex, multi-element visuals that tell a richer story or support more advanced use cases. All composition processing is handled entirely on the client side, ensuring fast, secure, and efficient editing without requiring server infrastructure. You can use compositions to create a wide variety of projects, including social media posts, marketing materials, collages, and multi-page exports like PDFs. Whether you are building layouts manually through the UI or generating them dynamically with code, compositions give you the flexibility and control to design at scale. [Explore Demos](https://img.ly/showcases/cesdk?tags=android) [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) ## Exporting Compositions CE.SDK compositions can be exported in several formats: --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Create Templates" description: "Learn how to create, import, and manage reusable templates to streamline design creation in CE.SDK." platform: android url: "https://img.ly/docs/cesdk/android/create-templates-3aef79/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Use Templates](https://img.ly/docs/cesdk/android/create-templates-3aef79/) --- --- ## Related Pages - [Overview](https://img.ly/docs/cesdk/android/create-templates/overview-4ebe30/) - Learn how to create, import, and manage reusable templates to streamline design creation in CE.SDK. - [Create Templates From Scratch in Android (Kotlin)](https://img.ly/docs/cesdk/android/create-templates/from-scratch-663cda/) - Build and save reusable CE.SDK templates programmatically in Android using Kotlin. - [Dynamic Content](https://img.ly/docs/cesdk/android/create-templates/add-dynamic-content-53fad7/) - Use variables and placeholders to inject dynamic data into templates at design or runtime. - [Lock the Template](https://img.ly/docs/cesdk/android/create-templates/lock-131489/) - Restrict editing access to specific elements or properties in a template to enforce design rules. - [Overview](https://img.ly/docs/cesdk/android/use-templates/overview-ae74e1/) - Learn how to browse, apply, and dynamically populate templates in CE.SDK to streamline design workflows. - [Apply a Template](https://img.ly/docs/cesdk/android/use-templates/apply-template-35c73e/) - Learn how to apply template scenes via API in the CreativeEditor SDK. - [Generate From Templates](https://img.ly/docs/cesdk/android/use-templates/generate-334e15/) - Learn how to load and populate CE.SDK templates in Kotlin for Android applications. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Dynamic Content" description: "Use variables and placeholders to inject dynamic data into templates at design or runtime." platform: android url: "https://img.ly/docs/cesdk/android/create-templates/add-dynamic-content-53fad7/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Use Templates](https://img.ly/docs/cesdk/android/create-templates-3aef79/) > [Insert Dynamic Content](https://img.ly/docs/cesdk/android/create-templates/add-dynamic-content-53fad7/) --- --- ## Related Pages - [Text Variables](https://img.ly/docs/cesdk/android/create-templates/add-dynamic-content/text-variables-7ecb50/) - Define dynamic text elements that can be populated with custom values during design generation. - [Placeholders](https://img.ly/docs/cesdk/android/create-templates/add-dynamic-content/placeholders-d9ba8a/) - Use placeholders to mark editable image, video, or text areas within a locked template layout. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Placeholders" description: "Use placeholders to mark editable image, video, or text areas within a locked template layout." platform: android url: "https://img.ly/docs/cesdk/android/create-templates/add-dynamic-content/placeholders-d9ba8a/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Use Templates](https://img.ly/docs/cesdk/android/create-templates-3aef79/) > [Insert Dynamic Content](https://img.ly/docs/cesdk/android/create-templates/add-dynamic-content-53fad7/) > [Placeholders](https://img.ly/docs/cesdk/android/create-templates/add-dynamic-content/placeholders-d9ba8a/) --- ```kotlin reference-only // Check if block supports placeholder behavior if (engine.block.supportsPlaceholderBehavior(block)) { // Enable the placeholder behavior engine.block.setPlaceholderBehaviorEnabled(block, enabled = true) val placeholderBehaviorIsEnabled = engine.block.isPlaceholderBehaviorEnabled(block) // Enable the placeholder capabilities (interaction in Adopter mode) engine.block.setPlaceholderEnabled(block, enabled = true) val placeholderIsEnabled = engine.block.isPlaceholderEnabled(block) // Check if block supports placeholder controls if (engine.block.supportsPlaceholderControls(block)) { // Enable the visibility of the placeholder overlay pattern engine.block.setPlaceholderControlsOverlayEnabled(block, enabled = true) val overlayEnabled = engine.block.isPlaceholderControlsOverlayEnabled(block) // Enable the visibility of the placeholder button engine.block.setPlaceholderControlsButtonEnabled(block, enabled = true) val buttonEnabled = engine.block.isPlaceholderControlsButtonEnabled(block) } } ``` In this example, we will demonstrate how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to manage placeholder behavior and controls through the block Api. ## Placeholder Behavior and Controls ```kotlin fun supportsPlaceholderBehavior(block: DesignBlock): Boolean ``` Query whether the block supports placeholder behavior. - `block`: the block to query. - Returns whether the block supports placeholder behavior. ```kotlin fun setPlaceholderBehaviorEnabled( block: DesignBlock, enabled: Boolean, ) ``` Enable or disable the placeholder behavior for a block. - `block`: the block whose placeholder behavior should be enabled or disabled. - `enabled`: Whether the placeholder behavior should be enabled or disabled. ```kotlin fun isPlaceholderBehaviorEnabled(block: DesignBlock): Boolean ``` Query whether the placeholder behavior for a block is enabled. - `block`: the block whose placeholder behavior state should be queried. - Returns the enabled state of the block's placeholder behavior. ```kotlin fun setPlaceholderEnabled( block: DesignBlock, enabled: Boolean, ) ``` Enable or disable the placeholder function for a block. - `block`: the block whose placeholder function should be enabled or disabled. - `enabled`: whether the function should be enabled or disabled. ```kotlin fun isPlaceholderEnabled(block: DesignBlock): Boolean ``` Query whether the placeholder function for a block is enabled. - `block`: the block whose placeholder function state should be queried. - Returns the enabled state of the placeholder function. ```kotlin fun supportsPlaceholderControls(block: DesignBlock): Boolean ``` Checks whether the block supports placeholder controls. - `block`: The block to query. - Returns whether the block supports placeholder controls. ```kotlin fun setPlaceholderControlsOverlayEnabled( block: DesignBlock, enabled: Boolean, ) ``` Enable or disable the visibility of the placeholder overlay pattern for a block. - `block`: The block whose placeholder overlay should be enabled or disabled. - `enabled`: Whether the placeholder overlay should be shown or not. ```kotlin fun isPlaceholderControlsOverlayEnabled(block: DesignBlock): Boolean ``` Query whether the placeholder overlay pattern for a block is shown. - `block`: The block whose placeholder overlay visibility state should be queried. - Returns the visibility state of the block's placeholder overlay pattern. ```kotlin fun setPlaceholderControlsButtonEnabled( block: DesignBlock, enabled: Boolean, ) ``` Enable or disable the visibility of the placeholder button for a block. - `block`: The block whose placeholder button should be shown or not. - `enabled`: Whether the placeholder button should be shown or not. ```kotlin fun isPlaceholderControlsButtonEnabled(block: DesignBlock): Boolean ``` Query whether the placeholder button for a block is shown. - `block`: The block whose placeholder button visibility state should be queried. - Returns the visibility state of the block's placeholder button. ## Full Code Here's the full code: ```kotlin // Check if block supports placeholder behavior if (engine.block.supportsPlaceholderBehavior(block)) { // Enable the placeholder behavior engine.block.setPlaceholderBehaviorEnabled(block, enabled = true) val placeholderBehaviorIsEnabled = engine.block.isPlaceholderBehaviorEnabled(block) // Enable the placeholder capabilities (interaction in Adopter mode) engine.block.setPlaceholderEnabled(block, enabled = true) val placeholderIsEnabled = engine.block.isPlaceholderEnabled(block) // Check if block supports placeholder controls if (engine.block.supportsPlaceholderControls(block)) { // Enable the visibility of the placeholder overlay pattern engine.block.setPlaceholderControlsOverlayEnabled(block, enabled = true) val overlayEnabled = engine.block.isPlaceholderControlsOverlayEnabled(block) // Enable the visibility of the placeholder button engine.block.setPlaceholderControlsButtonEnabled(block, enabled = true) val buttonEnabled = engine.block.isPlaceholderControlsButtonEnabled(block) } } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Text Variables" description: "Define dynamic text elements that can be populated with custom values during design generation." platform: android url: "https://img.ly/docs/cesdk/android/create-templates/add-dynamic-content/text-variables-7ecb50/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Use Templates](https://img.ly/docs/cesdk/android/create-templates-3aef79/) > [Insert Dynamic Content](https://img.ly/docs/cesdk/android/create-templates/add-dynamic-content-53fad7/) > [Text Variables](https://img.ly/docs/cesdk/android/create-templates/add-dynamic-content/text-variables-7ecb50/) --- ```kotlin reference-only // Query all variables val variableNames = engine.variable.findAll() // Set, get and remove a variable engine.variable.set(key = "name", value = "Chris") val name = engine.variable.get(key = "name") // Chris engine.variable.remove(key = "name") val block = engine.block.create(DesignBlockType.Graphic) engine.block.referencesAnyVariables(block) ``` In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to modify variables through the `variable` API. The `variable` API lets you set or get the contents of variables that exist in your scene. ## Functions ```kotlin fun findAll(): List ``` Get all text variables currently stored in the engine. - Returns a list of variable names. ```kotlin fun set( key: String, value: String, ) ``` Set a text variable. - `key`: the variable's key. - `value`: the text to replace the variable with. ```kotlin fun get(key: String): String ``` Get a text variable. - `key`: the variable's key. - Returns the text value of the variable. ```kotlin fun remove(key: String) ``` Destroy a text variable. - `key`: the variable's key. ```kotlin fun referencesAnyVariables(block: DesignBlock): Boolean ``` Checks whether the given block references any variables. Doesn't check the block's children. - `block`: the block to query. - Returns true if the block references variables, false otherwise. ## Localizing Variable Keys (CE.SDK only) You can show localized labels for the registered variables to your users by adding a corresponding label property to the object stored at `i18n..variables..label` in the configuration. Otherwise, the name used in `variable.setString()` will be shown.  ## Full Code Here's the full code: ```kotlin // Query all variables val variableNames = engine.variable.findAll() // Set, get and remove a variable engine.variable.set(key = "name", value = "Chris") val name = engine.variable.get(key = "name") // Chris engine.variable.remove(key = "name") val block = engine.block.create(DesignBlockType.Graphic) engine.block.referencesAnyVariables(block) ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Create Templates From Scratch in Android (Kotlin)" description: "Build and save reusable CE.SDK templates programmatically in Android using Kotlin." platform: android url: "https://img.ly/docs/cesdk/android/create-templates/from-scratch-663cda/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Use Templates](https://img.ly/docs/cesdk/android/create-templates-3aef79/) > [Create From Scratch](https://img.ly/docs/cesdk/android/create-templates/from-scratch-663cda/) --- Templates define a reusable design pattern—text regions, image placeholders, and locked brand elements that your app can populate at runtime. This guide walks you through creating a template **from scratch** in Android using Kotlin, enabling variable bindings, and saving the result as a string or archive for reuse. ## What You'll Learn - Differences between **templates** and **scenes**. - Programmatically build a template scene. - Enable **variable** bindings for dynamic text. - Save templates to **string** or **archive**. - Store basic **metadata** for library use. ## When to Use It Choose this guide when you need to **author** templates programmatically for things such as: - Automation pipelines - Unit tests - Code‑generated layouts. Prefer the web-based CE.SDK editors if your goal is to let designers craft rich templates visually including: - Marking placeholders. - Locking styles. - Setting edit permissions. ## Templates vs Scenes - **Scene**: a complete document (pages, blocks, assets). Edit and export it directly. - **Template**: a reusable pattern applied to scenes; often includes placeholders and variables to control what's editable versus locked. ## Create Templates Programmatically The web-based CE.SDK editors include built-in template logic and UI. You can use them to: - Mark blocks as placeholders - Bind variables - Assign granular edit permissions. For most teams, this is the recommended path to author templates. This guide shows how to achieve similar results **in Android/Kotlin**, which is useful for code‑driven generation, CI pipelines, or dynamic authoring. In the code below: - You'll create a scene. - Add a page. - Insert a text block bound to a variable - Add an image block. ```kotlin import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) // Text block bound to a variable (e.g., {{name}}) val text = engine.block.create(DesignBlockType.Text) engine.block.setString(text, property = "text/text", value = "{{name}}") engine.block.setPositionX(text, value = 0.1F) engine.block.setPositionY(text, value = 0.1F) engine.block.appendChild(parent = page, child = text) // Image block for dynamic content val image = engine.block.create(DesignBlockType.Graphic) val shape = engine.block.createShape(ShapeType.Rect) engine.block.setShape(image, shape = shape) val imageFill = engine.block.createFill(FillType.Image) engine.block.setFill(image, fill = imageFill) engine.block.setWidth(image, value = 300F) engine.block.setHeight(image, value = 200F) engine.block.setPositionX(image, value = 0.1F) engine.block.setPositionY(image, value = 0.3F) engine.block.appendChild(parent = page, child = image) ``` ## Binding Variables - Use variables for [text substitution](https://img.ly/docs/cesdk/android/create-templates/add-dynamic-content/text-variables-7ecb50/). - Use named blocks or image fills for media that users swap at runtime. Define a variable in text using curly brackets. The variable can be the entire string or part of a string, such as `"Hello, {{guest_name}}"`. To populate variables at runtime: ```kotlin import ly.img.engine.Engine // Populate the template with actual data engine.variable.set(key = "name", value = "John Smith") engine.variable.set(key = "guest_name", value = "Alice") ``` For image replacement in templates, use named blocks: ```kotlin import ly.img.engine.Engine // Give the image block a name for easy lookup engine.block.setString(imageBlock, property = "name", value = "profile-photo") // Later, find and replace the image fill val blocks = engine.block.findByType(DesignBlockType.Graphic) for (block in blocks) { val name = engine.block.getString(block, property = "name") if (name == "profile-photo") { val fill = engine.block.getFill(block) engine.block.setString(fill, property = "fill/image/imageFileURI", value = "https://example.com/photo.jpg") } } ``` ## Saving Templates Templates are scenes with some extra settings. Save templates: - Use the same logic as for scenes. - Save as a **string** for a lightweight file: the template needs to be able to resolve all asset URLs at runtime. - Save as an **archive** for a self-contained, portable file: bundles the assets into the file. ### Save as String ```kotlin import ly.img.engine.Engine val sceneAsString = engine.scene.saveToString(scene = scene) // Persist to your DB or send to a backend ``` ### Save as Archive ```kotlin import android.content.Context import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import ly.img.engine.Engine import java.io.File suspend fun saveTemplateAsArchive( engine: Engine, context: Context, scene: Int ): File { val blob = engine.scene.saveToArchive(scene = scene) // Save to file val file = File(context.filesDir, "template_${System.currentTimeMillis()}.cesdk") withContext(Dispatchers.IO) { file.outputStream().channel.use { channel -> channel.write(blob) } } return file } ``` Once you've created the string or data blob, use standard methods to persist it. ## Complete Example Here's a complete example that creates a template from scratch: ```kotlin import android.content.Context import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import kotlinx.coroutines.withContext import ly.img.engine.Color import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType import ly.img.engine.SizeMode import java.io.File fun createTemplateFromScratch( context: Context, license: String, userId: String ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.template") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) try { // Create scene and page val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) engine.block.setWidth(page, value = 1080F) engine.block.setHeight(page, value = 1920F) // Background (brand color that stays locked) val background = engine.block.create(DesignBlockType.Graphic) val bgShape = engine.block.createShape(ShapeType.Rect) engine.block.setShape(background, shape = bgShape) val bgFill = engine.block.createFill(FillType.Color) val bgColor = Color.fromRGBA(r = 0.95F, g = 0.95F, b = 0.98F, a = 1.0F) engine.block.setColor(bgFill, property = "fill/color/value", color = bgColor) engine.block.setFill(background, fill = bgFill) engine.block.appendChild(parent = page, child = background) engine.block.fillParent(background) engine.block.sendToBack(background) // Title text with variable val title = engine.block.create(DesignBlockType.Text) engine.block.setString(title, property = "text/text", value = "{{product_name}}") engine.block.setTextFontSize(title, fontSize = 48F) engine.block.setWidthMode(title, mode = SizeMode.AUTO) engine.block.setHeightMode(title, mode = SizeMode.AUTO) engine.block.setPositionX(title, value = 100F) engine.block.setPositionY(title, value = 200F) engine.block.appendChild(parent = page, child = title) // Description text with variable val description = engine.block.create(DesignBlockType.Text) engine.block.setString(description, property = "text/text", value = "{{description}}") engine.block.setTextFontSize(description, fontSize = 24F) engine.block.setWidthMode(description, mode = SizeMode.AUTO) engine.block.setHeightMode(description, mode = SizeMode.AUTO) engine.block.setPositionX(description, value = 100F) engine.block.setPositionY(description, value = 300F) engine.block.appendChild(parent = page, child = description) // Product image placeholder (named for easy replacement) val productImage = engine.block.create(DesignBlockType.Graphic) val imageShape = engine.block.createShape(ShapeType.Rect) engine.block.setShape(productImage, shape = imageShape) val imageFill = engine.block.createFill(FillType.Image) // Set a placeholder image URL engine.block.setString( imageFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg" ) engine.block.setFill(productImage, fill = imageFill) // Name it for easy lookup later engine.block.setString(productImage, property = "name", value = "product-image") engine.block.setWidth(productImage, value = 600F) engine.block.setHeight(productImage, value = 600F) engine.block.setPositionX(productImage, value = 240F) engine.block.setPositionY(productImage, value = 600F) engine.block.appendChild(parent = page, child = productImage) // Price text with variable val price = engine.block.create(DesignBlockType.Text) engine.block.setString(price, property = "text/text", value = "${{price}}") engine.block.setTextFontSize(price, fontSize = 36F) engine.block.setTextColor( price, color = Color.fromRGBA(r = 0.2F, g = 0.6F, b = 0.2F, a = 1.0F) ) engine.block.setWidthMode(price, mode = SizeMode.AUTO) engine.block.setHeightMode(price, mode = SizeMode.AUTO) engine.block.setPositionX(price, value = 100F) engine.block.setPositionY(price, value = 1350F) engine.block.appendChild(parent = page, child = price) // Save as string val templateString = engine.scene.saveToString(scene = scene) println("Template saved as string (${templateString.length} characters)") // Save to file (for demonstration) val stringFile = File(context.filesDir, "template_string.scene") withContext(Dispatchers.IO) { stringFile.writeText(templateString) } // Save as archive (includes all assets) val archiveBlob = engine.scene.saveToArchive(scene = scene) val archiveFile = File(context.filesDir, "template_archive.cesdk") withContext(Dispatchers.IO) { archiveFile.outputStream().channel.use { channel -> channel.write(archiveBlob) } } println("Template saved as archive: ${archiveFile.absolutePath}") // Example: Populate the template with actual data engine.variable.set(key = "product_name", value = "Premium Coffee Mug") engine.variable.set(key = "description", value = "Hand-crafted ceramic, dishwasher safe") engine.variable.set(key = "price", value = "24.99") println("Template created and saved successfully!") } finally { // Note: Don't stop the engine here if you want to keep using it // engine.stop() } } ``` ## Add Template Metadata Like other assets, you can: - Load templates into the [asset library](https://img.ly/docs/cesdk/android/import-media/asset-library-65d6c4/). - Store metadata in your CMS or local database. - Use the saved metadata later when you register the template as an `AssetDefinition` in an `AssetSource`. That way the UI can display names, thumbnails, and categories. Example metadata structure: ```kotlin data class TemplateMetadata( val id: String, val name: String, val description: String, val thumbnailUrl: String, val category: String, val tags: List, val variables: List, val createdAt: Long, val updatedAt: Long ) ``` ## Lock Template Properties Templates can restrict editing at runtime so that users don't edit any part of the design that should remain static. To protect integrity, you can lock properties such as: - Position - Size - Color - Fill The guide for [locking templates](https://img.ly/docs/cesdk/android/create-templates/lock-131489/) provides details on which properties are lockable and how to set up editor and adopter rules. Example of locking a block: ```kotlin import ly.img.engine.Engine // Lock the background so users can't move or resize it engine.block.setScopeEnabled(background, key = "layer/move", enabled = false) engine.block.setScopeEnabled(background, key = "layer/resize", enabled = false) engine.block.setScopeEnabled(background, key = "fill/change", enabled = false) ``` ## Load and Use Templates Once you've created and saved a template, load it back and populate with data: ### Load from String ```kotlin import android.net.Uri import ly.img.engine.Engine // Load template from string val scene = engine.scene.load(scene = templateString) // Populate with data engine.variable.set(key = "product_name", value = "Wireless Headphones") engine.variable.set(key = "description", value = "Premium sound quality") engine.variable.set(key = "price", value = "149.99") // Find and replace the product image val blocks = engine.block.findByType(DesignBlockType.Graphic) for (block in blocks) { val name = engine.block.getString(block, property = "name") if (name == "product-image") { val fill = engine.block.getFill(block) engine.block.setString( fill, property = "fill/image/imageFileURI", value = "https://example.com/headphones.jpg" ) } } ``` ### Load from Archive Archives need to be unzipped before loading. Here's how to load a template from an archive file: ```kotlin import android.content.Context import android.net.Uri import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import ly.img.engine.Engine import java.io.File import java.io.FileOutputStream import java.util.zip.ZipInputStream suspend fun loadTemplateFromArchive( engine: Engine, context: Context, archiveFile: File ): Int { // Unzip archive to cache directory val extractDir = File(context.cacheDir, "template_${System.currentTimeMillis()}") extractDir.mkdirs() withContext(Dispatchers.IO) { ZipInputStream(archiveFile.inputStream()).use { zipInputStream -> var entry = zipInputStream.nextEntry while (entry != null) { val file = File(extractDir, entry.name) if (entry.isDirectory) { file.mkdirs() } else { file.parentFile?.mkdirs() FileOutputStream(file).use { outputStream -> zipInputStream.copyTo(outputStream) } } zipInputStream.closeEntry() entry = zipInputStream.nextEntry } } } // Load the scene.scene file from the extracted archive val sceneFile = File(extractDir, "scene.scene") val sceneUri = Uri.fromFile(sceneFile) return engine.scene.load(sceneUri = sceneUri) } ``` ## Troubleshooting **❌ Variables not populating**: - Confirm the variable syntax uses double curly brackets: `{{variable_name}}` - Verify that `engine.variable.set()` is called with the correct key. - Check that the scene is loaded before setting variables. **❌ Named blocks not found**: - Use `engine.block.getString(block, property = "name")` to verify block names. - Make sure the name was set during template creation. - Search within the correct block type using `engine.block.findByType()`. **❌ Missing fonts/images at runtime**: - Use an archive save to embed assets into a template for portability. - Ensure that the asset URIs are reachable and stable. - For local files, use `file:///android_asset/` for assets in the app's assets folder. **❌ Template won't load**: - Verify the template string or archive file is not corrupted. - Check that all required assets are accessible at the specified URIs. - Ensure the CE.SDK version used to create the template matches the version loading it. ## Next Steps Now that you can create templates, some related topics you may find helpful are: - [Generate scenes](https://img.ly/docs/cesdk/android/use-templates/generate-334e15/) with templates as the source. - [Apply templates](https://img.ly/docs/cesdk/android/use-templates/apply-template-35c73e/) to existing scenes. - [Batch Processing](https://img.ly/docs/cesdk/android/automation/batch-processing-ab2d18/) — automate template population at scale. - [Multi-Image Generation](https://img.ly/docs/cesdk/android/automation/multi-image-generation-2a0de4/) — generate multiple variants from a single template. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Lock the Template" description: "Restrict editing access to specific elements or properties in a template to enforce design rules." platform: android url: "https://img.ly/docs/cesdk/android/create-templates/lock-131489/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Use Templates](https://img.ly/docs/cesdk/android/create-templates-3aef79/) > [Lock the Template](https://img.ly/docs/cesdk/android/create-templates/lock-131489/) --- ```kotlin file=@cesdk_android_examples/engine-guides-scopes/Scopes.kt reference-only import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.GlobalScope fun scopes( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) engine.scene.createFromImage(Uri.parse("https://img.ly/static/ubq_samples/imgly_logo.jpg")) val block = engine.block.findByType(DesignBlockType.Graphic).first() val scopes = engine.editor.findAllScopes() // Let the global scope defer to the block-level. engine.editor.setGlobalScope(key = "layer/move", globalScope = GlobalScope.DEFER) // Manipulation of layout properties of any block will fail at this point. try { engine.block.setPositionX(block, value = 100F) // Not allowed } catch (exception: Exception) { exception.printStackTrace() } // This will return `GlobalScope.DEFER`. engine.editor.getGlobalScope(key = "layer/move") // Allow the user to control the layout properties of the image block. engine.block.setScopeEnabled(block, key = "layer/move", enabled = true) // Manipulation of layout properties of any block is now allowed. try { engine.block.setPositionX(block, value = 100F) // Allowed } catch (exception: Exception) { exception.printStackTrace() } // Verify that the "layer/move" scope is now enabled for the image block. engine.block.isScopeEnabled(block, key = "layer/move") // This will return true as well since the global scope is set to `GlobalScope.DEFER`. engine.block.isAllowedByScope(block, key = "layer/move") engine.stop() } ``` CE.SDK allows you to control which parts of a block can be manipulated. Scopes describe different aspects of a block, e.g. layout or style and can be enabled or disabled for every single block. There's also the option to control a scope globally. When configuring a scope globally you can set an override to always allow or deny a certain type of manipulation for every block. Or you can configure the global scope to defer to the individual block scopes. Initially, the block-level scopes are all disabled while at the global level all scopes are set to `"Allow"`. This overrides the block-level and allows for any kind of manipulation. If you want to implement a limited editing mode in your software you can set the desired scopes on the blocks you want the user to manipulate and then restrict the available actions by globally setting the scopes to `"Defer"`. In the same way you can prevent any manipulation of properties covered by a scope by setting the respective global scope to `"Deny"`. ## Available Scopes You can retrieve all available scopes by calling `engine.editor.findAllScopes()`. ```kotlin highlight-findAllScopes val scopes = engine.editor.findAllScopes() ``` We currently support the following scopes: | Scope | Explanation | | -------------------------- | -------------------------------------------------- | | `"layer/move"` | Whether the block's position can be changed | | `"layer/resize"` | Whether the block can be resized | | `"layer/rotate"` | Whether the block's rotation can be changed | | `"layer/flip"` | Whether the block can be flipped | | `"layer/crop"` | Whether the block's content can be cropped | | `"layer/clipping"` | Whether the block's clipping can be changed | | `"layer/opacity"` | Whether the block's opacity can be changed | | `"layer/blendMode"` | Whether the block's blend mode can be changed | | `"layer/visibility"` | Whether the block's visibility can be changed | | `"appearance/adjustments"` | Whether the block's adjustments can be changed | | `"appearance/filter"` | Whether the block's filter can be changed | | `"appearance/effect"` | Whether the block's effect can be changed | | `"appearance/blur"` | Whether the block's blur can be changed | | `"appearance/shadow"` | Whether the block's shadow can be changed | | `"lifecycle/destroy"` | Whether the block can be deleted | | `"lifecycle/duplicate"` | Whether the block can be duplicated | | `"editor/add"` | Whether new blocks can be added | | `"editor/select"` | Whether a block can be selected or not | | `"fill/change"` | Whether the block's fill can be changed | | `"fill/changeType"` | Whether the block's fill type can be changed | | `"stroke/change"` | Whether the block's stroke can be changed | | `"shape/change"` | Whether the block's shape can be changed | | `"text/edit"` | Whether the block's text can be changed | | `"text/character"` | Whether the block's text properties can be changed | ## Managing Scopes First, we globally defer the `"layer/move"` scope to the block-level using `engine.editor.setGlobalScope(key = "layer/move", globalScope = GlobalScope.DEFER)`. Since all blocks default to having their scopes set to `false` initially, modifying the layout properties of any block will fail at this point. | Value | Explanation | | -------- | ----------------------------------------------------------------- | | `.allow` | Manipulation of properties covered by the scope is always allowed | | `.deny` | Manipulation of properties covered by the scope is always denied | | `.defer` | Permission is deferred to the scope of the individual blocks | ```kotlin highlight-setGlobalScope // Let the global scope defer to the block-level. engine.editor.setGlobalScope(key = "layer/move", globalScope = GlobalScope.DEFER) // Manipulation of layout properties of any block will fail at this point. try { engine.block.setPositionX(block, value = 100F) // Not allowed } catch (exception: Exception) { exception.printStackTrace() } ``` We can verify the current state of the global `"layer/move"` scope using `engine.editor.getGlobalScope(key = "layer/move")`. ```kotlin highlight-getGlobalScope // This will return `GlobalScope.DEFER`. engine.editor.getGlobalScope(key = "layer/move") ``` Now we can allow the `"layer/move"` scope for a single block by setting it to `true` using `fun setScopeEnabled(block: DesignBlock, key: String, enabled: Boolean)`. ```kotlin highlight-setScopeEnabled // Allow the user to control the layout properties of the image block. engine.block.setScopeEnabled(block, key = "layer/move", enabled = true) // Manipulation of layout properties of any block is now allowed. try { engine.block.setPositionX(block, value = 100F) // Allowed } catch (exception: Exception) { exception.printStackTrace() } ``` Again we can verify this change by calling `fun isScopeEnabled(block: DesignBlock, key: String): Boolean`. ```kotlin highlight-isScopeEnabled // Verify that the "layer/move" scope is now enabled for the image block. engine.block.isScopeEnabled(block, key = "layer/move") ``` Finally, `fun isAllowedByScope(block: DesignBlock, key: String): Boolean` will allow us to verify a block's final scope state by taking both the global state as well as block-level state into account. ```kotlin highlight-isAllowedByScope // This will return true as well since the global scope is set to `GlobalScope.DEFER`. engine.block.isAllowedByScope(block, key = "layer/move") ``` ## Full Code Here's the full code: ```kotlin import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.GlobalScope fun scopes( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) engine.scene.createFromImage(Uri.parse("https://img.ly/static/ubq_samples/imgly_logo.jpg")) val block = engine.block.findByType(DesignBlockType.Graphic).first() val scopes = engine.editor.findAllScopes() // Let the global scope defer to the block-level. engine.editor.setGlobalScope(key = "layer/move", globalScope = GlobalScope.DEFER) // Manipulation of layout properties of any block will fail at this point. try { engine.block.setPositionX(block, value = 100F) // Not allowed } catch (exception: Exception) { exception.printStackTrace() } // This will return `GlobalScope.DEFER`. engine.editor.getGlobalScope(key = "layer/move") // Allow the user to control the layout properties of the image block. engine.block.setScopeEnabled(block, key = "layer/move", enabled = true) // Manipulation of layout properties of any block is now allowed. try { engine.block.setPositionX(block, value = 100F) // Allowed } catch (exception: Exception) { exception.printStackTrace() } // Verify that the "layer/move" scope is now enabled for the image block. engine.block.isScopeEnabled(block, key = "layer/move") // This will return true as well since the global scope is set to `GlobalScope.DEFER`. engine.block.isAllowedByScope(block, key = "layer/move") engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Overview" description: "Learn how to create, import, and manage reusable templates to streamline design creation in CE.SDK." platform: android url: "https://img.ly/docs/cesdk/android/create-templates/overview-4ebe30/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Use Templates](https://img.ly/docs/cesdk/android/create-templates-3aef79/) > [Overview](https://img.ly/docs/cesdk/android/create-templates/overview-4ebe30/) --- In CE.SDK, a *template* is a reusable, structured design that defines editable areas and constraints for end users. Templates can be based on static visuals or video compositions and are used to guide content creation, enable mass personalization, and enforce design consistency. Unlike a regular editable design, a template introduces structure through placeholders and constraints, allowing you to define which elements users can change and how. Templates support both static output formats (like PNG, PDF) and videos (like MP4), and can be created or applied using either the CE.SDK UI or API. Templates are a core part of enabling design automation, personalization, and streamlined workflows in any app that includes creative functionality. [Explore Demos](https://img.ly/showcases/cesdk?tags=android) [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) These imported designs can then be adapted into editable, structured templates inside CE.SDK. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Create Videos" description: "Learn how to create and customize videos in CE.SDK using scenes, assets, and timeline-based editing." platform: android url: "https://img.ly/docs/cesdk/android/create-video-c41a08/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Videos](https://img.ly/docs/cesdk/android/create-video-c41a08/) --- --- ## Related Pages - [Create Videos Overview](https://img.ly/docs/cesdk/android/create-video/overview-b06512/) - Learn how to create and customize videos in CE.SDK using scenes, assets, and timeline-based editing. - [Timeline Editor in Android (Kotlin)](https://img.ly/docs/cesdk/android/create-video/timeline-editor-912252/) - Use the timeline editor to arrange and edit video clips, audio, and animations frame by frame using Kotlin. - [Control Audio and Video](https://img.ly/docs/cesdk/android/create-video/control-daba54/) - Learn how to configure and control audio and video through offset, trim, playback, and resource control. - [Transform](https://img.ly/docs/cesdk/android/edit-video/transform-369f28/) - Documentation for Transform - [Add Captions](https://img.ly/docs/cesdk/android/edit-video/add-captions-f67565/) - Documentation for adding captions to videos - [Annotation in Android (Kotlin)](https://img.ly/docs/cesdk/android/edit-video/annotation-e9cbad/) - Add timed text, shapes, and highlights to videos programmatically in Android using Kotlin. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Control Audio and Video" description: "Learn how to configure and control audio and video through offset, trim, playback, and resource control." platform: android url: "https://img.ly/docs/cesdk/android/create-video/control-daba54/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Videos](https://img.ly/docs/cesdk/android/create-video-c41a08/) > [Control Audio and Video](https://img.ly/docs/cesdk/android/create-video/control-daba54/) --- In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to configure and control audio and video through the `block` API. ## Time Offset and Duration The time offset determines when a block becomes active during playback on the scene's timeline, and the duration decides how long this block is active. Page blocks are a special case in that they have an implicitly calculated time offset that is determined by their order and the total duration of their preceding pages. As with any audio/video-related property, not every block supports these properties. Use `supportsTimeOffset` and `supportsDuration` to check. ```kotlin fun supportsTimeOffset(block: DesignBlock): Boolean ``` Returns whether the block has a time offset property. - `block`: the block to query. - Returns true, if the block has a time offset property. ```kotlin fun setTimeOffset( block: DesignBlock, offset: Double, ) ``` Set the time offset of the given block relative to its parent. The time offset controls when the block is first active in the timeline. Note: The time offset is not supported by the page block. - `block`: the block whose time offset should be changed. - `offset`: the new time offset in seconds. ```kotlin fun getTimeOffset(block: DesignBlock): Double ``` Get the time offset of the given block relative to its parent. - `block`: the block whose time offset should be queried. - Returns the time offset of the block. ```kotlin fun supportsDuration(block: DesignBlock): Boolean ``` Returns whether the block has a duration property. - `block`: the block to query. - Returns true if the block has a duration property. ```kotlin fun setDuration( block: DesignBlock, duration: Double, ) ``` Set the playback duration of the given block in seconds. The duration defines for how long the block is active in the scene during playback. If a duration is set on the page block, it becomes the duration source block. Note: The duration is ignored when the scene is not in "Video" mode. Note: This also adjusts the trim for non looping blocks. - `block`: the block whose duration should be changed. - `duration`: the new duration in seconds. ```kotlin fun getDuration(block: DesignBlock): Double ``` Get the playback duration of the given block in seconds. The duration defines for how long the block is active in the scene during playback. Note: The duration is ignored when the scene is not in `Video` mode. - `block`: the block whose duration should be returned. - Returns the block's duration. ```kotlin fun supportsPageDurationSource( page: DesignBlock, block: DesignBlock, ): Boolean ``` Returns whether the block can be marked as the element that defines the duration of the given page. - `page`: the page block for which to query for. - `block`: the block to query. - Returns true, if the block can be marked as the element that defines the duration of the given page. ```kotlin fun setPageDurationSource( page: DesignBlock, block: DesignBlock, ) ``` Set an block as duration source so that the overall page duration is automatically determined by this. If no defining block is set, the page duration is calculated over all children. Only one block per page can be marked as duration source. Will automatically unmark the previously marked. Note: This is only supported for blocks that have a duration. - `page`: the page block for which it should be enabled. - `block`: the block which should be marked as duration source. ```kotlin fun isPageDurationSource(block: DesignBlock): Boolean ``` Returns whether the block is a duration source block. - `block`: the block whose duration source property should be queried. - Returns if the block is a duration source for a page. ```kotlin fun removePageDurationSource(block: DesignBlock) ``` Remove the block as duration source block for the page. If a scene or page given set as block, it is deactivated for all blocks in the scene or page. - `block`: the block whose duration source property should be removed. ## Trim You can select a specific range of footage from your audio/video resource by providing a trim offset and a trim length. The footage will loop if the trim's length is shorter than the block's duration. This behavior can also be disabled using the `setLooping` function. ```kotlin fun supportsTrim(block: DesignBlock): Boolean ``` Returns whether the block has trim properties. - `block`: the block to query. - Returns true, if the block has trim properties. ```kotlin fun setTrimOffset( block: DesignBlock, offset: Double, ) ``` Set the trim offset of the given block or fill. Sets the time in seconds within the fill at which playback of the audio or video clip should begin. Note: This requires the video or audio clip to be loaded. - `block`: the block whose trim should be updated. - `offset`: the new trim offset, measured in timeline seconds (scaled by playback rate). ```kotlin fun getTrimOffset(block: DesignBlock): Double ``` Get the trim offset of this block. Note: This requires the video or audio clip to be loaded. - `block`: the block whose trim offset should be queried. - Returns the trim offset in timeline seconds. ```kotlin fun setTrimLength( block: DesignBlock, length: Double, ) ``` Set the trim length of the given block or fill. The trim length is the duration of the audio or video clip that should be used for playback. Note: After reaching this value during playback, the trim region will loop. Note: This requires the video or audio clip to be loaded. - `block`: the object whose trim length should be updated. - `length`: the new trim length, measured in timeline seconds (scaled by playback rate). ```kotlin fun getTrimLength(block: DesignBlock): Double ``` Get the trim length of the given block or fill. - `block`: the object whose trim length should be queried. - Returns the trim length of the object measured in timeline seconds (scaled by playback rate). ## Playback Control You can start and pause playback and seek to a certain point on the scene's timeline. There's also a solo playback mode to preview audio and video blocks individually while the rest of the scene stays frozen. Finally, you can enable or disable the looping behavior of blocks and control their audio volume. ```kotlin fun setPlaying( block: DesignBlock, enabled: Boolean, ) ``` Set whether the block should be during active playback. - `block`: the block that should be updated. - `enabled`: whether the block should be playing its contents. ```kotlin fun isPlaying(block: DesignBlock): Boolean ``` Returns whether the block is currently during active playback. - `block`: the block to query. - Returns whether the block is during playback. ```kotlin fun setSoloPlaybackEnabled( block: DesignBlock, enabled: Boolean, ) ``` Set whether the given block or fill should play its contents while the rest of the scene remains paused. Note: Setting this to true for one block will automatically set it to false on all other blocks. - `block`: the block or fill to update. - `enabled`: whether the block's playback should progress as time moves on. ```kotlin fun isSoloPlaybackEnabled(block: DesignBlock): Boolean ``` Return whether the given block or fill is currently set to play its contents while the rest of the scene remains paused. - `block`: the block or fill to query. - Returns whether solo playback is enabled for this block. ```kotlin fun supportsPlaybackTime(block: DesignBlock): Boolean ``` Returns whether the block has a playback time property. - `block`: the block to query. - Returns whether the block has a playback time property. ```kotlin fun setPlaybackTime( block: DesignBlock, time: Double, ) ``` Set the playback time of the given block. - `block`: the block whose playback time should be updated. - `time`: the new playback time of the block in seconds. ```kotlin fun getPlaybackTime(block: DesignBlock): Double ``` Get the playback time of the given block. - `block`: the block to query. - Returns the playback time of the block in seconds. ```kotlin fun isVisibleAtCurrentPlaybackTime(block: DesignBlock): Boolean ``` Returns whether the block should be visible on the canvas at the current playback time. - `block`: the block to query. - Returns the visibility state if the query succeeded. ```kotlin fun supportsPlaybackControl(block: DesignBlock): Boolean ``` Returns whether the block supports a playback control. - `block`: the block to query. - Returns whether the block has playback control. ```kotlin fun setLooping( block: DesignBlock, looping: Boolean, ) ``` Set whether the block should start from the beginning again or stop. - `block`: the block or video fill to update. - Returns whether the block should loop to the beginning or stop. ```kotlin fun isLooping(block: DesignBlock): Boolean ``` Query whether the block is looping. - `block`: the block to query. - Returns whether the block is looping. ```kotlin fun setMuted( block: DesignBlock, muted: Boolean, ) ``` Set whether the audio of the block is muted. - `block`: the block or video fill to update. - `muted`: whether the audio should be muted. ```kotlin fun isMuted(block: DesignBlock): Boolean ``` Query whether the block is muted. - `block`: the block to query. - Returns whether the block is muted. ```kotlin fun setVolume( block: DesignBlock, @FloatRange(from = 0.0, to = 1.0) volume: Float, ) ``` Set the audio volume of the given block. - `block`: the block or video fill to update. - `volume`: the desired volume with a range of `0, 1`. ```kotlin @FloatRange(from = 0.0, to = 1.0) fun getVolume(block: DesignBlock): Float ``` Get the audio volume of the given block. - `block`: the block to query. - Returns volume with a range of `0, 1`. ## Playback Speed You can control the playback speed of audio and video blocks to create slow-motion or fast-forward effects. The playback speed is a multiplier that affects how quickly the content plays back. Audio blocks accept values from 0.25x (quarter speed) to 3.0x (triple speed). Video fills can exceed 3.0x whenever you need more aggressive fast-forward playback. Note that changing the playback speed automatically adjusts both the trim and duration of the block to maintain the same visual timeline length. ```kotlin fun setPlaybackSpeed(block: DesignBlock, speed: Float): Unit ``` Set the playback speed of the given block. Note: This also adjusts the trim and duration of the block. Video fills running faster than 3.0x are force muted until their speed is reduced to 3.0x or below. - `block`: the block or video fill to update. - `speed`: The desired playback speed multiplier. Valid range is \[0.25, 3.0] for audio blocks and \[0.25, ∞) for video fills. ```kotlin fun getPlaybackSpeed(block: DesignBlock): Float ``` Get the playback speed of the given block. - `block`: the block to query. - Returns the playback speed multiplier. ## Resource Control Until an audio/video resource referenced by a block is loaded, properties like the duration of the resource aren't available, and accessing those will lead to an error. You can avoid this by forcing the resource you want to access to load using `forceLoadAVResource`. ```kotlin suspend fun forceLoadAVResource(block: DesignBlock) ``` Begins loading the required audio and video resource for the given video fill or audio block. If the resource had been loaded earlier and resulted in an error, it will be reloaded. - `block`: the video fill or audio block whose resource should be loaded. ```kotlin @UnstableEngineApi fun isAVResourceLoaded(block: DesignBlock): Boolean ``` Returns whether the audio and video resource for the given video fill or audio block is loaded. Note that the function is unstable and mared with `UnstableEngineApi`. - `block`: the video fill or audio block. - Returns whether the resource is loaded. ```kotlin fun getAVResourceTotalDuration(block: DesignBlock): Double ``` Get the duration in seconds of the video or audio resource that is attached to the given block. - `block`: the video fill or audio block. - Returns the video or audio file duration. ```kotlin fun getVideoWidth(videoFill: DesignBlock): Int ``` Get the video width in pixels of the video resource that is attached to the given block. - `videoFill`: the video fill. - Returns the video width in pixels. ```kotlin fun getVideoHeight(videoFill: DesignBlock): Int ``` Get the video height in pixels of the video resource that is attached to the given block. - `videoFill`: the video fill. - Returns the video height in pixels. ## Thumbnail Previews For a user interface, it can be helpful to have image previews in the form of thumbnails for any given video resource. For videos, the engine can provide one or more frames using `generateVideoThumbnailSequence`. Pass the video fill that references the video resource. In addition to video thumbnails, the engine can also render compositions of design blocks over time. To do this pass in the respective design block. The video editor uses these to visually represent blocks in the timeline. In order to visualize audio signals `generateAudioThumbnailSequence` can be used. This generates a sequence of values in the range of 0 to 1 that represent the loudness of the signal. These values can be used to render a waveform pattern in any custom style. Note: there can be at most one thumbnail generation request per block at any given time. If you don't want to wait for the request to finish before issuing a new request, you can cancel it by calling `cancel()` on the `Job` object returned on launching the flow. ```kotlin fun generateVideoThumbnailSequence( block: DesignBlock, thumbnailHeight: Int, timeBegin: Double, timeEnd: Double, numberOfFrames: Int, ): Flow ``` Generate a thumbnail sequence for the given video fill or design block. Note: There can only be one thumbnail generation request in progress for a given block. Note: During playback, the thumbnail generation will be paused. - `block`: the video fill or a design block. - `thumbnailHeight`: the height of a thumbnail. The width will be calculated from the video aspect ratio. - `timeBegin`: the time in seconds relative to the time offset of the design block at which the thumbnail sequence should start. - `timeEnd`: the time in seconds relative to the time offset of the design block at which the thumbnail sequence should end. - `numberOfFrames`: the number of frames to generate. - Returns a flow of `VideoThumbnailResult` object which emits for every generated frame thumbnail. It emits exactly `numberOfFrames` times. ```kotlin fun generateAudioThumbnailSequence( block: DesignBlock, samplesPerChunk: Int, timeBegin: Double, timeEnd: Double, numberOfSamples: Int, numberOfChannels: Int, ): Flow ``` Generate a thumbnail sequence for the given audio block or video fill. A thumbnail in this case is a chunk of samples in the range of 0 to 1. In case stereo data is requested, the samples are interleaved, starting with the left channel. Note: During playback, the thumbnail generation will be paused. - `block`: the audio block or video fill. - `samplesPerChunk`: the number of samples per chunk. - `timeBegin`: the time in seconds at which the thumbnail sequence should start. - `timeEnd`: the time in seconds at which the thumbnail sequence should end. - `numberOfSamples`: the total number of samples to generate. - `numberOfChannels`: the number of channels in the output. 1 for mono, 2 for stereo. - Returns a flow of `AudioThumbnailResult` object which emits numberOfSamples / samplesPerChunk times. ## Full Code Here's the full code: ```kotlin file=@cesdk_android_examples/engine-guides-control-av/ControlAudioVideo.kt import kotlinx.coroutines.coroutineScope import kotlinx.coroutines.flow.collect import kotlinx.coroutines.flow.onEach import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType suspend fun controlAudioVideo(engine: Engine) = coroutineScope { // Setup a minimal video scene val scene = engine.scene.createForVideo() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) engine.block.setWidth(page, value = 1280.0f) engine.block.setHeight(page, value = 720.0f) // Create a video block and track val videoBlock = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(videoBlock, shape = engine.block.createShape(ShapeType.Rect)) val videoFill = engine.block.createFill(FillType.Video) engine.block.setString( block = videoFill, property = "fill/video/fileURI", value = "https://cdn.img.ly/assets/demo/v1/ly.img.video/videos/pexels-drone-footage-of-a-surfer-barrelling-a-wave-12715991.mp4", ) engine.block.setFill(videoBlock, fill = videoFill) val track = engine.block.create(DesignBlockType.Track) engine.block.appendChild(parent = page, child = track) engine.block.appendChild(parent = track, child = videoBlock) engine.block.fillParent(track) // Create an audio block val audio = engine.block.create(DesignBlockType.Audio) engine.block.appendChild(parent = page, child = audio) engine.block.setString( block = audio, property = "audio/fileURI", value = "https://cdn.img.ly/assets/demo/v1/ly.img.audio/audios/far_from_home.m4a", ) // Time Offset and Duration engine.block.supportsTimeOffset(audio) engine.block.setTimeOffset(audio, offset = 2.0) engine.block.getTimeOffset(audio) // Returns 2 engine.block.supportsDuration(page) engine.block.setDuration(page, duration = 10.0) engine.block.getDuration(page) // Returns 10 // Duration of the page can be that of a block engine.block.supportsPageDurationSource(page, videoBlock) engine.block.setPageDurationSource(page, videoBlock) engine.block.isPageDurationSource(videoBlock) engine.block.getDuration(page) // Returns duration plus offset of the block // Duration of the page can be the maximum end time of all page child blocks engine.block.removePageDurationSource(page) engine.block.getDuration(page) // Returns the maximum end time of all page child blocks // Trim engine.block.supportsTrim(videoFill) engine.block.setTrimOffset(videoFill, offset = 1.0) engine.block.getTrimOffset(videoFill) // Returns 1 engine.block.setTrimLength(videoFill, length = 5.0) engine.block.getTrimLength(videoFill) // Returns 5 // Playback Control engine.block.setPlaying(page, enabled = true) engine.block.isPlaying(page) engine.block.setSoloPlaybackEnabled(videoFill, enabled = true) engine.block.isSoloPlaybackEnabled(videoFill) engine.block.supportsPlaybackTime(page) engine.block.setPlaybackTime(page, time = 1.0) engine.block.getPlaybackTime(page) engine.block.isVisibleAtCurrentPlaybackTime(videoBlock) engine.block.supportsPlaybackControl(videoFill) engine.block.setLooping(videoFill, looping = true) engine.block.isLooping(videoFill) engine.block.setMuted(videoFill, muted = true) engine.block.isMuted(videoFill) engine.block.setVolume(videoFill, volume = 0.5F) // 50% volume engine.block.getVolume(videoFill) // Playback Speed engine.block.setPlaybackSpeed(videoFill, speed = 0.5f) // Half speed val currentSpeed = engine.block.getPlaybackSpeed(videoFill) // 0.5 engine.block.setPlaybackSpeed(videoFill, speed = 2.0f) // Double speed engine.block.setPlaybackSpeed(videoFill, speed = 1.0f) // Normal speed // Resource Control engine.block.forceLoadAVResource(videoFill) // Unstable engine api engine.block.isAVResourceLoaded(videoFill) engine.block.getAVResourceTotalDuration(videoFill) val videoWidth = engine.block.getVideoWidth(videoFill) val videoHeight = engine.block.getVideoHeight(videoFill) // Thumbnail Previews launch { engine.block.generateVideoThumbnailSequence( block = videoFill, thumbnailHeight = 128, timeBegin = 0.5, timeEnd = 9.5, numberOfFrames = 10, ).onEach { println("frameIndex = ${it.frameIndex}, width = ${it.width}, height = ${it.height}") }.collect() } launch { engine.block.generateAudioThumbnailSequence( block = audio, samplesPerChunk = 20, timeBegin = 0.5, timeEnd = 9.5, numberOfSamples = 10 * 20, numberOfChannels = 2, ).onEach { println("chunkIndex = ${it.chunkIndex}, samples:size = ${it.samples.size}") // drawWavePattern(it.samples) }.collect() } } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Create Videos Overview" description: "Learn how to create and customize videos in CE.SDK using scenes, assets, and timeline-based editing." platform: android url: "https://img.ly/docs/cesdk/android/create-video/overview-b06512/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Videos](https://img.ly/docs/cesdk/android/create-video-c41a08/) > [Overview](https://img.ly/docs/cesdk/android/create-video/overview-b06512/) --- ```kotlin file=@cesdk_android_examples/engine-guides-video/Video.kt reference-only import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.MimeType import ly.img.engine.ShapeType fun editVideo( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1280, height = 720) val scene = engine.scene.createForVideo() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) engine.block.setWidth(page, value = 1280F) engine.block.setHeight(page, value = 720F) engine.block.setDuration(page, duration = 20.0) val video1 = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(video1, shape = engine.block.createShape(ShapeType.Rect)) val videoFill = engine.block.createFill(FillType.Video) engine.block.setString( block = videoFill, property = "fill/video/fileURI", value = "https://cdn.img.ly/assets/demo/v1/ly.img.video/videos/pexels-drone-footage-of-a-surfer-barrelling-a-wave-12715991.mp4", ) engine.block.setFill(video1, fill = videoFill) val video2 = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(video1, shape = engine.block.createShape(ShapeType.Rect)) val videoFill2 = engine.block.createFill(FillType.Video) engine.block.setString( block = videoFill, property = "fill/video/fileURI", value = "https://cdn.img.ly/assets/demo/v3/ly.img.video/videos/pexels-kampus-production-8154913.mp4", ) engine.block.setFill(video2, fill = videoFill2) val track = engine.block.create(DesignBlockType.Track) engine.block.appendChild(parent = page, child = track) engine.block.appendChild(parent = track, child = video1) engine.block.appendChild(parent = track, child = video2) engine.block.fillParent(track) engine.block.setDuration(video1, duration = 15.0) // Make sure that the video is loaded before calling the trim APIs. engine.block.forceLoadAVResource(videoFill) engine.block.setTrimOffset(videoFill, offset = 1.0) engine.block.setTrimLength(videoFill, length = 10.0) engine.block.setLooping(videoFill, looping = true) engine.block.setMuted(videoFill, muted = true) val audio = engine.block.create(DesignBlockType.Audio) engine.block.appendChild(parent = page, child = audio) engine.block.setString( block = audio, property = "audio/fileURI", value = "https://cdn.img.ly/assets/demo/v1/ly.img.audio/audios/far_from_home.m4a", ) // Set the volume level to 70%. engine.block.setVolume(audio, volume = 0.7F) // Start the audio after two seconds of playback. engine.block.setTimeOffset(audio, offset = 2.0) // Give the Audio block a duration of 7 seconds. engine.block.setDuration(audio, duration = 7.0) // Export page as mp4 video. val blob = engine.block.exportVideo( block = page, timeOffset = 0.0, duration = engine.block.getDuration(page), mimeType = MimeType.MP4, progressCallback = { println( "Rendered ${it.renderedFrames} frames and encoded ${it.encodedFrames} frames out of ${it.totalFrames} frames", ) }, ) engine.stop() } ``` In addition to static designs, CE.SDK also allows you to create and edit videos. Working with videos introduces the concept of time into the scene, which requires you to switch the scene into the `"Video"` mode. In this mode, each page in the scene has its own separate timeline within which its children can be placed. The `"playback/time"` property of each page controls the progress of time through the page. In order to add videos to your pages, you can add a block with a `FillType.video` fill. As the playback time of the page progresses, the corresponding point in time of the video fill is rendered by the block. You can also customize the video fill's trim in order to control the portion of the video that should be looped while the block is visible. `DesignBlockType.Audio` blocks can be added to the scene in order to play an audio file during playback. The `playback/timeOffset` property controls after how many seconds the audio should begin to play, while the duration property defines how long the audio should play. The same APIs can be used for other design blocks as well, such as text or graphic blocks. Finally, the whole page can be exported as a video file using the `BlockApi.exportVideo` function. ## Creating a Video Scene First, we create a scene that is set up for video editing by calling the `scene.createForVideo()` API. Then we create a page, add it to the scene and define its dimensions. This page will hold our composition. ```kotlin highlight-setupScene val scene = engine.scene.createForVideo() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) engine.block.setWidth(page, value = 1280F) engine.block.setHeight(page, value = 720F) ``` ## Setting Page Durations Next, we define the duration of the page using the `fun setDuration(block: DesignBlock, duration: Double)` API to be 20 seconds long. This will be the total duration of our exported video in the end. ```kotlin highlight-setPageDuration engine.block.setDuration(page, duration = 20.0) ``` ## Adding Videos In this example, we want to show two videos, one after the other. For this, we first create two graphic blocks and assign two `'video'` fills to them. ```kotlin highlight-assignVideoFill val video1 = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(video1, shape = engine.block.createShape(ShapeType.Rect)) val videoFill = engine.block.createFill(FillType.Video) engine.block.setString( block = videoFill, property = "fill/video/fileURI", value = "https://cdn.img.ly/assets/demo/v1/ly.img.video/videos/pexels-drone-footage-of-a-surfer-barrelling-a-wave-12715991.mp4", ) engine.block.setFill(video1, fill = videoFill) val video2 = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(video1, shape = engine.block.createShape(ShapeType.Rect)) val videoFill2 = engine.block.createFill(FillType.Video) engine.block.setString( block = videoFill, property = "fill/video/fileURI", value = "https://cdn.img.ly/assets/demo/v3/ly.img.video/videos/pexels-kampus-production-8154913.mp4", ) engine.block.setFill(video2, fill = videoFill2) ``` ## Creating a Track While we could add the two blocks directly to the page and manually set their sizes and time offsets, we can alternatively also use the `DesignBlockType.Track` block to simplify this work. A track automatically adjusts the time offsets of its children to make sure that they play one after another without any gaps, based on each child's duration. Tracks themselves cannot be selected directly by clicking on the canvas, nor do they have any visual representation. We create a `DesignBlockType.Track` block, add it to the page and add both videos in the order in which they should play as the track's children. Next, we use the `fillParent` API, which will resize all children of the track to the same dimensions as the page. The dimensions of a track are always derived from the dimensions of its children, so you should not call the `setWidth` or `setHeight` APIs on a track, but on its children instead if you can't use the `fillParent` API. ```kotlin highlight-addToTrack val track = engine.block.create(DesignBlockType.Track) engine.block.appendChild(parent = page, child = track) engine.block.appendChild(parent = track, child = video1) engine.block.appendChild(parent = track, child = video2) engine.block.fillParent(track) ``` By default, each block has a duration of 5 seconds after it is created. If we want to show it on the page for a different amount of time, we can use the `setDuration` API. Note that we can just increase the duration of the first video block to 15 seconds without having to adjust anything about the second video. The `track` takes care of that for us automatically so that the second video starts playing after 15 seconds. ```kotlin highlight-setDuration engine.block.setDuration(video1, duration = 15.0) ``` If the video is longer than the duration of the graphic block that it's attached to, it will cut off once the duration of the graphic is reached. If it is too short, the video will automatically loop for as long as its graphic block is visible. We can also manually define the portion of our video that should loop within the page using the `fun setTrimOffset(block: DesignBlock, offset: Double)` and `fun setTrimLength(block: DesignBlock, length: Double)` APIs. We use the trim offset to cut away the first second of the video and the trim length to only play 10 seconds of the video. ```kotlin highlight-trim // Make sure that the video is loaded before calling the trim APIs. engine.block.forceLoadAVResource(videoFill) engine.block.setTrimOffset(videoFill, offset = 1.0) engine.block.setTrimLength(videoFill, length = 10.0) ``` We can control if a video will loop back to its beginning by calling `fun setLooping(block: DesignBlock, looping: Boolean)`. Otherwise, the video will simply hold its last frame instead and audio will stop playing. Looping behavior is activated for all blocks by default. ```kotlin highlight-looping engine.block.setLooping(videoFill, looping = true) ``` ## Audio If the video of a video fill contains an audio track, that audio will play automatically by default when the video is playing. We can mute it by calling `fun setMuted(block: DesignBlock, muted: Boolean)`. ```kotlin highlight-mute-audio engine.block.setMuted(videoFill, muted = true) ``` We can also add audio-only files to play together with the contents of the scene by adding an `audio` block to the scene and assigning it the uri of the audio file. ```kotlin highlight-audio val audio = engine.block.create(DesignBlockType.Audio) engine.block.appendChild(parent = page, child = audio) engine.block.setString( block = audio, property = "audio/fileURI", value = "https://cdn.img.ly/assets/demo/v1/ly.img.audio/audios/far_from_home.m4a", ) ``` We can adjust the volume level of any audio block or video fill by calling `fun setVolume(block: DesignBlock, volume: Float)`. The volume is given as a fraction in the range of 0 to 1. ```kotlin highlight-audio-volume // Set the volume level to 70%. engine.block.setVolume(audio, volume = 0.7F) ``` By default, our audio block will start playing at the very beginning of the page. We can change this by specifying how many seconds into the page it should begin to play using the `fun setTimeOffset(block: DesignBlock, offset: Double)` API. ```kotlin highlight-timeOffset // Start the audio after two seconds of playback. engine.block.setTimeOffset(audio, offset = 2.0) ``` By default, our audio block will have a duration of 5 seconds. We can change this by specifying its duration in seconds by using the `fun setDuration(block: DesignBlock, duration: Double)` API. ```kotlin highlight-audioDuration // Give the Audio block a duration of 7 seconds. engine.block.setDuration(audio, duration = 7.0) ``` ## Exporting Video You can start exporting the entire page as a video file by calling `blockApi.exportVideo`. The encoding process will run in the background. You can get notified about the progress of the encoding process by using `progressCallback` parameter. Since the encoding process runs in the background, the engine will stay interactive. So, you can continue to use the engine to manipulate the scene. Please note that these changes won't be visible in the exported video file because the scene's state has been frozen at the start of the export. ```kotlin highlight-exportVideo // Export page as mp4 video. val blob = engine.block.exportVideo( block = page, timeOffset = 0.0, duration = engine.block.getDuration(page), mimeType = MimeType.MP4, progressCallback = { println( "Rendered ${it.renderedFrames} frames and encoded ${it.encodedFrames} frames out of ${it.totalFrames} frames", ) }, ) ``` ## Full Code Here's the full code: ```kotlin import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.MimeType import ly.img.engine.ShapeType fun editVideo( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val scene = engine.scene.createForVideo() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) engine.block.setWidth(page, value = 1280F) engine.block.setHeight(page, value = 720F) engine.block.setDuration(page, duration = 20.0) val video1 = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(video1, shape = engine.block.createShape(ShapeType.Rect)) val videoFill = engine.block.createFill(FillType.Video) engine.block.setString( block = videoFill, property = "fill/video/fileURI", value = "https://cdn.img.ly/assets/demo/v1/ly.img.video/videos/pexels-drone-footage-of-a-surfer-barrelling-a-wave-12715991.mp4", ) engine.block.setFill(video1, fill = videoFill) val video2 = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(video1, shape = engine.block.createShape(ShapeType.Rect)) val videoFill2 = engine.block.createFill(FillType.Video) engine.block.setString( block = videoFill, property = "fill/video/fileURI", value = "https://cdn.img.ly/assets/demo/v3/ly.img.video/videos/pexels-kampus-production-8154913.mp4", ) engine.block.setFill(video2, fill = videoFill2) val track = engine.block.create(DesignBlockType.Track) engine.block.appendChild(parent = page, child = track) engine.block.appendChild(parent = track, child = video1) engine.block.appendChild(parent = track, child = video2) engine.block.fillParent(track) engine.block.setDuration(video1, duration = 15.0) // Make sure that the video is loaded before calling the trim APIs. engine.block.forceLoadAVResource(videoFill) engine.block.setTrimOffset(videoFill, offset = 1.0) engine.block.setTrimLength(videoFill, length = 10.0) engine.block.setLooping(videoFill, looping = true) engine.block.setMuted(videoFill, muted = true) val audio = engine.block.create(DesignBlockType.Audio) engine.block.appendChild(parent = page, child = audio) engine.block.setString( block = audio, property = "audio/fileURI", value = "https://cdn.img.ly/assets/demo/v1/ly.img.audio/audios/far_from_home.m4a", ) // Set the volume level to 70%. engine.block.setVolume(audio, volume = 0.7F) // Start the audio after two seconds of playback. engine.block.setTimeOffset(audio, offset = 2.0) // Give the Audio block a duration of 7 seconds. engine.block.setDuration(audio, duration = 7.0) // Export page as mp4 video. val blob = engine.block.exportVideo( block = page, timeOffset = 0.0, duration = engine.block.getDuration(page), mimeType = MimeType.MP4, progressCallback = { println( "Rendered ${it.renderedFrames} frames and encoded ${it.encodedFrames} frames out of ${it.totalFrames} frames", ) }, ) engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Timeline Editor in Android (Kotlin)" description: "Use the timeline editor to arrange and edit video clips, audio, and animations frame by frame using Kotlin." platform: android url: "https://img.ly/docs/cesdk/android/create-video/timeline-editor-912252/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Videos](https://img.ly/docs/cesdk/android/create-video-c41a08/) > [Timeline Editor](https://img.ly/docs/cesdk/android/create-video/timeline-editor-912252/) --- Timeline editing is the heart of any professional video creation tool. With CE.SDK, you can build video editors that use a **timeline model**. Each scene contains tracks and clips that align precisely over time. Developers can build **custom headless timelines** using the `Engine` APIs to programmatically arrange, trim, and export video content. ## What You'll Learn - How the CE.SDK timeline hierarchy works (`Scene → Page → Track → Clip`). - How to create and organize video tracks programmatically. - How to trim and arrange video clips in a timeline. - How to generate thumbnails for a timeline view. - How to connect timeline scenes to export or playback features. ## When You'll Use It - You want to build a **custom video editing interface** that arranges clips. - You need to **trim or rearrange** clips programmatically before export. - You're adding **thumbnail visualization** or building a playback scrubber. - You're automating video generation from templates or data. ## Understanding the Timeline Hierarchy CE.SDK organizes time-based video projects into a structured hierarchy: ```text Scene └── Page (timeline segment) ├── Track (parallel layer) │ ├── Clip (video or audio content) │ ├── Clip … ``` - **Scene:** the root container of your video project. - **Page:** a timeline segment (often a full video composition). - **Track:** a parallel layer for clips (like separate video or audio lanes). - **Clip:** an individual media item placed on a track. > **Note:** By default, a new scene has dimensions of **100 × 100 units**, which is small. For realistic video compositions, explicitly set a size that matches your export or camera input:```kotlin > import ly.img.engine.DesignBlockType > import ly.img.engine.Engine > > val scene = engine.scene.createForVideo() > val page = engine.block.create(DesignBlockType.Page) > > engine.block.appendChild(parent = scene, child = page) > > // Set page dimensions to match a 1080x1920 portrait video > engine.block.setWidth(page, value = 1080F) > engine.block.setHeight(page, value = 1920F) > ``` ## Creating a Timeline Programmatically When you're building a custom UI, create a timeline structure directly through the block API. ```kotlin import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType val scene = engine.scene.createForVideo() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) // Always set a realistic frame size engine.block.setWidth(page, value = 1080F) engine.block.setHeight(page, value = 1920F) // Create a video track val track = engine.block.create(DesignBlockType.Track) engine.block.appendChild(parent = page, child = track) // Insert a video clip val clip = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(clip, shape = engine.block.createShape(ShapeType.Rect)) val fill = engine.block.createFill(FillType.Video) engine.block.setString( block = fill, property = "fill/video/fileURI", value = "https://example.com/video.mp4" ) engine.block.setFill(clip, fill = fill) engine.block.appendChild(parent = track, child = clip) ``` You can repeat this process for all clips and tracks, allowing for multi-layered compositions that include: - background video - overlays - captions When you append a clip to a track, CE.SDK automatically places the new clip **directly after the last clip in that track**. This gives you a continuous, gap-free sequence, so playback flows cleanly from one clip to the next without extra timing math. If you need gaps or overlaps, either: - Place the clips in separate tracks. - Disable automatic offset management for the track and fully control offsets yourself. ```kotlin import ly.img.engine.Engine // Disable automatic offset management for this track engine.block.setBool( videoTrack, property = "track/automaticallyManageBlockOffsets", value = false ) // Manage playback/timeOffset on each clip manually engine.block.setTimeOffset(aRoll, offset = 0.0) engine.block.setTimeOffset(overlayClip, offset = 3.0) ``` ### Multi-Track Example (Video + Overlay + Audio) You can build layered timelines by adding tracks to the same page. Each track maintains its own sequence of clips. The following code creates two video tracks to create a picture-in-picture display with an audio track accompaniment. ```kotlin import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun createMultiTrackTimeline( license: String, userId: String ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.timeline") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) // Create a video scene and page val scene = engine.scene.createForVideo() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) // Set page dimensions and duration engine.block.setWidth(page, value = 1080F) engine.block.setHeight(page, value = 1920F) // Focus the canvas on this page engine.scene.zoomToBlock( page, paddingLeft = 0F, paddingTop = 0F, paddingRight = 0F, paddingBottom = 0F ) // A-roll primary video track val videoTrack = engine.block.create(DesignBlockType.Track) engine.block.appendChild(parent = page, child = videoTrack) val aRoll = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(aRoll, shape = engine.block.createShape(ShapeType.Rect)) val aRollFill = engine.block.createFill(FillType.Video) engine.block.setString( block = aRollFill, property = "fill/video/fileURI", value = "https://cdn.img.ly/assets/demo/v1/ly.img.video/videos/pexels-drone-footage-of-a-surfer-barrelling-a-wave-12715991.mp4" ) engine.block.setFill(aRoll, fill = aRollFill) engine.block.appendChild(parent = videoTrack, child = aRoll) // Force load to get duration engine.block.forceLoadAVResource(aRollFill) val rollDuration = engine.block.getAVResourceTotalDuration(aRollFill) engine.block.setDuration(aRoll, duration = rollDuration) engine.block.fillParent(videoTrack) // Overlay track (B-roll or picture-in-picture) val overlayTrack = engine.block.create(DesignBlockType.Track) engine.block.appendChild(parent = page, child = overlayTrack) val overlayClip = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(overlayClip, shape = engine.block.createShape(ShapeType.Rect)) val overlayFill = engine.block.createFill(FillType.Video) engine.block.setString( block = overlayFill, property = "fill/video/fileURI", value = "https://cdn.img.ly/assets/demo/v2/ly.img.video/videos/pexels-kampus-production-8154913.mp4" ) engine.block.setFill(overlayClip, fill = overlayFill) // Position overlay visually engine.block.setPositionX(overlayClip, value = 400F) engine.block.setPositionY(overlayClip, value = 200F) engine.block.setWidth(overlayClip, value = 225F) engine.block.setHeight(overlayClip, value = 500F) engine.block.appendChild(parent = overlayTrack, child = overlayClip) engine.block.forceLoadAVResource(overlayFill) val duration = engine.block.getAVResourceTotalDuration(overlayFill) engine.block.setDuration(overlayClip, duration = duration) // Audio bed track val audioTrack = engine.block.create(DesignBlockType.Track) engine.block.appendChild(parent = page, child = audioTrack) val audioClip = engine.block.create(DesignBlockType.Audio) engine.block.setString( block = audioClip, property = "audio/fileURI", value = "https://cdn.img.ly/assets/demo/v1/ly.img.audio/audios/far_from_home.m4a" ) engine.block.appendChild(parent = audioTrack, child = audioClip) // Set duration of composition to be the same as the longer clip engine.block.setDuration(page, duration = maxOf(rollDuration, duration)) // Start playing engine.block.setPlaying(page, enabled = true) } ``` The preceding code creates a complete multi-track video timeline with A-roll, B-roll overlay, and background audio. ## Trimming and Clip Duration The `duration` of the page block controls the length of the final composition. If you don't set a duration for clips, they truncate after a few seconds. Setting a duration for a clip that's longer than the video asset for that clip causes the asset to loop. Setting a duration for a page that's longer than the duration of its clips results in a blank screen. Use `getAVResourceTotalDuration()` on audio clips or video fills to get the duration of the underlying source media. CE.SDK gives you fine control over: - **trim start** - **trim length** - **timeline position** Each clip can define how much of its source video to display and where it begins in the composition's timeline. Assume `aRoll` is a `Graphic` block and `aRollFill` is its `Video` fill. ```kotlin import ly.img.engine.Engine // Skip the first 2 seconds of the source engine.block.setTrimOffset( block = aRollFill, offset = 2.0 ) // Play only 5 seconds after the trim offset engine.block.setTrimLength( block = aRollFill, length = 5.0 ) ``` Use `setTimeOffset` on the clip block to move it along the track: ```kotlin // Start this clip 10 seconds into the track engine.block.setTimeOffset( block = aRoll, offset = 10.0 ) ``` ## Timeline Playback Control You can preview playback using the **Block API** after you've placed and trimmed clips. See [Control Audio and Video](https://img.ly/docs/cesdk/android/create-video/control-daba54/) for detailed playback control. That guide covers: - Play, pause, and seek. - Playback speed and looping. - Current playback time queries. - Synchronization across different tracks. Here's a quick example: ```kotlin import ly.img.engine.Engine // Start playback engine.block.setPlaying(page, enabled = true) // Check if playing val isPlaying = engine.block.isPlaying(page) // Seek to specific time (in seconds) engine.block.setPlaybackTime(page, time = 5.0) // Get current playback time val currentTime = engine.block.getPlaybackTime(page) // Pause playback engine.block.setPlaying(page, enabled = false) ``` ## Generating Timeline Thumbnails You can render thumbnails directly from any video clip using CE.SDK's **asynchronous** thumbnail generator. The API returns a `Flow` that emits thumbnail frames. ```kotlin import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.flow.collect import kotlinx.coroutines.flow.onEach import kotlinx.coroutines.launch import ly.img.engine.Engine fun generateVideoThumbnails( engine: Engine, videoFill: Int ) = CoroutineScope(Dispatchers.Main).launch { engine.block.generateVideoThumbnailSequence( block = videoFill, thumbnailHeight = 128, timeBegin = 0.0, timeEnd = 10.0, numberOfFrames = 20 ).onEach { thumbnail -> // thumbnail.frameIndex: Int // thumbnail.width: Int // thumbnail.height: Int // thumbnail.data: ByteBuffer (RGBA pixel data) println("Frame ${thumbnail.frameIndex}: ${thumbnail.width}x${thumbnail.height}") // Convert ByteBuffer to Bitmap if needed for display // val bitmap = Bitmap.createBitmap(thumbnail.width, thumbnail.height, Bitmap.Config.ARGB_8888) // bitmap.copyPixelsFromBuffer(thumbnail.data) }.collect() } ``` Each emitted `VideoThumbnail` corresponds to a frame sample along the clip's timeline. You can display these in a `RecyclerView` or custom view to create a scrubber or timeline strip. ### Audio Waveforms Generate **Audio waveforms** in a similar way using `generateAudioThumbnailSequence`. This function emits a `Flow` of `AudioThumbnail` structs, which contain normalized audio samples (0…1). You can use the samples to render a waveform in a custom view. ```kotlin import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.flow.collect import kotlinx.coroutines.flow.onEach import kotlinx.coroutines.launch import ly.img.engine.Engine fun generateAudioWaveform( engine: Engine, audioClip: Int ) = CoroutineScope(Dispatchers.Main).launch { engine.block.generateAudioThumbnailSequence( block = audioClip, samplesPerChunk = 512, timeBegin = 0.0, timeEnd = 10.0, numberOfSamples = 8192, numberOfChannels = 2 // 1 = mono, 2 = stereo (interleaved L/R) ).onEach { audioThumbnail -> // audioThumbnail.chunkIndex: Int // audioThumbnail.samples: FloatArray (normalized 0.0 to 1.0) println("Audio chunk ${audioThumbnail.chunkIndex}: ${audioThumbnail.samples.size} samples") // Use samples to draw waveform // drawWaveform(audioThumbnail.samples) }.collect() } ``` > **Note:** Rendering a waveform is application-specific and must be implemented using a custom Android view or Canvas drawing. ## Exporting the Timeline To export a timeline, you export the `page` block as a video file. `exportVideo` accepts a progress callback to report export progress. ```kotlin import android.content.Context import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import ly.img.engine.Engine import ly.img.engine.MimeType import java.io.File suspend fun exportTimeline( engine: Engine, context: Context, page: Int ): File { // Get page duration val duration = engine.block.getDuration(page) // Export the page as MP4 val blob = engine.block.exportVideo( block = page, timeOffset = 0.0, duration = duration, mimeType = MimeType.MP4, progressCallback = { progress -> println("Export progress: ${progress.renderedFrames}/${progress.totalFrames} frames") println("Encoded: ${progress.encodedFrames} frames") } ) // Save to file val outputFile = File(context.filesDir, "export_${System.currentTimeMillis()}.mp4") withContext(Dispatchers.IO) { outputFile.outputStream().channel.use { channel -> channel.write(blob) } } return outputFile } ``` CE.SDK supports standard formats (MP4, MOV, WebM, and audio-only tracks). ## Complete Timeline Example Here's a complete example that creates a timeline, adds multiple clips, trims them, and exports: ```kotlin import android.content.Context import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import kotlinx.coroutines.withContext import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.MimeType import ly.img.engine.ShapeType import java.io.File fun buildAndExportTimeline( context: Context, license: String, userId: String ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.timeline") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1280, height = 720) // Create scene and page val scene = engine.scene.createForVideo() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) engine.block.setWidth(page, value = 1280F) engine.block.setHeight(page, value = 720F) // Create track val track = engine.block.create(DesignBlockType.Track) engine.block.appendChild(parent = page, child = track) // Add first video clip val video1 = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(video1, shape = engine.block.createShape(ShapeType.Rect)) val videoFill1 = engine.block.createFill(FillType.Video) engine.block.setString( block = videoFill1, property = "fill/video/fileURI", value = "https://cdn.img.ly/assets/demo/v1/ly.img.video/videos/pexels-drone-footage-of-a-surfer-barrelling-a-wave-12715991.mp4" ) engine.block.setFill(video1, fill = videoFill1) engine.block.appendChild(parent = track, child = video1) // Trim first clip: skip first 1 second, play 10 seconds engine.block.forceLoadAVResource(videoFill1) engine.block.setTrimOffset(videoFill1, offset = 1.0) engine.block.setTrimLength(videoFill1, length = 10.0) engine.block.setDuration(video1, duration = 10.0) // Add second video clip (automatically placed after first) val video2 = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(video2, shape = engine.block.createShape(ShapeType.Rect)) val videoFill2 = engine.block.createFill(FillType.Video) engine.block.setString( block = videoFill2, property = "fill/video/fileURI", value = "https://cdn.img.ly/assets/demo/v2/ly.img.video/videos/pexels-kampus-production-8154913.mp4" ) engine.block.setFill(video2, fill = videoFill2) engine.block.appendChild(parent = track, child = video2) engine.block.setDuration(video2, duration = 8.0) engine.block.fillParent(track) // Set page duration (10 + 8 = 18 seconds) engine.block.setDuration(page, duration = 18.0) // Export the timeline val blob = engine.block.exportVideo( block = page, timeOffset = 0.0, duration = 18.0, mimeType = MimeType.MP4, progressCallback = { progress -> println("Rendering: ${progress.renderedFrames}/${progress.totalFrames}") } ) // Save to file val outputFile = File(context.filesDir, "timeline_export.mp4") withContext(Dispatchers.IO) { outputFile.outputStream().channel.use { it.write(blob) } } println("Timeline exported to: ${outputFile.absolutePath}") engine.stop() } ``` ## Troubleshooting | Symptom | Likely Cause | Solution | |----------|---------------|-----------| | Clips overlap or play out of order | Misaligned time offset values | Ensure each clip's start time is unique and sequential | | Trim changes ignored | Trim start + duration exceed source length | Use `getAVResourceTotalDuration()` to confirm clip duration | | Thumbnails are blank | Resource not loaded yet | Call `forceLoadAVResource()` before generating thumbnails | | Playback stutters | Too many parallel HD tracks | Reduce simultaneous tracks or use compressed preview | | Export fails | Page duration not set | Always set page duration using `setDuration()` | *** ## Next Steps - Use [Control Audio and Video](https://img.ly/docs/cesdk/android/create-video/control-daba54/) to play, pause, seek, loop, and adjust volume or speed for timeline content. - [Add Captions](https://img.ly/docs/cesdk/android/edit-video/add-captions-f67565/) to place timed text that stays in sync with video and audio. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Edit Image" description: "Use CE.SDK to crop, transform, annotate, or enhance images with editing tools and programmatic APIs." platform: android url: "https://img.ly/docs/cesdk/android/edit-image-c64912/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Images](https://img.ly/docs/cesdk/android/edit-image-c64912/) --- --- ## Related Pages - [Integrating Background Removal in Android (Kotlin)](https://img.ly/docs/cesdk/android/edit-image/remove-bg-9dfcf7/) - Learn how to implement custom background removal using Google ML Kit's Selfie Segmentation in Android with CE.SDK. - [Transform](https://img.ly/docs/cesdk/android/edit-image/transform-9d189b/) - Crop, resize, rotate, scale, or flip images using CE.SDK's built-in transformation tools. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Integrating Background Removal in Android (Kotlin)" description: "Learn how to implement custom background removal using Google ML Kit's Selfie Segmentation in Android with CE.SDK." platform: android url: "https://img.ly/docs/cesdk/android/edit-image/remove-bg-9dfcf7/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Images](https://img.ly/docs/cesdk/android/edit-image-c64912/) > [Remove Background](https://img.ly/docs/cesdk/android/edit-image/remove-bg-9dfcf7/) --- The CE.SDK provides a flexible architecture that allows you to extend its capability to meet your specific needs. This guide demonstrates how to integrate a custom background removal feature using Google ML Kit. You can apply the same approach to implement any custom image processing functionality in your Android app. > **Note:** **ML Kit Selfie Segmentation** works best with images containing people. For more general subject segmentation, you may need to use third-party libraries or cloud-based APIs. ## What You'll Learn - How to extract the current image from the CE.SDK engine. - How to implement background removal using ML Kit Selfie Segmentation. - How to process the image and apply the segmentation mask. - How to update the image in the scene with the processed result. - How to keep operations async and handle errors gracefully. ## When To Use It - Want programmatic "Remove BG" functionality in your app. - Prefer on-device processing (no uploads) for latency, privacy, or offline use. - Need to integrate custom image processing logic (ML Kit, third-party libraries, or your own API). - Building custom UI or automation workflows. ## Setup ML Kit First, add the ML Kit Selfie Segmentation dependency to your `build.gradle`: ```kotlin dependencies { implementation("com.google.mlkit:segmentation-selfie:16.0.0-beta5") } ``` ## Extracting the Image A block that displays an image has an `imageFill` which contains the URI of the underlying image. The first step is to extract the image data from the fill. ```kotlin import android.content.Context import android.graphics.Bitmap import android.graphics.BitmapFactory import android.net.Uri import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import java.io.ByteArrayOutputStream import java.net.URL suspend fun extractImageFromScene( engine: Engine, context: Context ): Bitmap? { // Get the current page from the scene val page = engine.scene.getCurrentPage() ?: return null // Validate that the page contains an image val imageFill = engine.block.getFill(page) val fillType = engine.block.getType(imageFill) if (fillType != "//ly.img.ubq/fill/image") { return null } // Extract the image URI val imageFileURI = engine.block.getString(imageFill, property = "fill/image/imageFileURI") // Download and decode the image return withContext(Dispatchers.IO) { try { val imageData = if (imageFileURI.startsWith("http")) { // Download from URL val url = URL(imageFileURI) val outputStream = ByteArrayOutputStream() url.openStream().use { inputStream -> outputStream.use(inputStream::copyTo) } outputStream.toByteArray() } else { // Load from local file or content URI val uri = Uri.parse(imageFileURI) val inputStream = context.contentResolver.openInputStream(uri) inputStream?.readBytes() ?: byteArrayOf() } BitmapFactory.decodeByteArray(imageData, 0, imageData.size) } catch (e: Exception) { null } } } ``` ## Processing the Image with ML Kit With a `Bitmap`, you can now process the image using ML Kit Selfie Segmentation. Here's a complete implementation: ```kotlin import android.graphics.Bitmap import android.graphics.Color import com.google.mlkit.vision.common.InputImage import com.google.mlkit.vision.segmentation.Segmentation import com.google.mlkit.vision.segmentation.SegmentationMask import com.google.mlkit.vision.segmentation.selfie.SelfieSegmenterOptions import kotlinx.coroutines.tasks.await /** * Removes the background from an image using ML Kit Selfie Segmentation. * @param original The source bitmap to process. * @return A new bitmap with the background removed (transparent), or null if processing fails. */ suspend fun removeBackgroundWithMLKit(original: Bitmap): Bitmap? { try { // Configure ML Kit Selfie Segmentation val options = SelfieSegmenterOptions.Builder() .setDetectorMode(SelfieSegmenterOptions.SINGLE_IMAGE_MODE) .enableRawSizeMask() // Get mask at original image resolution .build() val segmenter = Segmentation.getClient(options) // Create InputImage from bitmap val inputImage = InputImage.fromBitmap(original, 0) // Process the image and get the segmentation mask val segmentationMask: SegmentationMask = segmenter.process(inputImage).await() // Create output bitmap with transparency val width = original.width val height = original.height val result = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888) // Get mask data val mask = segmentationMask.buffer val maskWidth = segmentationMask.width val maskHeight = segmentationMask.height // Apply the mask to create transparent background for (y in 0 until height) { for (x in 0 until width) { // Map image coordinates to mask coordinates val maskX = (x * maskWidth / width).coerceIn(0, maskWidth - 1) val maskY = (y * maskHeight / height).coerceIn(0, maskHeight - 1) // Get mask confidence (0.0 = background, 1.0 = foreground) val maskIndex = maskY * maskWidth + maskX val confidence = mask.getFloat(maskIndex * 4) // 4 bytes per float // Get original pixel color val originalPixel = original.getPixel(x, y) if (confidence > 0.5f) { // Foreground - keep original pixel result.setPixel(x, y, originalPixel) } else { // Background - make transparent result.setPixel(x, y, Color.TRANSPARENT) } } } // Clean up segmenter.close() return result } catch (e: Exception) { e.printStackTrace() return null } } ``` ## Replace the Image in the Scene With a processed image, the last step is to update the fill with the new image: 1. Save the processed bitmap to a file. 2. Get the file URI. 3. Update the image fill's source set with the new URI. ```kotlin import android.content.Context import android.graphics.Bitmap import android.net.Uri import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import ly.img.engine.Engine import ly.img.engine.Source import java.io.File import java.io.FileOutputStream suspend fun replaceImageInScene( engine: Engine, context: Context, processedBitmap: Bitmap ) { // Save the bitmap to a file val imageFile = withContext(Dispatchers.IO) { val file = File(context.cacheDir, "bg_removed_${System.currentTimeMillis()}.png") FileOutputStream(file).use { outputStream -> processedBitmap.compress(Bitmap.CompressFormat.PNG, 100, outputStream) } file } val processedImageUri = Uri.fromFile(imageFile) // Get the current page and its fill val page = engine.scene.getCurrentPage() ?: return val imageFill = engine.block.getFill(page) // Update the source set with the new image engine.block.setSourceSet( block = imageFill, property = "fill/image/sourceSet", sourceSet = listOf( Source( uri = processedImageUri, width = processedBitmap.width.toUInt(), height = processedBitmap.height.toUInt() ) ) ) } ``` ## Complete Function Here's the complete function that combines all the steps: ```kotlin import android.content.Context import android.graphics.Bitmap import android.graphics.BitmapFactory import android.graphics.Color import android.net.Uri import com.google.mlkit.vision.common.InputImage import com.google.mlkit.vision.segmentation.Segmentation import com.google.mlkit.vision.segmentation.SegmentationMask import com.google.mlkit.vision.segmentation.selfie.SelfieSegmenterOptions import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.tasks.await import kotlinx.coroutines.withContext import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.Source import java.io.ByteArrayOutputStream import java.io.File import java.io.FileOutputStream import java.net.URL suspend fun performBackgroundRemoval( engine: Engine, context: Context ): Boolean { return withContext(Dispatchers.Main) { try { // Step 1: Get the current page val page = engine.scene.getCurrentPage() ?: return@withContext false // Step 2: Validate it's an image fill val imageFill = engine.block.getFill(page) val fillType = engine.block.getType(imageFill) if (fillType != "//ly.img.ubq/fill/image") { return@withContext false } // Step 3: Extract image data val imageFileURI = engine.block.getString(imageFill, property = "fill/image/imageFileURI") val originalBitmap = withContext(Dispatchers.IO) { val imageData = if (imageFileURI.startsWith("http")) { val url = URL(imageFileURI) val outputStream = ByteArrayOutputStream() url.openStream().use { inputStream -> outputStream.use(inputStream::copyTo) } outputStream.toByteArray() } else { val uri = Uri.parse(imageFileURI) context.contentResolver.openInputStream(uri)?.readBytes() ?: byteArrayOf() } BitmapFactory.decodeByteArray(imageData, 0, imageData.size) } ?: return@withContext false // Step 4: Process with ML Kit val options = SelfieSegmenterOptions.Builder() .setDetectorMode(SelfieSegmenterOptions.SINGLE_IMAGE_MODE) .enableRawSizeMask() .build() val segmenter = Segmentation.getClient(options) val inputImage = InputImage.fromBitmap(originalBitmap, 0) val segmentationMask: SegmentationMask = segmenter.process(inputImage).await() // Step 5: Apply mask to create transparent background val width = originalBitmap.width val height = originalBitmap.height val result = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888) val mask = segmentationMask.buffer val maskWidth = segmentationMask.width val maskHeight = segmentationMask.height for (y in 0 until height) { for (x in 0 until width) { val maskX = (x * maskWidth / width).coerceIn(0, maskWidth - 1) val maskY = (y * maskHeight / height).coerceIn(0, maskHeight - 1) val maskIndex = maskY * maskWidth + maskX val confidence = mask.getFloat(maskIndex * 4) val originalPixel = originalBitmap.getPixel(x, y) result.setPixel( x, y, if (confidence > 0.5f) originalPixel else Color.TRANSPARENT ) } } segmenter.close() // Step 6: Save processed image val imageFile = withContext(Dispatchers.IO) { val file = File(context.cacheDir, "bg_removed_${System.currentTimeMillis()}.png") FileOutputStream(file).use { outputStream -> result.compress(Bitmap.CompressFormat.PNG, 100, outputStream) } file } val processedImageUri = Uri.fromFile(imageFile) // Step 7: Update the scene engine.block.setSourceSet( block = imageFill, property = "fill/image/sourceSet", sourceSet = listOf( Source( uri = processedImageUri, width = result.width.toUInt(), height = result.height.toUInt() ) ) ) return@withContext true } catch (e: Exception) { e.printStackTrace() return@withContext false } } } ``` ## Usage Example Here's how to use the background removal function in your app: ```kotlin import android.content.Context import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.Engine fun removeBackgroundFromCurrentImage( engine: Engine, context: Context ) = CoroutineScope(Dispatchers.Main).launch { val success = performBackgroundRemoval(engine, context) if (success) { println("✅ Background removed successfully!") } else { println("❌ Failed to remove background") } } ``` ## Optimizations ### 1. Performance for Large Images For better performance with large images, downscale before processing: ```kotlin fun downscaleIfNeeded(bitmap: Bitmap, maxSize: Int = 1024): Bitmap { val maxDimension = maxOf(bitmap.width, bitmap.height) if (maxDimension <= maxSize) return bitmap val scale = maxSize.toFloat() / maxDimension val newWidth = (bitmap.width * scale).toInt() val newHeight = (bitmap.height * scale).toInt() return Bitmap.createScaledBitmap(bitmap, newWidth, newHeight, true) } ``` ### 2. Improve Mask Quality Apply smoothing to the mask for better edge quality: ```kotlin /** * Apply feathering to the mask for softer edges. */ fun applyFeathering(confidence: Float, threshold: Float = 0.5f, feather: Float = 0.1f): Float { return when { confidence >= threshold + feather -> 1.0f confidence <= threshold - feather -> 0.0f else -> { // Linear interpolation in the feather range (confidence - (threshold - feather)) / (2 * feather) } } } ``` Then use it when applying the mask: ```kotlin val alpha = applyFeathering(confidence) if (alpha > 0) { val r = Color.red(originalPixel) val g = Color.green(originalPixel) val b = Color.blue(originalPixel) val newAlpha = (alpha * 255).toInt() result.setPixel(x, y, Color.argb(newAlpha, r, g, b)) } else { result.setPixel(x, y, Color.TRANSPARENT) } ``` ## Troubleshooting **❌ Fill is not an image**: Always check the fill type before processing: ```kotlin val fillType = engine.block.getType(imageFill) if (fillType != "//ly.img.ubq/fill/image") { // Not an image fill, cannot process return } ``` **❌ Mask quality is poor**: - Use `enableRawSizeMask()` for full-resolution masks. - Apply feathering (see optimization section above). - Consider pre-processing the image for better lighting/contrast. **❌ Performance is slow on large images**: - Downscale images before processing (see optimization section). - Use `STREAM_MODE` instead of `SINGLE_IMAGE_MODE` for video. - Process on a background thread (already handled with coroutines in the example). **❌ Segmentation only works for people**: ML Kit Selfie Segmentation is optimized for human subjects. For general object segmentation, consider: - Using TensorFlow Lite models for object detection. - Cloud-based APIs (Google Cloud Vision, etc.). - Third-party segmentation libraries. **❌ App crashes or ML Kit errors**: - Ensure ML Kit dependencies are properly included. - Check that Google Play Services are available on the device. - Handle exceptions gracefully and provide user feedback. ## Alternative: Custom Segmentation Models For more advanced segmentation beyond people, you can use TensorFlow Lite models. Here's a basic structure: ```kotlin import org.tensorflow.lite.Interpreter import java.nio.ByteBuffer class CustomSegmentation(modelPath: String) { private val interpreter: Interpreter = Interpreter(loadModelFile(modelPath)) fun segment(bitmap: Bitmap): Bitmap? { // 1. Preprocess bitmap to model input format // 2. Run inference // 3. Post-process output to mask // 4. Apply mask to create transparent background // Implementation depends on your specific model return null } private fun loadModelFile(modelPath: String): ByteBuffer { // Load TFLite model file // Implementation omitted for brevity TODO("Load your .tflite model file") } } ``` ## Next Steps Now that you can remove backgrounds, explore related guides: - [Scale & Transform](https://img.ly/docs/cesdk/android/edit-image/transform/scale-ebe367/) images after background removal. - [Chroma Key](https://img.ly/docs/cesdk/android/filters-and-effects/chroma-key-green-screen-1e3e99/) for green screen effects. - [Batch Processing](https://img.ly/docs/cesdk/android/automation/batch-processing-ab2d18/) for processing multiple images. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Transform" description: "Crop, resize, rotate, scale, or flip images using CE.SDK's built-in transformation tools." platform: android url: "https://img.ly/docs/cesdk/android/edit-image/transform-9d189b/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Images](https://img.ly/docs/cesdk/android/edit-image-c64912/) > [Transform](https://img.ly/docs/cesdk/android/edit-image/transform-9d189b/) --- --- ## Related Pages - [Move](https://img.ly/docs/cesdk/android/edit-image/transform/move-818dd9/) - Position an image relative to its parent using either percentage or units - [Crop Images in Android](https://img.ly/docs/cesdk/android/edit-image/transform/crop-f67a47/) - Cut out specific areas of an image to focus on key content or change aspect ratio. - [Rotate](https://img.ly/docs/cesdk/android/edit-image/transform/rotate-5f39c9/) - Documentation for Rotate - [Resize](https://img.ly/docs/cesdk/android/edit-image/transform/resize-407242/) - Change the size of individual elements or groups. - [Scale in Android (Kotlin)](https://img.ly/docs/cesdk/android/edit-image/transform/scale-ebe367/) - Resize images uniformly in your Android app using Kotlin. - [Flip Images](https://img.ly/docs/cesdk/android/edit-image/transform/flip-035e9f/) - Flip images horizontally or vertically. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Crop Images in Android" description: "Cut out specific areas of an image to focus on key content or change aspect ratio." platform: android url: "https://img.ly/docs/cesdk/android/edit-image/transform/crop-f67a47/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Images](https://img.ly/docs/cesdk/android/edit-image-c64912/) > [Transform](https://img.ly/docs/cesdk/android/edit-image/transform-9d189b/) > [Crop](https://img.ly/docs/cesdk/android/edit-image/transform/crop-f67a47/) --- The CreativeEditor SDK (CE.SDK) offers both interactive UI components and powerful Kotlin APIs for cropping images. Image cropping is an essential feature for any Android photo editing app, allowing users to focus on important content and fit images to specific dimensions. Whether you need simple aspect ratio adjustments or advanced programmatic, follow this guide to learn how to integrate cropping into your Android app. ## Interactive crop interface The SDK includes ready-to-use crop controls that integrate seamlessly with your Android app. These components: - Handle tap gestures and aspect ratio selection. - Provide immediate visual feedback to users. This is particularly useful for: - Apps targeting social media formats. - Maintaining consistent visual branding.  ### How users interact with crop tools 1. **Tap the image** to select it for editing. 2. **Tap the crop button** in your app's editing interface. 3. **Drag handles** at corners and edges to define the crop region. 4. **Apply transformations** like flip or rotate before finalizing. 5. **Confirm changes** to complete the crop operation.  Once cropped, your image: - Updates in the editor. - Preserves the original data and transformation history for future adjustments. ### Configuring crop capabilities By default, cropping is enabled in the editor UI. When building custom interfaces or specialized editing flows, you can control crop availability through configuration settings: ```kotlin engine.editor.setSettingBoolean("doubleClickToCropEnabled", true) engine.editor.setSettingBoolean("controlGizmo/showCropHandles", true) engine.editor.setSettingBoolean("controlGizmo/showCropScaleHandles", true) ``` The cropping handles are only available when a selected block has a fill of type `FillType.Image`. Otherwise setting the edit mode of the `engine.editor` to crop has no effect. ## Crop images with Kotlin code For advanced Android applications, you'll often need precise control over cropping operations through code. This approach suits very well: - Batch processing - Automated workflows - Custom editing interfaces implementations. The SDK automatically handles image fitting when you load content into blocks – if your image dimensions don't match the container, intelligent cropping is applied automatically. When implementing crop operations in your Kotlin code, keep in mind that you're manipulating the underlying image's scale, position, and orientation properties. The examples shown typically modify both x and y axes uniformly, but you can adjust them independently for creative distortion effects. ### Reset Crop When an image is initially placed into a block it will get crop scale and crop translation values. Resetting the crop will return the image to the original values.  This is a block (called `imageBlock` in the example code) with the following elements: - Dimensions of 400 × 400. - Filled with an image that has dimensions of 600 × 530. - The image has slight scaling and translation applied so that it fills the block evenly. At any time, the code can execute the reset crop command to return it to this stage. ```kotlin engine.block.resetCrop(imageBlock) ``` ### Crop Translation The **translation values**: - Adjust the placement of the **origin point** of an image. - Can be read and changed. - Aren't pixel units or centimeters, but are scaled percentages. An image that has its origin point at the origin point of the crop block will have a translation value of 0.0 for x and y.  ```kotlin engine.block.setCropTranslationX(imageBlock, 0.25f) ``` This image: - Has had its translation in the x direction set to 0.25. - Was moved 1/4 of its width to the right as a result. Setting the value to -0.25 would shift the origin to the left. These are absolute values. Setting the x value to 0.25 and then setting it to -0.25 does not move the image to an offset of 0.0. How values might affect the image: - `setCropTranslationY(block: DesignBlock, translationY: Float)` function adjusts the translation of the image in the **vertical direction**. - **Negative** values move the image **up**. - **Positive** values move the image **down**. To read the current crop translation values you can use the convenience getters for the x and y values. ```kotlin val currentX = engine.block.getCropTranslationX(imageBlock) val currentY = engine.block.getCropTranslationY(imageBlock) ``` ### Crop Scale The scale values: - Adjust the height and width of the underlying image. - Make the image **larger** when greater than **1.0**. - Make the image **smaller** when less than 1.0. Unless the image also has offsetting translation applied, the center of the image will move.  This image has been scaled by 1.5 in the x and y directions, but the origin point has not been translated. So, the center of the image has moved. ```kotlin engine.block.setCropScaleX(imageBlock, 1.5f) engine.block.setCropScaleY(imageBlock, 1.5f) ``` To read the current crop scale values you can use the convenience getters for the x and y values. ```kotlin val currentX = engine.block.getCropScaleX(imageBlock) val currentY = engine.block.getCropScaleY(imageBlock) ``` ## Crop Rotate Similar to rotating blocks, the crop rotation function uses radians in the following way: - **Positive** values rotate clockwise. - **Negative** values rotate counterclockwise. - The image rotates around its **center**.  ```kotlin import kotlin.math.PI engine.block.setCropRotation(imageBlock, (PI / 4.0).toFloat()) ``` For working with radians, Kotlin has a constant defined for pi. It can be used as `PI` from `kotlin.math.PI`. Because the `setCropRotation` function takes a `Float` for the rotation value, you can use `.toFloat()` to convert the Double to Float. ### Crop to Scale Ratio To center crop an image, you can use the scale ratio. This will adjust the x and y scales of the image evenly, and adjust the translation to keep it centered.  This image has been scaled by 2.0 in the x and y directions. Its translation has been adjusted by -0.5 in the x and y directions to keep the image centered. ```kotlin engine.block.setCropScaleRatio(imageBlock, 2.0f) ``` Using the crop scale ratio function is the same as calling the translation and scale functions, but in one line. ```kotlin engine.block.setCropScaleX(imageBlock, 2.0f) engine.block.setCropScaleY(imageBlock, 2.0f) engine.block.setCropTranslationX(imageBlock, -0.5f) engine.block.setCropTranslationY(imageBlock, -0.5f) ``` ### Chained Crops Crop operations can be chained together. The order of the chaining impacts the final image.  ```kotlin import kotlin.math.PI engine.block.setCropScaleRatio(imageBlock, 2.0f) engine.block.setCropRotation(imageBlock, (PI / 3.0).toFloat()) ```  ```kotlin import kotlin.math.PI engine.block.setCropRotation(imageBlock, (PI / 3.0).toFloat()) engine.block.setCropScaleRatio(imageBlock, 2.0f) ``` ### Flipping the Crop There are two functions for crop flipping the image: - Horizontal - Vertical They each flip the image along its center.  ```kotlin engine.block.flipCropVertical(imageBlock) engine.block.flipCropHorizontal(imageBlock) ``` The image will be crop flipped every time the function gets called. So calling the function an even number of times will return the image to its original orientation. ### Filling the Frame When the various crop operations cause the background of the crop block to be displayed, such as in the **Crop Translation** example above, the function ```kotlin engine.block.adjustCropToFillFrame(imageBlock, minScaleRatio = 1.0f) ``` will adjust the translation values and the scale values of the image so that the entire crop block is filled. This is not the same as resetting the crop. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Flip Images" description: "Flip images horizontally or vertically." platform: android url: "https://img.ly/docs/cesdk/android/edit-image/transform/flip-035e9f/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Images](https://img.ly/docs/cesdk/android/edit-image-c64912/) > [Transform](https://img.ly/docs/cesdk/android/edit-image/transform-9d189b/) > [Flip](https://img.ly/docs/cesdk/android/edit-image/transform/flip-035e9f/) --- The CreativeEditor SDK includes a **flipping** feature that you can add to your **Android** app. Flipping is a powerful transformation that Android photo apps use for creating mirror effects, correcting orientation, and achieving symmetrical layouts. Learn in this guide how to implement both **interactive** flip controls and **programmatic** flipping, through clean **Kotlin** APIs. ## Flip features The flip feature enables the following actions: - Horizontal and vertical image mirroring - Integration with template systems and creative workflows - Programmatic flip state management and toggling ## Flip applications Implement flipping for: - Correcting selfie camera orientation in Android camera apps - Creating mirror effects for product photography - Building symmetrical design layouts and compositions *** ## Flip horizontally or vertically Use the `flip/horizontal` and `flip/vertical` properties to control mirroring. These are **boolean** properties with defined helper functions. All flips occur around the center point of a block. ```kotlin engine.block.setFlipVertical(imageBlock, true) engine.block.setFlipHorizontal(imageBlock, true) ``` To determine if a block has been flipped, you can either: - Query the **properties**. - Use **helper functions**. ```kotlin val isFlippedVertical = engine.block.getFlipVertical(imageBlock) val isFlippedHorizontal = engine.block.getFlipHorizontal(imageBlock) ``` *** ## Toggle flipping To toggle the flip state, the code reads the current flip value and sets it to its opposite: ```kotlin val currentVerticalFlip = engine.block.getFlipVertical(imageBlock) engine.block.setFlipVertical(imageBlock, !currentVerticalFlip) val currentHorizontalFlip = engine.block.getFlipHorizontal(imageBlock) engine.block.setFlipHorizontal(imageBlock, !currentHorizontalFlip) ``` ## Reset flipping To reset all flips: ```kotlin engine.block.setFlipVertical(imageBlock, false) engine.block.setFlipHorizontal(imageBlock, false) ``` *** ## Flip multiple elements Group elements to flip them together: ```kotlin val groupId = engine.block.group(listOf(imageBlock, textBlock)) engine.block.setFlipHorizontal(groupId, true) ``` *** --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Move" description: "Position an image relative to its parent using either percentage or units" platform: android url: "https://img.ly/docs/cesdk/android/edit-image/transform/move-818dd9/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Images](https://img.ly/docs/cesdk/android/edit-image-c64912/) > [Transform](https://img.ly/docs/cesdk/android/edit-image/transform-9d189b/) > [Move](https://img.ly/docs/cesdk/android/edit-image/transform/move-818dd9/) --- The CreativeEditor SDK provides a **positioning** feature you can add to your Android app. Positioning images accurately is fundamental to creating **professional layouts**. Both drag-and-drop interfaces and precise coordinate-based positioning are available through Kotlin. Whether you're building **grid layouts**, **freeform canvases**, or **template-based designs**, this guide covers all positioning needs. ## Movement Capabilities The positioning feature in CE.SDK enables the following movements: - **Precise positioning** with Kotlin coordinate APIs. - **Drag-and-drop** interface for user interaction. - Canvas-based absolute and **percentage** positioning. - Group movement for **maintaining element relationships**. - Position constraints for **template protection**. ## Position control scenarios Implement positioning to: - Create pixel-perfect layouts for Android interfaces. - Enable intuitive drag-and-drop editing experiences. - Create snap-to-grid or guided positioning systems. *** ## Move an image block programmatically Image position is controlled using the `position/x` and `position/y` properties. They can use either absolute or relative (percentage) values. Helper functions are also available for setting properties. For example, the following code moves the image to coordinates (150, 100) on the canvas. ```kotlin engine.block.setFloat(imageBlock, "position/x", 150f) engine.block.setFloat(imageBlock, "position/y", 100f) ``` or ```kotlin engine.block.setPositionX(imageBlock, 150f) engine.block.setPositionY(imageBlock, 100f) ``` For percentage-based positioning, the following code moves the image to the center of the canvas, regardless of the dimensions of the canvas: ```kotlin import ly.img.engine.PositionMode engine.block.setPositionXMode(imageBlock, PositionMode.PERCENT) engine.block.setPositionYMode(imageBlock, PositionMode.PERCENT) engine.block.setPositionX(imageBlock, 0.5f) engine.block.setPositionY(imageBlock, 0.5f) ``` As with setting position, you can update or check the mode using `position/x/mode` and `position/y/mode` properties. ```kotlin val xPosition = engine.block.getPositionX(imageBlock) val yPosition = engine.block.getPositionY(imageBlock) ``` *** ## Move images with the UI Users can drag and drop elements directly in the editor canvas. *** ## Move multiple elements together Group elements before moving to keep them aligned: ```kotlin val groupId = engine.block.group(listOf(imageBlock, textBlock)) engine.block.setPositionX(groupId, 200f) ``` The preceding code moves the entire group to 200 from the left edge. *** ## Move relative to current position To nudge an image instead of setting an absolute position: ```kotlin val xPosition = engine.block.getPositionX(imageBlock) engine.block.setPositionX(imageBlock, xPosition + 20f) ``` The preceding code moves the image 20 points to the right. *** ## Lock movement (optional) When building templates, you might want to lock movement to protect the layout: ```kotlin engine.block.setScopeEnabled(imageBlock, "layer/move", false) ``` You can also disable all transformations by locking, this is regardless of working with a template. ```kotlin engine.block.setTransformLocked(imageBlock, true) ``` *** ## Troubleshooting | Issue | Solution | | ------------------------ | ----------------------------------------------------- | | Image not moving | Ensure it is not constrained or locked | | Unexpected position | Check canvas coordinates and alignment settings | | Grouped items misaligned | Confirm all items share the same reference point | | Can't move via UI | Ensure the move feature is enabled in the UI settings | *** --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Resize" description: "Change the size of individual elements or groups." platform: android url: "https://img.ly/docs/cesdk/android/edit-image/transform/resize-407242/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Images](https://img.ly/docs/cesdk/android/edit-image-c64912/) > [Transform](https://img.ly/docs/cesdk/android/edit-image/transform-9d189b/) > [Resize](https://img.ly/docs/cesdk/android/edit-image/transform/resize-407242/) --- The CreativeEditor SDK (CE.SDK) provides a **resize** feature for **Android** apps. Precise image sizing is crucial for **fitting content** into specific layouts, or exporting to various formats. CE.SDK offers both **interactive** resize controls and powerful **Kotlin** APIs for dimensional control. Whether you're building **social media templates** or **responsive interfaces**, this guide covers all resizing scenarios. ## Resizing features CE.SDK provides comprehensive tools for adjusting image dimensions in your Android app. The resizing feature enables the following actions: - Interactive resize handles for user control - Programmatic dimension setting with Kotlin - Group resizing for maintaining element relationships - Resize restrictions for layout protection ## Common resizing scenarios Apply resizing for: - Fitting images to Android layout constraints - Creating content for different screen densities - Implementing template-based designs with fixed dimensions ### Resize a block using the UI When a block is selected: - **Handles** appear on the four sides to allow the user to resize either the width or the height of the block. - A setting in the `editor` controls the **visibility** of the handles. - When the handles are **invisible**, a user can't resize using tapping or a mouse. ```kotlin engine.editor.setSettingBoolean("controlGizmo/showResizeHandles", false) ```  The image on the left displays all resize handles, while the right image has them disabled. Even with resize handles hidden, users can still access scale and rotation controls. ### Resize a block programmatically Each block contains the following **properties** that you can update to resize the block: - `width` - `height` The values of each property can be: - `SizeMode.AUTO`: automatic sizing. - `SizeMode.PERCENT`: the relationship between a block and its parent. For example, a block containing the following properties: - `SizeMode.PERCENT` mode - `width` set to `1.0f` will make its size to 100% of its parent's width. The following code sets a block to be 400 × 400 px: ```kotlin engine.block.setWidth(imageBlock, 400.0f) engine.block.setHeight(imageBlock, 400.0f) ```  There's also a convenience function for setting both width and height at once: ```kotlin engine.block.resize(imageBlock, 400.0f, 400.0f) ```  ```kotlin import ly.img.engine.SizeMode engine.block.setWidthMode(imageBlock, SizeMode.PERCENT) engine.block.setWidth(imageBlock, 0.5f) // 50% of parent width engine.block.setHeightMode(imageBlock, SizeMode.PERCENT) engine.block.setHeight(imageBlock, 0.5f) // 50% of parent height ``` In this code: - The block on the **left** takes up 50% of the width and height of its parent. - The block on the **right** has been set to 25% of the width and height of its parent. ### Resize blocks as a group Group blocks to resize them together: ```kotlin val groupId = engine.block.group(listOf(imageBlock, textBlock)) engine.block.resize(groupId, 600.0f, 400.0f) ``` ### Lock resizing When working with templates, you can lock a block from being resized by setting its scope: ```kotlin engine.block.setScopeEnabled(imageBlock, "layer/resize", false) ``` To prevent users from transforming an element at all: ```kotlin engine.block.setTransformLocked(imageBlock, true) ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Rotate" description: "Documentation for Rotate" platform: android url: "https://img.ly/docs/cesdk/android/edit-image/transform/rotate-5f39c9/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Images](https://img.ly/docs/cesdk/android/edit-image-c64912/) > [Transform](https://img.ly/docs/cesdk/android/edit-image/transform-9d189b/) > [Rotate](https://img.ly/docs/cesdk/android/edit-image/transform/rotate-5f39c9/) --- The CreativeEditor SDK provides a **rotation** feature for Android apps. Image rotation is a core editing feature that Android users expect in photo apps. The CreativeEditor SDK offers straightforward methods for incorporating both **touch-based rotation** controls and precise **programmatic rotation** using **Kotlin**. This guide covers everything from basic rotation gestures to advanced group transformations and rotation constraints. ## Key rotation features - Touch-based rotation with intuitive drag handles - Precise angle control through Kotlin APIs - Rotation locking for template protection - Multi-element rotation as grouped objects ### Touch-based image rotation Users can rotate images naturally using the built-in rotation handles. When you select an image: 1. Rotation controls automatically appear. 2. You can now freely rotate the image through drag gestures.  ### Implementing rotation in Kotlin Your Android app can control image rotation programmatically using the `setRotation` method. Pass the block ID and rotation angle in radians: ```kotlin import kotlin.math.PI engine.block.setRotation(imageBlock, (PI / 4).toFloat()) ``` Since Android developers often work with degrees, here are handy conversion utilities: ```kotlin val angleInRadians: Float = (angleInDegrees * PI / 180).toFloat() val angleInDegrees: Float = (angleInRadians * 180 / PI).toFloat() ``` To read the current rotation state in your app: ```kotlin val currentRotation = engine.block.getRotation(imageBlock) ``` > **Note:** This rotates the entire block. If you want to rotate an image that is filling > a block but not the block, explore the > [crop rotate](https://img.ly/docs/cesdk/android/edit-image/transform/crop-f67a47/) function. ### Locking Rotation You can remove the rotation handle from the UI by changing the setting for the engine. This will affect *all* blocks. ```kotlin engine.editor.setSettingBoolean("controlGizmo/showRotateHandles", false) ``` Although the code makes the rotation handle invisible, the user can still use the two-finger rotation gesture on a touch device. You can turn off that gesture with the following setting: ```kotlin engine.editor.setSettingBoolean("touch/rotateAction", false) ``` When you want to lock only certain blocks, you can toggle the transform lock property. This will apply to all transformations for the block. ```kotlin engine.block.setTransformLocked(imageBlock, true) ``` ### Rotating As a Group To rotate multiple elements together, first add them to a `group` and then rotate the group. ```kotlin import kotlin.math.PI val groupId = engine.block.group(listOf(imageBlock, textBlock)) engine.block.setRotation(groupId, (PI / 2).toFloat()) ``` ### Troubleshooting Troubleshooting | Issue | Solution | | ----------------------------------- | ------------------------------------------------------------------------------- | | Image appears offset after rotation | Make sure the pivot point is centered (default is center). | | Rotation not applying | Confirm that the image block is inserted and rendered before applying rotation. | | Rotation handle not visible | Check that interactive UI controls are enabled in the settings. | --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Scale in Android (Kotlin)" description: "Resize images uniformly in your Android app using Kotlin." platform: android url: "https://img.ly/docs/cesdk/android/edit-image/transform/scale-ebe367/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Images](https://img.ly/docs/cesdk/android/edit-image-c64912/) > [Transform](https://img.ly/docs/cesdk/android/edit-image/transform-9d189b/) > [Scale](https://img.ly/docs/cesdk/android/edit-image/transform/scale-ebe367/) --- Scaling lets users enlarge or shrink a block directly on the canvas. In CE.SDK, scaling is a transform property that applies uniformly to most block types. This guide shows how to scale images using CE.SDK in your Android app using Kotlin. You'll learn how to scale image blocks proportionally, scale groups, and apply scaling constraints to protect template structure. The standard UI already supports pinch-to-zoom and on-screen scale handles. Scaling programmatically gives you finer control. This is ideal for automation, custom UI, or template-driven apps. When you want to scale the image **inside** the block and leave the block dimensions unchanged, you'll use [crop scale](https://img.ly/docs/cesdk/android/edit-image/transform/crop-f67a47/) instead. ## What You'll Learn - Scale images programmatically using Kotlin. - Scale images proportionally or non-uniformly. - Scale grouped elements. - Enable or disable scaling via pinch gestures or gizmo handles. ## When to Use Use image scaling when your UI needs to: - Let users zoom artwork smoothly without cropping - Enforce a canonical image size in templates - Support controls like sliders instead of gestures - Scale multiple elements together (logos, product bundles, captions) ## Scaling Basics On Android, you scale blocks using the **block API**. The main pieces you'll use are: - `engine.block.scale(block: Int, scaleX: Float, scaleY: Float, anchorX: Float = 0f, anchorY: Float = 0f)` - `width` / `height` and their modes (`setWidthMode`, `setHeightMode`) - crop-related functions like `setCropScaleX`, `setCropScaleY`, and `setCropTranslationX` / `Y` Control the size with the following scale values: - `1.0f`: represents the **original** size. - Larger than `1.0f`: **increases** the size. - Smaller than `1.0f`: **shrinks** the size. > **Note:** The examples below use image blocks, but this same approach works for shapes, text, stickers, and groups as long as you have their block ID. ## Scale an Image Uniformly Uniform scaling uses the `scale()` function. A scale value of `1.0f` is the original scale. Values larger than `1.0f` increase the scale of the block and values lower than `1.0f` scale the block smaller. A value of `2.0f`, for example makes the block twice as large. This scales the image to 150% of its original size. Because the default anchor point is the top-left corner, the block grows outward from that corner. ```kotlin import ly.img.engine.Engine engine.block.scale(imageBlock, scaleX = 1.5f, scaleY = 1.5f) ```  By default, the anchor point for the image when scaling is the origin point on the top left. The scale function has two optional parameters to move the anchor point in the x and y direction. They can have values between `0.0f` and `1.0f` This scales the image to 150% of its original size. The origin anchor point is 0.5, 0.5 so the image expands from the center. ```kotlin engine.block.scale(imageBlock, scaleX = 1.5f, scaleY = 1.5f, anchorX = 0.5f, anchorY = 0.5f) ```  ## Scale Non-Uniformly To stretch or compress only one axis, thus distorting an image, use this combination: - The crop scale function - The width or height function How you decide to make the adjustment will have different results. Below are three examples of scaling the original image in the x direction only.  ```kotlin import ly.img.engine.Engine import ly.img.engine.SizeMode engine.block.setWidthMode(imageBlock, mode = SizeMode.AUTO) val newWidth = engine.block.getWidth(imageBlock) * 1.5f engine.block.setWidth(imageBlock, value = newWidth) ``` The image continues respecting its fill mode (usually `.COVER`), so the content scales automatically as the frame widens.  ```kotlin engine.block.setCropScaleX(imageBlock, scaleX = 1.5f) engine.block.setWidthMode(imageBlock, mode = SizeMode.AUTO) val newWidth = engine.block.getWidth(imageBlock) * 1.5f engine.block.setWidth(imageBlock, value = newWidth) ``` This uses crop scale to scale the image in a single direction and then adjusts the block's width to match the change. The change in width does not take the crop into account and so distorts the image as it's scaling the scaled image.  ```kotlin engine.block.setCropScaleX(imageBlock, scaleX = 1.5f) engine.block.setWidthMode(imageBlock, mode = SizeMode.AUTO) val newWidth = engine.block.getWidth(imageBlock) * 1.5f engine.block.setWidth(imageBlock, value = newWidth, maintainCrop = true) ``` By setting the `maintainCrop` parameter to true, expanding the width of the image by the scale factor respects the crop scale and the image is less distorted. ## Scale Images with Built-In Gestures or Gizmos The CE.SDK UI supports these interactions automatically: ### Pinch to Zoom Enabled by default: ```kotlin import ly.img.engine.Engine engine.editor.setSettingBoolean("touch/pinchAction", value = true) ``` Setting this to false disables pinch scaling entirely. For environments with keyboard and mouse a similar property exists: ```kotlin engine.editor.setSettingBoolean("mouse/enableZoom", value = true) ``` ### Gizmo Scale Handles The UI can show corner handles for drag-scaling: ```kotlin engine.editor.setSettingBoolean("controlGizmo/showScaleHandles", value = true) ``` This mirrors the behavior of native editors. > **Note:** Changing these settings affects how the CE.SDK interprets user input. It doesn't prevent you from scaling blocks programmatically with `scale()`. ## Scale Multiple Elements Together If you combine multiple blocks into a group, scaling the group scales every member: ```kotlin import ly.img.engine.Engine val groupId = engine.block.group(listOf(imageBlock, textBlock)) engine.block.scale(groupId, scaleX = 0.75f, scaleY = 0.75f) ``` This scales the entire group to 75%. ## Lock Scaling When working with templates, you can lock a block from scaling by setting its scope. The [guide on locking](https://img.ly/docs/cesdk/android/create-templates/lock-131489/) provides more information. ```kotlin import ly.img.engine.Engine engine.block.setScopeEnabled(imageBlock, key = "layer/resize", enabled = false) ``` To prevent users from applying **any** transform to a block: ```kotlin engine.block.setTransformLocked(imageBlock, locked = true) ``` ## Complete Scaling Example Here's a complete example showing different scaling operations in a single function: ```kotlin import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType import ly.img.engine.SizeMode fun scaleImageExample( license: String, userId: String ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.scale") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) // Create scene and page val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) // Create an image block val imageBlock = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(imageBlock, shape = engine.block.createShape(ShapeType.Rect)) val imageFill = engine.block.createFill(FillType.Image) engine.block.setString( block = imageFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg" ) engine.block.setFill(imageBlock, fill = imageFill) engine.block.setWidth(imageBlock, value = 300F) engine.block.setHeight(imageBlock, value = 300F) engine.block.appendChild(parent = page, child = imageBlock) // Example 1: Scale uniformly from top-left engine.block.scale(imageBlock, scaleX = 1.5f, scaleY = 1.5f) // Example 2: Scale uniformly from center engine.block.scale( imageBlock, scaleX = 0.75f, scaleY = 0.75f, anchorX = 0.5f, anchorY = 0.5f ) // Example 3: Non-uniform scaling with crop engine.block.setCropScaleX(imageBlock, scaleX = 1.5f) engine.block.setWidthMode(imageBlock, mode = SizeMode.AUTO) val newWidth = engine.block.getWidth(imageBlock) * 1.5f engine.block.setWidth(imageBlock, value = newWidth, maintainCrop = true) // Example 4: Lock scaling engine.block.setScopeEnabled(imageBlock, key = "layer/resize", enabled = false) engine.stop() } ``` ## Troubleshooting |Symptom|Likely Cause|Fix| |---|---|---| |"Property not found: transform/scale/x"|Using old spec property names that no longer exist.|Replace with `engine.block.scale()` for uniform scale. See [Crop](https://img.ly/docs/cesdk/android/edit-image/transform/crop-f67a47/) for more on how crop scale affects scaling results.| |Image changes size but looks oddly distorted|Combining crop and width changes in a surprising way.|Use a simpler pattern: either change width alone, or use a controlled crop/scaleX + width approach and test with sample images.| |Pinch does nothing on canvas|Pinch scaling disabled|Ensure "touch/pinchAction" is true (or not overridden in settings).| |Scale handles don't appear|Gizmo handles disabled in editor settings|Set `controlGizmo/showScaleHandles` to true.| |Image won't scale at all|Block is transform-locked or scope-locked|Check `transformLocked` and any related scopes like "layer/resize". Unlock or re-enable scope if needed.| ## Next Steps Once you're comfortable scaling images, explore the other transform tools: - [Resize](https://img.ly/docs/cesdk/android/edit-image/transform/resize-407242/) for changing the size of a block's frame. - [Crop](https://img.ly/docs/cesdk/android/edit-image/transform/crop-f67a47/) for changing what part of the image is visible. - [Rotate](https://img.ly/docs/cesdk/android/edit-image/transform/rotate-5f39c9/) for rotating images around an anchor. - [Flip](https://img.ly/docs/cesdk/android/edit-image/transform/flip-035e9f/) to mirror images horizontally or vertically. - [Move](https://img.ly/docs/cesdk/android/edit-image/transform/move-818dd9/) to reposition blocks on the canvas. Together, these guides give you a complete picture of how to position and transform images in CE.SDK on Android. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Add Captions" description: "Documentation for adding captions to videos" platform: android url: "https://img.ly/docs/cesdk/android/edit-video/add-captions-f67565/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Videos](https://img.ly/docs/cesdk/android/create-video-c41a08/) > [Add Captions](https://img.ly/docs/cesdk/android/edit-video/add-captions-f67565/) --- ```kotlin file=@cesdk_android_examples/engine-guides-captions/Captions.kt reference-only import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.Color import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.MimeType import ly.img.engine.PositionMode import ly.img.engine.SizeMode fun editVideoCaptions( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1280, height = 720) val scene = engine.scene.createForVideo() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) engine.block.setWidth(page, value = 1280F) engine.block.setHeight(page, value = 720F) engine.editor.setSettingBoolean(keypath = "features/videoCaptionsEnabled", value = true) engine.block.setDuration(page, duration = 20.0) val caption1 = engine.block.create(DesignBlockType.Caption) engine.block.setString(caption1, property = "caption/text", value = "Caption text 1") val caption2 = engine.block.create(DesignBlockType.Caption) engine.block.setString(caption2, property = "caption/text", value = "Caption text 2") val captionTrack = engine.block.create("captionTrack") engine.block.appendChild(parent = page, child = captionTrack) engine.block.appendChild(parent = captionTrack, child = caption1) engine.block.appendChild(parent = captionTrack, child = caption2) engine.block.setDuration(caption1, duration = 3.0) engine.block.setDuration(caption2, duration = 5.0) engine.block.setTimeOffset(caption1, offset = 0.0) engine.block.setTimeOffset(caption2, offset = 3.0) // Captions can also be loaded from a caption file, i.e., from SRT and VTT files. // The text and timing of the captions are read from the file. val captions = engine.block.createCaptionsFromURI("https://img.ly/static/examples/captions.srt") for (caption in captions) { engine.block.appendChild(parent = captionTrack, child = caption) } // The position and size are synced with all caption blocks in the scene so only needs to be set once. engine.block.setPositionX(caption1, 0.05F) engine.block.setPositionXMode(caption1, PositionMode.PERCENT) engine.block.setPositionY(caption1, 0.8F) engine.block.setPositionYMode(caption1, PositionMode.PERCENT) engine.block.setHeight(caption1, 0.15F) engine.block.setHeightMode(caption1, SizeMode.PERCENT) engine.block.setWidth(caption1, 0.9F) engine.block.setWidthMode(caption1, SizeMode.PERCENT) // The style is synced with all caption blocks in the scene so only needs to be set once. engine.block.setColor(caption1, property = "fill/solid/color", value = Color.fromRGBA(0.9F, 0.9F, 0F, 1F)) engine.block.setBoolean(caption1, property = "dropShadow/enabled", value = true) engine.block.setColor(caption1, property = "dropShadow/color", value = Color.fromRGBA(0F, 0F, 0F, 0.8F)) // Export page as mp4 video. val blob = engine.block.exportVideo( block = page, timeOffset = 0.0, duration = engine.block.getDuration(page), mimeType = MimeType.MP4, progressCallback = { println( "Rendered ${it.renderedFrames} frames and encoded ${it.encodedFrames} frames out of ${it.totalFrames} frames", ) }, ) engine.stop() } ``` For video scenes, open captions can be added in CE.SDK. These allow to follow the content without the audio. Two blocks are available for this. The `DesignBlockType.Caption` blocks hold the text of individual captions and the `DesignBlockType.CaptionTrack` is an optional structuring block to hold the `Caption` blocks, e.g., all captions for one video. The `"playback/timeOffset"` property of each caption block controls when the caption should be shown and the `"playback/duration"` property how long the caption should be shown. Usually, the captions do not overlap. As the playback time of the page progresses, the corresponding caption is shown. With the `"caption/text"` property, the text of the caption can be set. In addition, all text properties are also available for captions, e.g., to change the font, the font size, or the alignment. Position, size, and style changes on caption blocks are automatically synced across all caption blocks. Finally, the whole page can be exported as a video file using the `block.exportVideo` function. ## Creating a Video Scene First, we create a scene that is set up for captions editing by calling the `scene.createForCaptions()` API. Then we create a page, add it to the scene and define its dimensions. This page will hold our composition. ```kotlin highlight-setupScene val scene = engine.scene.createForVideo() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) engine.block.setWidth(page, value = 1280F) engine.block.setHeight(page, value = 720F) engine.editor.setSettingBoolean(keypath = "features/videoCaptionsEnabled", value = true) ``` ## Setting Page Durations Next, we define the duration of the page using the `fun setDuration(block: DesignBlock, duration: Double)` API to be 20 seconds long. This will be the total duration of our exported captions in the end. ```kotlin highlight-setPageDuration engine.block.setDuration(page, duration = 20.0) ``` ## Adding Captions In this example, we want to show two captions, one after the other. For this, we create two caption blocks. ```kotlin highlight-createCaptions val caption1 = engine.block.create(DesignBlockType.Caption) engine.block.setString(caption1, property = "caption/text", value = "Caption text 1") val caption2 = engine.block.create(DesignBlockType.Caption) engine.block.setString(caption2, property = "caption/text", value = "Caption text 2") ``` As an alternative to manually creating the captions, changing the text, and adjusting the timings, the captions can also be loaded from a caption file, i.e., an SRT or VTT file with the `createCaptionsFromURI` API. This return a list of caption blocks, with the parsed texts and timings. These can be added to a caption track as well. ```kotlin highlight-createCaptionsFromURI // Captions can also be loaded from a caption file, i.e., from SRT and VTT files. // The text and timing of the captions are read from the file. val captions = engine.block.createCaptionsFromURI("https://img.ly/static/examples/captions.srt") for (caption in captions) { engine.block.appendChild(parent = captionTrack, child = caption) } ``` ## Creating a Captions Track While we could add the two blocks directly to the page, we can alternatively also use the `captionTrack` block to group them. Caption tracks themselves cannot be selected directly by clicking on the canvas, nor do they have any visual representation. We create a `captionTrack` block, add it to the page and add both captions in the order in which they should play as the track's children. The dimensions of a `captionTrack` are always derived from the dimensions of its children, so you should not call the `setWidth` or `setHeight` APIs on a track, but on its children instead. ```kotlin highlight-addToTrack val captionTrack = engine.block.create("captionTrack") engine.block.appendChild(parent = page, child = captionTrack) engine.block.appendChild(parent = captionTrack, child = caption1) engine.block.appendChild(parent = captionTrack, child = caption2) ``` ## Modifying Captions By default, each caption block has a duration of 3 seconds after it is created. If we want to show it on the page for a different amount of time, we can use the `setDuration` API. ```kotlin highlight-setDuration engine.block.setDuration(caption1, duration = 3.0) engine.block.setDuration(caption2, duration = 5.0) ``` ```kotlin highlight-setTimeOffset engine.block.setTimeOffset(caption1, offset = 0.0) engine.block.setTimeOffset(caption2, offset = 3.0) ``` The position and size of the captions is automatically synced across all captions that are attached to the scene. Therefore, changes only need to be made on one of the caption blocks. ```kotlin highlight-positionAndSize // The position and size are synced with all caption blocks in the scene so only needs to be set once. engine.block.setPositionX(caption1, 0.05F) engine.block.setPositionXMode(caption1, PositionMode.PERCENT) engine.block.setPositionY(caption1, 0.8F) engine.block.setPositionYMode(caption1, PositionMode.PERCENT) engine.block.setHeight(caption1, 0.15F) engine.block.setHeightMode(caption1, SizeMode.PERCENT) engine.block.setWidth(caption1, 0.9F) engine.block.setWidthMode(caption1, SizeMode.PERCENT) ``` The styling of the captions is also automatically synced across all captions that are attached to the scene. For example, changing the text color to red on the first block, changes it on all caption blocks. ```kotlin highlight-changeStyle // The style is synced with all caption blocks in the scene so only needs to be set once. engine.block.setColor(caption1, property = "fill/solid/color", value = Color.fromRGBA(0.9F, 0.9F, 0F, 1F)) engine.block.setBoolean(caption1, property = "dropShadow/enabled", value = true) engine.block.setColor(caption1, property = "dropShadow/color", value = Color.fromRGBA(0F, 0F, 0F, 0.8F)) ``` ## Exporting Video You can start exporting the entire page as a captions file by calling `block.exportVideo`. The encoding process will run in the background. You can get notified about the progress of the encoding process by using `progressCallback` parameter. Since the encoding process runs in the background, the engine will stay interactive. So, you can continue to use the engine to manipulate the scene. Please note that these changes won't be visible in the exported captions file because the scene's state has been frozen at the start of the export. ```kotlin highlight-exportVideo // Export page as mp4 video. val blob = engine.block.exportVideo( block = page, timeOffset = 0.0, duration = engine.block.getDuration(page), mimeType = MimeType.MP4, progressCallback = { println( "Rendered ${it.renderedFrames} frames and encoded ${it.encodedFrames} frames out of ${it.totalFrames} frames", ) }, ) ``` ## Full Code Here's the full code: ```kotlin file=@cesdk_android_examples/engine-guides-captions/Captions.kt import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.Color import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.MimeType import ly.img.engine.PositionMode import ly.img.engine.SizeMode fun editVideoCaptions( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1280, height = 720) val scene = engine.scene.createForVideo() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) engine.block.setWidth(page, value = 1280F) engine.block.setHeight(page, value = 720F) engine.editor.setSettingBoolean(keypath = "features/videoCaptionsEnabled", value = true) engine.block.setDuration(page, duration = 20.0) val caption1 = engine.block.create(DesignBlockType.Caption) engine.block.setString(caption1, property = "caption/text", value = "Caption text 1") val caption2 = engine.block.create(DesignBlockType.Caption) engine.block.setString(caption2, property = "caption/text", value = "Caption text 2") val captionTrack = engine.block.create("captionTrack") engine.block.appendChild(parent = page, child = captionTrack) engine.block.appendChild(parent = captionTrack, child = caption1) engine.block.appendChild(parent = captionTrack, child = caption2) engine.block.setDuration(caption1, duration = 3.0) engine.block.setDuration(caption2, duration = 5.0) engine.block.setTimeOffset(caption1, offset = 0.0) engine.block.setTimeOffset(caption2, offset = 3.0) // Captions can also be loaded from a caption file, i.e., from SRT and VTT files. // The text and timing of the captions are read from the file. val captions = engine.block.createCaptionsFromURI("https://img.ly/static/examples/captions.srt") for (caption in captions) { engine.block.appendChild(parent = captionTrack, child = caption) } // The position and size are synced with all caption blocks in the scene so only needs to be set once. engine.block.setPositionX(caption1, 0.05F) engine.block.setPositionXMode(caption1, PositionMode.PERCENT) engine.block.setPositionY(caption1, 0.8F) engine.block.setPositionYMode(caption1, PositionMode.PERCENT) engine.block.setHeight(caption1, 0.15F) engine.block.setHeightMode(caption1, SizeMode.PERCENT) engine.block.setWidth(caption1, 0.9F) engine.block.setWidthMode(caption1, SizeMode.PERCENT) // The style is synced with all caption blocks in the scene so only needs to be set once. engine.block.setColor(caption1, property = "fill/solid/color", value = Color.fromRGBA(0.9F, 0.9F, 0F, 1F)) engine.block.setBoolean(caption1, property = "dropShadow/enabled", value = true) engine.block.setColor(caption1, property = "dropShadow/color", value = Color.fromRGBA(0F, 0F, 0F, 0.8F)) // Export page as mp4 video. val blob = engine.block.exportVideo( block = page, timeOffset = 0.0, duration = engine.block.getDuration(page), mimeType = MimeType.MP4, progressCallback = { println( "Rendered ${it.renderedFrames} frames and encoded ${it.encodedFrames} frames out of ${it.totalFrames} frames", ) }, ) engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Annotation in Android (Kotlin)" description: "Add timed text, shapes, and highlights to videos programmatically in Android using Kotlin." platform: android url: "https://img.ly/docs/cesdk/android/edit-video/annotation-e9cbad/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Videos](https://img.ly/docs/cesdk/android/create-video-c41a08/) > [Annotation](https://img.ly/docs/cesdk/android/edit-video/annotation-e9cbad/) --- Annotations are on-screen callouts: - text notes - shapes - highlights - icons that appear at precise moments in your video. With CE.SDK you can **create, update, and remove overlays programmatically** when building your Android interface. This guide shows how to add timed annotations to video scenes using Kotlin. ## What You'll Learn - Add text and shape annotations to a video scene. - Control **when** annotations appear with `timeOffset` and `duration`. - Read and set the **current playback time** to sync your UI. - Detect whether an annotation is **visible at the current time** and jump the playhead. - Build annotation UI with coroutines and Flow. ## When to Use It Use annotations for tutorials, sports analysis, education, product demos, and any workflow where viewers should notice specific moments without scrubbing manually. > **Note:** When creating scenes and pages programmatically, set `width = 1080F` and `height = 1920F` to match standard video dimensions. Otherwise, text or video clips may appear oddly sized relative to the canvas. ## Add a Text Annotation The following code: - Creates a text block. - Positions it. - Makes it visible from 5–10 seconds on the timeline. The code is the same as for any other block except for the addition of `timeOffset` and `duration` properties. ```kotlin import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.SizeMode fun addTextAnnotation(engine: Engine, page: Int): Int { val text = engine.block.create(DesignBlockType.Text) engine.block.replaceText(text, text = "Watch this part!") engine.block.setTextFontSize(text, fontSize = 32F) // Auto-size + place it visibly engine.block.setWidthMode(text, mode = SizeMode.AUTO) engine.block.setHeightMode(text, mode = SizeMode.AUTO) engine.block.setPositionX(text, value = 160F) engine.block.setPositionY(text, value = 560F) // Timeline: show between 5s and 10s engine.block.setTimeOffset(text, offset = 5.0) engine.block.setDuration(text, duration = 5.0) engine.block.appendChild(parent = page, child = text) return text } ``` Any visual block (text, shapes, stickers) can serve as an annotation. Time properties control when it's active on the page timeline. ## Add a Shape Annotation Use a graphic block with a vector shape for pointers or highlights. ```kotlin import ly.img.engine.Color import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun addStarAnnotation(engine: Engine, page: Int): Int { val star = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(star, shape = engine.block.createShape(ShapeType.Star)) val fill = engine.block.createFill(FillType.Color) engine.block.setColor( fill, property = "fill/color/value", color = Color.fromRGBA(r = 1F, g = 0F, b = 0F, a = 1F) ) engine.block.setFill(star, fill = fill) engine.block.setPositionX(star, value = 320F) engine.block.setPositionY(star, value = 420F) engine.block.setTimeOffset(star, offset = 12.0) engine.block.setDuration(star, duration = 4.0) engine.block.appendChild(parent = page, child = star) return star } ``` ## Timeline Sync: React to Playback & Highlight Active Annotations Below is a Kotlin pattern using coroutines and Flow to keep your UI in sync with the timeline. It: 1. Retrieves the current page's playback time on an interval. 2. Marks an annotation as **active** when it's visible at that time. 3. Lets you **seek** the playhead to an annotation's start time. ```kotlin import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.Job import kotlinx.coroutines.delay import kotlinx.coroutines.flow.MutableStateFlow import kotlinx.coroutines.flow.StateFlow import kotlinx.coroutines.flow.asStateFlow import kotlinx.coroutines.launch import ly.img.engine.Engine class TimelineSync( private val engine: Engine, private val page: Int ) { private val _currentTime = MutableStateFlow(0.0) val currentTime: StateFlow = _currentTime.asStateFlow() private val _activeAnnotation = MutableStateFlow(null) val activeAnnotation: StateFlow = _activeAnnotation.asStateFlow() private var pollingJob: Job? = null fun start(annotations: List, scope: CoroutineScope = CoroutineScope(Dispatchers.Main)) { pollingJob?.cancel() pollingJob = scope.launch { while (true) { // 1) Read the page's current playback time val time = engine.block.getPlaybackTime(page) _currentTime.value = time // 2) Determine which annotation is currently visible var foundActive: Int? = null for (id in annotations) { if (engine.block.isVisibleAtCurrentPlaybackTime(id)) { foundActive = id break } } _activeAnnotation.value = foundActive // Poll at ~5 fps (200ms) delay(200) } } } fun stop() { pollingJob?.cancel() pollingJob = null } fun seek(toSeconds: Double) { engine.block.setPlaybackTime(page, time = toSeconds) } } ``` > **Note:** * Use a modest polling rate, start with 5–10 Hz (100-200ms delay). It keeps UI responsive. > * For tighter coupling, combine this with the SDK's event subscriptions elsewhere in your app. **Wire it into your UI (Jetpack Compose example)**: ```kotlin import androidx.compose.foundation.clickable import androidx.compose.foundation.layout.Box import androidx.compose.foundation.layout.Row import androidx.compose.foundation.layout.padding import androidx.compose.foundation.lazy.LazyColumn import androidx.compose.foundation.lazy.items import androidx.compose.foundation.shape.CircleShape import androidx.compose.material3.Surface import androidx.compose.material3.Text import androidx.compose.runtime.Composable import androidx.compose.runtime.DisposableEffect import androidx.compose.runtime.collectAsState import androidx.compose.runtime.getValue import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.graphics.Color import androidx.compose.ui.unit.dp import ly.img.engine.Engine @Composable fun AnnotationListView( sync: TimelineSync, engine: Engine, annotations: List ) { val activeAnnotation by sync.activeAnnotation.collectAsState() DisposableEffect(Unit) { sync.start(annotations) onDispose { sync.stop() } } LazyColumn { items(annotations) { id -> val isActive = (activeAnnotation == id) Row( modifier = Modifier .padding(8.dp) .clickable { // Seek to this annotation's start val start = engine.block.getTimeOffset(id) sync.seek(start) }, verticalAlignment = Alignment.CenterVertically ) { Surface( modifier = Modifier.padding(end = 8.dp), shape = CircleShape, color = if (isActive) Color.Red else Color.Gray ) { Box( modifier = Modifier.padding(4.dp) ) } Text( text = "Annotation $id", color = if (isActive) Color.Black else Color.Gray ) } } } } ``` The list: - Highlights active annotations with a red indicator - Jumps the playhead when you tap an annotation. This example doesn't include: - The main UI - The video clips - Playback controls. ## Controlling Playback (Play/Pause, Loop) You can perform actions such as: - Play/pause the page timeline - Set looping - Play solo playback for a single block when previewing. ```kotlin import ly.img.engine.Engine fun play(engine: Engine, page: Int) { engine.block.setPlaying(page, enabled = true) } fun pause(engine: Engine, page: Int) { engine.block.setPlaying(page, enabled = false) } fun setLooping(engine: Engine, blockId: Int, enabled: Boolean) { engine.block.setLooping(blockId, looping = enabled) } fun isPlaying(engine: Engine, page: Int): Boolean { return engine.block.isPlaying(page) } ``` ## Edit & Remove Annotations Following code shows the functions for: - Updating text - Moving an annotation - Deleting an annotation entirely. ```kotlin import ly.img.engine.Engine fun updateAnnotationText(engine: Engine, annotationId: Int, newText: String) { engine.block.replaceText(annotationId, text = newText) } fun moveAnnotation(engine: Engine, annotationId: Int, x: Float, y: Float) { engine.block.setPositionX(annotationId, value = x) engine.block.setPositionY(annotationId, value = y) } fun removeAnnotation(engine: Engine, annotationId: Int) { engine.block.destroy(annotationId) } ``` ## Complete Example Here's a complete example that creates a video scene with multiple annotations: ```kotlin import android.content.Context import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.Color import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType import ly.img.engine.SizeMode fun createVideoWithAnnotations( context: Context, license: String, userId: String ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.annotations") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) try { // Create video scene val scene = engine.scene.createForVideo() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) engine.block.setWidth(page, value = 1080F) engine.block.setHeight(page, value = 1920F) engine.block.setDuration(page, duration = 30.0) // Add video track val track = engine.block.create(DesignBlockType.Track) engine.block.appendChild(parent = page, child = track) // Add video clip val videoBlock = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(videoBlock, shape = engine.block.createShape(ShapeType.Rect)) val videoFill = engine.block.createFill(FillType.Video) engine.block.setString( block = videoFill, property = "fill/video/fileURI", value = "https://cdn.img.ly/assets/demo/v1/ly.img.video/videos/pexels-drone-footage-of-a-surfer-barrelling-a-wave-12715991.mp4" ) engine.block.setFill(videoBlock, fill = videoFill) engine.block.appendChild(parent = track, child = videoBlock) engine.block.fillParent(track) // Add annotation 1: Intro text (0-5 seconds) val introText = engine.block.create(DesignBlockType.Text) engine.block.replaceText(introText, text = "Welcome!") engine.block.setTextFontSize(introText, fontSize = 48F) engine.block.setWidthMode(introText, mode = SizeMode.AUTO) engine.block.setHeightMode(introText, mode = SizeMode.AUTO) engine.block.setPositionX(introText, value = 100F) engine.block.setPositionY(introText, value = 100F) engine.block.setTimeOffset(introText, offset = 0.0) engine.block.setDuration(introText, duration = 5.0) engine.block.appendChild(parent = page, child = introText) // Add annotation 2: Highlight shape (5-10 seconds) val star = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(star, shape = engine.block.createShape(ShapeType.Star)) val starFill = engine.block.createFill(FillType.Color) engine.block.setColor( starFill, property = "fill/color/value", color = Color.fromRGBA(r = 1F, g = 0.84F, b = 0F, a = 1F) // Gold ) engine.block.setFill(star, fill = starFill) engine.block.setPositionX(star, value = 400F) engine.block.setPositionY(star, value = 300F) engine.block.setWidth(star, value = 100F) engine.block.setHeight(star, value = 100F) engine.block.setTimeOffset(star, offset = 5.0) engine.block.setDuration(star, duration = 5.0) engine.block.appendChild(parent = page, child = star) // Add annotation 3: Detail text (10-15 seconds) val detailText = engine.block.create(DesignBlockType.Text) engine.block.replaceText(detailText, text = "Check this out! 👀") engine.block.setTextFontSize(detailText, fontSize = 32F) engine.block.setWidthMode(detailText, mode = SizeMode.AUTO) engine.block.setHeightMode(detailText, mode = SizeMode.AUTO) engine.block.setPositionX(detailText, value = 100F) engine.block.setPositionY(detailText, value = 800F) engine.block.setTimeOffset(detailText, offset = 10.0) engine.block.setDuration(detailText, duration = 5.0) engine.block.appendChild(parent = page, child = detailText) // Start playback engine.block.setPlaying(page, enabled = true) println("Video with annotations created successfully!") println("Total annotations: 3") println("Video duration: ${engine.block.getDuration(page)}s") } finally { // Note: Don't stop the engine here if you want to keep using it // engine.stop() } } ``` ## Design Tips (Quick Wins) - **Readable contrast:** Light text over dark video (or add a translucent background for the text block). - **Consistent rhythm:** Align callout durations to beats/phrases; use 2–5s for most labels. - **Safe zones:** Keep annotations away from edges (device notches, social crop areas). Pair with your existing Rules/Scopes. - **Hierarchy:** Title (bolder), detail (smaller). Reserve color for emphasis. - **Motion restraint:** Prefer fades and basic transforms over heavy effects for legibility. ## Testing & QA Checklist - **Device playback:** Verify on physical devices; long H.265 exports may differ from emulator previews. - **Performance:** Poll timeline at ~5–10 Hz for UI sync; avoid tight loops. - **Edge timing:** Test annotations starting at `0.0` and ending at page duration; confirm no off-by-one visibility. - **Layer order:** Ensure annotations render above background clips; append after media or bring to front when needed. - **Export parity:** Compare in-app preview vs `.mp4` export for small text and any blurs. ## Troubleshooting **❌ Annotation doesn't show up**: - Confirm you appended it to the **page** (or a track on the page). - Ensure its `timeOffset`/`duration` place it within the page's total duration. - If hidden behind media, append it **after** the background or bring to front using layer management. **❌ Jumps don't seem to work**: - Seek on the **page** block with `setPlaybackTime(page, time)`, not on the annotation itself. - Verify the page supports playback time with `engine.block.supportsPlaybackTime(page)`. **❌ Performance stutters**: - Poll the timeline at 5–10 Hz (100-200ms delay). Avoid tight loops. - Use coroutines with proper dispatchers (Dispatchers.Main for UI updates). **❌ Exported video looks different**: - Make sure the scene mode is **Video** and the page duration property has the correct value. - Long blurs/glows may differ depending on codec settings. ## Next Steps Now that you've explored annotation basics, these topics can deepen your understanding: - [Add Captions & Subtitles](https://img.ly/docs/cesdk/android/edit-video/add-captions-f67565/) to your clips. - [Variables for Dynamic Labels](https://img.ly/docs/cesdk/android/create-templates/add-dynamic-content/text-variables-7ecb50/) for displaying information like usernames or scores. - [Control Audio and Video](https://img.ly/docs/cesdk/android/create-video/control-daba54/) for advanced playback control. - [Timeline Editor](https://img.ly/docs/cesdk/android/create-video/timeline-editor-912252/) for creating multi-track video compositions. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Transform" description: "Documentation for Transform" platform: android url: "https://img.ly/docs/cesdk/android/edit-video/transform-369f28/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Videos](https://img.ly/docs/cesdk/android/create-video-c41a08/) > [Transform](https://img.ly/docs/cesdk/android/edit-video/transform-369f28/) --- --- ## Related Pages - [Move](https://img.ly/docs/cesdk/android/edit-video/transform/move-aa9d89/) - Position a video relative to its parent using either percentage or units - [Crop Video in Android](https://img.ly/docs/cesdk/android/edit-video/transform/crop-8b1741/) - Cut out specific areas of a video to focus on key content or change aspect ratio - [Rotate](https://img.ly/docs/cesdk/android/edit-video/transform/rotate-eaf662/) - Documentation for Rotate - [Resize](https://img.ly/docs/cesdk/android/edit-video/transform/resize-b1ce14/) - Change the size of individual elements or groups. - [Scale](https://img.ly/docs/cesdk/android/edit-video/transform/scale-f75c8a/) - Scale videos uniformly in your Android app. - [Flip Videos](https://img.ly/docs/cesdk/android/edit-video/transform/flip-a603b0/) - Flip videos horizontally or vertically. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Crop Video in Android" description: "Cut out specific areas of a video to focus on key content or change aspect ratio" platform: android url: "https://img.ly/docs/cesdk/android/edit-video/transform/crop-8b1741/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Videos](https://img.ly/docs/cesdk/android/create-video-c41a08/) > [Transform](https://img.ly/docs/cesdk/android/edit-video/transform-369f28/) > [Crop](https://img.ly/docs/cesdk/android/edit-video/transform/crop-8b1741/) --- Video cropping is essential for Android video editing apps, enabling users to focus on important content and optimize videos for different platforms. The CreativeEditor SDK provides both intuitive crop interfaces and powerful Kotlin APIs for video manipulation. Whether you're targeting TikTok, Instagram, or YouTube formats, this guide covers all video cropping scenarios for your Android application. ## Interactive video crop tools The SDK includes specialized video crop controls designed for Android touch interfaces. These components handle real-time video preview, aspect ratio selection, and provide smooth crop adjustments that maintain video quality during editing.  ### User interaction workflow 1. **Select the video** you want to crop. 2. **Tap the crop icon** in the editor toolbar. 3. **Adjust the crop area** by dragging the corners or edges or using two-finger gestures. 4. **Use the tools** to modify the crop flip, rotation and angle or to reset the crop. 5. **Close the Sheet** to finalize the crop. The cropped video appears in your project, but the underlying original video and crop values are preserved even when you rotate or resize the cropped video. ### Enable and configure crop tool The default UI allows cropping. When you are creating your own UI or custom toolbars you can configure editing behavior. To ensure the crop tool is available in the UI, make sure it's included in your dock configuration or quick actions. ```kotlin engine.editor.setSettingBoolean("doubleClickToCropEnabled", true) engine.editor.setSettingBoolean("controlGizmo/showCropHandles", true) engine.editor.setSettingBoolean("controlGizmo/showCropScaleHandles", true) ``` The cropping handles are only available when a selected block has a fill of type `FillType.Video`. Otherwise setting the edit mode of the `engine.editor` to crop has no effect. ## Programmatic Cropping Programmatic cropping gives you complete control over video block boundaries, dimensions, and integration with other transformations like rotation or flipping. This is useful for automation, predefined layouts, or server-synced workflows. When you initially create a fill to insert a video into a block, the engine centers the video in the block and crops any dimension that doesn't match. For example: when a block with dimensions of 400.0 × 400.0 is filled with a video that is 600.0 × 500.0, there will be horizontal cropping. When working with cropping using code, it's important to remember that you are modifying the scale, translation, rotation, etc. of the underlying video. The examples below always adjust the x and y values equally. This is not required, but adjusting them unequally can distort the video, which might be just what you want. ### Reset Crop When a video is initially placed into a block it will get crop scale and crop translation values. Resetting the crop will return the video to the original values.  This is a block (called `videoBlock` in the example code) with dimensions of 400 × 400 filled with a video that has dimensions of 720 × 1280. The video has slight scaling and translation applied so that it fills the block evenly. At any time, the code can execute the reset crop command to return it to this stage. ```kotlin engine.block.resetCrop(videoBlock) ``` ### Crop Translation The translation values adjust the placement of the origin point of a video. You can read and change the values. They are not pixel units or centimeters, they are scaled percentages. A video that has its origin point at the origin point of the crop block will have translation value of 0.0 for x and y.  ```kotlin engine.block.setCropTranslationX(videoBlock, 0.25f) ``` This video has had its translation in the x direction set to 0.25. That moved the video one quarter of its width to the right. Setting the value to -0.25 would change the offset of the origin to the left. These are absolute values. Setting the x value to 0.25 and then setting it to -0.25 does not move the video to an offset of 0.0. There is a `setCropTranslationY(block: DesignBlock, translationY: Float)` function to adjust the translation of the video in the vertical direction. Negative values move the video up and positive values move the video down. To read the current crop translation values you can use the convenience getters for the x and y values. ```kotlin val currentX = engine.block.getCropTranslationX(videoBlock) val currentY = engine.block.getCropTranslationY(videoBlock) ``` ### Crop scale The scale values adjust the height and width of the underlying video. Values larger than 1.0 will make the video larger while values less than 1.0 make the video smaller. Unless the video also has offsetting translation applied, the center of the video will move.  This video has been scaled by 1.5 in the x and y directions, but the origin point has not been translated. So, the center of the video has moved. ```kotlin engine.block.setCropScaleX(videoBlock, 1.5f) engine.block.setCropScaleY(videoBlock, 1.5f) ``` To read the current crop scale values, use the convenience getters for the x and y values. ```kotlin val currentX = engine.block.getCropScaleX(videoBlock) val currentY = engine.block.getCropScaleY(videoBlock) ``` ### Crop rotate The same as when rotating blocks, the crop rotation function uses radians. Positive values rotate clockwise and negative values rotate counter clockwise. The video rotates around its center.  ```kotlin import kotlin.math.PI engine.block.setCropRotation(videoBlock, (PI / 4.0).toFloat()) ``` For working with radians, Kotlin has a constant defined for pi. It can be used as `PI` from `kotlin.math.PI`. Because the `setCropRotation` function takes a `Float` for the rotation value, you can use `.toFloat()` to convert the Double to Float. ### Crop to scale ratio To center crop a video, you can use the scale ratio. This will adjust the x and y scales of the video evenly, and adjust the translation to keep it centered.  This video has been scaled by 2.0 in the x and y directions. Its translation has been adjusted automatically by -0.5 in the x and y directions to keep the video centered. ```kotlin engine.block.setCropScaleRatio(videoBlock, 2.0f) ``` Using the crop scale ratio function is the same as calling the translation and scale functions, but in one line. ```kotlin engine.block.setCropScaleX(videoBlock, 2.0f) engine.block.setCropScaleY(videoBlock, 2.0f) engine.block.setCropTranslationX(videoBlock, -0.5f) engine.block.setCropTranslationY(videoBlock, -0.5f) ``` ### Chained crops Crop operations can be chained together. The order of the chaining impacts the final video.  ```kotlin import kotlin.math.PI engine.block.setCropScaleRatio(videoBlock, 2.0f) engine.block.setCropRotation(videoBlock, (PI / 3.0).toFloat()) ```  ```kotlin import kotlin.math.PI engine.block.setCropRotation(videoBlock, (PI / 3.0).toFloat()) engine.block.setCropScaleRatio(videoBlock, 2.0f) ``` ### Flipping the crop There are two functions for crop flipping the video. One for horizontal and one for vertical. They each flip the video along its center.  ```kotlin engine.block.flipCropVertical(videoBlock) engine.block.flipCropHorizontal(videoBlock) ``` The video will be crop flipped every time the function gets called. So calling the function an even number of times will return the video to its original orientation. ### Filling the frame When the various crop operations cause the background of the crop block to be displayed, such as in the **Crop Translation** example above, the function ```kotlin engine.block.adjustCropToFillFrame(videoBlock, minScaleRatio = 1.0f) ``` will adjust the translation values and the scale values of the video so that the entire crop block is filled. This is not the same as resetting the crop. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Flip Videos" description: "Flip videos horizontally or vertically to create mirror effects and symmetrical designs." platform: android url: "https://img.ly/docs/cesdk/android/edit-video/transform/flip-a603b0/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Videos](https://img.ly/docs/cesdk/android/create-video-c41a08/) > [Transform](https://img.ly/docs/cesdk/android/edit-video/transform-369f28/) > [Flip](https://img.ly/docs/cesdk/android/edit-video/transform/flip-a603b0/) --- Video flipping in CreativeEditor SDK (CE.SDK) allows you to mirror video content horizontally or vertically. This transformation is useful for creating symmetrical designs, correcting orientation issues, or achieving specific visual effects in your video projects. You can flip videos both through the built-in user interface and programmatically using the SDK's APIs, providing flexibility for different workflow requirements. [Launch Web Demo](https://img.ly/showcases/cesdk) [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) ## Available Flip Operations CE.SDK supports two types of video flipping: - **Horizontal Flip**: Mirror the video along its vertical axis, creating a left-right reflection - **Vertical Flip**: Mirror the video along its horizontal axis, creating a top-bottom reflection These operations can be applied individually or combined to achieve the desired visual effect. ## Applying Flips ### UI-Based Flipping You can apply flips directly in the CE.SDK user interface. The editor provides intuitive controls for horizontally and vertically flipping videos, making it easy for users to quickly mirror content without writing code. ### Programmatic Flipping Developers can also apply flips programmatically, using the SDK's API. This allows for dynamic video adjustments based on application logic, user input, or automated processes. ## Combining with Other Transforms Video flipping works seamlessly with other transformation operations like rotation, scaling, and cropping. You can chain multiple transformations to create complex visual effects while maintaining video quality. ## Guides --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Move" description: "Position a video relative to its parent using either percentage or units" platform: android url: "https://img.ly/docs/cesdk/android/edit-video/transform/move-aa9d89/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Videos](https://img.ly/docs/cesdk/android/create-video-c41a08/) > [Transform](https://img.ly/docs/cesdk/android/edit-video/transform-369f28/) > [Move](https://img.ly/docs/cesdk/android/edit-video/transform/move-aa9d89/) --- Video positioning is crucial for creating professional video compositions in Android apps. The CreativeEditor SDK enables precise video placement through both touch-based dragging and coordinate-based Kotlin APIs. Perfect for building video collages, picture-in-picture effects, or complex multi-layer video compositions. ## Video positioning features - Touch-based video dragging with smooth gestures - Coordinate-based positioning through Kotlin code - Multi-video positioning with relationship preservation - Position constraints for maintaining video layouts ## Video positioning scenarios Apply video movement for: - Creating picture-in-picture video layouts - Building video collages and multi-layer compositions - Implementing drag-and-drop video editing interfaces *** ## Move videos with the UI Users can drag and drop elements directly in the editor canvas. *** ## Move a video block programmatically Video block position is controlled using the `position/x` and `position/y` properties. They can either use absolute or percentage (relative) values. In addition to setting the properties, there are helper functions. ```kotlin engine.block.setFloat(videoBlock, "position/x", 150f) engine.block.setFloat(videoBlock, "position/y", 100f) ``` or ```kotlin engine.block.setPositionX(videoBlock, 150f) engine.block.setPositionY(videoBlock, 100f) ``` The preceding code moves the video to coordinates (150, 100) on the canvas. The origin point (0, 0) is at the top-left. ```kotlin import ly.img.engine.PositionMode engine.block.setPositionXMode(videoBlock, PositionMode.PERCENT) engine.block.setPositionYMode(videoBlock, PositionMode.PERCENT) engine.block.setPositionX(videoBlock, 0.5f) engine.block.setPositionY(videoBlock, 0.5f) ``` The preceding code moves the video to the center of the canvas, regardless of the dimensions of the canvas. As with setting position, you can update or check the mode using `position/x/mode` and `position/y/mode` properties. ```kotlin val xPosition = engine.block.getPositionX(videoBlock) val yPosition = engine.block.getPositionY(videoBlock) ``` *** ## Move multiple elements together Group elements before moving to keep them aligned: ```kotlin val groupId = engine.block.group(listOf(videoBlock, textBlock)) engine.block.setPositionX(groupId, 200f) ``` The preceding code moves the entire group to 200 from the left edge. *** ## Move relative to current position To nudge a video instead of setting an absolute position: ```kotlin val xPosition = engine.block.getPositionX(videoBlock) engine.block.setPositionX(videoBlock, xPosition + 20f) ``` The preceding code moves the video 20 points to the right. *** ## Lock movement (optional) When building templates, you might want to lock movement to protect the layout: ```kotlin engine.block.setScopeEnabled(videoBlock, "layer/move", false) ``` You can also disable all transformations for a block by locking, this is regardless of working with a template. ```kotlin engine.block.setTransformLocked(videoBlock, true) ``` *** ## Troubleshooting | Issue | Solution | | ------------------------ | ----------------------------------------------------- | | Video block not moving | Ensure it is not constrained or locked | | Unexpected position | Check canvas coordinates and alignment settings | | Grouped items misaligned | Confirm all items share the same reference point | | Can't move via UI | Ensure the move feature is enabled in the UI settings | *** --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Resize Videos" description: "Change the dimensions of video elements to fit specific layout requirements." platform: android url: "https://img.ly/docs/cesdk/android/edit-video/transform/resize-b1ce14/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Videos](https://img.ly/docs/cesdk/android/create-video-c41a08/) > [Transform](https://img.ly/docs/cesdk/android/edit-video/transform-369f28/) > [Resize](https://img.ly/docs/cesdk/android/edit-video/transform/resize-b1ce14/) --- Video resizing in CreativeEditor SDK (CE.SDK) allows you to change the dimensions of video elements to match specific layout requirements. Unlike scaling, resizing allows independent control of width and height dimensions, making it ideal for fitting videos into predefined spaces or responsive layouts. You can resize videos both through the built-in user interface and programmatically using the SDK's APIs, providing flexibility for different workflow requirements. [Launch Web Demo](https://img.ly/showcases/cesdk) [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) ## Resize Methods CE.SDK supports several approaches to video resizing: - **Absolute Dimensions**: Set specific pixel dimensions for precise control - **Percentage-based Resizing**: Size relative to parent container for responsive designs - **UI Resize Handles**: Interactive resize controls in the editor interface - **Aspect Ratio Constraints**: Maintain or ignore aspect ratios during resize operations ## Applying Resizing ### UI-Based Resizing You can resize videos directly in the CE.SDK user interface using resize handles. Users can drag edge and corner handles to adjust dimensions independently or proportionally, making it easy to fit videos into specific layouts visually. ### Programmatic Resizing Developers can apply resizing programmatically, using the SDK's API. This allows for precise dimension control, automated layout adjustments, and integration with responsive design systems or template constraints. ## Combining with Other Transforms Video resizing works seamlessly with other transformation operations like rotation, cropping, and positioning. You can chain multiple transformations to create complex layouts while maintaining video quality and performance. ## Guides --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Rotate" description: "Documentation for Rotate" platform: android url: "https://img.ly/docs/cesdk/android/edit-video/transform/rotate-eaf662/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Videos](https://img.ly/docs/cesdk/android/create-video-c41a08/) > [Transform](https://img.ly/docs/cesdk/android/edit-video/transform-369f28/) > [Rotate](https://img.ly/docs/cesdk/android/edit-video/transform/rotate-eaf662/) --- Video rotation is critical for Android video apps, especially when dealing with content from mobile cameras that may be recorded in different orientations. The CreativeEditor SDK provides smooth video rotation with both touch controls and precise Kotlin APIs, ensuring your users can easily correct orientation and create dynamic video compositions. ## Video rotation features - Smooth video rotation with real-time preview - Orientation correction for mobile-recorded content - Precise angle control through Kotlin programming - Multi-video rotation for synchronized editing ### Rotating a Video Using the UI By default, selecting a block will show handles for resizing and rotating. You can freeform rotate a block by dragging the rotation handle.  ### Rotating a Video Using Code You can rotate a video block using the `setRotation` function. It takes the `id` of the block and a rotation amount in radians. ```kotlin import kotlin.math.PI engine.block.setRotation(videoBlock, (PI / 4).toFloat()) ``` If you need to convert between radians and degrees, multiply the number in degrees by pi and divide by 180. ```kotlin val angleInRadians: Float = (angleInDegrees * PI / 180).toFloat() val angleInDegrees: Float = (angleInRadians * 180 / PI).toFloat() ``` You can discover the current rotation of a block using the `getRotation` function. ```kotlin val rotationOfVideo = engine.block.getRotation(videoBlock) ```  > **Note:** This rotates the entire block. If you want to rotate a video that is filling > a block but not the block, explore the crop rotate function. ### Locking Rotation You can remove the rotation handle from the UI by changing the setting for the engine. This will affect *all* blocks. ```kotlin engine.editor.setSettingBoolean("controlGizmo/showRotateHandles", false) ``` Though the handle is gone, the user can still use the two finger rotation gesture on a touch device. You can disable that gesture with the following setting. ```kotlin engine.editor.setSettingBoolean("touch/rotateAction", false) ``` When you want to lock only certain blocks, you can toggle the transform lock property. This will apply to all transformations for the block. ```kotlin engine.block.setTransformLocked(videoBlock, true) ``` ### Rotating As a Group To rotate multiple elements together, first add them to a `group` and then rotate the group. ```kotlin import kotlin.math.PI val groupId = engine.block.group(listOf(videoBlock, textBlock)) engine.block.setRotation(groupId, (PI / 2).toFloat()) ``` ### Troubleshooting Troubleshooting | Issue | Solution | | ----------------------------------- | ------------------------------------------------------------------------------- | | Video appears offset after rotation | Make sure the pivot point is centered (default is center). | | Rotation not applying | Confirm that the video block is inserted and rendered before applying rotation. | | Rotation handle not visible | Check that interactive UI controls are enabled in the settings. | --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Scale" description: "Scale videos uniformly in your Android app." platform: android url: "https://img.ly/docs/cesdk/android/edit-video/transform/scale-f75c8a/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Videos](https://img.ly/docs/cesdk/android/create-video-c41a08/) > [Transform](https://img.ly/docs/cesdk/android/edit-video/transform-369f28/) > [Scale](https://img.ly/docs/cesdk/android/edit-video/transform/scale-f75c8a/) --- This guide shows how to scale videos using CE.SDK in your Android app. You'll learn how to scale video blocks proportionally, scale groups, and apply scaling constraints to protect template structure. ## What you'll learn - Scale videos programmatically using Kotlin - Scale proportionally or non-uniformly - Scale grouped elements - Apply scale constraints in templates ## When to use Use scaling to: - Emphasize or de-emphasize elements - Fit videos to available space without cropping - Enable pinch-to-zoom gestures or dynamic layouts *** ## Scale a video uniformly Scaling uses the `scale(block: DesignBlock, scaleX: Float, scaleY: Float, anchorX: Float = 0f, anchorY: Float = 0f)` function. A scale value of `1.0f` is the original scale. Values larger than `1.0f` increase the scale of the block and values lower than `1.0f` scale the block smaller. A value of `2.0f`, for example makes the block twice as large. The following code scales the video to 150% of its original size. The origin anchor point remains unchanged, so the video expands down and to the right: ```kotlin engine.block.scale(videoBlock, 1.5f, 1.5f) ```  By default, the anchor point for the video when scaling is the origin point on the top left. The scale function has optional parameters to move the anchor point in the x and y direction. They can have values between `0.0f` and `1.0f` The following code scales the video to 150% of its original size. The origin anchor point is 0.5, 0.5, so the video expands from the center: ```kotlin engine.block.scale(videoBlock, 1.5f, 1.5f, 0.5f, 0.5f) ```  *** ## Scale non-uniformly To stretch or compress only one axis, thus distorting a video, use the crop scale function in combination with the width or height function. How you decide to make the adjustment will have different results. Below are three examples of scaling the original video in the x direction only.  ```kotlin import ly.img.engine.SizeMode engine.block.setWidthMode(videoBlock, SizeMode.AUTO) val newWidth = engine.block.getWidth(videoBlock) * 1.5f engine.block.setWidth(videoBlock, newWidth) ``` The preceding code adjusts the width of the block and allows the engine to adjust the scale of the video to maintain it as a fill.  ```kotlin engine.block.setCropScaleX(videoBlock, 1.5f) engine.block.setWidthMode(videoBlock, SizeMode.AUTO) val newWidth = engine.block.getWidth(videoBlock) * 1.5f engine.block.setWidth(videoBlock, newWidth) ``` The preceding code uses crop scale to scale the video in a single direction and then adjusts the block's width to match the change. The change in width does not take the crop into account and so distorts the video as it's scaling the scaled video.  ```kotlin engine.block.setCropScaleX(videoBlock, 1.5f) engine.block.setWidthMode(videoBlock, SizeMode.AUTO) val newWidth = engine.block.getWidth(videoBlock) * 1.5f engine.block.setWidth(videoBlock, newWidth, true) // maintainCrop = true ``` By setting the `maintainCrop` parameter to true, expanding the width of the video by the scale factor respects the crop scale and the video is less distorted. *** ## Scale multiple elements together Group blocks to scale them proportionally: ```kotlin val groupId = engine.block.group(listOf(videoBlock, textBlock)) engine.block.scale(groupId, 0.75f, 0.75f) ``` The preceding code scales the entire group to 75%. *** ## Lock scaling When working with templates, you can lock a block from scaling by setting its scope. Remember that the global layer has to defer to the blocks using `setGlobalScope`. ```kotlin engine.block.setScopeEnabled(videoBlock, "layer/resize", false) ``` To prevent users from transforming an element at all: ```kotlin engine.block.setTransformLocked(videoBlock, true) ``` *** --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Engine Interface" description: "Understand CE.SDK's architecture and learn when to use direct Engine access for automation workflows" platform: android url: "https://img.ly/docs/cesdk/android/engine-interface-6fb7cf/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Engine](https://img.ly/docs/cesdk/android/engine-interface-6fb7cf/) --- The Creative Engine is the powerhouse behind CE.SDK's cross-platform capabilities. While the UI components provide ready-to-use editing experiences, the Engine interface gives you direct programmatic control over all creative operations—from simple batch processing to complex automated workflows. ## Client-Side vs Server-Side Processing Understanding when to use client-side versus server-side processing is crucial for building efficient creative automation workflows. Each approach offers distinct advantages depending on your use case requirements. ### Client-Side Processing (Mobile Device) Client-side processing runs the Engine directly in the user's device — but importantly, this doesn't mean visible to the user. The Engine operates headlessly in the background, making it perfect for automation tasks that enhance user experience without interrupting their workflow. **Common Implementation Patterns:** **Hidden Engine Instances**: Run a second, invisible Engine instance alongside your main UI for background processing. While users edit in the primary interface, the hidden instance can validate designs, generate previews, or prepare export-ready assets. **Underlying Engine Access**: Access the Engine API directly from prebuilt UI components for custom automation within existing workflows. **Dedicated Engine Packages**: Use platform-specific Engine packages for specialized client-side automation without any UI overhead. **Ideal Client-Side Use Cases:** - **Design Validation**: Check for empty placeholders, low-resolution images, or brand guideline violations in real-time - **Thumbnail Generation**: Create preview images for design galleries or version history - **Effect Previews**: Generate quick previews of filters or effects before applying them to the main design - **Auto-Save Optimization**: Compress and optimize scenes for storage while maintaining editability - **Real-Time Feedback**: Provide instant visual feedback for design rules or constraints ### Server-Side Processing Server-side processing moves the Engine to your backend infrastructure, unlocking powerful capabilities for resource-intensive operations and scalable workflows. **Key Advantages:** - **Enhanced Resources**: Access to more CPU, memory, and storage than client devices - **Secure Asset Access**: Process private assets without exposing them to client-side code - **Background Operations**: Handle long-running tasks without affecting user experience - **Scheduled Automation**: Trigger design generation based on events, schedules, or external APIs **Ideal Server-Side Use Cases:** - **High-Resolution Exports**: Generate print-quality assets that would be too resource-intensive for client devices - **Bulk Generation**: Create thousands of design variations for marketing campaigns or product catalogs - **Data Pipeline Integration**: Connect to databases, APIs, or file systems for automated content generation - **Multi-Format Output**: Export designs in multiple formats and resolutions simultaneously - **Workflow Orchestration**: Coordinate complex multi-step automation processes **Hybrid Workflows**: Often, the most effective approach combines both client and server-side processing. Users can design and preview on the client with instant feedback, while heavy processing happens on the server in the background. ## Engine-Powered Use Cases The Engine interface unlocks [powerful automation scenarios](https://img.ly/docs/cesdk/android/automation/overview-34d971/) that can scale creative workflows: ### Batch Processing Process multiple designs simultaneously with consistent results. Whether you're applying filters to hundreds of images or generating variations of a marketing template, the Engine handles bulk operations efficiently both client-side and server-side. ### Auto-Resize Automatically adapt designs to different aspect ratios and platforms. The Engine intelligently repositions elements, adjusts text sizes, and maintains visual hierarchy across formats—from Instagram stories to LinkedIn posts. ### Data Merge Connect external data sources (CSV, JSON, APIs) to templates for personalized content generation. Perfect for creating thousands of product cards, personalized certificates, or location-specific campaigns. ### Product Variations Generate multiple versions of product designs with different colors, sizes, or configurations. Ideal for e-commerce platforms needing to showcase product options without manual design work. ### Design Generation Create entirely new designs programmatically based on rules, templates, or AI inputs. The Engine can compose layouts, select appropriate fonts, and arrange elements according to your design guidelines. ### Multiple Image Generation Efficiently process and export designs in various formats and resolutions. Generate web-optimized previews alongside print-ready high-resolution files in a single workflow. ### Actions Implement complex multi-step operations as reusable actions. Chain together filters, transformations, and exports to create sophisticated automated workflows that can be triggered programmatically. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Create Thumbnail in Android (Kotlin)" description: "Generate small preview images for scenes and pages using CE.SDK export options in Kotlin." platform: android url: "https://img.ly/docs/cesdk/android/export-save-publish/create-thumbnail-749be1/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Export Media Assets](https://img.ly/docs/cesdk/android/export-save-publish/export-82f968/) > [Create Thumbnail](https://img.ly/docs/cesdk/android/export-save-publish/create-thumbnail-749be1/) --- Thumbnails are scaled down previews of your designs. They let you show galleries or document picker previews without loading the full editor. CE.SDK generates thumbnails using the same API you use for final output, just with smaller target dimensions and often lower quality settings. This guide focuses on **image thumbnails**: small PNG, JPEG or WebP previews for use in grids, lists and document icons. It **doesn't cover audio waveforms** or arrays of **preview frames** for scrubbers. ## What You'll Learn - How to export a scene or page as a small preview image. - How to control thumbnail dimensions while preserving aspect ratio. - When to choose PNG, JPEG, or WebP for thumbnails. - How to tune quality and file size using `ExportOptions`. - How to batch-generate different thumbnail sizes safely. ## When You'll Use It - Showing a "My Designs" or "Recent Files" gallery. - Rendering previews for templates or drafts. - Generating document icons or share sheet previews. - Creating thumbnail sizes for different UI contexts. ## How Thumbnail Export Works In CE.SDK, `export` means *rendering bitmap image data from the engine*. When you call `export`, the SDK: 1. Renders the current visual state of a block (for example, a page). 2. Composites all **visible** child blocks (images, text, shapes, effects). 3. Produces raw bitmap image data in the requested format (PNG, JPEG, or WebP). Exporting **doesn't** imply writing a file to disk. The result of the export call is an in-memory `ByteBuffer` that you can: - Convert to a `Bitmap`. - Cache in memory. - Write to disk if needed. - Upload elsewhere. CE.SDK doesn't provide a separate "thumbnail API". If you build your own UI, you call `engine.block.export(...)` directly whenever you want. If you use the **prebuilt editor UI** (the default CE.SDK editors), there *is* a convenient hook for the built-in Export/Share button: the editor exposes an `DesignEditor` configuration. The default export: 1. Renders (PDF for design scenes, MP4 for video scenes). 2. Writes the result to a temporary file 3. Opens the system share sheet. That hook is great for customizing what happens when the user taps Export in the prebuilt UI, but under the hood it still uses the same engine export APIs that you use for thumbnails. ## Export a Scene Thumbnail You generate thumbnails by exporting a design block. In most cases this should be either: - The **page block**, which represents the full visible canvas. - The scene, if your design is single-page. Exporting the page block is the safest choice when you want a thumbnail that matches what the user sees on screen. ```kotlin import android.content.Context import android.net.Uri import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import ly.img.engine.Engine import ly.img.engine.ExportOptions import ly.img.engine.MimeType import java.io.File suspend fun exportSceneThumbnail( engine: Engine, context: Context, scene: Int ): File { // Define thumbnail size val options = ExportOptions( targetWidth = 400, targetHeight = 300, jpegQuality = 0.8f ) // Export the scene as JPEG val blob = engine.block.export( block = scene, mimeType = MimeType.JPEG, options = options ) // Save to temporary file val thumbnailFile = File(context.cacheDir, "thumbnail_${System.currentTimeMillis()}.jpg") withContext(Dispatchers.IO) { thumbnailFile.outputStream().channel.use { channel -> channel.write(blob) } } return thumbnailFile } ``` The preceding code exports a scene at 400×300 resolution with JPEG quality set to 0.8 for efficient file size. ## Control Thumbnail Size and Aspect Ratio ### How `targetWidth` and `targetHeight` behave When both `targetWidth` and `targetHeight` have values, CE.SDK renders the block large enough to **fill the target box while maintaining its aspect ratio**. Important implications: - You don't need to calculate aspect-fit or aspect-fill yourself. - The exported image may exceed one of the target dimensions internally to preserve aspect ratio. - Consider `targetWidth` and `targetHeight` as a *desired bounding box*, not a hard crop. ### Typical Thumbnail Sizes Common choices include: - 150 × 150 for dense grids - 161 × 161 for Instagram Video Feeds - 55 × 55 or 222 × 150 for Pinterest - 400 × 300 for list previews - 800 × 600 for high-quality previews ## Choose the Right Thumbnail Format CE.SDK supports PNG, JPEG, and WebP for image export. It provides a `MimeType` enum including `JPEG`, `PNG` and `WEBP`. ### PNG - Preserves transparency - Lossless quality - Compression affects speed, not quality - Best for stickers, cutouts, or UI elements ### JPEG - Smaller and faster for photographic content - No transparency - Control quality via `jpegQuality` ### WebP - Efficient compression - Supports lossless and lossy modes - Requires WebP support everywhere you display thumbnails Switching formats only requires changing the `mimeType` and relevant quality option. ```kotlin import android.content.Context import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import ly.img.engine.Engine import ly.img.engine.ExportOptions import ly.img.engine.MimeType import java.io.File suspend fun exportJPEGThumbnail( engine: Engine, context: Context, page: Int ): File { val options = ExportOptions( jpegQuality = 0.8f, targetWidth = 400, targetHeight = 300 ) val blob = engine.block.export( block = page, mimeType = MimeType.JPEG, options = options ) val file = File(context.cacheDir, "thumbnail.jpg") withContext(Dispatchers.IO) { file.outputStream().channel.use { channel -> channel.write(blob) } } return file } ``` When you need **different thumbnails of different sizes or image formats**, call `export` for each permutation. Pass in the correct mime type and an `ExportOptions` configuration. ```kotlin import android.content.Context import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import ly.img.engine.Engine import ly.img.engine.ExportOptions import ly.img.engine.MimeType import java.io.File suspend fun exportMultipleThumbnails( engine: Engine, context: Context, page: Int ): Map { val results = mutableMapOf() // Small thumbnail (22x22) val smallOptions = ExportOptions( jpegQuality = 0.8f, targetWidth = 22, targetHeight = 22 ) val smallBlob = engine.block.export(page, MimeType.JPEG, smallOptions) val smallFile = File(context.cacheDir, "thumbnail_small.jpg") withContext(Dispatchers.IO) { smallFile.outputStream().channel.use { it.write(smallBlob) } } results["small"] = smallFile // Medium thumbnail (150x150) val mediumOptions = ExportOptions( jpegQuality = 0.8f, targetWidth = 150, targetHeight = 150 ) val mediumBlob = engine.block.export(page, MimeType.JPEG, mediumOptions) val mediumFile = File(context.cacheDir, "thumbnail_medium.jpg") withContext(Dispatchers.IO) { mediumFile.outputStream().channel.use { it.write(mediumBlob) } } results["medium"] = mediumFile return results } ``` > **Note:** ## Caching ThumbnailsThumbnail export is expensive compared to image display.Even a basic in-memory cache (for example, `LruCache`) can dramatically improve scrolling performance in galleries and `RecyclerView` lists. ## Tune Quality and File Size with `ExportOptions` `ExportOptions` lets you balance visual quality, file size, and export speed. Key fields for thumbnails: - `pngCompressionLevel` (0–9, default 5) - `jpegQuality` (0.0–1.0, default 0.9) - `webpQuality` (0.0–1.0, default 1.0) - `targetWidth` / `targetHeight` CE.SDK applies only the options relevant to the chosen MIME type. Others are ignored. ```kotlin import ly.img.engine.ExportOptions import ly.img.engine.MimeType // PNG with maximum compression (slower, smaller file) val pngOptions = ExportOptions( pngCompressionLevel = 9, targetWidth = 400, targetHeight = 300 ) val pngBlob = engine.block.export(page, MimeType.PNG, pngOptions) // JPEG with lower quality (faster, much smaller file) val jpegOptions = ExportOptions( jpegQuality = 0.6f, targetWidth = 400, targetHeight = 300 ) val jpegBlob = engine.block.export(page, MimeType.JPEG, jpegOptions) // WebP with lossless mode val webpOptions = ExportOptions( webpQuality = 1.0f, targetWidth = 400, targetHeight = 300 ) val webpBlob = engine.block.export(page, MimeType.WEBP, webpOptions) ``` ## Headless and Background Thumbnail Generation CE.SDK offers two common ways to export without blocking your UI: ### Use Your Existing Engine For occasional thumbnail creation (for example, when a user saves a draft), it's often fine to export from the same `Engine` instance that powers the editor. ### Use a Separate Headless Engine Instance For batch thumbnail generation (for example, populating a large gallery), you can create a separate `Engine` instance, load the same scene data into it, and export thumbnails there. ```kotlin import android.content.Context import android.net.Uri import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import ly.img.engine.Engine import ly.img.engine.ExportOptions import ly.img.engine.MimeType import java.io.File suspend fun generateThumbnailsHeadless( context: Context, license: String, userId: String, sceneUris: List ): List { val thumbnails = mutableListOf() // Create a headless engine instance val engine = Engine.getInstance(id = "ly.img.engine.thumbnail") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) try { for (sceneUri in sceneUris) { // Load scene val scene = engine.scene.load(sceneUri = sceneUri) // Export thumbnail val options = ExportOptions( jpegQuality = 0.8f, targetWidth = 400, targetHeight = 300 ) val blob = engine.block.export(scene, MimeType.JPEG, options) // Save to file val file = File(context.cacheDir, "thumb_${System.currentTimeMillis()}.jpg") withContext(Dispatchers.IO) { file.outputStream().channel.use { it.write(blob) } } thumbnails.add(file) } } finally { engine.stop() } return thumbnails } ``` > **Note:** When you're using the **prebuilt editor UI** in Android, you can also customize what happens when the user taps the Export button via the editor's export configuration. The default callback writes the exported data to a temporary file and triggers the share sheet. You could generate thumbnails here and control the export instead. ## Thumbnails from Video Blocks (Single Frame) Although this guide focuses on static image thumbnails, it's worth calling out an important edge case that often surprises developers: If you export a **paused video fill block**, the result is a **single image thumbnail**, just like exporting a graphic or page. This is *not* the same as generating a stream of video thumbnails or scrubbing previews. ### How This Works - Video blocks render their current frame when exported. - You can control *which* frame becomes the thumbnail by setting the playhead time before calling `export`. Conceptually: 1. Seek the video to the desired time. 2. Pause playback. 3. Export the block using the thumbnail export flow shown earlier. This produces a single static image suitable for: - Gallery previews - Document icons - Poster-frame–style thumbnails ## Troubleshooting | Symptom | Likely Cause | Solution | |---|---|---| | Thumbnail only shows part of the design | Exported a child block instead of the page | Export the page block to capture the full visible canvas | | Thumbnail size looks wrong | Missing or zero target dimension | Set both `targetWidth` and `targetHeight` | | Export is slow | Large target size or high PNG compression | Reduce dimensions or compression level | | File size too large | Quality settings too high | Lower JPEG/WebP quality or size | | Thumbnail looks blurry | Target size too small | Increase target dimensions | | Export fails | Scene not loaded | Ensure `engine.scene.get()` returns a valid scene | ## Next Steps - To learn more about exporting images and controlling output quality, see [Export designs to image formats](https://img.ly/docs/cesdk/android/export-save-publish/export/overview-9ed3a8/). - Reduce file size or tune quality for thumbnails and previews, with [Compress exported images](https://img.ly/docs/cesdk/android/export-save-publish/export/compress-29105e/). - If you need to generate thumbnails at scale or as part of automated workflows, take a look at [Batch processing designs](https://img.ly/docs/cesdk/android/automation/batch-processing-ab2d18/). --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Export" description: "Explore export options, supported formats, and configuration features for sharing or rendering output." platform: android url: "https://img.ly/docs/cesdk/android/export-save-publish/export-82f968/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Export Media Assets](https://img.ly/docs/cesdk/android/export-save-publish/export-82f968/) --- --- ## Related Pages - [Options](https://img.ly/docs/cesdk/android/export-save-publish/export/overview-9ed3a8/) - Explore export options, supported formats, and configuration features for sharing or rendering output. - [For Audio Processing](https://img.ly/docs/cesdk/android/guides/export-save-publish/export/audio-68de25/) - Learn how to export audio in WAV or MP4 format from any block type in CE.SDK for Android. - [To PDF](https://img.ly/docs/cesdk/android/export-save-publish/export/to-pdf-95e04b/) - Learn how to export pages to PDF. - [Compress Exports for Smaller Files](https://img.ly/docs/cesdk/android/export-save-publish/export/compress-29105e/) - Learn how to reduce file sizes during export from CE.SDK for Android by tuning format-specific compression settings in Kotlin. - [Create Thumbnail in Android (Kotlin)](https://img.ly/docs/cesdk/android/export-save-publish/create-thumbnail-749be1/) - Generate small preview images for scenes and pages using CE.SDK export options in Kotlin. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Compress Exports for Smaller Files" description: "Learn how to reduce file sizes during export from CE.SDK for Android by tuning format-specific compression settings in Kotlin." platform: android url: "https://img.ly/docs/cesdk/android/export-save-publish/export/compress-29105e/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Export Media Assets](https://img.ly/docs/cesdk/android/export-save-publish/export-82f968/) > [Compress](https://img.ly/docs/cesdk/android/export-save-publish/export/compress-29105e/) --- Compression's goal is to reduce file sizes during export while maintaining as much visual quality as possible. With the CreativeEditor SDK (CE.SDK) for Android, you can fine-tune compression settings for both images and videos in Kotlin. This allows your app to balance performance, quality, and storage efficiency across all Android devices. ## What You'll Learn - How to configure compression for PNG, JPEG, and WebP exports in Kotlin. - How to control video file size using bitrate and resolution scaling. - How to balance file size, quality, and export performance for different use cases. - How to configure compression programmatically during automation or batch operations. ## When to Use It Compression tuning is useful whenever: - Exported media is too large for upload limits - You need to optimize storage quotas - You have constrained network bandwidth Use it when preparing images or videos for any workflow that benefits from: - Faster load times and smaller files, like: - Social media - Web delivery - Consistent file size and predictable performance, like: - Batch export - Automation scenarios ## Understanding Compression Options by Format Each format supports its own parameters for balancing: - Speed - File size - Quality You pass these through the `ExportOptions` structure when calling the export functions. | Format | Parameter | Type | Effect | Default | | ------- | ---------- | ---- | ------- | -------- | | PNG | `pngCompressionLevel` | 0–9 | Higher = smaller, slower (lossless) | 5 | | JPEG | `jpegQuality` | 0.0–1.0 | Lower = smaller, lower quality | 0.9 | | WebP | `webpQuality` | 0.0–1.0 | 1.0 = lossless, \<1.0 = lossy | 1.0 | | MP4 | Video bitrate via options | bits/sec | Higher = larger, higher quality | Auto | ## Export Images with Compression Below is an example that exports a design block as PNG and JPEG while tuning compression options. ```kotlin import android.content.Context import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import kotlinx.coroutines.withContext import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.ExportOptions import ly.img.engine.MimeType import java.io.File fun exportCompressedImages( context: Context, license: String, userId: String ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) // Load a demo scene val sceneUri = Uri.parse("https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene") val scene = engine.scene.load(sceneUri = sceneUri) // Select the first graphic block to export val blocks = engine.block.findByType(DesignBlockType.Graphic) if (blocks.isNotEmpty()) { val block = blocks.first() // Export PNG with maximum compression (lossless) val pngOptions = ExportOptions(pngCompressionLevel = 9) val pngData = engine.block.export(block, mimeType = MimeType.PNG, options = pngOptions) // Save PNG to file val pngFile = File(context.filesDir, "compressed.png") withContext(Dispatchers.IO) { pngFile.outputStream().channel.use { channel -> channel.write(pngData) } } // Export JPEG with balanced quality (lossy) val jpegOptions = ExportOptions(jpegQuality = 0.7f) val jpegData = engine.block.export(block, mimeType = MimeType.JPEG, options = jpegOptions) // Save JPEG to file val jpegFile = File(context.filesDir, "compressed.jpg") withContext(Dispatchers.IO) { jpegFile.outputStream().channel.use { channel -> channel.write(jpegData) } } } engine.stop() } ``` Choose a format depending on what matters the most for your output: - **PNG** is ideal for flat graphics or assets that require **transparency**. - **JPEG** is best for photographs where slight **compression** artifacts are acceptable. - **WebP** can serve **both** roles: it supports transparency like PNG and delivers smaller files like JPEG. ## Combine Compression with Resolution Scaling You can further reduce file size by downscaling exports: ```kotlin import ly.img.engine.ExportOptions import ly.img.engine.MimeType val scaledOptions = ExportOptions( pngCompressionLevel = 7, targetWidth = 1080f, targetHeight = 1080f ) val scaledData = engine.block.export(block, mimeType = MimeType.PNG, options = scaledOptions) ``` When you specify only one dimension, CE.SDK automatically preserves aspect ratio for consistent results. ## Compress Video Exports For video exports, you can control compression through various export parameters. The Android SDK uses callback-based video export with progress tracking. ```kotlin import android.content.Context import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import kotlinx.coroutines.withContext import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.MimeType import java.io.File fun exportCompressedVideo( context: Context, license: String, userId: String ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1280, height = 720) // Load or create a video scene val scene = engine.scene.createForVideo() // ... add video content ... // Export page as compressed MP4 val page = engine.block.findByType(DesignBlockType.Page).firstOrNull() if (page != null) { val videoData = engine.block.exportVideo( block = page, timeOffset = 0.0, duration = engine.block.getDuration(page), mimeType = MimeType.MP4, progressCallback = { progress -> println("Rendered ${progress.renderedFrames}/${progress.totalFrames} frames") println("Encoded ${progress.encodedFrames}/${progress.totalFrames} frames") } ) // Save video to file val videoFile = File(context.filesDir, "compressed_video.mp4") withContext(Dispatchers.IO) { videoFile.outputStream().channel.use { channel -> channel.write(videoData) } } } engine.stop() } ``` About the video compression: - Video bitrate and encoding settings are handled automatically by the engine - The SDK optimizes compression based on the content and target resolution - You can control output quality through resolution scaling using `targetWidth` and `targetHeight` in export options ## Performance and Trade-Offs Higher compression results in smaller files but slower export speeds. For example: - PNG Level 9 may take twice as long to encode as Level 3–5, though it produces smaller files. - JPEG and WebP are faster but can introduce visible compression artifacts. Video exports are more demanding and depend heavily on device CPU and GPU performance. You can check available export limits before encoding: ```kotlin import ly.img.engine.Engine val maxSize = engine.editor.getMaxExportSize() println("Max export size: $maxSize pixels") ``` ## Real-World Compression Comparison (1080 × 1080) The following table compares average results across different compression settings for photo-like and graphic-like images. | Format | Setting | Avg. File Size (KB) | Encode Time (ms) | PSNR (dB)\* | Notes | | ------- | -------- | ------------------- | ---------------- | ------------ | ------ | | **PNG** | Level 0 | ~1 450 | ~44 | ∞ (lossless) | Fastest, largest | | | Level 5 | ~1 260 | ~61 | ∞ | Balanced speed and size | | | Level 9 | ~1 080 | ~88 | ∞ | Smallest, slowest | | **JPEG** | Quality 95 | ~640 | ~24 | 43 | Near-lossless appearance | | | Quality 80 | ~420 | ~20 | 39 | Good default for photos | | | Quality 60 | ~290 | ~17 | 35 | Some artifacts visible | | | Quality 40 | ~190 | ~15 | 31 | Heavy compression | | **WebP** | Quality 95 | ~510 | ~27 | 44 | Smaller than JPEG | | | Quality 80 | ~350 | ~23 | 39 | Excellent web balance | | | Quality 60 | ~240 | ~20 | 35 | Mild artifacts | | | Quality 40 | ~160 | ~18 | 31 | Compact, noticeable loss | | | Lossless | ~830 | ~33 | ∞ | Smaller than PNG, keeps alpha | \*PSNR > 40 dB ≈ visually lossless; 30–35 dB shows mild artifacts. **Key Takeaways**: - **WebP** achieves 70–85 % smaller files than uncompressed PNG with high quality around `webpQuality = 0.8f`. - **JPEG** performs well for photographs; use `jpegQuality = 0.8f–0.9f` for web or print, `0.6f` for compact exports. - **PNG** is essential for transparency and vector-like shapes; higher levels reduce size modestly at the cost of speed. - Test on realistic assets: complex photos and flat graphics compress differently. ## Practical Presets These presets provide starting points for common export scenarios. | Use Case | Format | Typical Settings | Result | Notes | |-----------|---------|------------------|---------|-------| | **Web or Social Sharing** | JPEG / WebP | `jpegQuality: 0.8f` or `webpQuality: 0.8f` | ~60–70 % smaller than PNG | Balanced quality and size | | **UI Graphics / Transparent Assets** | PNG / WebP | `pngCompressionLevel: 6–8` or `webpQuality: 1.0f (lossless)` | ~25 % smaller than default PNG | Maintains transparency | | **High-Quality Print or Archival** | PNG / WebP Lossless | `pngCompressionLevel: 9` or `webpQuality: 1.0f` | Maximum fidelity | Slower export, large files | | **Video for Web / Social** | MP4 | Use default settings with resolution scaling | Smooth playback, small file | Adjust resolution as needed | | **Video for Download / HD** | MP4 | Higher resolution (1920×1080) | Full HD quality | Larger file, slower encode | **PDF and Print**: PDF exports use vector graphics when possible and aren't compressed by default. > **Note:** Consider showing users an **estimated file size** before export. It helps them make informed choices about quality vs. performance. ## Automating Compression in Batch Exports When exporting multiple elements, apply the same compression settings programmatically: ```kotlin import android.content.Context import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.ExportOptions import ly.img.engine.MimeType import java.io.File suspend fun exportAllGraphics(engine: Engine, context: Context) { val blocks = engine.block.findByType(DesignBlockType.Graphic) val options = ExportOptions(jpegQuality = 0.8f) blocks.forEachIndexed { index, block -> val data = engine.block.export(block, mimeType = MimeType.JPEG, options = options) val file = File(context.filesDir, "export_$index.jpg") withContext(Dispatchers.IO) { file.outputStream().channel.use { channel -> channel.write(data) } } } } ``` This ensures consistent quality and file size across all exported assets. ## Troubleshooting **❌ File size not reduced**: - Ensure correct property name such as `jpegQuality`, `webpQuality`. - Check that values are floats (e.g., `0.8f` not `0.8`). **❌ JPEG Quality too low**: - Increase quality to `0.9f` or use PNG/WebP lossless. **❌ Export slow**: - Check for excessive compression level. - Lower PNG level to 5–6. - Use `withContext(Dispatchers.IO)` for file operations. **❌ Video export issues**: - Ensure video scene is properly configured. - Check available memory with `engine.editor.getMaxExportSize()`. - Monitor progress callback for encoding status. **❌ Out of memory errors**: - Reduce target resolution with `targetWidth` and `targetHeight`. - Export smaller blocks instead of full scene. - Call `engine.stop()` and restart for fresh memory state. ## Next Steps Compression is one of the most practical tools for optimizing export workflows. By adjusting the `ExportOptions` structure in Kotlin, you can deliver high-quality results efficiently—whether your users are exporting social media posts, UI assets, or professional-grade print layouts. - [Export Overview](https://img.ly/docs/cesdk/android/export-save-publish/export/overview-9ed3a8/) to learn about all available export formats. - Apply compression consistently in automated exports using [batch processing](https://img.ly/docs/cesdk/android/automation/batch-processing-ab2d18/). - Combine scaling and compression for [thumbnails](https://img.ly/docs/cesdk/android/export-save-publish/create-thumbnail-749be1/). - Learn about [export formats](https://img.ly/docs/cesdk/android/export-save-publish/export-82f968/) and their capabilities. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Options" description: "Explore export options, supported formats, and configuration features for sharing or rendering output." platform: android url: "https://img.ly/docs/cesdk/android/export-save-publish/export/overview-9ed3a8/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Export Media Assets](https://img.ly/docs/cesdk/android/export-save-publish/export-82f968/) > [Overview](https://img.ly/docs/cesdk/android/export-save-publish/export/overview-9ed3a8/) --- ```kotlin file=@cesdk_android_examples/engine-guides-exporting-blocks/ExportingBlocks.kt reference-only import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import kotlinx.coroutines.withContext import ly.img.engine.Engine import ly.img.engine.ExportOptions import ly.img.engine.MimeType import ly.img.engine.addDefaultAssetSources import java.io.File import java.util.UUID fun exportingBlocks( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) engine.scene.create() engine.editor.setSettingString( "basePath", value = "https://cdn.img.ly/packages/imgly/cesdk-engine/1.70.0/assets", ) engine.addDefaultAssetSources() val sceneUri = Uri.parse( "https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene", ) val scene = engine.scene.load(sceneUri = sceneUri) // Export scene as PNG image. val mimeType = MimeType.PNG // Optionally, the maximum supported export size can be checked before exporting. val maxExportSizeInPixels = engine.editor.getMaxExportSize() // Optionally, the compression level and the target size can be specified. val options = ExportOptions(pngCompressionLevel = 9, targetWidth = null, targetHeight = null) val blob = engine.block.export(scene, mimeType = mimeType, options = options) // Save the blob to file withContext(Dispatchers.IO) { File.createTempFile(UUID.randomUUID().toString(), ".png").apply { outputStream().channel.write(blob) } } engine.stop() } ``` Exporting via the `block.export` endpoint allows fine-grained control of the target format. CE.SDK currently supports exporting scenes, pages, groups, or individual blocks in the MP4, PNG, TGA, JPEG, WEBP, BINARY and PDF formats. To specify the desired type, just pass in the corresponding `mimeType`. Pass additional options in a mime-type specific object: | Format | MimeType | Options (Default) | | ------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PNG | `image/png` | `pngCompressionLevel (5)` - The compression level is a trade-off between file size and encoding/decoding speed, but doesn't affect quality. Valid values are `[0-9]` ranging from no to maximum compression. | | JPEG | `image/jpeg` | `jpegQuality (0.9)` - Directly influences the resulting files visual quality. Smaller = worse quality, but lower file size. Valid values are `(0-1]` | | WEBP | `image/webp` | `webpQuality (1.0)` - Controls the desired output quality. 1.0 results in a special lossless encoding that usually produces smaller file sizes than PNG. Valid values are (0-1], higher means better quality. | | BINARY | `application/octet-stream` | No additional options. This type returns the raw image data in RGBA8888 order in a blob. | | PDF | `application/pdf` | `exportPdfWithHighCompatibility (true)` - Increase compatibility with different PDF viewers. Images and effects will be rasterized with regard to the scene's DPI value instead of simply being embedded. | | PDF | `application/pdf` | `exportPdfWithUnderlayer (false)` - An underlayer is generated by adding a graphics block behind the existing elements of the shape of the elements on the page. | | PDF | `application/pdf` | `underlayerSpotColorName ("")` - The name of the spot color to be used for the underlayer's fill. | | PDF | `application/pdf` | `underlayerOffset (0.0)` - The adjustment in size of the shape of the underlayer. | Certain formats allow additional configuration, e.g. `options.jpegQuality` controls the output quality level when exporting to JPEG. These format-specific options are ignored when exporting to other formats. You can choose which part of the scene to export by passing in the respective block as the first parameter. For all formats, an optional `targetWidth` and `targetHeight` in pixels can be specified. If used, the block will be rendered large enough, that it fills the target size entirely while maintaining its aspect ratio. The supported export size limit can be queried with `editor.getMaxExportSize()`, the width and height should not exceed this value. ### PDF Export Performance The `exportPdfWithHighCompatibility` option controls how images and gradients are embedded in PDFs. When set to `false`, PDF exports can be **6-15x faster** for high-DPI content by embedding images directly instead of rasterizing them. However, this may cause rendering issues in Safari and macOS Preview with gradients that use transparency. Export details: - Exporting automatically performs an internal update to resolve the final layout for all blocks. - Only blocks that belong to the scene hierarchy can be exported. - The export will include the block and all child elements in the block hierarchy. - If the exported block itself is rotated it will be exported without rotation. - If a margin is set on the block it will be included. - If an outside stroke is set on the block it will be included except for pages. - Exporting a scene with more than one page may result in transparent areas between the pages, it is recommended to export the individual pages instead. - Exporting as JPEG drops any transparency on the final image and may lead to unexpected results. ```kotlin reference-only val scene = engine.scene.get()!! val page = engine.scene.getCurrentPage()!! val exportOptions = options = ExportOptions( /** * The PNG compression level to use, when exporting to PNG. * Valid values are 0 to 9, higher means smaller, but slower. * Quality is not affected. * Ignored for other encodings. * The default value is 5. */ pngCompressionLevel = 5, /** * The JPEG quality to use when encoding to JPEG. * Valid values are (0F-1F], higher means better quality. * Ignored for other encodings. * The default value is 0.9F. */ jpegQuality = 0.9F, /** * The WebP quality to use when encoding to WebP. Valid values are (0-1], higher means better quality. * WebP uses a special lossless encoding that usually produces smaller file sizes than PNG. * Ignored for other encodings. Defaults to 1.0. */ webpQuality = 1.0F, /** * An optional target width used in conjunction with target height. * If used, the block will be rendered large enough, that it fills the target * size entirely while maintaining its aspect ratio. * The default value is null. */ targetWidth = null, /** * An optional target height used in conjunction with target with. * If used, the block will be rendered large enough, that it fills the target * size entirely while maintaining its aspect ratio. * The default value is null. */ targetHeight = null, /** * Export the PDF document with a higher compatibility to different PDF viewers. * Bitmap images and some effects like gradients will be rasterized with the DPI * setting instead of embedding them directly. * The default value is true. */ exportPdfWithHighCompatibility = true, /** * Export the PDF document with an underlayer. * An underlayer is generated by adding a graphics block behind the existing elements of the shape of the elements on * the page. */ exportPdfWithUnderlayer = false, /** * The name of the spot color to be used for the underlayer's fill. */ underlayerSpotColorName = "" /** * The adjustment in size of the shape of the underlayer. */ underlayerOffset = 0.0F ) val blob = engine.block.export( block = scene, mimeType = MimeType.PNG, options = exportOptions ) val colorMaskedBlob = engine.block.exportWithColorMask( block = scene, mimeType = MimeType.PNG, maskColor = Color.fromRGBA(r = 1F, g = 0F, b = 0F) options = exportOptions ) val videoExportOptions = ExportVideoOptions( /** * Determines the encoder feature set and in turn the quality, size and speed of the encoding process. * The default value is 77 (Main Profile). */ h264Profile = 77, /** * Controls the H.264 encoding level. This relates to parameters used by the encoder such as bit rate, * timings and motion vectors. Defined by the spec are levels 1.0 up to 6.2. To arrive at an integer value, * the level is multiplied by ten. E.g. to get level 5.2, pass a value of 52. * The default value is 52. */ h264Level = 52, /** * The video bitrate in bits per second. The maximum bitrate is determined by h264Profile and h264Level. * If the value is 0, the bitrate is automatically determined by the engine. */ videoBitrate = 0, /** * The audio bitrate in bits per second. If the value is 0, the bitrate is automatically determined by the engine (128kbps for stereo AAC stream). */ audioBitrate = 0, /** * The target frame rate of the exported video in Hz. * The default value is 30. */ frameRate = 30.0F, /** * An optional target width used in conjunction with target height. * If used, the block will be rendered large enough, that it fills the target * size entirely while maintaining its aspect ratio. */ targetWidth = 1280, /** * An optional target height used in conjunction with target width. * If used, the block will be rendered large enough, that it fills the target * size entirely while maintaining its aspect ratio. */ targetHeight = 720 ) val videoBlob = engine.block.exportVideo( block = page, timeOffset = 0.0, duration = engine.block.getDuration(page), mimeType = MimeType.MP4, progressCallback = { println("Rendered ${it.renderedFrames} frames and encoded ${it.encodedFrames} frames out of ${it.totalFrames} frames") } ) val maxExportSizeInPixels = engine.editor.getMaxExportSize() val availableMemoryInBytes = engine.editor.getAvailableMemory() ``` ## Export a Static Design ```kotlin suspend fun export( block: DesignBlock, mimeType: MimeType, options: ExportOptions? = null, onPreExport: suspend Engine.() -> Unit = {}, ): ByteBuffer ``` Exports a design block element as a file of the given mime type. Performs an internal update to resolve the final layout for the blocks. Note: The export happens in a background thread and the `Engine` instance in the `onPreExport` lambda is a separate instance and is alive until the suspending function resumes. Use this lambda to configure the background engine for export. - `block`: the design block element to export. - `mimeType`: the mime type of the output file. - `options`: the options for exporting the block type - `onPreExport`: the lambda to configure the engine before export. This lambda is called on a background thread, and the `Engine` parameter of this lambda is a separate engine instance running in that background thread. - Returns the exported data. ## Export with a Color Mask ```kotlin suspend fun exportWithColorMask( block: DesignBlock, mimeType: MimeType, maskColor: RGBAColor, options: ExportOptions? = null, onPreExport: suspend Engine.() -> Unit = {}, ): Pair ``` Exports a design block element as a file of the given mime type. Performs an internal update to resolve the final layout for the blocks. Note: The export happens in a background thread and the `Engine` instance in the `onPreExport` lambda is a separate instance and is alive until the suspending function resumes. Use this lambda to configure the background engine for export. - `block`: the design block element to export. - `mimeType`: the mime type of the output file. - `maskColor`: the mask color. - `options`: the options for exporting the block type - `onPreExport`: the lambda to configure the engine before export. This lambda is called on a background thread, and the `Engine` parameter of this lambda is a separate engine instance running in that background thread. - Returns a pair where first is the exported image data and second is the mask data. ## Export a Video Export a page as a video file of the given mime type. ```kotlin suspend fun exportVideo( block: DesignBlock, timeOffset: Double, duration: Double, mimeType: MimeType, progressCallback: (ExportVideoProgress) -> Unit, options: ExportVideoOptions? = null, onPreExport: suspend Engine.() -> Unit = {}, ): ByteBuffer ``` Exports a design block as a video file of the given mime type. Note: The export will run across multiple iterations of the update loop. In each iteration a frame is scheduled for encoding. Note: The export happens in a background thread and the `Engine` instance in the `onPreExport` lambda is a separate instance and is alive until the suspending function resumes. Use this lambda to configure the background engine for export. - `block`: the design block to export. Currently, only page blocks are supported. - `timeOffset`: the time offset in seconds of the page's timeline from which the video will start. - `duration`: the duration in seconds of the final video. - `mimeType`: the mime type of the output video file. - `progressCallback`: a callback that reports on the progress of the export. It informs the receiver of the number of frames rendered by the engine, the number of encoded frames, and the total number of frames to encode. - `options`: the options used for the export of the block. - `onPreExport`: the lambda to configure the engine before export. This lambda is called on a background thread, and the `Engine` parameter of this lambda is a separate engine instance running in that background thread. - Returns the exported video as a file in filesDir. Note that you are responsible for deleting the file after it is used. - Returns the exported data. ## Export Information Before exporting, the maximum export size and available memory can be queried. ```kotlin fun getMaxExportSize(): Int ``` Get the export size limit in pixels on the current device. An export is only possible when both the width and height of the output are below or equal this limit. However, this is only an upper limit as the export might also not be possible due to other reasons, e.g., memory constraints. - Returns the upper export size limit in pixels or an unlimited size, i.e, the maximum signed 32-bit integer value, if the limit is unknown. ```kotlin fun getAvailableMemory(): Long ``` Get the currently available memory in bytes. - Returns the currently available memory in bytes. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "To PDF" description: "Learn how to export pages to PDF." platform: android url: "https://img.ly/docs/cesdk/android/export-save-publish/export/to-pdf-95e04b/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Export Media Assets](https://img.ly/docs/cesdk/android/export-save-publish/export-82f968/) > [To PDF](https://img.ly/docs/cesdk/android/export-save-publish/export/to-pdf-95e04b/) --- ```kotlin file=@cesdk_android_examples/editor-guides-configuration-callbacks/CallbacksEditorSolution.kt reference-only import android.net.Uri import android.widget.Toast import androidx.compose.runtime.Composable import androidx.core.content.FileProvider import androidx.navigation.NavHostController import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.coroutineScope import kotlinx.coroutines.flow.distinctUntilChanged import kotlinx.coroutines.flow.map import kotlinx.coroutines.launch import kotlinx.coroutines.withContext import ly.img.editor.DesignEditor import ly.img.editor.DismissVideoExportEvent import ly.img.editor.EditorDefaults import ly.img.editor.EngineConfiguration import ly.img.editor.HideLoading import ly.img.editor.OnSceneLoaded import ly.img.editor.ShareUriEvent import ly.img.editor.ShowCloseConfirmationDialogEvent import ly.img.editor.ShowErrorDialogEvent import ly.img.editor.ShowLoading import ly.img.editor.ShowVideoExportErrorEvent import ly.img.editor.ShowVideoExportProgressEvent import ly.img.editor.ShowVideoExportSuccessEvent import ly.img.editor.core.event.EditorEvent import ly.img.editor.core.library.data.TextAssetSource import ly.img.editor.core.library.data.TypefaceProvider import ly.img.engine.MimeType import ly.img.engine.SceneMode import ly.img.engine.addDefaultAssetSources import ly.img.engine.addDemoAssetSources import kotlin.coroutines.cancellation.CancellationException // Add this composable to your NavHost @Composable fun CallbacksEditorSolution(navController: NavHostController) { val engineConfiguration = EngineConfiguration.remember( license = "", // pass null or empty for evaluation mode with watermark onCreate = { // Note that lambda is copied from EditorDefaults.onCreate coroutineScope { // In case of process recovery, engine automatically recovers the scene that is why we need to check if (editorContext.engine.scene.get() == null) { editorContext.engine.scene.load(EngineConfiguration.defaultDesignSceneUri) } launch { editorContext.engine.addDefaultAssetSources() val defaultTypeface = TypefaceProvider().provideTypeface(editorContext.engine, "Roboto") requireNotNull(defaultTypeface) editorContext.engine.asset.addSource(TextAssetSource(editorContext.engine, defaultTypeface)) } launch { editorContext.engine.addDemoAssetSources( sceneMode = editorContext.engine.scene.getMode(), withUploadAssetSources = true, ) } } editorContext.eventHandler.send(HideLoading) editorContext.eventHandler.send(OnSceneLoaded()) }, onLoaded = { editorContext.engine.editor.setSettingEnum("touch/pinchAction", "Scale") coroutineScope { launch { editorContext.engine.editor .onHistoryUpdated() .collect { Toast.makeText(editorContext.activity, "History is updated!", Toast.LENGTH_SHORT).show() } } launch { editorContext.engine.editor .onStateChanged() .map { editorContext.engine.editor.getEditMode() } .distinctUntilChanged() .collect { Toast.makeText(editorContext.activity, "Edit mode is updated to $it!", Toast.LENGTH_SHORT).show() } } } }, onExport = { val engine = editorContext.engine val eventHandler = editorContext.eventHandler val context = engine.applicationContext EditorDefaults.run { if (engine.scene.getMode() == SceneMode.VIDEO) { val page = engine.scene.getCurrentPage() ?: engine.scene.getPages()[0] var exportProgress = 0f eventHandler.send(ShowVideoExportProgressEvent(exportProgress)) runCatching { val buffer = engine.block.exportVideo( block = page, timeOffset = 0.0, duration = engine.block.getDuration(page), mimeType = MimeType.MP4, progressCallback = { progress -> val newProgress = progress.encodedFrames.toFloat() / progress.totalFrames if (newProgress >= exportProgress + 0.01f) { exportProgress = newProgress eventHandler.send(ShowVideoExportProgressEvent(exportProgress)) } }, ) val file = writeToTempFile(buffer, MimeType.MP4) withContext(Dispatchers.IO) { FileProvider.getUriForFile( context, "${context.packageName}.ly.img.editor.fileprovider", file, ) } }.onSuccess { uri -> eventHandler.send(ShowVideoExportSuccessEvent(uri, MimeType.MP4.key)) }.onFailure { if (it is CancellationException) { eventHandler.send(DismissVideoExportEvent) } else { eventHandler.send(ShowVideoExportErrorEvent) } } } else { eventHandler.send(ShowLoading) runCatching { val buffer = engine.block.export( block = requireNotNull(engine.scene.get()), mimeType = MimeType.PDF, ) { scene.getPages().forEach { block.setScopeEnabled(it, key = "layer/visibility", enabled = true) block.setVisible(it, visible = true) } } val file = writeToTempFile(buffer, MimeType.PDF) withContext(Dispatchers.IO) { FileProvider.getUriForFile( context, "${context.packageName}.ly.img.editor.fileprovider", file, ) } }.onSuccess { uri -> eventHandler.send(HideLoading) eventHandler.send(ShareUriEvent(uri, MimeType.PDF.key)) }.onFailure { eventHandler.send(HideLoading) eventHandler.send(ShowErrorDialogEvent(error = it)) } } } }, onUpload = { assetDefinition, _ -> val meta = assetDefinition.meta ?: return@remember assetDefinition val sourceUri = Uri.parse(meta["uri"]) val uploadedUri = sourceUri // todo upload the asset here and return remote uri val newMeta = meta + listOf( "uri" to uploadedUri.toString(), "thumbUri" to uploadedUri.toString(), ) assetDefinition.copy(meta = newMeta) }, onClose = { hasUnsavedChanges -> if (hasUnsavedChanges) { editorContext.eventHandler.send(ShowCloseConfirmationDialogEvent) } else { editorContext.eventHandler.send(EditorEvent.CloseEditor()) } }, onError = { error -> editorContext.eventHandler.send(ShowErrorDialogEvent(error)) }, ) DesignEditor(engineConfiguration = engineConfiguration) { // You can set result here navController.popBackStack() } } ``` In this guide, you'll learn how to configure the prebuilt editor (Design Editor, Photo Editor, etc.) to export designs as PDFs. You can keep the built-in file write and share behavior, or inject export options (DPI, underlayer, high compatibility) while preserving the default flow. ## What You'll Learn - Switch the prebuilt editor's export to PDF via `onExport`. - Preserve the default event flow (share file) without custom UI code. - Add export options (DPI, high-compat, underlayer) for design scenes. - Keep MP4 export for video scenes while using PDF for design scenes. ## When to Use It - You want editor UI out of the box, with export customized to PDF. - You want to avoid writing your own share/save UI. - You need optional export tweaks but prefer the editor's default UX. ## Export Control The prebuilt editors have a share control in the navigation bar. This control exports the current scene as either a PNG or MP4, depending on the scene's mode. Then it displays a share sheet or system share dialog.  The editors provide an `onExport` callback you can use to control this behavior. If your export to PDF isn't complicated, configuring the MIME type may be all you need. ```kotlin val engineConfiguration = EngineConfiguration.remember( license = "", onExport = { val engine = editorContext.engine val eventHandler = editorContext.eventHandler EditorDefaults.run { eventHandler.send(ShowLoading) runCatching { val buffer = engine.block.export( block = requireNotNull(engine.scene.get()), mimeType = MimeType.PDF, ) writeToTempFile(buffer, MimeType.PDF) }.onSuccess { file -> eventHandler.send(HideLoading) eventHandler.send(ShareFileEvent(file, MimeType.PDF.key)) }.onFailure { eventHandler.send(HideLoading) eventHandler.send(ShowErrorDialogEvent(error = it)) } } } ) DesignEditor(engineConfiguration = engineConfiguration) { navController.popBackStack() } ``` The preceding code: - Tells the default handler to export design scenes to PDF. - Writes the PDF to a temp file and shares it. - Displays loading and error states using the event handler. ## Adding Options to Export For more complex configurations, you can use `ExportOptions` to customize the PDF output. The `onExport` callback gets access to the engine and event handler. ```kotlin val engineConfiguration = EngineConfiguration.remember( license = "", onExport = { val engine = editorContext.engine val eventHandler = editorContext.eventHandler EditorDefaults.run { when (engine.scene.getMode()) { SceneMode.VIDEO -> { val page = engine.scene.getCurrentPage() ?: engine.scene.getPages()[0] runCatching { val buffer = engine.block.exportVideo( block = page, timeOffset = 0.0, duration = engine.block.getDuration(page), mimeType = MimeType.MP4, ) writeToTempFile(buffer, MimeType.MP4) }.onSuccess { file -> eventHandler.send(ShareFileEvent(file, MimeType.MP4.key)) } } else -> { eventHandler.send(ShowLoading) runCatching { val options = ExportOptions( exportPdfWithHighCompatibility = true, ) val buffer = engine.block.export( block = requireNotNull(engine.scene.get()), mimeType = MimeType.PDF, options = options, ) writeToTempFile(buffer, MimeType.PDF) }.onSuccess { file -> eventHandler.send(HideLoading) eventHandler.send(ShareFileEvent(file, MimeType.PDF.key)) }.onFailure { eventHandler.send(HideLoading) eventHandler.send(ShowErrorDialogEvent(error = it)) } } } } } ) ``` The preceding code creates an `ExportOptions` object and passes it to the PDF export function. You can configure additional options like underlayer generation and DPI settings. Once the PDF has been written to disk, the callback passes it to the event handler to display the share dialog. For video scenes, the callback exports as MP4 instead. ## Export Options The `ExportOptions` class provides these parameters for PDF customization: ```kotlin val options = ExportOptions( exportPdfWithHighCompatibility = true, // Flatten complex elements exportPdfWithUnderlayer = true, // Generate print underlayer underlayerSpotColorName = "White", // Spot color for underlayer ink underlayerOffset = -2.0f, // Offset in design units ) ``` **Available options:** - `exportPdfWithHighCompatibility`: Flatten PDF for better compatibility with older viewers. - `exportPdfWithUnderlayer`: Generate an underlayer shape for specialized printing (fabric, glass). - `underlayerSpotColorName`: Specify the spot color name for the underlayer ink. - `underlayerOffset`: Adjust underlayer size with positive (larger) or negative (smaller) offset. > **Note:** When using underlayer, do not flatten the resulting PDF or you will remove the underlayer. The underlayer sits behind your design as a separate layer. ## Troubleshooting **❌ Export still shares PNG/MP4**: - Ensure `MimeType.PDF` is specified in the `onExport` callback. - Verify the callback is properly configured in `EngineConfiguration`. **❌ PDF looks soft**: - Check the "scene/dpi" property of the scene and increase it if necessary. - Ensure placed images have enough pixels to cover the frame. **❌ Underlayer absent in output**: - Verify the spot color name is correct and matches what the printer expects. - Ensure `exportPdfWithUnderlayer = true` is set in `ExportOptions`. - Do not flatten the PDF or the underlayer will be lost. **❌ Video scene shows different flow**: - This is expected. The SDK exports videos slightly differently than static image scenes. ## Next Steps Now that you know how to configure the editor to export to PDF, here are some topics to explore: - [Spot Colors](https://img.ly/docs/cesdk/android/colors-a9b79c/) – use spot colors for specialized printing. - [Asset Sources & Upload](https://img.ly/docs/cesdk/android/import-media-4e3703/) – bring user images/videos in, then export as PDF. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Save" description: "Save design progress locally or to a backend service to allow for later editing or publishing." platform: android url: "https://img.ly/docs/cesdk/android/export-save-publish/save-c8b124/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Save](https://img.ly/docs/cesdk/android/export-save-publish/save-c8b124/) --- The CreativeEngine allows you to save scenes in a binary format to share them between editors or store them for later editing. Saving a scene can be done as a either scene file or as an archive file. A scene file does not include any fonts or images. Only the source URIs of assets, the general layout, and element properties are stored. When loading scenes in a new environment, ensure previously used asset URIs are available. Conversely, an archive file contains within it the scene's assets and references them as relative URIs. > **Note:** **Warning** A scene file does not include any fonts or images. Only the source > URIs of assets, the general layout, and element properties are stored. When > loading scenes in a new environment, ensure previously used asset URIs are > available. ```kotlin file=@cesdk_android_examples/engine-guides-save-scene-to-archive/SaveSceneToArchive.kt reference-only import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import kotlinx.coroutines.withContext import ly.img.engine.Engine import java.net.HttpURLConnection import java.net.URL import java.nio.channels.Channels fun saveSceneToArchive( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val sceneUri = Uri.parse( "https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene", ) val scene = engine.scene.load(sceneUri = sceneUri) val blob = engine.scene.saveToArchive(scene = scene) withContext(Dispatchers.IO) { val connection = URL("https://example.com/upload/").openConnection() as HttpURLConnection connection.requestMethod = "POST" connection.doOutput = true connection.outputStream.use { Channels.newChannel(it).write(blob) } connection.connect() } engine.stop() } ``` ## Save Scenes to an Archive In this example, we will show you how to save scenes as an archive with the [CreativeEditor SDK](https://img.ly/products/creative-sdk). As an archive, the resulting `Blob` includes all pages and any hidden elements and all the asset data. To get hold of such a `Blob`, you need to use `engine.scene.saveToArchive()`. This is an asynchronous method. After waiting for the coroutine to finish, we receive a `Blob` holding the entire scene currently loaded in the editor including its assets' data. ```kotlin highlight-saveToArchive val blob = engine.scene.saveToArchive(scene = scene) ``` That `Blob` can then be treated as a form file parameter and sent to a remote location. ```kotlin highlight-create-form-data-archive withContext(Dispatchers.IO) { val connection = URL("https://example.com/upload/").openConnection() as HttpURLConnection connection.requestMethod = "POST" connection.doOutput = true connection.outputStream.use { Channels.newChannel(it).write(blob) } connection.connect() } ``` ### Full Code Here's the full code: ```kotlin import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import kotlinx.coroutines.withContext import ly.img.engine.Engine import java.net.HttpURLConnection import java.net.URL import java.nio.channels.Channels fun saveSceneToArchive( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val sceneUri = Uri.parse( "https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene", ) val scene = engine.scene.load(sceneUri = sceneUri) val blob = engine.scene.saveToArchive(scene = scene) withContext(Dispatchers.IO) { val connection = URL("https://example.com/upload/").openConnection() as HttpURLConnection connection.requestMethod = "POST" connection.doOutput = true connection.outputStream.use { Channels.newChannel(it).write(blob) } connection.connect() } engine.stop() } ``` ```kotlin file=@cesdk_android_examples/engine-guides-save-scene-to-blob/SaveSceneToBlob.kt reference-only import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import kotlinx.coroutines.withContext import ly.img.engine.Engine import java.net.HttpURLConnection import java.net.URL fun saveSceneToBlob( license: String?, // pass null or empty for evaluation mode with watermark userId: String, uploadUrl: String, ) = CoroutineScope( Dispatchers.Main, ).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val sceneUri = Uri.parse( "https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene", ) val scene = engine.scene.load(sceneUri = sceneUri) val savedSceneString = engine.scene.saveToString(scene = scene) val blob = savedSceneString.toByteArray(Charsets.UTF_8) runCatching { withContext(Dispatchers.IO) { val connection = URL(uploadUrl).openConnection() as HttpURLConnection connection.requestMethod = "POST" connection.doOutput = true connection.outputStream.use { it.write(blob) } connection.connect() } } engine.stop() } ``` ## Save Scenes to a Blob In this example, we will show you how to save scenes as a `Blob` with the [CreativeEditor SDK](https://img.ly/products/creative-sdk). This is done by converting the contents of a scene to a string, which can then be stored or transferred. For sending these to a remote location, we wrap them in a `Blob` and treat it as a file object. To get hold of the scene contents as string, you need to use `engine.scene.saveToString()`. This is an asynchronous method. After waiting for the coroutine to finish, we receive a plain string holding the entire scene currently loaded in the editor. This includes all pages and any hidden elements but none of the actual asset data. ```kotlin highlight-saveToBlob val savedSceneString = engine.scene.saveToString(scene = scene) ``` The returned string consists solely of ASCII characters and can safely be used further or written to a database. ```kotlin highlight-create-blob val blob = savedSceneString.toByteArray(Charsets.UTF_8) ``` That object can then be treated as a form file parameter and sent to a remote location. ```kotlin highlight-create-form-data-blob runCatching { withContext(Dispatchers.IO) { val connection = URL(uploadUrl).openConnection() as HttpURLConnection connection.requestMethod = "POST" connection.doOutput = true connection.outputStream.use { it.write(blob) } connection.connect() } } ``` ### Full Code Here's the full code: ```kotlin import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import kotlinx.coroutines.withContext import ly.img.engine.Engine import java.net.HttpURLConnection import java.net.URL fun saveSceneToBlob( license: String, userId: String, uploadUrl: String, ) = CoroutineScope( Dispatchers.Main, ).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val sceneUri = Uri.parse( "https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene", ) val scene = engine.scene.load(sceneUri = sceneUri) val savedSceneString = engine.scene.saveToString(scene = scene) val blob = savedSceneString.toByteArray(Charsets.UTF_8) runCatching { withContext(Dispatchers.IO) { val connection = URL(uploadUrl).openConnection() as HttpURLConnection connection.requestMethod = "POST" connection.doOutput = true connection.outputStream.use { it.write(blob) } connection.connect() } } engine.stop() } ``` ```kotlin file=@cesdk_android_examples/engine-guides-save-scene-to-string/SaveSceneToString.kt reference-only import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.Engine fun saveSceneToString( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val sceneUri = Uri.parse( "https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene", ) val scene = engine.scene.load(sceneUri = sceneUri) val savedSceneString = engine.scene.saveToString(scene = scene) println(savedSceneString) engine.stop() } ``` ## Save Scenes to a String In this example, we will show you how to save scenes as a string with the [CreativeEditor SDK](https://img.ly/products/creative-sdk). This is done by converting the contents of a scene to a single string, which can then be stored or transferred. To get hold of such a string, you need to use `engine.scene.saveToString()`. This is an asynchronous method. After waiting for the coroutine to finish, we receive a plain string holding the entire scene currently loaded in the editor. This includes all pages and any hidden elements, but none of the actual asset data. ```kotlin highlight-saveToString val savedSceneString = engine.scene.saveToString(scene = scene) ``` The returned string consists solely of ASCII characters and can safely be used further or written to a database. ```kotlin highlight-result-string println(savedSceneString) ``` ## Full Code ```kotlin import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.Engine fun saveSceneToString( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val sceneUri = Uri.parse( "https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene", ) val scene = engine.scene.load(sceneUri = sceneUri) val savedSceneString = engine.scene.saveToString(scene = scene) println(savedSceneString) engine.stop() } ``` ## Compression Options CE.SDK supports optional compression for saved scenes to reduce file size. Compression is particularly useful for large scenes or when storage space is limited. ```kotlin // Save with Zstd compression (recommended) val compressed = engine.scene.saveToString( scene = scene, options = SaveToStringOptions( compression = CompressionOptions( format = CompressionFormat.ZSTD, level = CompressionLevel.DEFAULT ) ) ) ``` **Compression Formats:** - `CompressionFormat.NONE` - No compression (default) - `CompressionFormat.ZSTD` - Zstandard compression (recommended for best performance) **Compression Levels:** - `CompressionLevel.FASTEST` - Fastest compression, larger output - `CompressionLevel.DEFAULT` - Balanced speed and size (recommended) - `CompressionLevel.BEST` - Best compression, slower **Performance:** Compression adds minimal overhead while reducing scene size by approximately 64%. The default level provides the best balance of speed and compression ratio. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Store Custom Metadata" description: "Attach and persist metadata alongside your design, such as tags, version info, or creator details." platform: android url: "https://img.ly/docs/cesdk/android/export-save-publish/store-custom-metadata-337248/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Store Custom Metadata](https://img.ly/docs/cesdk/android/export-save-publish/store-custom-metadata-337248/) --- ```kotlin file=@cesdk_android_examples/engine-guides-store-metadata/StoreMetadata.kt reference-only import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine fun storeMetadata( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) var scene = engine.scene.createFromImage( Uri.parse("https://img.ly/static/ubq_samples/imgly_logo.jpg"), ) val block = engine.block.findByType(DesignBlockType.Page).first() engine.block.setMetadata(scene, key = "author", value = "img.ly") engine.block.setMetadata(block, key = "customer_id", value = "1234567890") engine.block.setMetadata(block, key = "customer_name", value = "Name") // This will return "img.ly" engine.block.getMetadata(scene, key = "author") // This will return "1000000" engine.block.getMetadata(block, key = "customer_id") // This will return ["customer_id", "customer_name"] engine.block.findAllMetadata(block) engine.block.removeMetadata(block, key = "customer_id") // This will return false engine.block.hasMetadata(block, key = "customer_id") // We save our scene and reload it from scratch val sceneString = engine.scene.saveToString(scene) scene = engine.scene.load(scene = sceneString) // This still returns "img.ly" engine.block.getMetadata(scene, key = "author") // And this still returns "Name" engine.block.getMetadata(block, key = "customer_name") engine.stop() } ``` CE.SDK allows you to store custom metadata in your scenes. You can attach metadata to your scene or directly to your individual design blocks within the scene. This metadata is persistent across saving and loading of scenes. It simply consists of key value pairs of strings. Using any string-based serialization format such as JSON will allow you to store even complex objects. Please note that when duplicating blocks their metadata will also be duplicated. ## Working with Metadata We can add metadata to any design block using `fun setMetadata(block: DesignBlock, key: String, value: String)`. This also includes the scene block. ```kotlin highlight-setMetadata engine.block.setMetadata(scene, key = "author", value = "img.ly") engine.block.setMetadata(block, key = "customer_id", value = "1234567890") engine.block.setMetadata(block, key = "customer_name", value = "Name") ``` We can retrieve metadata from any design block or scene using `fun getMetadata(block: DesignBlock, key: String): String`. Before accessing the metadata you check for its existence using `fun hasMetadata(block: DesignBlock, key: String): Boolean`. ```kotlin highlight-getMetadata // This will return "img.ly" engine.block.getMetadata(scene, key = "author") // This will return "1000000" engine.block.getMetadata(block, key = "customer_id") ``` We can query all metadata keys from any design block or scene using `fun findAllMetadata(block: DesignBlock): List`. For blocks without any metadata, this will return an empty list. ```kotlin highlight-findAllMetadata // This will return ["customer_id", "customer_name"] engine.block.findAllMetadata(block) ``` If you want to get rid of any metadata, you can use `fun removeMetadata(block: DesignBlock, key: String)`. ```kotlin highlight-removeMetadata engine.block.removeMetadata(block, key = "customer_id") // This will return false engine.block.hasMetadata(block, key = "customer_id") ``` Metadata will automatically be saved and loaded as part the scene. So you don't have to worry about it getting lost or having to save it separately. ```kotlin highlight-persistence // We save our scene and reload it from scratch val sceneString = engine.scene.saveToString(scene) scene = engine.scene.load(scene = sceneString) // This still returns "img.ly" engine.block.getMetadata(scene, key = "author") // And this still returns "Name" engine.block.getMetadata(block, key = "customer_name") ``` ## Full Code Here's the full code: ```kotlin import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine fun storeMetadata( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) var scene = engine.scene.createFromImage( Uri.parse("https://img.ly/static/ubq_samples/imgly_logo.jpg"), ) val block = engine.block.findByType(DesignBlockType.Graphic).first() engine.block.setMetadata(scene, key = "author", value = "img.ly") engine.block.setMetadata(block, key = "customer_id", value = "1234567890") engine.block.setMetadata(block, key = "customer_name", value = "Name") // This will return "img.ly" engine.block.getMetadata(scene, key = "author") // This will return "1000000" engine.block.getMetadata(block, key = "customer_id") // This will return ["customer_id", "customer_name"] engine.block.findAllMetadata(block) engine.block.removeMetadata(block, key = "customer_id") // This will return false engine.block.hasMetadata(block, key = "customer_id") // We save our scene and reload it from scratch val sceneString = engine.scene.saveToString(scene) scene = engine.scene.load(scene = sceneString) // This still returns "img.ly" engine.block.getMetadata(scene, key = "author") // And this still returns "Name" engine.block.getMetadata(block, key = "customer_name") engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "File Format Support" description: "See which image, video, audio, font, and template formats CE.SDK supports for import and export." platform: android url: "https://img.ly/docs/cesdk/android/file-format-support-3c4b2a/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Compatibility & Security](https://img.ly/docs/cesdk/android/compatibility-fef719/) > [File Format Support](https://img.ly/docs/cesdk/android/file-format-support-3c4b2a/) --- ## Importing Media ### SVG Limitations ## Exporting Media ## Importing Templates ## Font Formats ## Video & Audio Codecs CE.SDK supports the most widely adopted video and audio codecs to ensure compatibility across platforms: ## Size Limits ### Image Resolution Limits ### Video Resolution & Duration Limits --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Fills" description: "Apply solid colors, gradients, images, or videos as fills to shapes, text, and other design elements." platform: android url: "https://img.ly/docs/cesdk/android/fills-402ddc/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Fills](https://img.ly/docs/cesdk/android/fills-402ddc/) --- --- ## Related Pages - [Fills](https://img.ly/docs/cesdk/android/fills/overview-3895ee/) - Apply solid colors, gradients, images, or videos as fills to shapes, text, and other design elements. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Fills" description: "Apply solid colors, gradients, images, or videos as fills to shapes, text, and other design elements." platform: android url: "https://img.ly/docs/cesdk/android/fills/overview-3895ee/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Fills](https://img.ly/docs/cesdk/android/fills-402ddc/) > [Overview](https://img.ly/docs/cesdk/android/fills/overview-3895ee/) --- ```kotlin file=@cesdk_android_examples/engine-guides-using-fills/UsingFills.kt reference-only import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.Color import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun usingFills( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) engine.scene.zoomToBlock( page, paddingLeft = 40F, paddingTop = 40F, paddingRight = 40F, paddingBottom = 40F, ) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setWidth(block, value = 100F) engine.block.setHeight(block, value = 100F) engine.block.setFill(block, fill = engine.block.createFill(FillType.Color)) engine.block.appendChild(parent = page, child = block) engine.block.supportsFill(scene) // Returns false engine.block.supportsFill(block) // Returns true val colorFill = engine.block.getFill(block) val defaultRectFillType = engine.block.getType(colorFill) val allFillProperties = engine.block.findAllProperties(colorFill) engine.block.setColor( block = colorFill, property = "fill/color/value", value = Color.fromRGBA(r = 1.0F, g = 0.0F, b = 0.0F, a = 1.0F), ) engine.block.setFillEnabled(block, enabled = false) engine.block.setFillEnabled(block, enabled = !engine.block.isFillEnabled(block)) val imageFill = engine.block.createFill(FillType.Image) engine.block.setString( block = imageFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg", ) engine.block.destroy(colorFill) engine.block.setFill(block, fill = imageFill) /* // The following line would also destroy imageFill engine.block.destroy(circle) */ val duplicateBlock = engine.block.duplicate(block) engine.block.setPositionX(duplicateBlock, value = 450F) val autoDuplicateFill = engine.block.getFill(duplicateBlock) engine.block.setString( block = autoDuplicateFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_2.jpg", ) /* // We could now assign this fill to another block. val manualDuplicateFill = engine.block.duplicate(autoDuplicateFill) engine.block.destroy(manualDuplicateFill) */ val sharedFillBlock = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(sharedFillBlock, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setPositionX(sharedFillBlock, value = 350F) engine.block.setPositionY(sharedFillBlock, value = 400F) engine.block.setWidth(sharedFillBlock, value = 100F) engine.block.setHeight(sharedFillBlock, value = 100F) engine.block.appendChild(parent = page, child = sharedFillBlock) engine.block.setFill(sharedFillBlock, fill = engine.block.getFill(block)) engine.stop() } ``` Some [design blocks](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/) in CE.SDK allow you to modify or replace their fill. The fill is an object that defines the contents within the shape of a block. CreativeEditor SDK supports many different types of fills, such as images, solid colors, gradients and videos. Similarly to blocks, each fill has a numeric id which can be used to query and [modify its properties](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/). We currently support the following fill types: - `FillType.Color` - `FillType.LinearGradient` - `FillType.RadialGradient` - `FillType.ConicalGradient` - `FillType.Image` - `FillType.Video` - `FillType.PixelStream` ## Accessing Fills Not all types of design blocks support fills, so you should always first call the `fun supportsFill(block: DesignBlock): Boolean` API before accessing any of the following APIs. ```kotlin highlight-supportsFill engine.block.supportsFill(scene) // Returns false engine.block.supportsFill(block) // Returns true ``` In order to receive the fill id of a design block, call the `fun getFill(block: DesignBlock): DesignBlock` API. You can now pass this id into other APIs in order to query more information about the fill, e.g. its type via the `fun getType(block: DesignBlock): String` API. ```kotlin highlight-getFill val colorFill = engine.block.getFill(block) val defaultRectFillType = engine.block.getType(colorFill) ``` ## Fill Properties Just like design blocks, fills with different types have different properties that you can query and modify via the API. Use `fun findAllProperties(block: DesignBlock): List` in order to get a list of all properties of a given fill. For the solid color fill in this example, the call would return `["fill/color/value", "type"]`. Please refer to the [design blocks](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/) for a complete list of all available properties for each type of fill. ```kotlin highlight-getProperties val allFillProperties = engine.block.findAllProperties(colorFill) ``` Once we know the property keys of a fill, we can use the same APIs as for design blocks in order to modify those properties. For example, we can use `fun setColor(block: DesignBlock, property: String, value: Color)` in order to change the color of the fill to red. Once we do this, our graphic block with rect shape will be filled with solid red. ```kotlin highlight-modifyProperties engine.block.setColor( block = colorFill, property = "fill/color/value", value = Color.fromRGBA(r = 1.0F, g = 0.0F, b = 0.0F, a = 1.0F), ) ``` ## Disabling Fills You can disable and enable a fill using the `fun setFillEnabled(block: DesignBlock, enabled: Boolean)` API, for example in cases where the design block should only have a stroke but no fill. Notice that you have to pass the id of the design block and not of the fill to the API. ```kotlin highlight-disableFill engine.block.setFillEnabled(block, enabled = false) engine.block.setFillEnabled(block, enabled = !engine.block.isFillEnabled(block)) ``` ## Changing Fill Types All design blocks that support fills allow you to also exchange their current fill for any other type of fill. In order to do this, you need to first create a new fill object using `fun createFill(fillType: FillType): DesignBlock`. ```kotlin highlight-createFill val imageFill = engine.block.createFill(FillType.Image) engine.block.setString( block = imageFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg", ) ``` In order to assign a fill to a design block, simply call `fun setFill(block: DesignBlock, fill: DesignBlock)`. Make sure to delete the previous fill of the design block first if you don't need it any more, otherwise we will have leaked it into the scene and won't be able to access it any more, because we don't know its id. Notice that we don't use the `appendChild` API here, which only works with design blocks and not fills. When a fill is attached to one design block, it will be automatically destroyed when the block itself gets destroyed. ```kotlin highlight-replaceFill engine.block.destroy(colorFill) engine.block.setFill(block, fill = imageFill) /* // The following line would also destroy imageFill engine.block.destroy(circle) */ ``` ## Duplicating Fills If we duplicate a design block with a fill that is only attached to this block, the fill will automatically be duplicated as well. In order to modify the properties of the duplicate fill, we have to query its id from the duplicate block. ```kotlin highlight-duplicateFill val duplicateBlock = engine.block.duplicate(block) engine.block.setPositionX(duplicateBlock, value = 450F) val autoDuplicateFill = engine.block.getFill(duplicateBlock) engine.block.setString( block = autoDuplicateFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_2.jpg", ) /* // We could now assign this fill to another block. val manualDuplicateFill = engine.block.duplicate(autoDuplicateFill) engine.block.destroy(manualDuplicateFill) */ ``` ## Sharing Fills It is also possible to share a single fill instance between multiple design blocks. In that case, changing the properties of the fill will apply to all of the blocks that it's attached to at once. Destroying a block with a shared fill will not destroy the fill until there are no other design blocks left that still use that fill. ```kotlin highlight-sharedFill val sharedFillBlock = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(sharedFillBlock, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setPositionX(sharedFillBlock, value = 350F) engine.block.setPositionY(sharedFillBlock, value = 400F) engine.block.setWidth(sharedFillBlock, value = 100F) engine.block.setHeight(sharedFillBlock, value = 100F) engine.block.appendChild(parent = page, child = sharedFillBlock) engine.block.setFill(sharedFillBlock, fill = engine.block.getFill(block)) ``` ## Full Code Here is the full code for working with fills: ```kotlin import kotlinx.coroutines.* import ly.img.engine.* fun usingFills( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) engine.scene.zoomToBlock( page, paddingLeft = 40F, paddingTop = 40F, paddingRight = 40F, paddingBottom = 40F, ) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setWidth(block, value = 100F) engine.block.setHeight(block, value = 100F) engine.block.setFill(block, fill = engine.block.createFill(FillType.Color)) engine.block.appendChild(parent = page, child = block) engine.block.supportsFill(scene) // Returns false engine.block.supportsFill(block) // Returns true val colorFill = engine.block.getFill(block) val defaultRectFillType = engine.block.getType(colorFill) val allFillProperties = engine.block.findAllProperties(colorFill) engine.block.setColor( block = colorFill, property = "fill/color/value", value = Color.fromRGBA(r = 1.0F, g = 0.0F, b = 0.0F, a = 1.0F), ) engine.block.setFillEnabled(block, enabled = false) engine.block.setFillEnabled(block, enabled = !engine.block.isFillEnabled(block)) val imageFill = engine.block.createFill(FillType.Image) engine.block.setString( block = imageFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg", ) engine.block.destroy(colorFill) engine.block.setFill(block, fill = imageFill) /* // The following line would also destroy imageFill engine.block.destroy(circle) */ val duplicateBlock = engine.block.duplicate(block) engine.block.setPositionX(duplicateBlock, value = 450F) val autoDuplicateFill = engine.block.getFill(duplicateBlock) engine.block.setString( block = autoDuplicateFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_2.jpg", ) /* // We could now assign this fill to another block. val manualDuplicateFill = engine.block.duplicate(autoDuplicateFill) engine.block.destroy(manualDuplicateFill) */ val sharedFillBlock = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(sharedFillBlock, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setPositionX(sharedFillBlock, value = 350F) engine.block.setPositionY(sharedFillBlock, value = 400F) engine.block.setWidth(sharedFillBlock, value = 100F) engine.block.setHeight(sharedFillBlock, value = 100F) engine.block.appendChild(parent = page, child = sharedFillBlock) engine.block.setFill(sharedFillBlock, fill = engine.block.getFill(block)) engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Filters and Effects" description: "Enhance visual elements with filters and effects such as blur, duotone, LUTs, and chroma keying." platform: android url: "https://img.ly/docs/cesdk/android/filters-and-effects-6f88ac/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Filters and Effects](https://img.ly/docs/cesdk/android/filters-and-effects-6f88ac/) --- --- ## Related Pages - [Android Filters & Effects SDK](https://img.ly/docs/cesdk/android/filters-and-effects/overview-299b15/) - Enhance visual elements with filters and effects such as blur, duotone, LUTs, and chroma keying. - [Add a Filter or Effect](https://img.ly/docs/cesdk/android/filters-and-effects/create-custom-filters-c796ba/) - Programmatically or manually add effects to design elements to modify their visual style. - [Chroma Key (Green Screen) in Android (Kotlin)](https://img.ly/docs/cesdk/android/filters-and-effects/chroma-key-green-screen-1e3e99/) - Use CE.SDK's green/blue screen keyer to replace backgrounds, tune edges & spill, and composite subjects over virtual scenes. - [Blur](https://img.ly/docs/cesdk/android/filters-and-effects/blur-71d642/) - Apply blur effects to soften backgrounds or create depth and focus in your designs. - [Create a Custom LUT Filter](https://img.ly/docs/cesdk/android/filters-and-effects/create-custom-lut-filter-6e3f49/) - Create and apply custom LUT filters to achieve consistent, brand-aligned visual styles. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Blur" description: "Apply blur effects to soften backgrounds or create depth and focus in your designs." platform: android url: "https://img.ly/docs/cesdk/android/filters-and-effects/blur-71d642/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Filters and Effects](https://img.ly/docs/cesdk/android/filters-and-effects-6f88ac/) > [Apply Blur](https://img.ly/docs/cesdk/android/filters-and-effects/blur-71d642/) --- ```kotlin reference-only // Create and configure a radial blur val radialBlur = engine.block.createBlur(type = BlurType.Radial) engine.block.setFloat(radialBlur, property = "radial/radius", value = 100F) engine.block.setBlur(block, blurBlock = radialBlur) engine.block.setBlurEnabled(block, enabled = true) val isBlurEnabled = engine.block.isBlurEnabled(block) // Access an existing blur if (engine.block.supportsBlur(block)) { val existingBlur = engine.block.getBlur(block) } ``` In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to modify a block's blur through the `block` API. Blurs can be added to any shape or page. You can create and configure individual blurs and apply them to blocks. Blocks support at most one blur at a time. The same blur may be used for different blocks at the same time. ## Creating a Blur To create a blur simply use `fun createBlur(type: BlurType): DesignBlock`. ```kotlin fun createBlur(type: BlurType): DesignBlock ``` Create a new blur, fails if type is unknown or not a valid blur type. - `type`: the type id of the block. - Returns the handle of the newly created blur. We currently support the following blur types: - `BlurType.Uniform` - `BlurType.Linear` - `BlurType.Mirrored` - `BlurType.Radial` ```kotlin highlight-BlockApi-createBlur // Create and configure a radial blur val radialBlur = engine.block.createBlur(type = BlurType.Radial) ``` ## Configuring a Blur You can configure blurs just like you configure design blocks. See [Modify Properties](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/) for more detail. ```kotlin highlight-configureBlur engine.block.setFloat(radialBlur, property = "radial/radius", value = 100F) engine.block.setBlur(block, blurBlock = radialBlur) engine.block.setBlurEnabled(block, enabled = true) val isBlurEnabled = engine.block.isBlurEnabled(block) ``` ## Functions ```kotlin fun setBlur( block: DesignBlock, blurBlock: DesignBlock, ) ``` Connects `block`'s blur to the given `blurBlock`. Required scope: "appearance/blur" - `block`: the block to update. - `blurBlock`: a blur block. ```kotlin fun setBlurEnabled( block: DesignBlock, enabled: Boolean, ) ``` Enable or disable the blur of the given design block. - `block`: the block to update. - `enabled`: the new enabled value. ```kotlin fun isBlurEnabled(block: DesignBlock): Boolean ``` Query if blur is enabled for the given block. - `block`: the block to query. - Returns true if the blur is enabled, false otherwise. ```kotlin fun supportsBlur(block: DesignBlock): Boolean ``` Checks whether the block supports blur. - `block`: the block to query. - Returns true if the block supports blur, false otherwise. ```kotlin fun getBlur(block: DesignBlock): DesignBlock ``` Get the blur block of the given design block. - `block`: the block to query. - Returns the blur block. ## Full Code Here's the full code: ```kotlin // Create and configure a radial blur val radialBlur = engine.block.createBlur(type = BlurType.Radial) engine.block.setFloat(radialBlur, property = "radial/radius", value = 100F) engine.block.setBlur(block, blurBlock = radialBlur) engine.block.setBlurEnabled(block, enabled = true) val isBlurEnabled = engine.block.isBlurEnabled(block) // Access an existing blur if (engine.block.supportsBlur(block)) { val existingBlur = engine.block.getBlur(block) } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Chroma Key (Green Screen) in Android (Kotlin)" description: "Use CE.SDK's green/blue screen keyer to replace backgrounds, tune edges & spill, and composite subjects over virtual scenes." platform: android url: "https://img.ly/docs/cesdk/android/filters-and-effects/chroma-key-green-screen-1e3e99/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Filters and Effects](https://img.ly/docs/cesdk/android/filters-and-effects-6f88ac/) > [Apply Chroma Key (Green Screen)](https://img.ly/docs/cesdk/android/filters-and-effects/chroma-key-green-screen-1e3e99/) --- Chroma keying removes a uniform background color (often green or blue) from a video or image so you can composite the foreground over a new scene. In CE.SDK for Android, chroma keying is an **effect** you attach to an image or video block, with parameters for **color selection**, **similarity threshold**, **edge smoothing**, and **spill suppression**. This guide walks you through applying the effect in Kotlin, dialing it in for clean edges, and composing the keyed result with a replacement background. ## What You'll Learn - How to add the **Green Screen** effect to **image** and **video** blocks. - How to set the key color (green by default, but any color works). - How to tune **colorMatch** (similarity), **smoothness** (edge falloff), and **spill** (desaturating color cast). - How to layer a new background behind the keyed subject. - How to persist, export, and protect templates that include chroma key. ## When to Use It Use chroma key when your source contains a uniform backdrop (green, blue, or a solid brand color) and you want to: - Replace the background with a **virtual set**, branded plate, or blurred depth backdrop. - Place talent over **slides** or **product footage**. - Standardize a team's talking‑head videos with consistent backgrounds. - Composite when using an asset formats such as MP4, H.264 or, JPEG that don't support transparency. Avoid chroma key if the subject's clothing, props, or lighting contains the same hue as your key color, or if the background is highly textured. > **Chroma Key vs. Background Removal:** The `effect/green_screen` shader operates on color similarity directly on the GPU. Unlike AI-based background removal, chroma keying provides predictable, real‑time control for studio footage where lighting and backdrop color are controlled. ## Apply the Green Screen Effect In a Prebuilt Editor Chroma key is one of the standard effects available for images and video clips in the prebuilt editors, such as the Design Editor and the Video Editor. Use it as follows: 1. Select a key image or video clip. 2. Look for the `Effects` button in the inspector and tap it.  Scroll through the effects until you find "Green Screen". Once you tap it, the effect implements immediately.  An options indicator appears for the effect. Tap it to show the options.  Use the sliders and the color wheel, to change the settings for: - key color - color match - smoothness - spill  The "Tuning the Effect" section below explains each of these in detail. ## Apply the Green Screen Effect In Code CE.SDK exposes chroma key as the `EffectType.GreenScreen` effect type with the following key properties: - `effect/green_screen/fromColor` the color to key out (default green). - `effect/green_screen/colorMatch` similarity threshold \[0…1]. - `effect/green_screen/smoothness` edge falloff \[0…1]. - `effect/green_screen/spill` desaturates remaining color spill \[0…1]. ### Key an Image Block ```kotlin import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.Color import ly.img.engine.EffectType import ly.img.engine.Engine fun applyGreenScreenToImage( engine: Engine, imageBlock: Int ) = CoroutineScope(Dispatchers.Main).launch { // 1) Create the effect and attach it to the block val keyer = engine.block.createEffect(type = EffectType.GreenScreen) engine.block.appendEffect(imageBlock, effectBlock = keyer) // 2) Choose the key color (here: pure green); any color works engine.block.setColor( keyer, property = "effect/green_screen/fromColor", color = Color.fromRGBA(r = 0.0f, g = 1.0f, b = 0.0f, a = 1.0f) ) // 3) Tune similarity, smoothness, and spill engine.block.setFloat(keyer, property = "effect/green_screen/colorMatch", value = 0.40f) engine.block.setFloat(keyer, property = "effect/green_screen/smoothness", value = 0.08f) engine.block.setFloat(keyer, property = "effect/green_screen/spill", value = 0.15f) } ``` ### Key a Video Block Video blocks use video fills instead of image fills, but the rest of the workflow is identical. ```kotlin import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.Color import ly.img.engine.EffectType import ly.img.engine.Engine fun applyGreenScreenToVideo( engine: Engine, videoBlock: Int ) = CoroutineScope(Dispatchers.Main).launch { val keyer = engine.block.createEffect(type = EffectType.GreenScreen) engine.block.appendEffect(videoBlock, effectBlock = keyer) // Blue screen example engine.block.setColor( keyer, property = "effect/green_screen/fromColor", color = Color.fromRGBA(r = 0.0f, g = 0.25f, b = 1.0f, a = 1.0f) ) engine.block.setFloat(keyer, property = "effect/green_screen/colorMatch", value = 0.35f) engine.block.setFloat(keyer, property = "effect/green_screen/smoothness", value = 0.10f) engine.block.setFloat(keyer, property = "effect/green_screen/spill", value = 0.25f) } ``` Order matters: if you add other effects, like color adjustments, place the **keyer first** in the stack so later effects operate on the premultiplied result. ### Pick the Key Color from the Image Hard‑coding `fromColor` works for controlled shoots. In general, sample the background color under the user's tap. > **Note:** CE.SDK doesn't provide a built-in API to read a pixel at a screen coordinate. In your Android app, map the tap location to the image/video buffer you control and sample the pixel using APIs such as `Bitmap.getPixel()` or `Canvas`. Convert the sampled RGBA to `Color.fromRGBA()` and set `effect/green_screen/fromColor`. If you embed the `DesignEditor`, keep an app-level copy of the media to sample from, since the editor's preview is GPU-rendered. Tie the sampled color back to the effect: ```kotlin import ly.img.engine.Color import ly.img.engine.Engine fun setKeyColor(engine: Engine, keyer: Int, r: Float, g: Float, b: Float) { engine.block.setColor( keyer, property = "effect/green_screen/fromColor", color = Color.fromRGBA(r = r, g = g, b = b, a = 1.0f) ) } ``` For polished UIs, show a zoomed loupe and a live matte preview as the user drags. ### Composite over a Replacement Background A keyed subject is transparent where the background was, so you **layer a background block beneath** the keyed block. ```kotlin import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun addBackgroundBehind(engine: Engine, page: Int, subject: Int, imageUrl: String) { val bg = engine.block.create(DesignBlockType.Graphic) val shape = engine.block.createShape(ShapeType.Rect) engine.block.setShape(bg, shape = shape) val fill = engine.block.createFill(FillType.Image) engine.block.setString(fill, property = "fill/image/imageFileURI", value = imageUrl) engine.block.setFill(bg, fill = fill) // Make background full‑bleed on the page // Place background **behind** subject engine.block.insertChild(parent = page, child = bg, index = 0) engine.block.fillParent(bg) engine.block.sendToBack(bg) } ``` For video, create a video fill instead of an image fill and align durations in your export. ## Tuning the Effect The three parameters for tuning chroma key composition are: - color match - spill - smoothness Knowing what they impact can help decide your strategy when the composition doesn't look correct. The examples below all show how these values can change this chroma key image.  > **Recommended Starting Values:** | Background | colorMatch | smoothness | spill | > |-------------|-------------|------------|--------| > | **Green Screen** | 0.35–0.45 | 0.08–0.12 | 0.15–0.25 | > | **Blue Screen** | 0.30–0.40 | 0.10–0.15 | 0.25–0.35 | > | **Custom Color** | 0.40–0.50 | 0.08–0.12 | 0.10–0.20 |Tune `colorMatch` first for coverage, then refine edge softness with `smoothness`, and finally correct color tint with `spill`. ### Color Match Color Match determines how close a pixel's color has to be to the key color to be considered *background*. When the value is low, only exact matches are removed. When the value is high, a larger range of colors similar to the key color get removed. What to watch for when the value is wrong: - Too low: you may see patches of the green screen still visible around edges, especially if lighting is uneven or shadows present. - Too high: you risk keying out part of the subject (hair strands, clothing edges, reflective items) creating holes or transparency because the effect is too aggressive.  The preceding image shows color match values of 0.0, 0.5 and 1.0. ### Smoothness Smoothness controls how gradually or sharply the transitions occur, how soft the matte edges of the gradients are. A low value produces sharp transition between keyed and un-keyed areas. When the value is high, there is softer transition. What to watch for when the value is wrong: - Too low: harsh edges, visible fringes around hair or "hard cutouts" that look unnatural. - Too high: a halo effect or the subject blends into the background.  The preceding image shows smoothness values of 0.0, 0.5 and 1.0. ### Spill Spill impacts the unwanted "color spill", when your key color reflects or bleeds onto the subject. This is especially noticeable around edges, hair and, shiny objects. What to watch for when the value is wrong: - Too low: you may see green reflection on the subject (especially edges/hair/shoulders) that doesn't get cleaned up, making it look unnatural or floating. - Too high: the subject's actual color edges are desaturated, making hair or detail look gray, faded or too soft.  The preceding image shows spill values of 0.0, 0.5 and 1.0. ## Lighting & Capture Tips - Keep your backdrop evenly lit and 1–2 stops brighter than your subject. - Avoid shadows or wrinkles. Uneven color creates transparency artifacts. - Separate your subject from the background by at least 1 m to reduce spill. ## Template & Scope Considerations If you ship templates that include a keyer, you might want to lock down parameters to protect quality: - Use **Scopes/Permissions** to limit which effect properties the end‑user can change. - Store platform‑tested defaults (match, smoothness, spill) in the template. - Provide preset chips like **"Green Screen"**, **"Blue Screen"**, **"Brand Cyan"** to switch `fromColor` quickly. ## Performance and Rendering Pipeline CE.SDK runs chroma keying directly on the graphics card for smooth, real-time results. Place the keyer near the start of your effect list so that later effects, like color or tone adjustments, apply correctly to the transparent areas. To keep playback fast, avoid heavy effects such as blur or LUTs before the keyer. ## Export Tips - Prefer **ProRes 4444** (or other alpha‑carrying formats) when exporting an intermediate keyed asset to reuse elsewhere. - For final composites, export with the background enabled and a standard delivery codec/format. ## Testing Checklist - Verify background color is uniform and well lit. - Check for reflective surfaces that might cause spill. - Test both **720p** and **4K** previews to compare performance. - Try different wardrobe colors. Avoid those close to the key color. - Examine edges on hair or fine detail under motion. - Validate output formats (e.g., MP4 with solid background vs. ProRes with alpha). ## Troubleshooting **❌ Holes in the matte (background not fully removed)**: - Increase `colorMatch` slightly. If edges get harsh, bump `smoothness` too. **❌ Foreground punched out (you lose subject detail)**: - Lower `colorMatch` until detail returns; then reduce `spill` if the subject appears tinted. **❌ Green/blue color cast on edges**: - Raise `spill` (try 0.2–0.4). If it looks gray, back it down. **❌ Jagged edges**: - Increase `smoothness` in small steps (0.05–0.15). - Consider adding a light `effect/blur` **after** the keyer for video. **❌ Uneven backgrounds / shadows**: - Sample a darker patch of the backdrop or increase `colorMatch` and compensate with `spill`. **❌ Nothing turns transparent:** - Verify the effect is attached to the **right block** and not to the page. - Check `fromColor` is close to the actual backdrop hue (sample it!). - Ensure your block type supports effects (graphic, video are supported). **❌ Performance drops with 4K video**: - Avoid stacking extra heavy effects **before** the keyer. - Render proxies or downscale the preview while tuning; export at full res. **❌ Skin tones look dull**: - Reduce `spill` and re‑tune `colorMatch`. **❌ Hair/fur looks crunchy:** - Raise `smoothness` incrementally (and consider light post‑blur). ## Next Steps With the core of chroma key compositing mastered, here are some other topics that may be interesting: - Learn about other [Filters & Effects](https://img.ly/docs/cesdk/android/filters-and-effects/overview-299b15/) and try combining the keyer with adjustments for color matching. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Add a Filter or Effect" description: "Programmatically or manually add effects to design elements to modify their visual style." platform: android url: "https://img.ly/docs/cesdk/android/filters-and-effects/create-custom-filters-c796ba/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Filters and Effects](https://img.ly/docs/cesdk/android/filters-and-effects-6f88ac/) > [Create Custom Filters](https://img.ly/docs/cesdk/android/filters-and-effects/create-custom-filters-c796ba/) --- ```kotlin file=@cesdk_android_examples/engine-guides-using-effects/UsingEffects.kt reference-only import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.EffectType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun usingEffects( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) engine.scene.zoomToBlock( page, paddingLeft = 40F, paddingTop = 40F, paddingRight = 40F, paddingBottom = 40F, ) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setPositionX(block, value = 100F) engine.block.setPositionY(block, value = 50F) engine.block.setWidth(block, value = 300F) engine.block.setHeight(block, value = 300F) engine.block.appendChild(parent = page, child = block) val fill = engine.block.createFill(FillType.Image) engine.block.setString( block = fill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg", ) engine.block.setFill(block, fill = fill) engine.block.supportsEffects(scene) // Returns false engine.block.supportsEffects(block) // Returns true val pixelize = engine.block.createEffect(type = EffectType.Pixelize) val adjustments = engine.block.createEffect(type = EffectType.Adjustments) engine.block.appendEffect(block, effectBlock = pixelize) engine.block.insertEffect(block, effectBlock = adjustments, index = 0) // engine.block.removeEffect(rect, index = 0) // This will return [adjustments, pixelize] val effectsList = engine.block.getEffects(block) val unusedEffect = engine.block.createEffect(type = EffectType.HalfTone) engine.block.destroy(unusedEffect) val allPixelizeProperties = engine.block.findAllProperties(pixelize) val allAdjustmentProperties = engine.block.findAllProperties(adjustments) engine.block.setInt(pixelize, property = "pixelize/horizontalPixelSize", value = 20) engine.block.setFloat(adjustments, property = "effect/adjustments/brightness", value = 0.2F) engine.block.setEffectEnabled(pixelize, enabled = false) engine.block.setEffectEnabled(pixelize, !engine.block.isEffectEnabled(pixelize)) engine.stop() } ``` Some [design blocks](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/) in CE.SDK such as pages and graphic blocks allow you to add effects to them. An effect can modify the visual output of a block's [fill](https://img.ly/docs/cesdk/android/fills-402ddc/). CreativeEditor SDK supports many different types of effects, such as adjustments, LUT filters, pixelization, glow, vignette and more. Similarly to blocks, each effect instance has a numeric id which can be used to query and [modify its properties](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/). We create a scene containing a graphic block with an image fill and want to apply effects to this image. ```kotlin highlight-setup val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) engine.scene.zoomToBlock( page, paddingLeft = 40F, paddingTop = 40F, paddingRight = 40F, paddingBottom = 40F, ) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setPositionX(block, value = 100F) engine.block.setPositionY(block, value = 50F) engine.block.setWidth(block, value = 300F) engine.block.setHeight(block, value = 300F) engine.block.appendChild(parent = page, child = block) val fill = engine.block.createFill(FillType.Image) engine.block.setString( block = fill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg", ) engine.block.setFill(block, fill = fill) ``` ## Accessing Effects Not all types of design blocks support effects, so you should always first call the `fun supportsEffects(block: DesignBlock): Boolean` API before accessing any of the following APIs. ```kotlin highlight-supportsEffects engine.block.supportsEffects(scene) // Returns false engine.block.supportsEffects(block) // Returns true ``` ## Creating an Effect In order to add effects to our block, we first have to create a new effect instance, which we can do by calling `fun createEffect(type: EffectType): DesignBlock` and passing it the type of effect that we want. In this example, we create a pixelization and an adjustment effect. Please refer to [API Docs](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/) for a complete list of supported effect types. ```kotlin highlight-createEffect val pixelize = engine.block.createEffect(type = EffectType.Pixelize) val adjustments = engine.block.createEffect(type = EffectType.Adjustments) ``` ## Adding Effects Now we have two effects but the output of our scene looks exactly the same as before. That is because we still need to append these effects to the graphic design block's list of effects, which we can do by calling `fun appendEffect(block: DesignBlock, effectBlock: DesignBlock)`. We can also insert or remove effects from specific indices of a block's effect list using the `fun insertEffect(block: DesignBlock, effectBlock: DesignBlock, index: Int)` and `fun removeEffect(block: DesignBlock, index: Int)` APIs. Effects will be applied to the block in the order they are placed in the block's effects list. If the same effect appears multiple times in the list, it will also be applied multiple times. In our case, the adjustments effect will be applied to the image first, before the result of that is then pixelated. ```kotlin highlight-addEffect engine.block.appendEffect(block, effectBlock = pixelize) engine.block.insertEffect(block, effectBlock = adjustments, index = 0) // engine.block.removeEffect(rect, index = 0) ``` ## Querying Effects Use the `fun getEffects(block: DesignBlock): List` API to query the ordered list of effect ids of a block. ```kotlin highlight-getEffects // This will return [adjustments, pixelize] val effectsList = engine.block.getEffects(block) ``` ## Destroying Effects If we created an effect that we don't want anymore, we have to make sure to destroy it using the same `fun destroy(block: DesignBlock)` API that we also call for design blocks. Effects that are attached to a design block will be automatically destroyed when the design block is destroyed. ```kotlin highlight-destroyEffect val unusedEffect = engine.block.createEffect(type = EffectType.HalfTone) engine.block.destroy(unusedEffect) ``` ## Effect Properties Just like design blocks, effects with different types have different properties that you can query and modify via the API. Use `fun findAllProperties(block: DesignBlock): List` in order to get a list of all properties of a given effect. Please refer to the [API Docs](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/) for a complete list of all available properties for each type of effect. ```kotlin highlight-getProperties val allPixelizeProperties = engine.block.findAllProperties(pixelize) val allAdjustmentProperties = engine.block.findAllProperties(adjustments) ``` Once we know the property keys of an effect, we can use the same APIs as for design blocks in order to [modify those properties](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/). Our adjustment effect here for example will not modify the output unless we at least change one of its adjustment properties - such as the brightness - to not be zero. ```kotlin highlight-modifyProperties engine.block.setInt(pixelize, property = "pixelize/horizontalPixelSize", value = 20) engine.block.setFloat(adjustments, property = "effect/adjustments/brightness", value = 0.2F) ``` ## Disabling Effects You can temporarily disable and enable the individual effects using the `fun setEffectEnabled(effectBlock: DesignBlock, enabled: Boolean)` API. When the effects are applied to a block, all disabled effects are simply skipped. Whether an effect is currently enabled or disabled can be queried with `fun isEffectEnabled(effectBlock: DesignBlock): Boolean`. ```kotlin highlight-disableEffect engine.block.setEffectEnabled(pixelize, enabled = false) engine.block.setEffectEnabled(pixelize, !engine.block.isEffectEnabled(pixelize)) ``` ## Full Code Here's the full code: ```kotlin import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.EffectType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun usingEffects( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) engine.scene.zoomToBlock( page, paddingLeft = 40F, paddingTop = 40F, paddingRight = 40F, paddingBottom = 40F, ) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setPositionX(block, value = 100F) engine.block.setPositionY(block, value = 50F) engine.block.setWidth(block, value = 300F) engine.block.setHeight(block, value = 300F) engine.block.appendChild(parent = page, child = block) val fill = engine.block.createFill(FillType.Image) engine.block.setString( block = fill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg", ) engine.block.setFill(block, fill = fill) engine.block.supportsEffects(scene) // Returns false engine.block.supportsEffects(block) // Returns true val pixelize = engine.block.createEffect(type = EffectType.Pixelize) val adjustments = engine.block.createEffect(type = EffectType.Adjustments) engine.block.appendEffect(block, effectBlock = pixelize) engine.block.insertEffect(block, effectBlock = adjustments, index = 0) // engine.block.removeEffect(rect, index = 0) // This will return [adjustments, pixelize] val effectsList = engine.block.getEffects(block) val unusedEffect = engine.block.createEffect(type = EffectType.HalfTone) engine.block.destroy(unusedEffect) val allPixelizeProperties = engine.block.findAllProperties(pixelize) val allAdjustmentProperties = engine.block.findAllProperties(adjustments) engine.block.setInt(pixelize, property = "pixelize/horizontalPixelSize", value = 20) engine.block.setFloat(adjustments, property = "effect/adjustments/brightness", value = 0.2F) engine.block.setEffectEnabled(pixelize, enabled = false) engine.block.setEffectEnabled(pixelize, !engine.block.isEffectEnabled(pixelize)) engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Create a Custom LUT Filter" description: "Create and apply custom LUT filters to achieve consistent, brand-aligned visual styles." platform: android url: "https://img.ly/docs/cesdk/android/filters-and-effects/create-custom-lut-filter-6e3f49/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Filters and Effects](https://img.ly/docs/cesdk/android/filters-and-effects-6f88ac/) > [Apply Custom LUT Filter](https://img.ly/docs/cesdk/android/filters-and-effects/create-custom-lut-filter-6e3f49/) --- ```kotlin file=@cesdk_android_examples/engine-guides-custom-lut-filter/CustomLUTFilter.kt reference-only import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.EffectType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun customLUTFilter( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope( Dispatchers.Main, ).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 100F) engine.block.setHeight(page, value = 100F) engine.block.appendChild(parent = scene, child = page) engine.scene.zoomToBlock( scene, paddingLeft = 40F, paddingTop = 40F, paddingRight = 40F, paddingBottom = 40F, ) val rect = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(rect, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setWidth(rect, value = 100F) engine.block.setHeight(rect, value = 100F) engine.block.appendChild(parent = page, child = rect) val imageFill = engine.block.createFill(FillType.Image) engine.block.setString( imageFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg", ) val lutFilter = engine.block.createEffect(EffectType.LutFilter) engine.block.setBoolean(lutFilter, property = "effect/enabled", value = true) engine.block.setFloat(lutFilter, property = "effect/lut_filter/intensity", value = 0.9F) @Suppress("ktlint:standard:max-line-length") val lutUri = "https://cdn.img.ly/packages/imgly/cesdk-js/1.70.0/assets/extensions/ly.img.cesdk.filters.lut/LUTs/imgly_lut_ad1920_5_5_128.png" engine.block.setString( lutFilter, property = "effect/lut_filter/lutFileURI", value = lutUri, ) engine.block.setInt(lutFilter, property = "effect/lut_filter/verticalTileCount", value = 5) engine.block.setInt(lutFilter, property = "effect/lut_filter/horizontalTileCount", value = 5) engine.block.appendEffect(rect, effectBlock = lutFilter) engine.block.setFill(rect, fill = imageFill) engine.stop() } ``` We use a technology called Lookup Tables (LUTs) in order to add new filters to our SDK. The main idea is that colors respond to operations that are carried out during the filtering process. We 'record' that very response by applying the filter to the identity image shown below. The resulting image can be used within our SDK and the recorded changes can then be applied to any image by looking up the transformed colors in the modified LUT. If you want to create a new filter, you'll need to [download](content-assets/6e3f49/imgly_lut_ad1920_5_5_128.png) the identity LUT shown above, load it into an image editing software of your choice, apply your operations, save it and add it to your app. > **WARNING:** As any compression artifacts in the edited LUT could lead to distorted results when applying the filter, you need to save your LUT as a PNG file. ## Using Custom Filters In this example, we will use a hosted CDN LUT filter file. First we will load one of our demo scenes and change the first image to use LUT filter we will provide. We will also configure the necessary setting based on the file. LUT file we will use: ## Load Scene After the setup, we create a new scene. Within this scene, we create a page, set its dimensions, and append it to the scene. Lastly, we adjust the zoom level to properly fit the page into the view. ```kotlin highlight-load-scene val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 100F) engine.block.setHeight(page, value = 100F) engine.block.appendChild(parent = scene, child = page) engine.scene.zoomToBlock( scene, paddingLeft = 40F, paddingTop = 40F, paddingRight = 40F, paddingBottom = 40F, ) ``` ## Create Rectangle Next, we create a rectangle with defined dimensions and append it to the page. We will apply our LUT filter to this rectangle. ```kotlin highlight-create-rect val rect = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(rect, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setWidth(rect, value = 100F) engine.block.setHeight(rect, value = 100F) engine.block.appendChild(parent = page, child = rect) ``` ## Load Image After creating the rectangle, we create an image fill with a specified URL. This will load the image as a fill for the rectangle to which we will apply the LUT filter. ```kotlin highlight-create-image-fill val imageFill = engine.block.createFill(FillType.Image) engine.block.setString( imageFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg", ) ``` ## Create LUT Filter Now, we create a Look-Up Table (LUT) filter effect. We enable the filter, set its intensity, and provide a URL for the LUT file. We also define the tile count for the filter. The LUT filter effect is then applied to the rectangle and image should appear black and white. ```kotlin highlight-create-lut-filter val lutFilter = engine.block.createEffect(EffectType.LutFilter) engine.block.setBoolean(lutFilter, property = "effect/enabled", value = true) engine.block.setFloat(lutFilter, property = "effect/lut_filter/intensity", value = 0.9F) @Suppress("ktlint:standard:max-line-length") val lutUri = "https://cdn.img.ly/packages/imgly/cesdk-js/1.70.0/assets/extensions/ly.img.cesdk.filters.lut/LUTs/imgly_lut_ad1920_5_5_128.png" engine.block.setString( lutFilter, property = "effect/lut_filter/lutFileURI", value = lutUri, ) engine.block.setInt(lutFilter, property = "effect/lut_filter/verticalTileCount", value = 5) engine.block.setInt(lutFilter, property = "effect/lut_filter/horizontalTileCount", value = 5) ``` ## Apply LUT Filter Finally, we apply the LUT filter effect to the rectangle, and set the image fill to the rectangle. Before setting an image fill, we destroy the default rectangle fill. ```kotlin highlight-apply-lut-filter engine.block.appendEffect(rect, effectBlock = lutFilter) engine.block.setFill(rect, fill = imageFill) ``` ## Full Code Here's the full code: ```kotlin import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.EffectType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun customLUTFilter( license: String, userId: String, ) = CoroutineScope( Dispatchers.Main, ).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 100F) engine.block.setHeight(page, value = 100F) engine.block.appendChild(parent = scene, child = page) engine.scene.zoomToBlock( scene, paddingLeft = 40F, paddingTop = 40F, paddingRight = 40F, paddingBottom = 40F, ) val rect = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(rect, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setWidth(rect, value = 100F) engine.block.setHeight(rect, value = 100F) engine.block.appendChild(parent = page, child = rect) val imageFill = engine.block.createFill(FillType.Image) engine.block.setString( imageFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg", ) val lutFilter = engine.block.createEffect(EffectType.LutFilter) engine.block.setBoolean(lutFilter, property = "effect/enabled", value = true) engine.block.setFloat(lutFilter, property = "effect/lut_filter/intensity", value = 0.9F) @Suppress("ktlint:standard:max-line-length") val lutUri = "https://cdn.img.ly/packages/imgly/cesdk-js/$UBQ_VERSION$/assets/extensions/ly.img.cesdk.filters.lut/LUTs/imgly_lut_ad1920_5_5_128.png" engine.block.setString( lutFilter, property = "effect/lut_filter/lutFileURI", value = lutUri, ) engine.block.setInt(lutFilter, property = "effect/lut_filter/verticalTileCount", value = 5) engine.block.setInt(lutFilter, property = "effect/lut_filter/horizontalTileCount", value = 5) engine.block.appendEffect(rect, effectBlock = lutFilter) engine.block.setFill(rect, fill = imageFill) engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Android Filters & Effects SDK" description: "Enhance visual elements with filters and effects such as blur, duotone, LUTs, and chroma keying." platform: android url: "https://img.ly/docs/cesdk/android/filters-and-effects/overview-299b15/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Filters and Effects](https://img.ly/docs/cesdk/android/filters-and-effects-6f88ac/) > [Overview](https://img.ly/docs/cesdk/android/filters-and-effects/overview-299b15/) --- In CreativeEditor SDK (CE.SDK), *filters* and *effects* refer to visual modifications that enhance or transform the appearance of design elements. Filters typically adjust an element’s overall color or tone, while effects add specific visual treatments like blur, sharpness, or distortion. You can apply both filters and effects through the user interface or programmatically using the CE.SDK API. They allow you to refine the look of images, videos, and graphic elements in your designs with precision and flexibility. [Explore Demos](https://img.ly/showcases/cesdk?tags=android) [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Clone GitHub Project" description: "Using CE.SDK with a cloned Android GitHub project" platform: android url: "https://img.ly/docs/cesdk/android/get-started/clone-github-project-f9890l/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) > [Quickstart Jetpack Compose](https://img.ly/docs/cesdk/android/get-started/new-jetpack-compose-project-c6567i/) --- This guide will walk you through cloning an existing sample project with the CE.SDK editor already set up ## Pre-requisites - Android Studio installed on your machine - A valid **CE.SDK license key** ([Get a free trial](https://img.ly/forms/free-trial)), use `null` or an empty string to run in evaluation mode with watermark. ## Clone the GitHub Repository Launch Android Studio and select `File -> New -> Project from version control` Next, add the following URL: ``` https://github.com/imgly/cesdk-android-examples.git ```  Click "Clone" and wait for the project to be downloaded and set up. ## Run the Project In the `local.properties` file, add your CE.SDK license key (or leave it empty to run in evaluation mode with watermark) ``` license=MY_LICENSE_GOES_HERE ``` You may have to create this file, if Android Studio did not generate it for you. Finally, run the app on your device or android emulator. ## Common Errors Here are some common errors you may encounter through this guide, and how to solve them. #### Invalid License |  |  | | ---------------------------------------------------- | ---------------------------------------------------- | | | | **Solution** -> Check whether you have supplied a valid license #### No Internet  **Solution** -> Check your internet connection --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Existing Project Setup" description: "Learn how to integrate the CreativeEditor SDK into your existing Android Jetpack Compose project" platform: android url: "https://img.ly/docs/cesdk/android/get-started/existing-project-g0901m/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) > [Quickstart Jetpack Compose](https://img.ly/docs/cesdk/android/get-started/new-jetpack-compose-project-c6567i/) --- This guide shows you how to integrate the CreativeEditor SDK into your existing Android Jetpack Compose project. Follow these steps to learn how to: - **add** the necessary dependencies. - **configure** the editor. - **test** the integration. ## Who Is This Guide For? This guide is for developers who: - Have an existing Android Jetpack Compose project - Want to add CreativeEditor SDK features to their app - Need to understand common integration patterns - Want to test available editing capabilities and workflows ## What You'll Achieve By following this guide, you'll perform the following tasks: - **Project Integration**: Add CreativeEditor SDK to your existing Android project - **Editor Implementation**: Implement the editor with proper lifecycle management - **Testing**: Verify the integration works correctly - **Customization**: Learn how to customize the editor for your use case [View Android Examples](https://github.com/imgly/cesdk-android-examples) [Android Documentation](https://img.ly/docs/cesdk/android) ## Prerequisites ### Development Environment - Android Studio (latest version) - Android SDK (API level 24 or higher) - Kotlin 1.9.10 or higher - Gradle 8.4 or later - Jetpack Compose BOM 2023.05.01 or higher ### Platform Requirements - **Android**: API level 24 (Android 7.0) or higher - **Supported ABIs**: arm64-v8a, armeabi-v7a, x86\_64, x86 ### License - A valid **CE.SDK license key** ([Get a free trial](https://img.ly/forms/free-trial)), use `null` or an empty string to run in evaluation mode with watermark. ## Verify Your Setup Before starting, verify your Android development environment: ```bash gradle --version ``` This command checks your Gradle installation and reports any issues to resolve before proceeding. > **Note:** You can customize the CreativeEditor SDK for Android exclusively through > native code (Kotlin), as described in the > [configuration overview section](https://img.ly/docs/cesdk/android/user-interface/customization-72b2f8/). ## Step 1: Add Dependencies to Your Existing Project ### 1.1 Add IMG.LY Repository Update your `settings.gradle.kts` file to include the IMG.LY repository: ```kotlin title="settings.gradle.kts" dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() maven { name = "IMG.LY Artifactory" url = uri("https://artifactory.img.ly/artifactory/maven") mavenContent { includeGroup("ly.img") } } } } ``` ### 1.2 Add Editor Dependencies Update your `app/build.gradle.kts` file to include the CreativeEditor SDK: ```kotlin title="build.gradle.kts" dependencies { // CreativeEditor SDK implementation("ly.img:editor:1.57.0") // Jetpack Compose BOM implementation(platform("androidx.compose:compose-bom:2025.04.01")) implementation("androidx.activity:activity-compose") implementation("androidx.compose.ui:ui") implementation("androidx.compose.ui:ui-tooling-preview") implementation("androidx.compose.material3:material3") implementation("androidx.compose.runtime:runtime") implementation("androidx.compose.foundation:foundation") } ``` ### 1.3 Configure Android Settings Ensure your `app/build.gradle.kts` has the correct Android configuration: ```kotlin title="build.gradle.kts" android { compileSdk = 34 defaultConfig { minSdk = 24 targetSdk = 34 } buildFeatures { compose = true } composeOptions { kotlinCompilerExtensionVersion = "1.5.15" } kotlinOptions { jvmTarget = "17" } packaging { resources { excludes += "/META-INF/{AL2.0,LGPL2.1}" } } } ``` ### 1.4 Sync Project After adding the dependencies, sync your project: In Android Studio, click **Sync Project with Gradle Files** to download and configure all dependencies. This downloads and installs the CreativeEditor SDK and its dependencies automatically through Gradle. ## Step 2: Implement the Editor Integration ### 2.1 Create Editor Composable Create a new Kotlin file (for example, `EditorComposable.kt`) in your project: ```kotlin file=@cesdk_android_examples/editor-guides-quickstart/EditorComposable.kt import androidx.compose.runtime.Composable import ly.img.editor.DesignEditor import ly.img.editor.EngineConfiguration import ly.img.editor.rememberForDesign @Composable fun EditorComposable() { val engineConfiguration = EngineConfiguration.rememberForDesign( // Get your license from https://img.ly/forms/free-trial // pass null or empty for evaluation mode with watermark license = "", userId = "", // A unique string to identify your user/session ) DesignEditor( engineConfiguration = engineConfiguration, onClose = { // Close the editor here // If using a navigation library, call pop() or navigateUp() here }, ) } ``` ### 2.2 Update Your MainActivity Modify your existing `MainActivity.kt` to include the editor: ```kotlin title="MainActivity.kt" import android.os.Bundle import androidx.activity.ComponentActivity import androidx.activity.compose.setContent import androidx.compose.foundation.layout.fillMaxSize import androidx.compose.material3.MaterialTheme import androidx.compose.material3.Surface import androidx.compose.ui.Modifier class MainActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContent { MaterialTheme { Surface( modifier = Modifier.fillMaxSize(), color = MaterialTheme.colorScheme.background ) { EditorComposable() } } } } } ``` ### 2.3 Add Required Permissions Update your `AndroidManifest.xml` to include necessary permissions: ```xml title="AndroidManifest.xml" ``` ## Step 3: Test Your Editor Integration ### 3.1 Build and Run Build your Android project using Gradle: ### 3.2 Test on Android Device ```bash ./gradlew installInternalDebug ``` ### 3.3 Verify Features After launching your app, verify these features work correctly: - **Editor Launch**: The CreativeEditor SDK opens without errors - **Template Selection**: You can browse and select templates - **Editing Tools**: All editing tools are accessible and functional - **Export**: You can export edited content successfully - **Navigation**: The editor closes properly when finished ### 3.4 Common Test Scenarios - **Photo Editing**: Import and edit photos - **Text Addition**: Add and customize text elements - **Template Usage**: Apply and customize templates - **Export Options**: Test different export formats - **Performance**: Verify smooth operation on target devices ## Step 4: Customize for Your Use Case ### 4.1 Editor Configuration Options The CreativeEditor SDK offers different presets for common use cases: #### Available Editor Types Summary | Editor Type | Parameters | Use Case | | --------------------- | ----------------------------------------------------------- | ----------------------- | | `rememberForDesign` | license, userId, baseUri, sceneUri, renderTarget | General design creation | | `rememberForPhoto` | license, imageUri, imageSize, userId, baseUri, renderTarget | Photo editing | | `rememberForVideo` | license, userId, baseUri, sceneUri, renderTarget | Video editing | | `rememberForApparel` | license, userId, baseUri, sceneUri, renderTarget | T-shirt/apparel design | | `rememberForPostcard` | license, userId, baseUri, sceneUri, renderTarget | Postcard creation | | Editor Type | Use Case | Kotlin Implementation | | ---------------- | ----------------------------- | ------------------------- | | **PhotoEditor** | Photo editing and enhancement | `PhotoEditor` composable | | **DesignEditor** | Graphic design and templates | `DesignEditor` composable | | **VideoEditor** | Video editing and effects | `VideoEditor` composable | ### 4.2 Custom Configuration You can customize the editor behavior: ```kotlin title="EditorComposable.kt" @Composable fun CustomEditorComposable() { val engineConfiguration = EngineConfiguration.rememberForDesign( license = "", userId = "", // Add custom configuration here ) DesignEditor( engineConfiguration = engineConfiguration, onClose = { /* Handle close */ }, onExport = { result -> /* Handle export */ } ) } ``` ## Step 5: Troubleshooting ### Common Issues and Solutions #### Gradle Sync Issues - **Problem**: Repository not found - **Solution**: Verify the IMG.LY repository URL in `settings.gradle.kts` #### Compilation Errors - **Problem**: Missing dependencies - **Solution**: Ensure you've installed all Jetpack Compose dependencies. #### Runtime Errors - **Problem**: Invalid license - **Solution**: Verify your license key is correct and valid (or pass `null` for evaluation mode with watermark) #### Performance Issues - **Problem**: Slow editor loading - **Solution**: Check device specifications and memory usage #### Integration Issues - **Problem**: Editor not displaying - **Solution**: Verify the composable is properly called in your activity ## Step 6: Next Steps ### Advanced Features - Implement custom asset sources - Add custom filters and effects - Integrate with your backend services - Implement user authentication ### Other Integrations - Explore camera integration - Add video editing capabilities - Implement batch processing - Add cloud storage integration ### Production Considerations - Optimize for performance - Implement proper error handling - Add analytics and monitoring - Test on different device configurations ## Additional Resources - [CreativeEditor SDK Documentation](https://img.ly/docs/cesdk/android) - [Android Examples Repository](https://github.com/imgly/cesdk-android-examples) - [Jetpack Compose Documentation](https://developer.android.com/jetpack/compose) - [Android Development Guide](https://developer.android.com/guide) --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "MCP Server" description: "Connect AI assistants to CE.SDK documentation using the Model Context Protocol (MCP) server." platform: android url: "https://img.ly/docs/cesdk/android/get-started/mcp-server-fde71c/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) > [MCP Server](https://img.ly/docs/cesdk/android/get-started/mcp-server-fde71c/) --- The CE.SDK MCP server provides a standardized interface that allows any compatible AI assistant to search and access our documentation. This enables AI tools like Claude, Cursor, and VS Code Copilot to provide more accurate, context-aware help when working with CE.SDK. ## What is MCP? The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that enables AI assistants to securely connect to external data sources. By connecting your AI tools to our MCP server, you get: - **Accurate answers**: AI assistants can search and retrieve the latest CE.SDK documentation - **Context-aware help**: Get platform-specific guidance for your development environment - **Up-to-date information**: Always access current documentation without relying on training data ## Available Tools The MCP server exposes two tools: | Tool | Description | |------|-------------| | `search` | Search documentation by query string | | `fetch` | Retrieve the full content of a document by ID | ## Server Endpoint | URL | Transport | |-----|-----------| | `https://mcp.img.ly/mcp` | Streamable HTTP | No authentication is required. ## Setup Instructions ### Claude Code Add the MCP server with a single command: ```bash claude mcp add --transport http imgly_docs https://mcp.img.ly/mcp ``` ### Claude Desktop 1. Open Claude Desktop and go to **Settings** (click your profile icon) 2. Navigate to **Connectors** in the sidebar 3. Click **Add custom connector** 4. Enter the URL: `https://mcp.img.ly/mcp` 5. Click **Add** to connect ### Cursor Add the following to your Cursor MCP configuration. You can use either: - **Project-specific**: `.cursor/mcp.json` in your project root - **Global**: `~/.cursor/mcp.json` ```json { "mcpServers": { "imgly_docs": { "url": "https://mcp.img.ly/mcp" } } } ``` ### VS Code Add to your workspace configuration at `.vscode/mcp.json`: ```json { "servers": { "imgly_docs": { "type": "http", "url": "https://mcp.img.ly/mcp" } } } ``` ### Windsurf Add the following to your Windsurf MCP configuration at `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "imgly_docs": { "serverUrl": "https://mcp.img.ly/mcp" } } } ``` ### Other Clients For other MCP-compatible clients, use the endpoint `https://mcp.img.ly/mcp` with HTTP transport. Refer to your client's documentation for the specific configuration format. ## Usage Once configured, your AI assistant will automatically have access to CE.SDK documentation. You can ask questions like: - "How do I add a text block in CE.SDK?" - "Show me how to export a design as PNG" - "What are the available blend modes?" The AI will search our documentation and provide answers based on the latest CE.SDK guides and API references. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "New Project Setup" description: "Learn how to integrate the CreativeEditor SDK into a new Android Activity-based project" platform: android url: "https://img.ly/docs/cesdk/android/get-started/new-activity-based-ui-project-d7678j/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) > [Quickstart Activity](https://img.ly/docs/cesdk/android/get-started/new-activity-based-ui-project-d7678j/) --- This guide shows you how to integrate the CreativeEditor SDK into a **new Android Activity-based project**. Learn how to: - **create** a new project. - **add** the necessary dependencies. - **configure** the editor. - **test** the integration. ## Who Is This Guide For? This guide is for developers who: - Have experience with Android development and Kotlin - Want to create a new Android Activity-based project with integrated creative editing capabilities - Need to implement user-friendly editing interfaces - Want to add professional-grade image editing, design creation, and video editing to their Android apps - Prefer using traditional Android Views with Activity-based architecture ## What You'll Achieve By following this guide, you: - Create a new Android Activity-based project with CreativeEditor SDK integration - Configure platform-specific requirements for Android - Implement a functional editor that you can launch from your app - Test and verify the integration works correctly [Explore Android Demos](https://img.ly/showcases/cesdk/?tags=android) [View on GitHub](https://github.com/imgly/cesdk-android-examples) ## Prerequisites Before you begin, ensure you have the following requirements: ### Development Environment - **Android Studio**: Latest version (Hedgehog or later) - **Kotlin**: 1.9.10 or later - **Gradle**: 8.4 or later - **Git CLI** for version control ### Platform Requirements - **Android**: 7.0+ (API level 24+) - **Minimum SDK**: 24 - **Target SDK**: Latest stable version ### License - A valid **CE.SDK license key** ([Get a free trial](https://img.ly/forms/free-trial)), use `null` or an empty string to run in evaluation mode with watermark. ### Verify Your Setup Run the following command to verify your Android development environment: ```bash gradle --version ``` This command checks your Gradle installation and reports any issues to resolve before proceeding. > **Note:** You can customize the CreativeEditor SDK for Android through **native code > (Kotlin) only**, as described in the > [configuration overview section](https://img.ly/docs/cesdk/android/user-interface/customization-72b2f8/). ## Step 1: Create a New Android Activity-Based Project First, verify your Android Studio installation and create a new project: 1. **Open Android Studio** and select "New Project" 2. **Choose "Empty Views Activity"** template 3. **Configure your project**: - Name: `cesdk_android_activity_app` - Package name: `com.example.cesdkactivityapp` - Language: **Kotlin** - Minimum SDK: **API 24 (Android 7.0)** - Build configuration language: **Kotlin DSL** ### Project Structure Your new project should have this structure: ``` cesdk_android_activity_app/ ├── app/ # Main application module │ ├── src/main/ │ │ ├── java/ # Kotlin source files │ │ ├── res/ # Resources │ │ └── AndroidManifest.xml │ ├── build.gradle.kts # App-level build configuration │ └── proguard-rules.pro # ProGuard rules ├── gradle/ # Gradle wrapper ├── build.gradle.kts # Project-level build configuration ├── settings.gradle.kts # Project settings └── gradle.properties # Gradle properties ``` ## Step 2: Add the CreativeEditor SDK Dependency Add the CreativeEditor SDK to your project by updating the build configuration: ### 2.1 Add IMG.LY Repository Update your `settings.gradle.kts` to include the IMG.LY repository: ```kotlin title="settings.gradle.kts" dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() // Add CE.SDK dependency here maven { name = "IMG.LY Artifactory" url = uri("https://artifactory.img.ly/artifactory/maven") mavenContent { includeGroup("ly.img") } } } } ``` ### 2.2 Add Editor Dependency Update your `app/build.gradle.kts` to include the editor dependency: ```kotlin title="build.gradle.kts" dependencies { implementation("ly.img:editor:1.57.0") // Required dependencies for CE.SDK (includes Compose internally) implementation("androidx.appcompat:appcompat:1.6.1") implementation("androidx.activity:activity-compose:1.8.2") implementation("androidx.compose.ui:ui:1.5.4") implementation("androidx.compose.material3:material3:1.1.2") // Other Android dependencies implementation("androidx.core:core-ktx:1.12.0") implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.7.0") implementation("com.google.android.material:material:1.11.0") } ``` ### 2.3 Configure Android Settings Ensure your `app/build.gradle.kts` has the correct Android configuration: ```kotlin title="build.gradle.kts" android { compileSdk = 34 defaultConfig { minSdk = 24 targetSdk = 34 } kotlinOptions { jvmTarget = "17" } packaging { resources { excludes += "/META-INF/{AL2.0,LGPL2.1}" } } } ``` ### 2.4 Sync Project After adding the dependency, sync your project to download the CreativeEditor SDK: In Android Studio, click **Sync Project with Gradle Files**. This downloads and installs the CreativeEditor SDK and its dependencies automatically through Gradle. ## Step 3: Implement the Editor Integration ### 3.1 Create Editor Activity Create a new Kotlin file called `EditorActivity.kt` in your app module's main source set (typically `app/src/main/java/com/yourpackage/`): ```kotlin file=@cesdk_android_examples/editor-guides-quickstart/EditorActivity.kt import android.os.Bundle import androidx.activity.compose.setContent import androidx.appcompat.app.AppCompatActivity import ly.img.editor.DesignEditor import ly.img.editor.EngineConfiguration import ly.img.editor.rememberForDesign class EditorActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContent { val engineConfiguration = EngineConfiguration.rememberForDesign( // Get your license from https://img.ly/forms/free-trial // pass null or empty for evaluation mode with watermark license = "", userId = "", // A unique string to identify your user/session ) DesignEditor( engineConfiguration = engineConfiguration, onClose = { // Close the editor here finish() }, ) } } } ``` ### 3.2 Update MainActivity Modify your existing `MainActivity.kt` file (located in `app/src/main/java/com/yourpackage/`) to launch the editor: ```kotlin title="MainActivity.kt" import android.content.Intent import android.os.Bundle import androidx.appcompat.app.AppCompatActivity import com.example.cesdkactivityapp.databinding.ActivityMainBinding class MainActivity : AppCompatActivity() { private lateinit var binding: ActivityMainBinding override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) binding = ActivityMainBinding.inflate(layoutInflater) setContentView(binding.root) binding.launchEditorButton.setOnClickListener { val intent = Intent(this, EditorActivity::class.java) startActivity(intent) } } } ``` ### 3.3 Update Layout File Update your `activity_main.xml` to include a button: ```xml title="activity_main.xml" ``` ### 3.4 Add Required Permissions Update your `AndroidManifest.xml` to include necessary permissions and register the activity: ```xml title="AndroidManifest.xml" ``` ## Step 4: Test Your Editor Integration ### 4.1 Build and Run Build your Android project using Gradle: ### 4.2 Test on Android Device ```bash ./gradlew installDebug ``` ### 4.3 Verify Features After launching your app, verify these features work correctly: - **App Launch**: The main activity opens without errors - **Button Interaction**: The "Launch Creative Editor SDK" button responds to taps - **Editor Launch**: The CreativeEditor SDK opens without errors - **Template Selection**: You can browse and select templates - **Editing Tools**: All editing tools are accessible and functional - **Export**: You can export edited content successfully - **Navigation**: The editor closes properly when finished ### 4.4 Common Test Scenarios - **Photo Editing**: Import and edit photos - **Text Addition**: Add and customize text elements - **Template Usage**: Apply and customize templates - **Export Options**: Test different export formats - **Performance**: Verify smooth operation on target devices ## Step 5: Customize for Your Use Case ### 5.1 Editor Configuration Options The CreativeEditor SDK offers different presets for common use cases: | Editor Type | Use Case | Kotlin Implementation | | ---------------- | ----------------------------- | ------------------------- | | **PhotoEditor** | Photo editing and enhancement | `PhotoEditor` composable | | **DesignEditor** | Graphic design and templates | `DesignEditor` composable | | **VideoEditor** | Video editing and effects | `VideoEditor` composable | ### 5.2 Custom Configuration You can customize the editor behavior: ```kotlin title="EditorActivity.kt" class CustomEditorActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val engineConfiguration = EngineConfiguration.rememberForDesign( license = "", userId = "", // Add custom configuration here ) setContent { DesignEditor( engineConfiguration = engineConfiguration, onClose = { finish() }, onExport = { result -> /* Handle export */ } ) } } } ``` ## Step 6: Troubleshooting ### Common Issues and Solutions #### Gradle Sync Issues - **Problem**: Repository not found - **Solution**: Verify the IMG.LY repository URL in `settings.gradle.kts` #### Compilation Errors - **Problem**: Missing dependencies - **Solution**: Ensure all required dependencies are included #### Runtime Errors - **Problem**: Invalid license - **Solution**: Verify your license key is correct and valid (or pass `null` for evaluation mode with watermark) #### Performance Issues - **Problem**: Slow editor loading - **Solution**: Check device specifications and memory usage #### Integration Issues - **Problem**: Editor not displaying - **Solution**: Verify the activity is properly registered in AndroidManifest.xml ## Step 7: Next Steps ### Advanced Features - Implement custom asset sources - Add custom filters and effects - Integrate with your backend services - Implement user authentication ### Other Integrations - Explore camera integration - Add video editing capabilities - Implement batch processing - Add cloud storage integration ### Production Considerations - Optimize for performance - Implement proper error handling - Add analytics and monitoring - Test on different device configurations ## Additional Resources - [CreativeEditor SDK Documentation](https://img.ly/docs/cesdk/android) - [Android Examples Repository](https://github.com/imgly/cesdk-android-examples) - [Android Activity Documentation](https://developer.android.com/guide/components/activities) - [Android Development Guide](https://developer.android.com/guide) --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "New Project Setup" description: "Learn how to integrate the CreativeEditor SDK into a new Android Fragment-based project" platform: android url: "https://img.ly/docs/cesdk/android/get-started/new-fragment-based-ui-project-e8789k/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) > [Quickstart Fragment](https://img.ly/docs/cesdk/android/get-started/new-fragment-based-ui-project-e8789k/) --- This guide shows you how to integrate the CreativeEditor SDK into a new Android Fragment-based project. Learn how to: - **create** a new project. - **add** the necessary dependencies. - **configure** the editor. - **test** the integration. ## Who Is This Guide For? This guide is for developers who: - Have experience with **Android** development and **Kotlin** - Want to create a **new Android Fragment**-based project with integrated creative editing capabilities - Need to implement user-friendly editing interfaces - Want to add professional-grade image editing, design creation, and video editing to their Android apps - Prefer using **traditional Android Views** with Fragment-based architecture ## What You'll Achieve By following this guide, you: - Create a new Android Fragment-based project with CreativeEditor SDK integration - Configure platform-specific requirements for Android - Implement a functional editor that you can launch from your app - Test and verify the integration works correctly [Explore Android Demos](https://img.ly/showcases/cesdk/?tags=android) [View on GitHub](https://github.com/imgly/cesdk-android-examples) ## Prerequisites Before you begin, ensure you have the following requirements: ### Development Environment - **Android Studio**: Latest version (Hedgehog or later) - **Kotlin**: 1.9.10 or later - **Gradle**: 8.4 or later - **Git CLI** for version control ### Platform Requirements - **Android**: 7.0+ (API level 24+) - **Minimum SDK**: 24 - **Target SDK**: Latest stable version ### License - A valid **CE.SDK license key** ([Get a free trial](https://img.ly/forms/free-trial)), use `null` or an empty string to run in evaluation mode with watermark. ### Verify Your Setup Run the following command to verify your Android development environment: ```bash gradle --version ``` This command checks your Gradle installation and reports any issues to resolve before proceeding. > **Note:** You can customize the CreativeEditor SDK for Android exclusively through > native code (Kotlin), as described in the > [configuration overview section](https://img.ly/docs/cesdk/android/user-interface/customization-72b2f8/). ## Step 1: Create a New Android Fragment-Based Project First, verify your Android Studio installation and create a new project: 1. **Open Android Studio** and select "New Project" 2. **Choose "Empty Views Activity"** template 3. **Configure your project**: - Name: `cesdk_android_fragment_app` - Package name: `com.example.cesdkfragmentapp` - Language: **Kotlin** - Minimum SDK: **API 24 (Android 7.0)** - Build configuration language: **Kotlin DSL** ### Project Structure Your new project should have this structure: ``` cesdk_android_fragment_app/ ├── app/ # Main application module │ ├── src/main/ │ │ ├── java/ # Kotlin source files │ │ ├── res/ # Resources │ │ └── AndroidManifest.xml │ ├── build.gradle.kts # App-level build configuration │ └── proguard-rules.pro # ProGuard rules ├── gradle/ # Gradle wrapper ├── build.gradle.kts # Project-level build configuration ├── settings.gradle.kts # Project settings └── gradle.properties # Gradle properties ``` ## Step 2: Add the CreativeEditor SDK Dependency Add the CreativeEditor SDK to your project by updating the build configuration: ### 2.1 Add IMG.LY Repository Update your `settings.gradle.kts` to include the IMG.LY repository: ```kotlin title="settings.gradle.kts" dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() maven { name = "IMG.LY Artifactory" url = uri("https://artifactory.img.ly/artifactory/maven") mavenContent { includeGroup("ly.img") } } } } ``` ### 2.2 Add Editor Dependency Update your `app/build.gradle.kts` to include the editor dependency: ```kotlin title="build.gradle.kts" dependencies { implementation("ly.img:editor:1.57.0") // Required dependencies for CE.SDK (includes Compose internally) implementation("androidx.appcompat:appcompat:1.7.0") implementation("androidx.fragment:fragment-ktx:1.8.5") implementation("androidx.activity:activity-compose:1.9.3") implementation("androidx.compose.ui:ui:1.7.6") implementation("androidx.compose.material3:material3:1.3.1") // Fragment dependencies implementation("androidx.navigation:navigation-fragment-ktx:2.8.4") implementation("androidx.navigation:navigation-ui-ktx:2.8.4") // Other Android dependencies implementation("androidx.core:core-ktx:1.12.0") implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.7.0") implementation("com.google.android.material:material:1.11.0") } ``` ### 2.3 Configure Android Settings Ensure your `app/build.gradle.kts` has the correct Android configuration: ```kotlin title="build.gradle.kts" android { namespace = "com.example.cesdkfragmentapp" compileSdk = 34 defaultConfig { minSdk = 24 targetSdk = 34 } buildFeatures { viewBinding = true } kotlinOptions { jvmTarget = "17" } packaging { resources { excludes += "/META-INF/{AL2.0,LGPL2.1}" } } } ``` ### 2.4 Sync Project After adding the dependency, sync your project to download the CreativeEditor SDK: In Android Studio, click **Sync Project with Gradle Files** to download and configure all dependencies. This downloads and installs the CreativeEditor SDK and its dependencies automatically through Gradle. ## Step 3: Implement the Editor Integration ### 3.1 Create Editor Fragment Create a new Kotlin file (for example, `EditorFragment.kt`) in your app module's main source set (typically `app/src/main/java/com/yourpackage/`): ```kotlin file=@cesdk_android_examples/editor-guides-quickstart/EditorFragment.kt import android.os.Bundle import android.view.LayoutInflater import android.view.View import android.view.ViewGroup import androidx.compose.ui.platform.ComposeView import androidx.fragment.app.Fragment import ly.img.editor.DesignEditor import ly.img.editor.EngineConfiguration import ly.img.editor.rememberForDesign class EditorFragment : Fragment() { override fun onCreateView( inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?, ): View = ComposeView(requireContext()).apply { setContent { val engineConfiguration = EngineConfiguration.rememberForDesign( // Get your license from https://img.ly/forms/free-trial // pass null or empty for evaluation mode with watermark license = "", userId = "", // A unique string to identify your user/session ) DesignEditor( engineConfiguration = engineConfiguration, onClose = { // Close the editor here parentFragmentManager.popBackStack() }, ) } } } ``` ### 3.2 Update MainActivity Modify your existing `MainActivity.kt` file (located in `app/src/main/java/com/yourpackage/`) to host the fragment: ```kotlin title="MainActivity.kt" import android.os.Bundle import androidx.appcompat.app.AppCompatActivity import androidx.fragment.app.Fragment import com.example.cesdkfragmentapp.databinding.ActivityMainBinding class MainActivity : AppCompatActivity() { private lateinit var binding: ActivityMainBinding override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) binding = ActivityMainBinding.inflate(layoutInflater) setContentView(binding.root) binding.launchEditorButton.setOnClickListener { launchEditorFragment() } } private fun launchEditorFragment() { val editorFragment = EditorFragment() supportFragmentManager.beginTransaction() .replace(R.id.fragmentContainer, editorFragment) .addToBackStack(null) .commit() } } ``` ### 3.3 Update Layout File Update your `activity_main.xml` to include a button and fragment container: ```xml title="activity_main.xml" ``` ### 3.4 Add Required Permissions Update your `AndroidManifest.xml` to include necessary permissions: ```xml title="AndroidManifest.xml" ``` ## Step 4: Test Your Editor Integration ### 4.1 Build and Run Build your Android project using Gradle: ### 4.2 Test on Android Device ```bash ./gradlew installInternalDebug ``` ### 4.3 Verify Features After launching your app, verify these features work correctly: - **App Launch**: The main activity opens without errors - **Button Interaction**: The "Launch Creative Editor SDK" button responds to taps - **Fragment Navigation**: The editor fragment loads properly - **Editor Launch**: The CreativeEditor SDK opens without errors - **Template Selection**: You can browse and select templates - **Editing Tools**: All editing tools are accessible and functional - **Export**: You can export edited content successfully - **Navigation**: The editor closes properly when finished ### 4.4 Common Test Scenarios - **Photo Editing**: Import and edit photos - **Text Addition**: Add and customize text elements - **Template Usage**: Apply and customize templates - **Export Options**: Test different export formats - **Performance**: Verify smooth operation on target devices ## Step 5: Customize for Your Use Case ### 5.1 Editor Configuration Options The CreativeEditor SDK offers different presets for common use cases: | Editor Type | Use Case | Kotlin Implementation | | ---------------- | ----------------------------- | ------------------------- | | **PhotoEditor** | Photo editing and enhancement | `PhotoEditor` composable | | **DesignEditor** | Graphic design and templates | `DesignEditor` composable | | **VideoEditor** | Video editing and effects | `VideoEditor` composable | ### 5.2 Custom Configuration You can customize the editor behavior: ```kotlin title="EditorFragment.kt" class CustomEditorFragment : Fragment() { override fun onCreateView( inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle? ): View { return ComposeView(requireContext()).apply { setContent { val engineConfiguration = EngineConfiguration.rememberForDesign( license = "", userId = "", // Add custom configuration here ) DesignEditor( engineConfiguration = engineConfiguration, onClose = { requireActivity().supportFragmentManager.popBackStack() }, onExport = { result -> /* Handle export */ } ) } } } } ``` ## Step 6: Troubleshooting ### Common Issues and Solutions #### Gradle Sync Issues - **Problem**: Repository not found - **Solution**: Verify the IMG.LY repository URL in `settings.gradle.kts` #### Compilation Errors - **Problem**: Missing dependencies - **Solution**: Ensure all required dependencies are included #### Runtime Errors - **Problem**: Invalid license - **Solution**: Verify your license key is correct and valid (or pass `null` for evaluation mode with watermark) #### Performance Issues - **Problem**: Slow editor loading - **Solution**: Check device specifications and memory usage #### Integration Issues - **Problem**: Editor not displaying - **Solution**: Verify the fragment is properly added to the fragment manager ## Step 7: Next Steps ### Advanced Features - Implement custom asset sources - Add custom filters and effects - Integrate with your backend services - Implement user authentication ### Other Integrations - Explore camera integration - Add video editing capabilities - Implement batch processing - Add cloud storage integration ### Production Considerations - Optimize for performance - Implement proper error handling - Add analytics and monitoring - Test on different device configurations ## Additional Resources - [CreativeEditor SDK Documentation](https://img.ly/docs/cesdk/android) - [Android Examples Repository](https://github.com/imgly/cesdk-android-examples) - [Android Fragment Documentation](https://developer.android.com/guide/fragments) - [Android Development Guide](https://developer.android.com/guide) --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Android Jetpack Compose New Project Setup" description: "Complete guide to integrate CreativeEditor SDK into a new Android Jetpack Compose project." platform: android url: "https://img.ly/docs/cesdk/android/get-started/new-jetpack-compose-project-c6567i/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) > [Quickstart Jetpack Compose](https://img.ly/docs/cesdk/android/get-started/new-jetpack-compose-project-c6567i/) --- This comprehensive guide walks you through integrating the CreativeEditor SDK (CE.SDK) into a new Android Jetpack Compose project from scratch. By the end, you'll have a fully functional creative editor running in your Android app, ready for: - photo editing - design creation - video processing ## Who Is This Guide For? This guide is for developers who: - Have experience with Android development and Kotlin - Want to create a new Android Jetpack Compose project with integrated creative editing capabilities - Need to implement user-friendly editing interfaces - Want to add professional-grade: - image editing - design creation - video editing to their Android apps - Prefer using Jetpack Compose for modern Android UI development ## What You'll Achieve By following this guide, you: - Create a new Android Jetpack Compose project with CreativeEditor SDK integration - Configure platform-specific requirements for Android - Implement a functional editor that you can launch from your app - Test and verify the integration works correctly [Explore Android Demos](https://img.ly/showcases/cesdk/?tags=android) [View on GitHub](https://github.com/imgly/cesdk-android-examples) ## Prerequisites Before you begin, ensure you have the following requirements: ### Development Environment - **Android Studio**: Latest version (Hedgehog or later) - **Kotlin**: 1.9.10 or later - **Gradle**: 8.4 or later - **Jetpack Compose**: Latest BOM version - **Git CLI** for version control ### Platform Requirements - **Android**: 7.0+ (API level 24+) - **Minimum SDK**: 24 - **Target SDK**: Latest stable version ### License - A valid **CE.SDK license key** ([Get a free trial](https://img.ly/forms/free-trial)), use `null` or an empty string to run in evaluation mode with watermark. ### Verify Your Setup Run the following command to verify your Android development environment: ```bash gradle --version ``` This command checks your Gradle installation and reports any issues to resolve before proceeding. > **Note:** You can customize the CreativeEditor SDK for Android exclusively through > Kotlin code, as described in the > [configuration overview section](https://img.ly/docs/cesdk/android/user-interface/customization-72b2f8/). ## Step 1: Create a New Android Jetpack Compose Project First, verify your Android Studio installation and create a new project: 1. **Open Android Studio** and select "New Project" 2. **Choose "Empty Activity"** template 3. **Configure your project**: - Name: `cesdk_android_app` - Package name: `com.example.cesdkapp` - Language: **Kotlin** - Minimum SDK: **API 24 (Android 7.0)** - Build configuration language: **Kotlin DSL** ### Project Structure Your new project should have this structure: ``` cesdk_android_app/ ├── app/ # Main application module │ ├── src/main/ │ │ ├── java/ # Kotlin source files │ │ ├── res/ # Resources │ │ └── AndroidManifest.xml │ ├── build.gradle.kts # App-level build configuration │ └── proguard-rules.pro # ProGuard rules ├── gradle/ # Gradle wrapper ├── build.gradle.kts # Project-level build configuration ├── settings.gradle.kts # Project settings └── gradle.properties # Gradle properties ``` ## Step 2: Add the CreativeEditor SDK Dependency Add the CreativeEditor SDK to your project by updating the build configuration: ### 2.1 Add IMG.LY Repository Update your `settings.gradle.kts` to include the IMG.LY repository: ```kotlin title="settings.gradle.kts" dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() maven { name = "IMG.LY Artifactory" url = uri("https://artifactory.img.ly/artifactory/maven") mavenContent { includeGroup("ly.img") } } } } ``` ### 2.2 Add Editor Dependency Update your `app/build.gradle.kts` to include the editor dependency: ```kotlin title="build.gradle.kts" dependencies { implementation("ly.img:editor:1.57.0") // Jetpack Compose dependencies implementation(platform("androidx.compose:compose-bom:2025.04.01")) implementation("androidx.activity:activity-compose") implementation("androidx.compose.ui:ui") implementation("androidx.compose.ui:ui-graphics") implementation("androidx.compose.ui:ui-tooling-preview") implementation("androidx.compose.material3:material3") // Other Android dependencies implementation("androidx.core:core-ktx:1.12.0") implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.7.0") implementation("androidx.activity:activity-compose:1.8.2") } ``` This adds the latest version of the CreativeEditor SDK editor to your `build.gradle.kts` file. ### 2.3 Configure Android Settings Update your `app/build.gradle.kts` to ensure proper configuration: ```kotlin title="build.gradle.kts" android { namespace = "com.example.cesdkapp" compileSdk = 34 defaultConfig { applicationId = "com.example.cesdkapp" minSdk = 24 // Required for CE.SDK targetSdk = 34 versionCode = 1 versionName = "1.0" testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner" vectorDrawables { useSupportLibrary = true } } buildTypes { release { isMinifyEnabled = false proguardFiles( getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro" ) } } compileOptions { sourceCompatibility = JavaVersion.VERSION_17 targetCompatibility = JavaVersion.VERSION_17 } kotlinOptions { jvmTarget = "17" } buildFeatures { compose = true } composeOptions { kotlinCompilerExtensionVersion = "1.5.8" } packaging { resources { excludes += "/META-INF/{AL2.0,LGPL2.1}" } } } ``` ### 2.4 Sync Project After adding the dependency, sync your project to download the CreativeEditor SDK: In Android Studio, click **Sync Project with Gradle Files** to download and configure all dependencies. This downloads and installs the CreativeEditor SDK and its dependencies automatically through Gradle. ## Step 3: Implement the Editor Integration Now let's implement the CreativeEditor SDK editor in your Android Jetpack Compose application: ### 3.1 Create Editor Composable Create a new file `EditorComposable.kt` in your project: ```kotlin file=@cesdk_android_examples/editor-guides-quickstart/EditorComposable.kt import androidx.compose.runtime.Composable import ly.img.editor.DesignEditor import ly.img.editor.EngineConfiguration import ly.img.editor.rememberForDesign @Composable fun EditorComposable() { val engineConfiguration = EngineConfiguration.rememberForDesign( // Get your license from https://img.ly/forms/free-trial // pass null or empty for evaluation mode with watermark license = "", userId = "", // A unique string to identify your user/session ) DesignEditor( engineConfiguration = engineConfiguration, onClose = { // Close the editor here // If using a navigation library, call pop() or navigateUp() here }, ) } ``` ### 3.2 Update MainActivity Update your `MainActivity.kt` to use the editor composable: ```kotlin title="MainActivity.kt" import android.os.Bundle import androidx.activity.ComponentActivity import androidx.activity.compose.setContent import androidx.activity.enableEdgeToEdge import androidx.compose.foundation.layout.fillMaxSize import androidx.compose.material3.MaterialTheme import androidx.compose.material3.Surface import androidx.compose.ui.Modifier class MainActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) enableEdgeToEdge() setContent { MaterialTheme { Surface( modifier = Modifier.fillMaxSize(), color = MaterialTheme.colorScheme.background ) { EditorComposable() } } } } } ``` ### 3.3 Add Required Permissions Add the necessary permissions to your `AndroidManifest.xml`: ```xml title="AndroidManifest.xml" ``` ## Step 4: Test Your Editor Integration Now let's test your CreativeEditor SDK editor integration: ### 4.1 Build and Run Build your Android project using Gradle: ### 4.2 Test on Android Device Connect your Android device and run: ```bash # Build and install the app ./gradlew installDebug # Or run from Android Studio # Click the "Run" button (green play icon) ``` ### 4.3 Verify Features When the app launches successfully, you should see: 1. **Main Screen**: A clean Android Jetpack Compose interface 2. **Editor Launch**: The CreativeEditor SDK editor should open immediately 3. **Editor Features**: You should be able to access: - photo editing tools - design creation tools - video editing capabilities 4. **User Interface**: The editor should have a complete UI with: - toolbar with editing tools - canvas for design work - panels for assets and properties ### 4.4 Common Test Scenarios Test these scenarios to ensure everything works: - **Editor Launch**: Verify the editor opens properly - **Tool Access**: Test that all editing tools are accessible - **Media Import**: Import photos from your device gallery - **Basic Editing**: Try basic editing features like: - filters and effects - text addition and styling - shape and graphic tools - **Save/Export**: Test saving and exporting edited content - **Navigation**: Ensure proper navigation within the editor > **Note**: The first build may take several minutes as it compiles all native dependencies. Subsequent builds are faster. ## Step 5: Customize for Your Use Case The CreativeEditor SDK editor offers different presets for common use cases: ### 5.1 Editor Configuration Options #### Available Editor Types Summary The CreativeEditor SDK provides several editor types for different use cases: | Editor Type | Description | Use Case | | ---------------- | --------------------------- | ----------------------------------- | | `DesignEditor` | Full-featured design editor | General design creation and editing | | `PhotoEditor` | Photo editing focused | Image enhancement and photo editing | | `VideoEditor` | Video editing focused | Video processing and editing | | `ApparelEditor` | Apparel design focused | T-shirt and merchandise design | | `PostcardEditor` | Postcard design focused | Greeting cards and postcards | **Available Editor Types with Parameters:** | Editor Type | Parameters | Use Case | | --------------------- | ----------------------------------------------------------- | ----------------------- | | `rememberForDesign` | license, userId, baseUri, sceneUri, renderTarget | General design creation | | `rememberForPhoto` | license, imageUri, imageSize, userId, baseUri, renderTarget | Photo editing | | `rememberForVideo` | license, userId, baseUri, sceneUri, renderTarget | Video editing | | `rememberForApparel` | license, userId, baseUri, sceneUri, renderTarget | T-shirt/apparel design | | `rememberForPostcard` | license, userId, baseUri, sceneUri, renderTarget | Postcard creation | Choose the appropriate editor type based on your use case: ```kotlin title="EditorComposable.kt" // For photo editing @Composable fun PhotoEditorComposable() { val engineConfiguration = EngineConfiguration.rememberForPhoto( license = "", userId = "", ) PhotoEditor( engineConfiguration = engineConfiguration, onClose = { /* handle close */ } ) } // For video editing @Composable fun VideoEditorComposable() { val engineConfiguration = EngineConfiguration.rememberForVideo( license = "", userId = "", ) VideoEditor( engineConfiguration = engineConfiguration, onClose = { /* handle close */ } ) } ``` ### 5.2 Custom Configuration **Note**: Custom configuration features are currently limited in version 1.57.0 for new Jetpack Compose projects. Basic editor types work as expected. You can customize the editor configuration for your specific needs: ```kotlin title="EditorComposable.kt" @Composable fun CustomEditorComposable() { val engineConfiguration = EngineConfiguration.rememberForDesign( license = "", userId = "", // Custom configuration options configuration = { // Configure editor appearance appearance { theme = Theme.DARK primaryColor = Color.Blue } // Configure available tools tools { // Enable/disable specific tools text = true shapes = true filters = true effects = false } // Configure asset sources assets { // Add custom asset sources addImageSource("my-images", "https://my-api.com/images") } } ) DesignEditor( engineConfiguration = engineConfiguration, onClose = { /* handle close */ } ) } ``` ## Step 6: Troubleshooting If you encounter issues, here are common solutions: ### 6.1 Build Issues #### 1. Gradle Sync Errors **Problem**: Gradle sync fails with dependency resolution errors. **Solution**: 1. Check your internet connection 2. Verify the IMG.LY repository URL is correct 3. Clean and rebuild the project: ```bash ./gradlew clean ./gradlew build ``` #### 2. Compilation Errors **Problem**: Kotlin compilation errors related to Compose. **Solution**: Ensure your Compose compiler version matches your Kotlin version. Check the [official compatibility matrix](https://developer.android.com/jetpack/androidx/releases/compose-kotlin). #### 3. Runtime Errors **Problem**: App crashes on startup with editor-related errors. **Solution**: 1. Verify your license key is valid (or pass `null` for evaluation mode with watermark) 2. Check that minSdk is set to 24 or higher 3. Ensure all required permissions are declared in AndroidManifest.xml ### 6.2 Performance Issues #### 1. Slow Editor Loading **Problem**: Editor takes too long to load or is sluggish. **Solution**: 1. Ensure you're running on a device with sufficient GPU capabilities 2. Check that the device has adequate memory 3. Verify the engine configuration is optimized #### 2. Memory Issues **Problem**: App crashes due to memory issues during editing. **Solution**: 1. Implement proper memory management 2. Monitor memory usage during editing operations 3. Use appropriate image sizes and formats ### 6.3 Integration Issues #### 1. Editor Not Displaying **Problem**: Editor doesn't appear or display correctly. **Solution**: 1. Check that the Composable is properly integrated 2. Verify the engine configuration is correct 3. Ensure proper lifecycle management #### 2. Tool Access Issues **Problem**: Editing tools are not accessible or don't work. **Solution**: 1. Check the editor configuration and tool permissions 2. Verify that the license includes the required features 3. Ensure proper asset loading and access ## Step 7: Next Steps Now that you have a basic CreativeEditor SDK editor integration, you can: ### 7.1 Explore Advanced Features - **[Editor Configuration](https://img.ly/docs/cesdk/android/configuration-2c1c3d/)**: Learn advanced editor customization - **[Custom Tools](https://img.ly/docs/cesdk/android/configuration-2c1c3d/)**: Implement custom editing tools - **[Asset Management](https://img.ly/docs/cesdk/android/import-media/concepts-5e6197/)**: Manage and organize media assets - **[Performance Optimization](https://img.ly/docs/cesdk/android/configuration-2c1c3d/)**: Optimize editor performance ### 7.2 Integrate with Other Components - **[Engine Integration](https://img.ly/docs/cesdk/android/engine-interface-6fb7cf/)**: Add custom engine features - **[Camera Integration](https://img.ly/docs/cesdk/android/import-media-4e3703/)**: Capture media directly in your app - **[Navigation Integration](https://img.ly/docs/cesdk/android/user-interface/customization/navigation-bar-4e5d39/)**: Integrate with app navigation ### 7.3 Production Considerations - **License Management**: Implement proper license validation - **Error Handling**: Add comprehensive error handling - **Performance Monitoring**: Monitor editor performance in production - **Testing**: Implement comprehensive testing for editor features ## Additional Resources - **[CreativeEditor SDK Documentation](https://img.ly/docs/cesdk/)** - **[Android Examples Repository](https://github.com/imgly/cesdk-android-examples)** - **[Community Support](https://img.ly/support)** Congratulations! You've successfully integrated the CreativeEditor SDK editor into your Android Jetpack Compose application. Your app now has powerful creative editing capabilities that work seamlessly on Android devices. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Get Started" description: "Start integrating CE.SDK into your application—from understanding the SDK to running your first editor." platform: android url: "https://img.ly/docs/cesdk/android/get-started/overview-e18f40/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) --- Everything you need to integrate CE.SDK into your application. Learn what the SDK offers, get up and running with starter kits, explore AI-powered workflows, and understand our licensing model. ## Next Steps - [What is CE.SDK?](props.paths['2e7acd']) - [Quickstart](props.paths['r1q2w3e']) - [Vibecoding](props.paths['c3014f']) - [Licensing](props.paths['8aa063']) --- ## Related Pages - [Android Creative Editor](https://img.ly/docs/cesdk/android/what-is-cesdk-2e7acd/) - The Android Mobile Design Editor SDK offers a robust and customizable solution for creating and editing visual designs directly within your Android applications. - [Android Jetpack Compose New Project Setup](https://img.ly/docs/cesdk/android/get-started/new-jetpack-compose-project-c6567i/) - Complete guide to integrate CreativeEditor SDK into a new Android Jetpack Compose project. - [New Project Setup](https://img.ly/docs/cesdk/android/get-started/new-activity-based-ui-project-d7678j/) - Learn how to integrate the CreativeEditor SDK into a new Android Activity-based project - [New Project Setup](https://img.ly/docs/cesdk/android/get-started/new-fragment-based-ui-project-e8789k/) - Learn how to integrate the CreativeEditor SDK into a new Android Fragment-based project - [MCP Server](https://img.ly/docs/cesdk/android/get-started/mcp-server-fde71c/) - Connect AI assistants to CE.SDK documentation using the Model Context Protocol (MCP) server. - [LLMs.txt](https://img.ly/docs/cesdk/android/llms-txt-eb9cc5/) - Our documentation is available in LLMs.txt format - [Licensing](https://img.ly/docs/cesdk/android/licensing-8aa063/) - Understand CE.SDK’s flexible licensing, trial options, and how keys work across dev, staging, and production. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Guides" description: "Documentation for Guides" platform: android url: "https://img.ly/docs/cesdk/android/guides-8d8b00/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) --- --- ## Related Pages - [Configuration](https://img.ly/docs/cesdk/android/configuration-2c1c3d/) - Learn how to configure CE.SDK to match your application's functional, visual, and performance requirements. - [Settings](https://img.ly/docs/cesdk/android/settings-970c98/) - Explore all configurable editor settings and learn how to read, update, and observe them via the Settings API. - [Serve Assets From Your Server](https://img.ly/docs/cesdk/android/serve-assets-b0827c/) - Set up and manage how assets are served to the editor, including local, remote, or CDN-based delivery. - [Engine Interface](https://img.ly/docs/cesdk/android/engine-interface-6fb7cf/) - Understand CE.SDK's architecture and learn when to use direct Engine access for automation workflows - [Automate Workflows](https://img.ly/docs/cesdk/android/automation-715209/) - Automate repetitive editing tasks using CE.SDK’s headless APIs to generate assets at scale. - [User Interface](https://img.ly/docs/cesdk/android/user-interface-5a089a/) - Use CE.SDK’s customizable, production-ready UI or replace it entirely with your own interface. - [Open the Editor](https://img.ly/docs/cesdk/android/open-the-editor-23a1db/) - Learn how to load and create scenes, set the zoom level, and configure file proxies or URI resolvers. - [Insert Media Into Scenes](https://img.ly/docs/cesdk/android/insert-media-a217f5/) - Understand how insertion works, how inserted media behave within scenes, and how to control them via UI or code. - [Import Media](https://img.ly/docs/cesdk/android/import-media-4e3703/) - Learn how to import, manage, and customize assets from local, remote, or camera sources in CE.SDK. - [Export](https://img.ly/docs/cesdk/android/export-save-publish/export-82f968/) - Explore export options, supported formats, and configuration features for sharing or rendering output. - [Save](https://img.ly/docs/cesdk/android/export-save-publish/save-c8b124/) - Save design progress locally or to a backend service to allow for later editing or publishing. - [Store Custom Metadata](https://img.ly/docs/cesdk/android/export-save-publish/store-custom-metadata-337248/) - Attach and persist metadata alongside your design, such as tags, version info, or creator details. - [Edit Image](https://img.ly/docs/cesdk/android/edit-image-c64912/) - Use CE.SDK to crop, transform, annotate, or enhance images with editing tools and programmatic APIs. - [Create Videos](https://img.ly/docs/cesdk/android/create-video-c41a08/) - Learn how to create and customize videos in CE.SDK using scenes, assets, and timeline-based editing. - [Text](https://img.ly/docs/cesdk/android/text-8a993a/) - Add, style, and customize text layers in your design using CE.SDK’s flexible text editing tools. - [Create and Edit Shapes](https://img.ly/docs/cesdk/android/shapes-9f1b2c/) - Draw custom vector shapes, combine them with boolean operations, and insert QR codes into your designs. - [Create and Edit Stickers](https://img.ly/docs/cesdk/android/stickers-3d4e5f/) - Create and customize stickers using image fills for icons, logos, emoji, and multi-color graphics. - [Create Compositions](https://img.ly/docs/cesdk/android/create-composition-db709c/) - Combine and arrange multiple elements to create complex, multi-page, or layered design compositions. - [Create Templates](https://img.ly/docs/cesdk/android/create-templates-3aef79/) - Learn how to create, import, and manage reusable templates to streamline design creation in CE.SDK. - [Colors](https://img.ly/docs/cesdk/android/colors-a9b79c/) - Manage color usage in your designs, from applying brand palettes to handling print and screen formats. - [Fills](https://img.ly/docs/cesdk/android/fills-402ddc/) - Apply solid colors, gradients, images, or videos as fills to shapes, text, and other design elements. - [Outlines](https://img.ly/docs/cesdk/android/outlines-b7820c/) - Enhance design elements with strokes, shadows, and glow effects to improve contrast and visual appeal. - [Filters and Effects](https://img.ly/docs/cesdk/android/filters-and-effects-6f88ac/) - Enhance visual elements with filters and effects such as blur, duotone, LUTs, and chroma keying. - [Animation](https://img.ly/docs/cesdk/android/animation-ce900c/) - Add motion to designs with support for keyframes, timeline editing, and programmatic animation control. - [Rules](https://img.ly/docs/cesdk/android/rules-1427c0/) - Define and enforce layout, branding, and safety rules to ensure consistent and compliant designs. - [Conversion](https://img.ly/docs/cesdk/android/conversion-c3fbb3/) - Convert designs into different formats such as PDF, PNG, MP4, and more using CE.SDK tools. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "For Audio Processing" description: "Learn how to export audio in WAV or MP4 format from any block type in CE.SDK for Android." platform: android url: "https://img.ly/docs/cesdk/android/guides/export-save-publish/export/audio-68de25/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Export Media Assets](https://img.ly/docs/cesdk/android/export-save-publish/export-82f968/) > [For Audio Processing](https://img.ly/docs/cesdk/android/guides/export-save-publish/export/audio-68de25/) --- Export audio from pages, video blocks, audio blocks, and tracks to WAV or MP4 format for external processing, transcription, or analysis. The `exportAudio` API allows you to extract audio from any block that contains audio content. This is particularly useful when integrating with external audio processing services like speech-to-text transcription, audio enhancement, or music analysis platforms. Audio can be exported from multiple block types: - **Page blocks** - Export the complete mixed audio timeline - **Video blocks** - Extract audio tracks from videos - **Audio blocks** - Export standalone audio content - **Track blocks** - Export audio from specific timeline tracks ## Export Audio Export audio from any block using the `exportAudio` API: ```kotlin val page = engine.scene.getCurrentPage() val audioData = engine.block.exportAudio( page, MimeType.AUDIO_WAV, 48000, 2 ) Log.d("AudioExport", "Exported ${audioData.size} bytes") ``` ### Export Options Configure your audio export with these parameters: - **`mimeType`** - `MimeType.AUDIO_WAV` (uncompressed) or `MimeType.AUDIO_MP4` (compressed AAC) - **`sampleRate`** - Audio quality in Hz (default: 48000) - **`numberOfChannels`** - 1 for mono or 2 for stereo - **`timeOffset`** - Start time in seconds (default: 0f) - **`duration`** - Length to export in seconds (0f = entire duration) - **`onProgress`** - Callback receiving `(rendered, encoded, total)` for progress tracking ## Find Audio Sources To find blocks with audio in your scene: ```kotlin // Find audio blocks val audioBlocks = engine.block.findByType(BlockType.Audio) // Find video fills with audio val videoFills = engine.block.findByType(BlockType.VideoFill) val videosWithAudio = videoFills.filter { block -> try { engine.block.getAudioInfoFromVideo(block).isNotEmpty() } catch (e: Exception) { false } } ``` ## Working with Multi-Track Video Audio Videos can contain multiple audio tracks (e.g., different languages). CE.SDK provides APIs to inspect and extract specific tracks. ### Check audio track count ```kotlin val videoFillId = engine.block.findByType(BlockType.VideoFill).first() val trackCount = engine.block.getAudioTrackCountFromVideo(videoFillId) Log.d("AudioExport", "Video has $trackCount audio track(s)") ``` ### Get track information ```kotlin val audioTracks = engine.block.getAudioInfoFromVideo(videoFillId) audioTracks.forEachIndexed { index, track -> Log.d("AudioExport", """ Track $index: - Channels: ${track.channels} // 1=mono, 2=stereo - Sample Rate: ${track.sampleRate} Hz - Language: ${track.language ?: "unknown"} - Label: ${track.label ?: "Track $index"} """.trimIndent()) } ``` ### Extract a specific track ```kotlin // Create audio block from track 0 (first track) val audioBlockId = engine.block.createAudioFromVideo(videoFillId, 0) // Export just this track's audio val trackAudioData = engine.block.exportAudio( audioBlockId, MimeType.AUDIO_WAV, 48000, 2 ) ``` ### Extract all tracks ```kotlin // Create audio blocks for all tracks val audioBlockIds = engine.block.createAudiosFromVideo(videoFillId) // Export each track audioBlockIds.forEachIndexed { i, audioBlockId -> val trackData = engine.block.exportAudio(audioBlockId, MimeType.AUDIO_WAV) Log.d("AudioExport", "Track $i: ${trackData.size} bytes") } ``` ## Complete Workflow: Audio to Captions A common workflow is to export audio, send it to a transcription service, and use the returned captions in your scene. ### Step 1: Export Audio ```kotlin val page = engine.scene.getCurrentPage() val audioData = engine.block.exportAudio( page, MimeType.AUDIO_WAV, 48000, 2 ) ``` ### Step 2: Send to Transcription Service Send the audio to a service that returns SubRip (SRT) format captions: ```kotlin suspend fun transcribeAudio(audioData: ByteArray): String = withContext(Dispatchers.IO) { val client = OkHttpClient() val requestBody = MultipartBody.Builder() .setType(MultipartBody.FORM) .addFormDataPart( "audio", "audio.wav", audioData.toRequestBody("audio/wav".toMediaType()) ) .addFormDataPart("format", "srt") .build() val request = Request.Builder() .url("https://api.transcription-service.com/transcribe") .addHeader("Authorization", "Bearer YOUR_API_KEY") .post(requestBody) .build() val response = client.newCall(request).execute() response.body?.string() ?: throw Exception("Empty response") } val srtContent = transcribeAudio(audioData) ``` ### Step 3: Import Captions from SRT Use the built-in API to create caption blocks from the SRT response: ```kotlin import java.io.File // Save SRT to temporary file val tempFile = File.createTempFile("captions", ".srt") tempFile.writeText(srtContent) // Import captions from file URI val uri = tempFile.toURI().toString() val captions = engine.block.createCaptionsFromURI(uri) // Clean up temporary file tempFile.delete() // Add captions to page val page = engine.scene.getCurrentPage() val captionTrack = engine.block.create(DesignBlockType.CaptionTrack) captions.forEach { caption -> engine.block.appendChild(captionTrack, caption) } engine.block.appendChild(page, captionTrack) // Center the first caption as a reference point engine.block.alignHorizontally(listOf(captions[0]), HorizontalBlockAlignment.Center) engine.block.alignVertically(listOf(captions[0]), VerticalBlockAlignment.Center) ``` ### Other Processing Services Audio export also supports these workflows: - **Audio enhancement** - Noise removal, normalization - **Music analysis** - Tempo, key, beat detection - **Language detection** - Identify spoken language - **Speaker diarization** - Identify who spoke when ## Next Steps Now that you understand audio export, explore related audio and video features in the [Create Video guides](https://img.ly/docs/cesdk/android/create-video-c41a08/). --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Import Media" description: "Learn how to import, manage, and customize assets from local, remote, or camera sources in CE.SDK." platform: android url: "https://img.ly/docs/cesdk/android/import-media-4e3703/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Import Media Assets](https://img.ly/docs/cesdk/android/import-media-4e3703/) --- --- ## Related Pages - [Overview](https://img.ly/docs/cesdk/android/import-media/overview-84bb23/) - Learn how to import, manage, and customize assets from local, remote, or camera sources in CE.SDK. - [Concepts](https://img.ly/docs/cesdk/android/import-media/concepts-5e6197/) - Understand key asset concepts like sources, formats, metadata, and how assets are integrated into designs. - [Asset Library](https://img.ly/docs/cesdk/android/import-media/asset-library-65d6c4/) - Manage how users browse, preview, and insert media assets into their designs with a customizable asset library. - [Import From Local Source](https://img.ly/docs/cesdk/android/import-media/from-local-source-39b2a9/) - Enable users to upload files from their device for use as design assets in the editor. - [Import From Remote Source](https://img.ly/docs/cesdk/android/import-media/from-remote-source-b65faf/) - Connect CE.SDK to external sources like servers or third-party platforms to import assets remotely. - [Capture From Camera](https://img.ly/docs/cesdk/android/import-media/capture-from-camera-92f388/) - Capture photos or videos directly from a connected camera for immediate use in your design. - [Source Sets](https://img.ly/docs/cesdk/android/import-media/source-sets-5679c8/) - Use multiple versions of an asset to support different resolutions or formats. - [Retrieve Mimetype](https://img.ly/docs/cesdk/android/import-media/retrieve-mimetype-ed13bf/) - Detect the file type of an asset to control how it’s handled or displayed. - [File Format Support](https://img.ly/docs/cesdk/android/import-media/file-format-support-8cdc84/) - Review the supported image, video, and audio formats for importing assets. - [Size Limits](https://img.ly/docs/cesdk/android/import-media/size-limits-c32275/) - Learn about file size restrictions and how to optimize large assets for use in CE.SDK. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Asset Library" description: "Manage how users browse, preview, and insert media assets into their designs with a customizable asset library." platform: android url: "https://img.ly/docs/cesdk/android/import-media/asset-library-65d6c4/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Import Media Assets](https://img.ly/docs/cesdk/android/import-media-4e3703/) > [Asset Library](https://img.ly/docs/cesdk/android/import-media/asset-library-65d6c4/) --- --- ## Related Pages - [Customize](https://img.ly/docs/cesdk/android/import-media/asset-panel/customize-c9a4de/) - Adapt the asset library UI and behavior to suit your application’s structure and user needs. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Customize" description: "Adapt the asset library UI and behavior to suit your application’s structure and user needs." platform: android url: "https://img.ly/docs/cesdk/android/import-media/asset-panel/customize-c9a4de/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Import Media Assets](https://img.ly/docs/cesdk/android/import-media-4e3703/) > [Asset Library](https://img.ly/docs/cesdk/android/import-media/asset-library-65d6c4/) > [Customize](https://img.ly/docs/cesdk/android/import-media/asset-panel/customize-c9a4de/) --- ```kotlin file=@cesdk_android_examples/editor-guides-configuration-asset-library/AssetLibraryEditorSolution.kt reference-only import androidx.compose.runtime.Composable import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EngineConfiguration import ly.img.editor.core.library.AssetLibrary import ly.img.editor.rememberForDesign // Add this composable to your NavHost @Composable fun AssetLibraryEditorSolution(navController: NavHostController) { val engineConfiguration = EngineConfiguration.rememberForDesign( license = "", // pass null or empty for evaluation mode with watermark ) val editorConfiguration = EditorConfiguration.rememberForDesign( assetLibrary = AssetLibrary.getDefault(), ) DesignEditor( engineConfiguration = engineConfiguration, editorConfiguration = editorConfiguration, ) { // You can set result here navController.popBackStack() } } ``` ```kotlin file=@cesdk_android_examples/editor-guides-configuration-asset-library/DefaultAssetLibraryEditorSolution.kt reference-only import androidx.compose.runtime.Composable import androidx.compose.runtime.remember import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EditorDefaults import ly.img.editor.EngineConfiguration import ly.img.editor.core.library.AssetLibrary import ly.img.editor.core.library.AssetType import ly.img.editor.core.library.LibraryCategory import ly.img.editor.core.library.LibraryContent import ly.img.editor.core.library.addSection import ly.img.editor.core.library.data.AssetSourceType import ly.img.editor.core.library.dropSection import ly.img.editor.core.library.replaceSection import ly.img.editor.rememberForDesign import ly.img.editor.smoketests.R // Add this composable to your NavHost @Composable fun DefaultAssetLibraryEditorSolution(navController: NavHostController) { val unsplashAssetSource = remember { UnsplashAssetSource("") } val engineConfiguration = EngineConfiguration.remember( license = "", // pass null or empty for evaluation mode with watermark onCreate = { EditorDefaults.onCreate( engine = editorContext.engine, sceneUri = EngineConfiguration.defaultDesignSceneUri, eventHandler = editorContext.eventHandler, ) { _, _ -> editorContext.engine.asset.addSource(unsplashAssetSource) } }, ) val assetLibrary = remember { val unsplashSection = LibraryContent.Section( titleRes = R.string.unsplash, sourceTypes = listOf(AssetSourceType(sourceId = unsplashAssetSource.sourceId)), assetType = AssetType.Image, ) AssetLibrary.getDefault( tabs = listOf( AssetLibrary.Tab.IMAGES, AssetLibrary.Tab.SHAPES, AssetLibrary.Tab.STICKERS, AssetLibrary.Tab.TEXT, ), images = LibraryCategory.Images .replaceSection(index = 0) { // We replace the title: "Image Uploads" -> "Uploads" copy(titleRes = R.string.uploads) } .dropSection(index = 1) .addSection(unsplashSection), ) } val editorConfiguration = EditorConfiguration.rememberForDesign( assetLibrary = assetLibrary, ) DesignEditor( engineConfiguration = engineConfiguration, editorConfiguration = editorConfiguration, ) { // You can set result here navController.popBackStack() } } ``` ```kotlin file=@cesdk_android_examples/editor-guides-configuration-asset-library/CustomAssetLibraryEditorSolution.kt reference-only import androidx.compose.runtime.Composable import androidx.compose.runtime.remember import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EditorDefaults import ly.img.editor.EngineConfiguration import ly.img.editor.core.R import ly.img.editor.core.iconpack.IconPack import ly.img.editor.core.iconpack.LibraryElements import ly.img.editor.core.library.AssetLibrary import ly.img.editor.core.library.AssetType import ly.img.editor.core.library.LibraryCategory import ly.img.editor.core.library.LibraryCategory.Companion.sourceTypes import ly.img.editor.core.library.LibraryContent import ly.img.editor.core.library.addSection import ly.img.editor.core.library.data.AssetSourceType import ly.img.editor.rememberForDesign import ly.img.editor.smoketests.R as SmokeTestR // Add this composable to your NavHost @Composable fun CustomAssetLibraryEditorSolution(navController: NavHostController) { val unsplashAssetSource = remember { UnsplashAssetSource("") } val engineConfiguration = EngineConfiguration.remember( license = "", // pass null or empty for evaluation mode with watermark onCreate = { EditorDefaults.onCreate( engine = editorContext.engine, sceneUri = EngineConfiguration.defaultDesignSceneUri, eventHandler = editorContext.eventHandler, ) { _, _ -> editorContext.engine.asset.addSource(unsplashAssetSource) } }, ) val assetLibrary = remember { // We create a custom tab with title "My Assets" that contains 2 sections: // 1. Stickers - expanding it opens the default stickers content // 2. Text - expanding it opens the default text content. Note that the title is skipped. val myAssetsCategory = LibraryCategory( tabTitleRes = SmokeTestR.string.my_assets, tabSelectedIcon = IconPack.LibraryElements, tabUnselectedIcon = IconPack.LibraryElements, content = LibraryContent.Sections( titleRes = SmokeTestR.string.my_assets, sections = listOf( LibraryContent.Section( titleRes = R.string.ly_img_editor_asset_library_title_stickers, sourceTypes = LibraryContent.Stickers.sourceTypes, assetType = AssetType.Sticker, expandContent = LibraryContent.Stickers, ), LibraryContent.Section( sourceTypes = LibraryContent.Text.sourceTypes, assetType = AssetType.Text, expandContent = LibraryContent.Text, ), ), ), ) AssetLibrary( tabs = { listOf( myAssetsCategory, LibraryCategory.Images, ) }, images = { val unsplashSection = LibraryContent.Section( titleRes = SmokeTestR.string.unsplash, sourceTypes = listOf(AssetSourceType(sourceId = unsplashAssetSource.sourceId)), assetType = AssetType.Image, ) // See how the images is different in tabs and here LibraryCategory.Images.addSection(unsplashSection) }, ) } val editorConfiguration = EditorConfiguration.rememberForDesign( assetLibrary = assetLibrary, ) DesignEditor( engineConfiguration = engineConfiguration, editorConfiguration = editorConfiguration, ) { // You can set result here navController.popBackStack() } } ``` In this example, we will show you how to customize the asset library for the mobile editor. The example is based on the `Design Editor`, however, it is exactly the same for all the other [solutions](https://img.ly/docs/cesdk/android/prebuilt-solutions-d0ed07/). Explore a full code sample on [GitHub](https://github.com/imgly/cesdk-swift-examples/tree/v$UBQ_VERSION$/editor-guides-configuration-asset-library/). ## Configuration Asset library configuration is part of the `EditorConfiguration` class. Use the `EditorConfiguration.getDefault` helper function to make asset library configurations. - `assetLibrary` - the asset library UI definition used by the editor. It defines the content of the tabs when floating action button is clicked as well as the content of sheets when images and stickers are replaced. By default, `AssetLibrary.getDefault()` is used. ```kotlin highlight-configuration-asset-library val editorConfiguration = EditorConfiguration.rememberForDesign( assetLibrary = AssetLibrary.getDefault(), ) ``` ### Custom Asset Source To use custom asset sources in the asset library UI, the custom asset source must be first added to the engine. In addition to creating or loading a scene, registering the asset sources should be done in the [callback](https://img.ly/docs/cesdk/android/user-interface/events-514b70/). In this example, the `EditorDefaults.onCreate` default implementation is used and afterwards, the [custom](https://img.ly/docs/cesdk/android/import-media/from-remote-source/unsplash-8f31f0/) is added. ```kotlin highlight-configuration-custom-asset-source val unsplashAssetSource = remember { UnsplashAssetSource("") } val engineConfiguration = EngineConfiguration.remember( license = "", // pass null or empty for evaluation mode with watermark onCreate = { EditorDefaults.onCreate( engine = editorContext.engine, sceneUri = EngineConfiguration.defaultDesignSceneUri, eventHandler = editorContext.eventHandler, ) { _, _ -> editorContext.engine.asset.addSource(unsplashAssetSource) } }, ) ``` ### Default Asset Library `AssetLibrary.getDefault()` provides a simple API in case you want to reorder/drop predefined tabs, as well as adjust the content of the tabs. In this example, firstly, we drop the `Elements` tab and reorder the remaining ones and secondly, we manipulate the sections of the `images` tab by dropping, swapping and appending sections. Note that we append the section based on the `UnsplashAssetSource` shown above. ```kotlin highlight-configuration-default-asset-library val assetLibrary = remember { val unsplashSection = LibraryContent.Section( titleRes = R.string.unsplash, sourceTypes = listOf(AssetSourceType(sourceId = unsplashAssetSource.sourceId)), assetType = AssetType.Image, ) AssetLibrary.getDefault( tabs = listOf( AssetLibrary.Tab.IMAGES, AssetLibrary.Tab.SHAPES, AssetLibrary.Tab.STICKERS, AssetLibrary.Tab.TEXT, ), images = LibraryCategory.Images .replaceSection(index = 0) { // We replace the title: "Image Uploads" -> "Uploads" copy(titleRes = R.string.uploads) } .dropSection(index = 1) .addSection(unsplashSection), ) } val editorConfiguration = EditorConfiguration.rememberForDesign( assetLibrary = assetLibrary, ) ``` ### Custom Asset Library In case you want to adjust the asset library even further (i.e. create your own completely custom tabs, use different `images` category in FAB and replace sheets etc), you should use the constructor of the `AssetLibrary` instead of the helper `AssetLibrary.getDefault()` function. In this example, firstly, we fill the tabs with a custom `My Assets` tab as well as with the default `images` tab and secondly, we use a different `images` category for the replace sheet, which contains the default `images` + `UnsplashAssetSource` section. ```kotlin highlight-configuration-custom-asset-library val assetLibrary = remember { // We create a custom tab with title "My Assets" that contains 2 sections: // 1. Stickers - expanding it opens the default stickers content // 2. Text - expanding it opens the default text content. Note that the title is skipped. val myAssetsCategory = LibraryCategory( tabTitleRes = SmokeTestR.string.my_assets, tabSelectedIcon = IconPack.LibraryElements, tabUnselectedIcon = IconPack.LibraryElements, content = LibraryContent.Sections( titleRes = SmokeTestR.string.my_assets, sections = listOf( LibraryContent.Section( titleRes = R.string.ly_img_editor_asset_library_title_stickers, sourceTypes = LibraryContent.Stickers.sourceTypes, assetType = AssetType.Sticker, expandContent = LibraryContent.Stickers, ), LibraryContent.Section( sourceTypes = LibraryContent.Text.sourceTypes, assetType = AssetType.Text, expandContent = LibraryContent.Text, ), ), ), ) AssetLibrary( tabs = { listOf( myAssetsCategory, LibraryCategory.Images, ) }, images = { val unsplashSection = LibraryContent.Section( titleRes = SmokeTestR.string.unsplash, sourceTypes = listOf(AssetSourceType(sourceId = unsplashAssetSource.sourceId)), assetType = AssetType.Image, ) // See how the images is different in tabs and here LibraryCategory.Images.addSection(unsplashSection) }, ) } val editorConfiguration = EditorConfiguration.rememberForDesign( assetLibrary = assetLibrary, ) ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Capture From Camera" description: "Capture photos or videos directly from a connected camera for immediate use in your design." platform: android url: "https://img.ly/docs/cesdk/android/import-media/capture-from-camera-92f388/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Import Media Assets](https://img.ly/docs/cesdk/android/import-media-4e3703/) > [Capture From Camera](https://img.ly/docs/cesdk/android/import-media/capture-from-camera-92f388/) --- --- ## Related Pages - [Integrate Mobile Camera](https://img.ly/docs/cesdk/android/import-media/capture-from-camera/integrate-33d863/) - Enable live camera capture in mobile apps to shoot and insert photos or video. - [Mobile Camera Configuration](https://img.ly/docs/cesdk/android/import-media/capture-from-camera/camera-configuration-46afd0/) - Set up camera permissions, quality, and behavior when capturing within CE.SDK. - [Record Video](https://img.ly/docs/cesdk/android/import-media/capture-from-camera/record-video-47819b/) - Record video directly inside the editor using a connected camera device. - [Access Recordings](https://img.ly/docs/cesdk/android/import-media/capture-from-camera/recordings-c2ca1e/) - Manage access to recorded videos or reactions for playback or editing. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Mobile Camera Configuration" description: "Set up camera permissions, quality, and behavior when capturing within CE.SDK." platform: android url: "https://img.ly/docs/cesdk/android/import-media/capture-from-camera/camera-configuration-46afd0/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Import Media Assets](https://img.ly/docs/cesdk/android/import-media-4e3703/) > [Capture From Camera](https://img.ly/docs/cesdk/android/import-media/capture-from-camera-92f388/) > [Camera Configuration](https://img.ly/docs/cesdk/android/import-media/capture-from-camera/camera-configuration-46afd0/) --- ```kotlin file=@cesdk_android_examples/camera-guides-configuration/ConfiguredCameraActivity.kt reference-only import android.os.Bundle import android.util.Log import androidx.activity.compose.rememberLauncherForActivityResult import androidx.activity.compose.setContent import androidx.appcompat.app.AppCompatActivity import androidx.compose.material3.Button import androidx.compose.material3.Text import androidx.compose.ui.graphics.Color import ly.img.camera.core.CameraConfiguration import ly.img.camera.core.CameraMode import ly.img.camera.core.CaptureVideo import ly.img.camera.core.EngineConfiguration import kotlin.time.Duration.Companion.seconds private const val TAG = "ConfiguredCameraActivity" class ConfiguredCameraActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val cameraInput = CaptureVideo.Input( engineConfiguration = EngineConfiguration( license = "", // pass null or empty for evaluation mode with watermark userId = "", ), cameraConfiguration = CameraConfiguration( recordingColor = Color.Blue, maxTotalDuration = 30.seconds, allowExceedingMaxDuration = false, ), cameraMode = CameraMode.Standard(), ) setContent { val cameraLauncher = rememberLauncherForActivityResult(contract = CaptureVideo()) { result -> result ?: run { Log.d(TAG, "Camera dismissed") return@rememberLauncherForActivityResult } Log.d(TAG, "Result: $result") } Button( onClick = { cameraLauncher.launch(cameraInput) }, ) { Text(text = "Open Camera") } } } } ``` In this example, we will show you how to configure the camera. ## EngineConfiguration All the basic engine configuration settings are part of the `EngineConfiguration` which are required to initialize the camera. ```kotlin highlight-engine-configuration engineConfiguration = EngineConfiguration( license = "", // pass null or empty for evaluation mode with watermark userId = "", ), ``` - `license` – the license to activate the [Engine](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) with. ```kotlin highlight-license license = "", // pass null or empty for evaluation mode with watermark ``` - `userID` – an optional unique ID tied to your application's user. This helps us accurately calculate monthly active users (MAU). Especially useful when one person uses the app on multiple devices with a sign-in feature, ensuring they're counted once. Providing this aids in better data accuracy. The default value is `null`. ```kotlin highlight-userId userId = "", ``` ## CameraConfiguration You can optionally pass a `CameraConfiguration` object to the `CaptureVideo.Input` constructor to customise the camera experience and behaviour. ```kotlin highlight-camera-configuration cameraConfiguration = CameraConfiguration( recordingColor = Color.Blue, maxTotalDuration = 30.seconds, allowExceedingMaxDuration = false, ), ``` - `recordingColor` – the color of the record button. ```kotlin highlight-recording-color recordingColor = Color.Blue, ``` - `maxTotalDuration` – the total duration that the camera is allowed to record. ```kotlin highlight-max-duration maxTotalDuration = 30.seconds, ``` - `allowExceedingMaxDuration` – Set to `true` to allow exceeding the `maxTotalDuration`. ```kotlin highlight-allow-exceeding-max-duration allowExceedingMaxDuration = false, ``` ## Mode You can optionally configure the initial mode of the camera. ### Available Modes - `Standard`: the regular camera. This is the default. - `Reaction(video, cameraLayoutMode, positionsSwapped)`: records with the camera while playing back a video. - `video` Uri of the video to react to. - `cameraLayoutMode` The layout mode. Available options are `Horizontal` and `Vertical`. - `positionsSwapped` A boolean indicating if the video and camera feed should swap positions. By default, it is false and the video being reacted to is on the top/left (depending on `cameraLayoutMode`) ```kotlin highlight-camera-mode cameraMode = CameraMode.Standard(), ``` ## Full Code Here's the full code: ```kotlin import android.os.Bundle import android.util.Log import androidx.activity.compose.rememberLauncherForActivityResult import androidx.activity.compose.setContent import androidx.appcompat.app.AppCompatActivity import androidx.compose.material3.Button import androidx.compose.material3.Text import androidx.compose.ui.graphics.Color import ly.img.camera.core.CameraConfiguration import ly.img.camera.core.CameraMode import ly.img.camera.core.CaptureVideo import ly.img.camera.core.EngineConfiguration import kotlin.time.Duration.Companion.seconds private const val TAG = "ConfiguredCameraActivity" class ConfiguredCameraActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val cameraInput = CaptureVideo.Input( engineConfiguration = EngineConfiguration( license = "", userId = "", ), cameraConfiguration = CameraConfiguration( recordingColor = Color.Blue, maxTotalDuration = 30.seconds, allowExceedingMaxDuration = false, ), cameraMode = CameraMode.Standard(), ) setContent { val cameraLauncher = rememberLauncherForActivityResult(contract = CaptureVideo()) { result -> result ?: run { Log.d(TAG, "Camera dismissed") return@rememberLauncherForActivityResult } Log.d(TAG, "Result: $result") } Button( onClick = { cameraLauncher.launch(cameraInput) }, ) { Text(text = "Open Camera") } } } } ``` ## Localization The CE.SDK camera currently supports English and German languages on Android, however it provides convenient API to replace the values of existing localization keys or add support for more languages. All the camera keys are located [here](https://github.com/imgly/cesdk-android/blob/v$UBQ_VERSION$/sources/camera-core/src/main/res/values/strings.xml) and they all follow strict naming convention to make locating keys simple and self-explanatory. For instance, the timer off button can be found via `ly_img_camera_timer_option_off` key, or the title in the alert dialog of deleting last recording can be found via `ly_img_camera_dialog_delete_last_recording_title` key. ### Replacing existing keys In order to replace any of the existing camera keys, find the key of the desired text, copy the key to `res/values/strings.xml` file of your app module and replace with the desired value. ### Supporting new languages In order to add support for a language that is not supported by the CE.SDK camera, copy the content of the English localization [file](https://github.com/imgly/cesdk-android/blob/v$UBQ_VERSION$/sources/camera-core/src/main/res/values/strings.xml) to `res/values-{desired-language-code}/strings.xml` file and replace the values with desired translations. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Integrate Mobile Camera" description: "Enable live camera capture in mobile apps to shoot and insert photos or video." platform: android url: "https://img.ly/docs/cesdk/android/import-media/capture-from-camera/integrate-33d863/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Import Media Assets](https://img.ly/docs/cesdk/android/import-media-4e3703/) > [Capture From Camera](https://img.ly/docs/cesdk/android/import-media/capture-from-camera-92f388/) > [Integrate Mobile Camera](https://img.ly/docs/cesdk/android/import-media/capture-from-camera/integrate-33d863/) --- In this example, we will show you how to initialize the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s mobile camera in your Android app. Explore a full code sample on [GitHub](https://github.com/imgly/cesdk-android-examples/tree/v$UBQ_VERSION$/camera-guides-quickstart/). ## Adding dependency Add IMG.LY maven repository to the list of maven urls in the `settings.gradle` file. ``` maven { name "IMG.LY Artifactory" url "https://artifactory.img.ly/artifactory/maven" mavenContent { includeGroup("ly.img") } } ``` Add camera dependency in the `build.gradle` file of your application module. ``` implementation "ly.img:camera:$UBQ_VERSION$" ``` ## Requirements In order to use the mobile camera, your application should meet the following requirements: - `buildFeatures.compose` should be `true`, as the camera is written in Jetpack Compose. ``` buildFeatures { compose true } ``` - `composeOptions.kotlinCompilerExtensionVersion` should match the kotlin version. Use the official compatibility map in [here](https://developer.android.com/jetpack/androidx/releases/compose-kotlin). ``` composeOptions { kotlinCompilerExtensionVersion = "1.5.3" } ``` - `compose-bom` version is `2023.05.01` or higher if your project uses Jetpack Compose dependencies. Note that using lower versions may cause crashes and issues in your own compose code, as our version will override yours. In case you are not using BOM, you can find the BOM to compose library version mapping in [here](https://developer.android.com/jetpack/compose/bom/bom-mapping). ``` implementation(platform("androidx.compose:compose-bom:2023.05.01")) ``` - Kotlin version is 1.9.10 or higher. - `minSdk` is 24 (Android 7) or higher. ``` minSdk 24 ``` By default, the mobile camera supports following ABIs: `arm64-v8a`, `armeabi-v7a`, `x86_64` and `x86`. If you want to filter out some of the ABIs, use `abiFilters`. ``` ndk { abiFilters "arm64-v8a", "armeabi-v7a", "x86_64", "x86" } ``` ## Usage This example shows the basic usage of the camera using the [Activity Result APIs](https://developer.android.com/training/basics/intents/result). In this integration example, on tapping the button, the `ActivityResultLauncher` is launched, presenting the camera `Activity`. ```kotlin cameraLauncher.launch(cameraInput) ``` ### Initialization The camera input is initialized with `EngineConfiguration`. You need to provide the license key that you received from IMG.LY. Optionally, you can provide a unique ID tied to your application's user. This helps us accurately calculate monthly active users (MAU) and it is especially useful when one person uses the app on multiple devices with a sign-in feature, ensuring they're counted once. ```kotlin val cameraInput = CaptureVideo.Input( engineConfiguration = EngineConfiguration( license = "", // or null for evaluation mode with watermark userId = "", ), ) ``` ### CaptureVideo ActivityResultContract Here, we register a request to start the Camera designated by the `CaptureVideo` contract. ```kotlin val cameraLauncher = rememberLauncherForActivityResult(contract = CaptureVideo()) { result -> ``` ### Result The `CaptureVideo` contract's output is a `CameraResult?`. It is `null` when the camera is dismissed by the user and non-null when the user has recorded videos. `CameraResult` is a sealed interface and the result can be obtained by casting it appropriately. ```kotlin result ?: run { Log.d(TAG, "Camera dismissed") return@rememberLauncherForActivityResult } when (result) { is CameraResult.Record -> { val recordedVideoUris = result.recordings.flatMap { it.videos.map { it.uri } } // Do something with the recorded videos Log.d(TAG, "Recorded videos: $recordedVideoUris") } else -> { Log.d(TAG, "Unhandled result") } } ``` That is all. For more than basic configuration, check out all the available [configurations](https://img.ly/docs/cesdk/android/user-interface/customization-72b2f8/). ## Full Code Here's the full code for all 3 files. ### settings.gradle ``` pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } } dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() maven { name "IMG.LY Artifactory" url "https://artifactory.img.ly/artifactory/maven" mavenContent { includeGroup("ly.img") } } } } rootProject.name = "My App" include ':app' ``` ### build.gradle ``` plugins { id 'com.android.application' id 'kotlin-android' } android { namespace "ly.img.editor.showcase" compileSdk 35 defaultConfig { applicationId "ly.img.editor.showcase" minSdk 24 targetSdk 35 versionCode 1 versionName "1.0" ndk { abiFilters "arm64-v8a", "armeabi-v7a", "x86_64", "x86" } } compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 } kotlinOptions { jvmTarget = '1.8' } buildFeatures { compose true } composeOptions { kotlinCompilerExtensionVersion = "1.5.3" } } dependencies { implementation "ly.img:camera:$UBQ_VERSION$" implementation(platform("androidx.compose:compose-bom:2023.05.01")) implementation "androidx.activity:activity-compose:1.8.2" implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3" } ``` ### CameraActivity.kt ```kotlin import android.os.Bundle import android.util.Log import androidx.activity.compose.rememberLauncherForActivityResult import androidx.activity.compose.setContent import androidx.appcompat.app.AppCompatActivity import androidx.compose.material3.Button import androidx.compose.material3.Text import ly.img.camera.core.CameraResult import ly.img.camera.core.CaptureVideo import ly.img.camera.core.EngineConfiguration private const val TAG = "CameraActivity" class CameraActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val cameraInput = CaptureVideo.Input( engineConfiguration = EngineConfiguration( license = "", userId = "", ), ) setContent { val cameraLauncher = rememberLauncherForActivityResult(contract = CaptureVideo()) { result -> result ?: run { Log.d(TAG, "Camera dismissed") return@rememberLauncherForActivityResult } when (result) { is CameraResult.Record -> { val recordedVideoUris = result.recordings.flatMap { it.videos.map { it.uri } } // Do something with the recorded videos Log.d(TAG, "Recorded videos: $recordedVideoUris") } else -> { Log.d(TAG, "Unhandled result") } } } Button( onClick = { cameraLauncher.launch(cameraInput) }, ) { Text(text = "Open Camera") } } } } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Record Video" description: "Record video directly inside the editor using a connected camera device." platform: android url: "https://img.ly/docs/cesdk/android/import-media/capture-from-camera/record-video-47819b/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Import Media Assets](https://img.ly/docs/cesdk/android/import-media-4e3703/) > [Capture From Camera](https://img.ly/docs/cesdk/android/import-media/capture-from-camera-92f388/) > [Record Video](https://img.ly/docs/cesdk/android/import-media/capture-from-camera/record-video-47819b/) --- ```kotlin file=@cesdk_android_examples/engine-guides-using-camera/build.gradle reference-only plugins { id 'com.android.application' id 'kotlin-android' } android { namespace "ly.img.editor.camera" compileSdk 35 defaultConfig { applicationId "ly.img.editor.camera" minSdk 24 targetSdk 35 versionCode 1 versionName "1.0" ndk { abiFilters "arm64-v8a", "armeabi-v7a", "x86_64", "x86" } } compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 } kotlinOptions { jvmTarget = '1.8' } } dependencies { implementation "ly.img:engine-camera:1.70.0" implementation "androidx.camera:camera-core:1.2.3" implementation "androidx.camera:camera-camera2:1.2.3" implementation "androidx.camera:camera-view:1.2.3" implementation "androidx.camera:camera-lifecycle:1.2.3" implementation "androidx.camera:camera-video:1.2.3" implementation "ly.img:engine:1.70.0" implementation "androidx.appcompat:appcompat:1.6.0" implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3" } ``` ```kotlin file=@cesdk_android_examples/engine-guides-using-camera/UsingCamera.kt reference-only import android.view.SurfaceView import androidx.appcompat.app.AppCompatActivity import androidx.camera.core.CameraSelector import androidx.camera.core.MirrorMode import androidx.camera.core.Preview import androidx.camera.lifecycle.ProcessCameraProvider import androidx.camera.video.FileOutputOptions import androidx.camera.video.Quality import androidx.camera.video.QualitySelector import androidx.camera.video.Recorder import androidx.camera.video.VideoCapture import androidx.camera.video.VideoRecordEvent import androidx.core.content.ContextCompat import androidx.core.net.toUri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.delay import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.EffectType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.camera.setCameraPreview import java.io.File fun usingCamera( activity: AppCompatActivity, surfaceView: SurfaceView, cameraProvider: ProcessCameraProvider, license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindSurfaceView(surfaceView) val cameraSelector = CameraSelector.Builder() .requireLensFacing(CameraSelector.LENS_FACING_FRONT) .build() val preview = Preview.Builder().build() val qualitySelector = QualitySelector.from(Quality.FHD) val recorder = Recorder.Builder() .setQualitySelector(qualitySelector) .build() val videoCapture = VideoCapture.Builder(recorder) .setMirrorMode(MirrorMode.MIRROR_MODE_ON_FRONT_ONLY) .build() cameraProvider.bindToLifecycle(activity, cameraSelector, preview, videoCapture) val scene = engine.scene.createForVideo() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) val pixelStreamFill = engine.block.createFill(FillType.PixelStream) engine.block.setFill(block = page, fill = pixelStreamFill) engine.setCameraPreview(pixelStreamFill, preview, mirrored = false) engine.block.appendEffect( block = page, effectBlock = engine.block.createEffect(EffectType.HalfTone), ) // If camerax preview transformation info rotation is 90, this will return Left. If we passed mirrored = true, this would be LeftMirrored. val orientation = engine.block.getEnum( block = pixelStreamFill, property = "fill/pixelStream/orientation", ) val recordingFile = File(surfaceView.context.filesDir, "temp.mp4") val fileOutputOptions = FileOutputOptions.Builder(recordingFile).build() val recording = videoCapture.output .prepareRecording(activity, fileOutputOptions) .start(ContextCompat.getMainExecutor(surfaceView.context)) { if (it !is VideoRecordEvent.Finalize) return@start val videoFill = engine.block.createFill(FillType.Video) engine.block.setFill(block = page, fill = videoFill) engine.block.setString( block = videoFill, property = "fill/video/fileURI", value = recordingFile.toUri().toString(), ) } delay(5000L) recording.stop() } ``` Other than having pre-recorded [video](https://img.ly/docs/cesdk/android/create-video-c41a08/) in your scene you can also have a live preview from a camera in the engine. This allows you to make full use of the engine's capabilities such as [effects](https://img.ly/docs/cesdk/android/filters-and-effects-6f88ac/), [strokes](https://img.ly/docs/cesdk/android/outlines/strokes-c2e621/) and [drop shadows](https://img.ly/docs/cesdk/android/outlines/shadows-and-glows-6610fa/), while the preview integrates with the composition of your scene. Simply swap out the `VideoFill` of a block with a `PixelStreamFill`. This guide shows you how the `PixelStreamFill` can be used in combination with a camera. Before starting the implementation, we are going to need couple more dependencies other than the Engine itself. Camera preview implementation is based on the android library [camerax](https://developer.android.com/training/camerax), therefore, we should include all required camerax dependencies to our project. You can check all available dependencies [here](https://developer.android.com/training/camerax/architecture). Other than camerax, we also need to include the Engine camera extension dependency. This dependency provides API for a single line bridging between camerax and the Engine. It is important that we use camerax version >= 1.1.0 in order to avoid unexpected crashes due to API signature changes. Also, it is highly recommended to always use the exact same version for both `engine` and `engine-camera` dependencies. ```kotlin highlight-dependencies implementation "ly.img:engine-camera:1.70.0" implementation "androidx.camera:camera-core:1.2.3" implementation "androidx.camera:camera-camera2:1.2.3" implementation "androidx.camera:camera-view:1.2.3" implementation "androidx.camera:camera-lifecycle:1.2.3" implementation "androidx.camera:camera-video:1.2.3" ``` Now we have all the required dependencies to work with the camera. We instantiate all required camerax objects in order to start previewing. You can check all available camerax preview configurations [here](https://developer.android.com/training/camerax/architecture). ```kotlin highlight-setupCamera val cameraSelector = CameraSelector.Builder() .requireLensFacing(CameraSelector.LENS_FACING_FRONT) .build() val preview = Preview.Builder().build() val qualitySelector = QualitySelector.from(Quality.FHD) val recorder = Recorder.Builder() .setQualitySelector(qualitySelector) .build() val videoCapture = VideoCapture.Builder(recorder) .setMirrorMode(MirrorMode.MIRROR_MODE_ON_FRONT_ONLY) .build() cameraProvider.bindToLifecycle(activity, cameraSelector, preview, videoCapture) ``` We create a video scene with a single page. Then we create a `PixelStreamFill` and assign it to the page. Then we connect camerax `Preview` and `PixelStreamFill` objects via `setCameraPreview` extension function that is provided by `engine-camera` dependency. To demonstrate the live preview capabilities of the engine we also apply an effect to the page. ```kotlin highlight-setupScene val scene = engine.scene.createForVideo() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) val pixelStreamFill = engine.block.createFill(FillType.PixelStream) engine.block.setFill(block = page, fill = pixelStreamFill) engine.setCameraPreview(pixelStreamFill, preview, mirrored = false) engine.block.appendEffect( block = page, effectBlock = engine.block.createEffect(EffectType.HalfTone), ) ``` ## Orientation To not waste expensive compute time by transforming the pixel data of the buffer itself, it's often beneficial to apply a transformation during rendering and let the GPU handle this work much more efficiently. For this purpose the `PixelStreamFill` has an `orientation` property. You can use it to mirror the image or rotate it in 90° steps. This property lets you easily mirror an image from a front facing camera or rotate the image by 90° when the user holds a device sideways. Note that its initial value is set in `setCameraPreview` based on camerax preview transformation info listener and `mirrored` flag. Available values are `Left`, `LeftMirrored`, `Down`, `DownMirrored`, `Right`, `RightMirrored`, `Up`, `UpMirrored`. ```kotlin highlight-orientation // If camerax preview transformation info rotation is 90, this will return Left. If we passed mirrored = true, this would be LeftMirrored. val orientation = engine.block.getEnum( block = pixelStreamFill, property = "fill/pixelStream/orientation", ) ``` ## Camera Camerax is a very powerful library and it allows video capturing, image capturing and other use cases. Note that the Engine does not limit usage of any of the camerax use cases: it only provides a mechanism to render camera preview into the Engine canvas. For demonstration purposes, we will proceed with video capture. We create a video capture session and start recording the frames into a temporary file in `filesDir`. Once the recording is finished we swap the `PixelStreamFill` with a `VideoFill` to play back the recorded video file. ```kotlin highlight-camera val recordingFile = File(surfaceView.context.filesDir, "temp.mp4") val fileOutputOptions = FileOutputOptions.Builder(recordingFile).build() val recording = videoCapture.output .prepareRecording(activity, fileOutputOptions) .start(ContextCompat.getMainExecutor(surfaceView.context)) { if (it !is VideoRecordEvent.Finalize) return@start val videoFill = engine.block.createFill(FillType.Video) engine.block.setFill(block = page, fill = videoFill) engine.block.setString( block = videoFill, property = "fill/video/fileURI", value = recordingFile.toUri().toString(), ) } delay(5000L) recording.stop() ``` ## Full Code Here's the full code for both files: ### build.gradle ``` plugins { id 'com.android.application' id 'kotlin-android' } android { namespace "ly.img.editor.camera" compileSdk 35 defaultConfig { applicationId "ly.img.editor.camera" minSdk 24 targetSdk 35 versionCode 1 versionName "1.0" ndk { abiFilters "arm64-v8a", "armeabi-v7a", "x86_64", "x86" } } compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 } kotlinOptions { jvmTarget = '1.8' } } dependencies { implementation "ly.img:engine-camera:$UBQ_VERSION$" implementation "androidx.camera:camera-core:1.2.3" implementation "androidx.camera:camera-camera2:1.2.3" implementation "androidx.camera:camera-view:1.2.3" implementation "androidx.camera:camera-lifecycle:1.2.3" implementation "androidx.camera:camera-video:1.2.3" implementation "ly.img:engine:$UBQ_VERSION$" implementation "androidx.appcompat:appcompat:1.6.0" implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3" } ``` ### UsingCamera.kt ```kotlin import android.view.SurfaceView import androidx.appcompat.app.AppCompatActivity import androidx.camera.core.CameraSelector import androidx.camera.core.MirrorMode import androidx.camera.core.Preview import androidx.camera.lifecycle.ProcessCameraProvider import androidx.camera.video.FileOutputOptions import androidx.camera.video.Quality import androidx.camera.video.QualitySelector import androidx.camera.video.Recorder import androidx.camera.video.VideoCapture import androidx.camera.video.VideoRecordEvent import androidx.core.content.ContextCompat import androidx.core.net.toUri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.delay import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.EffectType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.camera.setCameraPreview import java.io.File fun usingCamera( activity: AppCompatActivity, surfaceView: SurfaceView, cameraProvider: ProcessCameraProvider, license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindSurfaceView(surfaceView) val cameraSelector = CameraSelector.Builder() .requireLensFacing(CameraSelector.LENS_FACING_FRONT) .build() val preview = Preview.Builder().build() val qualitySelector = QualitySelector.from(Quality.FHD) val recorder = Recorder.Builder() .setQualitySelector(qualitySelector) .build() val videoCapture = VideoCapture.Builder(recorder) .setMirrorMode(MirrorMode.MIRROR_MODE_ON_FRONT_ONLY) .build() cameraProvider.bindToLifecycle(activity, cameraSelector, preview, videoCapture) val scene = engine.scene.createForVideo() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) val pixelStreamFill = engine.block.createFill(FillType.PixelStream) engine.block.setFill(block = page, fill = pixelStreamFill) engine.setCameraPreview(pixelStreamFill, preview, mirrored = false) engine.block.appendEffect( block = page, effectBlock = engine.block.createEffect(EffectType.HalfTone), ) // If camerax preview transformation info rotation is 90, this will return Left. If we passed mirrored = true, this would be LeftMirrored. val orientation = engine.block.getEnum( block = pixelStreamFill, property = "fill/pixelStream/orientation", ) val recordingFile = File(surfaceView.context.filesDir, "temp.mp4") val fileOutputOptions = FileOutputOptions.Builder(recordingFile).build() val recording = videoCapture.output .prepareRecording(activity, fileOutputOptions) .start(ContextCompat.getMainExecutor(surfaceView.context)) { if (it !is VideoRecordEvent.Finalize) return@start val videoFill = engine.block.createFill(FillType.Video) engine.block.setFill(block = page, fill = videoFill) engine.block.setString( block = videoFill, property = "fill/video/fileURI", value = recordingFile.toUri().toString(), ) } delay(5000L) recording.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Access Recordings" description: "Manage access to recorded videos or reactions for playback or editing." platform: android url: "https://img.ly/docs/cesdk/android/import-media/capture-from-camera/recordings-c2ca1e/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Import Media Assets](https://img.ly/docs/cesdk/android/import-media-4e3703/) > [Capture From Camera](https://img.ly/docs/cesdk/android/import-media/capture-from-camera-92f388/) > [Access Recordings](https://img.ly/docs/cesdk/android/import-media/capture-from-camera/recordings-c2ca1e/) --- ```kotlin file=@cesdk_android_examples/camera-guides-recordings/RecordingsCameraActivity.kt reference-only import android.os.Bundle import android.util.Log import androidx.activity.compose.rememberLauncherForActivityResult import androidx.activity.compose.setContent import androidx.appcompat.app.AppCompatActivity import androidx.compose.material3.Button import androidx.compose.material3.Text import ly.img.camera.core.CameraResult import ly.img.camera.core.CaptureVideo import ly.img.camera.core.EngineConfiguration private const val TAG = "RecordingsCameraActivity" class RecordingsCameraActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val cameraInput = CaptureVideo.Input( engineConfiguration = EngineConfiguration( license = "", // pass null or empty for evaluation mode with watermark userId = "", ), ) setContent { val cameraLauncher = rememberLauncherForActivityResult(contract = CaptureVideo()) { result -> result ?: run { Log.d(TAG, "Camera dismissed") return@rememberLauncherForActivityResult } when (result) { is CameraResult.Record -> { for (recording in result.recordings) { Log.d(TAG, "Duration: ${recording.duration}") for (video in recording.videos) { Log.d(TAG, "Video Uri: ${video.uri} Video Rect: ${video.rect}") } } } is CameraResult.Reaction -> { Log.d(TAG, "Video uri: ${result.video.uri}") for (reaction in result.reaction) { Log.d(TAG, "Duration: ${reaction.duration}") for (video in reaction.videos) { Log.d(TAG, "Video Uri: ${video.uri} Video Rect: ${video.rect}") } } } else -> { Log.d(TAG, "Unhandled result") } } } Button( onClick = { cameraLauncher.launch(cameraInput) }, ) { Text(text = "Open Camera") } } } } ``` Learn how to get the recorded videos from the `CameraResult` type using the Activity Result APIs. ## Success A `Recording` has a `duration` and contains a list of `Video`s. The list contains either one `Video` (for single camera recording) or two `Video`s (for dual camera recordings). > **Note:** Dual camera is currently only available for iOS. Each `Video` has: - A `uri` to the video file that is stored in `Context::getFilesDir()`. Make sure to copy the file to a permanent location if you want to access it later. - A `rect` that contains the position of the video as it was shown in the camera preview. ```kotlin highlight-success when (result) { is CameraResult.Record -> { for (recording in result.recordings) { Log.d(TAG, "Duration: ${recording.duration}") for (video in recording.videos) { Log.d(TAG, "Video Uri: ${video.uri} Video Rect: ${video.rect}") } } } is CameraResult.Reaction -> { Log.d(TAG, "Video uri: ${result.video.uri}") for (reaction in result.reaction) { Log.d(TAG, "Duration: ${reaction.duration}") for (video in reaction.videos) { Log.d(TAG, "Video Uri: ${video.uri} Video Rect: ${video.rect}") } } } else -> { Log.d(TAG, "Unhandled result") } } ``` ### Standard Camera If the user has recorded videos, the `CameraResult.Record` case will contain a list of `Recording`s, each representing a segment of the recorded video. ```kotlin highlight-standard is CameraResult.Record -> { for (recording in result.recordings) { Log.d(TAG, "Duration: ${recording.duration}") for (video in recording.videos) { Log.d(TAG, "Video Uri: ${video.uri} Video Rect: ${video.rect}") } } } ``` ### Video Reaction If the user has recorded a reaction, the `CameraResult.Reaction` case will contain the video that was reacted to and a list of `Recording`s, each representing a segment of the recorded video. ```kotlin highlight-reaction is CameraResult.Reaction -> { Log.d(TAG, "Video uri: ${result.video.uri}") for (reaction in result.reaction) { Log.d(TAG, "Duration: ${reaction.duration}") for (video in reaction.videos) { Log.d(TAG, "Video Uri: ${video.uri} Video Rect: ${video.rect}") } } } ``` ## Failure The result is `null` in case the user dismissed the camera at any point. ```kotlin highlight-failure result ?: run { Log.d(TAG, "Camera dismissed") return@rememberLauncherForActivityResult } ``` ## Full Code Here's the full code: ```kotlin import android.os.Bundle import android.util.Log import androidx.activity.compose.rememberLauncherForActivityResult import androidx.activity.compose.setContent import androidx.appcompat.app.AppCompatActivity import androidx.compose.material3.Button import androidx.compose.material3.Text import ly.img.camera.core.CameraResult import ly.img.camera.core.CaptureVideo import ly.img.camera.core.EngineConfiguration private const val TAG = "RecordingsCameraActivity" class RecordingsCameraActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val cameraInput = CaptureVideo.Input( engineConfiguration = EngineConfiguration( license = "", userId = "", ), ) setContent { val cameraLauncher = rememberLauncherForActivityResult(contract = CaptureVideo()) { result -> result ?: run { Log.d(TAG, "Camera dismissed") return@rememberLauncherForActivityResult } when (result) { is CameraResult.Record -> { for (recording in result.recordings) { Log.d(TAG, "Duration: ${recording.duration}") for (video in recording.videos) { Log.d(TAG, "Video Uri: ${video.uri} Video Rect: ${video.rect}") } } } is CameraResult.Reaction -> { Log.d(TAG, "Video uri: ${result.video.uri}") for (reaction in result.reaction) { Log.d(TAG, "Duration: ${reaction.duration}") for (video in reaction.videos) { Log.d(TAG, "Video Uri: ${video.uri} Video Rect: ${video.rect}") } } } else -> { Log.d(TAG, "Unhandled result") } } } Button( onClick = { cameraLauncher.launch(cameraInput) }, ) { Text(text = "Open Camera") } } } } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Concepts" description: "Understand key asset concepts like sources, formats, metadata, and how assets are integrated into designs." platform: android url: "https://img.ly/docs/cesdk/android/import-media/concepts-5e6197/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Import Media Assets](https://img.ly/docs/cesdk/android/import-media-4e3703/) > [Concepts](https://img.ly/docs/cesdk/android/import-media/concepts-5e6197/) --- ```kotlin reference-only val engine = Engine(id = "ly.img.engine.example") engine.start() engine.bindOffscreen(width = 1080, height = 1920) val coroutineScope = CoroutineScope(Dispatchers.Main) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) val block = engine.block.create(DesignBlockType.Graphic) engine.block.appendChild(parent = scene, child = page) engine.block.appendChild(parent = page, child = block) val source = UnsplashAssetSource() engine.asset.addSource(source) val localSourceId = "LocalSourceId" engine.asset.addLocalSource(localSourceId, supportedMimeTypes = "image/jpeg") val assetSourceIds = engine.asset.findAllSources() // List [ "ly.img.asset.source.unsplash", "LocalSourceId", ... ] engine.asset.onAssetSourceAdded() .onEach { println("Asset source added: id=$it") } .launchIn(coroutineScope) engine.asset.onAssetSourceRemoved() .onEach { println("Asset source removed: id=$it") } .launchIn(coroutineScope) engine.asset.onAssetSourceUpdated() .onEach { println("Asset source updated: id=$it") } .launchIn(coroutineScope) val mimeTypes = engine.asset.getSourceSupportedMimeTypes(sourceId = "ly.img.asset.source.unsplash") val list = engine.asset.findAssets( sourceId = source.sourceId, query = FindAssetsQuery(query = "", page = 1, perPage = 10) ) val sortByNewest = engine.asset.findAssets( sourceId = source.sourceId, query = FindAssetsQuery(query = "", page = 1, perPage = 10, sortingOrder = SortingOrder.DESCENDING) ) val sortById = engine.asset.findAssets( sourceId = source.sourceId, query = FindAssetsQuery(query = "", page = 1, perPage = 10, sortingOrder = SortingOrder.ASCENDING, sortKey = "id") ) val sortByMetaKeyValue = engine.asset.findAssets( sourceId = source.sourceId, query = FindAssetsQuery(query = "", page = 1, perPage = 10, sortingOrder = SortingOrder.ASCENDING, sortKey = "someMetaKey") ) val search = engine.asset.findAssets( sourceId = source.sourceId, query = FindAssetsQuery(query = "banana", page = 1, perPage = 10) ) val documentColors = engine.asset.findAssets( sourceId = "ly.img.scene.colors", query = FindAssetsQuery(query = "", page = 0, perPage = 99999) ) val colorAsset = documentColors.assets[0] engine.asset.applyAssetSourceAsset(sourceId = source.sourceId, asset = list.assets[0]) engine.asset.applyAssetSourceAsset(sourceId = source.sourceId, asset = list.assets[0], block = block) engine.asset.defaultApplyAsset(asset = search.assets[0]) engine.asset.defaultApplyAsset(asset = search.assets[0], block = block) val assetDefinition = AssetDefinition( id = "localAssetId", meta = mapOf( "uri" to "https://example.com/localAssetId.jpg", "thumbUri" to "https://example.com/thumbnails/localAssetId.jpg", "kind" to "image", "fillType" to FillType.Image, "width" to "1080", "height" to "1920" ) ) engine.asset.addAsset(sourceId = localSourceId, asset = assetDefinition) engine.asset.removeAsset(sourceId = localSourceId, assetId = assetDefinition.id) engine.asset.assetSourceContentsChanged(sourceId = source.sourceId) engine.asset.removeSource(sourceId = source.sourceId) engine.asset.removeSource(sourceId = localSourceId) val credits = engine.asset.getCredits(sourceId = source.sourceId) val license = engine.asset.getLicense(sourceId = source.sourceId) val groups = engine.asset.getGroups(sourceId = source.sourceId) engine.stop() class UnsplashAssetSource : AssetSource(sourceId = "ly.img.asset.source.unsplash") { override suspend fun getGroups(): List? = null override val credits = AssetCredits( name = "Unsplash", uri = Uri.parse("https://unsplash.com/") ) override val license = AssetLicense( name = "Unsplash license (free)", uri = Uri.parse("https://unsplash.com/license") ) override suspend fun findAssets(query: FindAssetsQuery): FindAssetsResult { return if (query.query.isNullOrEmpty()) query.getPopularList() else query.getSearchList() } private suspend fun FindAssetsQuery.getPopularList(): FindAssetsResult { val queryParams = listOf( "order_by" to "popular", "page" to page, "perPage" to perPage ).joinToString(separator = "&") { (key, value) -> "$key=$value" } val assetsArray = getResponseAsString("$BASE_URL/photos?$queryParams").let(::JSONArray) return FindAssetsResult( assets = (0 until assetsArray.length()).map { assetsArray.getJSONObject(it).toAsset() }, currentPage = page, nextPage = page + 1, total = 0 ) } private suspend fun FindAssetsQuery.getSearchList(): FindAssetsResult { val queryParams = listOf( "query" to query, "page" to page, "perPage" to perPage ).joinToString(separator = "&") { (key, value) -> "$key=$value" } val response = getResponseAsString("$BASE_URL/search/photos?$queryParams").let(::JSONObject) val assetsArray = response.getJSONArray("results") val total = response.getInt("total") val totalPages = response.getInt("total_pages") return FindAssetsResult( assets = (0 until assetsArray.length()).map { assetsArray.getJSONObject(it).toAsset() }, currentPage = page, nextPage = if (page == totalPages) -1 else page + 1, total = total ) } private suspend fun getResponseAsString(url: String) = withContext(Dispatchers.IO) { val connection = URL(url).openConnection() as HttpURLConnection require(connection.responseCode in 200 until 300) { connection.errorStream.bufferedReader().use { it.readText() } } connection.inputStream.bufferedReader().use { it.readText() } } private fun JSONObject.toAsset() = Asset( id = getString("id"), locale = "en", label = when { has("description") -> getString("description") has("alt_description") -> getString("alt_description") else -> null }, tags = takeIf { has("tags") }?.let { getJSONArray("tags") }?.let { (0 until it.length()).map { index -> it.getJSONObject(index).getString("title") } }?.takeIf { it.isNotEmpty() }, thumbnailUri = getJSONObject("urls").getString("thumb").let { Uri.parse(it) }, width = getInt("width").toFloat(), height = getInt("height").toFloat(), meta = mapOf("uri" to getJSONObject("urls").getString("full")), context = AssetContext(sourceId = "unsplash", createdByRole = ""), credits = AssetCredits( name = getJSONObject("user").getString("name"), uri = getJSONObject("user") .takeIf { it.has("links") } ?.getJSONObject("links") ?.getString("html") ?.let { Uri.parse(it) } ), utm = AssetUTM(source = "CE.SDK Demo", medium = "referral") ) companion object { private const val BASE_URL = "" // INSERT YOUR UNSPLASH PROXY URL HERE } } ``` In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to manage assets through the `asset` API. To begin working with assets first you need at least one asset source. As the name might imply asset sources provide the engine with assets. These assets then show up in the editor's asset library. But they can also be independently searched and used to create design blocks. Asset sources can be added dynamically using the `asset` API as we will show in this guide. ## Defining a Custom Asset Source Asset sources need at least an `id` and a `findAssets` function. You may notice `findAssets` method is `suspend`. This way you can use web requests or other long-running operations inside them and return results asynchronously. Let's go over these member one by one: All functions of `AssetApi` refer to an asset source by its unique `id`. That's why it has to be mandatory. Trying to add an asset source with an already registered `id` will fail. ```kotlin highlight-customSourceId val localSourceId = "LocalSourceId" ``` ```kotlin abstract suspend fun findAssets(query: FindAssetsQuery): FindAssetsResult ``` Searches assets based on the `query`. - `query`: the object that is used to filter results. - Returns asset search result. ```kotlin abstract suspend fun getGroups(): List? ``` Specifies all the available groups in this asset source. - Returns list of available groups. ```kotlin open val credits: AssetCredits? = null ``` Returns the credits info of this asset source. By default it is null. - Returns the credits info. ```kotlin open val license: AssetLicense? = null ``` Returns the license info of this asset source. By default it is null. - Returns the license info. ## Registering a New Asset Source ```kotlin fun addSource(source: AssetSource) ``` Adds a custom asset source. Its ID has to be unique. - `source`: the asset source. ```kotlin fun addLocalSource( sourceId: String, supportedMimeTypes: List, applyAsset: (suspend (Asset) -> DesignBlock?)? = null, applyAssetToBlock: (suspend (Asset, DesignBlock) -> Unit)? = null, ) ``` Adds a local asset source. Its ID has to be unique. - `sourceId`: the id of the new local asset source. - `supportedMimeTypes`: the mime types of assets that are allowed to be added to this local source. - `applyAsset`: an optional callback that can be used to override the default behavior of applying a given asset result to the active scene. - `applyAssetToBlock`: an optional callback that can be used to override the default behavior of applying an asset result to a given block. ```kotlin fun findAllSources(): List ``` Finds all registered asset sources. - Returns a list with the IDs of all registered asset sources. ```kotlin fun removeSource(sourceId: String) ``` Removes an asset source with the given ID. - `sourceId`: the ID to refer to the asset source. ```kotlin fun onAssetSourceAdded(): Flow ``` Subscribe to asset source addition events. - Returns flow of asset source addition events. ```kotlin fun onAssetSourceRemoved(): Flow ``` Subscribe to asset source removal events. - Returns flow of asset source removal events. ```kotlin fun onAssetSourceUpdated(): Flow ``` Subscribe to asset source's content update events. - Returns flow of asset source's content update events. ## Finding and Applying Assets The `findAssets` function should return paginated asset results for the given `query`. The asset results have a set of mandatory and optional properties. For a listing with an explanation for each property please refer to the [Integrate a Custom Asset Source](https://img.ly/docs/cesdk/android/import-media/from-remote-source/unsplash-8f31f0/) guide. The properties of the `query` and the pagination mechanism are also explained in this guide. ```kotlin suspend fun findAssets( sourceId: String, query: FindAssetsQuery, ): FindAssetsResult ``` Finds assets of a given type in a specific asset source. - `sourceId`: the ID of the asset source. - `query`: all the options to filter the search results by. - Returns the search results. The optional function 'applyAssetSourceAsset' is to define the behavior of what to do when an asset gets applied to the scene. You can use the engine's APIs to do whatever you want with the given asset result. In this case, we always create an image block and add it to the first page we find. If you don't provide this function the engine's default behavior is to create a block based on the asset.meta\["blockType"] property, add the block to the active page, and sensibly position and size it. ```kotlin suspend fun applyAssetSourceAsset( sourceId: String, asset: Asset, ): DesignBlock? ``` Applies an asset to the active scene using custom `AssetSource.applyAsset` function. - `sourceId`: the sourceId of `AssetSource` which `AssetSource.applyAsset` function is going to be invoked. - `asset`: the asset to be applied to the active scene. Normally it's a single result of a `findAssets` query. - Returns the newly created block or null if no new block is created. ```kotlin suspend fun applyAssetSourceAsset( sourceId: String, asset: Asset, block: DesignBlock, ) ``` Applies an asset to the `block` using custom `AssetSource.applyAsset` function. - `sourceId`: the sourceId of `AssetSource` which `AssetSource.applyAsset` function is going to be invoked. - `asset`: the asset that will be applied to the existing block. Normally it's a single result of a `findAssets` query. - `block`: the block that will be modified by the asset. ```kotlin suspend fun defaultApplyAsset(asset: Asset): DesignBlock? ``` This is the default implementation of applying asset to the active scene. This means a design block is instantiated and configured according to the `Asset.meta` properties. - `asset`: the asset to be applied to the active scene. Normally it's a single result of a `findAssets` query. - Returns the newly created block or null if no new block is created. ```kotlin suspend fun defaultApplyAsset( asset: Asset, block: DesignBlock, ) ``` This is the default implementation of applying `asset` object to an existing `block`. This means it replaces the `block` content with `asset` content, if compatible. - `asset`: the asset that will be applied to the existing block. Normally it's a single result of a `findAssets` query. - `block`: the block that will be modified by the asset. ```kotlin fun getSourceSupportedMimeTypes(sourceId: String): List ``` Get the asset source's list of supported mime types. - `sourceId`: the ID of the asset source. - Returns the list of supported mime types of this asset source. ## Document Asset Sources A document color asset source is automatically available that allows listing all colors in the document. This asset source is read-only and is updated when `findAssets` is called. ## Add an Asset ```kotlin fun addAsset( sourceId: String, asset: AssetDefinition, ) ``` Adds the given `asset` to a local asset source. - `sourceId`: The local asset source ID that the asset should be added to. - `asset`: the asset that should be added. ## Remove an Asset ```kotlin fun removeAsset( sourceId: String, assetId: String, ) ``` Removes the specified asset from its local asset source. - `sourceId`: the ID of the local asset source that currently contains the asset. - `assetId`: the asset id that should be removed. ## Asset Source Content Updates If the contents of your custom asset source change, you can call the `assetSourceContentsChanged` API to later notify all subscribers of the `onAssetSourceUpdated` API. ```kotlin fun assetSourceContentsChanged(sourceId: String) ``` Notifies the engine that the contents of an asset source changed. - `sourceId`: the asset source whose contents changed. ## Groups in Assets ```kotlin suspend fun getGroups(sourceId: String): List? ``` Queries the asset source's groups for a certain asset type. - `sourceId`: the ID of the asset source. - Returns the asset groups. ## Credits and License ```kotlin fun getCredits(sourceId: String): AssetCredits? ``` Queries the asset source's credits info. - `sourceId`: the ID of the asset source. - Returns the asset source's credits info consisting of a name and an optional URL. ```kotlin fun getLicense(sourceId: String): AssetLicense? ``` Queries the asset source's license info. - `sourceId`: the ID of the asset source. - Returns the asset source's license info consisting of a name and an optional URL. ## Full Code Here's the full code: ```kotlin val engine = Engine(id = "ly.img.engine.example") engine.start() engine.bindOffscreen(width = 100, height = 100) val coroutineScope = CoroutineScope(Dispatchers.Main) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) val block = engine.block.create(DesignBlockType.Graphic) engine.block.appendChild(parent = scene, child = page) engine.block.appendChild(parent = page, child = block) val source = UnsplashAssetSource() engine.asset.addSource(source) val localSourceId = "LocalSourceId" engine.asset.addLocalSource(localSourceId, supportedMimeTypes = "image/jpeg") val assetSourceIds = engine.asset.findAllSources() // List [ "ly.img.asset.source.unsplash", "LocalSourceId", ... ] engine.asset.onAssetSourceAdded() .onEach { println("Asset source added: id=$it") } .launchIn(coroutineScope) engine.asset.onAssetSourceRemoved() .onEach { println("Asset source removed: id=$it") } .launchIn(coroutineScope) engine.asset.onAssetSourceUpdated() .onEach { println("Asset source updated: id=$it") } .launchIn(coroutineScope) val mimeTypes = engine.asset.getSourceSupportedMimeTypes(sourceId = "ly.img.asset.source.unsplash") val list = engine.asset.findAssets( sourceId = source.sourceId, query = FindAssetsQuery(query = "", page = 1, perPage = 10) ) val sortByNewest = engine.asset.findAssets( sourceId = source.sourceId, query = FindAssetsQuery(query = "", page = 1, perPage = 10, sortingOrder = SortingOrder.DESCENDING) ) val sortById = engine.asset.findAssets( sourceId = source.sourceId, query = FindAssetsQuery(query = "", page = 1, perPage = 10, sortingOrder = SortingOrder.ASCENDING, sortKey = "id") ) val sortByMetaKeyValue = engine.asset.findAssets( sourceId = source.sourceId, query = FindAssetsQuery(query = "", page = 1, perPage = 10, sortingOrder = SortingOrder.ASCENDING, sortKey = "someMetaKey") ) val search = engine.asset.findAssets( sourceId = source.sourceId, query = FindAssetsQuery(query = "banana", page = 1, perPage = 10) ) val documentColors = engine.asset.findAssets( sourceId = "ly.img.scene.colors", query = FindAssetsQuery(query = "", page = 0, perPage = 99999) ) val colorAsset = documentColors.assets[0] engine.asset.applyAssetSourceAsset(sourceId = source.sourceId, asset = list.assets[0]) engine.asset.applyAssetSourceAsset(sourceId = source.sourceId, asset = list.assets[0], block = block) engine.asset.defaultApplyAsset(asset = search.assets[0]) engine.asset.defaultApplyAsset(asset = search.assets[0], block = block) val assetDefinition = AssetDefinition( id = "localAssetId", meta = mapOf( "uri" to "https://example.com/localAssetId.jpg", "thumbUri" to "https://example.com/thumbnails/localAssetId.jpg", "kind" to "image", "fillType" to FillType.Image, "width" to "1080", "height" to "1920" ) ) engine.asset.addAsset(sourceId = localSourceId, asset = assetDefinition) engine.asset.removeAsset(sourceId = localSourceId, assetId = assetDefinition.id) engine.asset.assetSourceContentsChanged(sourceId = source.sourceId) engine.asset.removeSource(sourceId = source.sourceId) engine.asset.removeSource(sourceId = localSourceId) val credits = engine.asset.getCredits(sourceId = source.sourceId) val license = engine.asset.getLicense(sourceId = source.sourceId) val groups = engine.asset.getGroups(sourceId = source.sourceId) engine.stop() class UnsplashAssetSource : AssetSource(sourceId = "ly.img.asset.source.unsplash") { override suspend fun getGroups(): List? = null override val credits = AssetCredits( name = "Unsplash", uri = Uri.parse("https://unsplash.com/") ) override val license = AssetLicense( name = "Unsplash license (free)", uri = Uri.parse("https://unsplash.com/license") ) override suspend fun findAssets(query: FindAssetsQuery): FindAssetsResult { return if (query.query.isNullOrEmpty()) query.getPopularList() else query.getSearchList() } private suspend fun FindAssetsQuery.getPopularList(): FindAssetsResult { val queryParams = listOf( "order_by" to "popular", "page" to page, "perPage" to perPage ).joinToString(separator = "&") { (key, value) -> "$key=$value" } val assetsArray = getResponseAsString("$BASE_URL/photos?$queryParams").let(::JSONArray) return FindAssetsResult( assets = (0 until assetsArray.length()).map { assetsArray.getJSONObject(it).toAsset() }, currentPage = page, nextPage = page + 1, total = 0 ) } private suspend fun FindAssetsQuery.getSearchList(): FindAssetsResult { val queryParams = listOf( "query" to query, "page" to page, "perPage" to perPage ).joinToString(separator = "&") { (key, value) -> "$key=$value" } val response = getResponseAsString("$BASE_URL/search/photos?$queryParams").let(::JSONObject) val assetsArray = response.getJSONArray("results") val total = response.getInt("total") val totalPages = response.getInt("total_pages") return FindAssetsResult( assets = (0 until assetsArray.length()).map { assetsArray.getJSONObject(it).toAsset() }, currentPage = page, nextPage = if (page == totalPages) -1 else page + 1, total = total ) } private suspend fun getResponseAsString(url: String) = withContext(Dispatchers.IO) { val connection = URL(url).openConnection() as HttpURLConnection require(connection.responseCode in 200 until 300) { connection.errorStream.bufferedReader().use { it.readText() } } connection.inputStream.bufferedReader().use { it.readText() } } private fun JSONObject.toAsset() = Asset( id = getString("id"), locale = "en", label = when { has("description") -> getString("description") has("alt_description") -> getString("alt_description") else -> null }, tags = takeIf { has("tags") }?.let { getJSONArray("tags") }?.let { (0 until it.length()).map { index -> it.getJSONObject(index).getString("title") } }?.takeIf { it.isNotEmpty() }, thumbnailUri = getJSONObject("urls").getString("thumb").let { Uri.parse(it) }, width = getInt("width").toFloat(), height = getInt("height").toFloat(), meta = mapOf("uri" to getJSONObject("urls").getString("full")), context = AssetContext(sourceId = "unsplash", createdByRole = ""), credits = AssetCredits( name = getJSONObject("user").getString("name"), uri = getJSONObject("user") .takeIf { it.has("links") } ?.getJSONObject("links") ?.getString("html") ?.let { Uri.parse(it) } ), utm = AssetUTM(source = "CE.SDK Demo", medium = "referral") ) companion object { private const val BASE_URL = "" // INSERT YOUR UNSPLASH PROXY URL HERE } } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "File Format Support" description: "Review the supported image, video, and audio formats for importing assets." platform: android url: "https://img.ly/docs/cesdk/android/import-media/file-format-support-8cdc84/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Import Media Assets](https://img.ly/docs/cesdk/android/import-media-4e3703/) > [File Format Support](https://img.ly/docs/cesdk/android/import-media/file-format-support-8cdc84/) --- CreativeEditor SDK (CE.SDK) supports importing high-resolution images, video, and audio content. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Import From Local Source" description: "Enable users to upload files from their device for use as design assets in the editor." platform: android url: "https://img.ly/docs/cesdk/android/import-media/from-local-source-39b2a9/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Import Media Assets](https://img.ly/docs/cesdk/android/import-media-4e3703/) > [Import From Local Source](https://img.ly/docs/cesdk/android/import-media/from-local-source-39b2a9/) --- --- ## Related Pages - [Import Local Asset](https://img.ly/docs/cesdk/android/import-media/from-local-source/local-asset-3f93f2/) - Import files directly from the user's device and insert them into the design canvas. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Import Local Asset" description: "Import files directly from the user's device and insert them into the design canvas." platform: android url: "https://img.ly/docs/cesdk/android/import-media/from-local-source/local-asset-3f93f2/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Import Media Assets](https://img.ly/docs/cesdk/android/import-media-4e3703/) > [Import From Local Source](https://img.ly/docs/cesdk/android/import-media/from-local-source-39b2a9/) > [Import Local Asset](https://img.ly/docs/cesdk/android/import-media/from-local-source/local-asset-3f93f2/) --- The Android editor provides an optional asset source that indexes the device gallery (images and videos) via the Android `MediaStore`. This section explains how to opt in, how the default (upload-only) workflow behaves, and how to take care of the required permissions when the gallery integration is enabled. ## Default behavior - By default, the SDK keeps the system gallery disabled and relies on the upload buttons and camera intents. The Gallery section stays visible but starts empty and fills with the media that users add or capture while editing. This means no storage permissions are requested automatically and the media picker is handled by system intents. - Opt in by calling `SystemGalleryPermission.setMode` inside your `EngineConfiguration.onCreate` callback (or any later editor scope). This keeps the opt-in explicit even when you rely on the helper composables. - Once enabled, the asset library shows a **Gallery** section and the dock/timeline expose a *Gallery* quick action (`Dock.Button.rememberSystemGallery`). When end users only grant partial access (Android 13+ “selected photos”), the UI combines the selected items with the MediaStore listing. ```kotlin import ly.img.editor.EngineConfiguration import ly.img.editor.EditorDefaults import ly.img.editor.core.library.data.SystemGalleryConfiguration import ly.img.editor.core.library.data.SystemGalleryPermission @Composable fun rememberEngineConfiguration(license: String): EngineConfiguration = EngineConfiguration.remember( license = license, onCreate = { EditorDefaults.onCreate( editorContext.engine, EngineConfiguration.defaultDesignSceneUri, editorContext.eventHandler, ) SystemGalleryPermission.setMode(SystemGalleryConfiguration.Enabled) }, ) ``` If you override the default `onCreate` handler or build your own engine bootstrap, add the sources manually as shown below. ## Adding the system gallery sources manually ```kotlin import ly.img.editor.core.library.data.SystemGalleryConfiguration import ly.img.editor.core.library.data.SystemGalleryPermission suspend fun onCreate(engine: Engine) { engine.addDefaultAssetSources() SystemGalleryPermission.setMode(SystemGalleryConfiguration.Enabled) // …register any additional asset sources that you need afterwards } ``` If you delegate to `EditorDefaults.onCreate`, call the scope helper afterwards: ```kotlin import ly.img.editor.EditorDefaults import ly.img.editor.core.library.data.SystemGalleryConfiguration EditorDefaults.onCreate( engine = engine, sceneUri = sceneUri, eventHandler = eventHandler, ) SystemGalleryPermission.setMode(SystemGalleryConfiguration.Enabled) ``` `SystemGalleryPermission.setMode` updates the gallery permission mode; `EditorDefaults` wire the sources automatically. If you build the engine manually, add the sources as shown above. The in-editor gallery relies on three sources: - `AssetSourceType.GalleryAllVisuals` – combined images and videos (used for the default Gallery section) - `AssetSourceType.GalleryImage` - `AssetSourceType.GalleryVideo` They are exposed in `LibraryCategory.getElements` and can also be consumed directly from custom `LibraryContent` definitions. When `SystemGalleryConfiguration.Disabled` is used, the sources only list the URIs that were manually added during the current session. ## Permissions and manifest setup - Declare the following permissions in your app manifest so the runtime requests can be triggered: - `READ_MEDIA_IMAGES` and `READ_MEDIA_VIDEO` on Android 13+ - `READ_MEDIA_VISUAL_USER_SELECTED` on Android 14+ (to support the *selected photos* mode) - Fallback to `READ_EXTERNAL_STORAGE` on Android 12 and lower - The built-in UI components (`LibrarySectionHeader`, `SystemGalleryAddMenu`, `Dock.Button.rememberSystemGallery`) request the appropriate permissions via `ActivityResultContracts.RequestMultiplePermissions` and update `GalleryPermissionManager` automatically. - If you build your own UI layer, use `GalleryPermissionManager.requiredPermission(mimeType)` to obtain the permission set and call `GalleryPermissionManager.setSelected(uris, context)` when the user picks a limited set of media. Once the permissions are granted, `SystemGalleryAssetSource` paginates over MediaStore and refreshes the gallery section automatically. ## Legacy upload flow ```kotlin file=@cesdk_android_examples/editor-guides-configuration-asset-library/UploadsOnlyAssetLibraryEditorSolution.kt reference-only import androidx.compose.runtime.Composable import androidx.compose.runtime.remember import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EngineConfiguration import ly.img.editor.core.library.AssetLibrary import ly.img.editor.core.library.AssetType import ly.img.editor.core.library.LibraryCategory import ly.img.editor.core.library.LibraryContent import ly.img.editor.core.library.data.AssetSourceType import ly.img.editor.rememberForDesign import ly.img.editor.smoketests.Secrets @Composable fun UploadsOnlyAssetLibraryEditorSolution(navController: NavHostController) { val uploadsOnlyImages = remember { LibraryCategory.Images.copy( content = LibraryContent.Sections( titleRes = ly.img.editor.core.R.string.ly_img_editor_asset_library_title_images, sections = listOf( LibraryContent.Section( titleRes = ly.img.editor.core.R.string.ly_img_editor_asset_library_section_image_uploads, sourceTypes = listOf(AssetSourceType.ImageUploads), assetType = AssetType.Image, expandContent = LibraryContent.Grid( titleRes = ly.img.editor.core.R.string.ly_img_editor_asset_library_section_image_uploads, sourceType = AssetSourceType.ImageUploads, assetType = AssetType.Image, ), ), ), ), ) } val assetLibrary = remember { AssetLibrary.getDefault(images = uploadsOnlyImages) } val engineConfiguration = EngineConfiguration.remember( license = Secrets.license, onCreate = {}, ) val editorConfiguration = EditorConfiguration.rememberForDesign( assetLibrary = assetLibrary, ) DesignEditor( engineConfiguration = engineConfiguration, editorConfiguration = editorConfiguration, ) { navController.popBackStack() } } ``` The `UploadsOnlyAssetLibraryEditorSolution` sample demonstrates how to replace the default gallery sections with the classic uploads picker and how to adjust the timeline options accordingly. ```kotlin highlight-uploads-only-asset-library val uploadsOnlyImages = remember { LibraryCategory.Images.copy( content = LibraryContent.Sections( titleRes = ly.img.editor.core.R.string.ly_img_editor_asset_library_title_images, sections = listOf( LibraryContent.Section( titleRes = ly.img.editor.core.R.string.ly_img_editor_asset_library_section_image_uploads, sourceTypes = listOf(AssetSourceType.ImageUploads), assetType = AssetType.Image, expandContent = LibraryContent.Grid( titleRes = ly.img.editor.core.R.string.ly_img_editor_asset_library_section_image_uploads, sourceType = AssetSourceType.ImageUploads, assetType = AssetType.Image, ), ), ), ), ) } val assetLibrary = remember { AssetLibrary.getDefault(images = uploadsOnlyImages) } ``` If you also want to hide the gallery quick action from the timeline menu, update the global configuration: > **Optional:** `TimelineConfiguration` lives in the `editor-base` module. You can only adjust it if your app includes is. ```kotlin import ly.img.editor.base.timeline.state.AddClipOption import ly.img.editor.base.timeline.state.TimelineConfiguration TimelineConfiguration.addClipOptions = listOf(AddClipOption.Camera, AddClipOption.Library) ``` - Update other categories (for example the combined `LibraryCategory.getElements`) the same way if you need to hide gallery sections globally. - The stock dock and timeline buttons open the image category, so once that category only contains `AssetSourceType.ImageUploads`, the uploads picker shows up automatically. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Import From Remote Source" description: "Connect CE.SDK to external sources like servers or third-party platforms to import assets remotely." platform: android url: "https://img.ly/docs/cesdk/android/import-media/from-remote-source-b65faf/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Import Media Assets](https://img.ly/docs/cesdk/android/import-media-4e3703/) > [Import From Remote Source](https://img.ly/docs/cesdk/android/import-media/from-remote-source-b65faf/) --- --- ## Related Pages - [From A Custom Source](https://img.ly/docs/cesdk/android/import-media/from-remote-source/unsplash-8f31f0/) - Browse and import royalty-free images from Unsplash into the editor. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "From A Custom Source" description: "Browse and import royalty-free images from Unsplash into the editor." platform: android url: "https://img.ly/docs/cesdk/android/import-media/from-remote-source/unsplash-8f31f0/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Import Media Assets](https://img.ly/docs/cesdk/android/import-media-4e3703/) > [Import From Remote Source](https://img.ly/docs/cesdk/android/import-media/from-remote-source-b65faf/) > [From a Custom Source](https://img.ly/docs/cesdk/android/import-media/from-remote-source/unsplash-8f31f0/) --- ```kotlin file=@cesdk_android_examples/engine-guides-custom-asset-source/UnsplashAssetSource.kt reference-only import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import kotlinx.coroutines.withContext import ly.img.engine.Asset import ly.img.engine.AssetColor import ly.img.engine.AssetContext import ly.img.engine.AssetCredits import ly.img.engine.AssetDefinition import ly.img.engine.AssetLicense import ly.img.engine.AssetPayload import ly.img.engine.AssetSource import ly.img.engine.AssetUTM import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.FindAssetsQuery import ly.img.engine.FindAssetsResult import ly.img.engine.ShapeType import org.json.JSONArray import org.json.JSONObject import java.net.HttpURLConnection import java.net.URL fun customAssetSource( license: String?, // pass null or empty for evaluation mode with watermark userId: String, unsplashBaseUrl: String, ) = CoroutineScope( Dispatchers.Main, ).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val source = UnsplashAssetSource(unsplashBaseUrl) // INSERT YOUR UNSPLASH PROXY URL HERE engine.asset.addSource(source) val list = runCatching { engine.asset.findAssets( sourceId = "ly.img.asset.source.unsplash", query = FindAssetsQuery(query = "", page = 1, perPage = 10), ) }.getOrElse { it.printStackTrace() } val search = runCatching { engine.asset.findAssets( sourceId = "ly.img.asset.source.unsplash", query = FindAssetsQuery(query = "banana", page = 1, perPage = 10), ) }.getOrElse { it.printStackTrace() } engine.asset.addLocalSource( sourceId = "background-videos", supportedMimeTypes = listOf("video/mp4"), ) val asset = AssetDefinition( id = "ocean-waves-1", label = mapOf( "en" to "relaxing ocean waves", "es" to "olas del mar relajantes", ), tags = mapOf( "en" to listOf("ocean", "waves", "soothing", "slow"), "es" to listOf("mar", "olas", "calmante", "lento"), ), meta = mapOf( "uri" to "https://example.com/ocean-waves-1.mp4", "thumbUri" to "https://example.com/thumbnails/ocean-waves-1.jpg", "mimeType" to "video/mp4", "width" to "1920", "height" to "1080", ), payload = AssetPayload(color = AssetColor.RGB(r = 0F, g = 0F, b = 1F)), ) engine.asset.addAsset(sourceId = "background-videos", asset = asset) engine.stop() } class UnsplashAssetSource( private val baseUrl: String, ) : AssetSource(sourceId = "ly.img.asset.source.unsplash") { override suspend fun getGroups(): List? = null override val supportedMimeTypes = listOf("image/jpeg") override val credits = AssetCredits( name = "Unsplash", uri = Uri.parse("https://unsplash.com/"), ) override val license = AssetLicense( name = "Unsplash license (free)", uri = Uri.parse("https://unsplash.com/license"), ) override suspend fun findAssets(query: FindAssetsQuery): FindAssetsResult = withContext(Dispatchers.IO) { if (query.query.isNullOrEmpty()) query.getPopularList() else query.getSearchList() } private suspend fun FindAssetsQuery.getPopularList(): FindAssetsResult { val queryParams = listOf( "order_by" to "popular", "page" to page + 1, "per_page" to perPage, ).joinToString(separator = "&") { (key, value) -> "$key=$value" } val assetsArray = getResponseAsString("$baseUrl/photos?$queryParams").let(::JSONArray) return FindAssetsResult( assets = (0 until assetsArray.length()).map { assetsArray.getJSONObject(it).toAsset() }, currentPage = page, nextPage = page + 1, total = Int.MAX_VALUE, ) } private suspend fun FindAssetsQuery.getSearchList(): FindAssetsResult { val queryParams = listOf( "query" to query, "page" to page + 1, "per_page" to perPage, ).joinToString(separator = "&") { (key, value) -> "$key=$value" } val response = getResponseAsString("$baseUrl/search/photos?$queryParams").let(::JSONObject) val assetsArray = response.getJSONArray("results") val total = response.getInt("total") val totalPages = response.getInt("total_pages") return FindAssetsResult( assets = (0 until assetsArray.length()).map { assetsArray.getJSONObject(it).toAsset() }, currentPage = page, nextPage = if (page == totalPages) -1 else page + 1, total = total, ) } private suspend fun getResponseAsString(url: String) = withContext(Dispatchers.IO) { val connection = URL(url).openConnection() as HttpURLConnection require(connection.responseCode in 200 until 300) { connection.errorStream.bufferedReader().use { it.readText() } } connection.inputStream.bufferedReader().use { it.readText() } } private fun JSONObject.toAsset() = Asset( id = getString("id"), locale = "en", label = when { !isNull("description") -> getString("description") !isNull("alt_description") -> getString("alt_description") else -> null }, tags = takeIf { has("tags") }?.let { getJSONArray("tags") }?.let { (0 until it.length()).map { index -> it.getJSONObject(index).getString("title") } }?.takeIf { it.isNotEmpty() }, meta = mapOf( "uri" to getJSONObject("urls").getString("full"), "thumbUri" to getJSONObject("urls").getString("thumb"), "blockType" to DesignBlockType.Graphic.key, "fillType" to FillType.Image.key, "shapeType" to ShapeType.Rect.key, "kind" to "image", "width" to getInt("width").toString(), "height" to getInt("height").toString(), ), context = AssetContext(sourceId = "unsplash"), credits = AssetCredits( name = getJSONObject("user").getString("name"), uri = getJSONObject("user") .takeIf { it.has("links") } ?.getJSONObject("links") ?.getString("html") ?.let { Uri.parse(it) }, ), utm = AssetUTM(source = "CE.SDK Demo", medium = "referral"), ) } ``` In this example, we will show you how to integrate your custom asset sources into [CE.SDK](https://img.ly/products/creative-sdk). With CE.SDK you can directly add external image providers like Unsplash or your own backend. A third option we will explore in this guide is using the engine's Asset API directly. Follow along with this example while we are going to add the Unsplash library. Adding an asset source is done creating an asset source definition and adding it using `fun addSource(source: AssetSource)`. The asset source needs a unique identifier as part of an object implementing the interface of the source. All Asset API methods require the asset source's unique identifier. ```kotlin highlight-unsplash-definition val source = UnsplashAssetSource(unsplashBaseUrl) // INSERT YOUR UNSPLASH PROXY URL HERE engine.asset.addSource(source) ``` The most important function to implement is `suspend fun findAssets(sourceId: String, query: FindAssetsQuery): FindAssetsResult`. With this function alone you can define the complete asset source. It receives the asset query as an argument and returns results asynchronously. - The argument is the `query` and describes the slice of data the engine wants to use. This includes a query string and pagination information. - The result of this query, besides the actual asset data, returns information like the current page, the next page and the total number of assets available for this specific query. Providing a `suspend` function gives us great flexibility since we are completely agnostic of how we want to get the assets. We can use `HttpURLConnection`, local storage, cache or import a 3rd party library to return the result. ```kotlin highlight-unsplash-findAssets val list = runCatching { engine.asset.findAssets( sourceId = "ly.img.asset.source.unsplash", query = FindAssetsQuery(query = "", page = 1, perPage = 10), ) }.getOrElse { it.printStackTrace() } ``` Let us implement an Unsplash asset source. Please note that this is just for demonstration purposes only and may not be ideal if you want to integrate Unsplash in your production environment. We will create a class implementing abstract class `AssetSource`. A unique `sourceId = "ly.img.asset.source.unsplash"` is passed via the constructor. There are multiple abstract methods that we need to implement, however, `findAssets` is the most important one. ```kotlin highlight-unsplash-source-creation class UnsplashAssetSource( private val baseUrl: String, ) : AssetSource(sourceId = "ly.img.asset.source.unsplash") { ``` `findAssets` is the function that receives `query` object from the engine and is supposed to return the corresponding results. Unsplash has different API endpoints for different use cases. If we want to search we need to call a different endpoint as if we just want to display images without any search term. Therefore we need to check if the query data contains a `query` string. If `findAssets` was called with a non-empty `query` we call the `/search` endpoint via `getSearchList` function, otherwise we call `getPopularList`. As we can see in the example, we are passing the `query` object to `findAssets` method, containing the following fields: - `query.query`: The current search string from the search bar in the asset library. - `query.page`: For Unsplash specifically the requested page number starts with 1. We do not query all assets at once but by pages. As the user scrolls down more pages will be requested by calls to the `findAssets` method. - `query.perPage`: Determines how many assets we want to have included per page. This might change between calls. For instance, `perPage` can be called with a small number to display a small preview, but with a higher number e.g. if we want to show more assets in a grid view. ```kotlin highlight-unsplash-query override suspend fun findAssets(query: FindAssetsQuery): FindAssetsResult = withContext(Dispatchers.IO) { if (query.query.isNullOrEmpty()) query.getPopularList() else query.getSearchList() } private suspend fun FindAssetsQuery.getPopularList(): FindAssetsResult { val queryParams = listOf( "order_by" to "popular", "page" to page + 1, "per_page" to perPage, ).joinToString(separator = "&") { (key, value) -> "$key=$value" } val assetsArray = getResponseAsString("$baseUrl/photos?$queryParams").let(::JSONArray) return FindAssetsResult( assets = (0 until assetsArray.length()).map { assetsArray.getJSONObject(it).toAsset() }, currentPage = page, nextPage = page + 1, total = Int.MAX_VALUE, ) } private suspend fun FindAssetsQuery.getSearchList(): FindAssetsResult { val queryParams = listOf( "query" to query, "page" to page + 1, "per_page" to perPage, ).joinToString(separator = "&") { (key, value) -> "$key=$value" } val response = getResponseAsString("$baseUrl/search/photos?$queryParams").let(::JSONObject) val assetsArray = response.getJSONArray("results") val total = response.getInt("total") val totalPages = response.getInt("total_pages") return FindAssetsResult( assets = (0 until assetsArray.length()).map { assetsArray.getJSONObject(it).toAsset() }, currentPage = page, nextPage = if (page == totalPages) -1 else page + 1, total = total, ) } ``` Once we receive the response and check for success we need to map Unsplash's result to what the asset source API needs as a result. The CE.SDK expects an object with the following properties: - `assets`: An array of assets for the current query. We will take a look at what these have to look like in the next paragraph. - `currentPage`: Return the current page that was requested. - `nextPage`: This is the next page that can be requested after the current one. Should be `-1` if there is no other page (no more assets). In this case we stop querying for more even if the user has scrolled to the bottom. - `total`: The total number of assets available for the current query. If we search for "Cat" with `perPage` set to 30, we will get 30 assets, but `total` likely will be a much higher number. ```kotlin highlight-unsplash-result-mapping val response = getResponseAsString("$baseUrl/search/photos?$queryParams").let(::JSONObject) val assetsArray = response.getJSONArray("results") val total = response.getInt("total") val totalPages = response.getInt("total_pages") return FindAssetsResult( assets = (0 until assetsArray.length()).map { assetsArray.getJSONObject(it).toAsset() }, currentPage = page, nextPage = if (page == totalPages) -1 else page + 1, total = total, ) ``` Every image we get as a result of Unsplash needs to be translated into an object that is expected by the asset source API. We will describe every mandatory and optional property in the following paragraphs. ```kotlin highlight-translateToAssetResult private fun JSONObject.toAsset() = Asset( id = getString("id"), locale = "en", label = when { !isNull("description") -> getString("description") !isNull("alt_description") -> getString("alt_description") else -> null }, tags = takeIf { has("tags") }?.let { getJSONArray("tags") }?.let { (0 until it.length()).map { index -> it.getJSONObject(index).getString("title") } }?.takeIf { it.isNotEmpty() }, meta = mapOf( "uri" to getJSONObject("urls").getString("full"), "thumbUri" to getJSONObject("urls").getString("thumb"), "blockType" to DesignBlockType.Graphic.key, "fillType" to FillType.Image.key, "shapeType" to ShapeType.Rect.key, "kind" to "image", "width" to getInt("width").toString(), "height" to getInt("height").toString(), ), context = AssetContext(sourceId = "unsplash"), credits = AssetCredits( name = getJSONObject("user").getString("name"), uri = getJSONObject("user") .takeIf { it.has("links") } ?.getJSONObject("links") ?.getString("html") ?.let { Uri.parse(it) }, ), utm = AssetUTM(source = "CE.SDK Demo", medium = "referral"), ) ``` `id`: The id of the asset (mandatory). This has to be unique for this source configuration. ```kotlin highlight-result-id id = getString("id"), ``` `locale` (optional): The language locale for this asset is used in `label` and `tags`. ```kotlin highlight-result-locale locale = "en", ``` `label` (optional): The label of this asset. It could be displayed in the tooltip as well as in the credits of the asset. ```kotlin highlight-result-label label = when { !isNull("description") -> getString("description") !isNull("alt_description") -> getString("alt_description") else -> null }, ``` `tags` (optional): The tags of this asset. It could be displayed in the credits of the asset. ```kotlin highlight-result-tags tags = takeIf { has("tags") }?.let { getJSONArray("tags") }?.let { (0 until it.length()).map { index -> it.getJSONObject(index).getString("title") } }?.takeIf { it.isNotEmpty() }, ``` `meta`: The meta object stores asset properties that depend on the specific asset type. ```kotlin highlight-result-meta meta = mapOf( "uri" to getJSONObject("urls").getString("full"), "thumbUri" to getJSONObject("urls").getString("thumb"), "blockType" to DesignBlockType.Graphic.key, "fillType" to FillType.Image.key, "shapeType" to ShapeType.Rect.key, "kind" to "image", "width" to getInt("width").toString(), "height" to getInt("height").toString(), ), ``` `uri`: For an image asset this is the URL to the image file that will be used to add the image to the scene. Note that we have to use the Unsplash API to obtain a usable URL at first. ```kotlin highlight-result-uri "uri" to getJSONObject("urls").getString("full"), ``` `thumbUri`: The URI of the asset's thumbnail. It could be used in an asset library. ```kotlin highlight-result-thumbUri "thumbUri" to getJSONObject("urls").getString("thumb"), ``` `blockType`: The type id of the design block that should be created when this asset is applied to the scene. If omitted, CE.SDK will try to infer the block type from an optionally provided `mimeType` property (e.g. `image/jpeg`) or by loading the asset data behind `uri` and parsing the mime type from that. However, this will cause a delay before the asset can be added to the scene, which is why it is always recommended to specify the `blockType` upfront. ```kotlin highlight-result-blockType "blockType" to DesignBlockType.Graphic.key, ``` `fillType`: The type id of the fill that should be attached to the block when this asset is applied to the scene. If omitted, CE.SDK will default to a solid color fill `//ly.img.ubq/fill/color`. ```kotlin highlight-result-fillType "fillType" to FillType.Image.key, ``` `shapeType`: The type id of the shape that should be attached to the block when this asset is applied to the scene. If omitted, CE.SDK will default to a rect shape `//ly.img.ubq/shape/rect`. ```kotlin highlight-result-shapeType "shapeType" to ShapeType.Rect.key, ``` `kind`: The kind that should be set to the block when this asset is applied to the scene. If omitted, CE.SDK will default to an empty string. ```kotlin highlight-result-kind "kind" to "image", ``` `width`: The original width of the image. `height`: The original height of the image. ```kotlin highlight-result-size "width" to getInt("width").toString(), "height" to getInt("height").toString(), ``` `looping`: Determines whether the asset allows looping (applicable only to Video and GIF). When set to `true`, the asset can extend beyond its original length by looping for the specified duration. `context`: Adds contextual information to the asset. Right now, this only includes the source id of the source configuration. ```kotlin highlight-result-context context = AssetContext(sourceId = "unsplash"), ``` `credits` (optional): Some image providers require to display credits to the asset's artist. If set, it has to be an object with the artist's `name` and a `url` to the artist page. ```kotlin highlight-result-credits credits = AssetCredits( name = getJSONObject("user").getString("name"), uri = getJSONObject("user") .takeIf { it.has("links") } ?.getJSONObject("links") ?.getString("html") ?.let { Uri.parse(it) }, ), ``` `utm` (optional): Some image providers require to add UTM parameters to all links to the source or the artist. If set, it contains a string to the `source` (added as `utm_source`) and the `medium` (added as `utm_medium`) ```kotlin highlight-result-utm utm = AssetUTM(source = "CE.SDK Demo", medium = "referral"), ``` After translating the asset to match the interface from the asset source API, the array of assets for the current page can be returned. Going further with our Unsplash integration we need to handle the case when no query was provided. Unsplash requires us to call a different API endpoint (`/photos`) with slightly different parameters but the basics are the same. We need to check for success, calculate `total` and `nextPage` and translate the assets. ```kotlin highlight-unsplash-list val search = runCatching { engine.asset.findAssets( sourceId = "ly.img.asset.source.unsplash", query = FindAssetsQuery(query = "banana", page = 1, perPage = 10), ) }.getOrElse { it.printStackTrace() } ``` In addition to `findAssets`, there are couple more methods that need to be implemented. We have already seen that an asset can define credits for the artist. Depending on the image provider you might need to add credits and the license for the source. In case of Unsplash, this includes a link as well as the license of all assets from this source. ```kotlin highlight-unsplash-credits-license override val credits = AssetCredits( name = "Unsplash", uri = Uri.parse("https://unsplash.com/"), ) override val license = AssetLicense( name = "Unsplash license (free)", uri = Uri.parse("https://unsplash.com/license"), ) ``` ## Local Asset Sources In many cases, you already have various finite sets of assets that you want to make available via asset sources. In order to save you the effort of having to implement custom asset query callbacks for each of these asset sources, CE.SDK also allows you to create "local" asset sources, which are managed by the engine and provide search and pagination functionalities. In order to add such a local asset source, simply call the `addLocalSource` API and choose a unique id with which you can later access the asset source. ```kotlin highlight-add-local-source engine.asset.addLocalSource( sourceId = "background-videos", supportedMimeTypes = listOf("video/mp4"), ) ``` The `fun addAsset(sourceId: String, asset: AssetDefinition)` API allows you to add new asset instances to your local asset source. The local asset source then keeps track of these assets and returns matching items as the result of asset queries. Asset queries return the assets in the same order in which they were inserted into the local asset source. Note that the `AssetDefinition` type that we pass to the `addAsset` API is slightly different than the `Asset` type which is returned by asset queries. The `AssetDefinition` for example contains all localizations of the labels and tags of the same asset whereas the `Asset` is specific to the locale property of the query. ```kotlin highlight-add-asset-to-source val asset = AssetDefinition( id = "ocean-waves-1", label = mapOf( "en" to "relaxing ocean waves", "es" to "olas del mar relajantes", ), tags = mapOf( "en" to listOf("ocean", "waves", "soothing", "slow"), "es" to listOf("mar", "olas", "calmante", "lento"), ), meta = mapOf( "uri" to "https://example.com/ocean-waves-1.mp4", "thumbUri" to "https://example.com/thumbnails/ocean-waves-1.jpg", "mimeType" to "video/mp4", "width" to "1920", "height" to "1080", ), payload = AssetPayload(color = AssetColor.RGB(r = 0F, g = 0F, b = 1F)), ) engine.asset.addAsset(sourceId = "background-videos", asset = asset) ``` ## Full Code Here's the full code: ```kotlin import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import kotlinx.coroutines.withContext import ly.img.engine.Asset import ly.img.engine.AssetColor import ly.img.engine.AssetContext import ly.img.engine.AssetCredits import ly.img.engine.AssetDefinition import ly.img.engine.AssetLicense import ly.img.engine.AssetPayload import ly.img.engine.AssetSource import ly.img.engine.AssetUTM import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.FindAssetsQuery import ly.img.engine.FindAssetsResult import ly.img.engine.ShapeType import org.json.JSONArray import org.json.JSONObject import java.net.HttpURLConnection import java.net.URL fun customAssetSource( license: String, userId: String, unsplashBaseUrl: String, ) = CoroutineScope( Dispatchers.Main, ).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val source = UnsplashAssetSource(unsplashBaseUrl) // INSERT YOUR UNSPLASH PROXY URL HERE engine.asset.addSource(source) val list = runCatching { engine.asset.findAssets( sourceId = "ly.img.asset.source.unsplash", query = FindAssetsQuery(query = "", page = 1, perPage = 10), ) }.getOrElse { it.printStackTrace() } val search = runCatching { engine.asset.findAssets( sourceId = "ly.img.asset.source.unsplash", query = FindAssetsQuery(query = "banana", page = 1, perPage = 10), ) }.getOrElse { it.printStackTrace() } engine.asset.addLocalSource( sourceId = "background-videos", supportedMimeTypes = listOf("video/mp4"), ) val asset = AssetDefinition( id = "ocean-waves-1", label = mapOf( "en" to "relaxing ocean waves", "es" to "olas del mar relajantes", ), tags = mapOf( "en" to listOf("ocean", "waves", "soothing", "slow"), "es" to listOf("mar", "olas", "calmante", "lento"), ), meta = mapOf( "uri" to "https://example.com/ocean-waves-1.mp4", "thumbUri" to "https://example.com/thumbnails/ocean-waves-1.jpg", "mimeType" to "video/mp4", "width" to "1920", "height" to "1080", ), payload = AssetPayload(color = AssetColor.RGB(r = 0F, g = 0F, b = 1F)), ) engine.asset.addAsset(sourceId = "background-videos", asset = asset) engine.stop() } class UnsplashAssetSource( private val baseUrl: String, ) : AssetSource(sourceId = "ly.img.asset.source.unsplash") { override suspend fun getGroups(): List? = null override val supportedMimeTypes = listOf("image/jpeg") override val credits = AssetCredits( name = "Unsplash", uri = Uri.parse("https://unsplash.com/"), ) override val license = AssetLicense( name = "Unsplash license (free)", uri = Uri.parse("https://unsplash.com/license"), ) override suspend fun findAssets(query: FindAssetsQuery): FindAssetsResult = withContext(Dispatchers.IO) { if (query.query.isNullOrEmpty()) query.getPopularList() else query.getSearchList() } private suspend fun FindAssetsQuery.getPopularList(): FindAssetsResult { val queryParams = listOf( "order_by" to "popular", "page" to page + 1, "per_page" to perPage, ).joinToString(separator = "&") { (key, value) -> "$key=$value" } val assetsArray = getResponseAsString("$baseUrl/photos?$queryParams").let(::JSONArray) return FindAssetsResult( assets = (0 until assetsArray.length()).map { assetsArray.getJSONObject(it).toAsset() }, currentPage = page, nextPage = page + 1, total = Int.MAX_VALUE, ) } private suspend fun FindAssetsQuery.getSearchList(): FindAssetsResult { val queryParams = listOf( "query" to query, "page" to page + 1, "per_page" to perPage, ).joinToString(separator = "&") { (key, value) -> "$key=$value" } val response = getResponseAsString("$baseUrl/search/photos?$queryParams").let(::JSONObject) val assetsArray = response.getJSONArray("results") val total = response.getInt("total") val totalPages = response.getInt("total_pages") return FindAssetsResult( assets = (0 until assetsArray.length()).map { assetsArray.getJSONObject(it).toAsset() }, currentPage = page, nextPage = if (page == totalPages) -1 else page + 1, total = total, ) } private suspend fun getResponseAsString(url: String) = withContext(Dispatchers.IO) { val connection = URL(url).openConnection() as HttpURLConnection require(connection.responseCode in 200 until 300) { connection.errorStream.bufferedReader().use { it.readText() } } connection.inputStream.bufferedReader().use { it.readText() } } private fun JSONObject.toAsset() = Asset( id = getString("id"), locale = "en", label = when { !isNull("description") -> getString("description") !isNull("alt_description") -> getString("alt_description") else -> null }, tags = takeIf { has("tags") }?.let { getJSONArray("tags") }?.let { (0 until it.length()).map { index -> it.getJSONObject(index).getString("title") } }?.takeIf { it.isNotEmpty() }, meta = mapOf( "uri" to getJSONObject("urls").getString("full"), "thumbUri" to getJSONObject("urls").getString("thumb"), "blockType" to DesignBlockType.Graphic.key, "fillType" to FillType.Image.key, "shapeType" to ShapeType.Rect.key, "kind" to "image", "width" to getInt("width").toString(), "height" to getInt("height").toString(), ), context = AssetContext(sourceId = "unsplash"), credits = AssetCredits( name = getJSONObject("user").getString("name"), uri = getJSONObject("user") .takeIf { it.has("links") } ?.getJSONObject("links") ?.getString("html") ?.let { Uri.parse(it) }, ), utm = AssetUTM(source = "CE.SDK Demo", medium = "referral"), ) } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Overview" description: "Learn how to import, manage, and customize assets from local, remote, or camera sources in CE.SDK." platform: android url: "https://img.ly/docs/cesdk/android/import-media/overview-84bb23/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Import Media Assets](https://img.ly/docs/cesdk/android/import-media-4e3703/) > [Overview](https://img.ly/docs/cesdk/android/import-media/overview-84bb23/) --- In CE.SDK, assets are the building blocks of your creative workflow—whether they’re images, videos, audio, fonts, or templates. They power everything from basic image edits to dynamic, template-driven design generation. This guide gives you a high-level understanding of how to bring assets into CE.SDK, where they can come from, and how to decide on the right strategy for your application. Whether you're working with local uploads, remote storage, or third-party sources, this guide will help you navigate your options and build an efficient import pipeline. [Explore Demos](https://img.ly/showcases/cesdk?tags=android) [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) ## File Type Support CreativeEditor SDK (CE.SDK) supports importing high-resolution images, video, and audio content. ## Media Constraints ### Image Resolution Limits ### Video Resolution & Duration Limits --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Retrieve Mimetype" description: "Detect the file type of an asset to control how it’s handled or displayed." platform: android url: "https://img.ly/docs/cesdk/android/import-media/retrieve-mimetype-ed13bf/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Import Media Assets](https://img.ly/docs/cesdk/android/import-media-4e3703/) > [Retrieve Mimetype](https://img.ly/docs/cesdk/android/import-media/retrieve-mimetype-ed13bf/) --- When working with media assets in CE.SDK, it is often necessary to determine the mimetype of a resource before processing it. This guide explains how to use the `getMimeType(uri: Uri)` function to retrieve the mimetype of a given resource. Returns the mimetype of the resources at the given Uri. If the resource is not already downloaded, this function will download it. - `uri:` the Uri of the resource. - Returns the mimetype of the resource. ```kotlin // Get the mimetype of a resource val mimeType = engine.editor.getMimeType(Uri.parse("https://cdn.img.ly/assets/demo/v1/ly.img.image/images/sample_1.jpg")) ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Size Limits" description: "Learn about file size restrictions and how to optimize large assets for use in CE.SDK." platform: android url: "https://img.ly/docs/cesdk/android/import-media/size-limits-c32275/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Import Media Assets](https://img.ly/docs/cesdk/android/import-media-4e3703/) > [Size Limits](https://img.ly/docs/cesdk/android/import-media/size-limits-c32275/) --- CreativeEditor SDK (CE.SDK) supports importing high-resolution images, video, and audio, but there are practical limits to consider based on the user's device capabilities. ## Image Resolution Limits ## Video Resolution & Duration Limits --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Source Sets" description: "Use multiple versions of an asset to support different resolutions or formats." platform: android url: "https://img.ly/docs/cesdk/android/import-media/source-sets-5679c8/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Import Media Assets](https://img.ly/docs/cesdk/android/import-media-4e3703/) > [Source Sets](https://img.ly/docs/cesdk/android/import-media/source-sets-5679c8/) --- ```kotlin file=@cesdk_android_examples/engine-guides-source-sets/SourceSets.kt reference-only import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.Asset import ly.img.engine.AssetContext import ly.img.engine.AssetDefinition import ly.img.engine.AssetPayload import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType import ly.img.engine.Source fun sourceSets( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) engine.scene.zoomToBlock( block = page, paddingLeft = 50F, paddingTop = 50F, paddingRight = 50F, paddingBottom = 50F, ) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block, engine.block.createShape(ShapeType.Rect)) val imageFill = engine.block.createFill(FillType.Image) engine.block.setSourceSet( block = imageFill, property = "fill/image/sourceSet", sourceSet = listOf( Source( uri = Uri.parse("https://img.ly/static/ubq_samples/sample_1_512x341.jpg"), width = 512, height = 341, ), Source( uri = Uri.parse("https://img.ly/static/ubq_samples/sample_1_1024x683.jpg"), width = 1024, height = 683, ), Source( uri = Uri.parse("https://img.ly/static/ubq_samples/sample_1_2048x1366.jpg"), width = 2048, height = 1366, ), ), ) engine.block.setFill(block = block, fill = imageFill) engine.block.appendChild(parent = page, child = block) val assetWithSourceSet = AssetDefinition( id = "my-image", meta = mapOf( "kind" to "image", "fillType" to "//ly.img.ubq/fill/image", ), payload = AssetPayload( sourceSet = listOf( Source( uri = Uri.parse("https://img.ly/static/ubq_samples/sample_1_512x341.jpg"), width = 512, height = 341, ), Source( uri = Uri.parse("https://img.ly/static/ubq_samples/sample_1_1024x683.jpg"), width = 1024, height = 683, ), Source( uri = Uri.parse("https://img.ly/static/ubq_samples/sample_1_2048x1366.jpg"), width = 2048, height = 1366, ), ), ), ) engine.asset.addLocalSource( sourceId = "my-dynamic-images", supportedMimeTypes = listOf("image/jpeg"), ) engine.asset.addAsset(sourceId = "my-dynamic-images", asset = assetWithSourceSet) // Could also acquire the asset using `findAssets` on the source val asset = Asset( id = assetWithSourceSet.id, meta = assetWithSourceSet.meta?.toMap(), context = AssetContext(sourceId = "my-dynamic-images"), ) val result = engine.asset.defaultApplyAsset(asset) val videoFill = engine.block.createFill(FillType.Video) engine.block.setSourceSet( block = videoFill, property = "fill/video/sourceSet", sourceSet = listOf( Source( uri = Uri.parse("https://img.ly/static/example-assets/sourceset/1x.mp4"), width = 720, height = 1280, ), ), ) engine.block.addVideoFileUriToSourceSet( block = videoFill, property = "fill/video/sourceSet", uri = "https://img.ly/static/example-assets/sourceset/2x.mp4", ) engine.stop() } ``` Source sets allow specifying an entire set of sources, each with a different size, that should be used for drawing a block. The appropriate source is then dynamically chosen based on the current drawing size. This allows using the same scene to render a preview on a mobile screen using a small image file and a high-resolution file for print in the backend. This guide will show you how to specify source sets both for existing blocks and when defining assets. ### Drawing When an image needs to be drawn, the current drawing size in screen pixels is calculated and the engine looks up the most appropriate source file to draw at that resolution. 1. If a source set is set, the source with the closest size exceeding the drawing size is used 2. If no source set is set, the full resolution image is downscaled to a maximum edge length of 4096 (configurable via `maxImageSize` setting) and drawn to the target area This also gives more control about up- and downsampling to you, as all intermediate resolutions can be generated using tooling of your choice. **Source sets are also used during export of your designs and will resolve to the best matching asset for the export resolution.** ## Setup the scene We first create a new scene with a new page. ```kotlin highlight-setup val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) engine.scene.zoomToBlock( block = page, paddingLeft = 50F, paddingTop = 50F, paddingRight = 50F, paddingBottom = 50F, ) ``` ## Using a Source Set for an existing Block To make use of a source set for an existing image fill, we use the `setSourceSet` API. This defines a set of sources and specifies height and width for each of these sources. The engine then chooses the appropriate source during drawing. You may query an existing source set using `getSourceSet`. You can add sources to an existing source set with `addImageFileURIToSourceSet`. ```kotlin highlight-set-source-set val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block, engine.block.createShape(ShapeType.Rect)) val imageFill = engine.block.createFill(FillType.Image) engine.block.setSourceSet( block = imageFill, property = "fill/image/sourceSet", sourceSet = listOf( Source( uri = Uri.parse("https://img.ly/static/ubq_samples/sample_1_512x341.jpg"), width = 512, height = 341, ), Source( uri = Uri.parse("https://img.ly/static/ubq_samples/sample_1_1024x683.jpg"), width = 1024, height = 683, ), Source( uri = Uri.parse("https://img.ly/static/ubq_samples/sample_1_2048x1366.jpg"), width = 2048, height = 1366, ), ), ) engine.block.setFill(block = block, fill = imageFill) engine.block.appendChild(parent = page, child = block) ``` ## Using a Source Set in an Asset For assets, source sets can be defined in the `payload.sourceSet` field. This is directly translated to the `sourceSet` property when applying the asset. The resulting block is configured in the same way as the one described above. The code demonstrates how to add an asset that defines a source set to a local source and how `applyAsset` handles a populated `payload.sourceSet`. ```kotlin highlight-asset-definition val assetWithSourceSet = AssetDefinition( id = "my-image", meta = mapOf( "kind" to "image", "fillType" to "//ly.img.ubq/fill/image", ), payload = AssetPayload( sourceSet = listOf( Source( uri = Uri.parse("https://img.ly/static/ubq_samples/sample_1_512x341.jpg"), width = 512, height = 341, ), Source( uri = Uri.parse("https://img.ly/static/ubq_samples/sample_1_1024x683.jpg"), width = 1024, height = 683, ), Source( uri = Uri.parse("https://img.ly/static/ubq_samples/sample_1_2048x1366.jpg"), width = 2048, height = 1366, ), ), ), ) ``` ## Video Source Sets Source sets can also be used for video fills. This is done by setting the `sourceSet` property of the video fill. The engine will then use the source with the closest size exceeding the drawing size. Thumbnails will use the smallest source if `features/matchThumbnailSourceToFill` is disabled, which is the default. For low end devices or scenes with large videos, you can force the preview to always use the smallest source when editing by enabling `features/forceLowQualityVideoPreview`. On export, the highest quality source is used in any case. ```kotlin highlight-video-source-sets val videoFill = engine.block.createFill(FillType.Video) engine.block.setSourceSet( block = videoFill, property = "fill/video/sourceSet", sourceSet = listOf( Source( uri = Uri.parse("https://img.ly/static/example-assets/sourceset/1x.mp4"), width = 720, height = 1280, ), ), ) engine.block.addVideoFileUriToSourceSet( block = videoFill, property = "fill/video/sourceSet", uri = "https://img.ly/static/example-assets/sourceset/2x.mp4", ) ``` ## Full Code Here's the full code: ```kotlin import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.Asset import ly.img.engine.AssetContext import ly.img.engine.AssetDefinition import ly.img.engine.AssetPayload import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType import ly.img.engine.Source fun sourceSets( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) engine.scene.zoomToBlock( block = page, paddingLeft = 50F, paddingTop = 50F, paddingRight = 50F, paddingBottom = 50F, ) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block, engine.block.createShape(ShapeType.Rect)) val imageFill = engine.block.createFill(FillType.Image) engine.block.setSourceSet( block = imageFill, property = "fill/image/sourceSet", sourceSet = listOf( Source( uri = Uri.parse("https://img.ly/static/ubq_samples/sample_1_512x341.jpg"), width = 512, height = 341, ), Source( uri = Uri.parse("https://img.ly/static/ubq_samples/sample_1_1024x683.jpg"), width = 1024, height = 683, ), Source( uri = Uri.parse("https://img.ly/static/ubq_samples/sample_1_2048x1366.jpg"), width = 2048, height = 1366, ), ), ) engine.block.setFill(block = block, fill = imageFill) engine.block.appendChild(parent = page, child = block) val assetWithSourceSet = AssetDefinition( id = "my-image", meta = mapOf( "kind" to "image", "fillType" to "//ly.img.ubq/fill/image", ), payload = AssetPayload( sourceSet = listOf( Source( uri = Uri.parse("https://img.ly/static/ubq_samples/sample_1_512x341.jpg"), width = 512, height = 341, ), Source( uri = Uri.parse("https://img.ly/static/ubq_samples/sample_1_1024x683.jpg"), width = 1024, height = 683, ), Source( uri = Uri.parse("https://img.ly/static/ubq_samples/sample_1_2048x1366.jpg"), width = 2048, height = 1366, ), ), ), ) engine.asset.addLocalSource( sourceId = "my-dynamic-images", supportedMimeTypes = listOf("image/jpeg"), ) engine.asset.addAsset(sourceId = "my-dynamic-images", asset = assetWithSourceSet) // Could also acquire the asset using `findAssets` on the source val asset = Asset( id = assetWithSourceSet.id, meta = assetWithSourceSet.meta?.toMap(), context = AssetContext(sourceId = "my-dynamic-images"), ) val result = engine.asset.defaultApplyAsset(asset) val videoFill = engine.block.createFill(FillType.Video) engine.block.setSourceSet( block = videoFill, property = "fill/video/sourceSet", sourceSet = listOf( Source( uri = Uri.parse("https://img.ly/static/example-assets/sourceset/1x.mp4"), width = 720, height = 1280, ), ), ) engine.block.addVideoFileUriToSourceSet( block = videoFill, property = "fill/video/sourceSet", uri = "https://img.ly/static/example-assets/sourceset/2x.mp4", ) engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Insert Media Into Scenes" description: "Understand how insertion works, how inserted media behave within scenes, and how to control them via UI or code." platform: android url: "https://img.ly/docs/cesdk/android/insert-media-a217f5/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Insert Media Assets](https://img.ly/docs/cesdk/android/insert-media-a217f5/) --- --- ## Related Pages - [Overview](https://img.ly/docs/cesdk/android/overview-491658/) - Understand how insertion works, how inserted media behave within scenes, and how to control them via UI or code. - [Insert Images](https://img.ly/docs/cesdk/android/insert-media/images-63848a/) - Add still images to CE.SDK scenes programmatically using Kotlin or using the built-in Android editor UI. Includes positioning, layering, sizing and format considerations. - [Insert Shapes or Stickers](https://img.ly/docs/cesdk/android/insert-media/shapes-or-stickers-20ac68/) - Add shapes and stickers to your designs using CE.SDK. Create rectangles, ellipses, stars, polygons, lines, and custom vector paths programmatically or through the built-in UI. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Insert Images" description: "Add still images to CE.SDK scenes programmatically using Kotlin or using the built-in Android editor UI. Includes positioning, layering, sizing and format considerations." platform: android url: "https://img.ly/docs/cesdk/android/insert-media/images-63848a/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Insert Media Assets](https://img.ly/docs/cesdk/android/insert-media-a217f5/) > [Insert Images](https://img.ly/docs/cesdk/android/insert-media/images-63848a/) --- ```kotlin file=@cesdk_android_examples/engine-guides-modifying-scenes/ModifyingScenes.kt reference-only import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun modifyingScenes( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) // In engine only mode we have to create our own scene and page. if (engine.scene.get() == null) { val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) } // Find all pages in our scene. val pages = engine.block.findByType(DesignBlockType.Page) // Use the first page we found. val page = pages.first() // Create a graphic block and add it to the scene's page. val block = engine.block.create(DesignBlockType.Graphic) val fill = engine.block.createFill(FillType.Image) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) engine.block.setFill(block = block, fill = fill) engine.block.setString( block = fill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/imgly_logo.jpg", ) // The content fill mode 'Contain' ensures the entire image is visible. engine.block.setEnum( block = block, property = "contentFill/mode", value = "Contain", ) engine.block.appendChild(parent = page, child = block) // Zoom the scene's camera on our page. engine.scene.zoomToBlock(page) engine.stop() } ``` You can insert images into a scene using CE.SDK, either through the prebuilt UI for Android or programmatically via Kotlin. This gives you the flexibility to build interactive design workflows, enable user-generated content, or automate image placement based on logic or data. > **Note:** CE.SDK supports a wide range of image formats, including:* `.png` > * `.jpeg`, `.jpg` > * `.gif` > * `.webp` > * `.svg` > * `.bmp`See a [full list](https://img.ly/docs/cesdk/android/file-format-support-3c4b2a/) of supported file types. ## What You'll Learn - Two ways to insert images: - Programmatically by creating a graphic block, applying an image fill, and setting its position/size/rotation/z-index. - With Editor UI using the controls and asset libraries of a prebuilt editor such as the Design Editor or Photo Editor. - Supported image sources such as app assets, file URIs, and remote URLs. - Practical transforms after insertion such as move, scale, rotate and order. ## When to Use It - You're building custom UI or automation flow to add images to compositions. - You want a ready-made editing experience on Android with an image picker and panels. ## Inserting Images Using the UI CE.SDK's UI includes a built-in **image tool** that lets users add images from device sources directly onto the canvas. Once inserted, users can move, resize, crop, rotate, or stack images visually. **Supported image sources:** - Gallery (Photos app) - Storage (Files app) - Camera (device camera) - Image (project asset library) In the Asset Library, a user can add images from the Gallery, the camera or the Files app. You can customize how the image tool appears in the user interface. ## Inserting Images Programmatically For apps with automation, batch workflows, or logic-driven design experiences, you can insert images into a scene using the block API and the graphics engine. Here's how to do it: ```kotlin // 1. Create a graphic block val imageBlock = engine.block.create(DesignBlockType.Graphic) // 2. Create a shape for the image val shape = engine.block.createShape(ShapeType.Rect) engine.block.setShape(imageBlock, shape = shape) // 3. Create an image fill val imageFill = engine.block.createFill(FillType.Image) engine.block.setString( block = imageFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_4.jpg" ) engine.block.setFill(imageBlock, fill = imageFill) // 4. (Optional) Set semantic kind to "image" for clarity engine.block.setKind(imageBlock, kind = "image") // 5. Add image to the scene val page = engine.block.findByType(DesignBlockType.Page).first() engine.block.appendChild(page, child = imageBlock) ``` The `shape` can be any of the supported shapes like `ShapeType.Rect`, `ShapeType.Star`, etc and masks the inserted image. The asset URI in step 3 can either be a remote URL or a local asset URI. For assets from app resources, use a URI: ```kotlin import android.net.Uri val uri = Uri.parse("file:///android_asset/images/poster.jpg") ``` For file assets, use standard Android file handling: ```kotlin import android.net.Uri import java.io.File val file = File(context.filesDir, "uploads/avatar.png") val uri = Uri.fromFile(file) ``` When working with the asset catalog, you can apply an image that's an `AssetResult` either to: - The scene directly - A block ```kotlin val assetList = engine.asset.findAssets(sourceId, queryData) val newAsset = assetList.assets.first() // Creates a new block that contains the image val imageBlock = engine.asset.defaultApplyAsset(newAsset) // Applies the image to a block that already exists engine.asset.defaultApplyAssetToBlock(newAsset, someBlock) ``` ## Image Properties After inserting the image, you can change the block's layout properties using standard methods in the `engine.block` API. ### Positioning Refer to the guide in the Transform Section for [Move](https://img.ly/docs/cesdk/android/edit-image/transform/move-818dd9/) for more details and other options. ```kotlin // Set X/Y position on the canvas (in absolute units) engine.block.setPositionX(imageBlock, value = 100f) engine.block.setPositionY(imageBlock, value = 200f) ``` ### Scaling Refer to the guide in the Transform Section for [Scale](https://img.ly/docs/cesdk/android/edit-image/transform/scale-ebe367/) for more details and other options. ```kotlin // Uniform scale engine.block.setFloat(imageBlock, property = "transform/scale/x", value = 1.5f) engine.block.setFloat(imageBlock, property = "transform/scale/y", value = 1.5f) // Non-uniform (stretching) engine.block.setFloat(imageBlock, property = "transform/scale/x", value = 2.0f) engine.block.setFloat(imageBlock, property = "transform/scale/y", value = 1.0f) ``` ### Rotation Refer to the guide in the Transform Section for [Rotate](https://img.ly/docs/cesdk/android/edit-image/transform/rotate-5f39c9/) for more details and other options. ```kotlin // Rotate 45 degrees (in radians) import kotlin.math.PI val degrees = 45.0 val radians = (degrees * PI / 180).toFloat() engine.block.setFloat(imageBlock, property = "transform/rotation", value = radians) ``` ### Layering Control stack order using the helper methods to move blocks forward (towards the user) or backwards. You can also pin a block to the front or back of the stack. ```kotlin engine.block.bringToFront(imageBlock) // Move above siblings engine.block.sendToBack(imageBlock) // Move below siblings engine.block.bringForward(imageBlock) // One step forward engine.block.sendBackward(imageBlock) // One step backward engine.block.setAlwaysOnTop(imageBlock, enabled = true) ``` > **Note:** You can also group images and other elements using `engine.block.group()` for easier layer management. ## Insert Into an Existing Block If your template exposes a placeholder block or you are creating an automated workflow, you can **replace an image fill** instead of creating a new block. Locate the block using its `name` property or by its known `id`. When you know the `id` of the target: ```kotlin val fill = engine.block.createFill(FillType.Image) engine.block.setString(fill, property = "fill/image/imageFileURI", value = imageURI) engine.block.setFill(targetBlock, fill = fill) ``` When you're using the `name` property to find the block, you need to search manually: ```kotlin val allBlocks = engine.block.findByType(DesignBlockType.Graphic) val targetBlock = allBlocks.find { block -> engine.block.getString(block, property = "name") == "HeroTile" } ?: return val fill = engine.block.createFill(FillType.Image) engine.block.setString(fill, property = "fill/image/imageFileURI", value = imageURI) engine.block.setFill(targetBlock, fill = fill) ``` > **Note:** When generating templates, assign names so downstream replacement stays straightforward:```kotlin > engine.block.setString(imageBlock, property = "name", value = "HeroImage") > ``` ## Troubleshooting **❌ Nothing appears after insert**: - Verify that the block is attached to the page. - Verify the URI string is correct. - Check the scene's current zoom and camera framing. **❌ Remote images fail**: - Confirm HTTPS and CORS settings. - Verify network permissions in AndroidManifest.xml. - Test the URL in a browser. **❌ Pixelated result**: - Change the block size or use a higher-resolution source image. **❌ Unexpected orientation of image**: - Some formats carry EXIF orientation information. Apply `setRotation` or normalize the asset during import. ## Next Steps Now that you've learned about inserting images into your compositions, here are some topics to explore to deepen your understanding. - Apply more [transformations](https://img.ly/docs/cesdk/android/edit-image/transform-9d189b/) such as crop, or scale. - Create [templates](https://img.ly/docs/cesdk/android/create-templates-3aef79/) for automating content creation and formatting. - [Export](https://img.ly/docs/cesdk/android/export-save-publish/export-82f968/) compositions in a variety of formats. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Positioning and Alignment" description: "Precisely position, align, and distribute objects using guides, snapping, and alignment tools." platform: android url: "https://img.ly/docs/cesdk/android/insert-media/position-and-align-cc6b6a/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Compositions](https://img.ly/docs/cesdk/android/create-composition-db709c/) > [Position and Align](https://img.ly/docs/cesdk/android/insert-media/position-and-align-cc6b6a/) --- ```kotlin reference-only val x = engine.block.getPositionX(block) val xMode = engine.block.getPositionXMode(block) val y = engine.block.getPositionY(block) val yMode = engine.block.getPositionYMode(block) engine.block.setPositionX(block, value = 0.25F) engine.block.setPositionXMode(block, mode = PositionMode.PERCENT) engine.block.setPositionY(block, value = 0.25) engine.block.setPositionYMode(block, mode = PositionMode.PERCENT) val rad = engine.block.getRotation(block) engine.block.setRotation(block, radians = PI.toFloat()) val isFlipHorizontal = engine.block.isFlipHorizontal(block) val isFlipVertical = engine.block.isFlipVertical(block) engine.block.setFlipHorizontal(block, flip = true) engine.block.setFlipVertical(block, flip = false) val width = engine.block.getWidth(block) val widthMode = engine.block.getWidthMode(block) val height = engine.block.getHeight(block) val heightMode = engine.block.getHeightMode(block) engine.block.setWidth(block, value = 0.5F) engine.block.setWidth(block, value = 2.5F, maintainCrop = true) engine.block.setWidthMode(block, mode = SizeMode.PERCENT) engine.block.setHeight(block, value = 0.5F) engine.block.setHeight(block, value = 2.5F, maintainCrop = true) engine.block.setHeightMode(block, mode = SizeMode.PERCENT) val frameX = engine.block.getFrameX(block) val frameY = engine.block.getFrameY(block) val frameWidth = engine.block.getFrameWidth(block) val frameHeight = engine.block.getFrameHeight(block) engine.block.setAlwaysOnTop(block, false) val isAlwaysOnTop = engine.block.isAlwaysOnTop(block) engine.block.setAlwaysOnBottom(block, false) val isAlwaysOnBottom = engine.block.isAlwaysOnBottom(block) engine.block.bringToFront(block) engine.block.sendToBack(block) engine.block.bringForward(block) engine.block.sendBackward(block) val globalX = engine.block.getGlobalBoundingBoxX(block) val globalY = engine.block.getGlobalBoundingBoxY(block) val globalWidth = engine.block.getGlobalBoundingBoxWidth(block) val globalHeight = engine.block.getGlobalBoundingBoxHeight(block) val screenSpaceRect = engine.block.getScreenSpaceBoundingBoxRect(listOf(block)) engine.block.scale(block, scale = 2F, anchorX = 0.5F, anchorY = 0.5F) engine.block.fillParent(block) val pages = engine.scene.getPages() engine.block.resizeContentAware(pages, width = 100F, height = 100F) // Create blocks and append to scene val member1 = engine.block.create(DesignBlockType.Graphic) val member2 = engine.block.create(DesignBlockType.Graphic) engine.block.appendChild(scene, child = member1) engine.block.appendChild(scene, child = member2) if (engine.block.isDistributable(listOf(member1, member2))) { engine.block.distributeHorizontally(listOf(member1, member2)) engine.block.distributeVertically(listOf(member1, member2)) } if (engine.block.isAlignable(listOf(member1, member2))) { engine.block.alignHorizontally(listOf(member1, member2), alignment = HorizontalBlockAlignment.LEFT) engine.block.alignVertically(listOf(member1, member2), alignment = VerticalBlockAlignment.TOP) } val isTransformLocked = engine.block.isTransformLocked(block) if (!isTransformLocked) { engine.block.setTransformLocked(block, locked = true) } ``` In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to modify scenes layout through the `block` API. ## Layout of Blocks > **Note:** **Note on layout and frame size** The frame size is determined during the > layout phase of the render process inside the engine. This means that calling > `getFrameSize()` immediately after modifying the scene might return an > inaccurate result. The CreativeEngine supports three different modes for positioning blocks. These can be set for each block and both coordinates independently: - `Absolute`: the position value is interpreted in the scene's current design unit. - `Percent`: the position value is interpreted as percentage of the block's parent's size, where 1F means 100%. - `Auto` : the position is automatically determined. Likewise there are also three different modes for controlling a block's size. Again both dimensions can be set independently: - `Absolute`: the size value is interpreted in the scene's current design unit. - `Percent`: the size value is interpreted as percentage of the block's parent's size, where 1F means 100%. - `Auto` : the block's size is automatically determined by the size of the block's content. ### Positioning ```kotlin fun getPositionX(block: DesignBlock): Float ``` Query a block's x position. - `block`: the block to query. - Returns the value of the x position. ```kotlin fun getPositionY(block: DesignBlock): Float ``` Query a block's y position. - `block`: the block to query. - Returns the value of the y position. ```kotlin fun getPositionXMode(block: DesignBlock): PositionMode ``` Query a block's mode for its x position. - `block`: the block to query. - Returns the current mode for the x position. ```kotlin fun getPositionYMode(block: DesignBlock): PositionMode ``` Query a block's mode for its y position. - `block`: the block to query. - Returns the current mode for the y position. ```kotlin fun setPositionX( block: DesignBlock, value: Float, ) ``` Update a block's x position. The position refers to the block's local space, relative to its parent with the origin at the top left. Required scope: "layer/move" - `block`: the block to update. - `value`: the value of the x position. ```kotlin fun setPositionY( block: DesignBlock, value: Float, ) ``` Update a block's y position. The position refers to the block's local space, relative to its parent with the origin at the top left. Required scope: "layer/move" - `block`: the block to update. - `value`: the value of the y position. ```kotlin fun setPositionXMode( block: DesignBlock, mode: PositionMode, ) ``` Set a block's mode for its x position. The position refers to the block's local space, relative to its parent with the origin at the top left. Required scope: "layer/move" - `block`: the block to update. - `mode`: the x position mode. ```kotlin fun setPositionYMode( block: DesignBlock, mode: PositionMode, ) ``` Set a block's mode for its y position. The position refers to the block's local space, relative to its parent with the origin at the top left. Required scope: "layer/move" - `block`: the block to update. - `mode`: the y position mode. ### Size ```kotlin fun getWidth(block: DesignBlock): Float ``` Query a block's width. - `block`: the block to query. - Returns the value of the block's width. ```kotlin fun getWidthMode(block: DesignBlock): SizeMode ``` Query a block's mode for its width. - `block`: the block to query. - Returns the current mode for the width. ```kotlin fun getHeight(block: DesignBlock): Float ``` Query a block's height. - `block`: the block to query. - Returns the value of the block's height. ```kotlin fun getHeightMode(block: DesignBlock): SizeMode ``` Query a block's mode for its height. - `block`: the block to query. - Returns the current mode for the height. ```kotlin fun setWidth( block: DesignBlock, value: Float, maintainCrop: Boolean = false, ) ``` Update a block's width and optionally maintain the crop. If the crop is maintained, the crop values will be automatically adjusted. The content fill mode `Cover` is only kept if the `features/transformEditsRetainCoverMode` setting is enabled, otherwise it will change to `Crop`. Required scope: "layer/resize" - `block`: the block to update. - `value`: the new width of the block. - `maintainCrop`: whether or not the crop values, if available, should be automatically adjusted. ```kotlin fun setWidthMode( block: DesignBlock, mode: SizeMode, ) ``` Set a block's mode for its width. Required scope: "layer/resize" - `block`: the block to update. - `mode`: the width mode. ```kotlin fun setHeight( block: DesignBlock, value: Float, maintainCrop: Boolean = false, ) ``` Update a block's height and optionally maintain the crop. If the crop is maintained, the crop values will be automatically adjusted. The content fill mode `Cover` is only kept if the `features/transformEditsRetainCoverMode` setting is enabled, otherwise it will change to `Crop`. Required scope: "layer/resize" - `block`: the block to update. - `value`: the new height of the block. - `maintainCrop`: whether or not the crop values, if available, should be automatically adjusted. ```kotlin fun setHeightMode( block: DesignBlock, mode: SizeMode, ) ``` Set a block's mode for its height. Required scope: "layer/resize" - `block`: the block to update. - `mode`: the height mode. ### Rotation ```kotlin fun getRotation(block: DesignBlock): Float ``` Query a block's rotation in radians. - `block`: the block to query. - Returns the block's rotation around its center in radians. ```kotlin fun setRotation( block: DesignBlock, radians: Float, ) ``` Update a block's rotation. Required scope: "layer/rotate" - `block`: the block to update. - `radians`: the new rotation in radians. Rotation is applied around the block's center. ### Flipping ```kotlin fun setFlipHorizontal( block: DesignBlock, flip: Boolean, ) ``` Update a block's horizontal flip. Required scope: "layer/flip" - `block`: the block to update. - `flip`: if the flip should be enabled. ```kotlin fun isFlipHorizontal(block: DesignBlock): Boolean ``` Query a block's horizontal flip state. - `block`: the block to query. - Returns a boolean indicating for whether the block is flipped in the queried direction. ```kotlin fun setFlipVertical( block: DesignBlock, flip: Boolean, ) ``` Update a block's vertical flip. Required scope: "layer/flip" - `block`: the block to update. - `flip`: if the flip should be enabled. ```kotlin fun isFlipVertical(block: DesignBlock): Boolean ``` Query a block's vertical flip state. - `block`: the block to query. - Returns a boolean indicating for whether the block is flipped in the queried direction. ### Scaling ```kotlin fun scale( block: DesignBlock, scale: Float, @FloatRange(from = 0.0, to = 1.0) anchorX: Float, @FloatRange(from = 0.0, to = 1.0) anchorY: Float, ) ``` Scales the block and all of its children proportionally around the specified relative anchor point. This updates the position, size and style properties (e.g. stroke width) of the block and its children. Required scope: "layer/resize" - `block`: the block that should be scaled. - `scale`: the scale factor to be applied to the current properties of the block. - `anchorX`: the relative position along the width of the block around which the scaling should occur. (0F = left edge, 0.5F = center, 1F = right edge) - `anchorY`: the relative position along the height of the block around which the scaling should occur. (0F = top edge, 0.5F = center, 1F = bottom edge) ### Fill a Block's Parent ```kotlin fun fillParent(block: DesignBlock) ``` Resize and position a block to entirely fill its parent block. The crop values of the block, except for the flip and crop rotation, are reset if it can be cropped. If the size of the block's fill is unknown, the content fill mode is changed from `Crop` to `Cover` to prevent invalid crop values. Required scope: "layer/move" - "layer/resize" - `block`: The block that should fill its parent. ### Resize Blocks Content-aware ```kotlin fun resizeContentAware( blocks: List, width: Float, height: Float, ) ``` Resize all blocks to the given size. The content of the blocks is automatically adjusted to fit the new dimensions. Required scope: "layer/resize" - `blocks`: The blocks to resize. - `width`: The new width of the blocks. - `height`: The new height of the blocks. ### Even Distribution ```kotlin fun isDistributable(blocks: List): Boolean ``` Confirms that a given set of blocks can be distributed. - `blocks`: a non-empty array of block ids. - Returns whether the blocks can be distributed. ```kotlin fun distributeHorizontally(blocks: List) ``` Distribute multiple blocks vertically within their bounding box so that the space between them is even. Required scope: "layer/move" - `blocks`: a non-empty array of block ids that should be distributed. ```kotlin fun distributeVertically(blocks: List) ``` Distribute multiple blocks vertically within their bounding box so that the space between them is even. Required scope: "layer/move" - `blocks`: a non-empty array of block ids that should be distributed. ### Alignment ```kotlin fun isAlignable(blocks: List): Boolean ``` Confirms that a given set of blocks can be aligned. - `blocks`: a non-empty array of block ids. - Returns whether the blocks can be aligned. ```kotlin fun alignHorizontally( blocks: List, alignment: HorizontalBlockAlignment, ) ``` Align multiple blocks vertically within their bounding box or a single block to its parent. Required scope: "layer/move" - `blocks`: a non-empty array of block ids that should be aligned. - `alignment`: How they should be aligned: left, right, or center ```kotlin fun alignVertically( blocks: List, alignment: VerticalBlockAlignment, ) ``` Align multiple blocks vertically within their bounding box or a single block to its parent. Required scope: "layer/move" - `blocks`: a non-empty array of block ids that should be aligned. - `alignment`: How they should be aligned: top, bottom, or center ### Computed Dimensions ```kotlin fun getFrameX(block: DesignBlock): Float ``` Get a block's layout position on the x-axis. The layout position is only available after an internal update loop, which may not happen immediately. - `block`: the block to query. - Returns the layout position. ```kotlin fun getFrameY(block: DesignBlock): Float ``` Get a block's layout position on the y-axis. The layout position is only available after an internal update loop, which may not happen immediately. - `block`: the block to query. - Returns the layout position. ```kotlin fun getFrameWidth(block: DesignBlock): Float ``` Get a block's layout width. The layout width is only available after an internal update loop, which may not happen immediately. - `block`: the block to query. - Returns the layout width. ```kotlin fun getFrameHeight(block: DesignBlock): Float ``` Get a block's layout height. The layout height is only available after an internal update loop, which may not happen immediately. - `block`: the block to query. - Returns the layout height. ```kotlin fun getGlobalBoundingBoxX(block: DesignBlock): Float ``` Get the x position of the block's axis-aligned bounding box in the scene's global coordinate space. The scene's global coordinate space has its origin at the top left. - `block`: the block to query. - Returns the x coordinate of the position of the axis-aligned bounding box. ```kotlin fun getGlobalBoundingBoxY(block: DesignBlock): Float ``` Get the y position of the block's axis-aligned bounding box in the scene's global coordinate space. The scene's global coordinate space has its origin at the top left. - `block`: the block to query. - Returns the y coordinate of the position of the axis-aligned bounding box. ```kotlin fun getGlobalBoundingBoxWidth(block: DesignBlock): Float ``` Get the width of the block's axis-aligned bounding box in the scene's global coordinate space. The scene's global coordinate space has its origin at the top left. - `block`: the block to query. - Returns the width of the axis-aligned bounding box. ```kotlin fun getGlobalBoundingBoxHeight(block: DesignBlock): Float ``` Get the height of the block's axis-aligned bounding box in the scene's global coordinate space. The scene's global coordinate space has its origin at the top left. - `block`: the block to query. - Returns the height of the axis-aligned bounding box. ```kotlin fun getScreenSpaceBoundingBoxRect(blocks: List): RectF ``` Get the position and size of the axis-aligned bounding box for the given blocks in screen space. - `blocks`: the blocks whose bounding box should be calculated. - Returns the position and size of the bounding box as RectF. ### Layers ```kotlin fun setAlwaysOnTop( block: DesignBlock, enabled: Boolean, ) ``` Update the block's always-on-top property. If true, this blocks's global sorting order is automatically adjusted to be higher than all other siblings without this property. If more than one block is set to be always-on-top, the child order decides which is on top. - `block`: the block to update. - `enabled`: whether the block shall be always-on-top. ```kotlin fun isAlwaysOnTop(block: DesignBlock): Boolean ``` Query a block's always-on-top property. - `block`: the block to query. - Returns true if the block is set to be always-on-top, false otherwise. ```kotlin fun setAlwaysOnBottom( block: DesignBlock, enabled: Boolean, ) ``` Update the block's always-on-bottom property. If true, this blocks's global sorting order is automatically adjusted to be lower than all other siblings without this property. If more than one block is set to be always-on-bottom, the child order decides which is on the bottom. - `block`: the block to update. - `enabled`: whether the block shall be always-on-bottom. ```kotlin fun isAlwaysOnBottom(block: DesignBlock): Boolean ``` Query a block's always-on-bottom property. - `block`: the block to query. - Returns true if the block is set to be always-on-bottom, false otherwise. ```kotlin fun bringToFront(block: DesignBlock) ``` Updates the sorting order of this block and all of its manually created siblings so that the given block has the highest sorting order. If the block is parented to a track, it is first moved up in the hierarchy. - `block`: the block to be given the highest sorting order among its siblings. ```kotlin fun sendToBack(block: DesignBlock) ``` Updates the sorting order of this block and all of its manually created siblings so that the given block has the lowest sorting order. If the block is parented to a track, it is first moved up in the hierarchy. - `block`: the block to be given the lowest sorting order among its siblings. ```kotlin fun bringForward(block: DesignBlock) ``` Updates the sorting order of this block and all of its superjacent siblings so that the given block has a higher sorting order than the next superjacent sibling. If the block is parented to a track, it is first moved up in the hierarchy. Empty tracks and empty groups are passed by. - `block`: the block to be given a higher sorting than the next superjacent sibling. ```kotlin fun sendBackward(block: DesignBlock) ``` Updates the sorting order of this block and all of its manually created and subjacent siblings so that the given block will have a lower sorting order than the next subjacent sibling. If the block is parented to a track, it is first moved up in the hierarchy. Empty tracks and empty groups are passed by. - `block`: the block to be given a lower sorting order than the next subjacent sibling. ### Transform Locking You can lock the transform of a block to prevent changes to any of its transformations. That is the block's position, rotation, scale, and sizing. ```kotlin fun isTransformLocked(block: DesignBlock): Boolean ``` Query a block's transform locked state. If `true`, the block's transform can't be changed. - `block`: the block to query. - Returns true if block is locked, false otherwise. ```kotlin fun setTransformLocked( block: DesignBlock, locked: Boolean, ) ``` Update a block's transform locked state. - `block`: the block to update. - `locked`: whether the block's transform should be locked. ## Full Code Here's the full code: ```kotlin val x = engine.block.getPositionX(block) val xMode = engine.block.getPositionXMode(block) val y = engine.block.getPositionY(block) val yMode = engine.block.getPositionYMode(block) engine.block.setPositionX(block, value = 0.25F) engine.block.setPositionXMode(block, mode = PositionMode.PERCENT) engine.block.setPositionY(block, value = 0.25) engine.block.setPositionYMode(block, mode = PositionMode.PERCENT) val rad = engine.block.getRotation(block) engine.block.setRotation(block, radians = PI.toFloat()) val isFlipHorizontal = engine.block.isFlipHorizontal(block) val isFlipVertical = engine.block.isFlipVertical(block) engine.block.setFlipHorizontal(block, flip = true) engine.block.setFlipVertical(block, flip = false) val width = engine.block.getWidth(block) val widthMode = engine.block.getWidthMode(block) val height = engine.block.getHeight(block) val heightMode = engine.block.getHeightMode(block) engine.block.setWidth(block, value = 0.5F) engine.block.setWidth(block, value = 2.5F, maintainCrop = true) engine.block.setWidthMode(block, mode = SizeMode.PERCENT) engine.block.setHeight(block, value = 0.5F) engine.block.setHeight(block, value = 2.5F, maintainCrop = true) engine.block.setHeightMode(block, mode = SizeMode.PERCENT) val frameX = engine.block.getFrameX(block) val frameY = engine.block.getFrameY(block) val frameWidth = engine.block.getFrameWidth(block) val frameHeight = engine.block.getFrameHeight(block) engine.block.setAlwaysOnTop(block, false) val isAlwaysOnTop = engine.block.isAlwaysOnTop(block) engine.block.setAlwaysOnBottom(block, false) val isAlwaysOnBottom = engine.block.isAlwaysOnBottom(block) engine.block.bringToFront(block) engine.block.sendToBack(block) engine.block.bringForward(block) engine.block.sendBackward(block) val globalX = engine.block.getGlobalBoundingBoxX(block) val globalY = engine.block.getGlobalBoundingBoxY(block) val globalWidth = engine.block.getGlobalBoundingBoxWidth(block) val globalHeight = engine.block.getGlobalBoundingBoxHeight(block) val screenSpaceRect = engine.block.getScreenSpaceBoundingBoxRect(listOf(block)) engine.block.scale(block, scale = 2F, anchorX = 0.5F, anchorY = 0.5F) engine.block.fillParent(block) val pages = engine.scene.getPages() engine.block.resizeContentAware(pages, width = 100F, height = 100F) // Create blocks and append to scene val member1 = engine.block.create(DesignBlockType.Graphic) val member2 = engine.block.create(DesignBlockType.Graphic) engine.block.appendChild(scene, child = member1) engine.block.appendChild(scene, child = member2) if (engine.block.isDistributable(listOf(member1, member2))) { engine.block.distributeHorizontally(listOf(member1, member2)) engine.block.distributeVertically(listOf(member1, member2)) } if (engine.block.isAlignable(listOf(member1, member2))) { engine.block.alignHorizontally(listOf(member1, member2), alignment = HorizontalBlockAlignment.LEFT) engine.block.alignVertically(listOf(member1, member2), alignment = VerticalBlockAlignment.TOP) } val isTransformLocked = engine.block.isTransformLocked(block) if (!isTransformLocked) { engine.block.setTransformLocked(block, locked = true) } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Insert Shapes or Stickers" description: "Add shapes and stickers to your designs using CE.SDK. Create rectangles, ellipses, stars, polygons, lines, and custom vector paths programmatically or through the built-in UI." platform: android url: "https://img.ly/docs/cesdk/android/insert-media/shapes-or-stickers-20ac68/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Insert Media Assets](https://img.ly/docs/cesdk/android/insert-media-a217f5/) > [Insert Shapes or Stickers](https://img.ly/docs/cesdk/android/insert-media/shapes-or-stickers-20ac68/) --- --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Key Capabilities" description: "Explore CE.SDK’s key features—manual editing, automation, templates, AI tools, and full UI and API control." platform: android url: "https://img.ly/docs/cesdk/android/key-capabilities-dbb5b1/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Concepts](https://img.ly/docs/cesdk/android/concepts-c9ff51/) > [Key Capabilities](https://img.ly/docs/cesdk/android/key-capabilities-dbb5b1/) --- This guide gives you a high-level look at what CreativeEditor SDK (CE.SDK) can do—and how deeply it can integrate into your workflows. Whether you’re building a design editor into your product, enabling automation, or scaling personalized content creation, CE.SDK provides a flexible and future-ready foundation. [Explore Demos](https://img.ly/showcases/cesdk/?tags=android) It’s designed for developers, product teams, and technical decision-makers evaluating how CE.SDK fits their use case. - 100% client-side processing - Custom-built rendering engine for consistent cross-platform performance - Flexible enough for both low-code and fully custom implementations --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Key Concepts" description: "Explore CE.SDK’s key features—manual editing, automation, templates, AI tools, and full UI and API control." platform: android url: "https://img.ly/docs/cesdk/android/key-concepts-21a270/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Concepts](https://img.ly/docs/cesdk/android/concepts-c9ff51/) > [Key Concepts](https://img.ly/docs/cesdk/android/key-concepts-21a270/) --- CE.SDK is built on two distinct technical layers that work together seamlessly: - **User Interface** — Pre-built editors optimized for different use cases - **Engine Interface** — Core rendering and processing engine  This intentional separation gives you powerful advantages: 1. **Cross-platform consistency** – The engine is cross-compiled to native web, iOS, Android, and Node.js, ensuring identical output everywhere 2. **Custom UI** – Build your own UI for simpler tools and workflows 3. **Headless automation** – Run the engine independently for automations and batch processing, both client-side and server-side ## Creative Engine The Creative Engine powers all core editing operations. It handles rendering, processing, and manipulation across images, layouts, text, video, audio, and vectors. **What the Engine Does:** - Maintains the scene file (your structured content) - Renders the canvas in real-time - Handles block positioning and resizing - Applies filters and effects to images - Manages text editing and typography - Controls templates with role-based permissions - Displays smart guides and snap lines Every engine capability is exposed through a comprehensive API, letting you build custom UIs, workflows, and automations. ## Headless / Engine only Use the engine without any UI for powerful automation scenarios: **Client-side automation** Perfect for in-browser batch operations and dynamic content generation without server dependencies. **Server-side automation with Node.js** Use the [Node.JS SDK](https://img.ly/docs/cesdk/android/what-is-cesdk-2e7acd/) for following scenarios: - **High-resolution processing** – Edit on the client with preview quality, then render server-side with full-resolution assets - **Bulk generation** – Create a large volume of design variations for variable data printing - **Non-blocking workflows** – Let users continue designing while exports process in the background **Server-side export with the CE.SDK Renderer** When exporting complex graphics and videos, the [CE.SDK Renderer](#broken-link-7f3e9a) can make use of GPU acceleration and video codecs on Linux server environments. **Plugin development** When building CE.SDK plugins, you get direct API access to manipulate canvas elements programmatically. ## User Interface Components CE.SDK includes pre-built UI configurations optimized for different use cases: - **Photo editing** — Advanced image editing tools and filters - **Video editing** — Timeline-based video editing and effects - **Design editing** — Layout and graphic design tools (similar to Canva) - **2D product design** — Apparel, postcards, and custom product templates More configurations are coming based on customer needs. ## UI Customization While UI configurations provide a solid foundation, you maintain control over the user experience: - Apply **custom color schemes** and branding to match your product - Add **custom asset libraries** with your own fonts, images, graphics, videos, and audio The plugin architecture lets you add custom buttons and panels throughout the interface, ensuring the editor feels native to your product. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Licensing" description: "Understand CE.SDK’s flexible licensing, trial options, and how keys work across dev, staging, and production." platform: android url: "https://img.ly/docs/cesdk/android/licensing-8aa063/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) > [Licensing](https://img.ly/docs/cesdk/android/licensing-8aa063/) --- Thanks for your interest in CreativeEditor SDK (CE.SDK). We offer flexible commercial licensing options to support teams and projects of all sizes. Whether you're building a new product or scaling an existing one, our goal is to provide the best creative editing experience—backed by a licensing model that aligns with your needs. Get in touch with us through our [contact sales form](https://img.ly/forms/contact-sales). ## Commercial Licensing CE.SDK is offered through a subscription-based commercial model. This allows us to: - Deliver ongoing updates and performance improvements - Ensure compatibility with new browsers and devices - Provide dedicated technical support - Build long-term partnerships with our customers ## How Licensing Works CE.SDK licenses are tied to a single commercial product instance, verified by the hostname for web apps and bundle/app ID for mobile apps. Licensing typically uses remote validation and includes lightweight event tracking. It’s possible to disable tracking or use offline-compatible options. To explore these options, [contact our sales team](https://img.ly/forms/contact-sales). ## Trial License Key Trial licenses are available for evaluation and testing and are valid for **30 days**. They provide full access to CE.SDK’s features so you can explore its capabilities in your environment. If you need more time to evaluate, [contact our sales team](https://img.ly/forms/contact-sales). ## Testing and Production Paid license keys can be used across development, staging, and production environments. Multiple domains or app identifiers can be added to support this setup. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "LLMs.txt" description: "Our documentation is available in LLMs.txt format" platform: android url: "https://img.ly/docs/cesdk/android/llms-txt-eb9cc5/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) > [Vibe Coding](https://img.ly/docs/cesdk/android/llms-txt-eb9cc5/) --- > **Note:** You can also connect your AI assistant directly to our documentation using our [MCP Server](https://img.ly/docs/cesdk/android/get-started/mcp-server-fde71c/). This enables real-time search and retrieval without downloading large files. Our documentation is now available in LLMs.txt format, optimized for AI reasoning engines. To better support platform-specific development, we've created separate documentation files for each platform. For developers, this means you can now access documentation tailored to your specific platform, whether it's iOS, Android, Web, or any other supported platform. This approach allows for a more focused and efficient use of AI tools in your development workflow. [Download](getFullUrl\(`/$\{props.platform.slug}/llms-full.txt`\)) These documentation files are substantial in size, with token counts exceeding the context windows of many AI models. This guide explains how to download and effectively use these platform-specific documentation files with AI tools to accelerate your development process. ## What are LLMs.txt files? LLMs.txt is an emerging standard for making documentation AI-friendly. Unlike traditional documentation formats, LLMs.txt: - Presents content in a clean, markdown-based format - Eliminates extraneous HTML, CSS, and JavaScript - Optimizes content for AI context windows - Provides a comprehensive view of documentation in a single file By using our platform-specific LLMs.txt files, you'll ensure that AI tools have the most relevant and complete context for helping with your development tasks. ## Handling Large Documentation Files Due to the size of our documentation files (upward of 500 000 tokens) most AI tools will face context window limitations. Standard models typically have context windows ranging from 8,000 to 200,000 tokens, making it challenging to process our complete documentation in a single session. ### Recommended AI Model for Full Documentation For working with our complete documentation files, we recommend: - **Gemini 2.5 Flash**: Available via Google AI Studio with a context window of 1-2 million tokens, capable of handling even our largest documentation file --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Open the Editor" description: "Learn how to load and create scenes, set the zoom level, and configure file proxies or URI resolvers." platform: android url: "https://img.ly/docs/cesdk/android/open-the-editor-23a1db/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Open the Editor](https://img.ly/docs/cesdk/android/open-the-editor-23a1db/) --- --- ## Related Pages - [Overview](https://img.ly/docs/cesdk/android/open-the-editor/overview-99444b/) - Learn how to load and create scenes, set the zoom level, and configure file proxies or URI resolvers. - [Load a Scene](https://img.ly/docs/cesdk/android/open-the-editor/load-scene-478833/) - Load existing design scenes into the editor to resume or modify previous work. - [Start With Blank Canvas](https://img.ly/docs/cesdk/android/open-the-editor/blank-canvas-18ff05/) - Launch the editor with an empty canvas as a starting point for new designs. - [Create From Image](https://img.ly/docs/cesdk/android/open-the-editor/from-image-ad9b5e/) - Open the editor using an image as the base design, with tools ready for immediate editing. - [Create From Video](https://img.ly/docs/cesdk/android/open-the-editor/from-video-86beb0/) - Load a video file into the editor to start editing frame-based or timeline-based video content. - [Android Image Zoom Library](https://img.ly/docs/cesdk/android/open-the-editor/set-zoom-level-d31896/) - Programmatically adjust the zoom level of the canvas to focus on specific areas of the design. - [URI Resolver](https://img.ly/docs/cesdk/android/open-the-editor/uri-resolver-36b624/) - Customize how asset URIs are resolved and loaded into the editor for full control over file handling. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Start With Blank Canvas" description: "Launch the editor with an empty canvas as a starting point for new designs." platform: android url: "https://img.ly/docs/cesdk/android/open-the-editor/blank-canvas-18ff05/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Open the Editor](https://img.ly/docs/cesdk/android/open-the-editor-23a1db/) > [Start With Blank Canvas](https://img.ly/docs/cesdk/android/open-the-editor/blank-canvas-18ff05/) --- ```kotlin file=@cesdk_android_examples/engine-guides-create-scene-from-scratch/CreateSceneFromScratch.kt reference-only import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun createSceneFromScratch( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope( Dispatchers.Main, ).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block = block, shape = engine.block.createShape(ShapeType.Star)) engine.block.setFill(block = block, fill = engine.block.createFill(FillType.Color)) engine.block.appendChild(parent = page, child = block) engine.stop() } ``` In this example, we will show you how to initialize the [CreativeEditor SDK](https://img.ly/products/creative-sdk) from scratch and add a star shape. We create an empty scene via `engine.scene.create()` which sets up the default scene block with a camera attached. Afterwards, the scene can be populated by creating additional blocks and appending them to the scene. See [Modifying Scenes](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/) for more details. ```kotlin highlight-create val scene = engine.scene.create() ``` We first add a page with `fun create(blockType: DesignBlockType): DesignBlock` specifying a `DesignBlockType.Page` and set a parent-child relationship between the scene and this page. ```kotlin highlight-add-page val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) ``` To this page, we add a graphic design block, again with `fun create(blockType: DesignBlockType): DesignBlock`. To make it more interesting, we set a star shape and a color fill to this block to give it a visual representation. Like for the page, we set the parent-child relationship between the page and the newly added block. From then on, modifications to this block are relative to the page. ```kotlin highlight-add-block-with-star-shape val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block = block, shape = engine.block.createShape(ShapeType.Star)) engine.block.setFill(block = block, fill = engine.block.createFill(FillType.Color)) engine.block.appendChild(parent = page, child = block) ``` This example first appends a page child to the scene as would typically be done but it is not strictly necessary and any child block can be appended directly to a scene. To later save your scene, see [Saving Scenes](https://img.ly/docs/cesdk/android/export-save-publish/save-c8b124/). ### Full Code Here's the full code: ```kotlin import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun createSceneFromScratch( license: String, userId: String, ) = CoroutineScope( Dispatchers.Main, ).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.appendChild(parent = scene, child = page) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block = block, shape = engine.block.createShape(ShapeType.Star)) engine.block.setFill(block = block, fill = engine.block.createFill(FillType.Color)) engine.block.appendChild(parent = page, child = block) engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Create From Image" description: "Open the editor using an image as the base design, with tools ready for immediate editing." platform: android url: "https://img.ly/docs/cesdk/android/open-the-editor/from-image-ad9b5e/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Open the Editor](https://img.ly/docs/cesdk/android/open-the-editor-23a1db/) > [Create From Image](https://img.ly/docs/cesdk/android/open-the-editor/from-image-ad9b5e/) --- ```kotlin file=@cesdk_android_examples/engine-guides-create-scene-from-image-blob/CreateSceneFromImageBlob.kt reference-only import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import kotlinx.coroutines.withContext import ly.img.engine.DesignBlockType import ly.img.engine.Engine import java.io.ByteArrayOutputStream import java.io.File import java.net.URL import java.util.UUID fun createSceneFromImageBlob( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope( Dispatchers.Main, ).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val blobUrl = URL("https://img.ly/static/ubq_samples/sample_4.jpg") val blob = withContext(Dispatchers.IO) { val outputStream = ByteArrayOutputStream() blobUrl.openStream().use { inputStream -> outputStream.use(inputStream::copyTo) } outputStream.toByteArray() } val blobFile = withContext(Dispatchers.IO) { File.createTempFile(UUID.randomUUID().toString(), ".tmp").apply { outputStream().use { it.write(blob) } } } val blobUri = Uri.fromFile(blobFile) val scene = engine.scene.createFromImage(blobUri) val page = engine.block.findByType(DesignBlockType.Page).first() val pageFill = engine.block.getFill(page) val imageFillType = engine.block.getType(pageFill) engine.stop() } ``` Starting from an existing image allows you to use the editor for customizing individual assets. This is done by using `suspend fun createFromImage(imageUri: URI, dpi: Float = 300F, pixelScaleFactor: Float = 1F): DesignBlock` and passing a URI as argument. The `dpi` argument sets the dots per inch of the scene. The `pixelScaleFactor` sets the display's pixel scale factor. ```kotlin file=@cesdk_android_examples/engine-guides-create-scene-from-image-url/CreateSceneFromImageURL.kt reference-only import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine fun createSceneFromImageURL( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope( Dispatchers.Main, ).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val imageRemoteUri = Uri.parse("https://img.ly/static/ubq_samples/sample_4.jpg") val scene = engine.scene.createFromImage(imageRemoteUri) val page = engine.block.findByType(DesignBlockType.Page).first() // Get the fill from the page and verify it's an image fill val pageFill = engine.block.getFill(page) val imageFillType = engine.block.getType(pageFill) engine.stop() } ``` ## Create a Scene From an Image URL In this example, we will show you how to initialize the [CreativeEditor SDK](https://img.ly/products/creative-sdk) with an initial image. Create an instance of `Uri` using the remote url. Use the object `imageRemoteUri` as a source for the initial image. ```kotlin highlight-createFromImage val imageRemoteUri = Uri.parse("https://img.ly/static/ubq_samples/sample_4.jpg") val scene = engine.scene.createFromImage(imageRemoteUri) ``` When starting with an initial image, the scene's page dimensions match the given resource and the scene is configured to be in pixel design units. To later save your scene, see [Saving Scenes](https://img.ly/docs/cesdk/android/export-save-publish/save-c8b124/). ```kotlin import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine fun createSceneFromImageURL( license: String, userId: String, ) = CoroutineScope( Dispatchers.Main, ).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val imageRemoteUri = Uri.parse("https://img.ly/static/ubq_samples/sample_4.jpg") val scene = engine.scene.createFromImage(imageRemoteUri) engine.stop() } ``` ## Create A Scene From an Image Blob In this example, we will show you how to initialize the [CreativeEditor SDK](https://img.ly/products/creative-sdk) with an initial image provided from a blob. First, get hold of a `blob` by fetching an image from the web. This is just for demonstration purposes and your `blob` object may come from a different source. ```kotlin highlight-blob val blobUrl = URL("https://img.ly/static/ubq_samples/sample_4.jpg") val blob = withContext(Dispatchers.IO) { val outputStream = ByteArrayOutputStream() blobUrl.openStream().use { inputStream -> outputStream.use(inputStream::copyTo) } outputStream.toByteArray() } ``` Afterward, create a temporary file and save the `Data`. Create an instance of `Uri` using the temporary file. ```kotlin highlight-objectURL val blobFile = withContext(Dispatchers.IO) { File.createTempFile(UUID.randomUUID().toString(), ".tmp").apply { outputStream().use { it.write(blob) } } } val blobUri = Uri.fromFile(blobFile) ``` Use the object `blobUri` as a source for the initial image. ```kotlin highlight-initialImageURL val scene = engine.scene.createFromImage(blobUri) ``` When starting with an initial image, the scenes page dimensions match the given image, and the scene is configured to be in pixel design units. To later save your scene, see [Saving Scenes](https://img.ly/docs/cesdk/android/export-save-publish/save-c8b124/). ### Full Code Here's the full code: ```kotlin import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import kotlinx.coroutines.withContext import ly.img.engine.DesignBlockType import ly.img.engine.Engine import java.io.ByteArrayOutputStream import java.io.File import java.net.URL import java.util.UUID fun createSceneFromImageBlob( license: String, userId: String, ) = CoroutineScope( Dispatchers.Main, ).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val blobUrl = URL("https://img.ly/static/ubq_samples/sample_4.jpg") val blob = withContext(Dispatchers.IO) { val outputStream = ByteArrayOutputStream() blobUrl.openStream().use { inputStream -> outputStream.use(inputStream::copyTo) } outputStream.toByteArray() } val blobFile = withContext(Dispatchers.IO) { File.createTempFile(UUID.randomUUID().toString(), ".tmp").apply { outputStream().use { it.write(blob) } } } val blobUri = Uri.fromFile(blobFile) val scene = engine.scene.createFromImage(blobUri) engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Create From Video" description: "Load a video file into the editor to start editing frame-based or timeline-based video content." platform: android url: "https://img.ly/docs/cesdk/android/open-the-editor/from-video-86beb0/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Open the Editor](https://img.ly/docs/cesdk/android/open-the-editor-23a1db/) > [Create From Video](https://img.ly/docs/cesdk/android/open-the-editor/from-video-86beb0/) --- ```kotlin file=@cesdk_android_examples/engine-guides-create-scene-from-video-url/CreateSceneFromVideoURL.kt reference-only import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine fun createSceneFromVideoURL( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope( Dispatchers.Main, ).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val videoRemoteUri = Uri.parse("https://img.ly/static/ubq_video_samples/bbb.mp4") val scene = engine.scene.createFromVideo(videoRemoteUri) // Find the automatically added graphic block in the scene that contains the video fill. val block = engine.block.findByType(DesignBlockType.Graphic).first() // Change its opacity. engine.block.setOpacity(block, value = 0.5F) engine.stop() } ``` In this example, we will show you how to initialize the [CreativeEditor SDK](https://img.ly/products/creative-sdk) with an initial video. Starting from an existing video allows you to use the editor for customizing individual assets. This is done by using `suspend fun createFromVideo(videoUri: URI): DesignBlock` and passing a URI as argument. Create an instance of `Uri` using the remote url. Use the object `videoRemoteUri` as a source for the initial video. ```kotlin highlight-createFromVideo val videoRemoteUri = Uri.parse("https://img.ly/static/ubq_video_samples/bbb.mp4") val scene = engine.scene.createFromVideo(videoRemoteUri) ``` We can retrieve the graphic block id of this initial video using `fun findByType(blockType: DesignBlockType): List`. Note that that function returns an array. Since there's only a single graphic block in the scene, the block is at index `0`. ```kotlin highlight-findByType // Find the automatically added graphic block in the scene that contains the video fill. val block = engine.block.findByType(DesignBlockType.Graphic).first() ``` We can then manipulate and modify this block. Here we modify its opacity with `fun setOpacity(block: DesignBlock, @FloatRange(from = 0.0, to = 1.0) value: Float)`. See [Modifying Scenes](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/) for more details. ```kotlin highlight-setOpacity // Change its opacity. engine.block.setOpacity(block, value = 0.5F) ``` When starting with an initial video, the scene's page dimensions match the given resource and the scene is configured to be in pixel design units. To later save your scene, see [Saving Scenes](https://img.ly/docs/cesdk/android/export-save-publish/save-c8b124/). ## Full Code Here's the full code: ```kotlin import android.net.Uri import kotlinx.coroutines.* import ly.img.engine.* fun createSceneFromVideoURL( license: String, userId: String, ) = CoroutineScope( Dispatchers.Main, ).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val videoRemoteUri = Uri.parse("https://img.ly/static/ubq_video_samples/bbb.mp4") val scene = engine.scene.createFromVideo(videoRemoteUri) // Find the automatically added graphic block in the scene that contains the video fill. val block = engine.block.findByType(DesignBlockType.Graphic).first() // Change its opacity. engine.block.setOpacity(block, value = 0.5F) engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Load a Scene" description: "Load existing design scenes into the editor to resume or modify previous work." platform: android url: "https://img.ly/docs/cesdk/android/open-the-editor/load-scene-478833/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Open the Editor](https://img.ly/docs/cesdk/android/open-the-editor-23a1db/) > [Load a Scene](https://img.ly/docs/cesdk/android/open-the-editor/load-scene-478833/) --- ```kotlin file=@cesdk_android_examples/engine-guides-load-scene-from-blob/LoadSceneFromBlob.kt reference-only import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import kotlinx.coroutines.withContext import ly.img.engine.DesignBlockType import ly.img.engine.Engine import java.io.ByteArrayOutputStream import java.net.URL fun loadSceneFromBlob( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val sceneUrl = URL("https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene") val sceneBlob = withContext(Dispatchers.IO) { val outputStream = ByteArrayOutputStream() sceneUrl.openStream().use { inputStream -> outputStream.use(inputStream::copyTo) } outputStream.toByteArray() } val blobString = String(sceneBlob, Charsets.UTF_8) val scene = engine.scene.load(scene = blobString) val text = engine.block.findByType(DesignBlockType.Text).first() engine.block.setDropShadowEnabled(text, enabled = true) engine.stop() } ``` ```kotlin file=@cesdk_android_examples/engine-guides-load-scene-from-string/LoadSceneFromString.kt reference-only import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import kotlinx.coroutines.withContext import ly.img.engine.DesignBlockType import ly.img.engine.Engine import java.io.ByteArrayOutputStream import java.net.URL fun loadSceneFromString( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val sceneUrl = URL("https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene") val sceneBlob = withContext(Dispatchers.IO) { val outputStream = ByteArrayOutputStream() sceneUrl.openStream().use { inputStream -> outputStream.use(inputStream::copyTo) } outputStream.toByteArray() } val blobString = String(sceneBlob, Charsets.UTF_8) val scene = engine.scene.load(scene = blobString) val text = engine.block.findByType(DesignBlockType.Text).first() engine.block.setDropShadowEnabled(text, enabled = true) engine.stop() } ``` ```kotlin file=@cesdk_android_examples/engine-guides-load-scene-from-remote/LoadSceneFromRemote.kt reference-only import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine fun loadSceneFromRemote( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val sceneUri = Uri.parse( "https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene", ) val scene = engine.scene.load(sceneUri = sceneUri) val text = engine.block.findByType(DesignBlockType.Text).first() engine.block.setDropShadowEnabled(text, enabled = true) engine.stop() } ``` Loading an existing scene allows resuming work on a previous session or adapting an existing template to your needs. > **Note:** **Warning** Saving a scene can be done as a either scene file or as > an archive file (c.f. > [Saving scenes](https://img.ly/docs/cesdk/android/export-save-publish/save-c8b124/)). A scene file does > not include any fonts or images. Only the source URIs of assets, the general > layout, and element properties are stored. When loading scenes in a new > environment, ensure previously used asset URIs are available. Conversely, an > archive file contains within it the scene's assets and references > them as relative URIs. ## Load Scenes from a Remote URL Determine a url that points to a scene binary string. Create an instance of `Uri` using the remote url. ```kotlin highlight-url val sceneUri = Uri.parse( "https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene", ) ``` We can then pass the object `sceneUri` to the `suspend fun load(sceneUri: Uri): DesignBlock` function. The editor will reset and present the given scene to the user. The function is asynchronous and it does not throw if the scene load succeeded. ```kotlin highlight-load-remote val scene = engine.scene.load(sceneUri = sceneUri) ``` From this point on we can continue to modify our scene. In this example, assuming the scene contains a text element, we add a drop shadow to it. See [Modifying Scenes](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/) for more details. ```kotlin highlight-modify-text-remote val text = engine.block.findByType(DesignBlockType.Text).first() engine.block.setDropShadowEnabled(text, enabled = true) ``` Scene loads may be reverted using `engine.editor.undo()`. To later save your scene, see [Saving Scenes](https://img.ly/docs/cesdk/android/export-save-publish/save-c8b124/). ### Full Code Here's the full code: ```kotlin import android.net.Uri import kotlinx.coroutines.* import ly.img.engine.* fun loadSceneFromRemote( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val sceneUri = Uri.parse( "https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene", ) val scene = engine.scene.load(sceneUri = sceneUri) val text = engine.block.findByType(DesignBlockType.Text).first() engine.block.setDropShadowEnabled(text, enabled = true) engine.stop() } ``` ## Load Scenes from a String In this example, we fetch a scene from a remote url and load it as a string. This string could also come from the result of `suspend fun saveToString(): String`. ```kotlin highlight-fetch-string val sceneUrl = URL("https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene") val sceneBlob = withContext(Dispatchers.IO) { val outputStream = ByteArrayOutputStream() sceneUrl.openStream().use { inputStream -> outputStream.use(inputStream::copyTo) } outputStream.toByteArray() } val blobString = String(sceneBlob, Charsets.UTF_8) ``` We can then pass that string to the `suspend fun load(scene: String): DesignBlock` function. The editor will then reset and present the given scene to the user. The function is asynchronous and it does not throw if the scene load succeeded. ```kotlin highlight-load-string val scene = engine.scene.load(scene = blobString) ``` From this point on we can continue to modify our scene. In this example, assuming the scene contains a text element, we add a drop shadow to it. See [Modifying Scenes](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/) for more details. ```kotlin highlight-modify-text-string val text = engine.block.findByType(DesignBlockType.Text).first() engine.block.setDropShadowEnabled(text, enabled = true) ``` Scene loads may be reverted using `engine.editor.undo()`. To later save your scene, see [Saving Scenes](https://img.ly/docs/cesdk/android/export-save-publish/save-c8b124/). ### Full Code Here's the full code: ```kotlin import kotlinx.coroutines.* import ly.img.engine.* import java.io.ByteArrayOutputStream import java.net.URL fun loadSceneFromString( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val sceneUrl = URL("https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene") val sceneBlob = withContext(Dispatchers.IO) { val outputStream = ByteArrayOutputStream() sceneUrl.openStream().use { inputStream -> outputStream.use(inputStream::copyTo) } outputStream.toByteArray() } val blobString = String(sceneBlob, Charsets.UTF_8) val scene = engine.scene.load(scene = blobString) val text = engine.block.findByType(DesignBlockType.Text).first() engine.block.setDropShadowEnabled(text, enabled = true) engine.stop() } ``` ## Load Scenes From a Blob In this example, we fetch a scene from a remote url and load it as `sceneBlob`. ```kotlin highlight-fetch-blob val sceneUrl = URL("https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene") val sceneBlob = withContext(Dispatchers.IO) { val outputStream = ByteArrayOutputStream() sceneUrl.openStream().use { inputStream -> outputStream.use(inputStream::copyTo) } outputStream.toByteArray() } ``` To acquire a scene string from `sceneBlob`, we need to read its contents into a string. ```kotlin highlight-read-blob val blobString = String(sceneBlob, Charsets.UTF_8) ``` We can then pass that string to the `suspend fun load(scene: String): DesignBlock` function. The editor will reset and present the given scene to the user. The function is asynchronous and it does not throw if the scene load succeeded. ```kotlin highlight-load-blob val scene = engine.scene.load(scene = blobString) ``` From this point on we can continue to modify our scene. In this example, assuming the scene contains a text element, we add a drop shadow to it. See [Modifying Scenes](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/) for more details. ```kotlin highlight-modify-text-blob val text = engine.block.findByType(DesignBlockType.Text).first() engine.block.setDropShadowEnabled(text, enabled = true) ``` Scene loads may be reverted using `engine.editor.undo()`. To later save your scene, see [Saving Scenes](https://img.ly/docs/cesdk/android/export-save-publish/save-c8b124/). ### Full Code Here's the full code: ```kotlin import kotlinx.coroutines.* import ly.img.engine.* import java.io.ByteArrayOutputStream import java.net.URL fun loadSceneFromBlob( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val sceneUrl = URL("https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene") val sceneBlob = withContext(Dispatchers.IO) { val outputStream = ByteArrayOutputStream() sceneUrl.openStream().use { inputStream -> outputStream.use(inputStream::copyTo) } outputStream.toByteArray() } val blobString = String(sceneBlob, Charsets.UTF_8) val scene = engine.scene.load(scene = blobString) val text = engine.block.findByType(DesignBlockType.Text).first() engine.block.setDropShadowEnabled(text, enabled = true) engine.stop() } ``` ```kotlin reference-only val scene = requireNotNull(engine.scene.get()) // Forcing all resources of all the blocks in a scene or the resources of graphic block to load engine.block.forceLoadResources(listOf(scene)) val graphics = engine.block.findByType(DesignBlockType) engine.block.forceLoadResources(graphics) ``` ## Loading Scene Archives Loading a scene archives requires unzipping the archives contents to a location, that's accessible to the CreativeEngine. One could for example unzip the archive via `unzip archive.zip` and then serve its contents using `$ npx serve`. This spins up a local test server, that serves everything contained in the current directory at `http://localhost:3000` The archive can then be loaded by calling `engine.scene.load("http://localhost:3000/scene.scene")`. See [loading scenes](https://img.ly/docs/cesdk/android/open-the-editor/load-scene-478833/) for more details. All asset paths in the archive are then resolved relative to the location of the `scene.scene` file. For an image, that would result in `'http://localhost:3000/images/1234.jpeg'`. After loading all URLs are fully resolved with the location of the `scene.scene` file and the scene behaves like any other scene. ### Resolving assets from a different source The engine will use its [URI resolver](https://img.ly/docs/cesdk/android/open-the-editor/uri-resolver-36b624/) to resolve all asset paths it encounters. This allows you to redirect requests for the assets contained in archive to a different location. To do so, you can add a custom resolver, that redirects requests for assets to a different location. Assuming you store your archived scenes in a `scenes/` directory, this would be an example of how to do so: ```kotlin engine.editor.setURIResolver { val uri = java.net.URI(it.path) if (uri.host == "localhost" && uri.path.startsWith("/scenes") && !uri.path.endsWith(".scene")) { // Apply custom logic here, e.g. redirect to a different server } engine.editor.defaultURIResolver(it) } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Overview" description: "Learn how to load and create scenes, set the zoom level, and configure file proxies or URI resolvers." platform: android url: "https://img.ly/docs/cesdk/android/open-the-editor/overview-99444b/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Open the Editor](https://img.ly/docs/cesdk/android/open-the-editor-23a1db/) > [Overview](https://img.ly/docs/cesdk/android/open-the-editor/overview-99444b/) --- CreativeEditor SDK (CE.SDK) offers multiple ways to open the editor. Whether you're starting with a blank canvas or importing complex layered files, CE.SDK gives you the building blocks to launch an editing session tailored to your users' needs. [Explore Demos](https://img.ly/showcases/cesdk?tags=android) [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Android Image Zoom Library" description: "Programmatically adjust the zoom level of the canvas to focus on specific areas of the design." platform: android url: "https://img.ly/docs/cesdk/android/open-the-editor/set-zoom-level-d31896/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Open the Editor](https://img.ly/docs/cesdk/android/open-the-editor-23a1db/) > [Set Zoom Level](https://img.ly/docs/cesdk/android/open-the-editor/set-zoom-level-d31896/) --- ```kotlin reference-only // Zoom to 100% engine.scene.setZoomLevel(level = 1F) // Zoom to 50% engine.scene.setZoomLevel(0.5F * engine.scene.getZoomLevel()) // Bring entire scene in view with padding of 20px in all directions engine.scene.zoomToBlock( block = scene, paddingLeft = 20F, paddingTop = 20F, paddingRight = 20F, paddingBottom = 20F ) engine.scene.immediateZoomToBlock( block = scene, paddingLeft = 20F, paddingTop = 20F, paddingRight = 20F, paddingBottom = 20F ) // Follow page with padding of 20px in both directions engine.scene.enableZoomAutoFit( block = page, axis = ZoomAutoFitAxis.BOTH, paddingLeft = 20F, paddingTop = 20F, paddingRight = 20F, paddingBottom = 20F ) // Stop following page engine.scene.disableZoomAutoFit(page) // Query if zoom auto-fit is enabled for page engine.scene.isZoomAutoFitEnabled(page) // Keep the scene with padding of 10px within the camera engine.scene.enableCameraPositionClamping( blocks = listOf(scene), paddingLeft = 10F, paddingTop = 10F, paddingRight = 10F, paddingBottom = 10F, scaledPaddingLeft = 0F, scaledPaddingTop = 0F, scaledPaddingRight = 0F, scaledPaddingBottom = 0F ) engine.scene.disableCameraPositionClamping() // Query if camera position clamping is enabled for the scene engine.scene.isCameraPositionClampingEnabled(scene) // Allow zooming from 12.5% to 800% relative to the size of a page engine.scene.enableCameraZoomClamping( listOf(page), minZoomLimit = 0.125F, maxZoomLimit = 8F, paddingLeft = 0F, paddingTop = 0F, paddingRight = 0F, paddingBottom = 0F, ) engine.scene.disableCameraZoomClamping() // Query if camera zoom clamping is enabled for the scene engine.scene.isCameraZoomClampingEnabled(scene) // Get notified when the zoom level changes engine.scene.onZoomLevelChanged() .onEach { val zoomLevel = engine.scene.getZoomLevel() println("Zoom level is now: $zoomLevel") } .launchIn(CoroutineScope(Dispatchers.Main)) ``` In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to control and observe camera zoom via the `scene` API. ## Functions ```kotlin fun getZoomLevel(): Float ``` Get the zoom level of the scene or for a camera in the scene. Returns the current zoom level of the scene in unit `dpx/dot`. A zoom level of 2F results in one dot in the design to be two pixels on the screen. - Returns the zoom level of the scene. ```kotlin fun setZoomLevel(level: Float) ``` Set the zoom level of the scene, e.g., for headless versions. This only shows an effect if the zoom level is not handled/overwritten by the UI. Setting a zoom level of 2F results in one dot in the design to be two pixels on the screen. - `level`: the zoom level with unit `dpx/dot`. is shown on the screen. ```kotlin suspend fun zoomToBlock( block: DesignBlock, paddingLeft: Float = 0F, paddingTop: Float = 0F, paddingRight: Float = 0F, paddingBottom: Float = 0F, ) ``` Sets the zoom and focus to show a block. Without padding, this results in a tight view on the block. It is set asynchronous to ensure that the block dimensions are known. - `block`: the block that should be focused on. - `paddingLeft`: optional padding in screen pixels to the left of the block. - `paddingTop`: optional padding in screen pixels to the top of the block. - `paddingRight`: optional padding in screen pixels to the right of the block. - `paddingBottom`: optional padding in screen pixels to the bottom of the block. ```kotlin fun immediateZoomToBlock( block: DesignBlock, paddingLeft: Float = 0F, paddingTop: Float = 0F, paddingRight: Float = 0F, paddingBottom: Float = 0F, forceUpdate: Boolean = false, ) ``` Sets the zoom and focus to show a block. This only shows an effect if the zoom level is not handled/overwritten by the UI. Without padding, this results in a tight view on the block. It is set immediately and assumes that the block dimensions are known. The block should not be in pending state and it's layout should be up to date. - `block`: the block that should be focused on. - `paddingLeft`: optional padding in screen pixels to the left of the block. - `paddingTop`: optional padding in screen pixels to the top of the block. - `paddingRight`: optional padding in screen pixels to the right of the block. - `paddingBottom`: optional padding in screen pixels to the bottom of the block. - `forceUpdate`: If true, the implicit update is called. ```kotlin fun enableZoomAutoFit( block: DesignBlock, axis: ZoomAutoFitAxis, paddingLeft: Float = 0.0F, paddingTop: Float = 0.0F, paddingRight: Float = 0.0F, paddingBottom: Float = 0.0F, ) ``` Continually adjusts the zoom level to fit the width or height of a block's axis-aligned bounding box. This only shows an effect if the zoom level is not handled/overwritten by the UI. Without padding, this results in a tight view on the block. No more than one block per scene can have zoom auto-fit enabled. Calling `setZoomLevel` or `zoomToBlock` disables the continuous adjustment. - `block`: the block in the scene for which to enable a zoom auto-fit. - `axis`: the block axis (or axes) for which the zoom is adjusted. - `paddingLeft`: optional padding in screen pixels to the left of the block. - `paddingTop`: optional padding in screen pixels to the top of the block. - `paddingRight`: optional padding in screen pixels to the right of the block. - `paddingBottom`: optional padding in screen pixels to the bottom of the block. ```kotlin fun disableZoomAutoFit(block: DesignBlock) ``` Disables any previously set zoom auto-fit. - `block`: the scene or a block in the scene for which to disable zoom auto-fit. ```kotlin fun isZoomAutoFitEnabled(block: DesignBlock): Boolean ``` Queries whether zoom auto-fit is enabled for `block`. - `block`: the scene or a block in the scene for which to query if zoom auto-fit is set. - Returns true if the given block has auto-fit set or the scene contains a block for which auto-fit is set, false otherwise. ```kotlin @UnstableEngineApi fun enableCameraPositionClamping( blocks: List, paddingLeft: Float = 0.0F, paddingTop: Float = 0.0F, paddingRight: Float = 0.0F, paddingBottom: Float = 0.0F, scaledPaddingLeft: Float = 0.0F, scaledPaddingTop: Float = 0.0F, scaledPaddingRight: Float = 0.0F, scaledPaddingBottom: Float = 0.0F, ) ``` Continually ensures the camera position to be within the width and height of the blocks axis-aligned bounding box. Disables any previously set camera position clamping in the scene and also takes priority over clamp camera commands. Without padding, this results in a tight clamp on the blocks. - `blocks`: the blocks for which the camera position is adjusted to, usually, the scene or a page. - `paddingLeft`: optional padding in screen pixels to the left of the block. - `paddingTop`: optional padding in screen pixels to the top of the block. - `paddingRight`: optional padding in screen pixels to the right of the block. - `paddingBottom`: optional padding in screen pixels to the bottom of the block. - `scaledPaddingLeft`: optional padding in screen pixels to the left of the block that scales with the zoom level until five times the initial value. - `scaledPaddingTop`: optional padding in screen pixels to the top of the block that scales with the zoom level until five times the initial value. - `scaledPaddingRight`: optional padding in screen pixels to the right of the block that scales with the zoom level until five times the initial value. - `scaledPaddingBottom`: optional padding in screen pixels to the bottom of the block that scales with the zoom level until five times the initial value. ```kotlin @UnstableEngineApi fun disableCameraPositionClamping() ``` Disables any previously set position clamping for the current scene. ```kotlin @UnstableEngineApi fun isCameraPositionClampingEnabled(blockOrScene: DesignBlock): Boolean ``` Queries whether position clamping is enabled for `blockOrScene`. - `blockOrScene`: the scene or a block in the scene for which to query the position clamping. - Returns true if the given block has position clamping set or the scene contains a block for which position clamping is set, false otherwise. ```kotlin @UnstableEngineApi fun enableCameraZoomClamping( blocks: List, minZoomLimit: Float = -1.0F, maxZoomLimit: Float = -1.0F, paddingLeft: Float = 0.0F, paddingTop: Float = 0.0F, paddingRight: Float = 0.0F, paddingBottom: Float = 0.0F, ) ``` Continually ensures the zoom level of the camera in the active scene to be in the given range. - Note: A zoom level of 2.0 results in one pixel in the design to be two pixels on the screen. - `blocks`: the blocks for which the camera position is adjusted to, usually, the scene or a page. - `minZoomLimit`: the minimum zoom level limit when zooming out, unlimited when negative. - `maxZoomLimit`: the maximum zoom level limit when zooming in, unlimited when negative. - `paddingLeft`: optional padding in screen pixels to the left of the block. Only applied when the block is not a camera. - `paddingTop`: optional padding in screen pixels to the top of the block. Only applied when the block is not a camera. - `paddingRight`: optional padding in screen pixels to the right of the block. Only applied when the block is not a camera. - `paddingBottom`: optional padding in screen pixels to the bottom of the block. Only applied when the block is not a camera. ```kotlin @UnstableEngineApi fun disableCameraZoomClamping() ``` Disables previously set zoom clamping for the current scene. ```kotlin @UnstableEngineApi fun isCameraZoomClampingEnabled(blockOrScene: DesignBlock): Boolean ``` Queries whether zoom clamping is enabled. - `blockOrScene`: the scene or a block in the scene for which to query the zoom clamping. - Returns true if the given block has zoom clamping set or the scene contains a block for which zoom clamping is set, false otherwise. ```kotlin fun onZoomLevelChanged(): Flow ``` Subscribe to changes to the zoom level. - Returns flow of zoom change events. ## Settings See clamp camera settings in the [editor settings](https://img.ly/docs/cesdk/android/settings-970c98/). ## Full Code Here's the full code: ```kotlin // Zoom to 100% engine.scene.setZoomLevel(level = 1F) // Zoom to 50% engine.scene.setZoomLevel(0.5F * engine.scene.getZoomLevel()) // Bring entire scene in view with padding of 20px in all directions engine.scene.zoomToBlock( block = scene, paddingLeft = 20F, paddingTop = 20F, paddingRight = 20F, paddingBottom = 20F ) engine.scene.immediateZoomToBlock( block = scene, paddingLeft = 20F, paddingTop = 20F, paddingRight = 20F, paddingBottom = 20F ) // Follow page with padding of 20px in both directions engine.scene.enableZoomAutoFit( block = page, axis = ZoomAutoFitAxis.BOTH, paddingLeft = 20F, paddingTop = 20F, paddingRight = 20F, paddingBottom = 20F ) // Stop following page engine.scene.disableZoomAutoFit(page) // Query if zoom auto-fit is enabled for page engine.scene.isZoomAutoFitEnabled(page) // Keep the scene with padding of 10px within the camera engine.scene.enableCameraPositionClamping( blocks = listOf(scene), paddingLeft = 10F, paddingTop = 10F, paddingRight = 10F, paddingBottom = 10F, scaledPaddingLeft = 0F, scaledPaddingTop = 0F, scaledPaddingRight = 0F, scaledPaddingBottom = 0F ) engine.scene.disableCameraPositionClamping() // Query if camera position clamping is enabled for the scene engine.scene.isCameraPositionClampingEnabled(scene) // Allow zooming from 12.5% to 800% relative to the size of a page engine.scene.enableCameraZoomClamping( listOf(page), minZoomLimit = 0.125F, maxZoomLimit = 8F, paddingLeft = 0F, paddingTop = 0F, paddingRight = 0F, paddingBottom = 0F, ) engine.scene.disableCameraZoomClamping() // Query if camera zoom clamping is enabled for the scene engine.scene.isCameraZoomClampingEnabled(scene) // Get notified when the zoom level changes engine.scene.onZoomLevelChanged() .onEach { val zoomLevel = engine.scene.getZoomLevel() println("Zoom level is now: $zoomLevel") } .launchIn(CoroutineScope(Dispatchers.Main)) ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "URI Resolver" description: "Customize how asset URIs are resolved and loaded into the editor for full control over file handling." platform: android url: "https://img.ly/docs/cesdk/android/open-the-editor/uri-resolver-36b624/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Open the Editor](https://img.ly/docs/cesdk/android/open-the-editor-23a1db/) > [URI Resolver](https://img.ly/docs/cesdk/android/open-the-editor/uri-resolver-36b624/) --- ```kotlin file=@cesdk_android_examples/engine-guides-uri-resolver/UriResolver.kt reference-only import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.Engine fun uriResolver( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) // This will return uri to "banana.jpg" asset file engine.editor.getAbsoluteUri(uri = Uri.parse("banana.jpg")) // This will return uri to remote resource "https://example.com/orange.png" engine.editor.getAbsoluteUri(uri = Uri.parse("https://example.com/orange.png")) // Replace all .jpg files with the IMG.LY logo! engine.editor.setUriResolver { if (it.toString().endsWith(".jpg")) { Uri.parse("https://img.ly/static/ubq_samples/imgly_logo.jpg") } else { engine.editor.defaultUriResolver(it) } } // The custom resolver will return a path to the IMG.LY logo because the given path ends with ".jpg". // This applies regardless if the given path is relative or absolute. engine.editor.getAbsoluteUri(uri = Uri.parse("banana.jpg")) // The custom resolver will not modify this path because it ends with ".png". engine.editor.getAbsoluteUri(uri = Uri.parse("https://example.com/orange.png")) // Because a custom resolver is set, relative paths that the resolver does not transform remain unmodified! engine.editor.getAbsoluteUri(uri = Uri.parse("/orange.png")) // Removes the previously set resolver. engine.editor.setUriResolver(null) // Since we've removed the custom resolver, this will return // Uri.Asset("banana.jpg") like before. engine.editor.getAbsoluteUri(uri = Uri.parse("banana.jpg")) engine.editor.setUriResolver { uri -> val path = uri.path if (uri.host == "localhost" && path != null && path.startsWith("/scenes") && !path.endsWith(".scene")) { // Apply custom logic here, e.g. redirect to a different server } engine.editor.defaultUriResolver(uri) } engine.stop() } ``` CE.SDK gives you full control over how Uris should be resolved. To register a custom resolver, use `setUriResolver` and pass in a function implementing your resolution logic. If a custom resolver is set, any Uri (both relative and absolute) requested by the engine is passed through the resolver. The Uri your logic returns is then fetched by the engine. The resolved Uri is just used for the current request and not stored. If, and only if, no custom resolver is set, the engine performs the default behaviour: absolute uri objects are unchanged and relative objects are turned into android asset Uris. > **Note:** **Warning** Your custom Uri resolver must return an absolute Uri. We can preview the effects of setting a custom Uri resolver with the function `fun getAbsoluteUri(uri: Uri): Uri`. Before setting a custom Uri resolver, the default behavior is as before: absolute Uri is unchanged and relative is turned into android asset Uri. ```kotlin highlight-get-absolute-base-path // This will return uri to "banana.jpg" asset file engine.editor.getAbsoluteUri(uri = Uri.parse("banana.jpg")) // This will return uri to remote resource "https://example.com/orange.png" engine.editor.getAbsoluteUri(uri = Uri.parse("https://example.com/orange.png")) ``` To show that the resolver can be fairly free-form, in this example we register a custom Uri resolver that replaces all `.jpg` images with our company logo. Note: you can still access the default Uri resolver by calling `fun defaultUriResolver(uri: Uri): Uri`. ```kotlin highlight-resolver // Replace all .jpg files with the IMG.LY logo! engine.editor.setUriResolver { if (it.toString().endsWith(".jpg")) { Uri.parse("https://img.ly/static/ubq_samples/imgly_logo.jpg") } else { engine.editor.defaultUriResolver(it) } } ``` Given the same uri as earlier, the custom resolver transforms it as specified. Note that after a custom resolver is set, uris that the resolver does not transform remain unmodified thanks to `defaultUriResolver`. ```kotlin highlight-get-absolute-custom // The custom resolver will return a path to the IMG.LY logo because the given path ends with ".jpg". // This applies regardless if the given path is relative or absolute. engine.editor.getAbsoluteUri(uri = Uri.parse("banana.jpg")) // The custom resolver will not modify this path because it ends with ".png". engine.editor.getAbsoluteUri(uri = Uri.parse("https://example.com/orange.png")) // Because a custom resolver is set, relative paths that the resolver does not transform remain unmodified! engine.editor.getAbsoluteUri(uri = Uri.parse("/orange.png")) ``` To remove a previously set custom resolver, call the function with a `null` value. The Uri resolution is now back to the default behavior. ```kotlin highlight-remove-resolver // Removes the previously set resolver. engine.editor.setUriResolver(null) // Since we've removed the custom resolver, this will return // Uri.Asset("banana.jpg") like before. engine.editor.getAbsoluteUri(uri = Uri.parse("banana.jpg")) ``` ## Full Code Here's the full code: ```kotlin import android.net.Uri import kotlinx.coroutines.* import ly.img.engine.* fun uriResolver( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) // This will return uri to "banana.jpg" asset file engine.editor.getAbsoluteUri(uri = Uri.parse("banana.jpg")) // This will return uri to remote resource "https://example.com/orange.png" engine.editor.getAbsoluteUri(uri = Uri.parse("https://example.com/orange.png")) // Replace all .jpg files with the IMG.LY logo! engine.editor.setUriResolver { if (it.toString().endsWith(".jpg")) { Uri.parse("https://img.ly/static/ubq_samples/imgly_logo.jpg") } else { engine.editor.defaultUriResolver(it) } } // The custom resolver will return a path to the IMG.LY logo because the given path ends with ".jpg". // This applies regardless if the given path is relative or absolute. engine.editor.getAbsoluteUri(uri = Uri.parse("banana.jpg")) // The custom resolver will not modify this path because it ends with ".png". engine.editor.getAbsoluteUri(uri = Uri.parse("https://example.com/orange.png")) // Because a custom resolver is set, relative paths that the resolver does not transform remain unmodified! engine.editor.getAbsoluteUri(uri = Uri.parse("/orange.png")) // Removes the previously set resolver. engine.editor.setUriResolver(null) // Since we've removed the custom resolver, this will return // Uri.Asset("banana.jpg") like before. engine.editor.getAbsoluteUri(uri = Uri.parse("banana.jpg")) engine.editor.setUriResolver { uri -> val path = uri.path if (uri.host == "localhost" && path != null && path.startsWith("/scenes") && !path.endsWith(".scene")) { // Apply custom logic here, e.g. redirect to a different server } engine.editor.defaultUriResolver(uri) } engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Outlines" description: "Enhance design elements with strokes, shadows, and glow effects to improve contrast and visual appeal." platform: android url: "https://img.ly/docs/cesdk/android/outlines-b7820c/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Outlines](https://img.ly/docs/cesdk/android/outlines-b7820c/) --- --- ## Related Pages - [Overview](https://img.ly/docs/cesdk/android/outlines/overview-dfeb12/) - Enhance design elements with strokes, shadows, and glow effects to improve contrast and visual appeal. - [Using Strokes](https://img.ly/docs/cesdk/android/outlines/strokes-c2e621/) - Add and customize outlines around shapes, text, or images using stroke settings. - [Shadows and Glows](https://img.ly/docs/cesdk/android/outlines/shadows-and-glows-6610fa/) - Apply shadow and glow effects to elements for added depth, contrast, or emphasis. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Overview" description: "Enhance design elements with strokes, shadows, and glow effects to improve contrast and visual appeal." platform: android url: "https://img.ly/docs/cesdk/android/outlines/overview-dfeb12/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Outlines](https://img.ly/docs/cesdk/android/outlines-b7820c/) > [Overview](https://img.ly/docs/cesdk/android/outlines/overview-dfeb12/) --- In CreativeEditor SDK (CE.SDK), *outlines* refer to visual enhancements added around design elements. They include strokes, shadows, and glows, each serving to emphasize, separate, or stylize content. Outlines help improve visibility, create visual contrast, and enhance the overall aesthetic of a design. You can add, edit, and remove outlines both through the CE.SDK user interface and programmatically via the API. [Explore Demos](https://img.ly/showcases/cesdk?tags=android) [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Shadows and Glows" description: "Apply shadow and glow effects to elements for added depth, contrast, or emphasis." platform: android url: "https://img.ly/docs/cesdk/android/outlines/shadows-and-glows-6610fa/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Outlines](https://img.ly/docs/cesdk/android/outlines-b7820c/) > [Shadows and Glows](https://img.ly/docs/cesdk/android/outlines/shadows-and-glows-6610fa/) --- ```kotlin reference-only // Configure a basic colored drop shadow if the block supports them if (engine.block.supportsDropShadow(block)) { engine.block.setDropShadowEnabled(block, enabled = true) engine.block.setDropShadowColor(block, Color.fromRGBA(r = 1F, g = 0.75F, b = 0.8F, a = 1F)) val dropShadowColor = engine.block.getDropShadowColor(block) engine.block.setDropShadowOffsetX(block, offsetX = -10F) engine.block.setDropShadowOffsetY(block, offsetY = 5F) val dropShadowOffsetX = engine.block.getDropShadowOffsetX(block); val dropShadowOffsetY = engine.block.getDropShadowOffsetY(block); engine.block.setDropShadowBlurRadiusX(block, blurRadiusX = -10F) engine.block.setDropShadowBlurRadiusY(block, blurRadiusY = 5F) engine.block.setDropShadowClip(block, clip = false) val dropShadowClip = engine.block.getDropShadowClip(block) // Query a blocks drop shadow properties val dropShadowIsEnabled = engine.block.isDropShadowEnabled(block) val dropShadowBlurRadiusX = engine.block.getDropShadowBlurRadiusX(block) val dropShadowBlurRadiusY = engine.block.getDropShadowBlurRadiusY(block) } ``` In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to modify an block's drop shadow through the `block` API. Drop shadows can be added to any shape, text or image. One can adjust its offset relative to its block on the X and Y axes, its blur factor on the X and Y axes and whether it is visible behind a transparent block. ## Functions ```kotlin fun supportsDropShadow(block: DesignBlock): Boolean ``` Query if the given block has a drop shadow property. - `block`: the block to query. - Returns true if the block has a drop shadow property, false otherwise. ```kotlin fun setDropShadowEnabled( block: DesignBlock, enabled: Boolean, ) ``` Enable or disable the drop shadow of the given design block. Required scope: "appearance/shadow" - `block`: the block whose drop shadow should be enabled or disabled. - `enabled`: if true, the drop shadow will be enabled. ```kotlin fun isDropShadowEnabled(block: DesignBlock): Boolean ``` Query if the drop shadow of the given design block is enabled. - `block`: the block whose drop shadow should be queried. - Returns true if the block's drop shadow is enabled, false otherwise. ```kotlin fun setDropShadowColor( block: DesignBlock, color: Color, ) ``` Set the drop shadow color of the given design block. Required scope: "appearance/shadow" - `block`: the block whose drop shadow color should be set. - `color`: the color to set. ```kotlin fun getDropShadowColor(block: DesignBlock): Color ``` Get the drop shadow color of the given design block. - `block`: the block whose drop shadow color should be queried. - Returns the drop shadow color. ```kotlin fun setDropShadowOffsetX( block: DesignBlock, offsetX: Float, ) ``` Set the drop shadow's x offset of the given design block. Required scope: "appearance/shadow" - `block`: the block whose drop shadow's x offset should be set. - `offsetX`: the x offset to be set. ```kotlin fun setDropShadowOffsetY( block: DesignBlock, offsetY: Float, ) ``` Set the drop shadow's y offset of the given design block. Required scope: "appearance/shadow" - `block`: the block whose drop shadow's y offset should be set. - `offsetY`: the y offset to be set. ```kotlin fun getDropShadowOffsetX(block: DesignBlock): Float ``` Get the drop shadow's x offset of the given design block. - `block`: the block whose drop shadow's x offset should be queried. - Returns the offset. ```kotlin fun getDropShadowOffsetY(block: DesignBlock): Float ``` Get the drop shadow's y offset of the given design block. - `block`: the block whose drop shadow's y offset should be queried. - Returns the offset. ```kotlin fun setDropShadowBlurRadiusX( block: DesignBlock, blurRadiusX: Float, ) ``` Set the drop shadow's blur radius on the x axis of the given design block. Required scope: "appearance/shadow" - `block`: the block whose drop shadow's blur radius on the x axis should be set. - `blurRadiusX`: the blur radius to be set. ```kotlin fun setDropShadowBlurRadiusY( block: DesignBlock, blurRadiusY: Float, ) ``` Set the drop shadow's blur radius on the y axis of the given design block. Required scope: "appearance/shadow" - `block`: the block whose drop shadow's blur radius on the y axis should be set. - `blurRadiusY`: the blur radius to be set. ```kotlin fun setDropShadowClip( block: DesignBlock, clip: Boolean, ) ``` Set the drop shadow's clipping of the given design block. (Only applies to shapes.) Required scope: "appearance/shadow" - `block`: the block whose drop shadow's clip should be set. - `clip`: the drop shadow's clip to be set. ```kotlin fun getDropShadowClip(block: DesignBlock): Boolean ``` Get the drop shadow's clipping of the given design block. - `block`: the block whose drop shadow's clipping should be queried. - Returns the drop shadow's clipping. ```kotlin fun getDropShadowBlurRadiusX(block: DesignBlock): Float ``` Get the drop shadow's blur radius on the x axis of the given design block. - `block`: the block whose drop shadow's blur radius on the x axis should be queried. - Returns the blur radius. ```kotlin fun getDropShadowBlurRadiusY(block: DesignBlock): Float ``` Get the drop shadow's blur radius on the y axis of the given design block. - `block`: the block whose drop shadow's blur radius on the y axis should be queried. - Returns the blur radius. ## Full Code Here's the full code: ```kotlin // Configure a basic colored drop shadow if the block supports them if (engine.block.supportsDropShadow(block)) { engine.block.setDropShadowEnabled(block, enabled = true) engine.block.setDropShadowColor(block, Color.fromRGBA(r = 1F, g = 0.75F, b = 0.8F, a = 1F)) val dropShadowColor = engine.block.getDropShadowColor(block) engine.block.setDropShadowOffsetX(block, offsetX = -10F) engine.block.setDropShadowOffsetY(block, offsetY = 5F) val dropShadowOffsetX = engine.block.getDropShadowOffsetX(block); val dropShadowOffsetY = engine.block.getDropShadowOffsetY(block); engine.block.setDropShadowBlurRadiusX(block, blurRadiusX = -10F) engine.block.setDropShadowBlurRadiusY(block, blurRadiusY = 5F) engine.block.setDropShadowClip(block, clip = false) val dropShadowClip = engine.block.getDropShadowClip(block) // Query a blocks drop shadow properties val dropShadowIsEnabled = engine.block.isDropShadowEnabled(block) val dropShadowBlurRadiusX = engine.block.getDropShadowBlurRadiusX(block) val dropShadowBlurRadiusY = engine.block.getDropShadowBlurRadiusY(block) } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Using Strokes" description: "Add and customize outlines around shapes, text, or images using stroke settings." platform: android url: "https://img.ly/docs/cesdk/android/outlines/strokes-c2e621/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Outlines](https://img.ly/docs/cesdk/android/outlines-b7820c/) > [Stroke (Outline)](https://img.ly/docs/cesdk/android/outlines/strokes-c2e621/) --- In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to modify strokes through the `block` API. Strokes can be added to any shape or text and stroke styles are varying from plain solid lines to dashes and gaps of varying lengths and can have different end caps. ## Strokes ```kotlin fun supportsStroke(block: DesignBlock): Boolean ``` Query if the given block has a stroke property. - `block`: the block to query. - Returns true if the block has a stroke property, false otherwise. ```kotlin fun setStrokeEnabled( block: DesignBlock, enabled: Boolean, ) ``` Enable or disable the stroke of the given design block. Required scope: "stroke/change" - `block`: the block whose stroke should be enabled or disabled. - `enabled`: if true, the stroke will be enabled. ```kotlin fun isStrokeEnabled(block: DesignBlock): Boolean ``` Query if the stroke of the given design block is enabled. - `block`: the block whose stroke state should be queried. - Returns true if the block's stroke is enabled, false otherwise. ```kotlin fun setStrokeColor( block: DesignBlock, color: Color, ) ``` Set the stroke color of the given design block. Required scope: "stroke/change" - `block`: the block whose stroke color should be set. - `color`: the color to set. ```kotlin fun getStrokeColor(block: DesignBlock): Color ``` Get the stroke color of the given design block. - `block`: he block whose stroke color should be queried. - Returns the stroke color. ```kotlin fun setStrokeWidth( block: DesignBlock, width: Float, ) ``` Set the stroke width of the given design block. Required scope: "stroke/change" - `block`: the block whose stroke width should be set. - `width`: the stroke width to be set. ```kotlin fun getStrokeWidth(block: DesignBlock): Float ``` Get the stroke width of the given design block. - `block`: the block whose stroke width should be queried. - Returns the stroke's width. ```kotlin fun setStrokeStyle( block: DesignBlock, style: StrokeStyle, ) ``` Set the stroke style of the given design block. Required scope: "stroke/change" - `block`: the block whose stroke style should be set. - `style`: the stroke style to be set. ```kotlin fun getStrokeStyle(block: DesignBlock): StrokeStyle ``` Get the stroke style of the given design block. - `block`: the block whose stroke style should be queried. - Returns the stroke's style. ```kotlin fun setStrokePosition( block: DesignBlock, position: StrokePosition, ) ``` Set the stroke position of the given design block. Required scope: "stroke/change" - `block`: the block whose stroke position should be set. - `position`: the stroke position to be set. ```kotlin fun getStrokePosition(block: DesignBlock): StrokePosition ``` Get the stroke position of the given design block. - `block`: the block whose stroke position should be queried. - Returns the stroke position. ```kotlin fun setStrokeCornerGeometry( block: DesignBlock, geometry: StrokeCornerGeometry, ) ``` Set the stroke corner geometry of the given design block. Required scope: "stroke/change" - `block`: the block whose stroke join geometry should be set. - `geometry`: the stroke join geometry to be set. ```kotlin fun getStrokeCornerGeometry(block: DesignBlock): StrokeCornerGeometry ``` Get the stroke corner geometry of the given design block. - `block`: the block whose stroke join geometry should be queried. - Returns the stroke join geometry. ## Full Code Here's the full code for using strokes: ```kotlin // Check if block supports strokes if (engine.block.supportsStroke(block)) { // Enable the stroke engine.block.setStrokeEnabled(block, enabled = true) val strokeIsEnabled = engine.block.isStrokeEnabled(block) // Configure it engine.block.setStrokeColor(block, color = Color.fromRGBA(r = 1F, g = 0.75F, b = 0.8F, a = 1F)) val strokeColor = engine.block.getStrokeColor(block) engine.block.setStrokeWidth(block, width = 5F) val strokeWidth = engine.block.getStrokeWidth(block) engine.block.setStrokeStyle(block, style = StrokeStyle.DASHED) val strokeStyle = engine.block.getStrokeStyle(block) engine.block.setStrokePosition(block, position = StrokePosition.OUTER) val strokePosition = engine.block.getStrokePosition(block) engine.block.setStrokeCornerGeometry(block, geometry = StrokeCornerGeometry.ROUND) val strokeCornerGeometry = engine.block.getStrokeCornerGeometry(block) } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Overview" description: "Understand how insertion works, how inserted media behave within scenes, and how to control them via UI or code." platform: android url: "https://img.ly/docs/cesdk/android/overview-491658/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Insert Media Assets](https://img.ly/docs/cesdk/android/insert-media-a217f5/) > [Overview](https://img.ly/docs/cesdk/android/overview-491658/) --- In CE.SDK, *inserting media into a scene* means placing visual or audio elements directly onto the canvas—images, videos, audio clips, shapes, or stickers—so they become part of the design. This differs from *importing assets*, which simply makes media available in the asset library. This guide helps you understand how insertion works, how inserted media behave within scenes, and how to control them via UI or code. By the end, you'll know how media are represented, modified, saved, and exported. [Explore Demos](https://img.ly/showcases/cesdk?tags=android) [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) ## Inserting Media --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Solutions" description: "Production-ready editor configurations for CE.SDK" platform: android url: "https://img.ly/docs/cesdk/android/prebuilt-solutions-d0ed07/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Solutions](https://img.ly/docs/cesdk/android/prebuilt-solutions-d0ed07/) --- Choose a starter kit to get up and running quickly with CE.SDK. Each kit provides a complete, customizable editor configuration. ## Choosing the Right Starter Kit Each starter kit is optimized for a specific workflow. Pick the one that matches your use case: ### Photo Editing Use **Photo Editor** when your users need to edit single images—crop, apply filters, adjust colors, or remove backgrounds. Ideal for profile photo uploads, product image editing, or any workflow where users enhance one image at a time. ### Graphic Design Use **Design Editor** when your users create graphics with multiple elements—social media posts, marketing materials, or personalized templates. Supports text, images, shapes, and multi-page documents like presentations or brochures. For power users who need full creative control, **Design Editor (Advanced)** adds a comprehensive toolbar, layer management, and professional design tools. ### Video Production Use **Video Editor** when your users need to edit video content—trim clips, add effects, overlay text, and export to MP4. Perfect for social media videos, short-form content, or basic video editing workflows. For professional video production with multi-track timelines, transitions, and audio mixing, choose **Video Editor (Advanced)**. ### Read-Only Display Use **Design Viewer** or **Video Player** when you need to display content without editing capabilities. These lightweight kits are ideal for approval workflows, content previews, or embedding finished designs in your application. --- ## Related Pages - [Android Photo Editor SDK](https://img.ly/docs/cesdk/android/prebuilt-solutions/photo-editor-42ccb2/) - The CreativeEditor SDK provides a robust and user-friendly solution for photo editing on Android devices. - [Android Design Tool & Design Editor](https://img.ly/docs/cesdk/android/prebuilt-solutions/design-editor-9bf041/) - Embed a ready-to-use design editor that lets users personalize templates while respecting layout constraints. - [Android Video Editor SDK](https://img.ly/docs/cesdk/android/prebuilt-solutions/video-editor-9e533a/) - The CreativeEditor SDK offers a comprehensive and versatile solution for video editing on Android devices. - [T-Shirt Designer in Android](https://img.ly/docs/cesdk/android/prebuilt-solutions/t-shirt-designer-02b48f/) - Embed a t-shirt design editor with print areas, PDF export, and a focused UI for apparel customization. - [Android Postcard Editor SDK](https://img.ly/docs/cesdk/android/prebuilt-solutions/postcard-editor-61e1f6/) - Let users personalize postcards with templates, style presets, and print-ready exports—no design skills needed. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Android Design Tool & Design Editor" description: "Embed a ready-to-use design editor that lets users personalize templates while respecting layout constraints." platform: android url: "https://img.ly/docs/cesdk/android/prebuilt-solutions/design-editor-9bf041/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Solutions](https://img.ly/docs/cesdk/android/prebuilt-solutions-d0ed07/) > [Design Editor](https://img.ly/docs/cesdk/android/prebuilt-solutions/design-editor-9bf041/) --- Give your users a fast, intuitive way to personalize templates with layout, text, and image editing — no design experience needed. The Design Editor comes ready to use and can be easily added to your Android app with minimal setup. [Explore Demo](https://img.ly/showcases/cesdk/default-ui/android) [View on GitHub](https://github.com/imgly/cesdk-android-examples/tree/main/editor-guides-solutions-design-editor) ## What is the Design Editor Solution? The Design Editor is a pre-built configuration of the CreativeEditor SDK (CE.SDK), tailored for non-professional users to easily adapt and personalize existing templates. It’s optimized for workflows that focus on editing layout elements like text, images, and shapes — all within clearly defined design constraints. Whether you're building a product customization app, dynamic ad creator, or template-based marketing tool, the Design Editor brings a polished, user-friendly interface to your users — right out of the box. ## Key Features - **Template-based editing**\ Empower users to customize existing templates while preserving brand integrity and layout rules. - **Smart context menus**\ Clicking an element opens a simplified editing toolbar, showing only the most relevant actions — like replacing or cropping an image. - **Streamlined user interface**\ The interface is designed to surface essential tools first. A “More” button reveals the full set of features for deeper editing. - **Role-based permissions**\ Easily toggle between *Creator* and *Adopter* roles to define what elements users can modify, lock, or hide. - **Cross-platform support**\ Available for Web, iOS, Android, and Desktop — all powered by the same core SDK. ## Why Use This Solution? The Design Editor is the fastest way to offer layout editing with production-ready UX. It reduces the effort of building a complete UI from scratch, while giving you full control over customization and integration. Choose this solution if you want to: - Provide a ready-to-use template editor that feels intuitive to end users - Accelerate your time to market with a polished layout editing experience - Maintain creative control by restricting editable areas with template constraints - Avoid building custom design tooling for every use case --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Android Photo Editor SDK" description: "The CreativeEditor SDK provides a robust and user-friendly solution for photo editing on Android devices." platform: android url: "https://img.ly/docs/cesdk/android/prebuilt-solutions/photo-editor-42ccb2/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Solutions](https://img.ly/docs/cesdk/android/prebuilt-solutions-d0ed07/) > [Photo Editor](https://img.ly/docs/cesdk/android/prebuilt-solutions/photo-editor-42ccb2/) --- The CreativeEditor SDK provides a robust and user-friendly solution for photo editing on Android devices. The photo UI is a specific configuration of the CE.SDK UI which enables developers to seamlessly integrate essential photo editing features into their Android applications, offering users a powerful yet intuitive editing experience. Whether you are developing an app for social media, content creation, or any other platform requiring photo editing tools, the CE.SDK Android Photo Editor is designed to meet your needs. [Explore Demo](https://img.ly/showcases/cesdk/photo-editor-ui/android) [View on GitHub](https://github.com/imgly/cesdk-android/blob/main/sources/editor/src/main/java/ly/img/editor/PhotoEditor.kt) ## Key Capabilities of the iOS Mobile Design Editor SDK ## What is the Photo Editor Solution? The Photo Editor is a fully customizable CE.SDK configuration focused on photo-centric use cases. It strips down the editor interface to include only the most relevant features for image adjustments — giving users a focused and responsive experience. Whether your users need to fine-tune selfies, prepare product photos, or create profile images, this solution makes it easy. Get a powerful photo editor into your app with minimal setup. The Photo Editor runs entirely client-side — which helps reduce cloud computing costs and improve privacy. ## Platform Compatibility The CE.SDK Photo Editor is optimized for use on Android devices, providing smooth and efficient performance across a variety of models. ## Prerequisites To get started with the CE.SDK Photo Editor on Android, ensure you have the latest version of Android Studio and Kotlin installed. ## Supported File Types The CE.SDK Photo Editor supports various image formats, enabling users to work with popular file types. ### Importing Media ### Exporting Media ### Importing Templates For detailed information, see the [full file format support list](https://img.ly/docs/cesdk/android/file-format-support-3c4b2a/). ## Understanding CE.SDK Architecture & API The following sections provide an overview of the key components of the CE.SDK photo editor UI and its API architecture. If you're ready to start integrating CE.SDK into your Android application, check out our Implementation Guide. ### CreativeEditor SDK Mobile Photo UI The CE.SDK photo editor UI is a streamlined configuration of the CreativeEditor SDK, focusing on essential photo editing features. This configuration is fully customizable, allowing developers to adjust the UI and functionality to suit different use cases. Key components include: - **Canvas:** The primary workspace where users interact with their photo content. - **Inspector Bar:** Offers tools for adjusting properties like size, position, and effects for selected elements. - **Asset Library:** A collection of media resources available for use within the photo editor, including images and stickers. Learn more about interacting with and customizing the photo editor UI in our design editor UI guide. ### CreativeEngine At the heart of CE.SDK is the CreativeEngine, which powers all rendering and photo manipulation tasks. It can be used in headless mode or in combination with the CreativeEditor UI. Key features and APIs provided by CreativeEngine include: - **Scene Management:** Create, load, save, and manipulate photo scenes programmatically. - **Block Management:** Manage images, text, and other elements within the photo editor. - **Asset Management:** Integrate and manage photo and image assets from various sources. - **Variable Management:** Define and manipulate variables for dynamic content within photo scenes. - **Event Handling:** Subscribe to events like image selection changes or editing actions for dynamic interaction. ## Customizing the Android Image Editor CE.SDK provides extensive [customization options](https://img.ly/docs/cesdk/android/user-interface-5a089a/), allowing you to tailor the UI and functionality to meet your specific needs. This can range from basic configuration settings to more advanced customizations involving custom asset sources and [hooking into UIEvents](https://img.ly/docs/cesdk/android/user-interface/events-514b70/). ### Basic Customizations - **Configuration Object:** Customize the editor’s appearance and functionality by passing a configuration object during initialization. ```kotlin val engineConfiguration = EngineConfiguration.rememberForPhoto( license = "", imageUri = Uri.parse("https://img.ly/static/ubq_samples/sample_4.jpg"), imageSize = SizeF(1080F, 1920F), userId = "", ) ``` - **Custom Asset Sources:** Serve custom images or stickers from a remote URL. ### UI Customization Options - **Theme:** Choose between 'dark' or 'light' themes. ```kotlin val editorConfiguration = EditorConfiguration.rememberForPhoto( uiMode = EditorUiMode.DARK, ) ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Android Postcard Editor SDK" description: "Let users personalize postcards with templates, style presets, and print-ready exports—no design skills needed." platform: android url: "https://img.ly/docs/cesdk/android/prebuilt-solutions/postcard-editor-61e1f6/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Solutions](https://img.ly/docs/cesdk/android/prebuilt-solutions-d0ed07/) > [Postcard Editor](https://img.ly/docs/cesdk/android/prebuilt-solutions/postcard-editor-61e1f6/) --- The Postcard Editor is a prebuilt CreativeEditor SDK (CE.SDK) solution designed for quickly creating and personalizing postcards and greeting cards. It provides an intuitive UI that guides users through selecting a design, editing its contents, and customizing messaging—all without needing design expertise. This ready-to-use editor can be easily added to your Android app and fully customized to match your brand, making it ideal for direct mail campaigns, seasonal greetings, or personalized customer engagement. [Explore Demo](https://img.ly/showcases/cesdk/post-greeting-cards/android) [View on GitHub](https://github.com/imgly/cesdk-web-examples/tree/main/showcase-post-greeting-cards) ## What is the Postcard Editor Solution? The Postcard Editor is a prebuilt CreativeEditor SDK (CE.SDK) solution designed for quickly creating and personalizing postcards and greeting cards. It provides an intuitive UI that guides users through selecting a design, editing its contents, and customizing messaging—all without needing design expertise. With built-in support for style presets, design constraints, and variable-driven personalization, the Postcard Editor enables scalable creation of high-quality, print-ready content for direct mail, seasonal greetings, and personalized campaigns. ## Key Features - **Style presets**\ Jump-start the design process with a collection of professionally crafted postcard templates. - **Design mode**\ After selecting a style, users can personalize the design. Depending on the template configuration, they can: - Change accent and background colors - Replace photos from a library or upload their own - Edit headings and body text (fonts, colors, layout) - Add stickers, shapes, or other decorative elements - **Write mode**\ Users can add a personal message and address the card. Text styling options include font, size, and color customization. - **Dynamic variables**\ Enable scalable personalization using variables like `{{firstname}}` or `{{address}}`. Templates can be connected to external data sources for automated batch generation. - **Print-ready export**\ Designs are exported in high-resolution, print-friendly formats, suitable for direct mail or digital delivery. ## Why Use This Solution? - **Accelerate development**\ Save time with a pre-configured UI that’s production-ready and easily customizable via CE.SDK’s headless API. - **Empower non-designers**\ Make creative tools accessible to any user by enforcing design constraints and simplifying the editing experience. - **Scale personalization**\ Integrate with external data to programmatically generate personalized postcards for marketing, e-commerce, or events. - **Cross-platform ready**\ The Postcard Editor works across web, mobile, and desktop environments, offering a seamless user experience wherever it’s deployed. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "T-Shirt Designer in Android" description: "Embed a t-shirt design editor with print areas, PDF export, and a focused UI for apparel customization." platform: android url: "https://img.ly/docs/cesdk/android/prebuilt-solutions/t-shirt-designer-02b48f/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Solutions](https://img.ly/docs/cesdk/android/prebuilt-solutions-d0ed07/) > [T-Shirt Designer](https://img.ly/docs/cesdk/android/prebuilt-solutions/t-shirt-designer-02b48f/) --- Quickly add a professional-grade t-shirt design editor to your Android app with CE.SDK. [Explore Demo](https://img.ly/showcases/cesdk/apparel-editor-ui/android) [View on GitHub](https://github.com/imgly/cesdk-android-examples/tree/main/editor-guides-solutions-apparel-editor) ## What is the T-Shirt Designer Solution? The T-Shirt Designer is a pre-configured instance of the CreativeEditor SDK (CE.SDK) tailored for apparel design workflows. It enables your users to create high-quality, print-ready t-shirt designs directly in your app—whether for a custom merchandise platform, print-on-demand storefront, or internal design tool. This solution comes with a realistic t-shirt mockup background, precise boundary enforcement, and a simplified UI. You can easily integrate it across web, mobile, or desktop platforms and customize it to match your brand or workflow. ## Key Features - **T-Shirt backdrop with placement guidance**\ A visually accurate t-shirt background helps users place artwork exactly where it will appear when printed. - **Strict print area enforcement**\ Elements that extend beyond the defined print region are clipped automatically, ensuring print precision. - **Placeholder-based template editing**\ Supports templates with editable placeholders, such as swappable images. Define which parts of a design are user-editable by toggling between Creator and Adopter modes. - **Print-ready PDF export**\ Outputs print-quality PDFs to seamlessly fit into your existing production workflows. - **Fully customizable UI**\ Adapt the interface and features to suit your brand and user needs using the CE.SDK configuration API. ## Why Use This Solution? - **Accelerated development**\ Save engineering time with a ready-made editor specifically configured for t-shirt design. - **Better user experience**\ The focused UI reduces complexity, guiding users through apparel creation with built-in visual feedback and safeguards. - **Seamless print integration**\ The export format and boundary enforcement make it ideal for print-on-demand systems with no additional post-processing required. - **Flexible and extensible**\ As with all CE.SDK solutions, the T-Shirt Designer is deeply customizable—extend features, change design constraints, or integrate external data and asset libraries. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Android Video Editor SDK" description: "The CreativeEditor SDK offers a comprehensive and versatile solution for video editing on Android devices." platform: android url: "https://img.ly/docs/cesdk/android/prebuilt-solutions/video-editor-9e533a/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Solutions](https://img.ly/docs/cesdk/android/prebuilt-solutions-d0ed07/) > [Video Editor](https://img.ly/docs/cesdk/android/prebuilt-solutions/video-editor-9e533a/) --- The CreativeEditor SDK offers a comprehensive and versatile solution for video editing on Android devices. The CE.SDK video editor enables developers to integrate powerful video editing capabilities into their Android applications, providing users with an intuitive and fully customizable editing experience. Whether you're building an app for social media, content creation, or any other platform that requires robust video editing tools, the CE.SDK Android Video Editor is designed to meet your needs. [Explore Demo](https://img.ly/showcases/cesdk/video-ui/android) [View on GitHub](https://github.com/imgly/cesdk-android/blob/main/sources/editor/src/main/java/ly/img/editor/VideoEditor.kt) ## Key Capabilities of the Android Mobile Video Editor SDK ## What is the Video Editor Solution? The Video Editor is a prebuilt solution powered by the CreativeEditor SDK (CE.SDK) that enables fast integration of high-performance video editing into web, mobile, and desktop applications. It’s designed to help your users create professional-grade videos—from short social clips to long-form stories—directly within your app. Skip building a video editor from scratch. This fully client-side solution provides a solid foundation with an extensible UI and a robust engine API to power video editing in any use case. ## Supported Platforms The Android Mobile Video Editor SDK is compatible with Android applications developed using Kotlin or Java, offering full support for both languages. ## Prerequisites Ensure that the **IMGLYUI Android Library** is added to your project. The SDK requires a license key, use `null` or an empty string to run in evaluation mode with watermark. Additionally, you can provide unique user IDs for accurate user tracking. ## Supported Media Types [IMG.LY](http://img.ly/)'s Creative Editor SDK enables you to load, edit, and save **MP4 files** directly on the device without server dependencies. ### Importing Media ### Exporting Media ### Importing Templates For detailed information, see the [full file format support list](https://img.ly/docs/cesdk/android/file-format-support-3c4b2a/). ## Understanding CE.SDK Architecture & API The following sections provide an overview of the key components of the CE.SDK video editor UI and its API architecture. If you're ready to start integrating CE.SDK into your Android application, check out our Implementation Guide. ### CreativeEditor SDK Mobile Video UI The CE.SDK video editor UI is a specific configuration of the CreativeEditor SDK, focusing on essential video editing features. It includes robust tools for video manipulation, customizable to suit different use cases. Key components include the **Canvas**, the main workspace where users interact with their video content. The **Timeline** provides control over the sequence and duration of video clips, images, and audio tracks. The **Tool Bar** provides essential editing options like adjustments, filters, effects, layer management or adding text or images in order of relevance. Lastly, the **Context Menu** presents relevant editing options for each selected element, simplifying the editing process for users. Learn more about interacting with and customizing the video editor UI in our design editor UI guide. ### CreativeEngine At the core of CE.SDK is the CreativeEngine, which handles all rendering and video manipulation tasks. It can be used in headless mode or alongside the CreativeEditor UI. Key features and APIs provided by CreativeEngine include functionalities for **Scene Management:** to create, load, save, and manipulate video scenes programmatically. **Block Management:** to manage video clips, images, text, and other elements within the timeline. **Asset Management:** to integrate and manage video, audio, and image assets from various sources. **Variable Management:** to define and manipulate variables for dynamic content within video scenes and **Event Handling:** to subscribe to events like clip selection changes or timeline updates for dynamic interaction. ## Customizing the Android Video Editor CE.SDK provides extensive customization options, allowing you to tailor the UI and functionality to meet your specific needs. This can range from basic configuration settings to more advanced customizations involving callbacks and custom elements. ### Basic Customizations - [Configuration Object:](https://img.ly/docs/cesdk/android/user-interface/customization-72b2f8/) Customize the editor’s appearance and functionality by passing a configuration object during initialization. - [Custom Asset Sources:](https://img.ly/docs/cesdk/android/import-media/asset-panel/customize-c9a4de/) Serve custom video clips or audio tracks from a remote URL. See the video editor getting started page for more configuration examples. ### UI Customization Options The editor's appearance can be customized with options like choosing between 'dark' or 'light' themes. You can also configure the editor color palette to match a particular CI. [- Hook into UI Events:](https://img.ly/docs/cesdk/android/user-interface/events-514b70/) Register event listener for UI events, for example, this would allow you to display a loading spinner while the editor is being initialized. ## Framework Support CreativeEditor SDK’s video editor is compatible with Swift and Objective-C, making it easy to integrate into any Android application. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Rules" description: "Define and enforce layout, branding, and safety rules to ensure consistent and compliant designs." platform: android url: "https://img.ly/docs/cesdk/android/rules-1427c0/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Rules](https://img.ly/docs/cesdk/android/rules-1427c0/) --- --- ## Related Pages - [Overview](https://img.ly/docs/cesdk/android/rules/overview-e27832/) - Define and enforce layout, branding, and safety rules to ensure consistent and compliant designs. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Overview" description: "Define and enforce layout, branding, and safety rules to ensure consistent and compliant designs." platform: android url: "https://img.ly/docs/cesdk/android/rules/overview-e27832/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Rules](https://img.ly/docs/cesdk/android/rules-1427c0/) > [Overview](https://img.ly/docs/cesdk/android/rules/overview-e27832/) --- In CreativeEditor SDK (CE.SDK), *rules*—referred to as **scopes** in the API and code—are automated validations that help enforce design and layout standards during editing. You can use scopes to maintain brand guidelines, ensure print readiness, moderate content, and enhance the overall editing experience. Scopes can be applied to both designs and videos, helping you deliver high-quality outputs while reducing the risk of common mistakes. [Explore Demos](https://img.ly/showcases/cesdk?tags=android) [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Security" description: "Learn how CE.SDK keeps your data private with client-side processing, secure licensing, and GDPR-compliant practices." platform: android url: "https://img.ly/docs/cesdk/android/security-777bfd/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Compatibility & Security](https://img.ly/docs/cesdk/android/compatibility-fef719/) > [Security](https://img.ly/docs/cesdk/android/security-777bfd/) --- This document provides a comprehensive overview of CE.SDK's security practices, focusing on data handling, privacy, and our commitment to maintaining the highest standards of security for our customers and their end users. ## Key Security Features - **Client-Side Processing**: All image and design processing occurs directly on the user's device or your servers, not on our servers - **No Data Transmission**: Your content (e.g. images, designs, templates, videos, audio, etc.) is never uploaded to or processed on IMG.LY servers - **Minimal Data Collection**: We only collect device identifiers and count exports for licensing purposes - **GDPR Compliance**: Our data collection practices adhere to GDPR regulations - **Secure Licensing**: Enterprise licenses are secured with RSA SHA256 encryption ## Data Protection & Access Controls ### Data Collection CE.SDK requires minimal data to provide its services. The only potentially personally identifiable information (PII) collected includes device-specific identifiers such as `identifierForVendor` on iOS and `ANDROID_ID` on Android. These identifiers are: - Used solely for tracking monthly active users for our usage-based pricing models - Reset when the user reinstalls the app or resets their device - Collected under GDPR's legitimate interest provision (no explicit consent required as they are necessary for our licensing system) Additionally, we track export operations for billing purposes in usage-based pricing models. For enterprise customers who prefer more accurate tracking, integrators can provide their own userID. This allows for more precise measurement of usage without requiring additional device identifiers. ### Data Storage & Encryption **We do not collect or store user data beyond the device identifiers and export counts mentioned above.** Since CE.SDK operates entirely client-side: - All content processing happens on the user's device - No images, designs, or user content is transmitted to IMG.LY servers - No content data is stored on IMG.LY infrastructure We use standard HTTPS (SSL/TLS) encryption for all communications between CE.SDK instances and our licensing backend. ### Access Controls We are using established industry standard practices to handle sensitive customer data. Therefore access control concerns are minimized. The limited data we do handle is protected as follows: - Billing information is stored in Stripe and accessed only by members of our finance team and C-level executives - API keys and credentials are stored securely in 1Password or GitHub with granular access levels - All employees sign Confidentiality Agreements to protect customer information This refers to data of our direct customers, not their users or customers. ## Licensing System CE.SDK uses a licensing system that works as follows: 1. During instantiation, an API key is provided to the CE.SDK instance 2. This API key is held in memory (never stored permanently on the device) 3. The SDK validates the key with our licensing backend 4. Upon successful validation, the backend returns a temporary local license 5. This license is periodically refreshed to maintain valid usage For browser implementations, we protect licenses against misuse by pinning them to specific domains. For mobile applications, licenses are pinned to the application identifiers to prevent unauthorized use. For enterprise customers, we offer an alternative model: - A license file is passed directly to the instance - No communication with our licensing service is required - Licenses are secured using RSA SHA256 encryption ### CE.SDK Renderer CE.SDK Renderer is a specialized variant of CE.SDK that consists of a native Linux binary bundled in a Docker container. It uses GPU acceleration and native code to render scenes and archives to various export formats. Due to bundled third-party codecs (mainly H.264 & H.265) and their associated patent requirements, CE.SDK Renderer implements additional licensing communication beyond the standard licensing handshake: 1. **Initial License Validation**: The tool performs the standard license validation with our licensing backend 2. **Periodic Heartbeats**: After successful validation, it sends periodic heartbeats to our licensing backend to track the number of active instances 3. **Instance Limits**: We limit the maximum number of active instances per license based on the settings in your dashboard 4. **Activation Control**: If the instance limit is exceeded, further activations (launches) of the tool will fail with a descriptive error message This additional communication allows us to ensure compliance with codec licensing requirements while providing transparent usage tracking for your organization. As with all CE.SDK products, no user data (images, videos, designs, or other content) is transmitted to IMG.LY servers - only device identifiers and instance counts are collected for licensing purposes. ## Security Considerations for User Input As CE.SDK deals primarily with arbitrary user input, we've implemented specific security measures to handle data safely: - The CreativeEngine reads files from external resources to fetch images, fonts, structured data, and other sources for designs. These reads are safeguarded by platform-specific default measures. - The engine never loads executable code or attempts to execute any data acquired from dynamic content. It generally relies on provided mime types to decode image data or falls back to byte-level inspection to choose the appropriate decoder. - For data writing operations, we provide a callback that returns a pointer to the to-be-written data. The engine itself never unconditionally writes to an externally defined path. If it writes to files directly, these are part of internal directories and can't be modified externally. - Generated PDFs may have original image files embedded if the image was not altered via effects or blurs and the `exportPdfWithHighCompatibility` option was **not** enabled. This means a malicious image file could theoretically be included in the exported PDF. - Inline text-editing allows arbitrary input of strings by users. The engine uses platform-specific default inputs and APIs and doesn't apply additional sanitization. The acquired strings are stored and used exclusively for text rendering - they are neither executed nor used for file operations. ## Security Infrastructure ### Vulnerability Management We take a proactive approach to security vulnerability management: - We use GitHub to track dependency vulnerabilities - We regularly update affected dependencies - We don't maintain a private network, eliminating network vulnerability concerns in that context - We don't manually maintain servers or infrastructure, as we don't have live systems beyond those required for licensing - For storage and licensing, we use virtual instances in Google Cloud which are managed by the cloud provider - All security-related fixes are published in our public changelog at [https://img.ly/docs/cesdk/changelog/](https://img.ly/docs/cesdk/changelog/) ### Security Development Practices Our development practices emphasize security: - We rely on established libraries with proven security track records - We don't directly process sensitive user data in our code - Secrets (auth tokens, passwords, API credentials, certificates) are stored in GitHub or 1Password with granular access levels - We use RSA SHA256 encryption for our enterprise licenses - We rely on platform-standard SSL implementations for HTTPS communications ### API Key Management API keys for CE.SDK are handled securely: - Keys are passed during instantiation and held in memory only - Keys are never stored permanently on client devices - For web implementation, keys are pinned to specific domains to prevent unauthorized use - Enterprise licenses use a file-based approach that doesn't require API key validation ## Compliance IMG.LY complies with the General Data Protection Regulation (GDPR) in all our operations, including CE.SDK. Our Privacy Policy is publicly available at [https://img.ly/privacy-policy](https://img.ly/privacy-policy). Our client-side approach to content processing significantly reduces privacy and compliance concerns, as user content never leaves their device environment for processing. ## FAQ ### Does CE.SDK upload my images or designs to IMG.LY servers? No. CE.SDK processes all content locally on the user's device. Your images, designs, and other content are never transmitted to IMG.LY servers. ### What data does IMG.LY collect through CE.SDK? CE.SDK only collects device identifiers (such as identifierForVendor on iOS or ANDROID\_ID on Android) for licensing purposes and export counts. No user content or personal information is collected. ### How does IMG.LY protect API keys? API keys are never stored permanently; they are held in memory during SDK operation. For web implementations, keys are pinned to specific domains to prevent unauthorized use. ### Has IMG.LY experienced any security breaches? No, IMG.LY has not been involved in any cybersecurity breaches in the last 12 months. ### Does IMG.LY conduct security audits? As we don't store customer data directly, but rely on third parties to do so, we focus our security efforts on dependency tracking and vulnerability management through GitHub's security features. We don't conduct security audits. ## Additional Information For more detailed information about our data collection practices, please refer to our Data Privacy and Retention information below. Should you have any additional questions regarding security practices or require more information, please contact our team at [support@img.ly](mailto:support@img.ly). ## Data Privacy and Retention At IMG.LY, we prioritize your data privacy and ensure that apart from a minimal contractually stipulated set of interactions with our servers all other operations take place on your local device. Below is an overview of our data privacy and retention policies: ### **Data Processing** All data processed by CE.SDK remains strictly on your device. We do not transfer your data to our servers for processing. This means that operations such as rendering, editing, and other in-app functionalities happen entirely locally, ensuring that sensitive project or personal data stays with you. ### **Data Retention** We do not store any project-related data on our servers. Since all data operations occur locally, no information about your edits, images, or video content is retained by CE.SDK. The only data that interacts with our servers is related to license validation and telemetry related to usage tied to your pricing plan. ### **License Validation** CE.SDK performs a license validation check with our servers once upon initialization to validate the software license being used. This interaction is minimal and does not involve the transfer of any personal, project, or media data. ### **Event Tracking** While CE.SDK does not track user actions other than the exceptions listed below through telemetry or analytics by default, there are specific events tracked to manage customer usage, particularly for API key usage tracking. We gather the following information during these events: - **When the engine loads:** App identifier, platform, engine version, user ID (provided by the client), device ID (mobile only), and session ID. - **When a photo or video is exported:** User ID, device ID, session ID, media type (photo/video), resolution (width and height), FPS (video only), and duration (video only). This tracking is solely for ensuring accurate usage calculation and managing monthly active user billing. Enterprise clients can opt out of this tracking under specific agreements. ### **Personal Identifiable Information (PII)** The only PII that is potentially collected includes device-specific identifiers such as `identifierForVendor` on iOS and `ANDROID_ID` on Android. These IDs are used for tracking purposes and are reset when the user reinstalls the app or resets the device. No consent is required for these identifiers because they are crucial for our usage-based pricing models. This is covered by the GDPR as legitimate interest. ### **User Consent** As mentioned above, user consent is not required when solely using the CE.SDK. However, this may change depending on the specific enterprise agreement or additional regulatory requirements. IMG.LY is committed to maintaining compliance with **GDPR** and other applicable data protection laws, ensuring your privacy is respected at all times. For details consult our [privacy policy](https://img.ly/privacy-policy). --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Serve Assets From Your Server" description: "Set up and manage how assets are served to the editor, including local, remote, or CDN-based delivery." platform: android url: "https://img.ly/docs/cesdk/android/serve-assets-b0827c/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Serve Assets](https://img.ly/docs/cesdk/android/serve-assets-b0827c/) --- In this example, we explain how to configure the Creative Engine to use assets hosted on your own servers. While we serve all assets from our own CDN by default, it is highly recommended to serve the assets from your own servers in a production environment. ## 1. Register IMG.LY's default assets If you want to use our default asset sources in your integration, call `fun Engine.addDefaultAssetSources(baseUri: Uri, exclude: Set)`. Right after initialization: ```kotlin val engine = Engine("ly.img.engine.example") engine.start() engine.addDefaultAssetSources() ``` This call adds IMG.LY's default asset sources for stickers, vectorpaths and filters to your engine instance. By default, these include the following sources represented by `DefaultAssetSource` enum\`: - `DefaultAssetSource.STICKER` - `ly.img.sticker` - Various stickers. - `DefaultAssetSource.VECTOR_PATH` - `ly.img.vectorpath` - Shapes and arrows. - `DefaultAssetSource.FILTER_LUT` - `ly.img.filter.lut` - LUT effects of various kinds. - `DefaultAssetSource.FILTER_DUO_TONE` - `ly.img.filter.duotone` - Color effects of various kinds. - `DefaultAssetSource.COLORS_DEFAULT_PALETTE` - `ly.img.colors.defaultPalette` - Default color palette. - `DefaultAssetSource.EFFECT` - `ly.img.effect` - Default effects. - `DefaultAssetSource.BLUR` - `ly.img.blur` - Default blurs. - `DefaultAssetSource.TYPEFACE` - `ly.img.typeface` - Default typefaces. If you don't specify a `baseUri` option, the assets are parsed and served from the IMG.LY CDN. It is highly recommended to serve the assets from your own servers in a production environment, if you decide to use them. To do so, follow the steps below and pass a `baseUri` option to `addDefaultAssetSources`. If you only need a subset of the IDs above, use the `exclude` option to pass a list of ignored `DefaultAssetSource` objects\`. ## 2. Copy Assets Download the IMG.LY default assets from [our CDN](https://cdn.img.ly/packages/imgly/cesdk-android/$UBQ_VERSION$/imgly-assets.zip). Copy the extracted folders to your own CDN server or to the android assets folder if you want to use them offline. It can be on the root or any subfolder. ## 3. Configure the IMGLYEngine to use your self-hosted assets Next, we need to configure the SDK to use the copied assets instead of the ones served via IMG.LY CDN. `Engine.addDefaultAssetSources` offers a `baseUri` option, that needs to be set to an absolute Uri, pointing to your newly added assets. In case you have copied to your own cdn path: ```kotlin val baseUri = Uri.parse("https://cdn.your.custom.domain/assets") engine.addDefaultAssetSources(baseUri) ``` In case you have copied to android assets folder: ```kotlin val baseUri = Uri.parse("file:///android_asset/assets") engine.addDefaultAssetSources(baseUri) ``` ## 4. Configure Engine-Level Assets The engine uses additional assets for font fallback (Unicode character coverage) and emoji rendering. By default, these are loaded from `https://cdn.img.ly/assets/v4`. When you configure the `basePath` setting, font fallback files and the emoji font are automatically loaded from that location: ```kotlin engine.editor.setSettingString("basePath", "https://cdn.your.custom.domain/cesdk-assets") ``` This setting affects: - **Font fallback files** — Used when text contains characters not covered by the selected font. Located at `{basePath}/fonts/font-{index}.ttf`. - **Emoji font** — The default emoji font (NotoColorEmoji.ttf). Located at `{basePath}/emoji/NotoColorEmoji.ttf`. To self-host these assets: 1. The `fonts/` and `emoji/` directories are already included in the `imgly-assets.zip` download 2. After extracting, set `basePath` to point to your extraction location For android assets folder: ```kotlin engine.editor.setSettingString("basePath", "file:///android_asset/cesdk-assets") ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Settings" description: "Explore all configurable editor settings and learn how to read, update, and observe them via the Settings API." platform: android url: "https://img.ly/docs/cesdk/android/settings-970c98/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Settings](https://img.ly/docs/cesdk/android/settings-970c98/) --- All keys listed below can be modified through the Editor API. The nested settings inside `UBQSettings` can be reached via key paths, e.g. `page/title/show`. ## Settings ### `BlockAnimationSettings` | Member | Type | Default | Description | | ------- | ------ | ------- | -------------------------------------------- | | enabled | `bool` | `true` | Whether animations should be enabled or not. | ### `CameraClampingSettings` | Member | Type | Default | Description | | ------------- | ----------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | overshootMode | `CameraClampingOvershootMode` | `Reverse` | Controls what happens when the clamp area is smaller than the viewport. Center: the clamp area is centered in the viewport. Reverse: the clamp area can move inside the viewport until it hits the edges. | ### `CameraSettings` | Member | Type | Default | Description | | -------- | ------------------------------------------------------------------- | ------- | --------------------------------- | | clamping | `CameraClampingSettings: CameraClampingOvershootMode overshootMode` | `{}` | Clamping settings for the camera. | ### `ControlGizmoSettings` | Member | Type | Default | Description | | -------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | blockScaleDownLimit | `float` | `8.0` | Scale-down limit for blocks in screen pixels when scaling them with the gizmos or with touch gestures. The limit is ensured to be at least 0.1 to prevent scaling to size zero. | | showCropHandles | `bool` | `{true}` | Whether or not to show the handles to adjust the crop area during crop mode. | | showCropScaleHandles | `bool` | `{true}` | Whether or not to display the outer handles that scale the full image during crop. | | showMoveHandles | `bool` | `{true}` | Whether or not to show the move handles. | | showResizeHandles | `bool` | `{true}` | Whether or not to display the non-proportional resize handles (edge handles) | | showRotateHandles | `bool` | `{true}` | Whether or not to show the rotation handles. | | showScaleHandles | `bool` | `{true}` | Whether or not to display the proportional scale handles (corner handles) | ### `DebugFlags` Flags that control debug outputs. | Member | Type | Default | Description | | -------------------------- | ------ | --------- | ------------------------------------------------------------------------------------------------------------- | | enforceScopesInAPIs | `bool` | `false` | Whether APIs calls that perform edits should throw errors if the corresponding scope does not allow the edit. | | showHandlesInteractionArea | `bool` | `{false}` | Display the interaction area around the handles. | | useDebugMipmaps | `bool` | `false` | Enable the use of colored mipmaps to see which mipmap is used. | ### `MouseSettings` | Member | Type | Default | Description | | ------------ | ------ | ------- | ------------------------------------------------- | | enableScroll | `bool` | `true` | Whether the engine processes mouse scroll events. | | enableZoom | `bool` | `true` | Whether the engine processes mouse zoom events. | ### `PageSettings` | Member | Type | Default | Description | | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | allowCropInteraction | `bool` | `true` | If crop interaction (by handles and gestures) should be possible when the enabled arrangements allow resizing. | | allowMoveInteraction | `bool` | `false` | If move interaction (by handles and gestures) should be possible when the enabled arrangements allow moving and if the page layout is not controlled by the scene, e.g., in a 'VerticalStack'. | | allowResizeInteraction | `bool` | `false` | If a resize interaction (by handles and gestures) should be possible when the enabled arrangements allow resizing. | | allowRotateInteraction | `bool` | `false` | If rotation interaction (by handles and gestures) should be possible when the enabled arrangements allow rotation and if the page layout is not controlled by the scene, e.g., in a 'VerticalStack'. | | dimOutOfPageAreas | `bool` | `true` | Whether the opacity of the region outside of all pages should be reduced. | | innerBorderColor | `Color` | `createRGBColor(0.0, 0.0, 0.0, 0.0)` | Color of the inner frame around the page. | | marginFillColor | `Color` | `createRGBColor(0.79, 0.12, 0.40, 0.1)` | Color of frame around the bleed margin area of the pages. | | marginFrameColor | `Color` | `createRGBColor(0.79, 0.12, 0.40, 0.0)` | Color filled into the bleed margins of pages. | | moveChildrenWhenCroppingFill | `bool` | `false` | Whether the children of the page should be transformed to match their old position relative to the page fill when a page fill is cropped. | | outerBorderColor | `Color` | `createRGBColor(1.0, 1.0, 1.0, 0.0)` | Color of the outer frame around the page. | | restrictResizeInteractionToFixedAspectRatio | `bool` | `false` | If the resize interaction should be restricted to fixed aspect ratio resizing. | | title | `PageTitleSettings(bool show, bool showOnSinglePage, bool showPageTitleTemplate, bool appendPageName, string separator, Color color, string fontFileUri)` | \`\` | Page title settings. | ### `PageTitleSettings` | Member | Type | Default | Description | | --------------------- | -------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | appendPageName | `bool` | `true` | Whether to append the page name to the title if a page name is set even if the name is not specified in the template or the template is not shown | | color | `Color` | `createRGBColor(1., 1., 1.)` | Color of page titles visible in preview mode, can change with different themes. | | fontFileUri | `string` | `DEFAULT_FONT` | Font of page titles. | | separator | `string` | `"-"` | Title label separator between the page number and the page name. | | show | `bool` | `true` | Whether to show titles above each page. | | showOnSinglePage | `bool` | `true` | Whether to hide the the page title when only a single page is given. | | showPageTitleTemplate | `bool` | `true` | Whether to include the default page title from `page.titleTemplate` | ### `PlaceholderControlsSettings` | Member | Type | Default | Description | | ----------- | ------ | ------- | ---------------------------- | | showButton | `bool` | `true` | Show the placeholder button. | | showOverlay | `bool` | `true` | Show the overlay pattern. | ### `Settings` | Member | Type | Default | Description | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | alwaysHighlightPlaceholders | `bool` | `false` | Whether placeholder elements should always be highlighted in the scene. | | basePath | `string` | `""` | The root directory to be used when resolving relative paths or when accessing `bundle://` URIs on platforms that don't offer bundles. | | blockAnimations | `BlockAnimationSettings: bool enabled` | `{}` | Settings that configure the behavior of block animations. | | borderOutlineColor | `Color` | `createRGBColor(0., 0., 0., 1.0)` | The border outline color, defaults to black. | | camera | `CameraSettings: CameraClampingSettings clamping` | `{}` | Settings that configure the behavior of the camera. | | clearColor | `Color` | `createClear()` | The color with which the render target is cleared before scenes get rendered. Only used while renderMode == Preview, else #00000000 (full transparency) is used. | | colorMaskingSettings | `ColorMaskingSettings(Color maskColor, bool secondPass)` | `{}` | A collection of settings used to perform color masking. | | controlGizmo | `ControlGizmoSettings(bool showCropHandles, bool showCropScaleHandles, bool showMoveHandles, bool showResizeHandles, bool showScaleHandles, bool showRotateHandles, float blockScaleDownLimit)` | `{}` | Settings that configure which touch/click targets for move/scale/rotate/etc. are enabled and displayed. | | cropOverlayColor | `Color` | `createRGBColor(0., 0., 0., 0.39)` | Color of the dimming overlay that's added in crop mode. | | debug | `DebugFlags(bool useDebugMipmaps, bool showHandlesInteractionArea, bool enforceScopesInAPIs)` | `{}` | ? | | defaultEmojiFontFileUri | `string` | `EMOJI_FONT` | URI of default font file for emojis. | | defaultFontFileUri | `string` | `DEFAULT_FONT` | URI of default font file This font file is the default everywhere unless overriden in specific settings. | | doubleClickSelectionMode | `DoubleClickSelectionMode` | `Hierarchical` | The current mode of selection on double-click. | | doubleClickToCropEnabled | `bool` | `true` | Whether double clicking on an image element should switch into the crop editing mode. | | emscriptenCORSConfigurations | `vector< CORSConfiguration >` | `{}` | CORS Configurations: `` pairs. See `FetchAsyncService-emscripten.cpp` for details. | | errorStateColor | `Color` | `createRGBColor(1., 1., 1., 0.7)` | The error state color for design blocks. | | fallbackFontUri | `string` | `""` | The URI of the fallback font to use for text that is missing certain characters. | | forceSystemEmojis | `bool` | `true` | Whether the system emojis should be used for text. | | globalScopes | `GlobalScopes(Text text, Fill fill, Stroke stroke, Shape shape, Layer layer, Appearance appearance, Lifecycle lifecycle, Editor editor)` | `Allow)` | Global scopes. | | handleFillColor | `Color` | `createWhite()` | The fill color for handles. | | highlightColor | `Color` | `createRGBColor(0.2, 85. / 255., 1.)` | Color of the selection, hover, and group frames and for the handle outlines for non-placeholder elements. | | license | `string` | `""` | A valid license string in JWT format, use an empty string or `null` to run in evaluation mode with watermark. | | maxImageSize | `int` | `4096` | The maximum size at which images are loaded into the engine. Images that exceed this size are down-scaled prior to rendering. Reducing this size further reduces the memory footprint. Defaults to 4096x4096. | | mouse | `MouseSettings(bool enableZoom, bool enableScroll)` | `{}` | Settings that configure the behavior of the mouse. | | page | `PageSettings(PageTitleSettings title, Color marginFillColor, Color marginFrameColor, Color innerBorderColor, Color outerBorderColor, bool dimOutOfPageAreas, bool allowCropInteraction, bool allowResizeInteraction, bool restrictResizeInteractionToFixedAspectRatio, bool allowRotateInteraction, bool allowMoveInteraction, bool moveChildrenWhenCroppingFill)` | `{}` | Page related settings. | | pageHighlightColor | `Color` | `createRGBColor(0.5, 0.5, 0.5, 0.2)` | Color of the outline of each page. | | placeholderControls | `PlaceholderControlsSettings(bool showOverlay, bool showButton)` | `{}` | Supersedes how the blocks' placeholder controls are applied. | | placeholderHighlightColor | `Color` | `createRGBColor(0.77, 0.06, 0.95)` | Color of the selection, hover, and group frames and for the handle outlines for placeholder elements. | | positionSnappingThreshold | `float` | `4.` | Position snapping threshold in screen space. | | progressColor | `Color` | `createRGBColor(1., 1., 1., 0.7)` | The progress indicator color. | | renderTextCursorAndSelectionInEngine | `bool` | `true` | Whether the engine should render the text cursor and selection highlights during text editing. This can be set to false, if the platform wants to perform this rendering itself. | | rotationSnappingGuideColor | `Color` | `createRGBColor(1., 0.004, 0.361)` | Color of the rotation snapping guides. | | rotationSnappingThreshold | `float` | `0.15` | Rotation snapping threshold in radians. | | ruleOfThirdsLineColor | `Color` | `createRGBColor(0.75, 0.75, 0.75, 0.75)` | Color of the rule-of-thirds lines. | | showBuildVersion | `bool` | `false` | Show the build version on the canvas. | | snappingGuideColor | `Color` | `createRGBColor(1., 0.004, 0.361)` | Color of the position snapping guides. | | textVariableHighlightColor | `Color` | `createRGBColor(0.7, 0., 0.7)` | Color of the text variable highlighting borders. | | touch | `TouchSettings(bool dragStartCanSelect, bool singlePointPanning, PinchGestureAction pinchAction, RotateGestureAction rotateAction)` | `{}` | Settings that configure which touch gestures are enabled and which actions they trigger. | | useSystemFontFallback | `bool` | `false` | Whether the IMG.LY hosted font fallback is used for fonts that are missing certain characters, covering most of the unicode range. | ### `TouchSettings` | Member | Type | Default | Description | | ------------------ | --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | dragStartCanSelect | `bool` | `true` | Whether dragging an element requires selecting it first. When not set, elements can be directly dragged. | | pinchAction | `PinchGestureAction` | `Scale` | The action to perform when a pinch gesture is performed. | | rotateAction | `RotateGestureAction` | `Rotate` | Whether or not the two finger turn gesture can rotate selected elements. | | singlePointPanning | `bool` | `true` | Whether or not dragging on the canvas should move the camera (scrolling). When not set, the scroll bars have to be used. This setting might get overwritten with the feature flag `preventScrolling`. | ```kotlin reference-only engine.editor.findAllSettings() engine.editor.getSettingType("doubleClickSelectionMode") engine.editor.onSettingsChanged() .onEach { println("Editor settings have changed") } .launchIn(CoroutineScope(Dispatchers.Main)) engine.editor.onRoleChanged() .onEach { role -> println("Role changed to $role") } .launchIn(CoroutineScope(Dispatchers.Main)) engine.editor.setSettingBoolean("doubleClickToCropEnabled", value = true) engine.editor.getSettingBoolean("doubleClickToCropEnabled") try engine.editor.setSettingInt("integerSetting", value: 0) try engine.editor.getSettingInt("integerSetting") engine.editor.setSettingFloat("positionSnappingThreshold", value = 2.0F) engine.editor.getSettingFloat("positionSnappingThreshold") engine.editor.setSettingString("license", value = "invalid") engine.editor.getSettingString("license") engine.editor.setSettingColor("highlightColor", Color.fromRGBA(r = 1F, g = 0F, b = 1F, a = 1F)) // Pink engine.editor.getSettingColor("highlightColor") engine.editor.setSettingEnum("doubleClickSelectionMode", value = "Direct") engine.editor.getSettingEnum("doubleClickSelectionMode") engine.editor.getSettingEnumOptions("doubleClickSelectionMode") engine.editor.getRole() engine.editor.setRole("Adopter") ``` ## Change Settings In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to control with the `editor` API. A list of all available settings can be found above. ### Exploration ```kotlin fun findAllSettings(): List ``` Returns a list of all the settings available. - Returns the list of all settings. ```kotlin fun getSettingType(keypath: String): PropertyType ``` Get the type of a setting. - `keypath`: the settings enum keypath, e.g. `doubleClickSelectionMode`. - Returns the type of the setting. ### Functions ```kotlin fun onSettingsChanged(): Flow ``` Subscribe to changes to the editor settings. - Returns flow of editor settings change events. ```kotlin fun onRoleChanged(): Flow ``` Subscribe to changes to the editor role. - Returns flow of role change events. ```kotlin fun setSettingBoolean( keypath: String, value: Boolean, ) ``` Set a boolean setting. - `keypath`: the settings keypath, e.g. `doubleClickToCropEnabled`. - `value`: the value to set. ```kotlin fun getSettingBoolean(keypath: String): Boolean ``` Get a boolean setting. - `keypath`: the settings keypath, e.g. `doubleClickToCropEnabled`. - Returns the current value. ```kotlin fun setSettingInt( keypath: String, value: Int, ) ``` Set an integer setting. - `keypath`: the settings keypath. - `value`: the value to set. ```kotlin fun getSettingInt(keypath: String): Int ``` Get an integer setting. - `keypath`: the settings keypath. - Returns the current value. ```kotlin fun setSettingFloat( keypath: String, value: Float, ) ``` Set a float setting. - `keypath`: the settings keypath, e.g. `positionSnappingThreshold`. - `value`: the value to set. ```kotlin fun getSettingFloat(keypath: String): Float ``` Get a float setting. - `keypath`: the settings keypath, e.g. `positionSnappingThreshold`. - Returns the current value. ```kotlin fun setSettingString( keypath: String, value: String, ) ``` Set a string setting. - `keypath`: the settings keypath, e.g. `license`. - `value`: the value to set. ```kotlin fun getSettingString(keypath: String): String ``` Get a string setting. - `keypath`: the settings keypath, e.g. `license`. - Returns the current value. ```kotlin fun setSettingColor( keypath: String, value: RGBAColor, ) ``` Set a color setting. - `keypath`: the settings keypath, e.g. `highlightColor`. - `value`: the value to set. ```kotlin fun getSettingColor(keypath: String): RGBAColor ``` Get a color setting. - `keypath`: the settings keypath, e.g. `highlightColor`. - Returns the current value. ```kotlin fun setSettingEnum( keypath: String, value: String, ) ``` Set an enum setting. - `keypath`: the settings keypath, e.g. `doubleClickSelectionMode`. - `value`: the value to set. ```kotlin fun getSettingEnum(keypath: String): String ``` Get an enum setting. - `keypath`: the settings keypath, e.g. `doubleClickSelectionMode`. - Returns the current value. ```kotlin fun getSettingEnumOptions(keypath: String): List ``` Get all the available options of an enum setting. - `keypath`: the settings enum keypath, e.g. `doubleClickSelectionMode`. - Returns the list of enum options. ```kotlin fun getRole(): String ``` Get the current role of the user ```kotlin fun setRole(role: String) ``` Set the role of the user and apply role-dependent defaults for scopes and settings ## Full Code Here's the full code: ```kotlin engine.editor.findAllSettings() engine.editor.getSettingType("doubleClickSelectionMode") engine.editor.onSettingsChanged() .onEach { println("Editor settings have changed") } .launchIn(CoroutineScope(Dispatchers.Main)) engine.editor.onRoleChanged() .onEach { role -> println("Role changed to $role") } .launchIn(CoroutineScope(Dispatchers.Main)) engine.editor.setSettingBoolean("doubleClickToCropEnabled", value = true) engine.editor.getSettingBoolean("doubleClickToCropEnabled") try engine.editor.setSettingInt("integerSetting", value: 0) try engine.editor.getSettingInt("integerSetting") engine.editor.setSettingFloat("positionSnappingThreshold", value = 2.0F) engine.editor.getSettingFloat("positionSnappingThreshold") engine.editor.setSettingString("license", value = "invalid") engine.editor.getSettingString("license") engine.editor.setSettingColor("highlightColor", Color.fromRGBA(r = 1F, g = 0F, b = 1F, a = 1F)) // Pink engine.editor.getSettingColor("highlightColor") engine.editor.setSettingEnum("doubleClickSelectionMode", value = "Direct") engine.editor.getSettingEnum("doubleClickSelectionMode") engine.editor.getSettingEnumOptions("doubleClickSelectionMode") engine.editor.getRole() engine.editor.setRole("Adopter") ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Create and Edit Shapes" description: "Draw custom vector shapes, combine them with boolean operations, and insert QR codes into your designs." platform: android url: "https://img.ly/docs/cesdk/android/shapes-9f1b2c/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Shapes](https://img.ly/docs/cesdk/android/shapes-9f1b2c/) --- --- ## Related Pages - [Create Shapes](https://img.ly/docs/cesdk/android/stickers-and-shapes/create-edit/create-shapes-64acc0/) - Draw custom vector shapes and insert them into your design canvas. - [Edit Shapes](https://img.ly/docs/cesdk/android/stickers-and-shapes/create-edit/edit-shapes-d67cfb/) - Modify shape properties like size, color, position, and border radius. - [Combine](https://img.ly/docs/cesdk/android/stickers-and-shapes/combine-2a9e26/) - Group and merge multiple stickers or shapes into a single element for easier manipulation. - [Insert QR Code in Android (Kotlin)](https://img.ly/docs/cesdk/android/stickers-and-shapes/insert-qr-code-b6cc53/) - Generate a QR code with ZXing and insert it into a scene as an image fill, with positioning, sizing, and optional metadata for later updates. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Design Editor (Advanced)" description: "Add a comprehensive design editor to your web app in minutes. Professional tools for graphics, templates, and multi-page documents—all client-side." platform: android url: "https://img.ly/docs/cesdk/android/starterkits/advanced-editor-87riel/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). --- --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Video Editor (Advanced)" description: "Add a comprehensive video editor to your web app in minutes. Professional tools for timeline editing, effects, and MP4 export—all client-side." platform: android url: "https://img.ly/docs/cesdk/android/starterkits/advanced-video-editor-2a68z2/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). --- --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Video Player" description: "Add video playback to your web app in minutes. Play, pause, and navigate video content—all client-side." platform: android url: "https://img.ly/docs/cesdk/android/starterkits/player-6sjm1w/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). --- --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Design Viewer" description: "Add design viewing to your web app in minutes. Pan, zoom, and navigate multi-page designs—all client-side." platform: android url: "https://img.ly/docs/cesdk/android/starterkits/viewer-zgs556/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). --- --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Create and Edit Stickers" description: "Create and customize stickers using image fills for icons, logos, emoji, and multi-color graphics." platform: android url: "https://img.ly/docs/cesdk/android/stickers-3d4e5f/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Stickers](https://img.ly/docs/cesdk/android/stickers-3d4e5f/) --- --- ## Related Pages - [Create Cutout](https://img.ly/docs/cesdk/android/stickers-and-shapes/create-cutout-384be3/) - Create cutouts from images or shapes by masking or removing specific areas. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Combine" description: "Group and merge multiple stickers or shapes into a single element for easier manipulation." platform: android url: "https://img.ly/docs/cesdk/android/stickers-and-shapes/combine-2a9e26/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Shapes](https://img.ly/docs/cesdk/android/shapes-9f1b2c/) > [Combine](https://img.ly/docs/cesdk/android/stickers-and-shapes/combine-2a9e26/) --- ```kotlin file=@cesdk_android_examples/engine-guides-bool-ops/BoolOps.kt reference-only import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.BooleanOperation import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun usingBoolOps( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) val circle1 = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(circle1, shape = engine.block.createShape(ShapeType.Ellipse)) engine.block.setFill(circle1, fill = engine.block.createFill(FillType.Color)) engine.block.setPositionX(circle1, value = 30F) engine.block.setPositionY(circle1, value = 30F) engine.block.setWidth(circle1, value = 40F) engine.block.setHeight(circle1, value = 40F) engine.block.appendChild(parent = page, child = circle1) val circle2 = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(circle2, shape = engine.block.createShape(ShapeType.Ellipse)) engine.block.setFill(circle2, fill = engine.block.createFill(FillType.Color)) engine.block.setPositionX(circle2, value = 80F) engine.block.setPositionY(circle2, value = 30F) engine.block.setWidth(circle2, value = 40F) engine.block.setHeight(circle2, value = 40F) engine.block.appendChild(parent = page, child = circle2) val circle3 = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(circle3, shape = engine.block.createShape(ShapeType.Ellipse)) engine.block.setFill(circle3, fill = engine.block.createFill(FillType.Color)) engine.block.setPositionX(circle3, value = 50F) engine.block.setPositionY(circle3, value = 50F) engine.block.setWidth(circle3, value = 50F) engine.block.setHeight(circle3, value = 50F) engine.block.appendChild(parent = page, child = circle3) engine.block.combine(listOf(circle1, circle2, circle3), op = BooleanOperation.UNION) val text = engine.block.create(DesignBlockType.Text) engine.block.replaceText(text, "Removed text") engine.block.setPositionX(text, value = 10F) engine.block.setPositionY(text, value = 40F) engine.block.setWidth(text, value = 80F) engine.block.setHeight(text, value = 10F) engine.block.appendChild(parent = page, child = text) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) val imageFill = engine.block.createFill(FillType.Image) engine.block.setFill(block = block, fill = imageFill) engine.block.setPositionX(block, value = 0F) engine.block.setPositionY(block, value = 0F) engine.block.setWidth(block, value = 100F) engine.block.setHeight(block, value = 100F) engine.block.setString( block = imageFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg", ) engine.block.appendChild(parent = page, child = block) engine.block.sendToBack(block) engine.block.forceLoadResources(listOf(block)) val difference = engine.block.combine(listOf(block, text), op = BooleanOperation.DIFFERENCE) engine.stop() } ``` You can use four different boolean operations on blocks to combine them into unique shapes. These operations are: - `'Union'`: adds all the blocks' shapes into one - `'Difference'`: removes from the bottom-most block the shapes of the other blocks overlapping with it - `'Intersection'`: keeps only the overlapping parts of all the blocks' shapes - `'XOR'`: removes the overlapping parts of all the block's shapes Combining blocks allows you to create a new block with a customized shape. Combining blocks with the `union`, `intersection` or `XOR` operation will result in the new block whose fill is that of the top-most block and whose shape is the result of applying the operation pair-wise on blocks from the top-most block to the bottom-most block. Combining blocks with the `difference` operation will result in the new block whose fill is that of the bottom-most block and whose shape is the result of applying the operation pair-wise on blocks from the bottom-most block to the top-most block. The combined blocks will be destroyed. > **Note:** **Only the following blocks can be combined*** A graphics block > * A text block ```kotlin fun isCombinable(blocks: List): Boolean ``` Checks whether blocks could be combined. Only graphics blocks and text blocks can be combined. All blocks must have the "lifecycle/duplicate" scope enabled. - `blocks`: blocks for which the confirm combinability. - Returns whether the blocks can be combined or an error. ```kotlin fun combine( blocks: List, op: BooleanOperation, ): DesignBlock ``` Perform a boolean operation on the given blocks. All blocks must be combinable. See `isCombinable`. The parent, fill and sort order of the new block is that of the prioritized block. When performing a `Union`, `Intersection` or `XOR`, the operation is performed pair-wise starting with the element with the highest sort order. When performing a `Difference`, the operation is performed pair-wise starting with the element with the lowest sort order. Required scopes: "lifecycle/duplicate", "lifecycle/destroy" - `blocks`: blocks to combine. They will be destroyed if "lifecycle/destroy" scope is enabled. - `op`: boolean operation to perform. - Returns the newly created block or an error. Here's the full code: ```kotlin // Create blocks and append to scene val star = engine.block.create(DesignBlockType.STAR_SHAPE) val rect = engine.block.create(DesignBlockType.RECT_SHAPE) engine.block.appendChild(scene, child = star) engine.block.appendChild(scene, child = rect) // Check whether the blocks may be combined if (engine.block.isCombinable(listOf(star, rect))) { val combined = engine.block.combine(listOf(star, rect), op = BooleanOperation.UNION) } ``` ## Combining three circles together We create three circles and arrange in a recognizable pattern. Combing them with `'Union'` result in a single block with a unique shape. The result will inherit the top-most block's fill, in this case `circle3`'s fill. ```kotlin highlight-combine-union val circle1 = engine.block.create(DesignBlockType.Graphic) ``` To create a special effect of text punched out from an image, we create an image and a text. We ensure that the image is at the bottom as that is the base block from which we want to remove shapes. The result will be a block with the size, shape and fill of the image but with a hole in it in the shape of the removed text. ```kotlin highlight-combine-difference val text = engine.block.create(DesignBlockType.Text) engine.block.replaceText(text, "Removed text") engine.block.setPositionX(text, value = 10F) engine.block.setPositionY(text, value = 40F) engine.block.setWidth(text, value = 80F) engine.block.setHeight(text, value = 10F) engine.block.appendChild(parent = page, child = text) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) val imageFill = engine.block.createFill(FillType.Image) engine.block.setFill(block = block, fill = imageFill) engine.block.setPositionX(block, value = 0F) engine.block.setPositionY(block, value = 0F) engine.block.setWidth(block, value = 100F) engine.block.setHeight(block, value = 100F) engine.block.setString( block = imageFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg", ) engine.block.appendChild(parent = page, child = block) engine.block.sendToBack(block) engine.block.forceLoadResources(listOf(block)) val difference = engine.block.combine(listOf(block, text), op = BooleanOperation.DIFFERENCE) ``` ### Full Code Here's the full code: ```kotlin import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.BooleanOperation import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun usingBoolOps( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) val circle1 = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(circle1, shape = engine.block.createShape(ShapeType.Ellipse)) engine.block.setFill(circle1, fill = engine.block.createFill(FillType.Color)) engine.block.setPositionX(circle1, value = 30F) engine.block.setPositionY(circle1, value = 30F) engine.block.setWidth(circle1, value = 40F) engine.block.setHeight(circle1, value = 40F) engine.block.appendChild(parent = page, child = circle1) val circle2 = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(circle2, shape = engine.block.createShape(ShapeType.Ellipse)) engine.block.setFill(circle2, fill = engine.block.createFill(FillType.Color)) engine.block.setPositionX(circle2, value = 80F) engine.block.setPositionY(circle2, value = 30F) engine.block.setWidth(circle2, value = 40F) engine.block.setHeight(circle2, value = 40F) engine.block.appendChild(parent = page, child = circle2) val circle3 = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(circle3, shape = engine.block.createShape(ShapeType.Ellipse)) engine.block.setFill(circle3, fill = engine.block.createFill(FillType.Color)) engine.block.setPositionX(circle3, value = 50F) engine.block.setPositionY(circle3, value = 50F) engine.block.setWidth(circle3, value = 50F) engine.block.setHeight(circle3, value = 50F) engine.block.appendChild(parent = page, child = circle3) engine.block.combine(listOf(circle1, circle2, circle3), op = BooleanOperation.UNION) val text = engine.block.create(DesignBlockType.Text) engine.block.replaceText(text, "Removed text") engine.block.setPositionX(text, value = 10F) engine.block.setPositionY(text, value = 40F) engine.block.setWidth(text, value = 80F) engine.block.setHeight(text, value = 10F) engine.block.appendChild(parent = page, child = text) val block = engine.block.create(DesignBlockType.Graphic) engine.block.setShape(block, shape = engine.block.createShape(ShapeType.Rect)) val imageFill = engine.block.createFill(FillType.Image) engine.block.setFill(block = block, fill = imageFill) engine.block.setPositionX(block, value = 0F) engine.block.setPositionY(block, value = 0F) engine.block.setWidth(block, value = 100F) engine.block.setHeight(block, value = 100F) engine.block.setString( block = imageFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg", ) engine.block.appendChild(parent = page, child = block) engine.block.sendToBack(block) engine.block.forceLoadResources(listOf(block)) val difference = engine.block.combine(listOf(block, text), op = BooleanOperation.DIFFERENCE) engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Create Cutout" description: "Create cutouts from images or shapes by masking or removing specific areas." platform: android url: "https://img.ly/docs/cesdk/android/stickers-and-shapes/create-cutout-384be3/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Stickers](https://img.ly/docs/cesdk/android/stickers-3d4e5f/) > [Create Cutout](https://img.ly/docs/cesdk/android/stickers-and-shapes/create-cutout-384be3/) --- ```kotlin file=@cesdk_android_examples/engine-guides-cutouts/Cutouts.kt reference-only import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.Color import ly.img.engine.CutoutOperation import ly.img.engine.DesignBlockType import ly.img.engine.Engine fun cutouts( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) val circle = engine.block.createCutoutFromPath( "M 0,25 a 25,25 0 1,1 50,0 a 25,25 0 1,1 -50,0 Z", ) engine.block.setFloat(circle, "cutout/offset", 3F) engine.block.setEnum(circle, "cutout/type", "Dashed") val square = engine.block.createCutoutFromPath("M 0,0 H 50 V 50 H 0 Z") engine.block.setFloat(square, "cutout/offset", 6F) val union = engine.block.createCutoutFromOperation( listOf(circle, square), op = CutoutOperation.UNION, ) engine.block.destroy(circle) engine.block.destroy(square) engine.editor.setSpotColor("CutContour", Color.fromRGBA(r = 0F, g = 0F, b = 1F, a = 1F)) engine.stop() } ``` Cutouts are a special feature one can use with cuttings printers. When printing a PDF file containing cutouts paths, a cutting printer will cut these paths with a cutter rather than print them with ink. Use cutouts to create stickers, iron on decals, etc. Cutouts can be created from an SVG string describing its underlying shape. Cutouts can also be created from combining multiple existing cutouts using the boolean operations `UNION`, `DIFFERENCE`, `INTERSECTION` and `XOR`. Cutouts have a type property which can take one of two values: `SOLID` and `DASHED`. Cutting printers recognize cutouts paths through their specially named spot colors. By default, `SOLID` cutouts have the spot color `"CutContour"` to produce a continuous cutting line and `DASHED` cutouts have the spot colors `"PerfCutContour"` to produce a perforated cutting line. You may need to adjust these spot color names for you printer. > **Note:** **Note** Note that the actual color approximation given to the spot color does > not affect how the cutting printer interprets the cutout, only how it is > rendered. The default color approximations are magenta for "CutContour" and > green for "PerfCutContour". Cutouts have an offset property that determines the distance at which the cutout path is rendered from the underlying path set when created. ## Setup the scene We first create a new scene with a new page. ```kotlin highlight-setup val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) ``` ## Create cutouts Here we add two cutouts. First, a circle of type `DASHED` and with an offset of 3.0. Second, a square of default type `SOLID` and an offset of 6.0. ```kotlin create-cutouts ``` ## Combining multiple cutouts into one Here we use the `UNION` operation to create a new cutout that consists of the combination of the earlier two cutouts we have created. Note that we destroy the previously created `circle` and `square` cutouts as we don't need them anymore and we certainly don't want to printer to cut through those paths as well. When combining multiple cutouts, the resulting cutout will be of the type of the first cutout given and an offset of 0. In this example, since the `circle` cutout is of type `DASHED`, the newly created cutout will also be of type `DASHED`. > **Note:** **Warning** When using the Difference operation, the first cutout is the > cutout that is subtracted from. For other operations, the order of > the cutouts don't matter. ```kotlin highlight-cutout-union val union = engine.block.createCutoutFromOperation( listOf(circle, square), op = CutoutOperation.UNION, ) engine.block.destroy(circle) engine.block.destroy(square) ``` ## Change the default color for Solid cutouts For some reason, we'd like the cutouts of type `SOLID` to not render as magenta but as blue. Knowing that `"CutContour"` is the spot color associated with `SOLID`, we change it RGB approximation to blue. Thought the cutout will render as blue, the printer will still interpret this path as a cutting because of its special spot color name. ```kotlin highlight-spot-color-solid engine.editor.setSpotColor("CutContour", Color.fromRGBA(r = 0F, g = 0F, b = 1F, a = 1F)) ``` ## Full Code Here's the full code: ```kotlin import kotlinx.coroutines.* import ly.img.engine.* fun cutouts( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) val circle = engine.block.createCutoutFromPath( "M 0,25 a 25,25 0 1,1 50,0 a 25,25 0 1,1 -50,0 Z", ) engine.block.setFloat(circle, "cutout/offset", 3F) engine.block.setEnum(circle, "cutout/type", CutoutType.DASHED.key) val square = engine.block.createCutoutFromPath("M 0,0 H 50 V 50 H 0 Z") engine.block.setFloat(square, "cutout/offset", 6F) val union = engine.block.createCutoutFromOperation( listOf(circle, square), op = CutoutOperation.UNION, ) engine.block.destroy(circle) engine.block.destroy(square) engine.editor.setSpotColor("CutContour", Color.fromRGBA(r = 0F, g = 0F, b = 1F, a = 1F)) engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Create Shapes" description: "Draw custom vector shapes and insert them into your design canvas." platform: android url: "https://img.ly/docs/cesdk/android/stickers-and-shapes/create-edit/create-shapes-64acc0/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Shapes](https://img.ly/docs/cesdk/android/shapes-9f1b2c/) > [Create Shapes](https://img.ly/docs/cesdk/android/stickers-and-shapes/create-edit/create-shapes-64acc0/) --- ```kotlin file=@cesdk_android_examples/engine-guides-using-shapes/UsingShapes.kt reference-only import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun usingShapes( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val scene = engine.scene.create() val graphic = engine.block.create(DesignBlockType.Graphic) val imageFill = engine.block.createFill(FillType.Image) engine.block.setString( block = imageFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg", ) engine.block.setFill(graphic, fill = imageFill) engine.block.setWidth(graphic, value = 100F) engine.block.setHeight(graphic, value = 100F) engine.block.appendChild(parent = scene, child = graphic) engine.scene.zoomToBlock( graphic, paddingLeft = 40F, paddingTop = 40F, paddingRight = 40F, paddingBottom = 40F, ) engine.block.supportsShape(graphic) // Returns true val text = engine.block.create(DesignBlockType.Text) engine.block.supportsShape(text) // Returns false val rectShape = engine.block.createShape(ShapeType.Rect) engine.block.setShape(graphic, shape = rectShape) val shape = engine.block.getShape(graphic) val shapeType = engine.block.getType(shape) val starShape = engine.block.createShape(ShapeType.Star) engine.block.destroy(engine.block.getShape(graphic)) engine.block.setShape(graphic, shape = starShape) // The following line would also destroy the currently attached starShape // engine.block.destroy(graphic) val allShapeProperties = engine.block.findAllProperties(starShape) engine.block.setInt(starShape, property = "shape/star/points", value = 6) engine.stop() } ``` The CE.SDK provides a flexible way to create and customize shapes, including rectangles, circles, lines, and polygons. ## Supported Shapes The following shapes are supported in CE.SDK: - `ShapeType.Rect` - `ShapeType.Line` - `ShapeType.Ellipse` - `ShapeType.Polygon` - `ShapeType.Star` - `ShapeType.VectorPath` ## Creating Shapes `graphic` blocks don't have any shape after you create them, which leaves them invisible by default. In order to make them visible, we need to assign both a shape and a fill to the `graphic` block. You can find more information on fills [here](https://img.ly/docs/cesdk/android/fills-402ddc/). In this example we have created and attached an image fill. In order to create a new shape, we must call the `fun createShape(type: ShapeType): DesignBlock` API. ```kotlin highlight-createShape val rectShape = engine.block.createShape(ShapeType.Rect) ``` In order to assign this shape to the `graphic` block, call the `fun setShape(block: DesignBlock, shape: DesignBlock)` API. ```kotlin highlight-setShape engine.block.setShape(graphic, shape = rectShape) ``` Just like design blocks, shapes with different types have different properties that you can set via the API. Please refer to the [API docs](https://img.ly/docs/cesdk/android/stickers-and-shapes/create-edit/edit-shapes-d67cfb/) for a complete list of all available properties for each type of shape. ## Full Code Here's the full code: ```kotlin import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun usingShapes( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val scene = engine.scene.create() val graphic = engine.block.create(DesignBlockType.Graphic) val imageFill = engine.block.createFill(FillType.Image) engine.block.setString( block = imageFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg", ) engine.block.setFill(graphic, fill = imageFill) engine.block.setWidth(graphic, value = 100F) engine.block.setHeight(graphic, value = 100F) engine.block.appendChild(parent = scene, child = graphic) engine.scene.zoomToBlock( graphic, paddingLeft = 40F, paddingTop = 40F, paddingRight = 40F, paddingBottom = 40F, ) engine.block.supportsShape(graphic) // Returns true val text = engine.block.create(DesignBlockType.Text) engine.block.supportsShape(text) // Returns false val rectShape = engine.block.createShape(ShapeType.Rect) engine.block.setShape(graphic, shape = rectShape) engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Edit Shapes" description: "Modify shape properties like size, color, position, and border radius." platform: android url: "https://img.ly/docs/cesdk/android/stickers-and-shapes/create-edit/edit-shapes-d67cfb/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Shapes](https://img.ly/docs/cesdk/android/shapes-9f1b2c/) > [Edit Shapes](https://img.ly/docs/cesdk/android/stickers-and-shapes/create-edit/edit-shapes-d67cfb/) --- ```kotlin file=@cesdk_android_examples/engine-guides-using-shapes/UsingShapes.kt reference-only import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun usingShapes( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val scene = engine.scene.create() val graphic = engine.block.create(DesignBlockType.Graphic) val imageFill = engine.block.createFill(FillType.Image) engine.block.setString( block = imageFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg", ) engine.block.setFill(graphic, fill = imageFill) engine.block.setWidth(graphic, value = 100F) engine.block.setHeight(graphic, value = 100F) engine.block.appendChild(parent = scene, child = graphic) engine.scene.zoomToBlock( graphic, paddingLeft = 40F, paddingTop = 40F, paddingRight = 40F, paddingBottom = 40F, ) engine.block.supportsShape(graphic) // Returns true val text = engine.block.create(DesignBlockType.Text) engine.block.supportsShape(text) // Returns false val rectShape = engine.block.createShape(ShapeType.Rect) engine.block.setShape(graphic, shape = rectShape) val shape = engine.block.getShape(graphic) val shapeType = engine.block.getType(shape) val starShape = engine.block.createShape(ShapeType.Star) engine.block.destroy(engine.block.getShape(graphic)) engine.block.setShape(graphic, shape = starShape) // The following line would also destroy the currently attached starShape // engine.block.destroy(graphic) val allShapeProperties = engine.block.findAllProperties(starShape) engine.block.setInt(starShape, property = "shape/star/points", value = 6) engine.stop() } ``` The `graphic` [design block](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/) in CE.SDK allows you to modify and replace its shape. CreativeEditor SDK supports many different types of shapes, such as rectangles, lines, ellipses, polygons and custom vector paths. Similarly to blocks, each shape object has a numeric id which can be used to query and [modify its properties](https://img.ly/docs/cesdk/android/concepts/blocks-90241e/). ## Accessing Shapes In order to query whether a block supports shapes, you should call the `fun supportsShape(block: DesignBlock): Boolean` API. Currently, only the `graphic` design block supports shape objects. ```kotlin highlight-supportsShape engine.block.supportsShape(graphic) // Returns true val text = engine.block.create(DesignBlockType.Text) engine.block.supportsShape(text) // Returns false ``` To query the shape of a design block, call the `fun getShape(block: DesignBlock): DesignBlock` API. You can now pass the returned result into other APIs in order to query more information about the shape, e.g. its type via the `fun getType(block: DesignBlock): String` API. ```kotlin highlight-getShape val shape = engine.block.getShape(graphic) val shapeType = engine.block.getType(shape) ``` When replacing the shape of a design block, remember to destroy the previous shape object if you don't intend to use it any further. Shape objects that are not attached to a design block will never be automatically destroyed. Destroying a design block will also destroy its attached shape block. ```kotlin highlight-replaceShape val starShape = engine.block.createShape(ShapeType.Star) engine.block.destroy(engine.block.getShape(graphic)) engine.block.setShape(graphic, shape = starShape) // The following line would also destroy the currently attached starShape // engine.block.destroy(graphic) ``` ## Shape Properties Just like design blocks, shapes with different types have different properties that you can query and modify via the API. Use `fun findAllProperties(block: DesignBlock): List` in order to get a list of all properties of a given shape. For the star shape in this example, the call would return `["name", "shape/star/innerDiameter", "shape/star/points", "type", "uuid"]`. Please refer to the [API docs](https://img.ly/docs/cesdk/android/stickers-and-shapes/create-edit/edit-shapes-d67cfb/) for a complete list of all available properties for each type of shape. ```kotlin highlight-getProperties val allShapeProperties = engine.block.findAllProperties(starShape) ``` Once we know the property keys of a shape, we can use the same APIs as for design blocks in order to modify those properties. For example, we can use `fun setInt(block: DesignBlock, property: String, value: Int)` in order to change the number of points of the star to six. ```kotlin highlight-modifyProperties engine.block.setInt(starShape, property = "shape/star/points", value = 6) ``` ## Full Code Here's the full code: ```kotlin import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType fun usingShapes( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val scene = engine.scene.create() val graphic = engine.block.create(DesignBlockType.Graphic) val imageFill = engine.block.createFill(FillType.Image) engine.block.setString( block = imageFill, property = "fill/image/imageFileURI", value = "https://img.ly/static/ubq_samples/sample_1.jpg", ) engine.block.setFill(graphic, fill = imageFill) engine.block.setWidth(graphic, value = 100F) engine.block.setHeight(graphic, value = 100F) engine.block.appendChild(parent = scene, child = graphic) engine.scene.zoomToBlock( graphic, paddingLeft = 40F, paddingTop = 40F, paddingRight = 40F, paddingBottom = 40F, ) engine.block.supportsShape(graphic) // Returns true val text = engine.block.create(DesignBlockType.Text) engine.block.supportsShape(text) // Returns false val rectShape = engine.block.createShape(ShapeType.Rect) engine.block.setShape(graphic, shape = rectShape) val shape = engine.block.getShape(graphic) val shapeType = engine.block.getType(shape) val starShape = engine.block.createShape(ShapeType.Star) engine.block.destroy(engine.block.getShape(graphic)) engine.block.setShape(graphic, shape = starShape) // The following line would also destroy the currently attached starShape // engine.block.destroy(graphic) val allShapeProperties = engine.block.findAllProperties(starShape) engine.block.setInt(starShape, property = "shape/star/points", value = 6) engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Insert QR Code in Android (Kotlin)" description: "Generate a QR code with ZXing and insert it into a scene as an image fill, with positioning, sizing, and optional metadata for later updates." platform: android url: "https://img.ly/docs/cesdk/android/stickers-and-shapes/insert-qr-code-b6cc53/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Shapes](https://img.ly/docs/cesdk/android/shapes-9f1b2c/) > [Insert QR Code](https://img.ly/docs/cesdk/android/stickers-and-shapes/insert-qr-code-b6cc53/) --- QR codes are a practical way to turn any design into a scannable gateway for: - Landing pages - App installs - Product info - Event tickets - You name it CE.SDK doesn't include a built-in QR generator, but you can create the image with **ZXing** in just a few lines and place it on the canvas as an **image fill**. This guide shows the full workflow with Kotlin examples. ## What You'll Learn - Generate a QR code image from a `String` using **ZXing**. - Add it to a CE.SDK scene as an **image fill** on a shape block. - Control **size**, **position**, and **color** for brand consistency. - Store **metadata** for quick regeneration later. ## When You'll Use It - Business cards, flyers, or packaging that need a **scannable link**. - Apps that let users personalize templates with their own URLs. - Automated workflows that embed links into generated designs. ## Setup ZXing Dependency Add the ZXing library to your `build.gradle` file: ```kotlin dependencies { implementation("com.google.zxing:core:3.5.3") } ``` ## Generate a QR Code Image Use **ZXing** to create a high-resolution QR code, then colorize it to match your brand. ```kotlin import android.graphics.Bitmap import android.graphics.Color import com.google.zxing.BarcodeFormat import com.google.zxing.EncodeHintType import com.google.zxing.qrcode.QRCodeWriter import com.google.zxing.qrcode.decoder.ErrorCorrectionLevel /** * Generate a QR code with brand colors. * @param content The content to encode. * @param size The size of the QR code in pixels. * @param errorCorrection Error correction level (L, M, Q, H). * @param foreground Color for the QR modules. * @param background Color for the QR background. */ fun generateQRCode( content: String, size: Int = 512, errorCorrection: ErrorCorrectionLevel = ErrorCorrectionLevel.M, foreground: Int = Color.BLACK, background: Int = Color.WHITE ): Bitmap { val hints = hashMapOf( EncodeHintType.ERROR_CORRECTION to errorCorrection, EncodeHintType.MARGIN to 1 ) val writer = QRCodeWriter() val bitMatrix = writer.encode(content, BarcodeFormat.QR_CODE, size, size, hints) val bitmap = Bitmap.createBitmap(size, size, Bitmap.Config.ARGB_8888) for (x in 0 until size) { for (y in 0 until size) { bitmap.setPixel(x, y, if (bitMatrix[x, y]) foreground else background) } } return bitmap } ``` Keep the foreground dark and the background light for reliable scanning. ## Insert the QR as an Image Fill Create a `graphic` block, assign it a `rect` shape, and fill it with your generated QR image. ```kotlin import android.content.Context import android.graphics.Bitmap import android.net.Uri import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.FillType import ly.img.engine.ShapeType import java.io.File import java.io.FileOutputStream suspend fun insertQRCode( engine: Engine, context: Context, page: Int, urlString: String, positionX: Float = 200f, positionY: Float = 200f, size: Float = 160f ): Int { // Generate QR code bitmap val qrBitmap = generateQRCode(content = urlString, size = 512) // Save to temporary file val file = File(context.cacheDir, "qr_${System.currentTimeMillis()}.png") withContext(Dispatchers.IO) { FileOutputStream(file).use { out -> qrBitmap.compress(Bitmap.CompressFormat.PNG, 100, out) } } val fileUri = Uri.fromFile(file) // Create graphic block with rect shape val graphic = engine.block.create(DesignBlockType.Graphic) val rectShape = engine.block.createShape(ShapeType.Rect) engine.block.setShape(graphic, shape = rectShape) // Create and apply image fill val imageFill = engine.block.createFill(FillType.Image) engine.block.setString(imageFill, property = "fill/image/imageFileURI", value = fileUri.toString()) engine.block.setFill(graphic, fill = imageFill) // Set size and position engine.block.setWidth(graphic, value = size) engine.block.setHeight(graphic, value = size) engine.block.setPositionX(graphic, value = positionX) engine.block.setPositionY(graphic, value = positionY) // Add to page engine.block.appendChild(parent = page, child = graphic) return graphic } ``` The preceding code creates a QR code and then saves it to the cache directory to generate a file URI the block can use. ## Add Optional Metadata Store the URL alongside the block for quick updates later. Metadata `key` values are anything you want. The `key` and the `value` must be `String` types. ```kotlin import ly.img.engine.Engine fun storeQRMetadata(engine: Engine, qrBlock: Int, urlString: String) { engine.block.setMetadata(qrBlock, key = "qr/url", value = urlString) } ``` ## Update an Existing QR Code If data changes, just regenerate the QR image and update the fill URI. ```kotlin import android.content.Context import android.graphics.Bitmap import android.net.Uri import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import ly.img.engine.Engine import java.io.File import java.io.FileOutputStream suspend fun updateQRCode( engine: Engine, context: Context, qrBlock: Int, newURL: String ) { // Generate new QR code bitmap val qrBitmap = generateQRCode(content = newURL, size = 512) // Save to temporary file val file = File(context.cacheDir, "qr_${System.currentTimeMillis()}.png") withContext(Dispatchers.IO) { FileOutputStream(file).use { out -> qrBitmap.compress(Bitmap.CompressFormat.PNG, 100, out) } } val fileUri = Uri.fromFile(file) // Update the fill URI val fill = engine.block.getFill(qrBlock) engine.block.setString(fill, property = "fill/image/imageFileURI", value = fileUri.toString()) engine.block.setMetadata(qrBlock, key = "qr/url", value = newURL) } ``` To generate many QR codes, for instance during a batch run, loop through your data and call `insertQRCode` for each. ## Troubleshooting | Symptom | Cause | Solution | |----------|--------|-----------| | QR looks blurry | Bitmap size too small | Increase the `size` parameter in `generateQRCode` (e.g., 1024). | | QR won't scan | Low contrast or invalid URL | Use dark-on-light colors and ensure URLs are properly encoded. | | QR not visible | Shape missing from block | Call `setShape` before applying the fill. | | File I/O error | Invalid cache directory | Always use `context.cacheDir` for temporary files. | ## Next Steps Now that you can generate QR codes, here are some related guides to help you learn more. - [Insert Shapes or Stickers](https://img.ly/docs/cesdk/android/insert-media/shapes-or-stickers-20ac68/) — Learn how fills and shapes interact. - [Batch Processing](https://img.ly/docs/cesdk/android/automation/batch-processing-ab2d18/) — Automate multiple QR insertions. - [Export Overview](https://img.ly/docs/cesdk/android/export-save-publish/export/overview-9ed3a8/) — Save and test your codes. - [Use Templates: Overview](https://img.ly/docs/cesdk/android/create-templates/overview-4ebe30/) — Add a placeholder for QR blocks in templates. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Text" description: "Add, style, and customize text layers in your design using CE.SDK’s flexible text editing tools." platform: android url: "https://img.ly/docs/cesdk/android/text-8a993a/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Text](https://img.ly/docs/cesdk/android/text-8a993a/) --- --- ## Related Pages - [Overview](https://img.ly/docs/cesdk/android/text/overview-0bd620/) - Add, style, and customize text layers in your design using CE.SDK’s flexible text editing tools. - [Edit Text](https://img.ly/docs/cesdk/android/text/edit-c5106b/) - Edit text content directly on the canvas or through the properties panel. - [Text Styling](https://img.ly/docs/cesdk/android/text/styling-269c48/) - Apply fonts, colors, alignment, and other styling options to customize text appearance. - [Text Designs](https://img.ly/docs/cesdk/android/text/text-designs-a1b2c3/) - Create and customize text component libraries using predefined text designs that appear in your asset library. - [Emojis](https://img.ly/docs/cesdk/android/text/emojis-510651/) - Insert and style emojis alongside text for expressive, modern typographic designs. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Edit Text" description: "Edit text content directly on the canvas or through the properties panel." platform: android url: "https://img.ly/docs/cesdk/android/text/edit-c5106b/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Text](https://img.ly/docs/cesdk/android/text-8a993a/) > [Edit Text](https://img.ly/docs/cesdk/android/text/edit-c5106b/) --- ```kotlin reference-only val text = engine.block.create(DesignBlockType.Text) engine.block.replaceText(text, "Hello World") engine.block.removeText(text, from = 0, to = 6) engine.block.setTextColor(text, Color.fromHex("#FFFF0000"), from = 1, to = 4) val colorsInRange = engine.block.getTextColors(text, from = 2, to = 5) engine.block.setTextFontWeight(text, fontWeight = FontWeight.BOLD, from = 0, to = 5) val fontWeights = engine.block.getTextFontWeights(text) val fontWeights = engine.block.setTextFontSize(text, fontSize: 14, from = 2, to = 5) val fontWeights = engine.block.getTextFontSizes(text) engine.block.setTextFontStyle(text, fontStyle = FontStyle.ITALIC, from = 0, to = 5) val fontStyles = engine.block.getTextFontStyles(text) engine.block.setTextCase(text, textCase = TextCase.TITLE_CASE) val textCases = engine.block.getTextCases() val canToggleBoldFont = engine.block.canToggleBoldFont(text) val canToggleItalicFont = engine.block.canToggleItalicFont(text) engine.block.toggleBoldFont(text) engine.block.toggleItalicFont(text) val typefaceAssetResults = engine.asset.findAssets( sourceId = "ly.img.typeface", query = FindAssetsQuery( query = "Open Sans", page = 0, perPage = 100 ) ) val typeface = typefaceAssetResults.assets[0].payload.typeface val font = typeface.fonts.first { font -> font.subFamily == "Bold" } engine.block.setFont(text, font.uri, typeface) engine.block.setTypeface(text, typeface, from = 0, to = 5) engine.block.setTypeface(text, typeface) val defaultTypeface = engine.block.getTypeface(text) val typefaces = engine.block.getTypefaces(text) val range = engine.block.getTextCursorRange() engine.block.setTextCursorRange(0..5) val lineCount = engine.block.getTextVisibleLineCount(text) val lineBoundingBox = engine.block.getTextLineBoundingBoxRect(text, 0) val fontMetrics = engine.editor.getFontMetrics(fontFileUri = font.uri.toString()) ``` In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to edit ranges within text blocks. A list of all available settings can be found above. ```kotlin fun replaceText( block: DesignBlock, text: String, from: Int = -1, to: Int = -1, ) ``` Inserts the given text into the selected range of the text block. Required scope: "text/edit" - `block`: the text block into which to insert the given text. - `text`: the text which should replace the selected range in the block. - `from`: the start index of the range that should be replaced. If the value is negative, this will fall back to the start of the entire text range. - `to`: the index after the last character that should be replaced by the inserted text. If the value is negative, this will fall back to the end of the entire text range. ```kotlin fun removeText( block: DesignBlock, from: Int = -1, to: Int = -1, ) ``` Removes selected range of text of the given text block. Required scope: "text/edit" - `block`: the text block from which the selected text should be removed. - `from`: the start index of the range that should be removed. If the value is negative, this will fall back to the start of the entire text range. - `to`: the index after the last character that should be removed. If the value is negative, this will fall back to the end of the entire text range. ```kotlin fun setTextColor( block: DesignBlock, color: Color, from: Int = -1, to: Int = -1, ) ``` Changes the color of the text in the selected range to the given color. Required scope: "fill/change" - `block`: the text block whose color should be changed. - `color`: the new color of the selected text range. - `from`: the start index of the range whose color should be changed. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range. - `to`: the index after the last character whose color should be changed. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range. ```kotlin fun getTextColors( block: DesignBlock, from: Int = -1, to: Int = -1, ): List ``` Returns the ordered unique list of colors of the text in the selected range. - `block`: the text block whose colors should be returned. - `from`: the start index of the range whose colors should be returned. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range. - `to`: the index after the last character of the range whose colors should be returned. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range. - Returns the ordered unique list of colors of the text in the selected range. ```kotlin fun setTextFontWeight( block: DesignBlock, fontWeight: FontWeight, from: Int = -1, to: Int = -1, ) ``` Changes the weight of the text in the selected range to the given weight. Required scope: "text/character" - `block`: the text block whose weight should be changed. - `fontWeight`: the new weight of the selected text range. - `from`: the start index of the UTF-16 range whose weight should be changed. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range. - `to`: the UTF-16 index after the last grapheme whose weight should be changed. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range. ```kotlin fun getTextFontWeights( block: DesignBlock, from: Int = -1, to: Int = -1, ): List ``` Returns the ordered unique list of font weights of the text in the selected range. - `block`: the text block whose font weights should be returned. - `from`: the start index of the range whose font weights should be returned. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range. - `to`: the index after the last character of the range whose font weights should be returned. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range. - Returns the ordered unique list of font weights of the text in the selected range. ```kotlin fun setTextFontSize( block: DesignBlock, fontSize: Float, from: Int = -1, to: Int = -1, ) ``` Changes the size of the text in the selected range to the given size. If the font size is applied to the entire text block, its font size property will be updated. Required scope: "text/character" - `block`: the text block whose size should be changed. - `fontStyle`: the new size of the selected text range. - `from`: the start index of the UTF-16 range whose size should be changed. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range. - `to`: the UTF-16 index after the last grapheme whose size should be changed. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range. ```kotlin fun getTextFontSizes( block: DesignBlock, from: Int = -1, to: Int = -1, ): List ``` Returns the ordered unique list of font sizes of the text in the selected range. - `block`: the text block whose font sizes should be returned. - `from`: the start index of the range whose font sizes should be returned. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range. - `to`: the index after the last character of the range whose font sizes should be returned. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range. - Returns the ordered unique list of font sizes of the text in the selected range. ```kotlin fun setTextFontStyle( block: DesignBlock, fontStyle: FontStyle, from: Int = -1, to: Int = -1, ) ``` Changes the style of the text in the selected range to the given style. Required scope: "text/character" - `block`: the text block whose style should be changed. - `fontStyle`: the new style of the selected text range. - `from`: the start index of the UTF-16 range whose style should be changed. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range. - `to`: the UTF-16 index after the last grapheme whose style should be changed. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range. ```kotlin fun getTextFontStyles( block: DesignBlock, from: Int = -1, to: Int = -1, ): List ``` Returns the ordered unique list of font styles of the text in the selected range. - `block`: the text block whose font styles should be returned. - `from`: the start index of the range whose font styles should be returned. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range. - `to`: the index after the last character of the range whose font styles should be returned. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range. - Returns the ordered unique list of font styles of the text in the selected range. ```kotlin fun setTextFontStyle( block: DesignBlock, fontStyle: FontStyle, from: Int = -1, to: Int = -1, ) ``` Changes the style of the text in the selected range to the given style. Required scope: "text/character" - `block`: the text block whose style should be changed. - `fontStyle`: the new style of the selected text range. - `from`: the start index of the UTF-16 range whose style should be changed. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range. - `to`: the UTF-16 index after the last grapheme whose style should be changed. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range. ```kotlin fun getTextFontStyles( block: DesignBlock, from: Int = -1, to: Int = -1, ): List ``` Returns the ordered unique list of font styles of the text in the selected range. - `block`: the text block whose font styles should be returned. - `from`: the start index of the range whose font styles should be returned. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range. - `to`: the index after the last character of the range whose font styles should be returned. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range. - Returns the ordered unique list of font styles of the text in the selected range. ```kotlin fun setTextCase( block: DesignBlock, textCase: TextCase, from: Int = -1, to: Int = -1, ) ``` Sets the given text case for the selected range of text. Required scope: "text/character" - `block`: the text block whose text case should be changed. - `textCase`: the new text case value. - `from`: the start index of the range whose text case should be changed. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range. - `to`: the index after the last character whose text case should be changed. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range. ```kotlin fun getTextCases( block: DesignBlock, from: Int = -1, to: Int = -1, ): List ``` Returns the ordered list of text cases of the text in the selected range. - `block`: the text block whose text cases should be returned. - `from`: the start index of the range whose text cases should be returned. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range. - `to`: the index after the last character of the range whose text cases should be returned. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range. - Returns the ordered list of text cases of the text in the selected range. ```kotlin fun canToggleBoldFont( block: DesignBlock, from: Int = -1, to: Int = -1, ): Boolean ``` Returns whether the font weight of the given block can be toggled between bold and normal. - `block`: the text block block whose font weight should be toggled. - `from`: the start index of the range whose whose font weight should be toggled. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range. - `to`: the index after the last character whose whose font weight should be toggled. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range. ```kotlin fun canToggleItalicFont( block: DesignBlock, from: Int = -1, to: Int = -1, ): Boolean ``` Returns whether the font style of the given block can be toggled between italic and normal. - `block`: the text block block whose font style should be toggled. - `from`: the start index of the range whose text case should be changed. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range. - `to`: the index after the last character whose text case should be changed. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range. ```kotlin fun toggleBoldFont( block: DesignBlock, from: Int = -1, to: Int = -1, ) ``` Toggles the font weight of the given block between bold and normal. Required scope: "text/character" - `block`: the text block whose font weight should be toggled. - `from`: the start index of the range whose font weight should be toggled. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range. - `to`: the index after the last character whose font weight should be toggled. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range. ```kotlin fun toggleItalicFont( block: DesignBlock, from: Int = -1, to: Int = -1, ) ``` Toggles the font style of the given block between italic and normal. Required scope: "text/character" - `block`: the text block whose font style should be toggled. - `from`: the start index of the range whose text case should be changed. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range. - `to`: the index after the last character whose text case should be changed. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range. ```kotlin fun setFont( block: DesignBlock, fontFileUri: Uri, typeface: Typeface, ) ``` Sets the given font and typeface for the text block. Existing formatting is reset. Required scope: "text/character" - `block`: the text block whose font should be changed. - `fontFileUri`: the Uri of the new font file. - `typeface`: the typeface of the new font. ```kotlin fun setTypeface( block: DesignBlock, typeface: Typeface, from: Int = -1, to: Int = -1, ) ``` Sets the given typeface for the text block. The current formatting, e.g., bold or italic, is retained as far as possible. Some formatting might change if the new typeface does not support it, e.g. thin might change to light, bold to normal, and/or italic to non-italic. If the typeface is applied to the entire text block, its typeface property will be updated. If a run does not support the new typeface, it will fall back to the default typeface from the typeface property. Required scope: "text/character" - `block`: the text block whose font should be changed. - `typeface`: the new typeface. - `from`: the start index of the range whose typeface should be set. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range. - `to`: the index after the last character of the range whose typeface should be set. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range. ```kotlin fun getTypeface(block: DesignBlock): Typeface ``` Returns the typeface property of the text block. Does not return the typefaces of the text runs. - `block`: the text block whose typeface should be returned. - Returns the typeface of the text block or throws exception if the typeface is unknown. ```kotlin fun getTypefaces( block: DesignBlock, from: Int = -1, to: Int = -1, ): List ``` Returns the typefaces of the text block. - `block`: the text block whose typefaces should be returned. - `from`: the start index of the range whose typefaces should be returned. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range. - `to`: the index after the last character of the range whose typefaces should be returned. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range. - Returns the typefaces of the text block or throws exception if the typeface is unknown. ```kotlin fun getTextCursorRange(): IntRange? ``` Returns the indices of the selected range of the text block that is currently being edited. If both the start and end index of the returned range have the same value, then the text cursor is positioned at that index. - Returns the selected grapheme range or null if no text block is currently being edited. ```kotlin fun setTextCursorRange(range: IntRange) ``` Sets the text cursor range (selection) within the text block that is currently being edited. Required scope: "text/edit" - `range`: The grapheme range to set as the selection. If start equals end, the cursor is positioned at that index. You can use -1 as a shorthand: `-1..-1` selects all text, `-1..5` selects from start to position 5, and `5..-1` selects from position 5 to the end. - Throws exception if no text block is currently being edited or if the range is invalid. ```kotlin fun getTextVisibleLineCount(block: DesignBlock): Int ``` Returns the number of visible lines in the given text block. - `block`: the text block whose line count should be returned. - Returns the number of lines of text in the block. ```kotlin fun getTextLineBoundingBoxRect( block: DesignBlock, index: Int, ): RectF ``` Returns the bounds of the visible area of the given line of the text block. The values are in the scene's global coordinate space (which has its origin at the top left). - `block`: the text block whose line bounding box should be returned. - `index`: the index of the line whose bounding box should be returned. - Returns the bounding box of the line. ```kotlin suspend fun getFontMetrics(fontFileUri: String): FontMetrics ``` Returns the font metrics for a given font file URI. If the font is not yet loaded, it will be fetched asynchronously. The returned metrics are in the font's design units coordinate space. - `fontFileUri`: the URI of the font file to get metrics from. - Returns the font metrics containing `ascender`, `descender`, `unitsPerEm`, `lineGap`, `capHeight`, `xHeight`, `underlineOffset`, `underlineSize`, `strikeoutOffset`, and `strikeoutSize` values. ## Full Code Here's the full code: ```kotlin val text = engine.block.create(DesignBlockType.Text) engine.block.replaceText(text, "Hello World") engine.block.removeText(text, from = 0, to = 6) engine.block.setTextColor(text, Color.fromHex("#FFFF0000"), from = 1, to = 4) val colorsInRange = engine.block.getTextColors(text, from = 2, to = 5) engine.block.setTextFontWeight(text, fontWeight = FontWeight.BOLD, from = 0, to = 5) val fontWeights = engine.block.getTextFontWeights(text) val fontWeights = engine.block.setTextFontSize(text, fontSize: 14, from = 2, to = 5) val fontWeights = engine.block.getTextFontSizes(text) engine.block.setTextFontStyle(text, fontStyle = FontStyle.ITALIC, from = 0, to = 5) val fontStyles = engine.block.getTextFontStyles(text) engine.block.setTextCase(text, textCase = TextCase.TITLE_CASE) val textCases = engine.block.getTextCases() val canToggleBoldFont = engine.block.canToggleBoldFont(text) val canToggleItalicFont = engine.block.canToggleItalicFont(text) engine.block.toggleBoldFont(text) engine.block.toggleItalicFont(text) val typefaceAssetResults = engine.asset.findAssets( sourceId = "ly.img.typeface", query = FindAssetsQuery( query = "Open Sans", page = 0, perPage = 100 ) ) val typeface = typefaceAssetResults.assets[0].payload.typeface val font = typeface.fonts.first { font -> font.subFamily == "Bold" } engine.block.setFont(text, font.uri, typeface) engine.block.setTypeface(text, typeface, from = 0, to = 5) engine.block.setTypeface(text, typeface) val defaultTypeface = engine.block.getTypeface(text) val typefaces = engine.block.getTypefaces(text) val range = engine.block.getTextCursorRange() engine.block.setTextCursorRange(0..5) val lineCount = engine.block.getTextVisibleLineCount(text) val lineBoundingBox = engine.block.getTextLineBoundingBoxRect(text, 0) val fontMetrics = engine.editor.getFontMetrics(fontFileUri = font.uri.toString()) ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Emojis" description: "Insert and style emojis alongside text for expressive, modern typographic designs." platform: android url: "https://img.ly/docs/cesdk/android/text/emojis-510651/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Text](https://img.ly/docs/cesdk/android/text-8a993a/) > [Emojis](https://img.ly/docs/cesdk/android/text/emojis-510651/) --- ```kotlin file=@cesdk_android_examples/engine-guides-text-with-emojis/TextWithEmojis.kt reference-only import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine fun textWithEmojis( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val uri = engine.editor.getSettingString(keypath = "ubq://defaultEmojiFontFileUri") // From a bundle engine.editor.setSettingString( keypath = "ubq://defaultEmojiFontFileUri", value = "file:///android_asset/ly.img.cesdk/fonts/NotoColorEmoji.ttf", ) // From a URL engine.editor.setSettingString( keypath = "ubq://defaultEmojiFontFileUri", value = "https://cdn.img.ly/assets/v4/emoji/NotoColorEmoji.ttf", ) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) engine.scene.zoomToBlock( page, paddingLeft = 40F, paddingTop = 40F, paddingRight = 40F, paddingBottom = 40F, ) val text = engine.block.create(DesignBlockType.Text) engine.block.setString(text, property = "text/text", value = "Text with an emoji 🧐") engine.block.setWidth(text, value = 50F) engine.block.setHeight(text, value = 10F) engine.block.appendChild(parent = page, child = text) engine.stop() } ``` Text blocks in CE.SDK support the use of emojis. A default emoji font is used to render these independently from the target platform. This guide shows how to change the default font and use emojis in text blocks. ```kotlin highlight-setup val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) engine.scene.zoomToBlock( page, paddingLeft = 40F, paddingTop = 40F, paddingRight = 40F, paddingBottom = 40F, ) ``` ## Change the Default Emoji Font The default font URI can be changed when another emoji font should be used or when the font should be served from another website, a content delivery network (CDN), or a local file path. The preset is to use the [NotoColorEmoji](https://github.com/googlefonts/noto-emoji) font loaded from our [CDN](https://cdn.img.ly/assets/v4/emoji/NotoColorEmoji.ttf). This font file supports a wide variety of Emojis and is licensed under the [Open Font License](https://cdn.img.ly/assets/v4/emoji/LICENSE.txt). The file is relatively small with 9.9 MB but has the emojis stored as PNG images. As an alternative for higher quality emojis, e.g., this [NotoColorEmoji](https://fonts.google.com/noto/specimen/Noto+Color+Emoji) font can be used. This font file supports also a wide variety of Emojis and is licensed under the [SIL Open Font License, Version 1.1](https://fonts.google.com/noto/specimen/Noto+Color+Emoji/license). The file is significantly larger with 24.3 MB but has the emojis stored as vector graphics. In order to change the emoji font URI, call the `fun setSettingString(keypath: string, value: string)` [Editor API](https://img.ly/docs/cesdk/android/settings-970c98/) with 'defaultEmojiFontFileUri' as keypath and the new URI as value. ```kotlin highlight-change-default-emoji-font val uri = engine.editor.getSettingString(keypath = "ubq://defaultEmojiFontFileUri") // From a bundle engine.editor.setSettingString( keypath = "ubq://defaultEmojiFontFileUri", value = "file:///android_asset/ly.img.cesdk/fonts/NotoColorEmoji.ttf", ) // From a URL engine.editor.setSettingString( keypath = "ubq://defaultEmojiFontFileUri", value = "https://cdn.img.ly/assets/v4/emoji/NotoColorEmoji.ttf", ) ``` ## Add a Text Block with an Emoji To add a text block with an emoji, add a text block and set the emoji as text content. ```kotlin highlight-add-text-with-emoji val text = engine.block.create(DesignBlockType.Text) engine.block.setString(text, property = "text/text", value = "Text with an emoji 🧐") engine.block.setWidth(text, value = 50F) engine.block.setHeight(text, value = 10F) engine.block.appendChild(parent = page, child = text) ``` ## Full Code Here's the full code: ```kotlin import kotlinx.coroutines.* import ly.img.engine.* fun textWithEmojis( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val uri = engine.editor.getSettingString(keypath = "ubq://defaultEmojiFontFileUri") // From a bundle engine.editor.setSettingString( keypath = "ubq://defaultEmojiFontFileUri", value = "file:///android_asset/ly.img.cesdk/fonts/NotoColorEmoji.ttf", ) // From a URL engine.editor.setSettingString( keypath = "ubq://defaultEmojiFontFileUri", value = "https://cdn.img.ly/assets/v4/emoji/NotoColorEmoji.ttf", ) val scene = engine.scene.create() val page = engine.block.create(DesignBlockType.Page) engine.block.setWidth(page, value = 800F) engine.block.setHeight(page, value = 600F) engine.block.appendChild(parent = scene, child = page) engine.scene.zoomToBlock( page, paddingLeft = 40F, paddingTop = 40F, paddingRight = 40F, paddingBottom = 40F, ) val text = engine.block.create(DesignBlockType.Text) engine.block.setString(text, property = "text/text", value = "Text with an emoji 🧐") engine.block.setWidth(text, value = 50F) engine.block.setHeight(text, value = 10F) engine.block.appendChild(parent = page, child = text) engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Overview" description: "Add, style, and customize text layers in your design using CE.SDK’s flexible text editing tools." platform: android url: "https://img.ly/docs/cesdk/android/text/overview-0bd620/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Text](https://img.ly/docs/cesdk/android/text-8a993a/) > [Overview](https://img.ly/docs/cesdk/android/text/overview-0bd620/) --- In CreativeEditor SDK (CE.SDK), a *text element* is an editable, stylable block that you can add to your design. Whether you're creating marketing graphics, videos, social media posts, or multilingual layouts, text plays a vital role in conveying information and enhancing your visuals. You can fully manipulate text elements using both the user interface and programmatic APIs, giving you maximum flexibility to control how text behaves and appears. Additionally, text can be animated to bring motion to your designs. [Explore Demos](https://img.ly/showcases/cesdk?tags=android) [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Text Styling" description: "Apply fonts, colors, alignment, and other styling options to customize text appearance." platform: android url: "https://img.ly/docs/cesdk/android/text/styling-269c48/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Text](https://img.ly/docs/cesdk/android/text-8a993a/) > [Text Styling](https://img.ly/docs/cesdk/android/text/styling-269c48/) --- ```kotlin file=@cesdk_android_examples/engine-guides-text-properties/TextProperties.kt reference-only import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.AnimationType import ly.img.engine.Color import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.Font import ly.img.engine.FontStyle import ly.img.engine.FontWeight import ly.img.engine.SizeMode import ly.img.engine.TextCase import ly.img.engine.Typeface fun textProperties( license: String?, // pass null or empty for evaluation mode with watermark userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val scene = engine.scene.create() val text = engine.block.create(DesignBlockType.Text) engine.block.appendChild(parent = scene, child = text) engine.block.setWidthMode(text, mode = SizeMode.AUTO) engine.block.setHeightMode(text, mode = SizeMode.AUTO) engine.block.replaceText(text, text = "Hello World") // Add a "!" at the end of the text engine.block.replaceText(text, text = "!", from = 11) // Replace "World" with "Alex" engine.block.replaceText(text, text = "Alex", from = 6, to = 11) engine.scene.zoomToBlock( block = text, paddingLeft = 100F, paddingTop = 100F, paddingRight = 100F, paddingBottom = 100F, ) // Remove the "Hello " engine.block.removeText(text, from = 0, to = 6) engine.block.setTextColor(text, color = Color.fromHex("#FFFF0000")) engine.block.setTextColor(text, color = Color.fromHex("#FFFF0000"), from = 1, to = 4) val allColors = engine.block.getTextColors(text) val colorsInRange = engine.block.getTextColors(text, from = 2, to = 5) engine.block.setBoolean(text, property = "backgroundColor/enabled", value = true) val color = engine.block.getColor(text, property = "backgroundColor/color") engine.block.setColor(text, property = "backgroundColor/color", value = Color.fromRGBA(r = 0, g = 0, b = 1, a = 1)) engine.block.setFloat(text, property = "backgroundColor/paddingLeft", value = 1.0F) engine.block.setFloat(text, property = "backgroundColor/paddingTop", value = 2.0F) engine.block.setFloat(text, property = "backgroundColor/paddingRight", value = 3.0F) engine.block.setFloat(text, property = "backgroundColor/paddingBottom", value = 4.0F) engine.block.setFloat(text, property = "backgroundColor/cornerRadius", value = 4.0F) val animation = engine.block.createAnimation(AnimationType.Slide) engine.block.setEnum(animation, property = "textAnimationWritingStyle", value = "Block") engine.block.setInAnimation(text, animation = animation) engine.block.setOutAnimation(text, animation = animation) engine.block.setTextCase(text, textCase = TextCase.TITLE_CASE) val textCases = engine.block.getTextCases(text) val typeface = Typeface( name = "Roboto", fonts = listOf( Font( uri = Uri.parse("https://cdn.img.ly/assets/v3/ly.img.typeface/fonts/Roboto/Roboto-Bold.ttf"), subFamily = "Bold", weight = FontWeight.BOLD, style = FontStyle.NORMAL, ), Font( uri = Uri.parse("https://cdn.img.ly/assets/v3/ly.img.typeface/fonts/Roboto/Roboto-BoldItalic.ttf"), subFamily = "Bold Italic", weight = FontWeight.BOLD, style = FontStyle.ITALIC, ), Font( uri = Uri.parse("https://cdn.img.ly/assets/v3/ly.img.typeface/fonts/Roboto/Roboto-Italic.ttf"), subFamily = "Italic", weight = FontWeight.BOLD, style = FontStyle.NORMAL, ), Font( uri = Uri.parse("https://cdn.img.ly/assets/v3/ly.img.typeface/fonts/Roboto/Roboto-Regular.ttf"), subFamily = "Regular", weight = FontWeight.NORMAL, style = FontStyle.NORMAL, ), ), ) engine.block.setFont(text, typeface.fonts[3].uri, typeface) engine.block.setTypeface(text, typeface, from = 1, to = 4) engine.block.setTypeface(text, typeface) val currentDefaultTypeface = engine.block.getTypeface(text) val currentTypefaces = engine.block.getTypefaces(text) val currentTypefacesOfRange = engine.block.getTypefaces(text, from = 1, to = 4) if (engine.block.canToggleBoldFont(text)) { engine.block.toggleBoldFont(text) } if (engine.block.canToggleBoldFont(text, from = 1, to = 4)) { engine.block.toggleBoldFont(text, from = 1, to = 4) } if (engine.block.canToggleItalicFont(text)) { engine.block.toggleItalicFont(text) } if (engine.block.canToggleItalicFont(text, from = 1, to = 4)) { engine.block.toggleItalicFont(text, from = 1, to = 4) } val fontWeights = engine.block.getTextFontWeights(text) engine.block.setTextFontStyle(text, FontStyle.NORMAL) val fontStyles = engine.block.getTextFontStyles(text) engine.stop() } ``` In this example, we want to show how to read and modify the text block's contents via the API in the offscreen Engine. ## Editing the Text String You can edit the text string contents of a text block using the `fun replaceText(block: DesignBlock, text: String, from: Int = -1, to: Int = -1)` and `fun removeText(block: DesignBlock, from: Int = -1, to: Int = -1)` APIs. The range of text that should be edited is defined using the UTF-16 indices \[from, to). When omitting both the `from` and `to` arguments, the entire existing string is replaced. ```kotlin highlight-replaceText engine.block.replaceText(text, text = "Hello World") ``` When only specifying the `from` index, the new text is inserted at this index. ```kotlin highlight-replaceText-single-index // Add a "!" at the end of the text engine.block.replaceText(text, text = "!", from = 11) ``` When both `from` and `to` indices are specified, then that range of text is replaced with the new text. ```kotlin highlight-replaceText-range // Replace "World" with "Alex" engine.block.replaceText(text, text = "Alex", from = 6, to = 11) ``` Similarly, the `removeText` API can be called to remove either a specific range or the entire text. ```kotlin highlight-removeText // Remove the "Hello " engine.block.removeText(text, from = 0, to = 6) ``` ## Text Colors Text blocks in the Engine allow different ranges to have multiple colors. Use the `fun setTextColor(block: DesignBlock, color: Color, from: Int = -1, to: Int = -1)` API to change either the color of the entire text ```kotlin highlight-setTextColor engine.block.setTextColor(text, color = Color.fromHex("#FFFF0000")) ``` or only that of a range. After these two calls, the text "Alex!" now starts with one yellow character, followed by three black characters and two more yellow ones. ```kotlin highlight-setTextColor-range engine.block.setTextColor(text, color = Color.fromHex("#FFFF0000"), from = 1, to = 4) ``` The `fun getTextColors(block: DesignBlock, from: Int = -1, to: Int = -1): List` API returns an ordered list of unique colors in the requested range. Here, `allColors` will be a list containing the colors yellow and black (in this order). ```kotlin highlight-getTextColors val allColors = engine.block.getTextColors(text) ``` When only the colors in the UTF-16 range from 2 to 5 are requested, the result will be an array containing black and then yellow, since black appears first in the requested range. ```kotlin highlight-getTextColors-range val colorsInRange = engine.block.getTextColors(text, from = 2, to = 5) ``` ## Text Background You can create and edit the background of a text block by setting specific block properties. To add a colored background to a text block use the `fun setBoolean(block: DesignBlock, property: String, value: Boolean))` API and enable the `backgroundColor/enabled` property. ```kotlin highlight-backgroundColor-enabled engine.block.setBoolean(text, property = "backgroundColor/enabled", value = true) ``` The color of the text background can be queried (by making use of the `fun setColor(block: DesignBlock, property: String, value: Color)` API ) and also changed (with the `fun setColor(block: DesignBlock, property: String, value: Color)` API). ```kotlin highlight-backgroundColor-get-set val color = engine.block.getColor(text, property = "backgroundColor/color") ``` The padding of the rectangular background shape can be edited by using the `fun setFloat(block: DesignBlock, property: String, value: Float)` API and setting the target value for the desired padding property like: - `backgroundColor/paddingLeft`: - `backgroundColor/paddingRight`: - `backgroundColor/paddingTop`: - `backgroundColor/paddingBottom`: ```kotlin highlight-backgroundColor-padding engine.block.setFloat(text, property = "backgroundColor/paddingLeft", value = 1.0F) ``` Additionally, the rectangular shape of the background can be rounded by setting a corner radius with the `fun setFloat(block: DesignBlock, property: String, value: Float)` API to adjust the value of the `backgroundColor/cornerRadius` property. ```kotlin highlight-backgroundColor-cornerRadius engine.block.setFloat(text, property = "backgroundColor/cornerRadius", value = 4.0F) ``` Text backgrounds inherit the animations assigned to their respective text block when the animation text writing style is set to `Block`. ```kotlin highlight-backgroundColor-animation val animation = engine.block.createAnimation(AnimationType.Slide) ``` ## Text Case You can apply text case modifications to ranges of text in order to display them in upper case, lower case or title case. It is important to note that these modifiers do not change the `text` string value of the text block but are only applied when the block is rendered. By default, the text case of all text within a text block is set to `TextCase.NORMAL`, which does not modify the appearance of the text at all. The `fun setTextCase(block: DesignBlock, textCase: TextCase, from: Int = -1, to: Int = -1)` API sets the given text case for the selected range of text. Possible values for `TextCase` are: - `NORMAL`: The text string is rendered without modifications. - `UPPER_CASE`: All characters are rendered in upper case. - `LOWER_CASE`: All characters are rendered in lower case. - `TITLE_CASE`: The first character of each word is rendered in upper case. ```kotlin highlight-setTextCase engine.block.setTextCase(text, textCase = TextCase.TITLE_CASE) ``` The `fun getTextCases(block: DesignBlock, from: Int = -1, to: Int = -1): List` API returns the ordered list of text cases of the text in the selected range. ```kotlin highlight-getTextCases val textCases = engine.block.getTextCases(text) ``` ## Typefaces In order to change the font of a text block, you have to call the `fun setFont(block: DesignBlock, fontFileUri: Uri, typeface: Typeface)` API and provide it with both the uri of the font file to be actively used and the complete typeface definition of the corresponding typeface. Existing formatting of the block is reset. A typeface definition consists of the unique typeface name (as it is defined within the font files), and a list of all font definitions that belong to this typeface. Each font definition must provide a `Uri` which points to the font file and a `subFamily` string which is this font's effective name within its typeface. The subfamily value is typically also defined within the font file. The `weight` and `style` properties default to `NORMAL`, but must be provided in other cases. For the sake of this example, we define a `Roboto` typeface with only four fonts: `Regular`, `Bold`, `Italic`, and `Bold Italic` and we change the font of the text block to the Roboto Regular font. ```kotlin highlight-setFont val typeface = Typeface( name = "Roboto", fonts = listOf( Font( uri = Uri.parse("https://cdn.img.ly/assets/v3/ly.img.typeface/fonts/Roboto/Roboto-Bold.ttf"), subFamily = "Bold", weight = FontWeight.BOLD, style = FontStyle.NORMAL, ), Font( uri = Uri.parse("https://cdn.img.ly/assets/v3/ly.img.typeface/fonts/Roboto/Roboto-BoldItalic.ttf"), subFamily = "Bold Italic", weight = FontWeight.BOLD, style = FontStyle.ITALIC, ), Font( uri = Uri.parse("https://cdn.img.ly/assets/v3/ly.img.typeface/fonts/Roboto/Roboto-Italic.ttf"), subFamily = "Italic", weight = FontWeight.BOLD, style = FontStyle.NORMAL, ), Font( uri = Uri.parse("https://cdn.img.ly/assets/v3/ly.img.typeface/fonts/Roboto/Roboto-Regular.ttf"), subFamily = "Regular", weight = FontWeight.NORMAL, style = FontStyle.NORMAL, ), ), ) engine.block.setFont(text, typeface.fonts[3].uri, typeface) ``` If the formatting, e.g., bold or italic, of the text should be kept, you have to call the `fun setTypeface(block: DesignBlock, fontFileUri: Uri, typeface: Typeface)` API and provide it with both the uri of the font file to be used and the complete typeface definition of the corresponding typeface. The font file should be a fallback font, e.g., `Regular`, from the same typeface. The actual font that matches the formatting is chosen automatically with the current formatting retained as much as possible. If the new typeface does not support the current formatting, the formatting changes to a reasonable close one, e.g. thin might change to light, bold to normal, and/or italic to non-italic. If no reasonable font can be found, the fallback font is used. ```kotlin highlight-setTypeface engine.block.setTypeface(text, typeface, from = 1, to = 4) engine.block.setTypeface(text, typeface) ``` You can query the currently used typeface definition of a text block by calling the `fun getTypeface(block: DesignBlock): Typeface` API. It is important to note that new text blocks don't have any explicit typeface set until you call the `setFont` API. In this case, the `getTypeface` API will throw an error. ```kotlin highlight-getTypeface val currentDefaultTypeface = engine.block.getTypeface(text) ``` ## Font Weights and Styles Text blocks can also have multiple ranges with different weights and styles. In order to toggle the text of a text block between the normal and bold font weights, first call the `fun canToggleBoldFont(block: DesignBlock, from: Int = -1, to: Int = -1): Boolean` API to check whether such an edit is possible and if so, call the `fun toggleBoldFont(block: DesignBlock, from: Int = -1, to: Int = -1)` API to change the weight. ```kotlin highlight-toggleBold if (engine.block.canToggleBoldFont(text)) { engine.block.toggleBoldFont(text) } if (engine.block.canToggleBoldFont(text, from = 1, to = 4)) { engine.block.toggleBoldFont(text, from = 1, to = 4) } ``` In order to toggle the text of a text block between the normal and italic font styles, first call the `fun canToggleItalicFont(block: DesignBlock, from: Int = -1, to: Int = -1): Boolean` API to check whether such an edit is possible and if so, call the `fun toggleItalicFont(block: DesignBlock, from: Int = -1, to: Int = -1)` API to change the style. ```kotlin highlight-toggleItalic if (engine.block.canToggleItalicFont(text)) { engine.block.toggleItalicFont(text) } if (engine.block.canToggleItalicFont(text, from = 1, to = 4)) { engine.block.toggleItalicFont(text, from = 1, to = 4) } ``` In order to change the font weight or style, the typeface definition of the text block must include a font definition that corresponds to the requested font weight and style combination. For example, if the text block currently uses a bold font and you want to toggle the font style to italic - such as in the example code - the typeface must contain a font that is both bold and italic. The `fun getTextFontWeights(block: DesignBlock, from: Int = -1, to: Int = -1): List` API returns an ordered list of unique font weights in the requested range, similar to the `getTextColors` API described above. For this example text, the result will be `listOf(FontWeight.BOLD)`. ```kotlin highlight-getTextFontWeights val fontWeights = engine.block.getTextFontWeights(text) ``` The fun `setTextFontStyle(block: DesignBlock, fontStyle: FontStyle, from: Int = -1, to: Int = -1)` API sets a font style in the requested range. ```kotlin highlight-setTextFontStyle engine.block.setTextFontStyle(text, FontStyle.NORMAL) ``` The `fun getTextFontStyles(block: DesignBlock, from: Int = -1, to: Int = -1): List` API returns an ordered list of unique font styles in the requested range, similar to the `getTextColors` API described above. For this example text, the result will be `listOf(FontWeight.ITALIC)`. ```kotlin highlight-getTextFontStyles val fontStyles = engine.block.getTextFontStyles(text) ``` ## Full Code Here's the full code: ```kotlin import android.net.Uri import kotlinx.coroutines.* import ly.img.engine.* fun textProperties( license: String, userId: String, ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.example") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 100, height = 100) val scene = engine.scene.create() val text = engine.block.create(DesignBlockType.Text) engine.block.appendChild(parent = scene, child = text) engine.block.setWidthMode(text, mode = SizeMode.AUTO) engine.block.setHeightMode(text, mode = SizeMode.AUTO) engine.block.replaceText(text, text = "Hello World") // Add a "!" at the end of the text engine.block.replaceText(text, text = "!", from = 11) // Replace "World" with "Alex" engine.block.replaceText(text, text = "Alex", from = 6, to = 11) engine.scene.zoomToBlock( block = text, paddingLeft = 100F, paddingTop = 100F, paddingRight = 100F, paddingBottom = 100F, ) // Remove the "Hello " engine.block.removeText(text, from = 0, to = 6) engine.block.setTextColor(text, color = Color.fromHex("#FFFF0000")) engine.block.setTextColor(text, color = Color.fromHex("#FFFF0000"), from = 1, to = 4) val allColors = engine.block.getTextColors(text) val colorsInRange = engine.block.getTextColors(text, from = 2, to = 5) engine.block.setBoolean(text, property = "backgroundColor/enabled", value = true) val color = engine.block.getColor(text, property = "backgroundColor/color") engine.block.setColor(text, property = "backgroundColor/color", value = Color.fromRGBA(r = 0, g = 0, b = 1, a = 1)) engine.block.setFloat(text, property = "backgroundColor/paddingLeft", value = 1.0F) engine.block.setFloat(text, property = "backgroundColor/paddingTop", value = 2.0F) engine.block.setFloat(text, property = "backgroundColor/paddingRight", value = 3.0F) engine.block.setFloat(text, property = "backgroundColor/paddingBottom", value = 4.0F) engine.block.setFloat(text, property = "backgroundColor/cornerRadius", value = 4.0F) val animation = engine.block.createAnimation(AnimationType.Slide) engine.block.setEnum(animation, property = "textAnimationWritingStyle", value = "Block") engine.block.setInAnimation(text, animation = animation) engine.block.setOutAnimation(text, animation = animation) engine.block.setTextCase(text, textCase = TextCase.TITLE_CASE) val textCases = engine.block.getTextCases(text) val typeface = Typeface( name = "Roboto", fonts = listOf( Font( uri = Uri.parse("https://cdn.img.ly/assets/v2/ly.img.typeface/fonts/Roboto/Roboto-Bold.ttf"), subFamily = "Bold", weight = FontWeight.BOLD, style = FontStyle.NORMAL, ), Font( uri = Uri.parse("https://cdn.img.ly/assets/v2/ly.img.typeface/fonts/Roboto/Roboto-BoldItalic.ttf"), subFamily = "Bold Italic", weight = FontWeight.BOLD, style = FontStyle.ITALIC, ), Font( uri = Uri.parse("https://cdn.img.ly/assets/v2/ly.img.typeface/fonts/Roboto/Roboto-Italic.ttf"), subFamily = "Italic", weight = FontWeight.BOLD, style = FontStyle.NORMAL, ), Font( uri = Uri.parse("https://cdn.img.ly/assets/v2/ly.img.typeface/fonts/Roboto/Roboto-Regular.ttf"), subFamily = "Regular", weight = FontWeight.NORMAL, style = FontStyle.NORMAL, ), ), ) engine.block.setFont(text, typeface.fonts[3].uri, typeface) engine.block.setTypeface(text, typeface, from = 1, to = 4) engine.block.setTypeface(text, typeface) val currentDefaultTypeface = engine.block.getTypeface(text) val currentTypefaces = engine.block.getTypefaces(text) val currentTypefacesOfRange = engine.block.getTypefaces(text, from = 1, to = 4) if (engine.block.canToggleBoldFont(text)) { engine.block.toggleBoldFont(text) } if (engine.block.canToggleBoldFont(text, from = 1, to = 4)) { engine.block.toggleBoldFont(text, from = 1, to = 4) } if (engine.block.canToggleItalicFont(text)) { engine.block.toggleItalicFont(text) } if (engine.block.canToggleItalicFont(text, from = 1, to = 4)) { engine.block.toggleItalicFont(text, from = 1, to = 4) } val fontWeights = engine.block.getTextFontWeights(text) engine.block.setTextFontStyle(text, FontStyle.NORMAL) val fontStyles = engine.block.getTextFontStyles(text) engine.stop() } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Text Designs" description: "Create and customize text component libraries using predefined text designs that appear in your asset library." platform: android url: "https://img.ly/docs/cesdk/android/text/text-designs-a1b2c3/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Edit Text](https://img.ly/docs/cesdk/android/text-8a993a/) > [Text Designs](https://img.ly/docs/cesdk/android/text/text-designs-a1b2c3/) --- Text Designs (also known as Text Components) are pre-designed text layouts that appear in your asset library. Users can click on these components to automatically insert them into their designs. This guide explains how to prepare and customize the `content.json` file that defines these components. ## What are Text Designs? Text Designs are serialized text blocks or groups of text blocks configured with specific styling, layout constraints, and behavior. They provide users with professionally designed text layouts that are easy to customize while maintaining their visual integrity. When users browse the asset library, they see thumbnails of these text components. Clicking on a component automatically loads and inserts it into their current scene. ## Default Components CE.SDK ships with over 20 pre-built text designs including: - **Box** - Text with decorative border elements - **Breaking** - Bold, attention-grabbing headlines - **Cinematic** - Movie poster-style text effects - **Glow** - Text with luminous glow effects - **Greetings** - Welcoming message layouts - **Promo** - Promotional and sale-focused designs - **Quote** - Quote bubble and callout styles - **Speech** - Dialog and conversation layouts - **Valentine** - Romantic and heart-themed designs - **Handwriting** - Script and handwritten font styles - And many more... ## Content.json Structure Text designs are defined in a `content.json` file with the following structure: ```json { "version": "3.0.0", "id": "ly.img.textComponents", "assets": [ { "id": "ly.img.textComponents.box", "label": { "en": "Box" }, "meta": { "uri": "{{base_url}}/ly.img.textComponents/data/box/blocks.blocks", "thumbUri": "{{base_url}}/ly.img.textComponents/thumbnails/box.png", "mimeType": "application/ubq-blocks-string" } } ], "blocks": [] } ``` ### Key Properties - **version**: Content format version (currently "3.0.0") - **id**: Unique identifier for the asset source ("ly.img.textComponents") - **assets**: Array of component definitions ### Asset Properties Each component in the assets array has: - **id**: Unique identifier following the pattern `ly.img.textComponents.[name]` - **label**: Display name object with language codes (e.g., `{"en": "Box"}`) - **meta**: - **uri**: Path to the `.blocks` file containing the serialized component - **thumbUri**: Path to the thumbnail image (400x320px PNG recommended) - **mimeType**: Always `"application/ubq-blocks-string"` for text components The `{{base_url}}` placeholder gets replaced with your configured base URL. ## Creating Custom Components ### 1. Design Your Component Follow these best practices when designing text components: #### Text Settings - Use **variable text** with a range of 0-1000 characters - Set **fixed frame** with **clipping enabled** - Avoid growing or shrinking frames to prevent scaling issues #### Constraints Setup - **Parent Group**: Give the parent group all available constraint options for maximum flexibility - **Child Elements**: Set constraints relative to the parent group to maintain proper relationships during resizing #### Design Considerations - Use **scopes** and **auto font-size** features to enable easy editing - Test components by dropping them into new files to verify constraint behavior - Ensure components work as cohesive units that are easy to edit but difficult to accidentally break ### 2. Export Your Component Once your design is ready: 1. Select the complete text component (parent group with all children) 2. Use the BlockAPI (not the SceneAPI) to serialize it to an archive: ```kotlin // Save the component to a blocks archive file val blocksArchive = engine.block.saveToArchive(listOf(componentBlockId)) ``` #### Resource Management Text components often reference external resources like fonts and images. When using `saveToArchive()`, these resources can be stored. If you later serve all the resources together with the blocks file, the component can be used in other editors. Using `saveToArchive()` ensures that: - Font references remain valid across different environments - Components can be safely used in any scene - Serialized scenes maintain all resource references **Best Practices:** 1. **Ensure resource availability**: Make sure all resources used in your components are served 2. **Test in isolation**: Always test components in fresh editor instances to verify resource loading 3. **Validate references**: Check that all asset URIs are accessible from your target environments ### 3. Create Component Files #### Save the Blocks Archive File Save the component archive and extract it: - Use descriptive names matching your component ID (e.g., `customBox`) - Extract the zip file and store it in your `/data/customBox` directory structure - All files should be included in the same file structure as in the archive Example with only a blocks file: ``` /data/customBox/blocks.blocks ``` Example with images and fonts: ``` /data/customBox/blocks.blocks /data/customBox/fonts/59251598.ttf /data/customBox/fonts/355809377.ttf /data/customBox/images/3255389386.jpeg /data/customBox/images/3302885400.jpeg ``` #### Create Thumbnails Generate 400x320px PNG thumbnails: 1. Remove page background color from your design 2. Export as PNG using the block export API: ```kotlin // Export component as 400x320px thumbnail val thumbnailBuffer = engine.block.export( block = componentBlockId, mimeType = MimeType.PNG, options = ExportOptions( targetWidth = 400f, targetHeight = 320f, ) ) // Save thumbnail to file File.createTempFile("customBox", ".png") .apply { outputStream().channel.write(thumbnailBuffer) } ``` ### 4. Update content.json Add your new component to the assets array: ```json { "id": "ly.img.textComponents.customBox", "label": { "en": "Custom Box", "de": "Eigene Box" }, "meta": { "uri": "{{base_url}}/ly.img.textComponents/data/customBox/blocks.blocks", "thumbUri": "{{base_url}}/ly.img.textComponents/thumbnails/customBox.png", "mimeType": "application/ubq-blocks-string" } } ``` ## Hosting Custom Components ### Backend Setup 1. **Host your files**: Upload your modified `content.json`, `.blocks` files, and thumbnails to your web server 2. **Maintain structure**: Keep the same directory structure: ``` /ly.img.textComponents/ ├── content.json ├── data/ │ ├── box/blocks.blocks │ ├── customBox/blocks.blocks │ ├── customBox/fonts/59251598.ttf │ ├── customBox/fonts/355809377.ttf │ ├── customBox/images/3255389386.jpeg │ ├── customBox/images/3302885400.jpeg │ └── ... └── thumbnails/ ├── box.png ├── customBox.png └── ... ``` ### SDK Configuration To customize your application to use your custom assets, refer to [Serve Assets](https://img.ly/docs/cesdk/android/serve-assets-b0827c/). Your custom text designs will now appear in the text components section of the asset library. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "To v1.19" description: "Learn what changed in v1.19 and how to update your implementation to stay compatible." platform: android url: "https://img.ly/docs/cesdk/android/to-v1-19-55bcad/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Upgrading](https://img.ly/docs/cesdk/android/upgrade-4f8715/) > [To v1.19](https://img.ly/docs/cesdk/android/to-v1-19-55bcad/) --- Version v1.19 of CreativeEngineSDK and CreativeEditorSDK introduces structural changes to many of the current design blocks, making them more composable and more powerful. Along with this update, there are mandatory license changes that require attention. This comes with a number of breaking changes. This document will explain the changes and describe the steps you need to take to adapt them to your setup. ## **Initialization** The initialization of the `Engine` has changed. Now `start` is a suspending function and it requires a new parameter `license` which is the API key you received from our dashboard. There is also a new optional parameter `userId` an optional unique ID tied to your application's user. This helps us accurately calculate monthly active users (MAU). Especially useful when one person uses the app on multiple devices with a sign-in feature, ensuring they're counted once. Providing this aids in better data accuracy. ```kotlin engine.start(license = "", userId = "") ``` ## **DesignBlockType** This class is not an enum class anymore, but a sealed class. These are the transformations of all `DesignBlockType` types: Removed: - `DesignBlockType.IMAGE` - `DesignBlockType.VIDEO` - `DesignBlockType.STICKER` - `DesignBlockType.VECTOR_PATH` - `DesignBlockType.RECT_SHAPE` - `DesignBlockType.LINE_SHAPE` - `DesignBlockType.STAR_SHAPE` - `DesignBlockType.POLYGON_SHAPE` - `DesignBlockType.ELLIPSE_SHAPE` - `DesignBlockType.COLOR_FILL` - `DesignBlockType.IMAGE_FILL` - `DesignBlockType.VIDEO_FILL` - `DesignBlockType.LINEAR_GRADIENT_FILL` - `DesignBlockType.RADIAL_GRADIENT_FILL` - `DesignBlockType.CONICAL_GRADIENT_FILL` Renamed: - `DesignBlockType.SCENE` -> `DesignBlockType.Scene` - `DesignBlockType.STACK` -> `DesignBlockType.Stack` - `DesignBlockType.CAMERA` -> `DesignBlockType.Camera` - `DesignBlockType.PAGE` -> `DesignBlockType.Page` - `DesignBlockType.AUDIO` -> `DesignBlockType.Audio` - `DesignBlockType.TEXT` -> `DesignBlockType.Text` - `DesignBlockType.GROUP` -> `DesignBlockType.Group` Added: - `DesignBlockType.Graphic` - `DesignBlockType.Cutout` Note that `DesignBlockType.values()` can be used to get the list of all instances mentioned above. ## **Graphic Design Block** A new generic `DesignBlockType.Graphic` type has been introduced, that forms the basis of the new unified block structure. ## **Shapes** Similar to how the fill of a block is a separate object which can be attached to and replaced on a design block, we have now introduced a similar concept for the shape of a block. You use the new `createShape`, `getShape` and `setShape` APIs in order to define the shape of a design block. Only the new `DesignBlockType.Graphic` block allows to change its shape with these APIs. The new available shape types are: - `ShapeType.Rect` - `ShapeType.Line` - `ShapeType.Ellipse` - `ShapeType.Polygon` - `ShapeType.Star` - `ShapeType.VectorPath` Note that `ShapeType.values()` can be used to get the list of all instances mentioned above. The following design block types are now removed in favor of using a `DesignBlockType.Graphic` block with one of the above mentioned shape instances: - `DesignBlockType.RECT_SHAPE` - `DesignBlockType.LINE_SHAPE` - `DesignBlockType.ELLIPSE_SHAPE` - `DesignBlockType.POLYGON_SHAPE` - `DesignBlockType.STAR_SHAPE` - `DesignBlockType.VECTOR_PATH` This structural change means that the shape-specific properties (e.g. the number of sides of a polygon) are not available on the design block anymore but on the shape instances instead. You will have to add calls to `getShape` to get the instance id of the shape instance and then pass that to the property getter and setter APIs. Also, remember to change property key strings in the getter and setter calls from plural `shapes/…` to singular `shape/…` to match the new type identifiers. ## **Image and Sticker** Previously, `DesignBlockType.IMAGE` and `DesignBlockType.STICKER` were their own high-level design block types. They neither support the fill APIs nor the effects APIs. Both of these blocks are now removed in favor of using a `DesignBlockType.Graphic` block with an image fill (`FillType.Image`) and using the effects APIs instead of the legacy image block’s numerous effects properties. At its core, the sticker block has always just been an image block that is heavily limited in its capabilities. You can neither crop it, nor apply any effects to it. In order to replicate the difference as closely as possible in the new unified structure, more fine-grained scopes have been added. You can now limit the adopter’s ability to crop a block and to edit its appearance. Note that since these scopes only apply to a user of the editor with the “Adopter” role, a “Creator” user will now have all of the same editing options for both images and for blocks that used to be stickers. ## **Scopes** The following is the list of changes to the design block scopes: - (Breaking) The permission to crop a block was split from `content/replace` and `design/style` into a separate scope: `layer/crop`. - Deprecated the `design/arrange` scope and renamed `design/arrange/move` → `layer/move` `design/arrange/resize` → `layer/resize` `design/arrange/rotate` → `layer/rotate` `design/arrange/flip` → `layer/flip` - Deprecated the `content/replace` scope. For `DesignBlockType.Text` blocks, it is replaced with the new `text/edit` scope. For other blocks it is replaced with `fill/change`. - Deprecated the `design/style` scope and replaced it with the following fine-grained scopes: `text/character`, `stroke/change`, `layer/opacity`, `layer/blendMode`, `layer/visibility`, `layer/clipping`, `appearance/adjustments`, `appearance/filter`, `appearance/effect`, `appearance/blur`, `appearance/shadow` - Introduced `fill/change`, `stroke/change`, and `shape/change` scopes that control whether the fill, stroke or shape of a block may be edited by a user with an "Adopter" role. - The deprecated scopes are automatically mapped to their new corresponding scopes by the scope APIs for now until they will be removed completely in a future update. ## **Kind** While the new unified block structure both simplifies a lot of code and makes design blocks more powerful, it also means that many of the design blocks that used to have unique type ids now all have the same generic `DesignBlockType.Graphic` type, which means that calls to the `findByType` cannot be used to filter blocks based on their legacy type ids any more. Simultaneously, there are many instances in which different blocks in the scene which might have the same type and underlying technical structure have different semantic roles in the document and should therefore be treated differently by the user interface. To solve both of these problems, we have introduced the concept of a block “kind”. This is a mutable string that can be used to tag different blocks with a semantic label. You can get the kind of a block using the `getKind` API and you can query blocks with a specific kind using the `findByKind` API. CreativeEngine provides the following default kind values: - `image` - `video` - `sticker` - `scene` - `camera` - `stack` - `page` - `audio` - `text` - `shape` - `group` Unlike the immutable design block type id, you can change the kind of a block with the new `setKind` API. It is important to remember that the underlying structure and properties of a design block are not strictly defined by its kind, since the kind, shape, fill and effects of a block can be changed independent of each other. Therefore, a user-interface should not make assumptions about available properties of a block purely based on its kind. > **Note:** **Note**Due to legacy reasons, blocks with the kind "sticker" will continue to not allow > their contents to be cropped. This special behavior will be addressed and replaced > with a more general-purpose implementation in a future update. ​ ## **Asset Definitions** The asset definitions have been updated to reflect the deprecation of legacy block type ids and the introduction of the “kind” property. In addition to the “blockType” meta property, you can now also define the `“shapeType”` ,`“fillType”` and `“kind”` of the block that should be created by the default implementation of the applyAsset function. - `“blockType”` defaults to `DesignBlockType.Graphic.key (“//ly.img.ubq/graphic”)` if left unspecified. - `“shapeType”` defaults to `ShapeType.Rect.key (“//ly.img.ubq/shape/rect”)` if left unspecified - `“fillType”` defaults to `FillType.Color.key (“//ly.img.ubq/fill/color”)` if left unspecified Video block asset definitions used to specify the `“blockType”` as `“//ly.img.ubq/fill/video“ (FillType.Video.key)`. The `“fillType”` meta asset property should now be used instead for such fill type ids. ## **Automatic Migration** CreativeEngine will always continue to support scene files that contain the now removed legacy block types. Those design blocks will be automatically replaced by the equivalent new unified block structure when the scene is loaded, which means that the types of all legacy blocks will change to `DesignBlockType.Graphic`. Note that this can mean that a block gains new capabilities that it did not have before. For example, the line shape block did not have any stroke properties, so the `hasStroke` API used to return `false`. However, after the automatic migration its `DesignBlockType.Graphic` design block replacement supports both strokes and fills, so the `hasStroke` API now returns `true` . Similarly, the image block did not support fills or effects, but the `DesignBlockType.Graphic` block does. ## **Types and API Signatures** To improve the type safety of our APIs, we have moved away from using the `DesignBlockType` enum and replaced with a set of types. Those changes have affected the following APIs: - `BlockApi.create()` - `BlockApi.createFill()` - `BlockApi.createEffect()` - `BlockApi.createBlur()` - `BlockApi.findByType()` > **Note:** **Note**All the functions above still support the string overload variants, however, their > usage will cause lint warnings in favor of type safe overloads. ## **Code Examples** This section will show some code examples of the breaking changes and how it would look like after migrating. ```kotlin /** Block Creation */ // Creating an Image before migration val image = engine.block.create(DesignBlockType.IMAGE) engine.block.setString( block = image, property = "image/imageFileURI", value = "https://domain.com/link-to-image.jpg" ) // Creating an Image after migration val block = engine.block.create(DesignBlockType.Graphic) val rectShape = engine.block.createShape(ShapeType.Rect) val imageFill = engine.block.createFill(FillType.Image) engine.block.setString( block = imageFill, property = "fill/image/imageFileURI", value = "https://domain.com/link-to-image.jpg" ) engine.block.setShape(block, shape = rectShape) engine.block.setFill(block, fill = imageFill) engine.block.setKind(block, kind = "image") // Creating a star shape before migration val star = engine.block.create(DesignBlockType.STAR_SHAPE) engine.block.setInt(star, property = "shapes/star/points", value = 8) // Creating a star shape after migration val block = engine.block.create(DesignBlockType.Graphic) val starShape = engine.block.createShape(ShapeType.Star) val colorFill = engine.block.createFill(FillType.Color) engine.block.setInt(block = starShape, property = "shape/star/points", value = 8) engine.block.setShape(block, shape = starShape) engine.block.setFill(block, fill = colorFill) engine.block.setKind(block, kind = "shape") // Creating a sticker before migration val sticker = engine.block.create(DesignBlockType.STICKER) engine.block.setString( block = sticker, property = "sticker/imageFileURI", value = "https://domain.com/link-to-sticker.png" ) // Creating a sticker after migration val block = engine.block.create(DesignBlockType.Graphic) val rectShape = engine.block.createShape(ShapeType.Rect) val imageFill = engine.block.createFill(FillType.Image) engine.block.setString( block = imageFill, property = "fill/image/imageFileURI", value = "https://domain.com/link-to-sticker.png" ) engine.block.setShape(block, shape = rectShape) engine.block.setFill(block, fill = imageFill) engine.block.setKind(block, kind = "sticker") /** Block Creation */ ``` ```kotlin /** Block Exploration */ // Query all images in the scene before migration val images = engine.block.findByType(DesignBlockType.IMAGE) // Query all images in the scene after migration val images = engine.block.findByType(DesignBlockType.Graphic).filter { block -> val fill = engine.block.getFill(block) engine.block.isValid(fill) && engine.block.getType(fill) == FillType.Image.key } // Query all stickers in the scene before migration val stickers = engine.block.findByType(DesignBlockType.STICKER) // Query all stickers in the scene after migration val stickers = engine.block.findByKind("sticker") // Query all Polygon shapes in the scene before migration val polygons = engine.block.findByType(DesignBlockType.POLYGON_SHAPE) // Query all Polygon shapes in the scene after migration val polygons = engine.block.findByType(DesignBlockType.Graphic).filter { block -> val shape = engine.block.getShape(block) engine.block.isValid(shape) && engine.block.getType(shape) == ShapeType.Polygon.key } /** Block Exploration */ ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Upgrade" description: "Learn how to upgrade CE.SDK and apply required changes when migrating between major SDK versions." platform: android url: "https://img.ly/docs/cesdk/android/upgrade-4f8715/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Upgrading](https://img.ly/docs/cesdk/android/upgrade-4f8715/) --- --- ## Related Pages - [To v1.19](https://img.ly/docs/cesdk/android/to-v1-19-55bcad/) - Learn what changed in v1.19 and how to update your implementation to stay compatible. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Apply a Template" description: "Learn how to apply template scenes via API in the CreativeEditor SDK." platform: android url: "https://img.ly/docs/cesdk/android/use-templates/apply-template-35c73e/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Use Templates](https://img.ly/docs/cesdk/android/create-templates-3aef79/) > [Apply a Template](https://img.ly/docs/cesdk/android/use-templates/apply-template-35c73e/) --- ```kotlin reference-only val rawResId = R.raw.cesdk_postcard_1 val rawResourcePath = context.resources.run { ContentResolver.SCHEME_ANDROID_RESOURCE + "://"+ getResourcePackageName(rawResId) + "/"" + getResourceTypeName(rawResId) + "/" + getResourceEntryName(rawResId) } engine.scene.applyTemplate(template = "UBQ1ewoiZm9ybWF0Ij...") engine.scene.applyTemplate(templateUri = Uri.parse("https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene")) engine.scene.applyTemplate(templateUri = Uri.parse("file:///android_asset/templates/cesdk_postcard_1.scene")) engine.scene.applyTemplate(templateUri = Uri.fromFile(File(filesDir, "templates/cesdk_postcard_1.scene"))) engine.scene.applyTemplate(templateUri = Uri.parse(rawResourcePath)) engine.scene.get() ``` In this example, we will show you how to use the [CreativeEditor SDK](https://img.ly/products/creative-sdk)'s CreativeEngine to apply the contents of a given template scene to the currently loaded scene through the `scene` API. ## Applying Template Scenes ```kotlin suspend fun applyTemplate(template: String) ``` Applies the contents of the given template scene to the currently loaded scene. This loads the template scene while keeping the design unit and page dimensions of the current scene. The content of the pages is automatically adjusted to fit the new dimensions. - `template`: the template scene file contents, a base64 string. ```kotlin suspend fun applyTemplate(templateUri: Uri) ``` Applies the contents of the given template scene to the currently loaded scene. This loads the template scene while keeping the design unit and page dimensions of the current scene. The content of the pages is automatically adjusted to fit the new dimensions. - `templateUri`: the resource of the template scene file. ```kotlin fun get(): DesignBlock? ``` Return the currently active scene. - Returns the scene or null, if none was created yet. ## Full Code Here's the full code: ```kotlin val rawResId = R.raw.cesdk_postcard_1 val rawResourcePath = context.resources.run { ContentResolver.SCHEME_ANDROID_RESOURCE + "://"+ getResourcePackageName(rawResId) + "/"" + getResourceTypeName(rawResId) + "/" + getResourceEntryName(rawResId) } engine.scene.applyTemplate(template = "UBQ1ewoiZm9ybWF0Ij...") engine.scene.applyTemplate(templateUri = Uri.parse("https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene")) engine.scene.applyTemplate(templateUri = Uri.parse("file:///android_asset/templates/cesdk_postcard_1.scene")) engine.scene.applyTemplate(templateUri = Uri.fromFile(File(filesDir, "templates/cesdk_postcard_1.scene"))) engine.scene.applyTemplate(templateUri = Uri.parse(rawResourcePath)) engine.scene.get() ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Generate From Templates" description: "Learn how to load and populate CE.SDK templates in Kotlin for Android applications." platform: android url: "https://img.ly/docs/cesdk/android/use-templates/generate-334e15/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Use Templates](https://img.ly/docs/cesdk/android/create-templates-3aef79/) > [Generate From Template](https://img.ly/docs/cesdk/android/use-templates/generate-334e15/) --- Once you create templates, either in CE.SDK's web-based editor or programmatically, your Android app can load and apply them to scenes at runtime. This guide explains **how to load templates**, populate them with variables and images, and use template libraries to integrate them into your app. ## What You'll Learn - Load templates from string or URL. - Launch the editor with a template as the initial scene. - Populate templates with dynamic content using variables and placeholders. - Create custom template libraries with thumbnails and metadata. - Work with template archives for bundled assets. ## When to Use It Use this guide when your Android app needs to **load and apply existing templates** to generate new scenes, such as: - Starting from a brand template. - Building a "Start from Template" screen. - Populating designs dynamically with user or product data. ## Loading Templates as Scenes You can load a template as the active scene when you start the engine or launch the editor. This is ideal when you want to either open directly into a predefined layout or start an editing session from a template. ### Load from URL Use `engine.scene.load(sceneUri =)` to load a template from a remote or local URL. ```kotlin import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.Engine fun loadTemplateFromURL(license: String, userId: String) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.template") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) val templateUri = Uri.parse("https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene") val scene = engine.scene.load(sceneUri = templateUri) // Template is now loaded and ready for modifications } ``` ### Load from String Use `engine.scene.load(scene =)` when you have the template as a string, such as when loading from a database or when your backend returns the raw string encoding. ```kotlin import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import kotlinx.coroutines.withContext import ly.img.engine.Engine import java.io.ByteArrayOutputStream import java.net.URL fun loadTemplateFromString(license: String, userId: String) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.template") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) // Fetch template string (could be from database, API, etc.) val templateUrl = URL("https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene") val templateString = withContext(Dispatchers.IO) { val outputStream = ByteArrayOutputStream() templateUrl.openStream().use { inputStream -> outputStream.use(inputStream::copyTo) } String(outputStream.toByteArray(), Charsets.UTF_8) } val scene = engine.scene.load(scene = templateString) // Template is now loaded and ready for modifications } ``` ### Load from Assets For templates bundled in your app's assets folder, use the `file:///android_asset/` URI scheme. ```kotlin import android.net.Uri import ly.img.engine.Engine suspend fun loadTemplateFromAssets(engine: Engine) { val templateUri = Uri.parse("file:///android_asset/templates/postcard_template.scene") val scene = engine.scene.load(sceneUri = templateUri) } ``` ### Load from Archive Archives bundle the scene file with all its assets (images, fonts) for portability. To load an archive: 1. Unzip the archive to a location accessible to the engine 2. Load the `scene.scene` file from the unzipped location ```kotlin import android.content.Context import android.net.Uri import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import ly.img.engine.Engine import java.io.File import java.io.FileOutputStream import java.util.zip.ZipInputStream suspend fun loadTemplateFromArchive( engine: Engine, context: Context, archiveUri: Uri ): Int { // Unzip archive to cache directory val extractDir = File(context.cacheDir, "template_${System.currentTimeMillis()}") extractDir.mkdirs() withContext(Dispatchers.IO) { context.contentResolver.openInputStream(archiveUri)?.use { inputStream -> ZipInputStream(inputStream).use { zipInputStream -> var entry = zipInputStream.nextEntry while (entry != null) { val file = File(extractDir, entry.name) if (entry.isDirectory) { file.mkdirs() } else { file.parentFile?.mkdirs() FileOutputStream(file).use { outputStream -> zipInputStream.copyTo(outputStream) } } zipInputStream.closeEntry() entry = zipInputStream.nextEntry } } } } // Load the scene.scene file from extracted directory val sceneFile = File(extractDir, "scene.scene") val sceneUri = Uri.fromFile(sceneFile) return engine.scene.load(sceneUri = sceneUri) } ``` ## Dynamic Population (Variables & Placeholders) Templates can include variable placeholders like `{{name}}` or image placeholders. Your app can inject values at runtime. > **Note:** Interactive placeholder behavior (tap-to-replace, drag-drop) is available only in **CE.SDK's predefined editors**.In **code-only or headless workflows**, use the `Variable` and `Block` APIs to replace content programmatically. ### Update Text Variables Variables allow you to dynamically populate text fields in your template. ```kotlin import ly.img.engine.Engine fun populateTextVariables(engine: Engine, userName: String, itemPrice: String) { engine.variable.set(key = "name", value = userName) engine.variable.set(key = "price", value = itemPrice) engine.variable.set(key = "date", value = "November 23, 2025") } ``` ### Replace Image Placeholders Find blocks by name and update their image fill URIs to replace placeholder images. ```kotlin import ly.img.engine.Engine fun replaceImagePlaceholder(engine: Engine, blockName: String, imageUri: String) { val blocks = engine.block.findByName(blockName) if (blocks.isNotEmpty()) { val block = blocks.first() val fill = engine.block.getFill(block) engine.block.setString(fill, property = "fill/image/imageFileURI", value = imageUri) engine.block.resetCrop(block) } } ``` ### Complete Population Example Here's a complete example that loads a template and populates it with dynamic content: ```kotlin import android.content.Context import android.net.Uri import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import ly.img.engine.DesignBlockType import ly.img.engine.Engine import ly.img.engine.MimeType import java.io.File fun generateFromTemplate( context: Context, license: String, userId: String ) = CoroutineScope(Dispatchers.Main).launch { val engine = Engine.getInstance(id = "ly.img.engine.template") engine.start(license = license, userId = userId) engine.bindOffscreen(width = 1080, height = 1920) // Load template val templateUri = Uri.parse("file:///android_asset/templates/greeting_card.scene") val scene = engine.scene.load(sceneUri = templateUri) // Populate text variables engine.variable.set(key = "recipientName", value = "Alice") engine.variable.set(key = "message", value = "Happy Birthday!") engine.variable.set(key = "senderName", value = "Bob") // Replace image placeholder val photoBlocks = engine.block.findByName("userPhoto") if (photoBlocks.isNotEmpty()) { val photoBlock = photoBlocks.first() val fill = engine.block.getFill(photoBlock) engine.block.setString( fill, property = "fill/image/imageFileURI", value = "https://example.com/photos/alice.jpg" ) engine.block.resetCrop(photoBlock) } // Export the result val page = engine.block.findByType(DesignBlockType.Page).firstOrNull() if (page != null) { val exportData = engine.block.export(page, mimeType = MimeType.PNG) // Save to file... } engine.stop() } ``` ## Template Libraries You can present templates in the Asset Library along with other assets via a local asset source. Each entry includes metadata that points to your template file and a preview image. You can learn more about working with custom assets in the [custom asset source](https://img.ly/docs/cesdk/android/import-media/asset-library-65d6c4/) guide. ### Create a Template Asset Source ```kotlin import ly.img.engine.AssetDefinition import ly.img.engine.Engine fun registerTemplateAssetSource(engine: Engine) { // Create a local source for templates engine.asset.addLocalSource( sourceId = "my-templates", supportedMimeTypes = listOf("application/octet-stream") ) // Add template assets to the source val postcardTemplate = AssetDefinition( id = "template-postcard-1", label = mapOf("en" to "Postcard Template"), tags = mapOf("en" to listOf("postcard", "greeting")), meta = mapOf( "uri" to "file:///android_asset/templates/postcard_1.scene", "thumbUri" to "file:///android_asset/templates/thumbnails/postcard_1.png", "width" to "1080", "height" to "1080" ) ) val socialTemplate = AssetDefinition( id = "template-social-1", label = mapOf("en" to "Social Media Post"), tags = mapOf("en" to listOf("social", "instagram")), meta = mapOf( "uri" to "file:///android_asset/templates/social_1.scene", "thumbUri" to "file:///android_asset/templates/thumbnails/social_1.png", "width" to "1080", "height" to "1350" ) ) engine.asset.addAsset(sourceId = "my-templates", asset = postcardTemplate) engine.asset.addAsset(sourceId = "my-templates", asset = socialTemplate) } ``` ## Launch Editor with Template When using one of CE.SDK's prebuilt editors, you can load a template as the initial scene: ```kotlin import android.net.Uri import androidx.compose.runtime.Composable import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EngineConfiguration @Composable fun EditorWithTemplate(navController: NavHostController) { val engineConfiguration = EngineConfiguration.rememberForDesign( license = "your-license", userId = "user-id", sceneUri = Uri.parse("file:///android_asset/templates/default_template.scene") ) DesignEditor(engineConfiguration = engineConfiguration) { navController.popBackStack() } } ``` ## Troubleshooting **❌ Template fails to load**: - Verify the URI is accessible and the file exists. - Check network permissions for remote URLs. - Ensure template format is compatible with your SDK version. **❌ Text variables not updating**: - Confirm variable names match exactly (case-sensitive). - Check that variables are defined in the template with `{{variableName}}` syntax. - Use `engine.variable.findAll()` to list available variables. **❌ Images missing after loading**: - Ensure image URIs in the template are accessible. - For archives, verify extraction was successful. - Check asset permissions in AndroidManifest.xml. **❌ Wrong dimensions or scaling**: - Templates maintain their original page dimensions. - Use `engine.block.getFrameWidth()` and `engine.block.getFrameHeight()` to check dimensions. - Consider template adaptation strategies for different aspect ratios. **Debugging Tips**: - Print all available variables: `engine.variable.findAll()` - List named blocks: Use `engine.block.findByName()` to verify block names - Test with a minimal template before using complex ones - Use Android Logcat to track loading and population flow ## Next Steps Now that you can generate creations from templates, some related topics you may find helpful are: - [Create templates](https://img.ly/docs/cesdk/android/create-templates/from-scratch-663cda/) from scratch. - Work with [text variables](https://img.ly/docs/cesdk/android/create-templates/add-dynamic-content/text-variables-7ecb50/) for dynamic content. - Build [batch processing](https://img.ly/docs/cesdk/android/automation/batch-processing-ab2d18/) workflows with templates. - Implement [multi-image generation](https://img.ly/docs/cesdk/android/automation/multi-image-generation-2a0de4/) for variants. - [Save scenes](https://img.ly/docs/cesdk/android/export-save-publish/save-c8b124/) as templates for reuse. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Overview" description: "Learn how to browse, apply, and dynamically populate templates in CE.SDK to streamline design workflows." platform: android url: "https://img.ly/docs/cesdk/android/use-templates/overview-ae74e1/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [Create and Use Templates](https://img.ly/docs/cesdk/android/create-templates-3aef79/) > [Use Templates Overview](https://img.ly/docs/cesdk/android/use-templates/overview-ae74e1/) --- Templates in CreativeEditor SDK (CE.SDK) are pre-designed layouts that serve as starting points for generating static designs, videos, or print-ready outputs. Templates can be used to produce a wide range of media, including images, PDFs, and videos. Instead of creating a design from scratch, you can use a template to quickly produce content by adapting pre-defined elements like text, images, and layout structures. Using templates offers significant advantages: faster content creation, consistent visual style, and scalable design workflows across many outputs. CE.SDK supports two modes of using templates: - **Fully Programmatic**: Generate content variations automatically by merging external data into templates without user intervention. - **User-Assisted**: Let users load a template, customize editable elements, and export the result manually. Template-based generation can be performed entirely on the client, entirely on a server, or in a hybrid setup where users interact with templates client-side before triggering automated server-side generation. [Explore Demos](https://img.ly/showcases/cesdk?tags=android) [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) ## Output Formats When Using Templates When generating outputs from templates, CE.SDK supports: Templates are format-aware, allowing you to design once and export to multiple formats seamlessly. For example, a single marketing template could be used to produce a social media graphic, a printable flyer, and a promotional video, all using the same underlying design. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "User Interface" description: "Use CE.SDK’s customizable, production-ready UI or replace it entirely with your own interface." platform: android url: "https://img.ly/docs/cesdk/android/user-interface-5a089a/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [User Interface](https://img.ly/docs/cesdk/android/user-interface-5a089a/) --- --- ## Related Pages - [Overview](https://img.ly/docs/cesdk/android/user-interface/overview-41101a/) - Use CE.SDK’s customizable, production-ready UI or replace it entirely with your own interface. - [Appearance](https://img.ly/docs/cesdk/android/user-interface/appearance-b155eb/) - Customize the visual style of the editor UI, including themes, fonts, labels, and icons. - [Customization](https://img.ly/docs/cesdk/android/user-interface/customization-72b2f8/) - Control which features are available and how UI components behave, appear, or are arranged in the editor. - [UI Extensions](https://img.ly/docs/cesdk/android/user-interface/ui-extensions-d194d1/) - Extend the editor interface with custom components, panels, actions, and dialogs tailored to your workflow. - [Localization](https://img.ly/docs/cesdk/android/user-interface/localization-508e20/) - Learn how to configure and manage multiple languages in the CE.SDK editor using the built-in internationalization API. - [UI Events](https://img.ly/docs/cesdk/android/user-interface/events-514b70/) - Listen to UI events and trigger custom logic based on user interactions in the editor interface. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Appearance" description: "Customize the visual style of the editor UI, including themes, fonts, labels, and icons." platform: android url: "https://img.ly/docs/cesdk/android/user-interface/appearance-b155eb/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [User Interface](https://img.ly/docs/cesdk/android/user-interface-5a089a/) > [Appearance](https://img.ly/docs/cesdk/android/user-interface/appearance-b155eb/) --- --- ## Related Pages - [Theming](https://img.ly/docs/cesdk/android/user-interface/appearance/theming-4b0938/) - Customize the editor's visual theme to match your brand using flexible theming options. - [Overlay](https://img.ly/docs/cesdk/android/user-interface/appearance/overlay-b7e891/) - Configure custom overlays for mobile to show dialogs or loading states in response to UI events. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Overlay" description: "Configure custom overlays for mobile to show dialogs or loading states in response to UI events." platform: android url: "https://img.ly/docs/cesdk/android/user-interface/appearance/overlay-b7e891/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [User Interface](https://img.ly/docs/cesdk/android/user-interface-5a089a/) > [Appearance](https://img.ly/docs/cesdk/android/user-interface/appearance-b155eb/) > [Overlay](https://img.ly/docs/cesdk/android/user-interface/appearance/overlay-b7e891/) --- In this example, we will show you how to make overlay configurations for the mobile editor. The example is based on the `Design Editor`, however, it is exactly the same for all the other [solutions](https://img.ly/docs/cesdk/android/prebuilt-solutions-d0ed07/). Explore a full code sample on [GitHub](https://github.com/imgly/cesdk-android-examples/tree/v$UBQ_VERSION$/editor-guides-configuration-overlay). ## Configuration When working with [UI events](https://img.ly/docs/cesdk/android/user-interface/events-514b70/), you may want to update the UI that is drawn over the editor (a.k.a `Overlay`) upon receiving events. A great example would be showing a loading indicator when the editor is being loaded or showing a custom dialog asking for export configurations when your customer taps on the `Export` button. This is when overlay configuration comes to help. In this example, we are going to demonstrate how upon capturing show/hide loading events you can render your own loading dialog. The default `EditorUiState` already contains `showLoading` property that is responsible for drawing an overlaying loading. Although we can use the same property, let's create our own state class in order to demonstrate how the default state can be wrapped and extended. The only requirement of the state class is that it has to be `Parcelable`. By default, both `onCreate` and `onExport` [callbacks](https://img.ly/docs/cesdk/android/user-interface/events-514b70/) send `ShowLoading` and `HideLoading` UI events. All we have to do is capture these events and override the default behavior. Similar to the [UI events](https://img.ly/docs/cesdk/android/user-interface/events-514b70/) guide, the events are captured and an updated state is returned. Note that instead of updating the `EditorUiState.showLoading` property we update the property of the brand new state: `OverlayCustomState.showCustomLoading`. As the state is updated, the updated state is received in the `overlay` composable callback to be rendered. Finally, we can render our custom loading dialog and render remaining default overlay components via `EditorDefaults.Overlay` composable function. Note that the callback receives `EditorEventHandler` object too in case your composable component requires UI interaction. In this example, tapping on the confirm button of the loading dialog closes the dialog and the editor. Note that the overlay is edge-to-edge, therefore it is your responsibility to draw over system bars too. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Theming" description: "Customize the editor's visual theme to match your brand using flexible theming options." platform: android url: "https://img.ly/docs/cesdk/android/user-interface/appearance/theming-4b0938/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [User Interface](https://img.ly/docs/cesdk/android/user-interface-5a089a/) > [Appearance](https://img.ly/docs/cesdk/android/user-interface/appearance-b155eb/) > [Theming](https://img.ly/docs/cesdk/android/user-interface/appearance/theming-4b0938/) --- In this example, we will show you how to make theming configurations for the mobile editor. The example is based on the `Design Editor`, however, it is exactly the same for all the other [solutions](https://img.ly/docs/cesdk/android/prebuilt-solutions-d0ed07/). ## Configuration Theming configuration is part of the `EditorConfiguration` class. Use the `EditorConfiguration.getDefault` helper function to make theming configurations. - `uiMode` - the UI mode of the editor. The default value is `EditorUiMode.SYSTEM`. These are the available values: - `EditorUiMode.SYSTEM` - editor will use the light color scheme if the system is in light mode and will use the dark color scheme if the system is in dark mode. - `EditorUiMode.LIGHT` - editor will always use the light color scheme. - `EditorUiMode.DARK` - editor will always use the dark color scheme. ```kotlin import androidx.compose.runtime.Composable import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EditorUiMode import ly.img.editor.EngineConfiguration import ly.img.editor.rememberForDesign // Add this composable to your NavHost @Composable fun ThemingEditorSolution(navController: NavHostController) { val engineConfiguration = EngineConfiguration.rememberForDesign( license = "", ) val editorConfiguration = EditorConfiguration.rememberForDesign( uiMode = EditorUiMode.DARK, ) DesignEditor( engineConfiguration = engineConfiguration, editorConfiguration = editorConfiguration, ) { // You can set result here navController.popBackStack() } } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Customization" description: "Control which features are available and how UI components behave, appear, or are arranged in the editor." platform: android url: "https://img.ly/docs/cesdk/android/user-interface/customization-72b2f8/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [User Interface](https://img.ly/docs/cesdk/android/user-interface-5a089a/) > [Customization](https://img.ly/docs/cesdk/android/user-interface/customization-72b2f8/) --- --- ## Related Pages - [Page Format](https://img.ly/docs/cesdk/android/user-interface/customization/page-format-496315/) - Define default page size, orientation, and other format settings for your design canvas. - [Crop Presets](https://img.ly/docs/cesdk/android/user-interface/customization/crop-presets-f94f26/) - Define crop presets settings for your design. - [Force Crop](https://img.ly/docs/cesdk/android/user-interface/customization/force-crop-c2854e/) - Apply predefined crop presets programmatically in the Android SDK. - [Navigation Bar](https://img.ly/docs/cesdk/android/user-interface/customization/navigation-bar-4e5d39/) - Show, hide, or customize the editor's top navigation bar to match your app layout. - [Dock](https://img.ly/docs/cesdk/android/user-interface/customization/dock-cb916c/) - Configure the dock area to show or hide tools, panels, or quick access actions. - [Panel](https://img.ly/docs/cesdk/android/user-interface/customization/panel-7ce1ee/) - Show or hide side panels to focus the user interface on what matters most for your use case. - [Inspector Bar](https://img.ly/docs/cesdk/android/user-interface/customization/inspector-bar-8ca1cd/) - Customize the inspector bar for editing properties like position, color, and size. - [Canvas Menu](https://img.ly/docs/cesdk/android/user-interface/customization/canvas-menu-0d2b5b/) - Control visibility and options in the canvas context menu. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Canvas Menu" description: "Control visibility and options in the canvas context menu." platform: android url: "https://img.ly/docs/cesdk/android/user-interface/customization/canvas-menu-0d2b5b/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [User Interface](https://img.ly/docs/cesdk/android/user-interface-5a089a/) > [Customization](https://img.ly/docs/cesdk/android/user-interface/customization-72b2f8/) > [Canvas Menu](https://img.ly/docs/cesdk/android/user-interface/customization/canvas-menu-0d2b5b/) --- ```kotlin file=@cesdk_android_examples/editor-guides-configuration-canvas-menu/SimpleCanvasMenuSolution.kt reference-only import androidx.compose.animation.EnterTransition import androidx.compose.animation.ExitTransition import androidx.compose.foundation.layout.Box import androidx.compose.foundation.layout.padding import androidx.compose.runtime.Composable import androidx.compose.runtime.collectAsState import androidx.compose.runtime.getValue import androidx.compose.runtime.remember import androidx.compose.ui.Modifier import androidx.compose.ui.unit.dp import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EngineConfiguration import ly.img.editor.core.component.CanvasMenu import ly.img.editor.core.component.CanvasMenu.Companion.DefaultDecoration import ly.img.editor.rememberForDesign import ly.img.engine.DesignBlockType // Add this composable to your NavHost @Composable fun SimpleCanvasMenuSolution(navController: NavHostController) { val engineConfiguration = EngineConfiguration.rememberForDesign( license = "", // pass null or empty for evaluation mode with watermark ) val editorConfiguration = EditorConfiguration.rememberForDesign( canvasMenu = { CanvasMenu.remember( // Implementation is too large, check the implementation of CanvasMenu.defaultScope scope = CanvasMenu.defaultScope, visible = { val editorState by editorContext.state.collectAsState() remember(this, editorState) { editorState.isTouchActive.not() && editorState.activeSheet == null && editorContext.safeSelection != null && editorContext.selection.type != DesignBlockType.Page && editorContext.selection.type != DesignBlockType.Audio && editorContext.engine.editor.getEditMode() != "Text" && editorContext.isScenePlaying.not() && editorContext.selection.isVisibleAtCurrentPlaybackTime } }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, // Implementation is too large, check the implementation of CanvasMenu.DefaultDecoration decoration = { DefaultDecoration { it() } }, listBuilder = CanvasMenu.ListBuilder.remember(), // default value is { it() } itemDecoration = { Box(modifier = Modifier.padding(2.dp)) { it() } }, ) }, ) DesignEditor( engineConfiguration = engineConfiguration, editorConfiguration = editorConfiguration, ) { // You can set result here navController.popBackStack() } } ``` ```kotlin file=@cesdk_android_examples/editor-guides-configuration-canvas-menu/CanvasMenuListBuilders.kt reference-only import androidx.compose.runtime.Composable import ly.img.editor.core.component.CanvasMenu import ly.img.editor.core.component.rememberBringForward import ly.img.editor.core.component.rememberDelete import ly.img.editor.core.component.rememberDuplicate import ly.img.editor.core.component.rememberSelectGroup import ly.img.editor.core.component.rememberSendBackward @Composable fun CanvasMenu.ListBuilder.remember() = CanvasMenu.ListBuilder.remember { add { CanvasMenu.Button.rememberSelectGroup() } add { CanvasMenu.Divider.remember(visible = { editorContext.isSelectionInGroup }) } add { CanvasMenu.Button.rememberBringForward() } add { CanvasMenu.Button.rememberSendBackward() } add { CanvasMenu.Divider.remember(visible = { editorContext.canSelectionMove }) } add { CanvasMenu.Button.rememberDuplicate() } add { CanvasMenu.Button.rememberDelete() } } ``` ```kotlin file=@cesdk_android_examples/editor-guides-configuration-canvas-menu/ModifyListBuilderCanvasMenuSolution.kt reference-only import androidx.compose.runtime.Composable import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EngineConfiguration import ly.img.editor.core.component.CanvasMenu import ly.img.editor.core.component.EditorComponent.ListBuilder.Companion.modify import ly.img.editor.core.component.EditorComponentId import ly.img.editor.core.component.bringForward import ly.img.editor.core.component.delete import ly.img.editor.core.component.duplicate import ly.img.editor.core.component.rememberDuplicate import ly.img.editor.core.component.sendBackward import ly.img.editor.core.iconpack.IconPack import ly.img.editor.core.iconpack.Music import ly.img.editor.rememberForDesign // Add this composable to your NavHost @Composable fun ModifyListBuilderCanvasMenuSolution(navController: NavHostController) { val engineConfiguration = EngineConfiguration.rememberForDesign( license = "", // pass null or empty for evaluation mode with watermark ) val editorConfiguration = EditorConfiguration.rememberForDesign( canvasMenu = { CanvasMenu.remember( listBuilder = CanvasMenu.ListBuilder.remember().modify { addFirst { CanvasMenu.Button.remember( id = EditorComponentId("my.package.canvasMenu.button.first"), vectorIcon = null, text = { "First Button" }, onClick = {}, ) } addLast { CanvasMenu.Button.remember( id = EditorComponentId("my.package.canvasMenu.button.last"), vectorIcon = null, text = { "Last Button" }, onClick = {}, ) } addAfter(id = CanvasMenu.Button.Id.bringForward) { CanvasMenu.Button.remember( id = EditorComponentId("my.package.canvasMenu.button.afterBringForward"), vectorIcon = null, text = { "After Bring Forward" }, onClick = {}, ) } addBefore(id = CanvasMenu.Button.Id.sendBackward) { CanvasMenu.Button.remember( id = EditorComponentId("my.package.canvasMenu.button.beforeSendBackward"), vectorIcon = null, text = { "Before Send Backward" }, onClick = {}, ) } replace(id = CanvasMenu.Button.Id.duplicate) { // Note that it can be replaced with a component that has a different id. CanvasMenu.Button.rememberDuplicate( vectorIcon = { IconPack.Music }, ) } remove(id = CanvasMenu.Button.Id.delete) }, ) }, ) DesignEditor( engineConfiguration = engineConfiguration, editorConfiguration = editorConfiguration, ) { // You can set result here navController.popBackStack() } } ``` ```kotlin file=@cesdk_android_examples/editor-guides-configuration-canvas-menu/CanvasMenuItems.kt reference-only import android.widget.Toast import androidx.compose.animation.EnterTransition import androidx.compose.animation.ExitTransition import androidx.compose.foundation.clickable import androidx.compose.foundation.layout.Box import androidx.compose.foundation.layout.fillMaxHeight import androidx.compose.foundation.layout.padding import androidx.compose.foundation.layout.size import androidx.compose.material3.Icon import androidx.compose.material3.MaterialTheme import androidx.compose.material3.Surface import androidx.compose.material3.Text import androidx.compose.runtime.Composable import androidx.compose.runtime.remember import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.unit.dp import ly.img.editor.ShowLoading import ly.img.editor.core.LocalEditorScope import ly.img.editor.core.component.CanvasMenu import ly.img.editor.core.component.EditorComponentId import ly.img.editor.core.event.EditorEvent import ly.img.editor.core.iconpack.IconPack import ly.img.editor.core.iconpack.Music import ly.img.editor.core.sheet.SheetType @Composable fun rememberCanvasMenuButton() = CanvasMenu.Button.remember( id = EditorComponentId("my.package.canvasMenu.button.newButton"), scope = LocalEditorScope.current.run { remember(this) { CanvasMenu.ButtonScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, // default value is { it() } decoration = { Surface(color = MaterialTheme.colorScheme.background) { it() } }, onClick = { editorContext.eventHandler.send(EditorEvent.Sheet.Open(SheetType.Volume())) }, // default value is null icon = { Icon( imageVector = IconPack.Music, contentDescription = null, ) }, // default value is null text = { Text( text = "Hello World", ) }, enabled = { true }, ) @Composable fun rememberCanvasMenuButtonSimpleOverload() = CanvasMenu.Button.remember( id = EditorComponentId("my.package.canvasMenu.button.newButton"), scope = LocalEditorScope.current.run { remember(this) { CanvasMenu.ButtonScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, decoration = { Surface(color = MaterialTheme.colorScheme.background) { it() } }, onClick = { editorContext.eventHandler.send(ShowLoading) }, vectorIcon = { IconPack.Music }, // default value is null text = { "Hello World" }, // default value is null tint = null, enabled = { true }, contentDescription = null, ) @Composable fun rememberCanvasMenuDivider() = CanvasMenu.Divider.remember( scope = LocalEditorScope.current.run { remember(this) { CanvasMenu.DividerScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, decoration = { it() }, modifier = { remember(this) { Modifier .padding(horizontal = 8.dp) .size(width = 1.dp, height = 24.dp) } }, ) @Composable fun rememberCanvasMenuCustomItem() = CanvasMenu.Custom.remember( id = EditorComponentId("my.package.canvasMenu.newCustomItem"), scope = LocalEditorScope.current.run { remember(this) { CanvasMenu.ItemScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, ) { Box( modifier = Modifier .fillMaxHeight() .clickable { Toast .makeText(editorContext.activity, "Hello World Clicked!", Toast.LENGTH_SHORT) .show() }, ) { Text( modifier = Modifier.align(Alignment.Center), text = "Hello World", ) } } ``` The canvas menu provides immediate access to frequently-used actions when you select a design element, offering operations like duplicate, delete, layer reordering, and grouping controls directly on the canvas. This guide shows you how to customize these contextual actions to streamline your users' editing workflow and match your app's feature priorities. While examples use the Design Editor, the same configuration principles apply to all [editor solutions](https://img.ly/docs/cesdk/android/prebuilt-solutions-d0ed07/). Explore a complete code sample on [GitHub](https://github.com/imgly/cesdk-android-examples/tree/v$UBQ_VERSION$/editor-guides-configuration-canvas-menu). ## Canvas Menu Architecture  The canvas menu displays horizontally when a design element is selected, offering quick access to editing actions relevant to that element type. **Key Components:** - **`CanvasMenu.Item`** - Abstract class that all canvas menu items inherit from - **`CanvasMenu.Button`** - Pre-built button implementation with icon and text - **`CanvasMenu.Divider`** - Visual separator between menu groups - **`CanvasMenu.Custom`** - Fully custom component for arbitrary content rendering - **`CanvasMenu.Scope`** - Provides access to the engine, event handler, and selected element ## Configuration Canvas menu customization is part of the `EditorConfiguration`, therefore, in order to configure the canvas menu we need to configure the `EditorConfiguration`. Below you can find the list of available configurations of the canvas menu. To demonstrate the default values, all parameters are assigned to their default values. **Available configuration parameters:** - **`scope`** - the scope of this component. Every new value will trigger recomposition of all the lambda parameters below. If you need to access `EditorScope` to construct the scope, use `LocalEditorScope`. Consider using Compose `State` objects in the lambda parameters below for granular recompositions over updating the scope, since scope change triggers full recomposition of the canvas menu. Prefer updating individual `CanvasMenu.Item`s over updating the whole canvas menu. Ideally, scope should be updated when the parent scope (scope of the parent component) is updated and when you want to observe changes from the `Engine`. By default, the scope is updated when the parent scope (accessed via `LocalEditorScope`) is updated, when selection is changed to a different design block (or unselected), and when the parent of the currently selected design block is changed to a different design block. - **`visible`** - Control canvas menu visibility based on selection state and editor conditions. By default the value is true when a design block is selected, it is not part of a group, canvas is not moving (finger is not on canvas), selected design block does not have a type `DesignBlockType.Audio` or `DesignBlockType.Page`, no sheet is displayed currently and the keyboard is not visible. In addition, selected design block should be visible at current playback time and containing scene should be on pause if design block is selected in a video scene. - **`enterTransition`** - Animation for when the canvas menu appears. Default value is always no enter transition. - **`exitTransition`** - Animation for when the canvas menu disappears. Default value is always no exit transition. - **`decoration`** - Apply custom styling like background, shadows, and positioning relative to the selected element. The default decoration adds background color, applies rounded corners and positions the list of items next to the selected design block. - **`listBuilder`** - Define the complete list of canvas menu items and their order. Items are only displayed when `visible` returns `true`. - **`itemDecoration`** - decoration of the items in the canvas menu. Useful when you want to add custom background, foreground, shadow, paddings etc to the items. Prefer using this decoration when you want to apply the same decoration to all the items, otherwise set decoration to individual items. Default value is always no decoration. ```kotlin highlight-canvasMenuConfiguration val editorConfiguration = EditorConfiguration.rememberForDesign( canvasMenu = { CanvasMenu.remember( // Implementation is too large, check the implementation of CanvasMenu.defaultScope scope = CanvasMenu.defaultScope, visible = { val editorState by editorContext.state.collectAsState() remember(this, editorState) { editorState.isTouchActive.not() && editorState.activeSheet == null && editorContext.safeSelection != null && editorContext.selection.type != DesignBlockType.Page && editorContext.selection.type != DesignBlockType.Audio && editorContext.engine.editor.getEditMode() != "Text" && editorContext.isScenePlaying.not() && editorContext.selection.isVisibleAtCurrentPlaybackTime } }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, // Implementation is too large, check the implementation of CanvasMenu.DefaultDecoration decoration = { DefaultDecoration { it() } }, listBuilder = CanvasMenu.ListBuilder.remember(), // default value is { it() } itemDecoration = { Box(modifier = Modifier.padding(2.dp)) { it() } }, ) }, ) ``` ### ListBuilder Configuration You can configure the complete item list or modify the default items using two main approaches: **Available approaches:** - **`CanvasMenu.ListBuilder.remember()`** - Define the complete list of canvas menu items from scratch. Use this when you want full control over the canvas menu configuration. - **`CanvasMenu.ListBuilder.remember().modify()`** - Modify the default item list by adding, replacing, or removing specific items without rebuilding the entire configuration. Use this when you want to keep most defaults but make targeted changes. The `CanvasMenu.Scope` provides access to the engine, event handler, and selected element state. Use this for advanced customization logic and to maintain consistency with the current editor context. ### Default Canvas Menu Items The default configuration includes essential editing actions with logical grouping: ```kotlin highlight-listBuilders @Composable fun CanvasMenu.ListBuilder.remember() = CanvasMenu.ListBuilder.remember { add { CanvasMenu.Button.rememberSelectGroup() } add { CanvasMenu.Divider.remember(visible = { editorContext.isSelectionInGroup }) } add { CanvasMenu.Button.rememberBringForward() } add { CanvasMenu.Button.rememberSendBackward() } add { CanvasMenu.Divider.remember(visible = { editorContext.canSelectionMove }) } add { CanvasMenu.Button.rememberDuplicate() } add { CanvasMenu.Button.rememberDelete() } } ``` ### Modify Canvas Menu Items Use the `modify` function to adjust the default item list without rebuilding the entire configuration: ```kotlin highlight-modifyListBuilderSignature listBuilder = CanvasMenu.ListBuilder.remember().modify { ``` **Available modification operations:** - `addFirst` - prepends a new item at the beginning: ```kotlin highlight-modifyListBuilder-addFirst addFirst { CanvasMenu.Button.remember( id = EditorComponentId("my.package.canvasMenu.button.first"), vectorIcon = null, text = { "First Button" }, onClick = {}, ) } ``` - `addLast` - appends a new item at the end: ```kotlin highlight-modifyListBuilder-addLast addLast { CanvasMenu.Button.remember( id = EditorComponentId("my.package.canvasMenu.button.last"), vectorIcon = null, text = { "Last Button" }, onClick = {}, ) } ``` - `addAfter` - adds a new item right after a specific item: ```kotlin highlight-modifyListBuilder-addAfter addAfter(id = CanvasMenu.Button.Id.bringForward) { CanvasMenu.Button.remember( id = EditorComponentId("my.package.canvasMenu.button.afterBringForward"), vectorIcon = null, text = { "After Bring Forward" }, onClick = {}, ) } ``` - `addBefore` - adds a new item right before a specific item: ```kotlin highlight-modifyListBuilder-addBefore addBefore(id = CanvasMenu.Button.Id.sendBackward) { CanvasMenu.Button.remember( id = EditorComponentId("my.package.canvasMenu.button.beforeSendBackward"), vectorIcon = null, text = { "Before Send Backward" }, onClick = {}, ) } ``` - `replace` - replaces an existing item with a new item: ```kotlin highlight-modifyListBuilder-replace replace(id = CanvasMenu.Button.Id.duplicate) { // Note that it can be replaced with a component that has a different id. CanvasMenu.Button.rememberDuplicate( vectorIcon = { IconPack.Music }, ) } ``` - `remove` - removes an existing item: ```kotlin highlight-modifyListBuilder-remove remove(id = CanvasMenu.Button.Id.delete) ``` > **Note:** **Warning** Note that the order of items may change between editor versions, > therefore `modify` must be used with care. Consider creating a new builder if > you want to have strict ordering between different editor versions. ## CanvasMenu.Item Configuration Each `CanvasMenu.Item` is an `EditorComponent`. Its `id` must be unique which is a requirement for proper component management. You have multiple options for creating canvas menu items, from simple predefined buttons to fully custom implementations. ### Use Predefined Buttons Start with predefined buttons which are provided as composable functions. All [available predefined buttons are listed below](https://img.ly/docs/cesdk/android/user-interface/customization/canvas-menu-0d2b5b/#list-of-available-canvasmenubuttons). ### Create New Buttons Create custom buttons when predefined options don't meet your needs: ```kotlin highlight-canvasMenuItems-newButton @Composable fun rememberCanvasMenuButton() = CanvasMenu.Button.remember( id = EditorComponentId("my.package.canvasMenu.button.newButton"), scope = LocalEditorScope.current.run { remember(this) { CanvasMenu.ButtonScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, // default value is { it() } decoration = { Surface(color = MaterialTheme.colorScheme.background) { it() } }, onClick = { editorContext.eventHandler.send(EditorEvent.Sheet.Open(SheetType.Volume())) }, // default value is null icon = { Icon( imageVector = IconPack.Music, contentDescription = null, ) }, // default value is null text = { Text( text = "Hello World", ) }, enabled = { true }, ) ``` **Required and optional parameters:** - `id` - the id of the button. Note that it is highly recommended that every unique `EditorComponent` has a unique id. Parameter does not have a default value. - `scope` - the scope of this component. Every new value will trigger recomposition of all the lambda parameters below. If you need to access `EditorScope` to construct the scope, use `LocalEditorScope`. Consider using Compose `State` objects in the lambda parameters below for granular recompositions over updating the scope, since scope change triggers full recomposition of the button. Ideally, scope should be updated when the parent scope (scope of the parent component `CanvasMenu` - `CanvasMenu.Scope`) is updated and when you want to observe changes from the `Engine`. By default the scope is updated only when the parent component scope (`CanvasMenu.scope`, accessed via `LocalEditorScope`) is updated. - `visible` - whether the button should be visible. Default value is always true. - `enterTransition` - transition of the button when it enters the parent composable. Default value is always no enter transition. - `exitTransition` - transition of the button when it exits the parent composable. Default value is always no exit transition. - `decoration` - decoration of the button. Useful when you want to add custom background, foreground, shadow, paddings etc. Default value is always no decoration. - `onClick` - the callback that is invoked when the button is clicked. Parameter does not have a default value. - `icon` - the icon content of the button. If null, it will not be rendered. Default value is null. - `text` - the text content of the button. If null, it will not be rendered. Default value is null. - `tint` - the tint color of the content. If null, then no tint is applied. Default value is null. - `enabled` - whether the button is enabled. Default value is always true. Other than the main `CanvasMenu.Button.remember` function, there is one more convenience overload that has three differences: 1. `icon` is replaced with `vectorIcon` lambda, that returns `VectorIcon` instead of drawing the icon content. 2. `text` is replaced with `text` lambda, that returns `String` instead of drawing the text content. 3. An extra parameter `contentDescription` is added that is used by accessibility services to describe what the button does. Note that it is not required to provide value when `text` is not null, since its value will be used by accessibility services, however having both `text` and `contentDescription` as null will cause a crash. ### Create Dividers Use dividers to visually separate groups of related actions: ```kotlin highlight-canvasMenuItems-newDivider @Composable fun rememberCanvasMenuDivider() = CanvasMenu.Divider.remember( scope = LocalEditorScope.current.run { remember(this) { CanvasMenu.DividerScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, decoration = { it() }, modifier = { remember(this) { Modifier .padding(horizontal = 8.dp) .size(width = 1.dp, height = 24.dp) } }, ) ``` **Required and optional parameters:** - `scope` - the scope of this component. Every new value will trigger recomposition of all the lambda parameters below. If you need to access `EditorScope` to construct the scope, use `LocalEditorScope`. Consider using Compose `State` objects in the lambda parameters below for granular recompositions over updating the scope, since scope change triggers full recomposition of the divider. Ideally, scope should be updated when the parent scope (scope of the parent component `CanvasMenu` - `CanvasMenu.Scope`) is updated and when you want to observe changes from the `Engine`. Parameter does not have a default value. - `visible` - whether the divider should be visible. Default value is always true. - `enterTransition` - transition of the divider when it enters the parent composable. Default value is always no enter transition. - `exitTransition` - transition of the divider when it exits the parent composable. Default value is always no exit transition. - `decoration` - decoration of the divider. Useful when you want to add custom background, foreground, shadow, paddings etc. Default value is always no decoration. - `modifier` - the modifier of the divider. Default value is always a `Modifier` that sets size and paddings to the divider. ### Create Custom Items For completely custom implementations, use `CanvasMenu.Custom` to render arbitrary content: ```kotlin highlight-canvasMenuItems-newCustomItem @Composable fun rememberCanvasMenuCustomItem() = CanvasMenu.Custom.remember( id = EditorComponentId("my.package.canvasMenu.newCustomItem"), scope = LocalEditorScope.current.run { remember(this) { CanvasMenu.ItemScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, ) { Box( modifier = Modifier .fillMaxHeight() .clickable { Toast .makeText(editorContext.activity, "Hello World Clicked!", Toast.LENGTH_SHORT) .show() }, ) { Text( modifier = Modifier.align(Alignment.Center), text = "Hello World", ) } } ``` **Required and optional parameters:** - `id` - the unique id of the custom item. Note that it is highly recommended that every unique `EditorComponent` has a unique id. Parameter does not have a default value. - `scope` - the scope of this component. Every new value will trigger recomposition of all the lambda parameters below. If you need to access `EditorScope` to construct the scope, use `LocalEditorScope`. Consider using Compose `State` objects in the lambda parameters below for granular recompositions over updating the scope, since scope change triggers full recomposition of the custom item. Ideally, scope should be updated when the parent scope (scope of the parent component `CanvasMenu` - `CanvasMenu.Scope`) is updated and when you want to observe changes from the `Engine`. Parameter does not have a default value. - `visible` - whether the custom item should be visible. Default value is always true. - `enterTransition` - transition of the custom item when it enters the parent composable. Default value is always no enter transition. - `exitTransition` - transition of the custom item when it exits the parent composable. Default value is always no exit transition. - `content` - the content of the custom item. You are responsible for drawing it, handling clicks etc. Parameter does not have a default value. ### List of Available CanvasMenu.Buttons All predefined buttons are available as composable functions in the `CanvasMenu.Button` namespace. Each function returns a `CanvasMenu.Button` with default parameters that you can customize as shown in the [Create New Buttons](https://img.ly/docs/cesdk/android/user-interface/customization/canvas-menu-0d2b5b/#create-new-buttons) section. | Button | ID | Description | | ---------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `CanvasMenu.Button.rememberBringForward` | `CanvasMenu.Button.Id.bringForward` | Brings forward currently selected design block via `EditorEvent.Selection.BringForward`. | | `CanvasMenu.Button.rememberSendBackward` | `CanvasMenu.Button.Id.sendBackward` | Sends backward currently selected design block via `EditorEvent.Selection.SendBackward`. | | `CanvasMenu.Button.rememberDuplicate` | `CanvasMenu.Button.Id.duplicate` | Duplicates currently selected design block via `EditorEvent.Selection.Duplicate`. | | `CanvasMenu.Button.rememberDelete` | `CanvasMenu.Button.Id.delete` | Deletes currently selected design block via `EditorEvent.Selection.Delete`. | | `CanvasMenu.Button.rememberSelectGroup` | `CanvasMenu.Button.Id.selectGroup` | Selects the group design block that contains the currently selected design block via `EditorEvent.Selection.SelectGroup`. | --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Crop Presets" description: "Define crop presets settings for your design." platform: android url: "https://img.ly/docs/cesdk/android/user-interface/customization/crop-presets-f94f26/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [User Interface](https://img.ly/docs/cesdk/android/user-interface-5a089a/) > [Customization](https://img.ly/docs/cesdk/android/user-interface/customization-72b2f8/) > [Crop Presets](https://img.ly/docs/cesdk/android/user-interface/customization/crop-presets-f94f26/) --- By default, the CreativeEditor SDK ships with an extensive list of commonly used crop presets, as shown below:  The CE.SDK can be configured with a series of crop presets by updating the `content.json` from the default asset sources - `ly.img.crop.presets` for fixed aspect ratio assets and `ly.img.page.presets` for fixed size assets - on your CDN. For further reference, [please take a look at the "Serve Assets" section here.](https://img.ly/docs/cesdk/android/serve-assets-b0827c/) To enable the CE.SDK defaults enable our default asset sources by using `addDefaultAssetSources`. ```kotlin val baseUri = Uri.parse("YOUR_CDN_URL") engine.addDefaultAssetSources(baseUri) ``` ## Configuring Custom Crop Presets When overriding the `content.json` with your custom crop presets each of the assets in the asset source must define a value for its `payload.transformPreset` property. ### Fixed Aspect Ratio When a fixed aspect ratio preset is applied it will resize the crop frame based on the `width` and `height` values provided. On Android, the fixed aspect ratio assets will be automatically rendered based on the dimensions and therefore do not need a separate icon. ```json { "id": "aspect-ratio-9-16", "label": { "en": "9:16", "de": "9:16" }, "payload": { "transformPreset": { "type": "FixedAspectRatio", "width": 9, "height": 16 } }, "groups": ["fixed-ratio"] } ``` - `type` - specifies the preset type. ```json "type": "FixedAspectRatio" ``` - `width` - specifies the width of the crop frame. ```json "width": 16 ``` - `height` - specifies the height of the crop frame. ```json "height": 9 ``` ### Free Aspect Ratio When a free aspect ratio preset is applied it will enable the side-handles of the crop frame. ```json { "id": "aspect-ratio-free", "label": { "en": "Free", "de": "Frei" }, "payload": { "transformPreset": { "type": "FreeAspectRatio" } }, "groups": ["fixed-ratio"] } ``` - `type` - specifies the preset type. ```json "type": "FreeAspectRatio" ``` ### Fixed Size When a fixed size preset is applied, the selected block will be resized to the specified `width` and `height`. Unlike assets with a fixed aspect ratio, this type of asset requires you to provide an icon. ```json { "id": "page-sizes-instagram-square", "label": { "en": "Square Post (1:1)", "de": "Quadratischer Post (1:1)" }, "meta": { "thumbUri": "{{base_url}}/ly.img.page.presets/thumbnails/instagram/ig-square.png" }, "payload": { "transformPreset": { "type": "FixedSize", "width": 1080, "height": 1080, "designUnit": "Pixel" } }, "groups": ["instagram"] } ``` - `type` - specifies the preset type. ```json "type": "FixedSize" ``` - `width` - specifies the width of the page in the specified design unit. ```json "width": 1280 ``` - `height` specifies the height of the page in the specified design unit. ```json "height": 720 ``` - `unit` describes unit in which `width` and `height` are specified. This can either be `Millimeter`, `Inch` or `Pixel`. ```json "designUnit": "Pixel" ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Dock" description: "Configure the dock area to show or hide tools, panels, or quick access actions." platform: android url: "https://img.ly/docs/cesdk/android/user-interface/customization/dock-cb916c/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [User Interface](https://img.ly/docs/cesdk/android/user-interface-5a089a/) > [Customization](https://img.ly/docs/cesdk/android/user-interface/customization-72b2f8/) > [Dock](https://img.ly/docs/cesdk/android/user-interface/customization/dock-cb916c/) --- ```kotlin file=@cesdk_android_examples/editor-guides-configuration-dock/SimpleDockSolution.kt reference-only import androidx.compose.animation.EnterTransition import androidx.compose.animation.ExitTransition import androidx.compose.foundation.background import androidx.compose.foundation.layout.Arrangement import androidx.compose.foundation.layout.Box import androidx.compose.foundation.layout.fillMaxWidth import androidx.compose.foundation.layout.padding import androidx.compose.material3.MaterialTheme import androidx.compose.runtime.Composable import androidx.compose.runtime.remember import androidx.compose.ui.Modifier import androidx.compose.ui.unit.dp import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EngineConfiguration import ly.img.editor.core.LocalEditorScope import ly.img.editor.core.component.Dock import ly.img.editor.core.theme.surface1 import ly.img.editor.rememberForDesign // Add this composable to your NavHost @Composable fun SimpleDockSolution(navController: NavHostController) { val engineConfiguration = EngineConfiguration.rememberForDesign( license = null, // evaluation mode with watermark ) val editorConfiguration = EditorConfiguration.rememberForDesign( dock = { Dock.remember( scope = LocalEditorScope.current.run { remember(this) { Dock.Scope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, decoration = { // Also available via Dock.DefaultDecoration Box( modifier = Modifier .fillMaxWidth() .background(MaterialTheme.colorScheme.surface1.copy(alpha = 0.95f)) .padding(vertical = 10.dp), ) { it() } }, listBuilder = Dock.ListBuilder.remember { }, horizontalArrangement = { Arrangement.SpaceEvenly }, // default value is { it() } itemDecoration = { Box(modifier = Modifier.padding(2.dp)) { it() } }, ) }, ) DesignEditor( engineConfiguration = engineConfiguration, editorConfiguration = editorConfiguration, ) { // You can set result here navController.popBackStack() } } ``` ```kotlin file=@cesdk_android_examples/editor-guides-configuration-dock/DockListBuilders.kt reference-only import androidx.compose.runtime.Composable import ly.img.camera.core.CaptureVideo import ly.img.editor.core.component.Dock import ly.img.editor.core.component.rememberAdjustments import ly.img.editor.core.component.rememberAudiosLibrary import ly.img.editor.core.component.rememberBlur import ly.img.editor.core.component.rememberCrop import ly.img.editor.core.component.rememberEffect import ly.img.editor.core.component.rememberElementsLibrary import ly.img.editor.core.component.rememberFilter import ly.img.editor.core.component.rememberImagesLibrary import ly.img.editor.core.component.rememberImglyCamera import ly.img.editor.core.component.rememberOverlaysLibrary import ly.img.editor.core.component.rememberReorder import ly.img.editor.core.component.rememberShapesLibrary import ly.img.editor.core.component.rememberStickersLibrary import ly.img.editor.core.component.rememberSystemCamera import ly.img.editor.core.component.rememberSystemGallery import ly.img.editor.core.component.rememberTextLibrary @Composable fun Dock.ListBuilder.rememberForDesign() = Dock.ListBuilder.remember { add { Dock.Button.rememberElementsLibrary() } add { Dock.Button.rememberSystemGallery() } add { Dock.Button.rememberSystemCamera() } add { Dock.Button.rememberImagesLibrary() } add { Dock.Button.rememberTextLibrary() } add { Dock.Button.rememberShapesLibrary() } add { Dock.Button.rememberStickersLibrary() } } @Composable fun Dock.ListBuilder.rememberForPhoto() = Dock.ListBuilder.remember { add { Dock.Button.rememberAdjustments() } add { Dock.Button.rememberFilter() } add { Dock.Button.rememberEffect() } add { Dock.Button.rememberBlur() } add { Dock.Button.rememberCrop() } add { Dock.Button.rememberTextLibrary() } add { Dock.Button.rememberShapesLibrary() } add { Dock.Button.rememberStickersLibrary() } } @Composable fun Dock.ListBuilder.rememberForVideo() = Dock.ListBuilder.remember { add { Dock.Button.rememberSystemGallery() } add { /* Make sure to add the gradle dependency of our camera library if you want to use the [rememberImglyCamera] button: implementation "ly.img:camera:". If the dependency is missing, then [rememberSystemCamera] is used. */ val isImglyCameraAvailable = androidx.compose.runtime.remember { runCatching { CaptureVideo() }.isSuccess } if (isImglyCameraAvailable) { Dock.Button.rememberImglyCamera() } else { Dock.Button.rememberSystemCamera() } } add { Dock.Button.rememberOverlaysLibrary() } add { Dock.Button.rememberTextLibrary() } add { Dock.Button.rememberStickersLibrary() } add { Dock.Button.rememberAudiosLibrary() } add { Dock.Button.rememberReorder() } } ``` ```kotlin file=@cesdk_android_examples/editor-guides-configuration-dock/ModifyListBuilderDockSolution.kt reference-only import androidx.compose.runtime.Composable import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EngineConfiguration import ly.img.editor.core.component.Dock import ly.img.editor.core.component.EditorComponent.ListBuilder.Companion.modify import ly.img.editor.core.component.EditorComponentId import ly.img.editor.core.component.rememberForDesign import ly.img.editor.core.component.shapesLibrary import ly.img.editor.core.component.systemCamera import ly.img.editor.core.component.systemGallery import ly.img.editor.core.component.textLibrary import ly.img.editor.rememberForDesign // Add this composable to your NavHost @Composable fun ModifyListBuilderDockSolution(navController: NavHostController) { val engineConfiguration = EngineConfiguration.rememberForDesign( license = null, // evaluation mode with watermark ) val editorConfiguration = EditorConfiguration.rememberForDesign( dock = { Dock.remember( listBuilder = Dock.ListBuilder.rememberForDesign().modify { addFirst { Dock.Button.remember( id = EditorComponentId("my.package.dock.button.first"), vectorIcon = null, text = { "First Button" }, onClick = {}, ) } addLast { Dock.Button.remember( id = EditorComponentId("my.package.dock.button.last"), vectorIcon = null, text = { "Last Button" }, onClick = {}, ) } addAfter(id = Dock.Button.Id.systemGallery) { Dock.Button.remember( id = EditorComponentId("my.package.dock.button.afterSystemGallery"), vectorIcon = null, text = { "After System Gallery" }, onClick = {}, ) } addBefore(id = Dock.Button.Id.systemCamera) { Dock.Button.remember( id = EditorComponentId("my.package.dock.button.beforeSystemCamera"), vectorIcon = null, text = { "Before System Camera" }, onClick = {}, ) } replace(id = Dock.Button.Id.textLibrary) { Dock.Button.remember( id = EditorComponentId("my.package.dock.button.replacedTextLibrary"), vectorIcon = null, text = { "Replaced Text Library" }, onClick = {}, ) } remove(id = Dock.Button.Id.shapesLibrary) }, ) }, ) DesignEditor( engineConfiguration = engineConfiguration, editorConfiguration = editorConfiguration, ) { // You can set result here navController.popBackStack() } } ``` ```kotlin file=@cesdk_android_examples/editor-guides-configuration-dock/DockItems.kt reference-only import android.widget.Toast import androidx.compose.animation.EnterTransition import androidx.compose.animation.ExitTransition import androidx.compose.foundation.clickable import androidx.compose.foundation.layout.Box import androidx.compose.foundation.layout.fillMaxHeight import androidx.compose.material3.Icon import androidx.compose.material3.MaterialTheme import androidx.compose.material3.Surface import androidx.compose.material3.Text import androidx.compose.runtime.Composable import androidx.compose.runtime.remember import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import ly.img.editor.ShowLoading import ly.img.editor.core.LocalEditorScope import ly.img.editor.core.component.Dock import ly.img.editor.core.component.EditorComponentId import ly.img.editor.core.event.EditorEvent import ly.img.editor.core.iconpack.IconPack import ly.img.editor.core.iconpack.Music import ly.img.editor.core.sheet.SheetType @Composable fun rememberDockButton() = Dock.Button.remember( id = EditorComponentId("my.package.dock.button.newButton"), scope = LocalEditorScope.current.run { remember(this) { Dock.ButtonScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, // default value is { it() } decoration = { Surface(color = MaterialTheme.colorScheme.background) { it() } }, onClick = { editorContext.eventHandler.send(EditorEvent.Sheet.Open(SheetType.Volume())) }, // default value is null icon = { Icon( imageVector = IconPack.Music, contentDescription = null, ) }, // default value is null text = { Text( text = "Hello World", ) }, enabled = { true }, ) @Composable fun rememberDockButtonSimpleOverload() = Dock.Button.remember( id = EditorComponentId("my.package.dock.button.newButton"), scope = LocalEditorScope.current.run { remember(this) { Dock.ButtonScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, decoration = { Surface(color = MaterialTheme.colorScheme.background) { it() } }, onClick = { editorContext.eventHandler.send(ShowLoading) }, vectorIcon = { IconPack.Music }, // default value is null text = { "Hello World" }, // default value is null tint = null, enabled = { true }, contentDescription = null, ) @Composable fun rememberCustomItem() = Dock.Custom.remember( id = EditorComponentId("my.package.dock.newCustomItem"), scope = LocalEditorScope.current.run { remember(this) { Dock.ItemScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, ) { Box( modifier = Modifier .fillMaxHeight() .clickable { Toast .makeText(editorContext.activity, "Hello World Clicked!", Toast.LENGTH_SHORT) .show() }, ) { Text( modifier = Modifier.align(Alignment.Center), text = "Hello World", ) } } ``` The dock provides quick access to content libraries and editing tools, appearing at the bottom of the editor interface. This guide shows you how to customize dock items and their layout to match your app's content strategy and user workflow. While examples use the Design Editor, the same configuration principles apply to all [editor solutions](https://img.ly/docs/cesdk/android/prebuilt-solutions-d0ed07/). Explore a complete code sample on [GitHub](https://github.com/imgly/cesdk-android-examples/tree/v$UBQ_VERSION$/editor-guides-configuration-dock). ## Dock Architecture  The dock displays horizontally at the bottom of the editor and provides quick access to content libraries and editing tools. It adapts its content based on the selected editor solution. **Key Components:** - **`Dock.Item`** - Abstract class that all dock items inherit from - **`Dock.Button`** - Pre-built button implementation with icon and text - **`Dock.Custom`** - Fully custom component for arbitrary content rendering - **`Dock.Scope`** - Provides access to the engine, event handler, and editor context ## Configuration Dock customization is part of the `EditorConfiguration`, therefore, in order to configure the dock we need to configure the `EditorConfiguration`. Below you can find the list of available configurations of the dock. To demonstrate the default values, all parameters are assigned to their default values. **Available configuration parameters:** - **`scope`** - the scope of this component. Every new value will trigger recomposition of all the lambda parameters below. If you need to access `EditorScope` to construct the scope, use `LocalEditorScope`. Consider using Compose `State` objects in the lambda parameters below for granular recompositions over updating the scope, since scope change triggers full recomposition of the dock. Prefer updating individual `Dock.Item`s over updating the whole dock. Ideally, scope should be updated when the parent scope (scope of the parent component) is updated and when you want to observe changes from the `Engine`. By default the scope is updated only when the parent scope (accessed via `LocalEditorScope`) is updated. - **`visible`** - Control dock visibility. Default value is always true. - **`enterTransition`** - Animation for when the dock appears. Default value is always no enter transition. - **`exitTransition`** - Animation for when the dock disappears. Default value is always no exit transition. - **`decoration`** - Apply custom styling like background, shadows, and padding. The default decoration adds background color and applies paddings to the dock. - **`listBuilder`** - Define the complete list of dock items and their order. Items are only displayed when `visible` returns `true`. By default, `listBuilder` does not add anything to the dock. - **`horizontalArrangement`** - Layout arrangement for dock items. Controls spacing and alignment of items within the dock. Default value is `Arrangement.SpaceEvenly`. - **`itemDecoration`** - decoration of the items in the dock. Useful when you want to add custom background, foreground, shadow, paddings etc to the items. Prefer using this decoration when you want to apply the same decoration to all the items, otherwise set decoration to individual items. Default value is always no decoration. ```kotlin highlight-dockConfiguration val editorConfiguration = EditorConfiguration.rememberForDesign( dock = { Dock.remember( scope = LocalEditorScope.current.run { remember(this) { Dock.Scope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, decoration = { // Also available via Dock.DefaultDecoration Box( modifier = Modifier .fillMaxWidth() .background(MaterialTheme.colorScheme.surface1.copy(alpha = 0.95f)) .padding(vertical = 10.dp), ) { it() } }, listBuilder = Dock.ListBuilder.remember { }, horizontalArrangement = { Arrangement.SpaceEvenly }, // default value is { it() } itemDecoration = { Box(modifier = Modifier.padding(2.dp)) { it() } }, ) }, ) ``` ### ListBuilder Configuration You can configure the complete item list or modify the default items using two main approaches: **Available approaches:** - **`Dock.ListBuilder.rememberForDesign()`** - Use the recommended default configuration for your editor solution (Design, Photo, Video). Each solution has optimized defaults for its workflow. - **`Dock.ListBuilder.rememberForDesign().modify()`** - Modify the default item list by adding, replacing, or removing specific items without rebuilding the entire configuration. Use this when you want to keep most defaults but make targeted changes. The `Dock.Scope` provides access to the engine, event handler, and editor context. Use this for advanced customization logic and to maintain consistency with the current editor state. ### Default Dock Items Each editor solution has its own default dock configuration optimized for its content workflow: These are the default items recommended to be used with the Design Editor: ```kotlin highlight-listBuilders-design @Composable fun Dock.ListBuilder.rememberForDesign() = Dock.ListBuilder.remember { add { Dock.Button.rememberElementsLibrary() } add { Dock.Button.rememberSystemGallery() } add { Dock.Button.rememberSystemCamera() } add { Dock.Button.rememberImagesLibrary() } add { Dock.Button.rememberTextLibrary() } add { Dock.Button.rememberShapesLibrary() } add { Dock.Button.rememberStickersLibrary() } } ``` These are the default items recommended to be used with the Photo Editor: ```kotlin highlight-listBuilders-photo @Composable fun Dock.ListBuilder.rememberForPhoto() = Dock.ListBuilder.remember { add { Dock.Button.rememberAdjustments() } add { Dock.Button.rememberFilter() } add { Dock.Button.rememberEffect() } add { Dock.Button.rememberBlur() } add { Dock.Button.rememberCrop() } add { Dock.Button.rememberTextLibrary() } add { Dock.Button.rememberShapesLibrary() } add { Dock.Button.rememberStickersLibrary() } } ``` These are the default items recommended to be used with the Video Editor: ```kotlin highlight-listBuilders-video @Composable fun Dock.ListBuilder.rememberForVideo() = Dock.ListBuilder.remember { add { Dock.Button.rememberSystemGallery() } add { /* Make sure to add the gradle dependency of our camera library if you want to use the [rememberImglyCamera] button: implementation "ly.img:camera:". If the dependency is missing, then [rememberSystemCamera] is used. */ val isImglyCameraAvailable = androidx.compose.runtime.remember { runCatching { CaptureVideo() }.isSuccess } if (isImglyCameraAvailable) { Dock.Button.rememberImglyCamera() } else { Dock.Button.rememberSystemCamera() } } add { Dock.Button.rememberOverlaysLibrary() } add { Dock.Button.rememberTextLibrary() } add { Dock.Button.rememberStickersLibrary() } add { Dock.Button.rememberAudiosLibrary() } add { Dock.Button.rememberReorder() } } ``` ### Modify Dock Items Use the `modify` function to adjust the default item list without rebuilding the entire configuration: ```kotlin highlight-modifyListBuilderSignature listBuilder = Dock.ListBuilder.rememberForDesign().modify { ``` **Available modification operations:** - `addFirst` - prepends new `Dock.Item`: ```kotlin highlight-modifyListBuilder-addFirst addFirst { Dock.Button.remember( id = EditorComponentId("my.package.dock.button.first"), vectorIcon = null, text = { "First Button" }, onClick = {}, ) } ``` - `addLast` - appends new `Dock.Item`: ```kotlin highlight-modifyListBuilder-addLast addLast { Dock.Button.remember( id = EditorComponentId("my.package.dock.button.last"), vectorIcon = null, text = { "Last Button" }, onClick = {}, ) } ``` - `addAfter` - adds new `Dock.Item` right after the item with the provided id: ```kotlin highlight-modifyListBuilder-addAfter addAfter(id = Dock.Button.Id.systemGallery) { Dock.Button.remember( id = EditorComponentId("my.package.dock.button.afterSystemGallery"), vectorIcon = null, text = { "After System Gallery" }, onClick = {}, ) } ``` - `addBefore` - adds new `Dock.Item` right before the item with the provided id: ```kotlin highlight-modifyListBuilder-addBefore addBefore(id = Dock.Button.Id.systemCamera) { Dock.Button.remember( id = EditorComponentId("my.package.dock.button.beforeSystemCamera"), vectorIcon = null, text = { "Before System Camera" }, onClick = {}, ) } ``` - `replace` - replaces the `Dock.Item` with the provided id with new item: ```kotlin highlight-modifyListBuilder-replace replace(id = Dock.Button.Id.textLibrary) { Dock.Button.remember( id = EditorComponentId("my.package.dock.button.replacedTextLibrary"), vectorIcon = null, text = { "Replaced Text Library" }, onClick = {}, ) } ``` - `remove` - removes the `Dock.Item` with the provided id: ```kotlin highlight-modifyListBuilder-remove remove(id = Dock.Button.Id.shapesLibrary) ``` > **Note:** **Warning** Note that the order of items may change between editor versions, > therefore `modify` must be used with care. Consider creating a new builder if > you want to have strict ordering between different editor versions. ## Dock.Item Configuration Each `Dock.Item` is an `EditorComponent`. Its `id` must be unique which is a requirement for proper component management. Depending on your needs there are multiple ways to define an item. In this example, we demonstrate your options with increasing complexity. ### Use Predefined Buttons The most basic option is to use our predefined buttons which are provided as composable functions. All [available predefined buttons are listed below](https://img.ly/docs/cesdk/android/user-interface/customization/dock-cb916c/#list-of-available-dockbuttons). ### Create New Buttons If our predefined buttons don't fit your needs you can create your own: ```kotlin highlight-dockItems-newButton @Composable fun rememberDockButton() = Dock.Button.remember( id = EditorComponentId("my.package.dock.button.newButton"), scope = LocalEditorScope.current.run { remember(this) { Dock.ButtonScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, // default value is { it() } decoration = { Surface(color = MaterialTheme.colorScheme.background) { it() } }, onClick = { editorContext.eventHandler.send(EditorEvent.Sheet.Open(SheetType.Volume())) }, // default value is null icon = { Icon( imageVector = IconPack.Music, contentDescription = null, ) }, // default value is null text = { Text( text = "Hello World", ) }, enabled = { true }, ) ``` **Required and optional parameters:** - `id` - the id of the button. Note that it is highly recommended that every unique `EditorComponent` has a unique id. Parameter does not have a default value. - `scope` - the scope of this component. Every new value will trigger recomposition of all the lambda parameters below. If you need to access `EditorScope` to construct the scope, use `LocalEditorScope`. Consider using Compose `State` objects in the lambda parameters below for granular recompositions over updating the scope, since scope change triggers full recomposition of the button. Ideally, scope should be updated when the parent scope (scope of the parent component `Dock` - `Dock.Scope`) is updated and when you want to observe changes from the `Engine`. By default the scope is updated only when the parent component scope (`Dock.scope`, accessed via `LocalEditorScope`) is updated. - `visible` - whether the button should be visible. Default value is always true. - `enterTransition` - transition of the button when it enters the parent composable. Default value is always no enter transition. - `exitTransition` - transition of the button when it exits the parent composable. Default value is always no exit transition. - `decoration` - decoration of the button. Useful when you want to add custom background, foreground, shadow, paddings etc. Default value is always no decoration. - `onClick` - the callback that is invoked when the button is clicked. Parameter does not have a default value. - `icon` - the icon content of the button. If null, it will not be rendered. Default value is null. - `text` - the text content of the button. If null, it will not be rendered. Default value is null. - `tint` - the tint color of the content. If null, then no tint is applied. Default value is null. - `enabled` - whether the button is enabled. Default value is always true. Other than the main `Dock.Button.remember` function, there is one more convenience overload that has three differences: 1. `icon` is replaced with `vectorIcon` lambda, that returns `VectorIcon` instead of drawing the icon content. 2. `text` is replaced with `text` lambda, that returns `String` instead of drawing the text content. 3. An extra parameter `contentDescription` is added that is used by accessibility services to describe what the button does. Note that it is not required to provide value when `text` is not null, since its value will be used by accessibility services, however having both `text` and `contentDescription` as null will cause a crash. ### Create Custom Items For completely custom implementations, use `Dock.Custom` to render arbitrary content: ```kotlin highlight-dockItems-newCustomItem @Composable fun rememberCustomItem() = Dock.Custom.remember( id = EditorComponentId("my.package.dock.newCustomItem"), scope = LocalEditorScope.current.run { remember(this) { Dock.ItemScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, ) { Box( modifier = Modifier .fillMaxHeight() .clickable { Toast .makeText(editorContext.activity, "Hello World Clicked!", Toast.LENGTH_SHORT) .show() }, ) { Text( modifier = Modifier.align(Alignment.Center), text = "Hello World", ) } } ``` **Required and optional parameters:** - `id` - the id of the custom item. Note that it is highly recommended that every unique `EditorComponent` has a unique id. Parameter does not have a default value. - `scope` - the scope of this component. Every new value will trigger recomposition of all the lambda parameters below. If you need to access `EditorScope` to construct the scope, use `LocalEditorScope`. Consider using Compose `State` objects in the lambda parameters below for granular recompositions over updating the scope, since scope change triggers full recomposition of the custom item. Ideally, scope should be updated when the parent scope (scope of the parent component `Dock` - `Dock.Scope`) is updated and when you want to observe changes from the `Engine`. Parameter does not have a default value. - `visible` - whether the custom item should be visible. Default value is always true. - `enterTransition` - transition of the custom item when it enters the parent composable. Default value is always no enter transition. - `exitTransition` - transition of the custom item when it exits the parent composable. Default value is always no exit transition. - `content` - the content of the custom item. You are responsible for drawing it, handling clicks etc. Parameter does not have a default value. ### List of Available Dock.Buttons As you often saw in the previous sections, there are composable functions that look like this: `Dock.Button.remember{name}`. All these functions return a `Dock.Button`, they are public and can be used in your application. Note that all the parameters of these functions have default values, therefore, you do not need to provide any values, however, if you want to modify any of the parameters, it is exactly the same as described in [Create New Buttons](https://img.ly/docs/cesdk/android/user-interface/customization/dock-cb916c/#create-new-buttons) section. | Button | ID | Description | | ------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Dock.Button.rememberElementsLibrary` | `Dock.Button.Id.elementsLibrary` | Opens library sheet with elements via `EditorEvent.Sheet.Open`. By default, the `LibraryCategory` is picked from the [Asset Library](https://img.ly/docs/cesdk/android/import-media/asset-panel/customize-c9a4de/). | | `Dock.Button.rememberOverlaysLibrary` | `Dock.Button.Id.overlaysLibrary` | Opens library sheet with overlays via `EditorEvent.Sheet.Open`. By default, the `LibraryCategory` is picked from the [Asset Library](https://img.ly/docs/cesdk/android/import-media/asset-panel/customize-c9a4de/). | | `Dock.Button.rememberImagesLibrary` | `Dock.Button.Id.imagesLibrary` | Opens library sheet with images via `EditorEvent.Sheet.Open`. By default, the `LibraryCategory` is picked from the [Asset Library](https://img.ly/docs/cesdk/android/import-media/asset-panel/customize-c9a4de/). | | `Dock.Button.rememberTextLibrary` | `Dock.Button.Id.textLibrary` | Opens library sheet with text via `EditorEvent.Sheet.Open`. By default, the `LibraryCategory` is picked from the [Asset Library](https://img.ly/docs/cesdk/android/import-media/asset-panel/customize-c9a4de/). | | `Dock.Button.rememberShapesLibrary` | `Dock.Button.Id.shapesLibrary` | Opens library sheet with shapes via `EditorEvent.Sheet.Open`. By default, the `LibraryCategory` is picked from the [Asset Library](https://img.ly/docs/cesdk/android/import-media/asset-panel/customize-c9a4de/). | | `Dock.Button.rememberStickersLibrary` | `Dock.Button.Id.stickersLibrary` | Opens library sheet with stickers via `EditorEvent.Sheet.Open`. By default, the `LibraryCategory` is picked from the [Asset Library](https://img.ly/docs/cesdk/android/import-media/asset-panel/customize-c9a4de/). | | `Dock.Button.rememberAudiosLibrary` | `Dock.Button.Id.audiosLibrary` | Opens library sheet with audios via `EditorEvent.Sheet.Open`. By default, the `LibraryCategory` is picked from the [Asset Library](https://img.ly/docs/cesdk/android/import-media/asset-panel/customize-c9a4de/). | | `Dock.Button.rememberSystemGallery` | `Dock.Button.Id.systemGallery` | Opens the system gallery via `EditorEvent.LaunchContract`. | | `Dock.Button.rememberSystemCamera` | `Dock.Button.Id.systemCamera` | Opens the system camera via `EditorEvent.LaunchContract`. | | `Dock.Button.rememberImglyCamera` | `Dock.Button.Id.imglyCamera` | Opens the IMG.LY camera via `EditorEvent.LaunchContract`. Note that the button can be used only if `ly.img:camera:` dependency is added in your `build.gradle` file. For more information, check the camera [documentation](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/). | | `Dock.Button.rememberReorder` | `Dock.Button.Id.reorder` | Opens reorder sheet via `EditorEvent.Sheet.Open`. | | `Dock.Button.rememberAdjustments` | `Dock.Button.Id.adjustments` | Opens adjustment sheet via `EditorEvent.Sheet.Open`. | | `Dock.Button.rememberFilter` | `Dock.Button.Id.filter` | Opens filter sheet via `EditorEvent.Sheet.Open`. | | `Dock.Button.rememberEffect` | `Dock.Button.Id.effect` | Opens effect sheet via `EditorEvent.Sheet.Open`. | | `Dock.Button.rememberBlur` | `Dock.Button.Id.blur` | Opens blur sheet via `EditorEvent.Sheet.Open`. | | `Dock.Button.rememberCrop` | `Dock.Button.Id.crop` | Opens crop sheet via `EditorEvent.Sheet.Open`. | | `Dock.Button.rememberResizeAll` | `Dock.Button.Id.crop` | Opens resize sheet via `EditorEvent.Sheet.Open`. | --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Force Crop" description: "Apply predefined crop presets programmatically in the Android SDK." platform: android url: "https://img.ly/docs/cesdk/android/user-interface/customization/force-crop-c2854e/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [User Interface](https://img.ly/docs/cesdk/android/user-interface-5a089a/) > [Customization](https://img.ly/docs/cesdk/android/user-interface/customization-72b2f8/) > [Force Crop](https://img.ly/docs/cesdk/android/user-interface/customization/force-crop-c2854e/) --- Use the Android SDK's force crop flow by preparing (or isolating) the preset in an asset source and calling `applyForceCrop` from your editor's `onLoaded` callback. *** ## Overview Force cropping ensures that a page (or any cropable block) uses a specific aspect ratio or fixed size when the editor loads. The helper `ForceCropConfiguration` can be passed to `EngineConfiguration.rememberForPhoto` and is applied during `onLoaded`. Alternatively, you can invoke `applyForceCrop` manually in a custom `onLoaded` implementation. ```kotlin suspend fun EditorScope.applyForceCrop( block: DesignBlock, configuration: ForceCropConfiguration, ) ``` *** ## Parameters | Name | Type | Description | | ---------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `block` | `DesignBlock` | The block to which the preset should be applied. Must support cropping (pages do by default). | | `configuration` | `ForceCropConfiguration` | Describes the preset source, preset IDs, optional fallbacks, and application mode. | | `sourceId` | `String` | Asset source that stores the forced preset. | | `presetId` | `String` | Primary preset ID that should be applied. | | `presetCandidates` | `List` | Additional presets the helper can fall back to. Omit this if you only want to use a single preset. | | `mode` | `ForceCropMode` | Controls whether the crop sheet opens (`Always` / `IfNeeded`) or stays silent (`Silent`). | `ForceCropConfiguration` supports optional fallback candidates so you can reuse the same block-level heuristics on Android. *** ## Modes | Mode | Behavior | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `Silent` | Applies the preset without opening the crop UI. | | `Always` | Applies the preset and opens the crop sheet immediately. | | `IfNeeded` | Compares the preset with the current frame dimensions. The crop is applied and the sheet opens only if the ratio/size differs materially. | `ForceCropMode.IfNeeded` accepts an optional `threshold` to tweak the tolerance for aspect-ratio comparisons. *** ## Usage Example The snippet below shows how to isolate a preset, pass it into `EngineConfiguration.rememberForPhoto`, and let the SDK apply the crop during `onLoaded`. ```kotlin val forceCropConfig = ForceCropConfiguration( sourceId = "ly.img.crop.presets", presetId = "aspect-ratio-1-1", presetCandidates = listOf( ForceCropPresetCandidate( sourceId = "ly.img.crop.presets", presetId = "aspect-ratio-16-9", ), ForceCropPresetCandidate( sourceId = "ly.img.crop.presets", presetId = "aspect-ratio-9-16", ), ), mode = ForceCropMode.IfNeeded(threshold = 0.01f), ) val engineConfiguration = EngineConfiguration.rememberForPhoto( license = license, imageUri = imageUri, forceCropConfiguration = forceCropConfig, ) ``` When the editor loads, `rememberForPhoto` calls `applyForceCrop(...)` for the first page. If you prefer to control the timing yourself, switch to the generic builder and call `applyForceCrop` in your own `onLoaded` block: ```kotlin EngineConfiguration.remember( license = license, onCreate = { EditorDefaults.onCreateFromImage(editorContext.engine, imageUri, editorContext.eventHandler) }, onLoaded = { val page = editorContext.engine.scene.getPages().first() applyForceCrop(page, forceCropConfig) }, ) ``` If you prefer to keep the configuration logic decoupled from `onLoaded`, dispatch the `ApplyForceCrop` event instead: ```kotlin editorContext.eventHandler.send( ApplyForceCrop( block = page, configuration = forceCropConfig, ), ) ``` ### Isolating the Preset Ensure the user only sees the enforced preset by recreating the asset source ahead of time: ```kotlin engine.asset.removeSource("ly.img.crop.presets") engine.asset.addLocalSource("ly.img.crop.presets") engine.asset.addAssetToSource("ly.img.crop.presets", forcedPreset) ``` *** ## Behavior Details - The helper locks page resizing while the crop sheet is open and restores the previous setting when finished. - Fixed-size presets adjust the scene size and trigger a zoom recalculation automatically. - All preset candidates are fetched on the main engine thread. Missing sources or IDs are logged and ignored. - Matching logic mirrors the iOS implementation: the helper picks the preset whose ratio/size best fits the current frame, then applies it according to the selected `mode`. *** ## See Also - [Force Crop (Web)](https://img.ly/docs/cesdk/android/edit-image/transform/crop-f67a47/) - [UI Events (iOS)](https://img.ly/docs/cesdk/android/user-interface/events-514b70/) - [Asset Library](https://img.ly/docs/cesdk/android/import-media/asset-library-65d6c4/) --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Inspector Bar" description: "Customize the inspector bar for editing properties like position, color, and size." platform: android url: "https://img.ly/docs/cesdk/android/user-interface/customization/inspector-bar-8ca1cd/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [User Interface](https://img.ly/docs/cesdk/android/user-interface-5a089a/) > [Customization](https://img.ly/docs/cesdk/android/user-interface/customization-72b2f8/) > [Inspector Bar](https://img.ly/docs/cesdk/android/user-interface/customization/inspector-bar-8ca1cd/) --- ```kotlin file=@cesdk_android_examples/editor-guides-configuration-inspector-bar/SimpleInspectorBarSolution.kt reference-only import androidx.compose.animation.ExitTransition import androidx.compose.animation.core.CubicBezierEasing import androidx.compose.animation.core.tween import androidx.compose.animation.slideInHorizontally import androidx.compose.animation.slideInVertically import androidx.compose.animation.slideOutVertically import androidx.compose.foundation.layout.Arrangement import androidx.compose.foundation.layout.Box import androidx.compose.foundation.layout.padding import androidx.compose.runtime.Composable import androidx.compose.runtime.remember import androidx.compose.ui.Modifier import androidx.compose.ui.unit.dp import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EngineConfiguration import ly.img.editor.core.component.InspectorBar import ly.img.editor.core.component.InspectorBar.Companion.DefaultDecoration import ly.img.editor.rememberForDesign // Add this composable to your NavHost @Composable fun SimpleInspectorBarSolution(navController: NavHostController) { val engineConfiguration = EngineConfiguration.rememberForDesign( license = "", // pass null or empty for evaluation mode with watermark ) val editorConfiguration = EditorConfiguration.rememberForDesign( inspectorBar = { InspectorBar.remember( // Implementation is too large, check the implementation of InspectorBar.defaultScope scope = InspectorBar.defaultScope, visible = { editorContext.safeSelection != null }, // Also available via InspectorBar.defaultEnterTransition enterTransition = { remember { slideInVertically( animationSpec = tween( durationMillis = 400, easing = CubicBezierEasing(0.05f, 0.7f, 0.1f, 1f), ), initialOffsetY = { it }, ) } }, // Also available via InspectorBar.defaultExitTransition exitTransition = { remember { slideOutVertically( animationSpec = tween( durationMillis = 150, easing = CubicBezierEasing(0.3f, 0f, 0.8f, 0.15f), ), targetOffsetY = { it }, ) } }, // Implementation is too large, check the implementation of InspectorBar.DefaultDecoration decoration = { DefaultDecoration { it() } }, listBuilder = InspectorBar.ListBuilder.remember(), horizontalArrangement = { Arrangement.Start }, // Also available via InspectorBar.defaultItemsRowEnterTransition itemsRowEnterTransition = { remember { slideInHorizontally( animationSpec = tween(400, easing = CubicBezierEasing(0.05F, 0.7F, 0.1F, 1F)), initialOffsetX = { it / 3 }, ) } }, // Also available via InspectorBar.defaultItemsRowExitTransition itemsRowExitTransition = { ExitTransition.None }, // default value is { it() } itemDecoration = { Box(modifier = Modifier.padding(2.dp)) { it() } }, ) }, ) DesignEditor( engineConfiguration = engineConfiguration, editorConfiguration = editorConfiguration, ) { // You can set result here navController.popBackStack() } } ``` ```kotlin file=@cesdk_android_examples/editor-guides-configuration-inspector-bar/InspectorBarListBuilders.kt reference-only import androidx.compose.runtime.Composable import ly.img.editor.core.component.InspectorBar import ly.img.editor.core.component.rememberAdjustments import ly.img.editor.core.component.rememberBlur import ly.img.editor.core.component.rememberCrop import ly.img.editor.core.component.rememberDelete import ly.img.editor.core.component.rememberDuplicate import ly.img.editor.core.component.rememberEditText import ly.img.editor.core.component.rememberEffect import ly.img.editor.core.component.rememberEnterGroup import ly.img.editor.core.component.rememberFillStroke import ly.img.editor.core.component.rememberFilter import ly.img.editor.core.component.rememberFormatText import ly.img.editor.core.component.rememberLayer import ly.img.editor.core.component.rememberMoveAsClip import ly.img.editor.core.component.rememberMoveAsOverlay import ly.img.editor.core.component.rememberReorder import ly.img.editor.core.component.rememberReplace import ly.img.editor.core.component.rememberSelectGroup import ly.img.editor.core.component.rememberShape import ly.img.editor.core.component.rememberSplit import ly.img.editor.core.component.rememberTextBackground import ly.img.editor.core.component.rememberVolume @Composable fun InspectorBar.ListBuilder.remember() = InspectorBar.ListBuilder.remember { add { InspectorBar.Button.rememberReplace() } // Video, Image, Sticker, Audio add { InspectorBar.Button.rememberEditText() } // Text add { InspectorBar.Button.rememberFormatText() } // Text add { InspectorBar.Button.rememberFillStroke() } // Page, Video, Image, Shape, Text add { InspectorBar.Button.rememberTextBackground() } // Text add { InspectorBar.Button.rememberVolume() } // Video, Audio add { InspectorBar.Button.rememberCrop() } // Video, Image add { InspectorBar.Button.rememberAdjustments() } // Video, Image add { InspectorBar.Button.rememberFilter() } // Video, Image add { InspectorBar.Button.rememberEffect() } // Video, Image add { InspectorBar.Button.rememberBlur() } // Video, Image add { InspectorBar.Button.rememberShape() } // Video, Image, Shape add { InspectorBar.Button.rememberSelectGroup() } // Video, Image, Sticker, Shape, Text add { InspectorBar.Button.rememberEnterGroup() } // Group add { InspectorBar.Button.rememberLayer() } // Video, Image, Sticker, Shape, Text add { InspectorBar.Button.rememberSplit() } // Video, Image, Sticker, Shape, Text, Audio add { InspectorBar.Button.rememberMoveAsClip() } // Video, Image, Sticker, Shape, Text add { InspectorBar.Button.rememberMoveAsOverlay() } // Video, Image, Sticker, Shape, Text add { InspectorBar.Button.rememberReorder() } // Video, Image, Sticker, Shape, Text add { InspectorBar.Button.rememberDuplicate() } // Video, Image, Sticker, Shape, Text, Audio add { InspectorBar.Button.rememberDelete() } // Video, Image, Sticker, Shape, Text, Audio } ``` ```kotlin file=@cesdk_android_examples/editor-guides-configuration-inspector-bar/ModifyListBuilderInspectorBarSolution.kt reference-only import androidx.compose.runtime.Composable import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EngineConfiguration import ly.img.editor.core.component.EditorComponent.ListBuilder.Companion.modify import ly.img.editor.core.component.EditorComponentId import ly.img.editor.core.component.InspectorBar import ly.img.editor.core.component.crop import ly.img.editor.core.component.delete import ly.img.editor.core.component.formatText import ly.img.editor.core.component.layer import ly.img.editor.rememberForDesign // Add this composable to your NavHost @Composable fun ModifyListBuilderInspectorBarSolution(navController: NavHostController) { val engineConfiguration = EngineConfiguration.rememberForDesign( license = "", // pass null or empty for evaluation mode with watermark ) val editorConfiguration = EditorConfiguration.rememberForDesign( inspectorBar = { InspectorBar.remember( listBuilder = InspectorBar.ListBuilder.remember().modify { addFirst { InspectorBar.Button.remember( id = EditorComponentId("my.package.inspectorBar.button.first"), vectorIcon = null, text = { "First Button" }, onClick = {}, ) } addLast { InspectorBar.Button.remember( id = EditorComponentId("my.package.inspectorBar.button.last"), vectorIcon = null, text = { "Last Button" }, onClick = {}, ) } addAfter(id = InspectorBar.Button.Id.layer) { InspectorBar.Button.remember( id = EditorComponentId("my.package.inspectorBar.button.afterLayer"), vectorIcon = null, text = { "After Layer" }, onClick = {}, ) } addBefore(id = InspectorBar.Button.Id.crop) { InspectorBar.Button.remember( id = EditorComponentId("my.package.inspectorBar.button.beforeCrop"), vectorIcon = null, text = { "Before Crop" }, onClick = {}, ) } replace(id = InspectorBar.Button.Id.formatText) { InspectorBar.Button.remember( id = EditorComponentId("my.package.inspectorBar.button.replacedFormatText"), vectorIcon = null, text = { "Replaced Format Text" }, onClick = {}, ) } remove(id = InspectorBar.Button.Id.delete) }, ) }, ) DesignEditor( engineConfiguration = engineConfiguration, editorConfiguration = editorConfiguration, ) { // You can set result here navController.popBackStack() } } ``` ```kotlin file=@cesdk_android_examples/editor-guides-configuration-inspector-bar/InspectorBarItems.kt reference-only import android.widget.Toast import androidx.compose.animation.EnterTransition import androidx.compose.animation.ExitTransition import androidx.compose.foundation.clickable import androidx.compose.foundation.layout.Box import androidx.compose.foundation.layout.fillMaxHeight import androidx.compose.material3.Icon import androidx.compose.material3.MaterialTheme import androidx.compose.material3.Surface import androidx.compose.material3.Text import androidx.compose.runtime.Composable import androidx.compose.runtime.remember import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import ly.img.editor.ShowLoading import ly.img.editor.core.LocalEditorScope import ly.img.editor.core.component.EditorComponentId import ly.img.editor.core.component.InspectorBar import ly.img.editor.core.event.EditorEvent import ly.img.editor.core.iconpack.IconPack import ly.img.editor.core.iconpack.Music import ly.img.editor.core.sheet.SheetType @Composable fun rememberInspectorBarButton() = InspectorBar.Button.remember( id = EditorComponentId("my.package.inspectorBar.button.newButton"), scope = LocalEditorScope.current.run { remember(this) { InspectorBar.ButtonScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, // default value is { it() } decoration = { Surface(color = MaterialTheme.colorScheme.background) { it() } }, onClick = { editorContext.eventHandler.send(EditorEvent.Sheet.Open(SheetType.Volume())) }, // default value is null icon = { Icon( imageVector = IconPack.Music, contentDescription = null, ) }, // default value is null text = { Text( text = "Hello World", ) }, enabled = { true }, ) @Composable fun rememberInspectorBarButtonSimpleOverload() = InspectorBar.Button.remember( id = EditorComponentId("my.package.inspectorBar.button.newButton"), scope = LocalEditorScope.current.run { remember(this) { InspectorBar.ButtonScope(parentScope = this) } }, onClick = { editorContext.eventHandler.send(ShowLoading) }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, decoration = { Surface(color = MaterialTheme.colorScheme.background) { it() } }, vectorIcon = { IconPack.Music }, // default value is null text = { "Hello World" }, // default value is null tint = null, enabled = { true }, contentDescription = null, ) @Composable fun rememberInspectorBarCustomItem() = InspectorBar.Custom.remember( id = EditorComponentId("my.package.inspectorBar.newCustomItem"), scope = LocalEditorScope.current.run { remember(this) { InspectorBar.ItemScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, ) { Box( modifier = Modifier .fillMaxHeight() .clickable { Toast .makeText(editorContext.activity, "Hello World Clicked!", Toast.LENGTH_SHORT) .show() }, ) { Text( modifier = Modifier.align(Alignment.Center), text = "Hello World", ) } } ``` The inspector bar provides context-sensitive editing controls that appear when you select a design element, offering tools specific to that element type like text formatting, image adjustments, or shape properties. This guide shows you how to customize these editing controls to match your app's feature set and user experience goals. While examples use the Design Editor, the same configuration principles apply to all [editor solutions](https://img.ly/docs/cesdk/android/prebuilt-solutions-d0ed07/). Explore a complete code sample on [GitHub](https://github.com/imgly/cesdk-android-examples/tree/v$UBQ_VERSION$/editor-guides-configuration-inspector-bar). ## Inspector Bar Architecture  The inspector bar displays horizontally at the bottom when a design element is selected. It contains context-sensitive editing tools that adapt based on the selected element type (text, image, video, etc.). **Key Components:** - **`InspectorBar.Item`** - Abstract class that all inspector items inherit from - **`InspectorBar.Button`** - Pre-built button implementation with icon and text - **`InspectorBar.Custom`** - Fully custom component for arbitrary content rendering - **`InspectorBar.Scope`** - Provides access to the engine, event handler, and selected element ## Configuration Inspector bar customization is part of the `EditorConfiguration`, therefore, in order to configure the inspector bar we need to configure the `EditorConfiguration`. Below you can find the list of available configurations of the inspector bar. To demonstrate the default values, all parameters are assigned to their default values. **Available configuration parameters:** - **`scope`** - the scope of this component. Every new value will trigger recomposition of all the lambda parameters below. If you need to access `EditorScope` to construct the scope, use `LocalEditorScope`. Consider using Compose `State` objects in the lambda parameters below for granular recompositions over updating the scope, since scope change triggers full recomposition of the inspector bar. Prefer updating individual `InspectorBar.Item`s over updating the whole inspector bar. Ideally, scope should be updated when the parent scope (scope of the parent component) is updated and when you want to observe changes from the `Engine`. - **`visible`** - Control inspector bar visibility based on selection state. Default value is always true. - **`enterTransition`** - Animation for when the inspector bar appears. By default, a vertical slide in animation is used. - **`exitTransition`** - Animation for when the inspector bar disappears. By default, a vertical slide out animation is used. - **`decoration`** - Apply custom styling like background, shadows, and padding. Default value is always no decoration. - **`listBuilder`** - Define the complete list of inspector bar items and their order. Items are only displayed when `visible` returns `true`. - **`horizontalArrangement`** - Layout arrangement for inspector bar items. Controls spacing and alignment of items within the inspector bar. Default value is `Arrangement.Start`. - **`itemDecoration`** - decoration of the items in the inspector bar. Useful when you want to add custom background, foreground, shadow, paddings etc to the items. Prefer using this decoration when you want to apply the same decoration to all the items, otherwise set decoration to individual items. Default value is always no decoration. - **`itemsRowEnterTransition`** - Animation for when the items row appears. By default, a horizontal slide in animation is used. - **`itemsRowExitTransition`** - Animation for when the items row disappears. Default value is always no exit transition. ```kotlin highlight-inspectorBarConfiguration val editorConfiguration = EditorConfiguration.rememberForDesign( inspectorBar = { InspectorBar.remember( // Implementation is too large, check the implementation of InspectorBar.defaultScope scope = InspectorBar.defaultScope, visible = { editorContext.safeSelection != null }, // Also available via InspectorBar.defaultEnterTransition enterTransition = { remember { slideInVertically( animationSpec = tween( durationMillis = 400, easing = CubicBezierEasing(0.05f, 0.7f, 0.1f, 1f), ), initialOffsetY = { it }, ) } }, // Also available via InspectorBar.defaultExitTransition exitTransition = { remember { slideOutVertically( animationSpec = tween( durationMillis = 150, easing = CubicBezierEasing(0.3f, 0f, 0.8f, 0.15f), ), targetOffsetY = { it }, ) } }, // Implementation is too large, check the implementation of InspectorBar.DefaultDecoration decoration = { DefaultDecoration { it() } }, listBuilder = InspectorBar.ListBuilder.remember(), horizontalArrangement = { Arrangement.Start }, // Also available via InspectorBar.defaultItemsRowEnterTransition itemsRowEnterTransition = { remember { slideInHorizontally( animationSpec = tween(400, easing = CubicBezierEasing(0.05F, 0.7F, 0.1F, 1F)), initialOffsetX = { it / 3 }, ) } }, // Also available via InspectorBar.defaultItemsRowExitTransition itemsRowExitTransition = { ExitTransition.None }, // default value is { it() } itemDecoration = { Box(modifier = Modifier.padding(2.dp)) { it() } }, ) }, ) ``` ### ListBuilder Configuration You can configure the complete item list or modify the default items using two main approaches: **Available approaches:** - **`InspectorBar.ListBuilder.remember()`** - Define the complete list of inspector bar items from scratch. Use this when you want full control over the inspector bar configuration. - **`InspectorBar.ListBuilder.remember().modify()`** - Modify the default item list by adding, replacing, or removing specific items without rebuilding the entire configuration. Use this when you want to keep most defaults but make targeted changes. The `InspectorBar.Scope` provides access to the engine, event handler, and selected element state. Use this for advanced customization logic and to maintain consistency with the current editor context. ### Default Inspector Bar Items The default configuration includes all essential editing tools for different element types: ```kotlin highlight-listBuilders @Composable fun InspectorBar.ListBuilder.remember() = InspectorBar.ListBuilder.remember { add { InspectorBar.Button.rememberReplace() } // Video, Image, Sticker, Audio add { InspectorBar.Button.rememberEditText() } // Text add { InspectorBar.Button.rememberFormatText() } // Text add { InspectorBar.Button.rememberFillStroke() } // Page, Video, Image, Shape, Text add { InspectorBar.Button.rememberTextBackground() } // Text add { InspectorBar.Button.rememberVolume() } // Video, Audio add { InspectorBar.Button.rememberCrop() } // Video, Image add { InspectorBar.Button.rememberAdjustments() } // Video, Image add { InspectorBar.Button.rememberFilter() } // Video, Image add { InspectorBar.Button.rememberEffect() } // Video, Image add { InspectorBar.Button.rememberBlur() } // Video, Image add { InspectorBar.Button.rememberShape() } // Video, Image, Shape add { InspectorBar.Button.rememberSelectGroup() } // Video, Image, Sticker, Shape, Text add { InspectorBar.Button.rememberEnterGroup() } // Group add { InspectorBar.Button.rememberLayer() } // Video, Image, Sticker, Shape, Text add { InspectorBar.Button.rememberSplit() } // Video, Image, Sticker, Shape, Text, Audio add { InspectorBar.Button.rememberMoveAsClip() } // Video, Image, Sticker, Shape, Text add { InspectorBar.Button.rememberMoveAsOverlay() } // Video, Image, Sticker, Shape, Text add { InspectorBar.Button.rememberReorder() } // Video, Image, Sticker, Shape, Text add { InspectorBar.Button.rememberDuplicate() } // Video, Image, Sticker, Shape, Text, Audio add { InspectorBar.Button.rememberDelete() } // Video, Image, Sticker, Shape, Text, Audio } ``` ### Modify Inspector Bar Items Use the `modify` function to adjust the default item list without rebuilding the entire configuration: ```kotlin highlight-modifyListBuilderSignature listBuilder = InspectorBar.ListBuilder.remember().modify { ``` **Available modification operations:** - `addFirst` - prepends a new item at the beginning: ```kotlin highlight-modifyListBuilder-addFirst addFirst { InspectorBar.Button.remember( id = EditorComponentId("my.package.inspectorBar.button.first"), vectorIcon = null, text = { "First Button" }, onClick = {}, ) } ``` - `addLast` - appends a new item at the end: ```kotlin highlight-modifyListBuilder-addLast addLast { InspectorBar.Button.remember( id = EditorComponentId("my.package.inspectorBar.button.last"), vectorIcon = null, text = { "Last Button" }, onClick = {}, ) } ``` - `addAfter` - adds a new item right after a specific item: ```kotlin highlight-modifyListBuilder-addAfter addAfter(id = InspectorBar.Button.Id.layer) { InspectorBar.Button.remember( id = EditorComponentId("my.package.inspectorBar.button.afterLayer"), vectorIcon = null, text = { "After Layer" }, onClick = {}, ) } ``` - `addBefore` - adds a new item right before a specific item: ```kotlin highlight-modifyListBuilder-addBefore addBefore(id = InspectorBar.Button.Id.crop) { InspectorBar.Button.remember( id = EditorComponentId("my.package.inspectorBar.button.beforeCrop"), vectorIcon = null, text = { "Before Crop" }, onClick = {}, ) } ``` - `replace` - replaces an existing item with a new item: ```kotlin highlight-modifyListBuilder-replace replace(id = InspectorBar.Button.Id.formatText) { InspectorBar.Button.remember( id = EditorComponentId("my.package.inspectorBar.button.replacedFormatText"), vectorIcon = null, text = { "Replaced Format Text" }, onClick = {}, ) } ``` - `remove` - removes an existing item: ```kotlin highlight-modifyListBuilder-remove remove(id = InspectorBar.Button.Id.delete) ``` > **Note:** **Warning** Note that the order of items may change between editor versions, > therefore `modify` must be used with care. Consider creating a new builder if > you want to have strict ordering between different editor versions. ## InspectorBar.Item Configuration Each `InspectorBar.Item` is an `EditorComponent`. Its `id` must be unique which is a requirement for proper component management. You have multiple options for creating inspector bar items, from simple predefined buttons to fully custom implementations. ### Use Predefined Buttons Start with predefined buttons which are provided as composable functions. All [available predefined buttons are listed below](https://img.ly/docs/cesdk/android/user-interface/customization/inspector-bar-8ca1cd/#list-of-available-inspectorbarbuttons). ### Create New Buttons Create custom buttons when predefined options don't meet your needs: ```kotlin highlight-inspectorBarItems-newButton @Composable fun rememberInspectorBarButton() = InspectorBar.Button.remember( id = EditorComponentId("my.package.inspectorBar.button.newButton"), scope = LocalEditorScope.current.run { remember(this) { InspectorBar.ButtonScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, // default value is { it() } decoration = { Surface(color = MaterialTheme.colorScheme.background) { it() } }, onClick = { editorContext.eventHandler.send(EditorEvent.Sheet.Open(SheetType.Volume())) }, // default value is null icon = { Icon( imageVector = IconPack.Music, contentDescription = null, ) }, // default value is null text = { Text( text = "Hello World", ) }, enabled = { true }, ) ``` **Required and optional parameters:** - `id` - the id of the button. Note that it is highly recommended that every unique `EditorComponent` has a unique id. Parameter does not have a default value. - `scope` - the scope of this component. Every new value will trigger recomposition of all the lambda parameters below. If you need to access `EditorScope` to construct the scope, use `LocalEditorScope`. Consider using Compose `State` objects in the lambda parameters below for granular recompositions over updating the scope, since scope change triggers full recomposition of the button. Ideally, scope should be updated when the parent scope (scope of the parent component `InspectorBar` - `InspectorBar.Scope`) is updated and when you want to observe changes from the `Engine`. By default the scope is updated only when the parent component scope (`InspectorBar.scope`, accessed via `LocalEditorScope`) is updated. - `visible` - whether the button should be visible. Default value is always true. - `enterTransition` - transition of the button when it enters the parent composable. Default value is always no enter transition. - `exitTransition` - transition of the button when it exits the parent composable. Default value is always no exit transition. - `decoration` - decoration of the button. Useful when you want to add custom background, foreground, shadow, paddings etc. Default value is always no decoration. - `onClick` - the callback that is invoked when the button is clicked. Parameter does not have a default value. - `icon` - the icon content of the button. If null, it will not be rendered. Default value is null. - `text` - the text content of the button. If null, it will not be rendered. Default value is null. - `tint` - the tint color of the content. If null, then no tint is applied. Default value is null. - `enabled` - whether the button is enabled. Default value is always true. Other than the main `InspectorBar.Button.remember` function, there is one more convenience overload that has three differences: 1. `icon` is replaced with `vectorIcon` lambda, that returns `VectorIcon` instead of drawing the icon content. 2. `text` is replaced with `text` lambda, that returns `String` instead of drawing the text content. 3. An extra parameter `contentDescription` is added that is used by accessibility services to describe what the button does. Note that it is not required to provide value when `text` is not null, since its value will be used by accessibility services, however having both `text` and `contentDescription` as null will cause a crash. ### Create Custom Items For completely custom implementations, use `InspectorBar.Custom` to render arbitrary content: ```kotlin highlight-inspectorBarItems-newCustomItem @Composable fun rememberInspectorBarCustomItem() = InspectorBar.Custom.remember( id = EditorComponentId("my.package.inspectorBar.newCustomItem"), scope = LocalEditorScope.current.run { remember(this) { InspectorBar.ItemScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, ) { Box( modifier = Modifier .fillMaxHeight() .clickable { Toast .makeText(editorContext.activity, "Hello World Clicked!", Toast.LENGTH_SHORT) .show() }, ) { Text( modifier = Modifier.align(Alignment.Center), text = "Hello World", ) } } ``` **Required and optional parameters:** - `id` - the id of the custom item. Note that it is highly recommended that every unique `EditorComponent` has a unique id. Parameter does not have a default value. - `scope` - the scope of this component. Every new value will trigger recomposition of all the lambda parameters below. If you need to access `EditorScope` to construct the scope, use `LocalEditorScope`. Consider using Compose `State` objects in the lambda parameters below for granular recompositions over updating the scope, since scope change triggers full recomposition of the custom item. Ideally, scope should be updated when the parent scope (scope of the parent component `InspectorBar` - `InspectorBar.Scope`) is updated and when you want to observe changes from the `Engine`. Parameter does not have a default value. - `visible` - whether the custom item should be visible. Default value is always true. - `enterTransition` - transition of the custom item when it enters the parent composable. Default value is always no enter transition. - `exitTransition` - transition of the custom item when it exits the parent composable. Default value is always no exit transition. - `content` - the content of the custom item. You are responsible for drawing it, handling clicks etc. Parameter does not have a default value. ### List of Available InspectorBar.Buttons As you often saw in the previous sections, there are composable functions that look like this: `InspectorBar.Button.remember{name}`. All these functions return an `InspectorBar.Button`, they are public and can be used in your application. Note that all the parameters of these functions have default values, therefore, you do not need to provide any values, however, if you want to modify any of the parameters, it is exactly the same as described in [Create New Buttons](https://img.ly/docs/cesdk/android/user-interface/customization/inspector-bar-8ca1cd/#create-new-buttons) section. | Button | ID | Description | Renders For | | -------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | `InspectorBar.Button.rememberReplace` | `InspectorBar.Button.Id.replace` | Opens library sheet via `EditorEvent.Sheet.Open`. By default, `DesignBlockType`, `FillType` and kind of the selected design block are used to find the library in the [Asset Library](https://img.ly/docs/cesdk/android/import-media/asset-panel/customize-c9a4de/). Selected asset will replace the content of the currently selected design block. | Video, Image, Sticker, Audio | | `InspectorBar.Button.rememberEditText` | `InspectorBar.Button.Id.editText` | Enters text editing mode for the selected design block. | Text | | `InspectorBar.Button.rememberFormatText` | `InspectorBar.Button.Id.formatText` | Opens format text sheet via `EditorEvent.Sheet.Open`. | Text | | `InspectorBar.Button.rememberFillStroke` | `InspectorBar.Button.Id.fillStroke` | Opens fill & stroke sheet via `EditorEvent.Sheet.Open`. | Page, Video, Image, Shape, Text | | `InspectorBar.Button.rememberTextBackground` | `InspectorBar.Button.Id.textBackground` | Opens text background sheet via `EditorEvent.Sheet.Open`. | Text | | `InspectorBar.Button.rememberEditVoiceover` | `InspectorBar.Button.Id.editVoiceover` | Opens voiceover sheet via `EditorEvent.Sheet.Open`. | Video, Audio, Voiceover | | `InspectorBar.Button.rememberVolume` | `InspectorBar.Button.Id.volume` | Opens volume sheet via `EditorEvent.Sheet.Open`. | Video, Audio, Voiceover | | `InspectorBar.Button.rememberCrop` | `InspectorBar.Button.Id.crop` | Opens crop sheet via `EditorEvent.Sheet.Open`. | Video, Image | | `InspectorBar.Button.rememberAdjustments` | `InspectorBar.Button.Id.adjustments` | Opens adjustments sheet via `EditorEvent.Sheet.Open`. | Video, Image | | `InspectorBar.Button.rememberFilter` | `InspectorBar.Button.Id.filter` | Opens filter sheet via `EditorEvent.Sheet.Open`. | Video, Image | | `InspectorBar.Button.rememberEffect` | `InspectorBar.Button.Id.effect` | Opens effect sheet via `EditorEvent.Sheet.Open`. | Video, Image | | `InspectorBar.Button.rememberBlur` | `InspectorBar.Button.Id.blur` | Opens blur sheet via `EditorEvent.Sheet.Open`. | Video, Image | | `InspectorBar.Button.rememberShape` | `InspectorBar.Button.Id.shape` | Opens shape sheet via `EditorEvent.Sheet.Open`. | Video, Image, Shape | | `InspectorBar.Button.rememberSelectGroup` | `InspectorBar.Button.Id.selectGroup` | Selects the group design block that contains the currently selected design block via `EditorEvent.selectGroupForSelection`. | Video, Image, Sticker, Shape, Text | | `InspectorBar.Button.rememberEnterGroup` | `InspectorBar.Button.Id.enterGroup` | Changes selection from the selected group design block to a design block within that group via `EditorEvent.enterGroupForSelection`. | Group | | `InspectorBar.Button.rememberLayer` | `InspectorBar.Button.Id.layer` | Opens layer sheet via `EditorEvent.Sheet.Open`. | Video, Image, Sticker, Shape, Text | | `InspectorBar.Button.rememberSplit` | `InspectorBar.Button.Id.split` | Splits currently selected design block via `EditorEvent.splitSelection` in a video scene. | Video, Image, Sticker, Shape, Text, Audio | | `InspectorBar.Button.rememberMoveAsClip` | `InspectorBar.Button.Id.moveAsClip` | Moves currently selected design block into the background track as clip via `EditorEvent.moveSelectionAsClip`. | Video, Image, Sticker, Shape, Text | | `InspectorBar.Button.rememberMoveAsOverlay` | `InspectorBar.Button.Id.moveAsOverlay` | Moves currently selected design block from the background track to an overlay via `EditorEvent.moveSelectionAsOverlay`. | Video, Image, Sticker, Shape, Text | | `InspectorBar.Button.rememberReorder` | `InspectorBar.Button.Id.reorder` | Opens reorder sheet via `EditorEvent.Sheet.Open`. | Video, Image, Sticker, Shape, Text | | `InspectorBar.Button.rememberDuplicate` | `InspectorBar.Button.Id.duplicate` | Duplicates currently selected design block via `EditorEvent.duplicateSelection`. | Video, Image, Sticker, Shape, Text, Audio | | `InspectorBar.Button.rememberDelete` | `InspectorBar.Button.Id.delete` | Deletes currently selected design block via `EditorEvent.deleteSelection`. | Video, Image, Sticker, Shape, Text, Audio, Voiceover | --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Navigation Bar" description: "Show, hide, or customize the editor's top navigation bar to match your app layout." platform: android url: "https://img.ly/docs/cesdk/android/user-interface/customization/navigation-bar-4e5d39/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [User Interface](https://img.ly/docs/cesdk/android/user-interface-5a089a/) > [Customization](https://img.ly/docs/cesdk/android/user-interface/customization-72b2f8/) > [Navigation Bar](https://img.ly/docs/cesdk/android/user-interface/customization/navigation-bar-4e5d39/) --- ```kotlin file=@cesdk_android_examples/editor-guides-configuration-navigation-bar/SimpleNavigationBarSolution.kt reference-only import androidx.compose.animation.EnterTransition import androidx.compose.animation.ExitTransition import androidx.compose.foundation.background import androidx.compose.foundation.layout.Arrangement import androidx.compose.foundation.layout.Box import androidx.compose.foundation.layout.PaddingValues import androidx.compose.foundation.layout.fillMaxWidth import androidx.compose.foundation.layout.heightIn import androidx.compose.foundation.layout.padding import androidx.compose.material3.MaterialTheme import androidx.compose.runtime.Composable import androidx.compose.runtime.remember import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.unit.dp import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EngineConfiguration import ly.img.editor.core.LocalEditorScope import ly.img.editor.core.component.NavigationBar import ly.img.editor.rememberForDesign // Add this composable to your NavHost @Composable fun SimpleNavigationBarSolution(navController: NavHostController) { val engineConfiguration = EngineConfiguration.rememberForDesign( license = "", // pass null or empty for evaluation mode with watermark ) val editorConfiguration = EditorConfiguration.rememberForDesign( navigationBar = { NavigationBar.remember( scope = LocalEditorScope.current.run { remember(this) { NavigationBar.Scope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, decoration = { // Also available via NavigationBar.DefaultDecoration Box( modifier = Modifier .fillMaxWidth() .heightIn(min = 64.dp) .background(MaterialTheme.colorScheme.surface) .padding(PaddingValues(horizontal = 4.dp)), contentAlignment = Alignment.Center, ) { it() } }, listBuilder = NavigationBar.ListBuilder.remember { }, horizontalArrangement = { Arrangement.SpaceEvenly }, // default value is { it() } itemDecoration = { Box(modifier = Modifier.padding(2.dp)) { it() } }, ) }, ) DesignEditor( engineConfiguration = engineConfiguration, editorConfiguration = editorConfiguration, ) { // You can set result here navController.popBackStack() } } ``` ```kotlin file=@cesdk_android_examples/editor-guides-configuration-navigation-bar/NavigationBarListBuilders.kt reference-only import androidx.compose.runtime.Composable import androidx.compose.ui.Alignment import androidx.compose.ui.res.stringResource import ly.img.editor.core.R import ly.img.editor.core.component.NavigationBar import ly.img.editor.core.component.rememberCloseEditor import ly.img.editor.core.component.rememberExport import ly.img.editor.core.component.rememberNextPage import ly.img.editor.core.component.rememberPreviousPage import ly.img.editor.core.component.rememberRedo import ly.img.editor.core.component.rememberTogglePagesMode import ly.img.editor.core.component.rememberTogglePreviewMode import ly.img.editor.core.component.rememberUndo @Composable fun NavigationBar.ListBuilder.rememberForDesign() = NavigationBar.ListBuilder.remember { aligned(alignment = Alignment.Start) { add { NavigationBar.Button.rememberCloseEditor() } } aligned(alignment = Alignment.End) { add { NavigationBar.Button.rememberUndo() } add { NavigationBar.Button.rememberRedo() } add { NavigationBar.Button.rememberTogglePagesMode() } add { NavigationBar.Button.rememberExport() } } } @Composable fun NavigationBar.ListBuilder.rememberForPhoto() = NavigationBar.ListBuilder.remember { aligned(alignment = Alignment.Start) { add { NavigationBar.Button.rememberCloseEditor() } } aligned(alignment = Alignment.End) { add { NavigationBar.Button.rememberUndo() } add { NavigationBar.Button.rememberRedo() } add { NavigationBar.Button.rememberTogglePreviewMode() } add { NavigationBar.Button.rememberExport() } } } @Composable fun NavigationBar.ListBuilder.rememberForVideo() = NavigationBar.ListBuilder.remember { aligned(alignment = Alignment.Start) { add { NavigationBar.Button.rememberCloseEditor() } } aligned(alignment = Alignment.End) { add { NavigationBar.Button.rememberUndo() } add { NavigationBar.Button.rememberRedo() } add { NavigationBar.Button.rememberExport() } } } @Composable fun NavigationBar.ListBuilder.rememberForApparel() = NavigationBar.ListBuilder.remember { aligned(alignment = Alignment.Start) { add { NavigationBar.Button.rememberCloseEditor() } } aligned(alignment = Alignment.CenterHorizontally) { add { NavigationBar.Button.rememberUndo() } add { NavigationBar.Button.rememberRedo() } add { NavigationBar.Button.rememberTogglePreviewMode() } } aligned(alignment = Alignment.End) { add { NavigationBar.Button.rememberExport() } } } @Composable fun NavigationBar.ListBuilder.rememberForPostcard() = NavigationBar.ListBuilder.remember { aligned(alignment = Alignment.Start) { add { NavigationBar.Button.rememberCloseEditor() } add { NavigationBar.Button.rememberPreviousPage( text = { stringResource(R.string.ly_img_editor_navigation_bar_button_design) }, ) } } aligned(alignment = Alignment.CenterHorizontally) { add { NavigationBar.Button.rememberUndo() } add { NavigationBar.Button.rememberRedo() } add { NavigationBar.Button.rememberTogglePreviewMode() } } aligned(alignment = Alignment.End) { add { NavigationBar.Button.rememberNextPage( text = { stringResource(R.string.ly_img_editor_navigation_bar_button_write) }, ) } add { NavigationBar.Button.rememberExport() } } } ``` ```kotlin file=@cesdk_android_examples/editor-guides-configuration-navigation-bar/ModifyListBuilderNavigationBarSolution.kt reference-only import androidx.compose.runtime.Composable import androidx.compose.ui.Alignment import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EngineConfiguration import ly.img.editor.core.component.EditorComponent.ListBuilder.Companion.modify import ly.img.editor.core.component.EditorComponentId import ly.img.editor.core.component.NavigationBar import ly.img.editor.core.component.export import ly.img.editor.core.component.redo import ly.img.editor.core.component.rememberForDesign import ly.img.editor.core.component.togglePagesMode import ly.img.editor.core.component.undo import ly.img.editor.core.iconpack.IconPack import ly.img.editor.core.iconpack.Music import ly.img.editor.rememberForDesign // Add this composable to your NavHost @Composable fun ModifyListBuilderNavigationBarSolution(navController: NavHostController) { val engineConfiguration = EngineConfiguration.rememberForDesign( license = "", // pass null or empty for evaluation mode with watermark ) val editorConfiguration = EditorConfiguration.rememberForDesign( navigationBar = { NavigationBar.remember( listBuilder = NavigationBar.ListBuilder.rememberForDesign().modify { addFirst(alignment = Alignment.End) { NavigationBar.Button.remember( id = EditorComponentId("my.package.navigationBar.button.endAligned.first"), vectorIcon = { IconPack.Music }, text = { "First Button" }, onClick = {}, ) } addLast(alignment = Alignment.End) { NavigationBar.Button.remember( id = EditorComponentId("my.package.navigationBar.button.endAligned.last"), vectorIcon = { IconPack.Music }, text = { "Last Button" }, onClick = {}, ) } addAfter(id = NavigationBar.Button.Id.redo) { NavigationBar.Button.remember( id = EditorComponentId("my.package.navigationBar.button.afterRedo"), vectorIcon = { IconPack.Music }, text = { "After Redo" }, onClick = {}, ) } addBefore(id = NavigationBar.Button.Id.undo) { NavigationBar.Button.remember( id = EditorComponentId("my.package.navigationBar.button.beforeUndo"), vectorIcon = { IconPack.Music }, text = { "Before Undo" }, onClick = {}, ) } replace(id = NavigationBar.Button.Id.export) { NavigationBar.Button.remember( id = EditorComponentId("my.package.navigationBar.button.replacedExport"), vectorIcon = null, text = { "Replaced Export" }, onClick = {}, ) } remove(id = NavigationBar.Button.Id.togglePagesMode) }, ) }, ) DesignEditor( engineConfiguration = engineConfiguration, editorConfiguration = editorConfiguration, ) { // You can set result here navController.popBackStack() } } ``` ```kotlin file=@cesdk_android_examples/editor-guides-configuration-navigation-bar/NavigationBarItems.kt reference-only import android.widget.Toast import androidx.compose.animation.EnterTransition import androidx.compose.animation.ExitTransition import androidx.compose.foundation.clickable import androidx.compose.foundation.layout.Box import androidx.compose.foundation.layout.fillMaxHeight import androidx.compose.material3.Icon import androidx.compose.material3.MaterialTheme import androidx.compose.material3.Surface import androidx.compose.material3.Text import androidx.compose.runtime.Composable import androidx.compose.runtime.remember import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import ly.img.editor.ShowLoading import ly.img.editor.core.LocalEditorScope import ly.img.editor.core.component.EditorComponentId import ly.img.editor.core.component.NavigationBar import ly.img.editor.core.event.EditorEvent import ly.img.editor.core.iconpack.IconPack import ly.img.editor.core.iconpack.Music import ly.img.editor.core.sheet.SheetType @Composable fun rememberNavigationBarButton() = NavigationBar.Button.remember( id = EditorComponentId("my.package.navigationBar.button.newButton"), scope = LocalEditorScope.current.run { remember(this) { NavigationBar.ButtonScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, // default value is { it() } decoration = { Surface(color = MaterialTheme.colorScheme.background) { it() } }, onClick = { editorContext.eventHandler.send(EditorEvent.Sheet.Open(SheetType.Volume())) }, // default value is null icon = { Icon( imageVector = IconPack.Music, contentDescription = null, ) }, // default value is null text = { Text( text = "Hello World", ) }, enabled = { true }, ) @Composable fun rememberNavigationBarButtonSimpleOverload() = NavigationBar.Button.remember( id = EditorComponentId("my.package.navigationBar.button.newButton"), scope = LocalEditorScope.current.run { remember(this) { NavigationBar.ButtonScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, decoration = { Surface(color = MaterialTheme.colorScheme.background) { it() } }, onClick = { editorContext.eventHandler.send(ShowLoading) }, vectorIcon = { IconPack.Music }, // default value is null text = { "Hello World" }, // default value is null tint = null, enabled = { true }, contentDescription = null, ) @Composable fun rememberNavigationBarCustomItem() = NavigationBar.Custom.remember( id = EditorComponentId("my.package.navigationBar.newCustomItem"), scope = LocalEditorScope.current.run { remember(this) { NavigationBar.ItemScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, ) { Box( modifier = Modifier .fillMaxHeight() .clickable { Toast .makeText(editorContext.activity, "Hello World Clicked!", Toast.LENGTH_SHORT) .show() }, ) { Text( modifier = Modifier.align(Alignment.Center), text = "Hello World", ) } } ``` The navigation bar serves as the primary control interface at the top of the editor, housing essential functions like session management (close/save), editing operations (undo/redo), mode switching, and export capabilities. This guide shows you how to customize the navigation layout, button placement, and functionality to align with your app's information architecture and user flow patterns. While examples use the Design Editor, the same configuration principles apply to all [editor solutions](https://img.ly/docs/cesdk/android/prebuilt-solutions-d0ed07/). Explore a complete code sample on [GitHub](https://github.com/imgly/cesdk-android-examples/tree/v$UBQ_VERSION$/editor-guides-configuration-navigation-bar). ## Navigation Bar Architecture  The navigation bar displays horizontally at the top of the editor, with items organized into alignment groups: start (left), center, and end (right). **Key Components:** - **`NavigationBar.Item`** - Abstract class that all navigation bar items inherit from - **`NavigationBar.Button`** - Pre-built button implementation with icon and text - **`NavigationBar.Custom`** - Fully custom component for arbitrary content rendering - **`NavigationBar.Scope`** - Provides access to the engine, event handler, and editor state - **Alignment Groups** - Container system that positions items by alignment (start, center, end) ## Configuration Navigation bar customization is part of the `EditorConfiguration`, therefore, in order to configure the navigation bar we need to configure the `EditorConfiguration`. Below you can find the list of available configurations of the navigation bar. To demonstrate the default values, all parameters are assigned to their default values. **Available configuration parameters:** - **`scope`** - the scope of this component. Every new value will trigger recomposition of all the lambda parameters below. If you need to access `EditorScope` to construct the scope, use `LocalEditorScope`. Consider using Compose `State` objects in the lambda parameters below for granular recompositions over updating the scope, since scope change triggers full recomposition of the navigation bar. Prefer updating individual `NavigationBar.Item`s over updating the whole navigation bar. Ideally, scope should be updated when the parent scope (scope of the parent component) is updated and when you want to observe changes from the `Engine`. By default the scope is updated only when the parent scope (accessed via `LocalEditorScope`) is updated. - **`visible`** - Control navigation bar visibility. Default value is always true. - **`enterTransition`** - Animation for when the navigation bar appears. Default value is always no enter transition. - **`exitTransition`** - Animation for when the navigation bar disappears. Default value is always no exit transition. - **`decoration`** - Apply custom styling like background, shadows, and padding. Default value is always no decoration. - **`listBuilder`** - Define the complete list of navigation bar items and their alignment groups. Items are only displayed when `visible` returns `true`. By default, `listBuilder` does not add anything to the navigation bar. - **`horizontalArrangement`** - Layout arrangement for navigation bar items. Controls spacing and alignment of items within the navigation bar. Default value is `Arrangement.SpaceEvenly`. - **`itemDecoration`** - decoration of the items in the navigation bar. Useful when you want to add custom background, foreground, shadow, paddings etc to the items. Prefer using this decoration when you want to apply the same decoration to all the items, otherwise set decoration to individual items. Default value is always no decoration. ```kotlin highlight-navigationBarConfiguration val editorConfiguration = EditorConfiguration.rememberForDesign( navigationBar = { NavigationBar.remember( scope = LocalEditorScope.current.run { remember(this) { NavigationBar.Scope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, decoration = { // Also available via NavigationBar.DefaultDecoration Box( modifier = Modifier .fillMaxWidth() .heightIn(min = 64.dp) .background(MaterialTheme.colorScheme.surface) .padding(PaddingValues(horizontal = 4.dp)), contentAlignment = Alignment.Center, ) { it() } }, listBuilder = NavigationBar.ListBuilder.remember { }, horizontalArrangement = { Arrangement.SpaceEvenly }, // default value is { it() } itemDecoration = { Box(modifier = Modifier.padding(2.dp)) { it() } }, ) }, ) ``` ### ListBuilder Configuration You can configure the complete item list or modify the default items using two main approaches: **Available approaches:** - **`NavigationBar.ListBuilder.rememberForDesign()`** - Use the recommended default configuration for your editor solution (Design, Photo, Video, Apparel, Postcard). Each solution has optimized defaults for its workflow. - **`NavigationBar.ListBuilder.rememberForDesign().modify()`** - Modify the default item list by adding, replacing, or removing specific items without rebuilding the entire configuration. Use this when you want to keep most defaults but make targeted changes. The `NavigationBar.Scope` provides access to the engine, event handler, and editor state. Use this for advanced customization logic and to maintain consistency with the current editor state. Items are organized into alignment groups for consistent positioning across different screen sizes. ### Default Navigation Bar Items Each editor solution has its own default navigation bar configuration optimized for its workflow: **Design Editor**: ```kotlin highlight-listBuilders-design @Composable fun NavigationBar.ListBuilder.rememberForDesign() = NavigationBar.ListBuilder.remember { aligned(alignment = Alignment.Start) { add { NavigationBar.Button.rememberCloseEditor() } } aligned(alignment = Alignment.End) { add { NavigationBar.Button.rememberUndo() } add { NavigationBar.Button.rememberRedo() } add { NavigationBar.Button.rememberTogglePagesMode() } add { NavigationBar.Button.rememberExport() } } } ``` **Photo Editor**: ```kotlin highlight-listBuilders-photo @Composable fun NavigationBar.ListBuilder.rememberForPhoto() = NavigationBar.ListBuilder.remember { aligned(alignment = Alignment.Start) { add { NavigationBar.Button.rememberCloseEditor() } } aligned(alignment = Alignment.End) { add { NavigationBar.Button.rememberUndo() } add { NavigationBar.Button.rememberRedo() } add { NavigationBar.Button.rememberTogglePreviewMode() } add { NavigationBar.Button.rememberExport() } } } ``` **Video Editor**: ```kotlin highlight-listBuilders-video @Composable fun NavigationBar.ListBuilder.rememberForVideo() = NavigationBar.ListBuilder.remember { aligned(alignment = Alignment.Start) { add { NavigationBar.Button.rememberCloseEditor() } } aligned(alignment = Alignment.End) { add { NavigationBar.Button.rememberUndo() } add { NavigationBar.Button.rememberRedo() } add { NavigationBar.Button.rememberExport() } } } ``` **Apparel Editor**: ```kotlin highlight-listBuilders-apparel @Composable fun NavigationBar.ListBuilder.rememberForApparel() = NavigationBar.ListBuilder.remember { aligned(alignment = Alignment.Start) { add { NavigationBar.Button.rememberCloseEditor() } } aligned(alignment = Alignment.CenterHorizontally) { add { NavigationBar.Button.rememberUndo() } add { NavigationBar.Button.rememberRedo() } add { NavigationBar.Button.rememberTogglePreviewMode() } } aligned(alignment = Alignment.End) { add { NavigationBar.Button.rememberExport() } } } ``` **Postcard Editor**: ```kotlin highlight-listBuilders-postcard @Composable fun NavigationBar.ListBuilder.rememberForPostcard() = NavigationBar.ListBuilder.remember { aligned(alignment = Alignment.Start) { add { NavigationBar.Button.rememberCloseEditor() } add { NavigationBar.Button.rememberPreviousPage( text = { stringResource(R.string.ly_img_editor_navigation_bar_button_design) }, ) } } aligned(alignment = Alignment.CenterHorizontally) { add { NavigationBar.Button.rememberUndo() } add { NavigationBar.Button.rememberRedo() } add { NavigationBar.Button.rememberTogglePreviewMode() } } aligned(alignment = Alignment.End) { add { NavigationBar.Button.rememberNextPage( text = { stringResource(R.string.ly_img_editor_navigation_bar_button_write) }, ) } add { NavigationBar.Button.rememberExport() } } } ``` ### Modify Navigation Bar Items Use the `modify` function to adjust the default item list without rebuilding the entire configuration: ```kotlin highlight-modifyListBuilderSignature listBuilder = NavigationBar.ListBuilder.rememberForDesign().modify { ``` **Available modification operations:** - `addFirst` - prepends a new item at the beginning of an alignment group: ```kotlin highlight-modifyListBuilder-addFirst addFirst(alignment = Alignment.End) { NavigationBar.Button.remember( id = EditorComponentId("my.package.navigationBar.button.endAligned.first"), vectorIcon = { IconPack.Music }, text = { "First Button" }, onClick = {}, ) } ``` - `addLast` - appends a new item at the end of an alignment group: ```kotlin highlight-modifyListBuilder-addLast addLast(alignment = Alignment.End) { NavigationBar.Button.remember( id = EditorComponentId("my.package.navigationBar.button.endAligned.last"), vectorIcon = { IconPack.Music }, text = { "Last Button" }, onClick = {}, ) } ``` - `addAfter` - adds a new item right after a specific item: ```kotlin highlight-modifyListBuilder-addAfter addAfter(id = NavigationBar.Button.Id.redo) { NavigationBar.Button.remember( id = EditorComponentId("my.package.navigationBar.button.afterRedo"), vectorIcon = { IconPack.Music }, text = { "After Redo" }, onClick = {}, ) } ``` - `addBefore` - adds a new item right before a specific item: ```kotlin highlight-modifyListBuilder-addBefore addBefore(id = NavigationBar.Button.Id.undo) { NavigationBar.Button.remember( id = EditorComponentId("my.package.navigationBar.button.beforeUndo"), vectorIcon = { IconPack.Music }, text = { "Before Undo" }, onClick = {}, ) } ``` - `replace` - replaces an existing item with a new item: ```kotlin highlight-modifyListBuilder-replace replace(id = NavigationBar.Button.Id.export) { NavigationBar.Button.remember( id = EditorComponentId("my.package.navigationBar.button.replacedExport"), vectorIcon = null, text = { "Replaced Export" }, onClick = {}, ) } ``` - `remove` - removes an existing item: ```kotlin highlight-modifyListBuilder-remove remove(id = NavigationBar.Button.Id.togglePagesMode) ``` > **Note:** **Warning**\ > Note that the order of items may change between editor versions, therefore `modify` must be used with care. Consider creating a new builder if you want to have strict ordering between different editor versions. ## NavigationBar.Item Configuration Each `NavigationBar.Item` is an `EditorComponent`. Its `id` must be unique which is a requirement for proper component management. Items must be organized within alignment groups when using the aligned layout system. ### Use Predefined Buttons Start with predefined buttons which are provided as composable functions. All [available predefined buttons are listed below](https://img.ly/docs/cesdk/android/user-interface/customization/navigation-bar-4e5d39/#list-of-available-navigationbarbuttons). ### Create New Buttons Create custom buttons when predefined options don't meet your needs: ```kotlin highlight-navigationBarItems-newButton @Composable fun rememberNavigationBarButton() = NavigationBar.Button.remember( id = EditorComponentId("my.package.navigationBar.button.newButton"), scope = LocalEditorScope.current.run { remember(this) { NavigationBar.ButtonScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, // default value is { it() } decoration = { Surface(color = MaterialTheme.colorScheme.background) { it() } }, onClick = { editorContext.eventHandler.send(EditorEvent.Sheet.Open(SheetType.Volume())) }, // default value is null icon = { Icon( imageVector = IconPack.Music, contentDescription = null, ) }, // default value is null text = { Text( text = "Hello World", ) }, enabled = { true }, ) ``` **Required and optional parameters:** - `id` - the id of the button. Note that it is highly recommended that every unique `EditorComponent` has a unique id. Parameter does not have a default value. - `scope` - the scope of this component. Every new value will trigger recomposition of all the lambda parameters below. If you need to access `EditorScope` to construct the scope, use `LocalEditorScope`. Consider using Compose `State` objects in the lambda parameters below for granular recompositions over updating the scope, since scope change triggers full recomposition of the button. Ideally, scope should be updated when the parent scope (scope of the parent component `NavigationBar` - `NavigationBar.Scope`) is updated and when you want to observe changes from the `Engine`. By default the scope is updated only when the parent component scope (accessed via `LocalEditorScope`) is updated. - `visible` - whether the button should be visible. Default value is always true. - `enterTransition` - transition of the button when it enters the parent composable. Default value is always no enter transition. - `exitTransition` - transition of the button when it exits the parent composable. Default value is always no exit transition. - `decoration` - decoration of the button. Useful when you want to add custom background, foreground, shadow, paddings etc. Default value is always no decoration. - `onClick` - the callback that is invoked when the button is clicked. Parameter does not have a default value. - `icon` - the icon content of the button. If null, it will not be rendered. Default value is null. - `text` - the text content of the button. If null, it will not be rendered. Default value is null. - `tint` - the tint color of the content. If null, then no tint is applied. Default value is null. - `enabled` - whether the button is enabled. Default value is always true. Other than the main `NavigationBar.Button.remember` function, there is one more convenience overload that has three differences: 1. `icon` is replaced with `vectorIcon` lambda, that returns `VectorIcon` instead of drawing the icon content. 2. `text` is replaced with `text` lambda, that returns `String` instead of drawing the text content. 3. An extra parameter `contentDescription` is added that is used by accessibility services to describe what the button does. Note that it is not required to provide value when `text` is not null, since its value will be used by accessibility services, however having both `text` and `contentDescription` as null will cause a crash. ### Create Custom Items For completely custom implementations, use `NavigationBar.Custom` to render arbitrary content: ```kotlin highlight-navigationBarItems-newCustomItem @Composable fun rememberNavigationBarCustomItem() = NavigationBar.Custom.remember( id = EditorComponentId("my.package.navigationBar.newCustomItem"), scope = LocalEditorScope.current.run { remember(this) { NavigationBar.ItemScope(parentScope = this) } }, visible = { true }, enterTransition = { EnterTransition.None }, exitTransition = { ExitTransition.None }, ) { Box( modifier = Modifier .fillMaxHeight() .clickable { Toast .makeText(editorContext.activity, "Hello World Clicked!", Toast.LENGTH_SHORT) .show() }, ) { Text( modifier = Modifier.align(Alignment.Center), text = "Hello World", ) } } ``` **Required and optional parameters:** - `id` - the unique id of the custom item. Note that it is highly recommended that every unique `EditorComponent` has a unique id. Parameter does not have a default value. - `scope` - the scope of this component. Every new value will trigger recomposition of all the lambda parameters below. If you need to access `EditorScope` to construct the scope, use `LocalEditorScope`. Consider using Compose `State` objects in the lambda parameters below for granular recompositions over updating the scope, since scope change triggers full recomposition of the custom item. Ideally, scope should be updated when the parent scope (scope of the parent component `NavigationBar` - `NavigationBar.Scope`) is updated and when you want to observe changes from the `Engine`. Parameter does not have a default value. - `visible` - whether the custom item should be visible. Default value is always true. - `enterTransition` - transition of the custom item when it enters the parent composable. Default value is always no enter transition. - `exitTransition` - transition of the custom item when it exits the parent composable. Default value is always no exit transition. - `content` - the content of the custom item. You are responsible for drawing it, handling clicks etc. Parameter does not have a default value. ### Alignment Groups When using alignment groups, items are positioned in three areas: - **`Alignment.Start`** - Items aligned to the start (left) of the navigation bar - **`Alignment.CenterHorizontally`** - Items centered in the navigation bar - **`Alignment.End`** - Items aligned to the end (right) of the navigation bar ```kotlin aligned(alignment = Alignment.Start) { add { NavigationBar.Button.rememberCloseEditor() } } aligned(alignment = Alignment.End) { add { NavigationBar.Button.rememberExport() } } ``` > **Note:** **Warning** It is not allowed to add items both inside and outside align > blocks at the same time: either all items should be in aligned groups, or no > items at all. ### List of Available NavigationBar.Buttons All predefined buttons are available as composable functions in the `NavigationBar.Button` namespace. Each function returns a `NavigationBar.Button` with default parameters that you can customize as shown in the [Create New Buttons](https://img.ly/docs/cesdk/android/user-interface/customization/navigation-bar-4e5d39/#create-new-buttons) section. | Button | Id | Description | | ------------------------------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `NavigationBar.Button.rememberCloseEditor` | `NavigationBar.Button.Id.closeEditor` | Triggers [EngineConfiguration.onClose](https://img.ly/docs/cesdk/android/user-interface/events-514b70/) callback via `EditorEvent.OnClose`. | | `NavigationBar.Button.rememberUndo` | `NavigationBar.Button.Id.undo` | Does undo operation in the editor via [EditorApi.undo](https://img.ly/docs/cesdk/android/concepts/undo-and-history-99479d/) engine API. | | `NavigationBar.Button.rememberRedo` | `NavigationBar.Button.Id.redo` | Does redo operation in the editor via [EditorApi.redo](https://img.ly/docs/cesdk/android/concepts/undo-and-history-99479d/) engine API. | | `NavigationBar.Button.rememberExport` | `NavigationBar.Button.Id.export` | Triggers [EngineConfiguration.onExport](https://img.ly/docs/cesdk/android/user-interface/events-514b70/) callback via `EditorEvent.Export`. | | `NavigationBar.Button.rememberTogglePreviewMode` | `NavigationBar.Button.Id.togglePreviewMode` | Updates editor view mode via `EditorEvent.SetViewMode`: when current view mode is `EditorViewMode.Edit`, then `EditorViewMode.Preview` is set and vice versa. Note that this button is intended to be used in Photo Editor, Apparel Editor and Postcard Editor and may cause unexpected behaviors when used in other solutions. | | `NavigationBar.Button.rememberTogglePagesMode` | `NavigationBar.Button.Id.togglePagesMode` | Updates editor view mode via `EditorEvent.SetViewMode`: when current view mode is `EditorViewMode.Edit`, then `EditorViewMode.Pages` is set and vice versa. Note that this button is intended to be used in Design Editor and may cause unexpected behaviors when used in other solutions. | | `NavigationBar.Button.rememberPreviousPage` | `NavigationBar.Button.Id.previousPage` | Navigates to the previous page via `EditorEvent.Navigation.ToPreviousPage`. | | `NavigationBar.Button.rememberNextPage` | `NavigationBar.Button.Id.nextPage` | Navigates to the next page via `EditorEvent.Navigation.ToNextPage`. | --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Page Format" description: "Define default page size, orientation, and other format settings for your design canvas." platform: android url: "https://img.ly/docs/cesdk/android/user-interface/customization/page-format-496315/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [User Interface](https://img.ly/docs/cesdk/android/user-interface-5a089a/) > [Customization](https://img.ly/docs/cesdk/android/user-interface/customization-72b2f8/) > [Page Format](https://img.ly/docs/cesdk/android/user-interface/customization/page-format-496315/) --- By default, the CreativeEditor SDK ships with an extensive list of commonly used formats, as shown below:  The CE.SDK can be configured with a series of crop presets by updating the `content.json` from the default asset source - `ly.img.page.presets` - on your CDN. For further reference, [please take a look at the "Serve Assets" section here.](https://img.ly/docs/cesdk/android/serve-assets-b0827c/) To enable the CE.SDK defaults enable our default asset sources by using `addDefaultAssetSources`. ```kotlin val baseUri = Uri.parse("YOUR_CDN_URL") engine.addDefaultAssetSources(baseUri) ``` ## Configuring Custom Page Formats When overriding the `content.json` with your custom crop presets each of the assets in the asset source must define a value for its `payload.transformPreset` property. When a fixed size preset is applied, the pages of the scene will be resized to the specified `width` and `height`. ```json { "id": "page-sizes-instagram-square", "label": { "en": "Square Post (1:1)", "de": "Quadratischer Post (1:1)" }, "meta": { "thumbUri": "{{base_url}}/ly.img.page.presets/thumbnails/instagram/ig-square.png" }, "payload": { "transformPreset": { "type": "FixedSize", "width": 1080, "height": 1080, "designUnit": "Pixel" } }, "groups": ["instagram"] } ``` - `type` - specifies the preset type. ```json "type": "FixedSize" ``` - `width` - specifies the width of the page in the specified design unit. ```json "width": 1280 ``` - `height` specifies the height of the page in the specified design unit. ```json "height": 720 ``` - `unit` describes unit in which `width` and `height` are specified. This can either be `Millimeter`, `Inch` or `Pixel`. ```json "designUnit": "Pixel" ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Panel" description: "Show or hide side panels to focus the user interface on what matters most for your use case." platform: android url: "https://img.ly/docs/cesdk/android/user-interface/customization/panel-7ce1ee/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [User Interface](https://img.ly/docs/cesdk/android/user-interface-5a089a/) > [Customization](https://img.ly/docs/cesdk/android/user-interface/customization-72b2f8/) > [Panel](https://img.ly/docs/cesdk/android/user-interface/customization/panel-7ce1ee/) --- ```kotlin file=@cesdk_android_examples/editor-guides-configuration-panel/DefaultPanelSolution.kt reference-only import androidx.compose.material.icons.Icons import androidx.compose.material.icons.rounded.KeyboardArrowUp import androidx.compose.material3.Icon import androidx.compose.material3.Text import androidx.compose.runtime.Composable import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EngineConfiguration import ly.img.editor.core.component.Dock import ly.img.editor.core.component.EditorComponent.ListBuilder.Companion.modify import ly.img.editor.core.component.EditorComponentId import ly.img.editor.core.component.rememberForDesign import ly.img.editor.core.event.EditorEvent import ly.img.editor.core.sheet.SheetType import ly.img.editor.rememberForDesign @Composable fun DefaultPanelSolution(navController: NavHostController) { val engineConfig = EngineConfiguration.rememberForDesign( license = "", // pass null or empty for evaluation mode with watermark ) val editorConfig = EditorConfiguration.rememberForDesign( dock = { Dock.rememberForDesign( listBuilder = Dock.ListBuilder.rememberForDesign().modify { addFirst { openPanelDockButton } }, ) }, ) DesignEditor( engineConfiguration = engineConfig, editorConfiguration = editorConfig, ) { navController.popBackStack() } } val openPanelDockButton @Composable get() = Dock.Button.remember( id = EditorComponentId("open_library_panel"), text = { Text("Open Library") }, icon = { Icon(Icons.Rounded.KeyboardArrowUp, null) }, onClick = { editorContext.eventHandler.send( EditorEvent.Sheet.Open( SheetType.LibraryAdd(), ), ) }, ) ``` ```kotlin file=@cesdk_android_examples/editor-guides-configuration-panel/CustomPanelSolution.kt reference-only import androidx.compose.foundation.layout.Column import androidx.compose.material.icons.Icons import androidx.compose.material.icons.rounded.KeyboardArrowUp import androidx.compose.material3.Button import androidx.compose.material3.Icon import androidx.compose.material3.Text import androidx.compose.runtime.Composable import androidx.compose.ui.unit.dp import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EngineConfiguration import ly.img.editor.core.component.Dock import ly.img.editor.core.component.EditorComponent.ListBuilder.Companion.modify import ly.img.editor.core.component.EditorComponentId import ly.img.editor.core.component.data.Height import ly.img.editor.core.component.rememberForDesign import ly.img.editor.core.event.EditorEvent import ly.img.editor.core.sheet.SheetStyle import ly.img.editor.core.sheet.SheetType import ly.img.editor.rememberForDesign @Composable fun CustomPanelSolution(navController: NavHostController) { val engineConfig = EngineConfiguration.rememberForDesign( license = null, // evaluation mode with watermark ) val editorConfig = EditorConfiguration.rememberForDesign( dock = { Dock.rememberForDesign( listBuilder = Dock.ListBuilder.rememberForDesign().modify { addFirst { openCustomPanelDockButton } }, ) }, ) DesignEditor( engineConfiguration = engineConfig, editorConfiguration = editorConfig, ) { navController.popBackStack() } } val openCustomPanelDockButton @Composable get() = Dock.Button.remember( id = EditorComponentId("open_panel"), text = { Text("Open Panel") }, icon = { Icon(Icons.Rounded.KeyboardArrowUp, null) }, onClick = { editorContext.eventHandler.send( EditorEvent.Sheet.Open( customSheetType, ), ) }, ) val customSheetType: SheetType get() = SheetType.Custom( style = SheetStyle( isFloating = false, minHeight = Height.Exactly(0.dp), maxHeight = Height.Fraction(0.7F), isHalfExpandingEnabled = true, isHalfExpandedInitially = true, animateInitialValue = true, ), content = { Column { Text("Custom Panel") Button( onClick = { editorContext.eventHandler.send( EditorEvent.Sheet.Close(animate = true), ) }, ) { Text("Close Panel") } } }, ) ``` A panel is a UI layer that displays above the canvas, and allows the user perform a scoped task like accessing asset library, selecting filters, or any custom action.  ## Controlling a Panel Panels are implemented as different types of `SheetType` that allow you to display content in standard sheet overlays. Panels are opened using the `EditorEvent.Sheet.Open` event, and passing in the desired `sheetType` ```kotlin highlight-open-panel editorContext.eventHandler.send( EditorEvent.Sheet.Open( SheetType.LibraryAdd(), ), ) ``` After use, they can be closed using the `EditorEvent.Sheet.Close` event. ```kotlin highlight-close-panel editorContext.eventHandler.send( EditorEvent.Sheet.Close(animate = true), ) ``` The boolean parameter indicates whether the panel should be closed with animation. ## Creating a Custom Panel To create a custom panel, you can make a new `SheetType.Custom()` and define your UI inside the `content` parameter. ```kotlin highlight-open-custom-panel SheetType.Custom( style = SheetStyle( isFloating = false, minHeight = Height.Exactly(0.dp), maxHeight = Height.Fraction(0.7F), isHalfExpandingEnabled = true, isHalfExpandedInitially = true, animateInitialValue = true, ), content = { Column { Text("Custom Panel") Button( onClick = { editorContext.eventHandler.send( EditorEvent.Sheet.Close(animate = true), ) }, ) { Text("Close Panel") } } }, ) ``` In the `style` parameter, you can define how the sheet will look like. These are the parameters available for `SheetStyle` constructor, and what they change: | Parameter | Default Value | Description | | ------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `isFloating` | `false` | whether the sheet should be floating. If `true` the sheet will be rendered over the editor, if `false` then the canvas will be zoomed to adjust the sheet. | | `minHeight` | `Height.Exactly(0.dp)` | the minimum height of the sheet. | | `maxHeight` | `Height.Fraction(0.5f)` | the maximum height of the sheet. If null, then there is no limit to the height. Once the maximum height is reached, the content of the sheet becomes vertically scrollable, if it is supported. Note that if you need the content to be scrollable in `SheetType.Custom`, then you need to add it manually. | | `isHalfExpandingEnabled` | `false` | whether the sheet should have a half expanded state. If false, then the sheet gets only 2 states: hidden and expanded. | | `isHaldExpandedInitially` | `false` | whether the sheet should be opened as half expanded initially. This flag takes effect only if `isHalfExpandingEnabled` is true. | | `animateInitialValue` | `true` | whether initial expanded or half-expanded state should be animated. | ## Default Sheet Types The editor provides several built-in sheet types for common functionality: | Panel Type | Description | | ---------------------------- | ----------------------------------------------------------------- | | `SheetType.LibraryAdd()` | Display `LibraryCategory` in order to add assets to the scene | | `SheetType.LibraryReplace()` | Display `LibraryCategory` in order to replace assets in the scene | | `SheetType.Reorder()` | Reorder videos on the background track | | `SheetType.Adjustments()` | Make adjustments to design blocks with image and video fills | | `SheetType.Filter()` | Set filters to design blocks with image and video fills | | `SheetType.Effect()` | Set effects to design blocks with image and video fills | | `SheetType.Blur()` | Set blurs to design blocks with image and video fills | | `SheetType.Crop()` | Crop design blocks with image and video fills | | `SheetType.Layer()` | Control the layering of design blocks | | `SheetType.FormatText()` | Control formatting of text blocks | | `SheetType.Shape()` | Control the shape of various blocks | | `SheetType.FillStroke()` | Control the fill and/or stroke of various blocks | | `SheetType.Volume()` | Control the volume of audio/video | | `SheetType.Animation()` | Set in/out/loop animation to design blocks | ## Full source code #### Default Panel Solution ```kotlin file=@cesdk_android_examples/editor-guides-configuration-panel/DefaultPanelSolution.kt import androidx.compose.material.icons.Icons import androidx.compose.material.icons.rounded.KeyboardArrowUp import androidx.compose.material3.Icon import androidx.compose.material3.Text import androidx.compose.runtime.Composable import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EngineConfiguration import ly.img.editor.core.component.Dock import ly.img.editor.core.component.EditorComponent.ListBuilder.Companion.modify import ly.img.editor.core.component.EditorComponentId import ly.img.editor.core.component.rememberForDesign import ly.img.editor.core.event.EditorEvent import ly.img.editor.core.sheet.SheetType import ly.img.editor.rememberForDesign @Composable fun DefaultPanelSolution(navController: NavHostController) { val engineConfig = EngineConfiguration.rememberForDesign( license = "", // pass null or empty for evaluation mode with watermark ) val editorConfig = EditorConfiguration.rememberForDesign( dock = { Dock.rememberForDesign( listBuilder = Dock.ListBuilder.rememberForDesign().modify { addFirst { openPanelDockButton } }, ) }, ) DesignEditor( engineConfiguration = engineConfig, editorConfiguration = editorConfig, ) { navController.popBackStack() } } val openPanelDockButton @Composable get() = Dock.Button.remember( id = EditorComponentId("open_library_panel"), text = { Text("Open Library") }, icon = { Icon(Icons.Rounded.KeyboardArrowUp, null) }, onClick = { editorContext.eventHandler.send( EditorEvent.Sheet.Open( SheetType.LibraryAdd(), ), ) }, ) ``` #### Custom Panel Solution ```kotlin file=@cesdk_android_examples/editor-guides-configuration-panel/CustomPanelSolution.kt import androidx.compose.foundation.layout.Column import androidx.compose.material.icons.Icons import androidx.compose.material.icons.rounded.KeyboardArrowUp import androidx.compose.material3.Button import androidx.compose.material3.Icon import androidx.compose.material3.Text import androidx.compose.runtime.Composable import androidx.compose.ui.unit.dp import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EngineConfiguration import ly.img.editor.core.component.Dock import ly.img.editor.core.component.EditorComponent.ListBuilder.Companion.modify import ly.img.editor.core.component.EditorComponentId import ly.img.editor.core.component.data.Height import ly.img.editor.core.component.rememberForDesign import ly.img.editor.core.event.EditorEvent import ly.img.editor.core.sheet.SheetStyle import ly.img.editor.core.sheet.SheetType import ly.img.editor.rememberForDesign @Composable fun CustomPanelSolution(navController: NavHostController) { val engineConfig = EngineConfiguration.rememberForDesign( license = null, // evaluation mode with watermark ) val editorConfig = EditorConfiguration.rememberForDesign( dock = { Dock.rememberForDesign( listBuilder = Dock.ListBuilder.rememberForDesign().modify { addFirst { openCustomPanelDockButton } }, ) }, ) DesignEditor( engineConfiguration = engineConfig, editorConfiguration = editorConfig, ) { navController.popBackStack() } } val openCustomPanelDockButton @Composable get() = Dock.Button.remember( id = EditorComponentId("open_panel"), text = { Text("Open Panel") }, icon = { Icon(Icons.Rounded.KeyboardArrowUp, null) }, onClick = { editorContext.eventHandler.send( EditorEvent.Sheet.Open( customSheetType, ), ) }, ) val customSheetType: SheetType get() = SheetType.Custom( style = SheetStyle( isFloating = false, minHeight = Height.Exactly(0.dp), maxHeight = Height.Fraction(0.7F), isHalfExpandingEnabled = true, isHalfExpandedInitially = true, animateInitialValue = true, ), content = { Column { Text("Custom Panel") Button( onClick = { editorContext.eventHandler.send( EditorEvent.Sheet.Close(animate = true), ) }, ) { Text("Close Panel") } } }, ) ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "UI Events" description: "Listen to UI events and trigger custom logic based on user interactions in the editor interface." platform: android url: "https://img.ly/docs/cesdk/android/user-interface/events-514b70/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [User Interface](https://img.ly/docs/cesdk/android/user-interface-5a089a/) > [UI Events](https://img.ly/docs/cesdk/android/user-interface/events-514b70/) --- ```kotlin file=@cesdk_android_examples/editor-guides-configuration-callbacks/CallbacksEditorSolution.kt reference-only import android.net.Uri import android.widget.Toast import androidx.compose.runtime.Composable import androidx.core.content.FileProvider import androidx.navigation.NavHostController import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.coroutineScope import kotlinx.coroutines.flow.distinctUntilChanged import kotlinx.coroutines.flow.map import kotlinx.coroutines.launch import kotlinx.coroutines.withContext import ly.img.editor.DesignEditor import ly.img.editor.DismissVideoExportEvent import ly.img.editor.EditorDefaults import ly.img.editor.EngineConfiguration import ly.img.editor.HideLoading import ly.img.editor.OnSceneLoaded import ly.img.editor.ShareUriEvent import ly.img.editor.ShowCloseConfirmationDialogEvent import ly.img.editor.ShowErrorDialogEvent import ly.img.editor.ShowLoading import ly.img.editor.ShowVideoExportErrorEvent import ly.img.editor.ShowVideoExportProgressEvent import ly.img.editor.ShowVideoExportSuccessEvent import ly.img.editor.core.event.EditorEvent import ly.img.editor.core.library.data.TextAssetSource import ly.img.editor.core.library.data.TypefaceProvider import ly.img.engine.MimeType import ly.img.engine.SceneMode import ly.img.engine.addDefaultAssetSources import ly.img.engine.addDemoAssetSources import kotlin.coroutines.cancellation.CancellationException // Add this composable to your NavHost @Composable fun CallbacksEditorSolution(navController: NavHostController) { val engineConfiguration = EngineConfiguration.remember( license = "", // pass null or empty for evaluation mode with watermark onCreate = { // Note that lambda is copied from EditorDefaults.onCreate coroutineScope { // In case of process recovery, engine automatically recovers the scene that is why we need to check if (editorContext.engine.scene.get() == null) { editorContext.engine.scene.load(EngineConfiguration.defaultDesignSceneUri) } launch { editorContext.engine.addDefaultAssetSources() val defaultTypeface = TypefaceProvider().provideTypeface(editorContext.engine, "Roboto") requireNotNull(defaultTypeface) editorContext.engine.asset.addSource(TextAssetSource(editorContext.engine, defaultTypeface)) } launch { editorContext.engine.addDemoAssetSources( sceneMode = editorContext.engine.scene.getMode(), withUploadAssetSources = true, ) } } editorContext.eventHandler.send(HideLoading) editorContext.eventHandler.send(OnSceneLoaded()) }, onLoaded = { editorContext.engine.editor.setSettingEnum("touch/pinchAction", "Scale") coroutineScope { launch { editorContext.engine.editor .onHistoryUpdated() .collect { Toast.makeText(editorContext.activity, "History is updated!", Toast.LENGTH_SHORT).show() } } launch { editorContext.engine.editor .onStateChanged() .map { editorContext.engine.editor.getEditMode() } .distinctUntilChanged() .collect { Toast.makeText(editorContext.activity, "Edit mode is updated to $it!", Toast.LENGTH_SHORT).show() } } } }, onExport = { val engine = editorContext.engine val eventHandler = editorContext.eventHandler val context = engine.applicationContext EditorDefaults.run { if (engine.scene.getMode() == SceneMode.VIDEO) { val page = engine.scene.getCurrentPage() ?: engine.scene.getPages()[0] var exportProgress = 0f eventHandler.send(ShowVideoExportProgressEvent(exportProgress)) runCatching { val buffer = engine.block.exportVideo( block = page, timeOffset = 0.0, duration = engine.block.getDuration(page), mimeType = MimeType.MP4, progressCallback = { progress -> val newProgress = progress.encodedFrames.toFloat() / progress.totalFrames if (newProgress >= exportProgress + 0.01f) { exportProgress = newProgress eventHandler.send(ShowVideoExportProgressEvent(exportProgress)) } }, ) val file = writeToTempFile(buffer, MimeType.MP4) withContext(Dispatchers.IO) { FileProvider.getUriForFile( context, "${context.packageName}.ly.img.editor.fileprovider", file, ) } }.onSuccess { uri -> eventHandler.send(ShowVideoExportSuccessEvent(uri, MimeType.MP4.key)) }.onFailure { if (it is CancellationException) { eventHandler.send(DismissVideoExportEvent) } else { eventHandler.send(ShowVideoExportErrorEvent) } } } else { eventHandler.send(ShowLoading) runCatching { val buffer = engine.block.export( block = requireNotNull(engine.scene.get()), mimeType = MimeType.PDF, ) { scene.getPages().forEach { block.setScopeEnabled(it, key = "layer/visibility", enabled = true) block.setVisible(it, visible = true) } } val file = writeToTempFile(buffer, MimeType.PDF) withContext(Dispatchers.IO) { FileProvider.getUriForFile( context, "${context.packageName}.ly.img.editor.fileprovider", file, ) } }.onSuccess { uri -> eventHandler.send(HideLoading) eventHandler.send(ShareUriEvent(uri, MimeType.PDF.key)) }.onFailure { eventHandler.send(HideLoading) eventHandler.send(ShowErrorDialogEvent(error = it)) } } } }, onUpload = { assetDefinition, _ -> val meta = assetDefinition.meta ?: return@remember assetDefinition val sourceUri = Uri.parse(meta["uri"]) val uploadedUri = sourceUri // todo upload the asset here and return remote uri val newMeta = meta + listOf( "uri" to uploadedUri.toString(), "thumbUri" to uploadedUri.toString(), ) assetDefinition.copy(meta = newMeta) }, onClose = { hasUnsavedChanges -> if (hasUnsavedChanges) { editorContext.eventHandler.send(ShowCloseConfirmationDialogEvent) } else { editorContext.eventHandler.send(EditorEvent.CloseEditor()) } }, onError = { error -> editorContext.eventHandler.send(ShowErrorDialogEvent(error)) }, ) DesignEditor(engineConfiguration = engineConfiguration) { // You can set result here navController.popBackStack() } } ``` In this example, we will show you how to configure the callbacks of various editor events for the mobile editor. The example is based on the `Design Editor`, however, it is exactly the same for all the other [solutions](https://img.ly/docs/cesdk/android/prebuilt-solutions-d0ed07/). Note that the bodies of all callbacks except `onUpload` are copied from the `Design Editor` default implementations. ## Configuration All the callback configurations are part of the `EngineConfiguration` class. Note that all the callbacks receive `EditorEventHandler` parameter that can be used to send UI events. - `onCreate` - the callback that is invoked when the editor is created. This is the main initialization block of both the editor and engine. Normally, you should [load](https://img.ly/docs/cesdk/android/open-the-editor/load-scene-478833/) or [create](https://img.ly/docs/cesdk/android/open-the-editor/blank-canvas-18ff05/) a scene as well as prepare asset sources in this block. We recommend that you check the availability of the scene before creating/loading a new scene since a recreated scene may already exist if the callback is invoked after a process recreation. Callback does not have a default implementation, as default scenes are solution-specific, however, `EditorDefaults.onCreate` contains the default logic. By default, it loads a scene and adds all default and demo asset sources. Note that the "create" coroutine job will survive configuration changes and will be cancelled only if the editor is closed or the process is killed when in the background. ```kotlin highlight-configuration-onCreate onCreate = { // Note that lambda is copied from EditorDefaults.onCreate coroutineScope { // In case of process recovery, engine automatically recovers the scene that is why we need to check if (editorContext.engine.scene.get() == null) { editorContext.engine.scene.load(EngineConfiguration.defaultDesignSceneUri) } launch { editorContext.engine.addDefaultAssetSources() val defaultTypeface = TypefaceProvider().provideTypeface(editorContext.engine, "Roboto") requireNotNull(defaultTypeface) editorContext.engine.asset.addSource(TextAssetSource(editorContext.engine, defaultTypeface)) } launch { editorContext.engine.addDemoAssetSources( sceneMode = editorContext.engine.scene.getMode(), withUploadAssetSources = true, ) } } editorContext.eventHandler.send(HideLoading) editorContext.eventHandler.send(OnSceneLoaded()) }, ``` - `onExport` - the callback that is invoked when the export button is tapped. You may want to call one of the [export functions](https://img.ly/docs/cesdk/android/export-save-publish/export/overview-9ed3a8/) in this callback. The default implementations call `BlockApi.export` or `BlockApi.exportVideo`, write the content into a temporary file and open a system dialog for sharing the exported file. Note that the "export" coroutine job will survive configuration changes and will be cancelled only if the editor is closed or the process is killed when in the background ```kotlin highlight-configuration-onExport onExport = { val engine = editorContext.engine val eventHandler = editorContext.eventHandler val context = engine.applicationContext EditorDefaults.run { if (engine.scene.getMode() == SceneMode.VIDEO) { val page = engine.scene.getCurrentPage() ?: engine.scene.getPages()[0] var exportProgress = 0f eventHandler.send(ShowVideoExportProgressEvent(exportProgress)) runCatching { val buffer = engine.block.exportVideo( block = page, timeOffset = 0.0, duration = engine.block.getDuration(page), mimeType = MimeType.MP4, progressCallback = { progress -> val newProgress = progress.encodedFrames.toFloat() / progress.totalFrames if (newProgress >= exportProgress + 0.01f) { exportProgress = newProgress eventHandler.send(ShowVideoExportProgressEvent(exportProgress)) } }, ) val file = writeToTempFile(buffer, MimeType.MP4) withContext(Dispatchers.IO) { FileProvider.getUriForFile( context, "${context.packageName}.ly.img.editor.fileprovider", file, ) } }.onSuccess { uri -> eventHandler.send(ShowVideoExportSuccessEvent(uri, MimeType.MP4.key)) }.onFailure { if (it is CancellationException) { eventHandler.send(DismissVideoExportEvent) } else { eventHandler.send(ShowVideoExportErrorEvent) } } } else { eventHandler.send(ShowLoading) runCatching { val buffer = engine.block.export( block = requireNotNull(engine.scene.get()), mimeType = MimeType.PDF, ) { scene.getPages().forEach { block.setScopeEnabled(it, key = "layer/visibility", enabled = true) block.setVisible(it, visible = true) } } val file = writeToTempFile(buffer, MimeType.PDF) withContext(Dispatchers.IO) { FileProvider.getUriForFile( context, "${context.packageName}.ly.img.editor.fileprovider", file, ) } }.onSuccess { uri -> eventHandler.send(HideLoading) eventHandler.send(ShareUriEvent(uri, MimeType.PDF.key)) }.onFailure { eventHandler.send(HideLoading) eventHandler.send(ShowErrorDialogEvent(error = it)) } } } }, ``` - `onUpload` - the callback that is invoked after an asset is added to `UploadAssetSourceType`. When selecting an asset to upload, a default `AssetDefinition` object is constructed based on the selected asset and the callback is invoked. By default, the callback leaves the asset definition unmodified and returns the same object. However, you may want to upload the selected asset to your server before adding it to the scene. This example demonstrates how you can access the URI of the new asset, use it to upload the file to your server, and then replace the URI with the URI of your server. Note that the "upload" coroutine job will survive configuration changes and will be cancelled only if the editor is closed or the process is killed when in the background. ```kotlin highlight-configuration-onUpload onUpload = { assetDefinition, _ -> val meta = assetDefinition.meta ?: return@remember assetDefinition val sourceUri = Uri.parse(meta["uri"]) val uploadedUri = sourceUri // todo upload the asset here and return remote uri val newMeta = meta + listOf( "uri" to uploadedUri.toString(), "thumbUri" to uploadedUri.toString(), ) assetDefinition.copy(meta = newMeta) }, ``` - `onClose` - the callback that is invoked after a tap on the navigation icon of the toolbar or on the system back button. The callback receives a boolean parameter that indicates whether editor has unsaved changes. Default implementation sends `ShowCloseConfirmationDialogEvent` event in case that parameter is `true` and closes the editor if it is `false`. Note that the "close" coroutine job will survive configuration changes and will be cancelled only if the editor is closed or the process is killed when in the background. ```kotlin highlight-configuration-onClose onClose = { hasUnsavedChanges -> if (hasUnsavedChanges) { editorContext.eventHandler.send(ShowCloseConfirmationDialogEvent) } else { editorContext.eventHandler.send(EditorEvent.CloseEditor()) } }, ``` - `onError` - the callback that is invoked after the editor captures an error. Default implementation sends `ShowErrorDialogEvent` event which displays a popup dialog with action button that closes the editor. Note that the "error" coroutine job will survive configuration changes and will be cancelled only if the editor is closed or the process is killed when in the background. ```kotlin highlight-configuration-onError onError = { error -> editorContext.eventHandler.send(ShowErrorDialogEvent(error)) }, ``` ### Full Code Here's the full code for configuring events: ```kotlin import android.net.Uri import androidx.compose.runtime.Composable import androidx.navigation.NavHostController import kotlinx.coroutines.Job import kotlinx.coroutines.coroutineScope import kotlinx.coroutines.launch import ly.img.editor.DesignEditor import ly.img.editor.EditorDefaults import ly.img.editor.EngineConfiguration import ly.img.editor.HideLoading import ly.img.editor.ShareFileEvent import ly.img.editor.ShowCloseConfirmationDialogEvent import ly.img.editor.ShowErrorDialogEvent import ly.img.editor.ShowLoading import ly.img.editor.core.event.EditorEvent import ly.img.editor.core.library.data.TextAssetSource import ly.img.editor.core.library.data.TypefaceProvider import ly.img.engine.MimeType import ly.img.engine.addDefaultAssetSources import ly.img.engine.addDemoAssetSources // Add this composable to your NavHost @Composable fun CallbacksEditorSolution(navController: NavHostController) { val engineConfiguration = EngineConfiguration.remember( license = "", onCreate = { // Note that lambda is copied from EditorDefaults.onCreate coroutineScope { // In case of process recovery, engine automatically recovers the scene that is why we need to check if (editorContext.engine.scene.get() == null) { editorContext.engine.scene.load(EngineConfiguration.defaultDesignSceneUri) } launch { val baseUri = Uri.parse("https://cdn.img.ly/assets/v4") editorContext.engine.addDefaultAssetSources(baseUri = baseUri) val defaultTypeface = TypefaceProvider().provideTypeface(editorContext.engine, "Roboto") requireNotNull(defaultTypeface) editorContext.engine.asset.addSource(TextAssetSource(editorContext.engine, defaultTypeface)) } launch { editorContext.engine.addDemoAssetSources( sceneMode = editorContext.engine.scene.getMode(), withUploadAssetSources = true, baseUri = Uri.parse("https://cdn.img.ly/assets/demo/v3"), ) } coroutineContext[Job]?.invokeOnCompletion { editorContext.eventHandler.send(HideLoading) } } }, onExport = { EditorDefaults.run { editorContext.eventHandler.send(ShowLoading) val blob = editorContext.engine.block.export( block = requireNotNull(editorContext.engine.scene.get()), mimeType = MimeType.PDF, ) { scene.getPages().forEach { block.setScopeEnabled(it, key = "layer/visibility", enabled = true) block.setVisible(it, visible = true) } } val tempFile = writeToTempFile(blob) editorContext.eventHandler.send(HideLoading) editorContext.eventHandler.send(ShareFileEvent(tempFile, MimeType.PDF.key)) } }, onUpload = { assetDefinition, _ -> val meta = assetDefinition.meta ?: return@remember assetDefinition val sourceUri = Uri.parse(meta["uri"]) val uploadedUri = sourceUri // todo upload the asset here and return remote uri val newMeta = meta + listOf( "uri" to uploadedUri.toString(), "thumbUri" to uploadedUri.toString(), ) assetDefinition.copy(meta = newMeta) }, onClose = { hasUnsavedChanges -> if (hasUnsavedChanges) { editorContext.eventHandler.send(ShowCloseConfirmationDialogEvent) } else { editorContext.eventHandler.send(EditorEvent.CloseEditor()) } }, onError = { error -> editorContext.eventHandler.send(ShowErrorDialogEvent(error)) }, ) DesignEditor(engineConfiguration = engineConfiguration) { // You can set result here navController.popBackStack() } } ``` ## Updating the UI When working with the callbacks, you may want to make UI updates before, during, or after the callback execution. This is when UI events come to help. All the callbacks receive an extra parameter EditorEventHandler, which can be used to send editor events. By default, there are existing ui events, which can be found in Events.kt file (i.e. ShowLoading, HideLoading etc). ```kotlin onCreate = { EditorDefaults.onCreate( engine = editorContext.engine, sceneUri = EngineConfiguration.defaultDesignSceneUri, eventHandler = editorContext.eventHandler, ) editorContext.eventHandler.send(OnCreateCustomEvent) }, ``` You may want to declare your own custom event. Simply inherit from class EditorEvent. ```kotlin data object OnCreateCustomEvent : EditorEvent ``` After declaring the event, you can send the UI event using send function. Note that EditorEventHandler has another function called sendCloseEditorEvent, which can be used to forcefully close the mobile editor. ```kotlin editorContext.eventHandler.send(OnCreateCustomEvent) ``` Once the event is sent, it can be captured in EditorConfiguration.onEvent. The lambda contains three parameters: activity, state and of course, the captured event. In this example, the editor state is of default type EditorUiState (initially provided in initialState), however, you can have your own state class that wraps the EditorUiState or does not contain EditorUiState at all. The only requirement is that it should be Parcelable. The lambda should return the updated state, which, if changed, will trigger overlay composable to be recomposed and the overlaying ui components will be updated. ```kotlin onEvent = { state, event -> when (event) { OnCreateCustomEvent -> { Toast.makeText(editorContext.activity, "Editor is created!", Toast.LENGTH_SHORT).show() state } ShowLoading -> { state.copy(showLoading = true) } else -> { // handle other default events EditorDefaults.onEvent(editorContext.activity, state, event) } } }, ``` To handle your brand new custom event, simply check the type of the event and handle it per your needs. ```kotlin OnCreateCustomEvent -> { Toast.makeText(editorContext.activity, "Editor is created!", Toast.LENGTH_SHORT).show() state } ``` Besides, you can override the behavior of existing events too. Simply extend your when block and override the behavior. ```kotlin ShowLoading -> { state.copy(showLoading = true) } ``` If you want to leave the behavior of remaining default events unchanged, simply return the result of EditorDefaults.onEvent in the else block. ```kotlin else -> { // handle other default events EditorDefaults.onEvent(editorContext.activity, state, event) } ``` ### Full Code Here's the full code for making UI updates before, during, or after the callback execution ```kotlin import android.widget.Toast import androidx.compose.runtime.Composable import androidx.navigation.NavHostController import ly.img.editor.DesignEditor import ly.img.editor.EditorConfiguration import ly.img.editor.EditorDefaults import ly.img.editor.EditorUiState import ly.img.editor.EngineConfiguration import ly.img.editor.ShowLoading import ly.img.editor.core.event.EditorEvent data object OnCreateCustomEvent : EditorEvent // Add this composable to your NavHost @Composable fun UiEventsEditorSolution(navController: NavHostController) { val engineConfiguration = EngineConfiguration.remember( license = "", onCreate = { EditorDefaults.onCreate( engine = editorContext.engine, sceneUri = EngineConfiguration.defaultDesignSceneUri, eventHandler = editorContext.eventHandler, ) editorContext.eventHandler.send(OnCreateCustomEvent) }, ) val editorConfiguration = EditorConfiguration.remember( initialState = EditorUiState(), onEvent = { state, event -> when (event) { OnCreateCustomEvent -> { Toast.makeText(editorContext.activity, "Editor is created!", Toast.LENGTH_SHORT).show() state } ShowLoading -> { state.copy(showLoading = true) } else -> { // handle other default events EditorDefaults.onEvent(editorContext.activity, state, event) } } }, ) DesignEditor( engineConfiguration = engineConfiguration, editorConfiguration = editorConfiguration, ) { // You can set result here navController.popBackStack() } } ``` --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Localization" description: "Learn how to configure and manage multiple languages in the CE.SDK editor using the built-in internationalization API." platform: android url: "https://img.ly/docs/cesdk/android/user-interface/localization-508e20/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [User Interface](https://img.ly/docs/cesdk/android/user-interface-5a089a/) > [Localization](https://img.ly/docs/cesdk/android/user-interface/localization-508e20/) --- The CE.SDK editor currently supports English and German languages on Android, however it provides convenient API to replace the values of existing localization keys or add support for more languages. All the editor keys are located [here](https://github.com/imgly/cesdk-android/blob/v$UBQ_VERSION$/sources/editor-core/src/main/res/values/strings.xml) and they all follow strict naming convention to make locating keys simple and self-explanatory. For instance, the gallery button in the dock can be found via `ly_img_editor_dock_button_gallery` key, or the title in the format text sheet can be found via `ly_img_editor_sheet_format_text_title` key. ### Replacing existing keys In order to replace any of the existing editor keys, find the key of the desired text, copy the key to `res/values/strings.xml` file of your app module and replace with the desired value. ### Supporting new languages In order to add support for a language that is not supported by the CE.SDK editor, copy the content of the English localization [file](https://github.com/imgly/cesdk-android/blob/v$UBQ_VERSION$/sources/editor-core/src/main/res/values/strings.xml) to `res/values-{desired-language-code}/strings.xml` file and replace the values with desired translations. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Overview" description: "Use CE.SDK’s customizable, production-ready UI or replace it entirely with your own interface." platform: android url: "https://img.ly/docs/cesdk/android/user-interface/overview-41101a/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [User Interface](https://img.ly/docs/cesdk/android/user-interface-5a089a/) > [Overview](https://img.ly/docs/cesdk/android/user-interface/overview-41101a/) --- The CreativeEditor SDK (CE.SDK) includes a powerful, fully-integrated user interface that enables your users to create, edit, and export stunning designs—without requiring you to build a UI from scratch. Whether you're launching a full-featured editor or embedding design tools into a larger application, CE.SDK provides everything you need to get started quickly. Out of the box, the UI is professional, responsive, and production-ready. But it’s not a one-size-fits-all solution. You can fully **customize**, **extend**, or even **replace the UI entirely** with your own interface built on top of the CE.SDK engine. The SDK is designed to be as flexible as your product demands. [Explore Demos](https://img.ly/showcases/cesdk?tags=android) [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) ## Architecture CE.SDK’s UI is modular, declaratively configured, and tightly integrated with the core engine. At a high level, it consists of: - **Core Engine APIs** — The underlying logic for manipulating scenes, blocks, assets, and rendering - **UI Components** — Panels, bars, buttons, and menus that interact with the engine through configuration and callbacks - **Event System** — A reactive layer that tracks user input, selections, and state transitions This separation of concerns allows you to extend, replace, or completely rebuild the UI without impacting the rendering and scene logic handled by the engine. ## Customizing the UI You can tailor the editor’s interface to match your brand and use case. CE.SDK provides flexible APIs and configuration options for customizing: ### Appearance - Change the UI theme or colors - Use custom fonts and icons - Localize labels and messages ### Layout - Show or hide components based on context - Reorder buttons or entire sections - Rearrange dock elements or panel positions ### Behavior - Enable or disable specific features - Apply feature-based logic (e.g., show certain tools only for certain block types) ## Extending the UI In addition to customizing what’s already there, you can **add entirely new functionality** to the UI: - **Quick Actions** — One-click tools that perform fast edits (e.g., remove background) - **Custom Buttons** — Add buttons to the dock, canvas menu, or canvas bar - **Custom Panels** — Create complex UIs to support advanced workflows like export wizards or AI tools - **Third-Party Integrations** — Connect with external APIs, such as QR generators or content management systems Use the **Plugin API** to encapsulate these enhancements into portable, declarative extensions. These plugins can be dynamically loaded, reused across projects, and even distributed. > Tip: You don’t need to use the Plugin API to modify the UI—but it’s the best approach when you want to encapsulate logic, reuse it, or offer it to others. ## Building Your Own UI While CE.SDK includes a fully-featured UI by default, you're not locked into it. Many developers choose to **build a completely custom UI** on top of the CE.SDK engine. This approach gives you full control over layout, interaction patterns, and visual design. When building your own UI, you interact directly with: - **The CE.SDK Engine** — Use the core APIs to manage scenes, create or modify blocks, control playback, and export content - **Canvas Rendering** — Render and manipulate the canvas area within your application shell - **State and Events** — Observe selections, listen for changes, and update your UI reactively This approach is ideal when: - You need tight integration with a larger application or workflow - You want to match a highly specific design system - You're building for a unique form factor or device - You need to simplify the UI dramatically for a focused use case ## Integrating with Custom Workflows The CE.SDK UI isn’t a closed system—it plays well with your broader application logic and workflows. You can: - **Sync programmatic state** — Reflect external data (e.g., product names or image URLs) directly in the editor - **Control headless rendering** — Run the engine without the UI for automation or server-side rendering - **Trigger external logic** — Connect UI actions (like export) to your own backend services The UI components can be programmatically configured, replaced, or completely bypassed depending on your needs. Whether you’re creating a collaborative editor, running batch jobs, or embedding CE.SDK in a no-code platform, you have full control over how the UI interacts with your app. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "UI Extensions" description: "Extend the editor interface with custom components, panels, actions, and dialogs tailored to your workflow." platform: android url: "https://img.ly/docs/cesdk/android/user-interface/ui-extensions-d194d1/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Guides](https://img.ly/docs/cesdk/android/guides-8d8b00/) > [User Interface](https://img.ly/docs/cesdk/android/user-interface-5a089a/) > [UI Extensions](https://img.ly/docs/cesdk/android/user-interface/ui-extensions-d194d1/) --- --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support --- --- title: "Android Creative Editor" description: "The Android Mobile Design Editor SDK offers a robust and customizable solution for creating and editing visual designs directly within your Android applications." platform: android url: "https://img.ly/docs/cesdk/android/what-is-cesdk-2e7acd/" --- > This is one page of the CE.SDK Android documentation. For a complete overview, see the [Android Documentation Index](https://img.ly/docs/cesdk/android.md). For all docs in one file, see [llms-full.txt](https://img.ly/docs/cesdk/android/llms-full.txt). **Navigation:** [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) > [What is CE.SDK?](https://img.ly/docs/cesdk/android/what-is-cesdk-2e7acd/) --- The Android Mobile Design Editor SDK offers a robust and customizable solution for creating and editing visual designs directly within your Android applications. ### What is CE.SDK? **CreativeEditor SDK (CE.SDK)** is a powerful design engine that brings fully customizable image, video, and design editing directly into your iOS app. Whether you're enabling AI-powered design workflows, template-based creation, dynamic content generation, or full-featured creative editing, CE.SDK offers the flexibility, performance, and developer control you need — all with minimal integration overhead. [Explore Demos](https://img.ly/showcases/cesdk/?tags=android) [Get Started](https://img.ly/docs/cesdk/android/get-started/overview-e18f40/) Trusted by leading organizations worldwide, CE.SDK powers the creative editors used in best-in-class applications, including those from Shopify, Semrush, HP, Shutterfly, Ticketmaster, and Swiss Post. ## Key Capabilities of the Android Creative Editor SDK ## File Format Support CE.SDK supports a wide range of file types to ensure maximum flexibility for developers: ### Importing Media ### Exporting Media ### Importing Templates For detailed information, see the [full file format support list](https://img.ly/docs/cesdk/android/file-format-support-3c4b2a/). ## Integrations CE.SDK supports out-of-the-box integrations with: - **Getty Images** - **Unsplash** - **Pexels** - **Airtable** - **Soundstripe** Want to connect your own asset sources? Register a custom provider using our API. --- ## More Resources - **[Android Documentation Index](https://img.ly/docs/cesdk/android.md)** - Browse all Android documentation - **[Complete Documentation](https://img.ly/docs/cesdk/android/llms-full.txt)** - Full documentation in one file (for LLMs) - **[Web Documentation](https://img.ly/docs/cesdk/android/)** - Interactive documentation with examples - **[Support](mailto:support@img.ly)** - Contact IMG.LY support