Skip to content

🎥 Make videos programmatically with React

10.9 KB
Raw Blame
import {findPropsToDelete} from './find-props-to-delete.js';
import {
	getFrameInKeyframedStatusClock,
	getEffectiveVisualModeValue,
	resolveDragOverrideValue,
} from './get-effective-visual-mode-value.js';
import {
	FILE_TOKEN,
	resolveFileTokenToUrl,
} from './input-props-serialization.js';
import type {
	InteractivitySchema,
	InteractivitySchemaField,
} from './interactivity-schema.js';
import {interpolateKeyframedStatus} from './interpolate-keyframed-status.js';
import type {ExtrapolateType, InterpolateOutputOption} from './interpolate.js';
import type {
	CanUpdateSequencePropsResponse,
	SequencePropsSubscriptionKey,
} from './SequenceManager.js';
import type {VideoConfigValues} from './video-config.js';

export type CanUpdateSequencePropStatusStatic<Numeric = number> = {
	status: 'static';
	codeValue: unknown;
	keyframeDisplayOffsetAdjustment: Numeric | null;
	/** Multiplies the element's local frame to recover the source frame clock. */
	keyframePlaybackRateAdjustment?: Numeric;
	/** False when the source frame clock cannot be represented by the Studio. */
	canKeyframe?: false;
	numericExpression?: VideoConfigNumericExpression;
};

export type CanUpdateSequencePropStatusKeyframe<Numeric = number> = {
	frame: Numeric;
	value: unknown;
	frameExpression?: VideoConfigNumericExpression;
};

/** Source bindings remain independent of the configuration of a mounted instance. */
export type VideoConfigNumericBinding =
	| {type: 'video-config'; field: keyof VideoConfigValues}
	| {type: 'constant'; value: number};

export type VideoConfigNumericExpression =
	| {type: 'literal'; value: number}
	| {
			type: 'video-config-value';
			identifier: string;
			binding: VideoConfigNumericBinding;
	  }
	| {
			type: 'video-config-multiplication';
			identifier: string;
			binding: VideoConfigNumericBinding;
			multiplier: number;
			factorPosition: 'left' | 'right';
	  }
	| {
			type: 'video-config-subtraction';
			identifier: string;
			binding: VideoConfigNumericBinding;
			subtrahend: number;
	  }
	| {
			type: 'binary';
			operator: '+' | '-' | '*' | '/';
			left: SourceNumericValue;
			right: SourceNumericValue;
	  };

export type SourceNumericValue = number | VideoConfigNumericExpression;
export type CanUpdateSequencePropSource =
	CanUpdateSequencePropStatus<SourceNumericValue>;

export type CanUpdateSequencePropStatusLinearEasing = {
	type: 'linear';
};

export type CanUpdateSequencePropStatusStep1Easing = {
	type: 'step1';
};

export type CanUpdateSequencePropStatusBezierEasing = {
	type: 'bezier';
	x1: number;
	y1: number;
	x2: number;
	y2: number;
};

export type CanUpdateSequencePropStatusSpringEasing = {
	type: 'spring';
	allowTail: boolean | null;
	damping: number;
	mass: number;
	stiffness: number;
	overshootClamping: boolean;
	durationRestThreshold: number | null;
};

export type CanUpdateSequencePropStatusEasing =
	| CanUpdateSequencePropStatusLinearEasing
	| CanUpdateSequencePropStatusStep1Easing
	| CanUpdateSequencePropStatusBezierEasing
	| CanUpdateSequencePropStatusSpringEasing;

export const DEFAULT_LINEAR_EASING: CanUpdateSequencePropStatusLinearEasing = {
	type: 'linear',
};

const getEasingIndexToDuplicate = ({
	insertedKeyframeIndex,
	easingLength,
	keyframeCount,
}: {
	insertedKeyframeIndex: number;
	easingLength: number;
	keyframeCount: number;
}): number | null => {
	const isSplittingExistingSegment =
		insertedKeyframeIndex > 0 && insertedKeyframeIndex < keyframeCount - 1;

	if (!isSplittingExistingSegment || easingLength === 0) {
		return null;
	}

	return Math.min(insertedKeyframeIndex - 1, easingLength - 1);
};

