🎥 Make videos programmatically with React
import * as z from 'zod/mini';
import {
isComponentIdentifier,
type ComponentDimensions,
} from './component-drag-data';
import {isValidPackageName} from './validation';
export type ElementInstallationMode = 'wrapped' | 'component-owned-sequence';
const maxElementAssets = 100;
export const maxElementAssetBytes = 50 * 1024 * 1024;
export type ElementAsset =
| {
readonly path: string;
readonly type: 'url';
readonly url: string;
}
| {
readonly path: string;
readonly type: 'base64';
readonly data: string;
};
export type StaticFileRef = {
readonly __remotion_element_asset: string;
};
export type ElementInitialPropValue =
| string
| number
| boolean
| null
| readonly ElementInitialPropValue[]
| Readonly<object>;
export type ElementInitialProps = Readonly<
Record<string, ElementInitialPropValue>
>;
export type ElementDependency =
| {
readonly name: `@remotion/${string}`;
readonly version: null;
}
| {
readonly name: string;
readonly version: string;
};
export type ElementDragData = {
type: 'remotion-element';
version: 1 | 2;
element: {
assets: ElementAsset[];
dependencies: ElementDependency[];
durationInFrames?: number;
initialProps: ElementInitialProps | null;
installationMode?: ElementInstallationMode;
isCaptionStyle?: boolean;
slug: string;
displayName: string;
sourceCode: string;
dimensions: ComponentDimensions | null;
};
};
const lowercaseElementFileNameSchema = z
.string()
.check(
z.refine(
(value) =>
value.length > 0 &&
value.length < 120 &&
value === value.toLowerCase() &&
value.endsWith('.tsx') &&
!value.includes('/') &&
!value.includes('\\') &&
!value.includes('\0') &&
!value.includes('..') &&
/^[a-z0-9][a-z0-9.-]*\.tsx$/.test(value),
),
);
const slugSchema = z
.string()
.check(
z.refine(
(value) =>
value.length > 0 &&
value.length < 120 &&
/^[a-z0-9][a-z0-9/-]*$/.test(value) &&
!value.includes('..') &&
!value.includes('//'),
),
);
export const isLowercaseElementFileName = (value: unknown): value is string =>
z.safeParse(lowercaseElementFileNameSchema, value).success;
export const makeElementFileNameFromSlug = (slug: string) => {
if (!z.safeParse(slugSchema, slug).success) {
return null;
}
const lastSegment = slug.split('/').at(-1);
if (!lastSegment) {
return null;
}
const fileName = `${lastSegment}.element.tsx`;
return z.safeParse(lowercaseElementFileNameSchema, fileName).success
? fileName
: null;
};
export const getElementComponentNameFromSourceCode = (sourceCode: string) => {
const componentNames = Array.from(
sourceCode.matchAll(
/export\s+(?:const|function)\s+([A-Z_$][A-Za-z0-9_$]*)\b/g,
),
).map((match) => match[1]);
const uniqueComponentNames = Array.from(new Set(componentNames));
if (uniqueComponentNames.length !== 1) {
return null;
}
return isComponentIdentifier(uniqueComponentNames[0])
? uniqueComponentNames[0]
: null;
};
const packagesProvidedByRemotionProjects = new Set([
'react',
'react-dom',
'remotion',
]);
const exactVersionSchema = z
.string()
.check(
z.regex(
/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(?:0|[1-9]\d*|[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/,
),
);
const elementDependencyEnvelopeSchema = z.looseObject({
name: z.string().check(z.refine(isValidPackageName)),
version: z.unknown(),
});
const getElementDependencyError = (value: unknown): string | null => {
const parsed = z.safeParse(elementDependencyEnvelopeSchema, value);
if (!parsed.success) {
return `Invalid Element dependency: ${JSON.stringify(value)}`;
}
if (packagesProvidedByRemotionProjects.has(parsed.data.name)) {
return `${JSON.stringify(parsed.data.name)} is provided by Remotion projects and must not be declared as an Element dependency.`;
}
if (parsed.data.name.startsWith('@remotion/')) {
return parsed.data.version === null
? null
: `Remotion Element dependency ${JSON.stringify(parsed.data.name)} must use version: null.`;
}
return z.safeParse(exactVersionSchema, parsed.data.version).success
? null
: `Non-Remotion Element dependency ${JSON.stringify(parsed.data.name)} must declare an exact version.`;
};
const elementDependencySchema = elementDependencyEnvelopeSchema.check(
z.refine((value) => getElementDependencyError(value) === null),
);
export function assertElementDependency(
value: unknown,
): asserts value is ElementDependency {
const error = getElementDependencyError(value);
if (error !== null) {
throw new TypeError(error);
}
}
export const isElementDependency = (
value: unknown,
): value is ElementDependency =>
z.safeParse(elementDependencySchema, value).success;
const windowsReservedNames = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i;
const strictBase64Regex =
/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
export const isValidElementAssetPath = (assetPath: string) => {
if (assetPath.length === 0 || assetPath.length > 1024) {
return false;
}
if (assetPath.startsWith('/') || assetPath.includes('\\')) {
return false;
}
return assetPath.split('/').every((segment) => {
if (segment === '' || segment === '.' || segment === '..') {
return false;
}
if (/[<>:"|?*]/.test(segment) || /[. ]$/.test(segment)) {
return false;
}
if (
Array.from(segment).some((character) => character.charCodeAt(0) <= 31)
) {
return false;
}
return !windowsReservedNames.test(segment);
});
};
const isValidElementAssetUrl = (value: string) => {
try {
const url = new URL(value);
return (
(url.protocol === 'http:' || url.protocol === 'https:') &&
url.username === '' &&
url.password === ''
);
} catch {
return false;
}
};
const elementAssetSchema = z.union([
z.strictObject({
path: z.string().check(z.refine(isValidElementAssetPath)),
type: z.literal('url'),
url: z.string().check(z.refine(isValidElementAssetUrl)),
}),
z.strictObject({
path: z.string().check(z.refine(isValidElementAssetPath)),
type: z.literal('base64'),
data: z.string().check(z.regex(strictBase64Regex)),
}),
]);
const elementAssetsSchema = z
.array(elementAssetSchema)
.check(z.maxLength(maxElementAssets));
export function assertElementAssets(
value: unknown,
): asserts value is ElementAsset[] {
const parsed = z.safeParse(elementAssetsSchema, value);
if (!parsed.success) {
throw new TypeError('Invalid Element assets');
}
const paths = new Set<string>();
let embeddedBytes = 0;
for (const asset of parsed.data) {
const assetPath = asset.path.toLowerCase();
if (
[...paths].some(
(existingPath) =>
existingPath === assetPath ||
existingPath.startsWith(`${assetPath}/`) ||
assetPath.startsWith(`${existingPath}/`),
)
) {
throw new TypeError(
`Element asset destination conflicts with another asset: ${asset.path}`,
);
}
paths.add(assetPath);
if (asset.type === 'base64') {
embeddedBytes += (asset.data.length / 4) * 3;
if (asset.data.endsWith('==')) {
embeddedBytes -= 2;
} else if (asset.data.endsWith('=')) {
embeddedBytes -= 1;
}
}
}
if (embeddedBytes > maxElementAssetBytes) {
throw new TypeError('Element assets exceed the 50MB aggregate limit');
}
}
const dimensionsSchema = z.object({
width: z.number().check(z.positive()),
height: z.number().check(z.positive()),
});
const elementInstallationModeSchema = z.union([
z.literal('wrapped'),
z.literal('component-owned-sequence'),
]);
const durationSchema = z
.number()
.check(z.int(), z.positive(), z.lte(100_000_000));
const elementInitialPropsSchema = z.record(z.string(), z.unknown());
const initialPropNameRegex = /^[A-Za-z_$][0-9A-Za-z_$]*$/;
const componentOwnedInstallationProps = new Set([
'durationInFrames',
'from',
'name',
]);
const isJsonCompatibleValue = (
value: unknown,
seen: Set<object>,
): value is ElementInitialPropValue => {
if (
value === null ||
typeof value === 'string' ||
typeof value === 'boolean'
) {
return true;
}
if (typeof value === 'number') {
return Number.isFinite(value);
}
if (typeof value !== 'object' || seen.has(value)) {
return false;
}
if (!Array.isArray(value)) {
// Plain objects from another realm have a different Object.prototype.
const prototype = Object.getPrototypeOf(value);
if (prototype !== null && Object.getPrototypeOf(prototype) !== null) {
return false;
}
}
seen.add(value);
const values = Array.isArray(value) ? value : Object.values(value);
const valid = values.every((item) => isJsonCompatibleValue(item, seen));
seen.delete(value);
return valid;
};
export const isElementInitialProps = (
value: unknown,
): value is ElementInitialProps | null => {
if (value === null) {
return true;
}
if (typeof value !== 'object' || Array.isArray(value)) {
return false;
}
if (!Object.keys(value).every((key) => initialPropNameRegex.test(key))) {
return false;
}
return isJsonCompatibleValue(value, new Set());
};
const elementAssetPathSchema = z
.string()
.check(z.refine(isValidElementAssetPath));
export const staticFileRef = (path: string): StaticFileRef => {
if (!z.safeParse(elementAssetPathSchema, path).success) {
throw new TypeError('staticFileRef() requires a safe Element asset path');
}
return {__remotion_element_asset: path};
};
export const isStaticFileRef = (value: unknown): value is StaticFileRef => {
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
return false;
}
if (Object.keys(value).length !== 1) {
return false;
}
if (
!Object.hasOwn(value, '__remotion_element_asset') ||
!('__remotion_element_asset' in value)
) {
return false;
}
return z.safeParse(elementAssetPathSchema, value.__remotion_element_asset)
.success;
};
export function assertElementAssetReferences({
assets,
initialProps,
}: {
assets: readonly {readonly path: string}[];
initialProps: ElementInitialProps | null;
}): void {
const paths = new Set(assets.map((asset) => asset.path));
const seen = new Set<object>();
const visit = (value: ElementInitialPropValue): void => {
if (value === null || typeof value !== 'object') {
return;
}
if (Object.hasOwn(value, '__remotion_element_asset')) {
if (!isStaticFileRef(value)) {
throw new TypeError('Invalid staticFileRef() in initialProps');
}
if (!paths.has(value.__remotion_element_asset)) {
throw new TypeError(
`staticFileRef() path ${JSON.stringify(value.__remotion_element_asset)} is not declared in the Element assets`,
);
}
return;
}
if (seen.has(value)) {
throw new TypeError(
'Element initialProps must not contain circular references',
);
}
seen.add(value);
Object.values(value).forEach(visit);
seen.delete(value);
};
Object.values(initialProps ?? {}).forEach(visit);
}
export const hasValidElementInitialPropsForInstallationMode = ({
initialProps,
installationMode,
}: {
initialProps: ElementInitialProps | null;
installationMode: ElementInstallationMode | undefined;
}) => {
if (
installationMode !== 'component-owned-sequence' ||
initialProps === null
) {
return true;
}
if (
Object.keys(initialProps).some((name) =>
componentOwnedInstallationProps.has(name),
)
) {
return false;
}
const {style} = initialProps;
if (style === undefined) {
return true;
}
if (style === null || Array.isArray(style)) {
return false;
}
return typeof style === 'object';
};
export const makeElementDragData = ({
assets,
dependencies,
dimensions,
displayName,
durationInFrames,
initialProps,
slug,
sourceCode,
installationMode,
isCaptionStyle,
}: Omit<ElementDragData['element'], 'dependencies'> & {
dependencies: ElementDependency[];
}): ElementDragData => {
assertElementAssets(assets);
assertElementAssetReferences({assets, initialProps});
for (const dependency of dependencies) {
assertElementDependency(dependency);
}
const uniqueDependencies = new Map(
dependencies.map((dependency) => [dependency.name, dependency]),
);
const element: ElementDragData['element'] = {
assets: [...assets],
dependencies: Array.from(uniqueDependencies.values()),
dimensions,
displayName,
initialProps,
slug,
sourceCode,
};
if (durationInFrames !== undefined) {
element.durationInFrames = durationInFrames;
}
if (installationMode !== undefined) {
element.installationMode = installationMode;
}
if (isCaptionStyle !== undefined) {
element.isCaptionStyle = isCaptionStyle;
}
return {
type: 'remotion-element',
version: assets.length === 0 ? 1 : 2,
element,
};
};
const elementDragDataSchema = z.object({
type: z.literal('remotion-element'),
version: z.union([z.literal(1), z.literal(2)]),
element: z.object({
assets: z.optional(z.array(z.unknown())),
dependencies: z.array(z.unknown()).check(z.maxLength(100)),
durationInFrames: z.optional(durationSchema),
initialProps: z.optional(z.nullable(elementInitialPropsSchema)),
installationMode: z.optional(elementInstallationModeSchema),
isCaptionStyle: z.optional(z.boolean()),
slug: slugSchema,
displayName: z.string().check(z.minLength(1), z.maxLength(119)),
sourceCode: z
.string()
.check(
z.refine(
(value) =>
value.trim().length > 0 &&
value.length < 200_000 &&
getElementComponentNameFromSourceCode(value) !== null,
),
),
dimensions: z.optional(z.nullable(dimensionsSchema)),
}),
});
export const parseElementDragData = (value: string): ElementDragData | null => {
try {
const parsed = z.safeParse(elementDragDataSchema, JSON.parse(value));
if (
!parsed.success ||
makeElementFileNameFromSlug(parsed.data.element.slug) === null
) {
return null;
}
const assets = parsed.data.element.assets ?? [];
try {
assertElementAssets(assets);
} catch {
return null;
}
const dependencies: ElementDependency[] = [];
for (const dependency of parsed.data.element.dependencies) {
if (!isElementDependency(dependency)) {
return null;
}
dependencies.push(dependency);
}
const initialProps = parsed.data.element.initialProps ?? null;
if (
!isElementInitialProps(initialProps) ||
!hasValidElementInitialPropsForInstallationMode({
initialProps,
installationMode: parsed.data.element.installationMode,
})
) {
return null;
}
const result = makeElementDragData({
assets,
dependencies,
dimensions: parsed.data.element.dimensions ?? null,
displayName: parsed.data.element.displayName,
durationInFrames: parsed.data.element.durationInFrames,
initialProps,
slug: parsed.data.element.slug,
sourceCode: parsed.data.element.sourceCode,
installationMode: parsed.data.element.installationMode,
isCaptionStyle: parsed.data.element.isCaptionStyle,
});
return result.version === parsed.data.version ? result : null;
} catch {
return null;
}
};