Merge pull request #11 from diffusionstudio/konstantin/feature/animation-builder

Implemented and tested animation builder

Author: k9p5

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "@diffusionstudio/core",
   "private": false,
-  "version": "1.0.0-rc.3",
+  "version": "1.0.0-rc.4",
   "type": "module",
   "description": "Build bleeding edge video processing applications",
   "files": [

package.json

@@ -8,39 +8,35 @@ const composition = new core.Composition({ background: '#76b7f5' });
 setupControls(composition);
 setupTimeline(composition);
 
-await composition.add(
-  new core.VideoClip(
-    await core.VideoSource
-      .from('/sample_aac_h264_yuv420p_1080p_60fps.mp4'),
-    {
-      volume: 0.1,
-      anchor: 0.5,
-      position: 'center',
-      height: '100%',
-      alpha: new core.Keyframe([0, 120, 240, 300], [0.5, 1, 0.5, 1]),
-      scale: new core.Keyframe([0, 30], [0.1, 1], { easing: 'easeIn' }),
-      rotation: new core.Keyframe([0, 30], [0, 360], { easing: 'easeOut' }),
-    })
+const video = await composition.add(
+  new core.VideoClip(await core.VideoSource
+    .from('/sample_aac_h264_yuv420p_1080p_60fps.mp4'), {
+    volume: 0.1,
+    anchor: 0.5,
+    position: 'center',
+    height: '100%',
+  })
     .subclip(30, 540)
     .offsetBy(30)
 );
 
-await composition.add(
+video.animate()
+  .alpha(0.5).to(1, 120).to(0.5, 120).to(1, 60)
+  .scale(0.1, 0, 'easeIn').to(1, 30)
+  .rotation(0, 0, 'easeOut').to(360, 30)
+
+const image = await composition.add(
   new core.ImageClip(await core.ImageSource.from('/lenna.png'), {
     position: 'center',
     height: 600,
-    translate: {
-      x: new core.Keyframe([0, 40], [1700, -1400], { easing: 'easeOut' }),
-      y: 0
-    },
-    rotation: new core.Keyframe(
-      [0, 5, 10, 15, 20, 25, 30, 35, 40],
-      [-16, 14, -7, 24, -3, 19, -14, 5, -30]
-    ),
-    scale: new core.Keyframe([0, 40], [2, 1])
   })
 );
 
+image.animate()
+  .rotation(-16).to(14, 5).to(-7, 10).to(24, 7).to(-3, 9).to(19, 7).to(-14, 12).to(5, 9).to(-30, 13)
+  .translateX(1700, 0, 'easeOut').to(-1400, 40)
+  .scale(2).to(1, 40);
+
 await composition.add(
   new core.HtmlClip(await core.HtmlSource.from('/test.html'), {
     position: {

playground/main.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) 2024 The Diffusion Studio Authors
+ *
+ * This Source Code Form is subject to the terms of the Mozilla 
+ * Public License, v. 2.0 that can be found in the LICENSE file.
+ */
+
+import { AnimationBuilder as Builder, AnimationFunction } from '../../models/animation-builder';
+
+export interface AnimationBuilder extends Builder {
+  height: AnimationFunction<number, this>;
+  width: AnimationFunction<number, this>;
+  x: AnimationFunction<number, this>;
+  y: AnimationFunction<number, this>;
+  translateX: AnimationFunction<number, this>;
+  translateY: AnimationFunction<number, this>;
+  rotation: AnimationFunction<number, this>;
+  alpha: AnimationFunction<number, this>;
+  scale: AnimationFunction<number, this>;
+}
+
+export class AnimationBuilder extends Builder { }

src/clips/mixins/visual.animation.ts

@@ -18,6 +18,8 @@ export interface VisualMixinProps {
   scale?: Scale | float | Keyframe<number> | NumberCallback;
   x?: int | Keyframe<int> | Percent | NumberCallback;
   y?: int | Keyframe<int> | Percent | NumberCallback;
+  translateX?: int | Keyframe<int> | NumberCallback;
+  translateY?: int | Keyframe<int> | NumberCallback;
   height?: Keyframe<int> | Percent | int | NumberCallback;
   width?: Keyframe<int> | Percent | int | NumberCallback;
   anchor?: Anchor | float;

src/clips/mixins/visual.interfaces.ts

@@ -7,6 +7,8 @@
 
 import { serializable } from '../../services';
 import * as deserializers from './visual.deserializers';
+import { createAnimationBuilder } from '../../models/animation-builder';
+import { AnimationBuilder } from './visual.animation';
 import { Keyframe } from '../../models';
 import { Sprite } from 'pixi.js';
 
@@ -18,6 +20,13 @@ type BaseClass = { view: Container } & Serializer;
 
 export function VisualMixin<T extends Constructor<BaseClass>>(Base: T) {
 	class Mixin extends Base {
+		/**
+		 * Apply one or more `Pixi.js` filters to the clip. 
+		 * @example 
+		 * clip.filters = [new BlurFilter()];
+		 */
+		public filters?: Filter | Filter[];
+
 		@serializable(deserializers.Deserializer1D)
 		public _height?: int | Keyframe<int> | Percent | NumberCallback;
 
@@ -33,12 +42,6 @@ export function VisualMixin<T extends Constructor<BaseClass>>(Base: T) {
 		@serializable(deserializers.Deserializer2D)
 		public _scale?: Scale;
 
-		/**
-		 * Apply one or more `Pixi.js` filters to the clip. 
-		 * @example 
-		 */
-		public filters?: Filter | Filter[];
-
 		/**
 		 * Defines the rotation of the clip in degrees
 		 * @default 0
@@ -124,6 +127,30 @@ export function VisualMixin<T extends Constructor<BaseClass>>(Base: T) {
 			this._position.y = value;
 		}
 
+		/**
+		 * Offset relative to the x position
+		 * @default 0
+		 */
+		public get translateX(): int | Keyframe<int> | NumberCallback {
+			return this.translate.x;
+		}
+
+		public set translateX(value: int | Keyframe<int> | NumberCallback) {
+			this.translate.x = value;
+		}
+
+		/**
+		 * Offset relative to the y position
+		 * @default 0
+		 */
+		public get translateY(): int | Keyframe<int> | NumberCallback {
+			return this.translate.y;
+		}
+
+		public set translateY(value: int | Keyframe<int> | NumberCallback) {
+			this.translate.y = value;
+		}
+
 		/**
 		 * The height of the clip/container
 		 */
@@ -184,6 +211,12 @@ export function VisualMixin<T extends Constructor<BaseClass>>(Base: T) {
 				this.view.filters = null as any;
 			}
 		}
+
+		public animate() {
+			return createAnimationBuilder(
+				new AnimationBuilder(this)
+			);
+		}
 	}
 
 	return Mixin;

src/clips/mixins/visual.ts

@@ -0,0 +1,121 @@
+/**
+ * Copyright (c) 2024 The Diffusion Studio Authors
+ *
+ * This Source Code Form is subject to the terms of the Mozilla 
+ * Public License, v. 2.0 that can be found in the LICENSE file.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { Keyframe } from './keyframe';
+
+import { AnimationBuilder as Builder, createAnimationBuilder } from './animation-builder';
+import { EasingFunction } from './keyframe.types';
+
+export interface AnimationBuilder extends Builder {
+  height(value: number, delay?: number, easing?: EasingFunction): this;
+  width(value: number, delay?: number, easing?: EasingFunction): this;
+}
+
+export class AnimationBuilder extends Builder { }
+
+class TestObject {
+  height = 5;
+  width = new Keyframe([0], [0]);
+}
+
+
+describe('The Animation Builder', () => {
+  let testObject: TestObject;
+  let animate: AnimationBuilder;
+
+
+  beforeEach(() => {
+    testObject = new TestObject();
+    animate = createAnimationBuilder(new AnimationBuilder(testObject));
+  });
+
+  it('should create and assign a new Keyframe', () => {
+    animate.height(20).to(100, 12).width(30).to(80, 18);
+
+    expect(testObject.height).toBeInstanceOf(Keyframe);
+    expect(testObject.width).toBeInstanceOf(Keyframe);
+
+    const height = testObject.height as any as Keyframe<number>;
+
+    expect(height.input.length).toBe(2);
+    expect(height.output.length).toBe(2);
+
+    expect(height.input[0]).toBe(0);
+    expect(height.input[1]).toBe(12 / 30 * 1000);
+
+    expect(height.output[0]).toBe(20);
+    expect(height.output[1]).toBe(100);
+
+    const width = testObject.width as any as Keyframe<number>;
+
+    expect(width.input.length).toBe(2);
+    expect(width.output.length).toBe(2);
+
+    expect(width.input[0]).toBe(0);
+    expect(width.input[1]).toBe(18 / 30 * 1000);
+
+    expect(width.output[0]).toBe(30);
+    expect(width.output[1]).toBe(80);
+  });
+
+  it('should be based on relative delays', () => {
+    animate.height(20).to(90, 12).to(200, 6).to(280, 3);
+
+    const height = testObject.height as any as Keyframe<number>;
+
+    expect(height.input.length).toBe(4);
+    expect(height.output.length).toBe(4);
+
+    expect(height.input[0]).toBe(0);
+    expect(height.input[1]).toBe(12 / 30 * 1000);
+    expect(height.input[2]).toBe(18 / 30 * 1000);
+    expect(height.input[3]).toBe(21 / 30 * 1000);
+
+    expect(height.output[0]).toBe(20);
+    expect(height.output[1]).toBe(90);
+    expect(height.output[2]).toBe(200);
+    expect(height.output[3]).toBe(280);
+  });
+
+  it('should set the easing function', () => {
+    animate.height(20, 0, 'easeIn').to(100, 12).width(30, 0, 'easeOut').to(80, 18);
+
+    const height = testObject.height as any as Keyframe<number>;
+    const width = testObject.width as any as Keyframe<number>;
+
+    expect(height.options.easing).toBe('easeIn');
+    expect(width.options.easing).toBe('easeOut');
+  });
+
+  it('should animate from the current value', () => {
+    animate.height(20, 12);
+
+    const height = testObject.height as any as Keyframe<number>;
+
+    expect(height.input.length).toBe(2);
+    expect(height.output.length).toBe(2);
+
+    expect(height.input[0]).toBe(0);
+    expect(height.input[1]).toBe(12 / 30 * 1000);
+
+    expect(height.output[0]).toBe(5);
+    expect(height.output[1]).toBe(20);
+  });
+
+  it("should not animate from the current value if it's a Keyframe", () => {
+    animate.width(20, 12);
+
+    const width = testObject.width as any as Keyframe<number>;
+
+    expect(width.input.length).toBe(1);
+    expect(width.output.length).toBe(1);
+
+    expect(width.input[0]).toBe(12 / 30 * 1000);
+    expect(width.output[0]).toBe(20);
+  });
+});

src/models/animation-builder.spec.ts

@@ -0,0 +1,72 @@
+/**
+ * Copyright (c) 2024 The Diffusion Studio Authors
+ *
+ * This Source Code Form is subject to the terms of the Mozilla 
+ * Public License, v. 2.0 that can be found in the LICENSE file.
+ */
+
+import { EasingFunction, Keyframe, Timestamp } from "../models";
+
+export type AnimationFunction<V extends number | string, T> =
+  (value: V, delay?: number, easing?: EasingFunction) => T;
+
+export interface AnimationBuilder {
+  to(value: number, relframe: number): this;
+}
+
+export class AnimationBuilder {
+  private target: any;
+  public animation: Keyframe<string | number> | undefined;
+
+  constructor(target: any) {
+    this.target = target;
+  }
+
+  init(property: string | symbol, value: number | string, delay: number = 0, easing?: EasingFunction) {
+    if (!(property in this.target)) {
+      throw new Error(`Property [${String(property)}] cannot be assigned`);
+    }
+
+    const input = [delay];
+    const ouptut = [value];
+
+    // animate from current value to next value
+    if (typeof (this.target[property]) == typeof (value) && delay != 0) {
+      input.unshift(0);
+      ouptut.unshift(this.target[property]);
+    }
+
+    this.target[property] = this.animation = new Keyframe(input, ouptut, { easing });
+
+  }
+}
+
+export function createAnimationBuilder<T extends AnimationBuilder>(builder: T) {
+  const proxy = new Proxy(builder, {
+    get(obj: T, prop) {
+      if (prop == 'to') {
+        return (value: number, relframe: number) => {
+          if (!obj.animation) {
+            throw new Error("Cannot use 'to() before selecting a property");
+          }
+
+          const timestamp = new Timestamp(obj.animation.input.at(-1));
+          const absframe = timestamp.frames + relframe;
+
+          // ATTENTION: The arguments are inversed here
+          obj.animation.push(absframe, value);
+
+          return proxy;
+        }
+      }
+
+      return (value: number, delay?: number, easing?: EasingFunction) => {
+        obj.init(prop, value, delay, easing);
+
+        return proxy;
+      };
+    },
+  });
+
+  return proxy;
+}