export type CanUpdateSequencePropStatusClamping = {
	left: ExtrapolateType;
	right: ExtrapolateType;
};

export type CanUpdateSequencePropStatusInterpolationFunction =
	| 'interpolate'
	| 'interpolateColors'
	| 'interpolatePaths';

export type CanUpdateSequencePropStatusComputed = {
	status: 'computed';
};

export type CanUpdateSequencePropStatusKeyframed<Numeric = number> = {
	status: 'keyframed';
	interpolationFunction: CanUpdateSequencePropStatusInterpolationFunction;
	/**
	 * Subtracted after applying keyframePlaybackRateAdjustment to the controlled
	 * element's local frame when evaluating the interpolation.
	 * This is non-zero when the useCurrentFrame() call is outside a timing
	 * element that wraps the controlled element.
	 */
	keyframeDisplayOffsetAdjustment: Numeric | null;
	/** Defaults to 1 for statuses produced without a playback rate conversion. */
	keyframePlaybackRateAdjustment?: Numeric;
	keyframes: CanUpdateSequencePropStatusKeyframe<Numeric>[];
	easing: CanUpdateSequencePropStatusEasing[];
	clamping: CanUpdateSequencePropStatusClamping;
	posterize: number | undefined;
	output: InterpolateOutputOption | undefined;
};

export type CanUpdateSequencePropStatusFalse =
	CanUpdateSequencePropStatusComputed;

export type CanUpdateSequencePropStatus<Numeric = number> =
	| CanUpdateSequencePropStatusStatic<Numeric>
	| CanUpdateSequencePropStatusKeyframed<Numeric>
	| CanUpdateSequencePropStatusFalse;

export type DragOverrideValue =
	| {
			readonly type: 'static';
			readonly value: unknown;
	  }
	| {
			readonly type: 'keyframed';
			readonly status: CanUpdateSequencePropStatusKeyframed;
	  };

export type DragOverrides = Record<string, Record<string, DragOverrideValue>>;
export type EffectDragOverrides = Record<
	string,
	Record<string, DragOverrideValue>
>;
export type PropStatuses = Record<string, CanUpdateSequencePropsResponse>;

export type GetPropStatuses = (
	nodePath: SequencePropsSubscriptionKey,
) => Record<string, CanUpdateSequencePropStatus> | undefined;

export type GetEffectPropStatuses = (
	nodePath: SequencePropsSubscriptionKey,
	effectIndex: number,
) => Record<string, CanUpdateSequencePropStatus> | undefined;

export type GetDragOverrides = (
	nodePath: SequencePropsSubscriptionKey,
) => DragOverrides[string];

export type GetEffectDragOverrides = (
	nodePath: SequencePropsSubscriptionKey,
	effectIndex: number,
) => Record<string, DragOverrideValue>;

export const makeStaticDragOverride = (value: unknown): DragOverrideValue => {
	return {type: 'static', value};
};

export const makeKeyframedDragOverride = ({
	status,
	frame,
	value,
	defaultEasing = DEFAULT_LINEAR_EASING,
}: {
	status: CanUpdateSequencePropStatusKeyframed;
	frame: number;
	value: unknown;
	defaultEasing?: CanUpdateSequencePropStatusEasing;
}): DragOverrideValue => {
	const existingIndex = status.keyframes.findIndex(
		(keyframe) => keyframe.frame === frame,
	);
	const keyframes =
		existingIndex === -1
			? [...status.keyframes, {frame, value}].sort(
					(first, second) => first.frame - second.frame,
				)
			: status.keyframes.map((keyframe, index) =>
					index === existingIndex ? {frame, value} : keyframe,
				);
	const easing = [...status.easing];
	if (existingIndex === -1) {
		const insertedKeyframeIndex = keyframes.findIndex(
			(keyframe) => keyframe.frame === frame,
		);
		const easingIndexToDuplicate = getEasingIndexToDuplicate({
			insertedKeyframeIndex,
			easingLength: easing.length,
			keyframeCount: keyframes.length,
		});
		const easingToDuplicate =
			easingIndexToDuplicate === null
				? defaultEasing
				: easing[easingIndexToDuplicate];
		easing.splice(insertedKeyframeIndex, 0, easingToDuplicate);
	}

	while (easing.length < keyframes.length - 1) {
		easing.push(defaultEasing);
	}

	if (easing.length > keyframes.length - 1) {
		easing.length = keyframes.length - 1;
	}

	return {
		type: 'keyframed',
		status: {
			...status,
			keyframes,
			easing,
		},
	};
};

