π₯ Make videos programmatically with React
import React, {
createContext,
forwardRef,
useContext,
useLayoutEffect,
useMemo,
useState,
} from 'react';
import {CanUseRemotionHooks} from './CanUseRemotionHooks.js';
import type {
JsxComponentIdentity,
SequenceControls,
} from './CompositionManager.js';
import {deleteNestedKey} from './delete-nested-key.js';
import {getPropStatusesForSequenceStatus} from './effects/use-memoized-effects.js';
import {
getStackForControls,
setStackForControls,
} from './enable-sequence-stack-traces.js';
import {
flattenActiveSchema,
getFlatSchemaWithAllKeys,
} from './flatten-schema.js';
import {
extendSchemaWithSequenceName,
type InteractivitySchema,
} from './interactivity-schema.js';
import {
OptimisticSequenceDeletion,
usePendingSequenceDeletions,
} from './optimistic-sequence-deletion.js';
import {createRuntimeValueStore} from './runtime-value-store.js';
import {OverrideIdsToNodePathsGettersContext} from './sequence-node-path.js';
import {
useDragOverridesForNodePath,
usePropStatusForNodePath,
} from './SequenceManager.js';
import {useCurrentFrameWithOptionalSubscription} from './use-current-frame.js';
import {useRemotionEnvironment} from './use-remotion-environment.js';
import {computeEffectiveSchemaValuesDotNotation} from './use-schema.js';
import {useUnsafeVideoConfig} from './use-unsafe-video-config.js';
export const getNestedValue = (
obj: Record<string, unknown>,
key: string,
): unknown => {
const parts = key.split('.');
let current: unknown = obj;
for (const part of parts) {
if (
current === null ||
current === undefined ||
typeof current !== 'object'
)
return undefined;
current = (current as Record<string, unknown>)[part];
}
return current;
};
export const getRuntimeValueForSchemaKey = ({
flatSchema,
key,
props,
}: {
flatSchema: InteractivitySchema;
key: string;
props: Record<string, unknown>;
}): unknown => {
const value = getNestedValue(props, key);
if (
(flatSchema[key]?.type === 'string' ||
flatSchema[key]?.type === 'text-content') &&
typeof value !== 'string'
) {
return undefined;
}
return value;
};
export const readValuesFromProps = (
props: Record<string, unknown>,
keys: string[],
flatSchema?: InteractivitySchema,
): Record<string, unknown> => {
const out: Record<string, unknown> = {};
for (const key of keys) {
out[key] = flatSchema
? getRuntimeValueForSchemaKey({flatSchema, key, props})
: getNestedValue(props, key);
}
return out;
};
export const selectActiveKeys = (
schema: InteractivitySchema,
values: Record<string, unknown>,
): string[] => {
return Object.keys(flattenActiveSchema(schema, (key) => values[key]));
};
export const mergeValues = ({
flatSchema,
props,
valuesDotNotation,
schemaKeys,
propsToDelete,
}: {
flatSchema: InteractivitySchema;
props: Record<string, unknown>;
valuesDotNotation: Record<string, unknown>;
schemaKeys: string[];
propsToDelete: Set<string>;
}): Record<string, unknown> => {
const merged = {...props};
for (const key of schemaKeys) {
const value = valuesDotNotation[key];
if (
(flatSchema[key]?.type === 'string' ||
flatSchema[key]?.type === 'text-content') &&
value === undefined
) {
continue;
}
const parts = key.split('.');
if (parts.length === 1) {
merged[key] = value;
continue;
}
// For dot-notation keys like 'style.opacity',
// clone and set the nested path
let current = merged;
for (let i = 0; i < parts.length - 1; i++) {
const part = parts[i];
if (typeof current[part] === 'object' && current[part] !== null) {
current[part] = {...(current[part] as Record<string, unknown>)};
} else {
current[part] = {};
}
current = current[part] as Record<string, unknown>;
}
current[parts[parts.length - 1]] = value;
}
const propsToDeleteWithoutTextContent = new Set(
[...propsToDelete].filter(
(key) =>
!(
(flatSchema[key]?.type === 'string' ||
flatSchema[key]?.type === 'text-content') &&
valuesDotNotation[key] === undefined
),
),
);
deleteNestedKey(merged, propsToDeleteWithoutTextContent);
return merged;
};
export type WithInteractivitySchemaOptions<
S extends InteractivitySchema,
Props extends object,
> = {
Component: React.ComponentType<
Props & {readonly controls: SequenceControls | undefined}
>;
componentName: string;
/** @internal */
componentIdentity?: JsxComponentIdentity | null;
schema: S;
supportsEffects: boolean;
};
const DisableInteractivityContext = createContext(false);
export const DisableInteractivityProvider: React.FC<{
readonly children: React.ReactNode;
}> = ({children}) => {
return React.createElement(
DisableInteractivityContext.Provider,
{value: true},
children,
);
};
// Authoring surfaces outside the Studio, such as @remotion/sdk, opt into
// populating `controls` and applying Visual Mode overrides.
const EnableInteractivityContext = createContext(false);
export const EnableInteractivityProvider: React.FC<{
readonly children: React.ReactNode;
}> = ({children}) => {
return React.createElement(
EnableInteractivityContext.Provider,
{value: true},
children,
);
};
export const withInteractivitySchema = <
S extends InteractivitySchema,
Props extends object,
>({
Component,
componentName,
componentIdentity = null,
schema,
supportsEffects,
}: WithInteractivitySchemaOptions<S, Props>): React.ComponentType<Props> => {
// Schema is static for a component, so we move this outside
const schemaWithSequenceName = extendSchemaWithSequenceName(schema);
const flatSchema = getFlatSchemaWithAllKeys(schemaWithSequenceName);
const flatKeys = Object.keys(flatSchema);
// A structural edit can put a different component at the same stack.
// Only reuse overrides for instances of this component.
const stackToOverrideMap: Record<string, string> = {};
const Wrapped = forwardRef<unknown, Props>((props, ref) => {
const {
_remotionInternalStack: internalStack,
...propsWithoutInternalStack
} = props as Props & {readonly _remotionInternalStack?: string};
const cleanProps = propsWithoutInternalStack as Props;
const env = useRemotionEnvironment();
const pendingDeletions = usePendingSequenceDeletions();
const canUseRemotionHooks = useContext(CanUseRemotionHooks);
const disableInteractivity = useContext(DisableInteractivityContext);
const enableInteractivity = useContext(EnableInteractivityContext);
if (
(!env.isStudio && !enableInteractivity) ||
env.isRendering ||
!canUseRemotionHooks ||
disableInteractivity
) {
return React.createElement(Component, {
...cleanProps,
controls: null,
ref,
} as Props & {
controls: SequenceControls | undefined;
ref: typeof ref;
});
}
// eslint-disable-next-line react-hooks/rules-of-hooks
const nodePathMapping = useContext(OverrideIdsToNodePathsGettersContext);
// eslint-disable-next-line react-hooks/rules-of-hooks
const videoConfig = useUnsafeVideoConfig();
const durationInFrames = videoConfig?.durationInFrames;
const fps = videoConfig?.fps;
const height = videoConfig?.height;
const width = videoConfig?.width;
// eslint-disable-next-line react-hooks/rules-of-hooks
const videoConfigValues = useMemo(
() =>
durationInFrames === undefined ||
fps === undefined ||
height === undefined ||
width === undefined
? null
: {
durationInFrames,
fps,
height,
width,
},
[durationInFrames, fps, height, width],
);
// Keep parent controls intact when adding missing source information.
// @ts-expect-error
const passedControls = cleanProps.controls as
| SequenceControls
| null
| undefined;
// eslint-disable-next-line react-hooks/rules-of-hooks
const resolvedPassedControls = useMemo(() => {
if (
!passedControls ||
getStackForControls(passedControls) !== null ||
internalStack === undefined
) {
return passedControls;
}
const controlsWithStack = {...passedControls};
setStackForControls(controlsWithStack, internalStack);
return controlsWithStack;
}, [internalStack, passedControls]);
if (resolvedPassedControls) {
return React.createElement(Component, {
...cleanProps,
controls: resolvedPassedControls,
ref,
} as unknown as Props & {
controls: SequenceControls | undefined;
ref: typeof ref;
});
}
// eslint-disable-next-line react-hooks/rules-of-hooks
const [overrideId] = useState(() => {
if (!internalStack) {
return String(Math.random());
}
const existingOverrideId = stackToOverrideMap[internalStack];
if (existingOverrideId) {
return existingOverrideId;
}
const newOverrideId = String(Math.random());
stackToOverrideMap[internalStack] = newOverrideId;
return newOverrideId;
});
const nodePath = env.isReadOnlyStudio
? null
: (nodePathMapping.overrideIdToNodePathMappings[overrideId] ?? null);
// eslint-disable-next-line react-hooks/rules-of-hooks
const dragOverrides = useDragOverridesForNodePath(nodePath);
// eslint-disable-next-line react-hooks/rules-of-hooks
const sequenceStatus = usePropStatusForNodePath(nodePath);
// eslint-disable-next-line react-hooks/rules-of-hooks
const propStatus = useMemo(
() => getPropStatusesForSequenceStatus(sequenceStatus, videoConfigValues),
[sequenceStatus, videoConfigValues],
);
// Runtime props already update through their owner. Only overrides with
// keyframes need this wrapper to subscribe to the advancing clock.
const needsFrame = flatKeys.some(
(key) =>
propStatus?.[key]?.status === 'keyframed' ||
dragOverrides[key]?.type === 'keyframed',
);
// eslint-disable-next-line react-hooks/rules-of-hooks
const frame = useCurrentFrameWithOptionalSubscription(needsFrame);
// Read the runtime values for every flat key from the JSX props,
// memoized on the leaf values so the object reference is stable
// when nothing changed β otherwise downstream `useMemo`s churn and
// effects (e.g. Sequence registration) re-fire every render.
const runtimeValues = flatKeys.map((key) =>
getRuntimeValueForSchemaKey({
flatSchema,
key,
props: cleanProps as Record<string, unknown>,
}),
);
// eslint-disable-next-line react-hooks/rules-of-hooks
const currentRuntimeValueDotNotation = useMemo(
() =>
readValuesFromProps(
cleanProps as Record<string, unknown>,
flatKeys,
flatSchema,
),
// eslint-disable-next-line react-hooks/exhaustive-deps
runtimeValues,
);
// eslint-disable-next-line react-hooks/rules-of-hooks
const [runtimeValueStore] = useState(() =>
createRuntimeValueStore(currentRuntimeValueDotNotation),
);
// Publishing in a layout effect ensures that abandoned renders cannot expose
// uncommitted runtime values to Studio consumers.
// eslint-disable-next-line react-hooks/rules-of-hooks
useLayoutEffect(() => {
runtimeValueStore.setSnapshot(currentRuntimeValueDotNotation);
}, [currentRuntimeValueDotNotation, runtimeValueStore]);
// eslint-disable-next-line react-hooks/rules-of-hooks
const controls = useMemo((): SequenceControls => {
const controlsForRender = {
schema: schemaWithSequenceName,
currentRuntimeValueDotNotation,
runtimeValues: runtimeValueStore.store,
videoConfigValues,
overrideId,
supportsEffects,
componentIdentity,
componentName,
};
setStackForControls(controlsForRender, internalStack);
return controlsForRender;
}, [
currentRuntimeValueDotNotation,
internalStack,
overrideId,
runtimeValueStore.store,
videoConfigValues,
]);
// Keep source identities available to parents that inspect their children
// before rendering them (Series and TransitionSeries).
// eslint-disable-next-line react-hooks/rules-of-hooks
useLayoutEffect(() => {
OptimisticSequenceDeletion.register(internalStack ?? null, nodePath);
}, [internalStack, nodePath]);
// 3. Apply drag/code overrides on top of the runtime values.
// eslint-disable-next-line react-hooks/rules-of-hooks
const {merged: valuesDotNotation, propsToDelete} = useMemo(() => {
return computeEffectiveSchemaValuesDotNotation({
schema: schemaWithSequenceName,
currentValue: currentRuntimeValueDotNotation,
overrideValues: dragOverrides,
propStatus,
frame,
});
}, [currentRuntimeValueDotNotation, dragOverrides, propStatus, frame]);
// 4. Eliminate values forbidden by the resolved discriminated union.
const activeKeys = selectActiveKeys(
schemaWithSequenceName,
valuesDotNotation,
);
// 5. Apply the active values back onto the props.
const mergedProps = mergeValues({
flatSchema,
props: cleanProps as Record<string, unknown>,
valuesDotNotation,
schemaKeys: activeKeys,
propsToDelete,
});
if (OptimisticSequenceDeletion.isDeleted(nodePath, pendingDeletions)) {
return null;
}
return React.createElement(Component, {
...mergedProps,
controls,
ref,
} as Props & {
controls: SequenceControls | undefined;
ref: typeof ref;
});
});
Wrapped.displayName = `withInteractivitySchema(${Component.displayName || Component.name || 'Component'})`;
return Wrapped as unknown as React.ComponentType<Props>;
};