Skip to content

🎥 Make videos programmatically with React

12.0 KB
Raw Blame
import * as z from 'zod/mini';
import {
	parseStudioElementPayload,
	type StudioElementPayload,
} from './element-payload';
import type {
	DiscoveredStudio,
	StudioProtocolFetcher,
	StudioProtocolInstallTarget,
} from './studio-discovery';
import {
	discoverStudios,
	fetchWithTimeout,
	getInstallCapability,
	isAbortError,
	studioProtocolProbePorts,
} from './studio-discovery';
import {
	isAwaitingConfirmationResponse,
	parseStudioProtocolError,
} from './studio-response';

export type InstallInStudioErrorCode =
	| 'unsupported-origin'
	| 'no-compatible-studio'
	| 'loopback-network-permission-denied'
	| 'studio-upgrade-required'
	| 'no-installable-target'
	| 'unsupported-protocol'
	| 'invalid-response'
	| 'target-expired'
	| 'request-rejected'
	| 'request-timed-out'
	| 'network-error';

export type InstallInStudioResult =
	| {
			readonly success: true;
			readonly status: 'awaiting-confirmation';
			readonly target: {
				readonly projectName: string | null;
				/**
				 * @deprecated The installation destination is chosen in Studio. Use projectName or studioOrigin to identify the receiving Studio instead.
				 */
				readonly compositionId: string | null;
				readonly studioOrigin: string;
				readonly studioVersion: string;
			};
	  }
	| {
			readonly success: false;
			readonly code: InstallInStudioErrorCode;
			readonly message: string;
	  };

type LoopbackPermissionName = 'loopback-network' | 'local-network-access';

type PermissionQueryFn = (descriptor: {
	readonly name: LoopbackPermissionName;
}) => Promise<{readonly state: PermissionState}>;

export type InstallInStudioDependencies = {
	readonly fetchFn: StudioProtocolFetcher;
	readonly now: () => number;
	readonly ports: readonly number[];
	readonly pageOrigin: string | null;
	readonly permissionQueryFn: PermissionQueryFn | null;
};

export type StudioProtocolInstallRequest = {
	readonly operation: 'install-element';
	readonly protocol: 'remotion-studio-protocol';
	readonly protocolVersion: 1;
	readonly targetId: string;
	readonly payload: StudioElementPayload;
};

const studioProtocolInstallRequestEnvelopeSchema = z.object({
	operation: z.literal('install-element'),
	protocol: z.literal('remotion-studio-protocol'),
	protocolVersion: z.literal(1),
	targetId: z.string(),
	payload: z.unknown(),
});

const studioProtocolIframeInstallRequestSchema = z.object({
	operation: z.literal('install-element'),
	protocol: z.literal('remotion-studio-protocol'),
	protocolVersion: z.literal(1),
	payload: z.unknown(),
});

const installInStudioResultSchema = z.union([
	z.object({
		success: z.literal(true),
		status: z.literal('awaiting-confirmation'),
		target: z.object({
			projectName: z.nullable(z.string()),
			compositionId: z.nullable(z.string()),
			studioOrigin: z.string(),
			studioVersion: z.string(),
		}),
	}),
	z.object({
		success: z.literal(false),
		code: z.enum(['no-installable-target', 'request-rejected']),
		message: z.string(),
	}),
]);

export const parseStudioProtocolIframeInstallRequest = (
	value: unknown,
): StudioElementPayload | null => {
	const envelope = z.safeParse(studioProtocolIframeInstallRequestSchema, value);

	return envelope.success
		? parseStudioElementPayload(envelope.data.payload)
		: null;
};

export const parseStudioProtocolInstallRequest = (
	value: unknown,
):
	| {readonly status: 'valid'; readonly request: StudioProtocolInstallRequest}
	| {readonly status: 'invalid-request' | 'invalid-payload'} => {
	const envelope = z.safeParse(
		studioProtocolInstallRequestEnvelopeSchema,
		value,
	);

	if (!envelope.success) {
		return {status: 'invalid-request'};
	}

	const payload = parseStudioElementPayload(envelope.data.payload);

	if (payload === null) {
		return {status: 'invalid-payload'};
	}

	return {
		status: 'valid',
		request: {
			operation: envelope.data.operation,
			protocol: envelope.data.protocol,
			protocolVersion: envelope.data.protocolVersion,
			targetId: envelope.data.targetId,
			payload,
		},
	};
};

