🎥 Make videos programmatically with React
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};
};