export const getStaticDragOverrideValue = (
	dragOverrideValue: DragOverrideValue | undefined,
): unknown => {
	if (dragOverrideValue?.type !== 'static') {
		return undefined;
	}

	return dragOverrideValue.value;
};

export const isKeyframedStatus = (
	status: CanUpdateSequencePropStatus | null,
): status is CanUpdateSequencePropStatusKeyframed => {
	return status !== null && status.status === 'keyframed';
};

const findFieldInSchema = (
	schema: InteractivitySchema,
	key: string,
): InteractivitySchemaField | undefined => {
	if (key in schema) {
		return schema[key];
	}

	for (const field of Object.values(schema)) {
		if (field.type !== 'enum') {
			continue;
		}

		for (const variant of Object.values(field.variants)) {
			const found = findFieldInSchema(variant, key);
			if (found) {
				return found;
			}
		}
	}

	return undefined;
};

export const computeEffectiveSchemaValuesDotNotation = ({
	schema,
	currentValue,
	overrideValues,
	propStatus,
	frame,
}: {
	schema: InteractivitySchema;
	currentValue: Record<string, unknown>;
	overrideValues: Record<string, DragOverrideValue>;
	propStatus: Record<string, CanUpdateSequencePropStatus> | undefined;
	frame: number | null;
}): {merged: Record<string, unknown>; propsToDelete: Set<string>} => {
	const merged: Record<string, unknown> = {};
	const propsToDelete = new Set<string>();
	for (const key of Object.keys(currentValue)) {
		const status = propStatus?.[key] ?? null;
		const field = findFieldInSchema(schema, key);

		if (field?.type === 'hidden') {
			continue;
		}

		let value: unknown;
		if (status === null) {
			// Without a source status (for example outside the Studio), an
			// override still previews on top of the runtime value.
			const dragOverride = resolveDragOverrideValue({
				dragOverrideValue: overrideValues[key],
				frame,
			});
			value =
				dragOverride.type === 'resolved'
					? dragOverride.value
					: currentValue[key];
		} else if (isKeyframedStatus(status)) {
			// keyframable controls authoring new keyframes in Studio. Existing
			// keyframes still need to follow the preview clock and drag overrides.
			if (field?.type === 'array') {
				value = currentValue[key];
			} else {
				const dragOverride = resolveDragOverrideValue({
					dragOverrideValue: overrideValues[key],
					frame,
				});
				if (dragOverride.type === 'resolved') {
					value = dragOverride.value;
				} else if (frame !== null) {
					const interpolated = interpolateKeyframedStatus({
						forceSpringAllowTail: null,
						frame: getFrameInKeyframedStatusClock({frame, status}),
						status,
					});
					value = interpolated ?? currentValue[key];
				} else {
					value = currentValue[key];
				}
			}
		} else if (status.status === 'computed') {
			value = currentValue[key];
		} else {
			value = getEffectiveVisualModeValue({
				propStatus: status,
				dragOverrideValue: overrideValues[key],
				defaultValue: field?.default,
				frame,
				shouldResortToDefaultValueIfUndefined: false,
			});
		}

		if (
			field?.type === 'asset' &&
			typeof value === 'string' &&
			value.startsWith(FILE_TOKEN)
		) {
			value = resolveFileTokenToUrl(value);
		}

		if (value === undefined) {
			propsToDelete.add(key);
		}

		merged[key] = value;
	}

	for (const key of Object.keys(overrideValues)) {
		if (schema[key]?.type === 'enum') {
			const propsToDeleteForKey = findPropsToDelete({
				schema,
				key,
				value: merged[key],
			});
			for (const propToDelete of propsToDeleteForKey) {
				propsToDelete.add(propToDelete);
			}
		}
	}

	return {merged, propsToDelete};
};