const failure = (
	code: InstallInStudioErrorCode,
	message: string,
): InstallInStudioResult => ({success: false, code, message});

export const isAllowedStudioProtocolPageOrigin = (
	origin: string | null,
): boolean => {
	if (origin === null) {
		return false;
	}

	try {
		const parsed = new URL(origin);

		return (
			parsed.protocol === 'https:' ||
			(parsed.protocol === 'http:' &&
				(parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1'))
		);
	} catch {
		return false;
	}
};

const isLoopbackPermissionDenied = async (
	permissionQueryFn: PermissionQueryFn | null,
): Promise<boolean> => {
	if (permissionQueryFn === null) {
		return false;
	}

	for (const name of ['loopback-network', 'local-network-access'] as const) {
		try {
			const permission = await permissionQueryFn({name});

			return permission.state === 'denied';
		} catch {
			// The compatibility alias may still be supported.
		}
	}

	return false;
};

const requestElementInstallation = async ({
	fetchFn,
	studio,
	target,
	payload,
}: {
	fetchFn: StudioProtocolFetcher;
	studio: DiscoveredStudio;
	target: StudioProtocolInstallTarget;
	payload: StudioElementPayload;
}): Promise<InstallInStudioResult> => {
	let response: Response;

	try {
		const requestBody = {
			operation: 'install-element',
			protocol: 'remotion-studio-protocol',
			protocolVersion: 1,
			targetId: target.id,
			payload,
		} satisfies StudioProtocolInstallRequest;

		response = await fetchWithTimeout({
			fetchFn,
			url: `${studio.origin}/api/studio-protocol/install`,
			options: {
				method: 'POST',
				headers: {'Content-Type': 'application/json'},
				body: JSON.stringify(requestBody),
			},
		});
	} catch (error) {
		const timedOut = isAbortError(error);

		return failure(
			timedOut ? 'request-timed-out' : 'network-error',
			timedOut
				? 'The request to Remotion Studio timed out.'
				: 'Could not connect to Remotion Studio.',
		);
	}

	let result: unknown;

	try {
		result = await response.json();
	} catch {
		return failure(
			'invalid-response',
			'Remotion Studio returned an invalid installation response.',
		);
	}

	if (response.ok && isAwaitingConfirmationResponse(result)) {
		return {
			success: true,
			status: 'awaiting-confirmation',
			target: {
				projectName: studio.descriptor.projectName,
				compositionId: target.compositionId,
				studioOrigin: studio.origin,
				studioVersion: studio.descriptor.studioVersion,
			},
		};
	}

	const protocolError = parseStudioProtocolError(result);

	if (protocolError !== null) {
		return failure(
			protocolError.code === 'target-expired'
				? 'target-expired'
				: 'request-rejected',
			protocolError.message,
		);
	}

	return failure(
		'invalid-response',
		'Remotion Studio returned an invalid installation response.',
	);
};

export const installInStudioWithDependencies = async (
	payload: StudioElementPayload,
	dependencies: InstallInStudioDependencies,
	fallbackPayload: StudioElementPayload | null = null,
): Promise<InstallInStudioResult> => {
	if (!isAllowedStudioProtocolPageOrigin(dependencies.pageOrigin)) {
		return failure(
			'unsupported-origin',
			'Install in Studio is only supported on HTTPS websites and local development origins.',
		);
	}

	const discovery = await discoverStudios(dependencies);

	if (discovery.studios.length === 0) {
		if (discovery.foundUnsupportedProtocol) {
			return failure(
				'unsupported-protocol',
				'The running Remotion Studio uses an unsupported Studio Protocol version.',
			);
		}

		if (discovery.foundInvalidResponse) {
			return failure(
				'invalid-response',
				'Remotion Studio returned an invalid Studio Protocol response.',
			);
		}

		if (await isLoopbackPermissionDenied(dependencies.permissionQueryFn)) {
			return failure(
				'loopback-network-permission-denied',
				'Access to localhost is blocked by your browser. Open the site settings, allow local network access for this site, then try again.',
			);
		}

		return failure(
			'no-compatible-studio',
			'Start Remotion Studio, then try again.',
		);
	}

	const supportedStudios = discovery.studios.flatMap((studio) => {
		const capability = getInstallCapability(studio.descriptor);

		if (capability === null) {
			return [];
		}

		const supportsPayload = capability.payloadVersions.includes(
			payload.version,
		);

		const supportsFallback =
			fallbackPayload !== null &&
			capability.payloadVersions.includes(fallbackPayload.version);

		if (!supportsPayload && !supportsFallback) {
			return [];
		}

		return [{...studio, capability}];
	});

	if (supportedStudios.length === 0) {
		return failure(
			payload.version === 2
				? 'studio-upgrade-required'
				: 'unsupported-protocol',
			payload.version === 2
				? 'Upgrade Remotion Studio to install Elements that include assets.'
				: 'The running Remotion Studio cannot install this Element payload version.',
		);
	}

	const now = dependencies.now();

	const installable = supportedStudios
		.flatMap((studio) => {
			const {target} = studio.capability;

			if (target === null || target.expiresAt <= now) {
				return [];
			}

			return [{...studio, target}];
		})
		.sort((a, b) => {
			const focusDifference =
				(b.target.lastFocusedAt ?? 0) - (a.target.lastFocusedAt ?? 0);

			return focusDifference === 0
				? b.discoveredAt - a.discoveredAt
				: focusDifference;
		});

	const selected = installable[0];

	if (
		!selected ||
		(selected.target.lastFocusedAt === null && installable.length > 1)
	) {
		return failure(
			'no-installable-target',
			'Focus Remotion Studio, then try again.',
		);
	}

	// Remove the v1 remote-URL fallback after 2026-10-23 (one-month
	// transition window for Studios without Element asset support).
	const selectedPayload = selected.capability.payloadVersions.includes(
		payload.version,
	)
		? payload
		: fallbackPayload;

	if (selectedPayload === null) {
		return failure(
			'unsupported-protocol',
			'The running Remotion Studio cannot install this Element payload version.',
		);
	}

	return requestElementInstallation({
		fetchFn: dependencies.fetchFn,
		studio: selected,
		target: selected.target,
		payload: selectedPayload,
	});
};

const installInParentStudio = (
	payload: StudioElementPayload,
): Promise<InstallInStudioResult | null> => {
	if (
		typeof window === 'undefined' ||
		window.parent === window ||
		typeof MessageChannel === 'undefined'
	) {
		return Promise.resolve(null);
	}

	return new Promise((resolve) => {
		const channel = new MessageChannel();

		const timeout = setTimeout(() => {
			channel.port1.close();
			resolve(null);
		}, 500);

		channel.port1.onmessage = (event) => {
			const response = z.safeParse(installInStudioResultSchema, event.data);

			if (!response.success) {
				return;
			}

			clearTimeout(timeout);
			channel.port1.postMessage(null);
			channel.port1.onmessage = null;
			resolve(response.data);
		};

		window.parent.postMessage(
			{
				operation: 'install-element',
				protocol: 'remotion-studio-protocol',
				protocolVersion: 1,
				payload,
			},
			'*',
			[channel.port2],
		);
	});
};

export const installInStudio = async ({
	payload,
	fallbackPayload,
}: {
	readonly payload: StudioElementPayload;
	readonly fallbackPayload?: StudioElementPayload;
}): Promise<InstallInStudioResult> => {
	const parentResult = await installInParentStudio(payload);

	if (parentResult !== null) {
		return parentResult;
	}

	// Older embedded Studios silently ignore v2. Retry with v1 after the
	// response timeout rather than preventing new parent Studios from using assets.
	if (fallbackPayload !== undefined) {
		const fallbackResult = await installInParentStudio(fallbackPayload);

		if (fallbackResult !== null) {
			return fallbackResult;
		}
	}

	return installInStudioWithDependencies(
		payload,
		{
			fetchFn: fetch,
			now: Date.now,
			pageOrigin:
				typeof globalThis.location === 'undefined'
					? null
					: globalThis.location.origin,
			permissionQueryFn:
				typeof globalThis.navigator === 'undefined' ||
				!z.safeParse(z.function(), globalThis.navigator.permissions?.query)
					.success
					? null
					: (descriptor) =>
							// @ts-expect-error Chromium's loopback permission names are not in lib.dom yet.
							globalThis.navigator.permissions.query(descriptor),
			ports: studioProtocolProbePorts,
		},
		fallbackPayload ?? null,
	);
};