@omnimedia/omnitool 1.1.0-104 → 1.1.0-106

package/README.md

@@ -56,6 +56,19 @@ const timeline = omni.timeline(o => {
 })
 ```
 
+Items can have `label` and `enabled` fields:
+
+```ts
+const visual = o.sequence(
+	"Main sequence",
+	o.video(clip, {label: "Intro"}),
+	o.transition.fade(500, {label: "Fade", enabled: false}),
+	o.text("Hello world", {label: "Title", enabled: false})
+)
+```
+
+Disabled items do not render or play audio, but still keep their timeline duration and occupy space.
+
 Declarative helper style (no explicit `o` in timeline declarations):
 
 ```ts

package/package.json

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

package/s/timeline/parts/captions.ts

@@ -5,6 +5,8 @@ import {TransformOptions, Vec2} from "../types.js"
 import {Transcription, TranscriptSegment} from "../../features/speech/transcribe/types.js"
 
 export type CaptionOptions = {
+	label?: string
+	enabled?: boolean
 	itemId?: Item.Caption["itemId"]
 	start?: number
 	duration?: number

package/s/timeline/parts/item.ts

@@ -26,11 +26,17 @@ export enum Kind {
 	Image
 }
 
+export type ItemBase = {
+	label?: string
+	enabled?: boolean
+}
+
 export namespace Item {
 	export type TextStyle = {
 		id: Id
 		kind: Kind.TextStyle
 		style: TextStyleOptions
+		enabled?: boolean
 	}
 
 	export type Spatial = {
@@ -38,14 +44,14 @@ export namespace Item {
 		kind: Kind.Spatial
 		transform: Transform
 		crop?: Crop
-		enabled: boolean
+		enabled?: boolean
 	}
 
 	export type Animation = {
 		id: Id
 		kind: Kind.Animation
 		anims: VisualAnimations
-		enabled: boolean
+		enabled?: boolean
 	}
 
 	export type Filter<T extends FilterType = FilterType> = {
@@ -53,14 +59,14 @@ export namespace Item {
 		kind: Kind.Filter
 		type: T
 		params?: FilterParams<T>
-		enabled: boolean
+		enabled?: boolean
 	}
 
 	export type Gap = {
 		id: Id
 		kind: Kind.Gap
 		duration: number
-	}
+	} & ItemBase
 
 	export type Sequence = {
 		id: Id
@@ -68,7 +74,7 @@ export namespace Item {
 		childrenIds: Id[]
 		spatialId?: Id
 		filterIds?: Id[]
-	}
+	} & ItemBase
 
 	export type Stack = {
 		id: Id
@@ -76,7 +82,7 @@ export namespace Item {
 		childrenIds: Id[]
 		spatialId?: Id
 		filterIds?: Id[]
-	}
+	} & ItemBase
 
 	export type Video = {
 		id: Id
@@ -87,7 +93,7 @@ export namespace Item {
 		spatialId?: Id
 		animationIds?: Id[]
 		filterIds?: Id[]
-	}
+	} & ItemBase
 
 	export type Image = {
 		id: Id
@@ -97,7 +103,7 @@ export namespace Item {
 		spatialId?: Id
 		animationIds?: Id[]
 		filterIds?: Id[]
-	}
+	} & ItemBase
 
 	export type Audio = {
 		id: Id
@@ -106,7 +112,7 @@ export namespace Item {
 		start: number
 		duration: number
 		gain?: number
-	}
+	} & ItemBase
 
 	export type Text = {
 		id: Id
@@ -117,7 +123,7 @@ export namespace Item {
 		animationIds?: Id[]
 		styleId?: Id
 		filterIds?: Id[]
-	}
+	} & ItemBase
 
 
 	export type Caption = {
@@ -134,14 +140,14 @@ export namespace Item {
 		animationIds?: Id[]
 		styleId?: Id
 		filterIds?: Id[]
-	}
+	} & ItemBase
 
 	export type Transition = {
 		id: Id
 		kind: Kind.Transition
 		name: TransitionName
 		duration: number
-	}
+	} & ItemBase
 
 	export type Any = (
 		| Sequence

package/s/timeline/parts/transitions.ts

@@ -1,4 +1,4 @@
-import type {Item} from "./item.js"
+import type {Item, ItemBase} from "./item.js"
 
 export const transitionNames = [
 	"Bounce",
@@ -78,7 +78,7 @@ export type Transition = {
 }
 
 export interface TransitionAction {
-	(duration: number): Item.Transition
+	(duration: number, options?: ItemBase): Item.Transition
 }
 
 export type TransitionActions = {

package/s/timeline/renderers/parts/handy.ts

@@ -110,7 +110,7 @@ function applySpatialIfAny(
 	let matrix = parentMatrix
 	if ("spatialId" in item && item.spatialId) {
 		const spatial = items.get(item.spatialId) as Item.Spatial | undefined
-		if (spatial?.enabled) {
+		if (spatial && spatial.enabled !== false) {
 			const local = transformToMat6(spatial.transform)
 			matrix = mul6(local, matrix)
 		}
@@ -120,7 +120,7 @@ function applySpatialIfAny(
 		for (const id of item.animationIds) {
 			const animation = items.get(id) as Item.Animation | undefined
 			const anim = animation?.anims.transform
-			if (animation?.enabled && anim && transformActiveAt(anim, time)) {
+			if (animation?.enabled !== false && anim && transformActiveAt(anim, time)) {
 				const local = transformToMat6(resolveTransformAnimation(time, anim))
 				matrix = mul6(local, matrix)
 			}
@@ -410,7 +410,7 @@ export function computeOpacity(
 	for (const id of item.animationIds) {
 		const animation = ctx.items.get(id) as Item.Animation | undefined
 		const anim = animation?.anims.opacity
-		if (animation?.enabled && anim && keyframesActiveAt(anim.track, time))
+		if (animation?.enabled !== false && anim && keyframesActiveAt(anim.track, time))
 			opacity = resolveScalarAnimation(time, anim)
 	}
 	return opacity

package/s/timeline/renderers/parts/samplers/audio/parts/init.ts

@@ -15,6 +15,8 @@ export async function initStreams(
 		items.map(async ({item, localTime}) => {
 			if (item.kind !== Kind.Audio)
 				return
+			if (item.enabled === false)
+				return
 
 			const sink = await pool.getSink(item.mediaHash)
 			if (!sink)

package/s/timeline/renderers/parts/samplers/visual/parts/sample.ts

@@ -17,6 +17,9 @@ export async function sampleVisual(
 		allowHandles?: boolean
 	} = {}
 ): Promise<Layer[]> {
+	if ("enabled" in item && item.enabled === false)
+		return item.kind === Kind.Gap ? [{id: item.id, kind: "gap"}] : []
+
 	const matrix = computeWorldMatrix(ctx.items, ancestors, item, time)
 	const alpha = computeOpacity(ctx, item, time)
 	const crop = "spatialId" in item && item.spatialId
@@ -25,7 +28,7 @@ export async function sampleVisual(
 	const filters = "filterIds" in item && item.filterIds
 		? item.filterIds
 			.map(id => ctx.items.get(id) as Item.Filter | undefined)
-			.filter((filter): filter is Item.Filter => !!filter?.enabled)
+			.filter((filter): filter is Item.Filter => !!filter && filter.enabled !== false)
 			.map(filter => ({type: filter.type, params: filter.params}) as FilterSpec)
 		: undefined
 
@@ -63,9 +66,10 @@ export async function sampleVisual(
 		case Kind.Text: {
 			if (!options.allowHandles && (time < 0 || time >= item.duration)) return []
 
-			const style = item.styleId
-				? (ctx.items.get(item.styleId) as Item.TextStyle)?.style
+			const textStyle = item.styleId
+				? ctx.items.get(item.styleId) as Item.TextStyle | undefined
 				: undefined
+			const style = textStyle?.enabled !== false ? textStyle?.style : undefined
 
 			return [{id: item.id, kind: "text", content: item.content, style, matrix, alpha, crop, filters}]
 		}
@@ -81,9 +85,10 @@ export async function sampleVisual(
 			if (!segment)
 				return []
 
-			const style = item.styleId
-				? (ctx.items.get(item.styleId) as Item.TextStyle)?.style
+			const textStyle = item.styleId
+				? ctx.items.get(item.styleId) as Item.TextStyle | undefined
 				: undefined
+			const style = textStyle?.enabled !== false ? textStyle?.style : undefined
 
 			return [{id: item.id, kind: "text", content: segment.text, style, matrix, alpha, crop, filters}]
 		}

package/s/timeline/renderers/parts/samplers/visual/parts/sequence.ts

@@ -53,6 +53,9 @@ function sampleSequenceAt(ctx: SampleContext, seq: Item.Sequence, time: Ms) {
 
 		const localTime = ms(time - cursor)
 
+		if (child.enabled === false)
+			return {isTransitioning: false, item: child, localTime} as const
+
 		if (child.kind !== Kind.Transition)
 			return {isTransitioning: false, item: child, localTime} as const
 

package/s/timeline/renderers/renderers.test.ts

@@ -92,6 +92,21 @@ export default Science.suite({
 		expect(textLayer[0].kind).is("text")
 	}),
 
+	"disabled visual item keeps sequence time but does not render": test(async () => {
+		const {omni, videoA, resolveMedia} = await setupTest()
+		const {timeline} = new O({timeline: omni.timeline(o => o.sequence(
+			o.video(videoA, {duration: 2000, enabled: false}),
+			o.video(videoA, {duration: 2000}),
+		))})
+		const sampler = createVisualSampler(resolveMedia)
+
+		const disabledLayers = await sampler.sample(timeline, ms(1000))
+		expect(disabledLayers.length).is(0)
+
+		const nextLayers = await sampler.sample(timeline, ms(2500))
+		expect(nextLayers[0].kind).is("image")
+	}),
+
 	"audio mix sums overlapping chunks": test(async () => {
 		const mixer = new AudioMix({chunkFrames: 4, clamp: false})
 		async function *samples() {

package/s/timeline/sugar/helpers.ts

@@ -10,7 +10,7 @@ import {filters, FilterParams, FilterType} from "../parts/filters.js"
 import {CaptionOptions, CaptionSourceItem} from "../parts/captions.js"
 import {Transcription} from "../../features/speech/transcribe/types.js"
 import {AnimationPreset, PresetOptions} from "../parts/animations/types.js"
-import {Crop, FilterableItem, Item, VisualAnimatableItem} from "../parts/item.js"
+import {Crop, FilterableItem, Item, ItemBase, VisualAnimatableItem} from "../parts/item.js"
 import {animationPresets, visualAnimations} from "../parts/animations/registry.js"
 import {Anim, AnimateAction, Interpolation, Keyframes, TrackTransform, Transform, Vec2, VisualAnimationInput, VisualAnimations} from "../types.js"
 
@@ -22,8 +22,9 @@ type BuildPresetAnimateActions = {
 	[TKey in AnimationPreset]: BuildPresetAnimateAction
 }
 type BuildTransitionActions = {
-	[TKey in TransitionName]: (duration: number) => Build<Item.Transition>
+	[TKey in TransitionName]: (duration: number, options?: ItemBase) => Build<Item.Transition>
 }
+type ContainerInput = [label: string, ...items: Build[]] | Build[]
 
 function createTimeline(): TimelineFile {
 	return {
@@ -42,12 +43,24 @@ export function timeline(root: Build): TimelineFile {
 	return o.timeline
 }
 
-export function sequence(...items: Build[]): Build<Item.Sequence> {
-	return o => o.sequence(...items.map(item => item(o)))
+export function sequence(...input: ContainerInput): Build<Item.Sequence> {
+	const [first, ...rest] = input
+	const label = typeof first === "string" ? first : undefined
+	const items = (label ? rest : input) as Build[]
+	return o => {
+		const built = items.map(item => item(o))
+		return label ? o.sequence(label, ...built) : o.sequence(...built)
+	}
 }
 
-export function stack(...items: Build[]): Build<Item.Stack> {
-	return o => o.stack(...items.map(item => item(o)))
+export function stack(...input: ContainerInput): Build<Item.Stack> {
+	const [first, ...rest] = input
+	const label = typeof first === "string" ? first : undefined
+	const items = (label ? rest : input) as Build[]
+	return o => {
+		const built = items.map(item => item(o))
+		return label ? o.stack(label, ...built) : o.stack(...built)
+	}
 }
 
 export function video(
@@ -55,6 +68,8 @@ export function video(
 	options?: {
 		start?: number,
 		duration?: number
+		label?: string
+		enabled?: boolean
 	}
 ): Build<Item.Video> {
 	return o => o.video(media, options)
@@ -64,6 +79,8 @@ export function image(
 	media: Media,
 	options?: {
 		duration?: number
+		label?: string
+		enabled?: boolean
 	}
 ): Build<Item.Image> {
 	return o => o.image(media, options)
@@ -75,6 +92,8 @@ export function audio(
 		start?: number,
 		duration?: number,
 		gain?: number
+		label?: string
+		enabled?: boolean
 	}
 ): Build<Item.Audio> {
 	return o => o.audio(media, options)
@@ -85,6 +104,8 @@ export function text(
 	options?: {
 		duration?: number,
 		styles?: TextStyleOptions
+		label?: string
+		enabled?: boolean
 	}
 ): Build<Item.Text> {
 	return o => o.text(content, options)
@@ -98,8 +119,8 @@ export function captions(
 	return o => o.captions(item(o), transcript, options)
 }
 
-export function gap(duration: number): Build<Item.Gap> {
-	return o => o.gap(duration)
+export function gap(duration: number, options?: ItemBase): Build<Item.Gap> {
+	return o => o.gap(duration, options)
 }
 
 export function spatial(transform?: Transform, crop?: Crop): Build<Item.Spatial> {
@@ -232,7 +253,7 @@ export function textStyle(style: TextStyleOptions): Build<Item.TextStyle> {
 
 function makeTransitionActions(): BuildTransitionActions {
 	const entries = Object.keys(transitions)
-		.map(key => [key, (duration: number) => (o: O) => o.transition[key as TransitionName](duration)])
+		.map(key => [key, (duration: number, options?: ItemBase) => (o: O) => o.transition[key as TransitionName](duration, options)])
 	return Object.fromEntries(entries) as BuildTransitionActions
 }
 

package/s/timeline/sugar/o.ts

@@ -6,7 +6,7 @@ import {Id, TimelineFile} from "../parts/basics.js"
 import {FilterAction, FilterActions} from "../parts/filters.js"
 import {filters, FilterParams, FilterType} from "../parts/filters.js"
 import {Transcription} from "../../features/speech/transcribe/types.js"
-import {Crop, FilterableItem, Item, Kind, VisualAnimatableItem} from "../parts/item.js"
+import {Crop, FilterableItem, Item, ItemBase, Kind, VisualAnimatableItem} from "../parts/item.js"
 import {animationPresets, makeAnimationPresets, visualAnimations} from "../parts/animations/registry.js"
 import {TransitionAction, TransitionActions, transitions, TransitionName} from "../parts/transitions.js"
 import {AnimationPreset, PresetAnimateAction, PresetAnimateActions, PresetAnimation, PresetOptions} from "../parts/animations/types.js"
@@ -17,6 +17,8 @@ type VisualAnimateActions = {
 	[TKey in keyof VisualAnimations]-?: AnimateAction<TKey>
 }
 
+type ContainerInput = [label: string, ...items: Item.Any[]] | Item.Any[]
+
 export class O {
 	constructor(public state: {timeline: TimelineFile}) {}
 
@@ -50,7 +52,7 @@ export class O {
 		const item = {
 			id: this.getId(),
 			kind: Kind.TextStyle,
-			style
+			style,
 		} as Item.TextStyle
 		this.register(item)
 		return item
@@ -62,7 +64,6 @@ export class O {
   		kind: Kind.Spatial,
   		transform: transform ?? this.transform(),
   		crop,
-  		enabled: true
   	}
 		this.register(item)
   	return item
@@ -73,7 +74,6 @@ export class O {
 			id: this.getId(),
 			kind: Kind.Animation,
 			anims,
-			enabled: true
 		}
 		this.register(item)
 		return item
@@ -134,7 +134,6 @@ export class O {
 				kind: Kind.Filter,
 				type,
 				params,
-				enabled: true
 			}
 			this.register(item)
 			return item
@@ -229,20 +228,28 @@ export class O {
 		presets: this.#makePresetAnimateActions(),
 	}
 
-	sequence = (...items: Item.Any[]): Item.Sequence => {
+	sequence = (...input: ContainerInput): Item.Sequence => {
+		const [first, ...rest] = input
+		const label = typeof first === "string" ? first : undefined
+		const items = (label ? rest : input) as Item.Any[]
 		const item =  {
 			id: this.getId(),
 			kind: Kind.Sequence,
+			label,
 			childrenIds: items.map(item => item.id)
 		} as Item.Sequence
 		this.register(item)
 		return item
 	}
 
-	stack = (...items: Item.Any[]): Item.Stack => {
+	stack = (...input: ContainerInput): Item.Stack => {
+		const [first, ...rest] = input
+		const label = typeof first === "string" ? first : undefined
+		const items = (label ? rest : input) as Item.Any[]
 		const item = {
 			kind: Kind.Stack,
 			id: this.getId(),
+			label,
 			childrenIds: items.map(item => item.id)
 		} as Item.Stack
 		this.register(item)
@@ -254,6 +261,8 @@ export class O {
 		options?: {
 			start?: number,
 			duration?: number
+			label?: string
+			enabled?: boolean
 		}): Item.Video => {
 
 		if(!media.hasVideo)
@@ -262,6 +271,8 @@ export class O {
 		const item: Item.Video = {
 			kind: Kind.Video,
 			id: this.getId(),
+			label: options?.label,
+			enabled: options?.enabled,
 			mediaHash: media.datafile.checksum.hash,
 			start: options?.start ?? 0,
 			duration: options?.duration ?? media.duration
@@ -274,6 +285,8 @@ export class O {
 		media: Media,
 		options?: {
 			duration?: number
+			label?: string
+			enabled?: boolean
 		}): Item.Image => {
 
 		if(!media.isImage)
@@ -282,6 +295,8 @@ export class O {
 		const item: Item.Image = {
 			kind: Kind.Image,
 			id: this.getId(),
+			label: options?.label,
+			enabled: options?.enabled,
 			mediaHash: media.datafile.checksum.hash,
 			duration: options?.duration ?? 2000
 		}
@@ -295,6 +310,8 @@ export class O {
 			start?: number,
 			duration?: number,
 			gain?: number
+			label?: string
+			enabled?: boolean
 		}): Item.Audio => {
 
 		if(!media.hasAudio)
@@ -303,6 +320,8 @@ export class O {
 		const item: Item.Audio = {
 			kind: Kind.Audio,
 			id: this.getId(),
+			label: options?.label,
+			enabled: options?.enabled,
 			mediaHash: media.datafile.checksum.hash,
 			start: options?.start ?? 0,
 			duration: options?.duration ?? media.duration,
@@ -315,10 +334,14 @@ export class O {
 	text = (content: string, options?: {
 			duration?: number,
 			styles?: TextStyleOptions
+			label?: string
+			enabled?: boolean
 		}): Item.Text => {
 
 		const item = {
 			id: this.getId(),
+			label: options?.label,
+			enabled: options?.enabled,
 			content,
 			kind: Kind.Text,
 			duration: options?.duration ?? 2000
@@ -341,6 +364,8 @@ export class O {
 		const item: Item.Caption = {
 			id: this.getId(),
 			kind: Kind.Caption,
+			label: options?.label,
+			enabled: options?.enabled,
 			transcript,
 			itemId: options?.itemId,
 			start,
@@ -386,10 +411,12 @@ export class O {
 		{presets: this.#makeCaptionPresetActions()}
 	) as CaptionActions
 
-	gap = (duration: number): Item.Gap => {
+	gap = (duration: number, options?: ItemBase): Item.Gap => {
 		const item = {
 			id: this.getId(),
 			kind: Kind.Gap,
+			label: options?.label,
+			enabled: options?.enabled,
 			duration
 		} as Item.Gap
 		this.register(item)
@@ -397,10 +424,12 @@ export class O {
 	}
 
 	#makeTransition = (key: TransitionName): TransitionAction => {
-		return (duration: number): Item.Transition => {
+		return (duration: number, options?: ItemBase): Item.Transition => {
 			const item: Item.Transition = {
 				id: this.getId(),
 				kind: Kind.Transition,
+				label: options?.label,
+				enabled: options?.enabled,
 				name: transitions[key].name,
 				duration,
 			}