@omnimedia/omnitool 1.1.0-82 → 1.1.0-84

package/README.md

@@ -150,7 +150,7 @@ Animated spatial transforms:
 
 ```ts
 const timeline = omni.timeline(o => {
-	const slideIn = o.animatedSpatial(
+	const customMotion = o.animatedSpatial(
 		o.anim.transform("linear", [
 			[0, o.transform({position: [-400, 0]})],
 			[1000, o.transform({position: [0, 0]})],
@@ -161,7 +161,7 @@ const timeline = omni.timeline(o => {
 		duration: 2000,
 		styles: {fill: "white", fontSize: 36}
 	})
-	o.set(title.id, {spatialId: slideIn.id})
+	o.set(title.id, {spatialId: customMotion.id})
 
 	return o.stack(
 		o.video(clip, {duration: 4000}),
@@ -170,6 +170,33 @@ const timeline = omni.timeline(o => {
 })
 ```
 
+Built-in spatial animations:
+
+```ts
+const animOut = {
+	duration: 500,
+	offset: item.duration - 500,
+}
+const slideIn = o.animatedSpatial(o.anim.presets.slideIn())
+const slideOut = o.animatedSpatial(o.anim.presets.slideOut(animOut))
+const spinIn = o.animatedSpatial(o.anim.presets.spinIn())
+const spinOut = o.animatedSpatial(o.anim.presets.spinOut(animOut))
+const zoomIn = o.animatedSpatial(o.anim.presets.zoomIn())
+const zoomOut = o.animatedSpatial(o.anim.presets.zoomOut(animOut))
+const bounceIn = o.animatedSpatial(o.anim.presets.bounceIn())
+const bounceOut = o.animatedSpatial(o.anim.presets.bounceOut(animOut))
+```
+
+Built-in scalar animations:
+
+```ts
+const fadeInPreset = o.anim.presets.fadeIn()
+const fadeIn = o.animate.opacity.make(fadeInPreset.terp, fadeInPreset.track)
+
+const fadeOutPreset = o.anim.presets.fadeOut({duration: 500})
+const fadeOut = o.animate.opacity.make(fadeOutPreset.terp, fadeOutPreset.track)
+```
+
 Animation application:
 
 ```ts
@@ -215,29 +242,57 @@ const timeline = omni.timeline(o => {
 })
 ```
 
-Animation registry:
+Animation metadata:
 
 ```ts
-import {animations} from "@omnimedia/omnitool"
+import {animatableProperties, animationPresets} from "@omnimedia/omnitool"
 
-Object.entries(animations).forEach(([property, meta]) => {
+Object.entries(animatableProperties).forEach(([property, meta]) => {
 	console.log(property, meta.type, meta.defaultTerp, meta.channels)
 	// transform transform linear [...]
 	// opacity scalar linear [...]
 })
+
+Object.entries(animationPresets).forEach(([preset, meta]) => {
+	console.log(preset, meta.type, meta.label, meta.defaults)
+	// slideIn motion Slide in {...}
+	// slideOut motion Slide out {...}
+	// spinIn motion Spin in {...}
+	// spinOut motion Spin out {...}
+	// zoomIn motion Zoom in {...}
+	// zoomOut motion Zoom out {...}
+	// bounceIn motion Bounce in {...}
+	// bounceOut motion Bounce out {...}
+	// fadeIn scalar Fade in {...}
+	// fadeOut scalar Fade out {...}
+})
 ```
 
-Each animation definition describes the semantic shape of the animation: its value kind, default interpolation, and numeric channels with defaults and units. This is useful for tools that need to create valid keyframes without hardcoding Omnitool's track layout.
+Animatable properties describe what can be keyframed, such as `transform` and `opacity`.
+Animation presets describe built-in recipes, such as `slideIn` and `fadeIn`, that create animation data.
+Use `animationPresets` to list available recipes, and `o.anim.presets` to create animation data from them.
+
+Preset options:
+- `duration` sets the animation duration, defaulting to `700`.
+- `offset` shifts generated keyframes in item-local time.
+  Useful for out animations: `item.duration - 500` starts `slideOut` 500ms before the item ends.
+- `from` sets the start value, like opacity `0` or position `[-400, 0]`.
+- `to` sets the end value, like opacity `1` or position `[0, 0]`.
+- `terp` sets interpolation, defaulting to the preset's `terp`.
 
 Utils:
 
 ```ts
-import {resolveTransform} from "@omnimedia/omnitool"
+import {resolveScalarAnimation, resolveTransformAnimation} from "@omnimedia/omnitool"
 
-const transform = resolveTransform(spatial, localTime)
+const transform = resolveTransformAnimation(localTime, spatial.anim)
+const opacity = resolveScalarAnimation(localTime, opacityAnimation)
 ```
 
