From 90879d46505cfa266a69c42ce23f1b614b2b30c9 Mon Sep 17 00:00:00 2001 From: Tej Pratap Singh Date: Mon, 1 Jun 2026 17:46:10 +0530 Subject: [PATCH 1/2] docs: rewrite root README with architecture and usage overview --- README.md | 145 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 138 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index d8e9d281..fa222d2b 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,99 @@ # AndroidVideoMotion -Motion Videos natively in Android +AndroidVideoMotion is a modular toolkit for generating **frame-accurate motion videos on Android** using native Views, transitions, effects, audio tracks, and optional rendering extensions (OpenGL, Filament, SDUI, ML, and more). [![](https://jitpack.io/v/tejpratap46/AndroidVideoMotion.svg)](https://jitpack.io/#tejpratap46/AndroidVideoMotion) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/tejpratap46/AndroidVideoMotion) -view [app](./app) module for example use case. +--- -### Install +## What this project provides -1. Add it in your root settings.gradle at the end of repositories: +- Build a video timeline from MotionView-based scenes. +- Compose transitions between scenes (cross-fade, slide, blur, etc.). +- Render frame-by-frame into video output via a producer adapter. +- Add synced audio over frame ranges. +- Extend rendering pipelines with dedicated modules (OpenGL, Filament, PyTorch, SDUI, etc.). +--- + +## Core architecture + +At the heart of the project is a composition pipeline where views are scheduled by frame ranges and rendered into video output. + +```text +Motion Views + Effects + Audio + │ + ▼ + MotionVideoProducer + (sequence + transitions) + │ + ▼ + MotionComposerView + (timeline composition root) + │ + ▼ + VideoProducerAdapter +(AndroidVideoProducerAdapter by default) + │ + ▼ + Output video file ``` + +### Main responsibilities + +- **`MotionVideoProducer`** + - Builder/facade for timeline authoring. + - Tracks `totalFrames`, applies pending transitions, keeps motion audio list. + - Delegates actual rendering/export to `VideoProducerAdapter`. + +- **`MotionComposerView`** + - Root container that aggregates all scheduled `MotionView` instances. + - Receives layout and frame-window metadata from each view. + +- **`VideoProducerAdapter`** + - Rendering backend abstraction. + - Default implementation is `AndroidVideoProducerAdapter`. + +- **Motion Views / Transitions / Effects** + - Views define what appears between `startFrame` and `endFrame`. + - Transitions stitch adjacent views. + - Effects provide visual modifiers (fade, slide, zoom, blur, etc.). + +--- + +## Project structure + +```text +AndroidVideoMotion/ +├── modules/ +│ ├── motionlib/ # Core motion engine and UI components +│ │ ├── core/motion/ # Motion timeline, composer, producer, transitions +│ │ ├── core/adapter/ # Video producer adapters +│ │ ├── core/animation/ # Easings, springs, interpolators +│ │ └── ui/custom/ # Motion-aware custom views (text, image, audio, video) +│ ├── app/ # Main sample app using motionlib +│ ├── ivi-demo/ # IVI-specific demo compositions +│ ├── sdui/ # JSON-driven Motion/Generic SDUI rendering +│ ├── 3d-opengl-renderer/ # OpenGL offscreen rendering integration +│ ├── 3d-filament-renderer/ # Filament-based 3D rendering integration +│ ├── pytorch-motion-ext/ # PyTorch-based image/video ML extensions +│ ├── tensorflow-motion-ext/ # TensorFlow extension module +│ ├── ffmpeg-motion-ext/ # FFmpeg-based processing extensions +│ ├── jcodec-motion-ext/ # JCodec-based processing extensions +│ ├── motion-video-player/ # Playback-focused module +│ └── ... # Additional feature modules +├── build.gradle.kts +├── settings.gradle +└── README.md +``` + +--- + +## Quick start + +### 1) Add JitPack repository + +```gradle dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { @@ -20,10 +103,58 @@ dependencyResolutionManagement { } ``` -2. add dependency to your module +### 2) Add dependency -``` +```gradle dependencies { - implementation 'com.github.tejpratap46.AndroidVideoMotion:core:TAG' + implementation 'com.github.tejpratap46.AndroidVideoMotion:core:TAG' } ``` + +> Replace `TAG` with a release/tag from JitPack. + +--- + +## Code snippets (project overview) + +### Build a motion timeline + +```kotlin +val motionProducer = MotionVideoProducer + .with(context = applicationContext, motionAudio = motionAudio) + .addMotionViewToSequence(firstMotionView) + .addTransition(CrossFadeTransition(), duration = 30) + .addMotionViewToSequence(secondMotionView) +``` + +### Export the composed video + +```kotlin +val file = motionProducer.produceVideo( + context = applicationContext, + outputFile = File(cacheDir, "output.mp4"), +) { progress, frameBitmap -> + // Update progress UI / preview +} +``` + +### Typical config setup + +```kotlin +val motionConfig = MotionConfig( + aspectRatio = VideoAspectRatio.Ratio9x16_480, + fps = 30, +) +setCurrentConfig(motionConfig) +``` + +--- + +## Where to look next + +- **Core implementation:** `modules/motionlib/src/main/java/.../core/motion` +- **UI motion views/effects:** `modules/motionlib/src/main/java/.../ui` +- **Sample composition:** `modules/app/src/main/java/.../presentation/SampleMotionVideo.kt` +- **JSON-driven rendering:** `modules/sdui` + +If you’re new to the repo, start with `motionlib` and then open `app` or `ivi-demo` to see end-to-end usage. From 96aa15e096002d4e603a75390d0dd6ef89251d64 Mon Sep 17 00:00:00 2001 From: Tej Pratap Singh Date: Wed, 3 Jun 2026 18:25:47 +0530 Subject: [PATCH 2/2] docs: add motion view and module dependency examples --- README.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 102 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index fa222d2b..c6c7585e 100644 --- a/README.md +++ b/README.md @@ -103,15 +103,50 @@ dependencyResolutionManagement { } ``` -### 2) Add dependency +### 2) Add the modules you need + +Every library module is consumable as a separate JitPack artifact, so you can keep your app dependency graph as small as the feature set you use. Replace `TAG` with a release/tag from JitPack. ```gradle dependencies { + // Shared primitives: config, MotionView contracts, layout metadata, audio, effects. implementation 'com.github.tejpratap46.AndroidVideoMotion:core:TAG' + + // Main Android View-based motion composer, custom views, transitions, and export flow. + implementation 'com.github.tejpratap46.AndroidVideoMotion:motionlib:TAG' + + // Ready-made composition templates and SDUI-backed template helpers. + implementation 'com.github.tejpratap46.AndroidVideoMotion:templates:TAG' + + // JSON-driven motion and generic server-driven UI rendering. + implementation 'com.github.tejpratap46.AndroidVideoMotion:sdui:TAG' + + // Persist, catalog, or retrieve reusable motion definitions/assets. + implementation 'com.github.tejpratap46.AndroidVideoMotion:motion-store:TAG' + + // Extract media metadata for timeline and asset decisions. + implementation 'com.github.tejpratap46.AndroidVideoMotion:metadata-extractor:TAG' + + // Playback helpers for generated motion videos. + implementation 'com.github.tejpratap46.AndroidVideoMotion:motion-video-player:TAG' + + // Video processing/export extension backed by FFmpeg. + implementation 'com.github.tejpratap46.AndroidVideoMotion:ffmpeg-motion-ext:TAG' + + // Video processing/export extension backed by JCodec. + implementation 'com.github.tejpratap46.AndroidVideoMotion:jcodec-motion-ext:TAG' + + // Offscreen 3D rendering integrations. + implementation 'com.github.tejpratap46.AndroidVideoMotion:3d-opengl-renderer:TAG' + implementation 'com.github.tejpratap46.AndroidVideoMotion:3d-filament-renderer:TAG' + + // ML-assisted motion/image/video extensions. + implementation 'com.github.tejpratap46.AndroidVideoMotion:tensorflow-motion-ext:TAG' + implementation 'com.github.tejpratap46.AndroidVideoMotion:pytorch-motion-ext:TAG' } ``` -> Replace `TAG` with a release/tag from JitPack. +> Demo/application modules such as `app`, `ivi-demo`, and `lyrics-maker` are intended as examples and entry points rather than reusable library dependencies. --- @@ -148,6 +183,71 @@ val motionConfig = MotionConfig( setCurrentConfig(motionConfig) ``` +### Create and customize a motion view + +Custom motion views usually extend one of the base motion containers, set a frame window, optionally expose `layoutInfo`, and update their child views inside `forFrame(frame)`. Always call `super.forFrame(frame)` so visibility, nested `MotionView` children, and attached effects continue to work. + +```kotlin +class CaptionMotionView( + context: Context, + private val caption: String, + private val fromFrame: Int, + private val toFrame: Int, +) : BaseLinearMotionView(context) { + + private val captionView = AppCompatTextView(context).apply { + text = caption + textSize = 28f + gravity = Gravity.CENTER + setTextColor(Color.WHITE) + } + + override var layoutInfo = MotionLayoutInfo( + width = MotionLayoutInfo.MATCH_PARENT, + height = MotionLayoutInfo.WRAP_CONTENT, + margin = MotionLayoutInfo.Margin(bottom = 48), + gravity = Gravity.BOTTOM or Gravity.CENTER_HORIZONTAL, + ) + + init { + startFrame = fromFrame + endFrame = toFrame + addView(captionView) + addEffect(FadeInEffect(startFrame = fromFrame, endFrame = fromFrame + 12)) + } + + override fun forFrame(frame: Int): MotionView { + super.forFrame(frame) + + val scale = MotionInterpolator.interpolateForRange( + interpolator = Interpolators(Easings.CUBIC_OUT), + currentFrame = frame.coerceIn(startFrame, endFrame), + frameRange = startFrame to endFrame, + valueRange = 0.92f to 1.08f, + ) + + captionView.scaleX = scale + captionView.scaleY = scale + return this + } +} +``` + +Use it in the producer exactly like a built-in view: + +```kotlin +val caption = CaptionMotionView( + context = applicationContext, + caption = "Generated with AndroidVideoMotion", + fromFrame = 1, + toFrame = motionConfig.fps * 3, +) + +val motionProducer = MotionVideoProducer + .with(context = applicationContext) + .addMotionViewToSequence(caption) +``` + --- ## Where to look next