Skip to content

🎥 Make videos programmatically with React

Elements: Install gallery assets with local file references (#11529)

Igor Samokhovets4bc033db0616
diff --git a/packages/docs/elements/audio/oscilloscope/initial-props.ts b/packages/docs/elements/audio/oscilloscope/initial-props.ts
new file mode 100644
index 0000000000..f9fbb1e730
--- /dev/null
+++ b/packages/docs/elements/audio/oscilloscope/initial-props.ts
@@ -0,0 +1,13 @@
+import type {ElementAsset} from '@remotion/studio-protocol';
+import type {ComponentProps} from 'react';
+import type {AudioOscilloscope} from './audio-oscilloscope';
+
+export const audioOscilloscopeAudio = {
+ path: 'elements/audio-oscilloscope/remotion-made-this-picture-move.mp3',
+ type: 'url',
+ url: 'https://remotion.media/elements/remotion-made-this-picture-move.mp3',
+} as const satisfies ElementAsset;
+
+export const audioOscilloscopeInitialProps = {
+ audioSrc: audioOscilloscopeAudio.url,
+} satisfies ComponentProps<typeof AudioOscilloscope>;
diff --git a/packages/docs/elements/youtube/youtube-subscribe-nudge/youtube-subscribe-nudge.tsx b/packages/docs/elements/youtube/youtube-subscribe-nudge/youtube-subscribe-nudge.tsx
index 8ca190a5aa..ca17b013f8 100644
--- a/packages/docs/elements/youtube/youtube-subscribe-nudge/youtube-subscribe-nudge.tsx
+++ b/packages/docs/elements/youtube/youtube-subscribe-nudge/youtube-subscribe-nudge.tsx
@@ -15,7 +15,15 @@ loadFont('normal', {
weights: ['500', '600', '700', '800'],
});
-export const YouTubeSubscribeNudge: React.FC = () => {
+export const YouTubeSubscribeNudge: React.FC<{
+ readonly clickSrc?: string;
+ readonly dingSrc?: string;
+ readonly avatarSrc?: string;
+}> = ({
+ clickSrc = mouseClick,
+ dingSrc = ding,
+ avatarSrc = 'https://remotion.media/elements/social-endcard-remotion-logo.png',
+}) => {
const frame = useCurrentFrame();
return (
@@ -30,7 +38,7 @@ export const YouTubeSubscribeNudge: React.FC = () => {
durationInFrames={12}
from={61}
name="Subscribe click"
- src={mouseClick}
+ src={clickSrc}
trimBefore={3}
volume={0.5}
/>
@@ -38,7 +46,7 @@ export const YouTubeSubscribeNudge: React.FC = () => {
durationInFrames={39}
from={81}
name="Bell chime"
- src={ding}
+ src={dingSrc}
trimBefore={4}
volume={0.24}
/>
@@ -105,7 +113,7 @@ export const YouTubeSubscribeNudge: React.FC = () => {
fit="cover"
height={88}
name="Avatar"
- src="https://remotion.media/elements/social-endcard-remotion-logo.png"
+ src={avatarSrc}
style={{
backgroundColor: '#ffffff',
border: '1px solid rgba(255, 255, 255, 0.12)',
diff --git a/packages/docs/src/components/Elements/ElementLibrary.tsx b/packages/docs/src/components/Elements/ElementLibrary.tsx
index cf03a9121d..233f3c05b3 100644
--- a/packages/docs/src/components/Elements/ElementLibrary.tsx
+++ b/packages/docs/src/components/Elements/ElementLibrary.tsx
@@ -48,7 +48,12 @@ const ElementCard: React.FC<{
const shouldPlay =
!prefersReducedMotion && !playbackFailed && (isFocused || isPointerOver);
const elementPayload = useMemo(
- () => createElementPayloadFromDefinition({definition, sourceCode}),
+ () =>
+ createElementPayloadFromDefinition({
+ definition,
+ sourceCode,
+ installAssets: false,
+ }),
[definition, sourceCode],
);
diff --git a/packages/docs/src/components/Elements/ElementPage.tsx b/packages/docs/src/components/Elements/ElementPage.tsx
index 57a3322732..1f8cb66f38 100644
--- a/packages/docs/src/components/Elements/ElementPage.tsx
+++ b/packages/docs/src/components/Elements/ElementPage.tsx
@@ -70,7 +70,23 @@ export const ElementPage: React.FC<ElementPageProps> = ({
return null;
}
- return createElementPayloadFromDefinition({definition, sourceCode});
+ return createElementPayloadFromDefinition({
+ definition,
+ sourceCode,
+ installAssets: false,
+ });
+ }, [definition, sourceCode]);
+
+ const assetPayload = useMemo(() => {
+ if (!sourceCode || definition.assets.length === 0) {
+ return null;
+ }
+
+ return createElementPayloadFromDefinition({
+ definition,
+ sourceCode,
+ installAssets: true,
+ });
}, [definition, sourceCode]);
useLayoutEffect(() => {
@@ -130,7 +146,10 @@ export const ElementPage: React.FC<ElementPageProps> = ({
setInstallStatus({type: 'installing'});
}
- const result = await installInStudio({payload: elementPayload});
+ const result = await installInStudio({
+ payload: assetPayload ?? elementPayload,
+ fallbackPayload: assetPayload === null ? undefined : elementPayload,
+ });
if (!result.success) {
setInstallStatus({
type: 'error',
@@ -155,7 +174,7 @@ export const ElementPage: React.FC<ElementPageProps> = ({
`https://www.remotion.pro/api/track/element-install-request?slug=${encodeURIComponent(definition.slug)}`,
);
}
- }, [definition.slug, elementPayload, isEmbeddedInStudio]);
+ }, [assetPayload, definition.slug, elementPayload, isEmbeddedInStudio]);
const openInBrowserStudio = useCallback(() => {
if (elementPayload === null) {
diff --git a/packages/docs/src/components/Elements/element-definitions.ts b/packages/docs/src/components/Elements/element-definitions.ts
index dff612f925..2d166dbf74 100644
--- a/packages/docs/src/components/Elements/element-definitions.ts
+++ b/packages/docs/src/components/Elements/element-definitions.ts
@@ -1,4 +1,7 @@
+import {ding, mouseClick} from '@remotion/sfx';
+import {staticFileRef} from '@remotion/studio-protocol';
import type {
+ ElementAsset,
ElementDependency,
ElementInitialProps,
ElementInstallationMode,
@@ -6,6 +9,10 @@ import type {
import type {ComponentType} from 'react';
import {MirroredAudioSpectrum} from '../../../elements/audio/mirrored-spectrum/mirrored-spectrum';
import {AudioOscilloscope} from '../../../elements/audio/oscilloscope/audio-oscilloscope';
+import {
+ audioOscilloscopeAudio,
+ audioOscilloscopeInitialProps,
+} from '../../../elements/audio/oscilloscope/initial-props';
import {AudioWaveformProgress} from '../../../elements/audio/waveform-progress/audio-waveform-progress';
import {LiquidContours} from '../../../elements/backgrounds/liquid-contours/liquid-contours';
import {MovingWaves} from '../../../elements/backgrounds/moving-waves/moving-waves';
@@ -75,6 +82,7 @@ export type ElementPreviewMetadata = {
};
export type ElementDefinition = {
+ readonly assets: readonly ElementAsset[];
readonly category: ElementCategory;
readonly component: ComponentType<never>;
readonly contributors: readonly Contributor[];
@@ -87,6 +95,8 @@ export type ElementDefinition = {
readonly fps: number;
readonly height: number;
readonly initialProps: ElementInitialProps | null;
+ // Shallow overrides for installation only; previews use initialProps unchanged.
+ readonly installationProps: ElementInitialProps | null;
readonly posterFrame: number;
readonly preview: ElementPreviewMetadata;
readonly previewUsesHtmlInCanvas: boolean;
@@ -96,10 +106,32 @@ export type ElementDefinition = {
readonly width: number;
};
+const youtubeSubscribeNudgeAssets = {
+ click: {
+ path: 'elements/youtube-subscribe-nudge/mouse-click.wav',
+ type: 'url',
+ url: mouseClick,
+ },
+ ding: {
+ path: 'elements/youtube-subscribe-nudge/ding.wav',
+ type: 'url',
+ url: ding,
+ },
+ avatar: {
+ path: 'elements/youtube-subscribe-nudge/remotion-logo.png',
+ type: 'url',
+ url: 'https://remotion.media/elements/social-endcard-remotion-logo.png',
+ },
+} as const satisfies Record<string, ElementAsset>;
+
// Array order defines the order of categories and cards in the Element library.
const elementImplementations = [
{
slug: 'audio/oscilloscope',
+ assets: [audioOscilloscopeAudio],
+ installationProps: {
+ audioSrc: staticFileRef(audioOscilloscopeAudio.path),
+ } as ElementInitialProps,
component: AudioOscilloscope,
contributors: [{username: 'samohovets', contribution: 'Author'}],
description: 'Suitable for visualizing speech.',
@@ -121,12 +153,16 @@ const elementImplementations = [
'https://remotion.media/elements/audio-oscilloscope-preview.mp4',
},
safeArea: 120,
- initialProps: null,
+ initialProps: audioOscilloscopeInitialProps,
installationMode: 'component-owned-sequence',
width: 1920,
},
{
slug: 'audio/waveform-progress',
+ assets: [audioOscilloscopeAudio],
+ installationProps: {
+ audioSrc: staticFileRef(audioOscilloscopeAudio.path),
+ } as ElementInitialProps,
component: AudioWaveformProgress,
contributors: [{username: 'samohovets', contribution: 'Author'}],
description: 'A static audio waveform with playback progress.',
@@ -148,12 +184,16 @@ const elementImplementations = [
'https://remotion.media/elements/audio-waveform-progress-preview.mp4',
},
safeArea: 120,
- initialProps: null,
+ initialProps: {audioSrc: audioOscilloscopeAudio.url} as ElementInitialProps,
installationMode: 'component-owned-sequence',
width: 1920,
},
{
slug: 'audio/mirrored-spectrum',
+ assets: [audioOscilloscopeAudio],
+ installationProps: {
+ audioSrc: staticFileRef(audioOscilloscopeAudio.path),
+ } as ElementInitialProps,
component: MirroredAudioSpectrum,
contributors: [{username: 'JonnyBurger', contribution: 'Author'}],
description: 'Suitable for both music and speech visualization.',
@@ -175,12 +215,14 @@ const elementImplementations = [
'https://remotion.media/elements/audio-mirrored-spectrum-preview.mp4',
},
safeArea: 120,
- initialProps: null,
+ initialProps: {audioSrc: audioOscilloscopeAudio.url} as ElementInitialProps,
installationMode: 'component-owned-sequence',
width: 1920,
},
{
slug: 'backgrounds/notebook-paper',
+ assets: [],
+ installationProps: null,
component: NotebookPaper,
contributors: [],
description: 'A white paper background with subtle blue gridlines.',
@@ -205,6 +247,8 @@ const elementImplementations = [
},
{
slug: 'backgrounds/paper-texture',
+ assets: [],
+ installationProps: null,
component: PaperTexture,
contributors: [],
description:
@@ -230,6 +274,8 @@ const elementImplementations = [
},
{
slug: 'backgrounds/rotating-starburst',
+ assets: [],
+ installationProps: null,
component: RotatingStarburst,
contributors: [],
description: 'A solid background with a slowly rotating starburst effect.',
@@ -254,6 +300,8 @@ const elementImplementations = [
},
{
slug: 'backgrounds/moving-waves',
+ assets: [],
+ installationProps: null,
component: MovingWaves,
contributors: [],
description: 'A seamless wave background that flows upward.',
@@ -278,6 +326,8 @@ const elementImplementations = [
},
{
slug: 'backgrounds/moving-zigzags',
+ assets: [],
+ installationProps: null,
component: MovingZigzags,
contributors: [],
description: 'A seamless zigzag background that flows upward.',
@@ -302,6 +352,8 @@ const elementImplementations = [
},
{
slug: 'backgrounds/liquid-contours',
+ assets: [],
+ installationProps: null,
component: LiquidContours,
contributors: [],
description:
@@ -327,6 +379,8 @@ const elementImplementations = [
},
{
slug: 'captions/basic-captions',
+ assets: [],
+ installationProps: null,
component: BasicCaptions,
contributors: [{username: 'JonnyBurger', contribution: null}],
description:
@@ -352,6 +406,8 @@ const elementImplementations = [
},
{
slug: 'captions/rounded-captions',
+ assets: [],
+ installationProps: null,
component: RoundedCaptions,
contributors: [{username: 'JonnyBurger', contribution: null}],
description:
@@ -382,6 +438,8 @@ const elementImplementations = [
},
{
slug: 'captions/moving-pill-captions',
+ assets: [],
+ installationProps: null,
component: MovingPillCaptions,
contributors: [{username: 'JonnyBurger', contribution: null}],
description:
@@ -411,6 +469,8 @@ const elementImplementations = [
},
{
slug: 'captions/popping-word-captions',
+ assets: [],
+ installationProps: null,
component: PoppingWordCaptions,
contributors: [{username: 'JonnyBurger', contribution: null}],
description: 'Synchronized captions that pop each spoken word into focus.',
@@ -439,6 +499,8 @@ const elementImplementations = [
},
{
slug: 'captions/word-highlight-captions',
+ assets: [],
+ installationProps: null,
component: WordHighlightCaptions,
contributors: [{username: 'JonnyBurger', contribution: null}],
description: 'Synchronized captions that highlight each spoken word.',
@@ -467,6 +529,8 @@ const elementImplementations = [
},
{
slug: 'commerce/product-collection',
+ assets: [],
+ installationProps: null,
component: ProductCollection,
contributors: [],
description: 'Three cards which each take center once.',
@@ -491,6 +555,8 @@ const elementImplementations = [
},
{
slug: 'commerce/product-discount-callout',
+ assets: [],
+ installationProps: null,
component: ProductDiscountCallout,
contributors: [],
description: 'An attention-grabbing speech bubble.',
@@ -518,6 +584,8 @@ const elementImplementations = [
},
{
slug: 'commerce/shine',
+ assets: [],
+ installationProps: null,
component: Shine,
contributors: [],
description: 'Adds a diagonal shine sweep to any content.',
@@ -540,6 +608,8 @@ const elementImplementations = [
},
{
slug: 'commerce/tear',
+ assets: [],
+ installationProps: null,
component: Tear,
contributors: [],
description: 'A tear effect that can be applied to any content.',
@@ -562,6 +632,8 @@ const elementImplementations = [
},
{
slug: 'data/horizontal-bar-chart',
+ assets: [],
+ installationProps: null,
component: HorizontalBarChart,
contributors: [],
description: 'A bold bar chart with three directly labeled data points.',
@@ -586,6 +658,8 @@ const elementImplementations = [
},
{
slug: 'data/line-chart',
+ assets: [],
+ installationProps: null,
component: LineChart,
contributors: [],
description: 'A bold animated line chart with a directly labeled trend.',
@@ -608,6 +682,8 @@ const elementImplementations = [
},
{
slug: 'data/number-counter',
+ assets: [],
+ installationProps: null,
component: NumberCounter,
contributors: [
{
@@ -638,6 +714,8 @@ const elementImplementations = [
},
{
slug: 'data/pie-chart',
+ assets: [],
+ installationProps: null,
component: PieChart,
contributors: [],
description:
@@ -661,6 +739,8 @@ const elementImplementations = [
},
{
slug: 'data/vertical-bar-chart',
+ assets: [],
+ installationProps: null,
component: VerticalBarChart,
contributors: [],
description:
@@ -686,6 +766,8 @@ const elementImplementations = [
},
{
slug: 'layouts/picture-in-picture-transition',
+ assets: [],
+ installationProps: null,
component: PictureInPictureTransition,
contributors: [],
description:
@@ -711,6 +793,8 @@ const elementImplementations = [
},
{
slug: 'layouts/slide-to-split-screen',
+ assets: [],
+ installationProps: null,
component: SlideToSplitScreen,
contributors: [],
description:
@@ -736,6 +820,8 @@ const elementImplementations = [
},
{
slug: 'maps/map-flyover',
+ assets: [],
+ installationProps: null,
component: MapFlyover,
contributors: [],
description:
@@ -762,6 +848,8 @@ const elementImplementations = [
},
{
slug: 'maps/watercolor-map',
+ assets: [],
+ installationProps: null,
component: WatercolorMap,
contributors: [
{username: 'JonnyBurger', contribution: 'Author'},
@@ -790,6 +878,8 @@ const elementImplementations = [
},
{
slug: 'overlays/location-lower-third',
+ assets: [],
+ installationProps: null,
component: LocationLowerThird,
contributors: [],
description: 'An animated lower third for an event location and venue.',
@@ -814,6 +904,8 @@ const elementImplementations = [
},
{
slug: 'overlays/name-lower-third',
+ assets: [],
+ installationProps: null,
component: NameLowerThird,
contributors: [],
description:
@@ -839,6 +931,8 @@ const elementImplementations = [
},
{
slug: 'overlays/social-safe-zones',
+ assets: [],
+ installationProps: null,
component: SocialSafeZones,
contributors: [],
description:
@@ -864,6 +958,8 @@ const elementImplementations = [
},
{
slug: 'text/news-article-highlight',
+ assets: [],
+ installationProps: null,
component: NewsArticleHighlight,
contributors: [],
description: 'A centered news headline with animated passage highlights.',
@@ -888,6 +984,8 @@ const elementImplementations = [
},
{
slug: 'storytelling/on-screen-messages',
+ assets: [],
+ installationProps: null,
component: OnScreenMessages,
contributors: [],
description:
@@ -913,6 +1011,8 @@ const elementImplementations = [
},
{
slug: 'storytelling/polaroid-pictures',
+ assets: [],
+ installationProps: null,
component: PolaroidPictures,
contributors: [],
description:
@@ -938,6 +1038,8 @@ const elementImplementations = [
},
{
slug: 'text/circle-marker',
+ assets: [],
+ installationProps: null,
component: CircleMarker,
contributors: [],
description:
@@ -966,6 +1068,8 @@ const elementImplementations = [
},
{
slug: 'text/crossed-off',
+ assets: [],
+ installationProps: null,
component: CrossedOffText,
contributors: [],
description:
@@ -992,6 +1096,8 @@ const elementImplementations = [
},
{
slug: 'text/spinning-text-wheel',
+ assets: [],
+ installationProps: null,
component: SpinningTextWheel,
contributors: [{username: 'JonnyBurger', contribution: null}],
description:
@@ -1017,6 +1123,8 @@ const elementImplementations = [
},
{
slug: 'text/strike-through',
+ assets: [],
+ installationProps: null,
component: StrikeThroughText,
contributors: [],
description:
@@ -1045,6 +1153,8 @@ const elementImplementations = [
},
{
slug: 'text/text-marker',
+ assets: [],
+ installationProps: null,
component: TextMarker,
contributors: [],
description:
@@ -1071,6 +1181,8 @@ const elementImplementations = [
},
{
slug: 'youtube/youtube-comment-highlight',
+ assets: [],
+ installationProps: null,
component: YouTubeCommentHighlight,
contributors: [],
description: 'A YouTube-style card for featuring a viewer comment.',
@@ -1095,6 +1207,8 @@ const elementImplementations = [
},
{
slug: 'youtube/youtube-end-card',
+ assets: [],
+ installationProps: null,
component: YouTubeEndCard,
contributors: [],
description:
@@ -1120,6 +1234,16 @@ const elementImplementations = [
},
{
slug: 'youtube/youtube-subscribe-nudge',
+ assets: [
+ youtubeSubscribeNudgeAssets.click,
+ youtubeSubscribeNudgeAssets.ding,
+ youtubeSubscribeNudgeAssets.avatar,
+ ],
+ installationProps: {
+ clickSrc: staticFileRef(youtubeSubscribeNudgeAssets.click.path),
+ dingSrc: staticFileRef(youtubeSubscribeNudgeAssets.ding.path),
+ avatarSrc: staticFileRef(youtubeSubscribeNudgeAssets.avatar.path),
+ } as ElementInitialProps,
component: YouTubeSubscribeNudge,
contributors: [],
description:
@@ -1143,7 +1267,11 @@ const elementImplementations = [
'https://remotion.media/elements/youtube-youtube-subscribe-nudge-preview.mp4',
},
safeArea: 240,
- initialProps: null,
+ initialProps: {
+ clickSrc: youtubeSubscribeNudgeAssets.click.url,
+ dingSrc: youtubeSubscribeNudgeAssets.ding.url,
+ avatarSrc: youtubeSubscribeNudgeAssets.avatar.url,
+ } as ElementInitialProps,
installationMode: 'wrapped',
width: 1920,
},
diff --git a/packages/docs/src/components/Elements/element-drag-data.ts b/packages/docs/src/components/Elements/element-drag-data.ts
index 7854adfae1..f448104499 100644
--- a/packages/docs/src/components/Elements/element-drag-data.ts
+++ b/packages/docs/src/components/Elements/element-drag-data.ts
@@ -7,9 +7,11 @@ import type {ElementDefinition} from './element-definitions';
export const createElementPayloadFromDefinition = ({
definition,
sourceCode,
+ installAssets,
}: {
readonly definition: ElementDefinition;
readonly sourceCode: string;
+ readonly installAssets: boolean;
}): StudioElementPayload => {
const dimensions =
definition.elementWidth !== null && definition.elementHeight !== null
@@ -20,11 +22,15 @@ export const createElementPayloadFromDefinition = ({
: null;
return createElementPayload({
+ assets: installAssets ? definition.assets : [],
dependencies: definition.dependencies,
dimensions,
displayName: definition.displayName,
durationInFrames: definition.durationInFrames,
- initialProps: definition.initialProps,
+ initialProps:
+ !installAssets || definition.installationProps === null
+ ? definition.initialProps
+ : {...definition.initialProps, ...definition.installationProps},
installationMode: definition.installationMode,
slug: definition.slug,
sourceCode,
diff --git a/packages/docs/src/remotion/element-playground/PlaygroundControls.tsx b/packages/docs/src/remotion/element-playground/PlaygroundControls.tsx
index 92c6b168dc..eb410569f3 100644
--- a/packages/docs/src/remotion/element-playground/PlaygroundControls.tsx
+++ b/packages/docs/src/remotion/element-playground/PlaygroundControls.tsx
@@ -46,11 +46,21 @@ export const PlaygroundControls: React.FC = () => {
setInstalling(true);
setError(null);
try {
+ const legacyPayload = createElementPayloadFromDefinition({
+ definition,
+ sourceCode,
+ installAssets: false,
+ });
const result = await installInStudio({
- payload: createElementPayloadFromDefinition({
- definition,
- sourceCode,
- }),
+ payload:
+ definition.assets.length === 0
+ ? legacyPayload
+ : createElementPayloadFromDefinition({
+ definition,
+ sourceCode,
+ installAssets: true,
+ }),
+ fallbackPayload: legacyPayload,
});
if (!result.success) setError(result.message);
} catch (err) {
diff --git a/packages/docs/src/test/elements.test.ts b/packages/docs/src/test/elements.test.ts
index f44f95e598..a9cf9179c2 100644
--- a/packages/docs/src/test/elements.test.ts
+++ b/packages/docs/src/test/elements.test.ts
@@ -346,17 +346,110 @@ describe('Element library', () => {
}
});
- test('creates canonical fixed-size and adaptive drag payloads', () => {
- const sourceCodeBySlug = getRemotionElementSourceMap({elementsRoot});
+ test('installs visualizer audio and subscribe sounds locally without breaking remote-URL installs', () => {
+ const sources = getRemotionElementSourceMap({elementsRoot});
for (const slug of [
- 'overlays/name-lower-third',
- 'backgrounds/paper-texture',
+ 'audio/oscilloscope',
+ 'audio/waveform-progress',
+ 'audio/mirrored-spectrum',
] as const) {
const definition = getElementDefinition(slug);
+ const legacy = createElementPayloadFromDefinition({
+ definition,
+ sourceCode: sources[slug],
+ installAssets: false,
+ });
+ const modern = createElementPayloadFromDefinition({
+ definition,
+ sourceCode: sources[slug],
+ installAssets: true,
+ });
+ expect(legacy.version).toBe(1);
+ expect(legacy.element.initialProps).toMatchObject({
+ audioSrc:
+ 'https://remotion.media/elements/remotion-made-this-picture-move.mp3',
+ });
+ expect(modern.version).toBe(2);
+ expect(modern.element.assets).toEqual([
+ {
+ path: 'elements/audio-oscilloscope/remotion-made-this-picture-move.mp3',
+ type: 'url',
+ url: 'https://remotion.media/elements/remotion-made-this-picture-move.mp3',
+ },
+ ]);
+ expect(modern.element.initialProps).toMatchObject({
+ audioSrc: {
+ __remotion_element_asset:
+ 'elements/audio-oscilloscope/remotion-made-this-picture-move.mp3',
+ },
+ });
+ }
+
+ const nudgeSlug = 'youtube/youtube-subscribe-nudge';
+ const nudgeDefinition = getElementDefinition(nudgeSlug);
+ const nudgeLegacy = createElementPayloadFromDefinition({
+ definition: nudgeDefinition,
+ sourceCode: sources[nudgeSlug],
+ installAssets: false,
+ });
+ const nudgeModern = createElementPayloadFromDefinition({
+ definition: nudgeDefinition,
+ sourceCode: sources[nudgeSlug],
+ installAssets: true,
+ });
+ expect(nudgeLegacy.version).toBe(1);
+ expect(nudgeLegacy.element.assets).toEqual([]);
+ expect(nudgeLegacy.element.initialProps).toMatchObject({
+ clickSrc: 'https://remotion.media/mouse-click.wav',
+ dingSrc: 'https://remotion.media/ding.wav',
+ });
+ expect(nudgeModern.version).toBe(2);
+ expect(nudgeModern.element.assets).toEqual(
+ expect.arrayContaining([
+ {
+ path: 'elements/youtube-subscribe-nudge/ding.wav',
+ type: 'url',
+ url: 'https://remotion.media/ding.wav',
+ },
+ {
+ path: 'elements/youtube-subscribe-nudge/mouse-click.wav',
+ type: 'url',
+ url: 'https://remotion.media/mouse-click.wav',
+ },
+ {
+ path: 'elements/youtube-subscribe-nudge/remotion-logo.png',
+ type: 'url',
+ url: 'https://remotion.media/elements/social-endcard-remotion-logo.png',
+ },
+ ]),
+ );
+ expect(nudgeModern.element.initialProps).toMatchObject({
+ clickSrc: {
+ __remotion_element_asset:
+ 'elements/youtube-subscribe-nudge/mouse-click.wav',
+ },
+ dingSrc: {
+ __remotion_element_asset: 'elements/youtube-subscribe-nudge/ding.wav',
+ },
+ avatarSrc: {
+ __remotion_element_asset:
+ 'elements/youtube-subscribe-nudge/remotion-logo.png',
+ },
+ });
+ expect(nudgeModern.element.sourceCode).toContain('src={clickSrc}');
+ expect(nudgeModern.element.sourceCode).toContain('src={dingSrc}');
+ expect(nudgeModern.element.sourceCode).toContain('src={avatarSrc}');
+ });
+
+ test('creates canonical drag payloads for every gallery Element', () => {
+ const sourceCodeBySlug = getRemotionElementSourceMap({elementsRoot});
+ for (const definition of elementDefinitionList) {
+ const {slug} = definition;
const sourceCode = sourceCodeBySlug[slug];
const payload = createElementPayloadFromDefinition({
definition,
sourceCode,
+ installAssets: false,
});
expect(payload).toMatchObject({
@@ -364,6 +457,7 @@ describe('Element library', () => {
version: 1,
durationInFrames: definition.durationInFrames,
element: {
+ assets: [],
dependencies: definition.dependencies,
displayName: definition.displayName,
durationInFrames: definition.durationInFrames,
@@ -380,6 +474,21 @@ describe('Element library', () => {
}
: null;
expect(payload.element.dimensions).toEqual(expectedDimensions);
+ expect(payload.element.initialProps).toEqual(definition.initialProps);
+
+ if (definition.assets.length > 0) {
+ const assetPayload = createElementPayloadFromDefinition({
+ definition,
+ sourceCode,
+ installAssets: true,
+ });
+ expect(assetPayload.version).toBe(2);
+ expect(assetPayload.element.assets).toEqual(definition.assets);
+ expect(assetPayload.element.initialProps).toEqual({
+ ...definition.initialProps,
+ ...definition.installationProps,
+ });
+ }
}
});
});
diff --git a/packages/studio-protocol/src/install-in-studio.ts b/packages/studio-protocol/src/install-in-studio.ts
index e44156d628..5ba7693dc7 100644
--- a/packages/studio-protocol/src/install-in-studio.ts
+++ b/packages/studio-protocol/src/install-in-studio.ts
@@ -168,6 +168,7 @@ export const isAllowedStudioProtocolPageOrigin = (
export const installInStudioWithDependencies = async (
payload: StudioElementPayload,
dependencies: InstallInStudioDependencies,
+ fallbackPayload: StudioElementPayload | null = null,
): Promise<InstallInStudioResult> => {
if (!isAllowedStudioProtocolPageOrigin(dependencies.pageOrigin)) {
return failure(
@@ -221,7 +222,9 @@ export const installInStudioWithDependencies = async (
const supportedStudios = discovery.studios.flatMap((studio) => {
const capability = getInstallCapability(studio.descriptor);
- return capability?.payloadVersions.includes(payload.version)
+ return capability?.payloadVersions.includes(payload.version) ||
+ (fallbackPayload !== null &&
+ capability?.payloadVersions.includes(fallbackPayload.version))
? [{...studio, capability}]
: [];
});
@@ -262,6 +265,20 @@ export const installInStudioWithDependencies = async (
);
}
+ // 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.',
+ );
+ }
+
let response: Response;
try {
const requestBody = {
@@ -269,7 +286,7 @@ export const installInStudioWithDependencies = async (
protocol: 'remotion-studio-protocol',
protocolVersion: 1,
targetId: selectedTarget.id,
- payload,
+ payload: selectedPayload,
} satisfies StudioProtocolInstallRequest;
response = await fetchWithTimeout({
fetchFn: dependencies.fetchFn,
@@ -373,28 +390,43 @@ const installInParentStudio = (
export const installInStudio = async ({
payload,
+ fallbackPayload,
}: {
readonly payload: StudioElementPayload;
+ readonly fallbackPayload?: StudioElementPayload;
}): Promise<InstallInStudioResult> => {
const parentResult = await installInParentStudio(payload);
if (parentResult !== null) {
return parentResult;
}
- return installInStudioWithDependencies(payload, {
- fetchFn: fetch,
- now: Date.now,
- pageOrigin:
- typeof globalThis.location === 'undefined'
- ? null
- : globalThis.location.origin,
- permissionQueryFn:
- typeof globalThis.navigator === 'undefined' ||
- typeof globalThis.navigator.permissions?.query !== 'function'
- ? null
- : (descriptor) =>
- // @ts-expect-error Chromium's loopback permission names are not in lib.dom yet.
- globalThis.navigator.permissions.query(descriptor),
- ports: studioProtocolProbePorts,
- });
+ // 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' ||
+ typeof globalThis.navigator.permissions?.query !== 'function'
+ ? 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,
+ );
};
diff --git a/packages/studio-protocol/src/test/install-in-studio.test.ts b/packages/studio-protocol/src/test/install-in-studio.test.ts
index 72ca194798..f19d909ce6 100644
--- a/packages/studio-protocol/src/test/install-in-studio.test.ts
+++ b/packages/studio-protocol/src/test/install-in-studio.test.ts
@@ -161,6 +161,87 @@ test('requires a Studio that supports asset payloads', async () => {
});
});
+test('sends remote URLs to a focused v1 Studio and local asset references to a focused v2 Studio', async () => {
+ const legacyPayload = createElementPayload({
+ dependencies: [],
+ dimensions: null,
+ displayName: 'Audio Element',
+ durationInFrames: 30,
+ slug: 'audio-element',
+ sourceCode: 'export const AudioElement = () => null;',
+ initialProps: {audioSrc: 'https://remotion.media/audio.mp3'},
+ });
+ const assetPayload = createElementPayload({
+ dependencies: [],
+ dimensions: null,
+ displayName: 'Audio Element',
+ durationInFrames: 30,
+ slug: 'audio-element',
+ sourceCode: 'export const AudioElement = () => null;',
+ assets: [
+ {path: 'audio.mp3', type: 'url', url: 'https://remotion.media/audio.mp3'},
+ ],
+ initialProps: {audioSrc: {__remotion_element_asset: 'audio.mp3'}},
+ });
+ for (const supportsAssets of [false, true]) {
+ const requests: unknown[] = [];
+ const fetchFn = (input: string | URL | Request, options?: RequestInit) => {
+ const url = String(input);
+ if (url.endsWith('/api/studio-protocol/install')) {
+ requests.push(JSON.parse(String(options?.body)));
+ return Promise.resolve(
+ jsonResponse({
+ protocol: 'remotion-studio-protocol',
+ protocolVersion: 1,
+ status: 'awaiting-confirmation',
+ }),
+ );
+ }
+
+ return Promise.resolve(
+ jsonResponse({
+ ...descriptor({
+ compositionId: 'Main',
+ lastFocusedAt: 999_000,
+ projectName: 'Studio',
+ targetId: 'target',
+ }),
+ capabilities: [
+ {
+ type: 'install-element',
+ payloadType: 'remotion-element',
+ payloadVersions: supportsAssets ? [1, 2] : [1],
+ target: {
+ id: 'target',
+ expiresAt: 1_010_000,
+ compositionId: 'Main',
+ lastFocusedAt: 999_000,
+ },
+ },
+ ],
+ }),
+ );
+ };
+
+ const result = await installInStudioWithDependencies(
+ assetPayload,
+ {...dependencies, fetchFn, ports: [3000]},
+ legacyPayload,
+ );
+
+ expect(result.success).toBe(true);
+ expect(requests).toEqual([
+ {
+ operation: 'install-element',
+ protocol: 'remotion-studio-protocol',
+ protocolVersion: 1,
+ targetId: 'target',
+ payload: supportsAssets ? assetPayload : legacyPayload,
+ },
+ ]);
+ }
+});
+
test('distinguishes a compatible Studio without an installable target', async () => {
const fetchFn = (input: string | URL | Request) => {
const url = String(input);