-`resolveTransform` gets a spatial item's current transform. It returns the static transform for `Item.Spatial`, or resolves the animated transform for `Item.AnimatedSpatial` at the given local time.
+`resolveTransformAnimation` resolves an animated transform at the given local time.
+`resolveScalarAnimation` resolves an animated scalar value at the given local time.
+`localTime` is time relative to the item being resolved.
+`clamp` is the default and currently only extrapolation mode, holding the first or last keyframe value outside the authored range.
 
 Worker URL notes:
 - `Driver.setup()` defaults to `/node_modules/@omnimedia/omnitool/x/driver/driver.worker.bundle.min.js`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@omnimedia/omnitool",
-	"version": "1.1.0-82",
+	"version": "1.1.0-84",
 	"description": "open source video processing tools",
 	"license": "MIT",
 	"author": "Przemysław Gałęzki",

package/s/timeline/index.ts

@@ -1,13 +1,13 @@
 
+export * from "./types.js"
 export * from "./parts/basics.js"
-export * from "./parts/animations.js"
 export * from "./parts/filters.js"
 export * from "./parts/item.js"
 export * from "./parts/media.js"
 export * from "./parts/resource-pool.js"
 export * from "./parts/resource.js"
 export * from "./parts/filmstrip.js"
-export * from "./types.js"
+export * from "./parts/animations/registry.js"
 
 export * from "./parts/waveform/waveform.js"
 export * from "./parts/waveform/parts/types.js"

package/s/timeline/parts/animations/make.ts

@@ -0,0 +1,38 @@
+
+import {animationPresets} from "./presets.js"
+import {AnimationPresetActions, MotionAnimationOptions, ScalarAnimationOptions} from "./types.js"
+import {Anim, Interpolation, Keyframes, TrackTransform, Transform, TransformOptions} from "../../types.js"
+
+export function makeAnimationPresets(
+	scalar: (terp: Interpolation, track: Keyframes) => Anim<Keyframes>,
+	transform: (terp: Interpolation, source: Keyframes<Transform>) => Anim<TrackTransform>,
+	transformFrom: (options: TransformOptions) => Transform,
+): AnimationPresetActions {
+	const entries = Object.entries(animationPresets).map(([name, preset]) => {
+		const action = preset.type === "motion"
+			? (options?: MotionAnimationOptions): Anim<TrackTransform> => {
+				const offset = options?.offset ?? 0
+				return transform(options?.terp ?? preset.defaults.terp, [
+					[offset, transformFrom({
+						...preset.transform.from,
+						...(options?.from === undefined ? {} : {position: options.from}),
+					})],
+					[offset + (options?.duration ?? preset.defaults.duration), transformFrom({
+						...preset.transform.to,
+						...(options?.to === undefined ? {} : {position: options.to}),
+					})],
+				])
+			}
+			: (options?: ScalarAnimationOptions): Anim<Keyframes> => {
+				const offset = options?.offset ?? 0
+				return scalar(options?.terp ?? preset.defaults.terp, [
+					[offset, options?.from ?? preset.defaults.from],
+					[offset + (options?.duration ?? preset.defaults.duration), options?.to ?? preset.defaults.to],
+				])
+			}
+
+		return [name, action]
+	})
+
+	return Object.fromEntries(entries) as AnimationPresetActions
+}

package/s/timeline/parts/animations/presets.ts

@@ -0,0 +1,138 @@
+
+import type {AnimationPresetDefinition} from "./types.js"
+
+export const animationPresets = {
+	slideIn: {
+		type: "motion",
+		label: "Slide in",
+		defaults: {
+			duration: 700,
+			from: [-400, 0],
+			to: [0, 0],
+			terp: "easeOut",
+		},
+		transform: {
+			from: {position: [-400, 0]},
+			to: {position: [0, 0]},
+		},
+	},
+	slideOut: {
+		type: "motion",
+		label: "Slide out",
+		defaults: {
+			duration: 700,
+			from: [0, 0],
+			to: [400, 0],
+			terp: "easeIn",
+		},
+		transform: {
+			from: {position: [0, 0]},
+			to: {position: [400, 0]},
+		},
+	},
+	spinIn: {
+		type: "motion",
+		label: "Spin in",
+		defaults: {
+			duration: 700,
+			from: [0, 0],
+			to: [0, 0],
+			terp: "easeOut",
+		},
+		transform: {
+			from: {scale: [0, 0], rotation: -Math.PI},
+			to: {scale: [1, 1], rotation: 0},
+		},
+	},
+	spinOut: {
+		type: "motion",
+		label: "Spin out",
+		defaults: {
+			duration: 700,
+			from: [0, 0],
+			to: [0, 0],
+			terp: "easeIn",
+		},
+		transform: {
+			from: {scale: [1, 1], rotation: 0},
+			to: {scale: [0, 0], rotation: Math.PI},
+		},
+	},
+	zoomIn: {
+		type: "motion",
+		label: "Zoom in",
+		defaults: {
+			duration: 700,
+			from: [0, 0],
+			to: [0, 0],
+			terp: "easeOut",
+		},
+		transform: {
+			from: {scale: [0, 0]},
+			to: {scale: [1, 1]},
+		},
+	},
+	zoomOut: {
+		type: "motion",
+		label: "Zoom out",
+		defaults: {
+			duration: 700,
+			from: [0, 0],
+			to: [0, 0],
+			terp: "easeIn",
+		},
+		transform: {
+			from: {scale: [1, 1]},
+			to: {scale: [0, 0]},
+		},
+	},
+	bounceIn: {
+		type: "motion",
+		label: "Bounce in",
+		defaults: {
+			duration: 700,
+			from: [0, 0],
+			to: [0, 0],
+			terp: "bounce",
+		},
+		transform: {
+			from: {scale: [0, 0]},
+			to: {scale: [1, 1]},
+		},
+	},
+	bounceOut: {
+		type: "motion",
+		label: "Bounce out",
+		defaults: {
+			duration: 700,
+			from: [0, 0],
+			to: [0, 0],
+			terp: "bounce",
+		},
+		transform: {
+			from: {scale: [1, 1]},
+			to: {scale: [0, 0]},
+		},
+	},
+	fadeIn: {
+		type: "scalar",
+		label: "Fade in",
+		defaults: {
+			duration: 700,
+			from: 0,
+			to: 1,
+			terp: "easeIn",
+		},
+	},
+	fadeOut: {
+		type: "scalar",
+		label: "Fade out",
+		defaults: {
+			duration: 700,
+			from: 1,
+			to: 0,
+			terp: "easeOut",
+		},
+	},
+} as const satisfies Record<string, AnimationPresetDefinition>
+

package/s/timeline/parts/{animations.ts → animations/properties.ts}

@@ -1,23 +1,5 @@
 
-import type {Interpolation} from "../types.js"
-
-export type AnimationType = "scalar" | "transform"
-export type AnimationChannelType = "number"
-export type AnimationUnit = "pixel" | "scale" | "radian" | "ratio"
-
-export type AnimationChannel = {
-	path?: string
-	type: AnimationChannelType
-	default: number
-	unit?: AnimationUnit
-	range?: readonly [min: number, max: number]
-}
-
-export type AnimationDefinition = {
-	type: AnimationType
-	defaultTerp: Interpolation
-	channels: readonly AnimationChannel[]
-}
+import type {AnimationDefinition} from "./types.js"
 
 export const spatialAnimations = {
 	transform: {
@@ -45,12 +27,8 @@ export const visualAnimations = {
 
 // const audioAnimations = {}
 
-export const animations = {
+export const animatableProperties = {
 	...spatialAnimations,
 	...visualAnimations,
 } as const
 
-export type SpatialAnimationProperty = keyof typeof spatialAnimations
-export type VisualAnimationProperty = keyof typeof visualAnimations
-export type AnimationProperty = keyof typeof animations
-

package/s/timeline/parts/animations/registry.ts

@@ -0,0 +1,13 @@
+
+import {animationPresets} from "./presets.js"
+import {animatableProperties} from "./properties.js"
+
+export const animationRegistry = {
+	presets: animationPresets,
+	properties: animatableProperties,
+} as const
+
+export * from "./make.js"
+export * from "./presets.js"
+export * from "./properties.js"
+export * from "./types.js"

package/s/timeline/parts/animations/types.ts

@@ -0,0 +1,69 @@
+
+import {animationPresets} from "./presets.js"
+import {spatialAnimations, visualAnimations, animatableProperties} from "./properties.js"
+import {Anim, Interpolation, Keyframes, TrackTransform, TransformOptions, Vec2} from "../../types.js"
+
+export type AnimationType = "scalar" | "transform"
+export type AnimationChannelType = "number"
+export type AnimationUnit = "pixel" | "scale" | "radian" | "ratio"
+
+export type AnimationChannel = {
+	path?: string
+	type: AnimationChannelType
+	default: number
+	unit?: AnimationUnit
+	range?: readonly [min: number, max: number]
+}
+
+export type AnimationDefinition = {
+	type: AnimationType
+	defaultTerp: Interpolation
+	channels: readonly AnimationChannel[]
+}
+
+export type MotionAnimationPresetDefinition = {
+	type: "motion"
+	label: string
+	defaults: Required<Omit<MotionAnimationOptions, "offset">>
+	transform: {
+		from: TransformOptions
+		to: TransformOptions
+	}
+}
+
+export type ScalarAnimationPresetDefinition = {
+	type: "scalar"
+	label: string
+	defaults: Required<Omit<ScalarAnimationOptions, "offset">>
+}
+
+export type AnimationPresetDefinition =
+	| MotionAnimationPresetDefinition
+	| ScalarAnimationPresetDefinition
+
+export type SpatialAnimationProperty = keyof typeof spatialAnimations
+export type VisualAnimationProperty = keyof typeof visualAnimations
+export type AnimationProperty = keyof typeof animatableProperties
+export type AnimationPreset = keyof typeof animationPresets
+
+type AnimationPresetAction<TPreset extends AnimationPresetDefinition> =
+	TPreset extends MotionAnimationPresetDefinition
+		? (options?: MotionAnimationOptions) => Anim<TrackTransform>
+		: TPreset extends ScalarAnimationPresetDefinition
+			? (options?: ScalarAnimationOptions) => Anim<Keyframes>
+			: never
+
+export type AnimationPresetActions = {
+	[TName in AnimationPreset]: AnimationPresetAction<(typeof animationPresets)[TName]>
+}
+
+export type AnimationPresetOptions<Value> = {
+	duration?: number
+	offset?: number
+	from?: Value
+	to?: Value
+	terp?: Interpolation
+}
+
+export type MotionAnimationOptions = AnimationPresetOptions<Vec2>
+export type ScalarAnimationOptions = AnimationPresetOptions<number>

package/s/timeline/sugar/helpers.ts

@@ -5,10 +5,34 @@ import {O} from "./o.js"
 import {Media} from "../parts/media.js"
 import {TimelineFile} from "../parts/basics.js"
 import {FilterAction} from "../parts/filters.js"
-import {visualAnimations} from "../parts/animations.js"
 import {filters, FilterParams, FilterType} from "../parts/filters.js"
 import {Crop, FilterableItem, Item, VisualAnimatableItem} from "../parts/item.js"
-import {Anim, AnimateAction, Interpolation, Keyframes, TrackTransform, Transform, Vec2, VisualAnimations} from "../types.js"
+import {makeAnimationPresets, visualAnimations} from "../parts/animations/registry.js"
+import {Anim, AnimateAction, Interpolation, Keyframes, TrackTransform, Transform, TransformOptions, Vec2, VisualAnimations} from "../types.js"
+
+const transformFrom = (options: TransformOptions): Transform => [
+	options.position ?? [0, 0],
+	options.scale ?? [1, 1],
+	options.rotation ?? 0,
+]
+
+const transformAnimation = (terp: Interpolation, source: Keyframes<Transform>): Anim<TrackTransform> => {
+	const track: TrackTransform = {
+		position: {x: [], y: []},
+		scale: {x: [], y: []},
+		rotation: [],
+	}
+
+	for (const [time, [position, scale, rotation]] of source) {
+		track.position.x.push([time, position[0]])
+		track.position.y.push([time, position[1]])
+		track.scale.x.push([time, scale[0]])
+		track.scale.y.push([time, scale[1]])
+		track.rotation.push([time, rotation])
+	}
+
+	return {terp, track}
+}
 
 export type Build<T extends Item.Any = Item.Any> = (o: O) => T
 type BuildVisualAnimateActions = {
@@ -99,23 +123,13 @@ export const anim = {
 		return {terp, track}
 	},
 
-	transform(terp: Interpolation, source: Keyframes<Transform>): Anim<TrackTransform> {
-		const track: TrackTransform = {
-			position: {x: [], y: []},
-			scale: {x: [], y: []},
-			rotation: [],
-		}
-
-		for (const [time, [position, scale, rotation]] of source) {
-			track.position.x.push([time, position[0]])
-			track.position.y.push([time, position[1]])
-			track.scale.x.push([time, scale[0]])
-			track.scale.y.push([time, scale[1]])
-			track.rotation.push([time, rotation])
-		}
+	transform: transformAnimation,
 
-		return {terp, track}
-	},
+	presets: makeAnimationPresets(
+		(terp, track) => ({terp, track}),
+		transformAnimation,
+		transformFrom,
+	),
 }
 
 interface BuildFilterAction<TFilter extends FilterType> {

package/s/timeline/sugar/o.ts

@@ -5,7 +5,7 @@ import {Media} from "../parts/media.js"
 import {Id, TimelineFile} from "../parts/basics.js"
 import {FilterAction, FilterActions} from "../parts/filters.js"
 import {filters, FilterParams, FilterType} from "../parts/filters.js"
-import {visualAnimations} from "../parts/animations.js"
+import {makeAnimationPresets, visualAnimations} from "../parts/animations/registry.js"
 import {Crop, Effect, FilterableItem, Item, Kind, VisualAnimatableItem} from "../parts/item.js"
 import {Anim, AnimateAction, Interpolation, Keyframes, TrackTransform, Transform, TransformOptions, Vec2, VisualAnimations} from "../types.js"
 
@@ -87,6 +87,24 @@ export class O {
 		return item
 	}
 
+	#transformAnimation = (terp: Interpolation, source: Keyframes<Transform>): Anim<TrackTransform> => {
+		const track: TrackTransform = {
+			position: {x: [], y: []},
+			scale: {x: [], y: []},
+			rotation: [],
+		}
+
+		for (const [time, [position, scale, rotation]] of source) {
+			track.position.x.push([time, position[0]])
+			track.position.y.push([time, position[1]])
+			track.scale.x.push([time, scale[0]])
+			track.scale.y.push([time, scale[1]])
+			track.rotation.push([time, rotation])
+		}
+
+		return {terp, track}
+	}
+
 	anim = {
 		scalar: (terp: Interpolation, track: Keyframes): Anim<Keyframes> => ({terp, track}),
 
@@ -101,23 +119,13 @@ export class O {
 			return {terp, track}
 		},
 
-		transform: (terp: Interpolation, source: Keyframes<Transform>): Anim<TrackTransform> => {
-			const track: TrackTransform = {
-				position: {x: [], y: []},
-				scale: {x: [], y: []},
-				rotation: [],
-			}
-
-			for (const [time, [position, scale, rotation]] of source) {
-				track.position.x.push([time, position[0]])
-				track.position.y.push([time, position[1]])
-				track.scale.x.push([time, scale[0]])
-				track.scale.y.push([time, scale[1]])
-				track.rotation.push([time, rotation])
-			}
+		transform: this.#transformAnimation,
 
-			return {terp, track}
-		},
+		presets: makeAnimationPresets(
+			(terp, track) => ({terp, track}),
+			this.#transformAnimation,
+			options => this.transform(options),
+		),
 	}
 
 	#makeFilter = <TFilter extends FilterType>(type: TFilter) => {

package/s/timeline/utils/anim.ts

@@ -1,7 +1,7 @@
 
 import {resolveTerp} from "./terps.js"
 import {Item, Kind} from "../parts/item.js"
-import {Anim, Keyframes, ScalarAnimation, TrackTransform, Transform} from "../types.js"
+import {Anim, Keyframes, ScalarAnimation, Transform, TransformAnimation} from "../types.js"
 
 const resolveScalar =(
 	time: number,
@@ -44,7 +44,7 @@ const resolveScalar =(
 
 export const resolveTransformAnimation =(
 	time: number,
-	anim: Anim<TrackTransform>,
+	anim: TransformAnimation,
 ): Transform => ([
 	[
 		resolveScalar(time, anim.track.position.x, anim.terp),