🎥 Make videos programmatically with React
feat(studio-protocol): subscribe to local caption style selection
Igor Samokhovets8a04963d0c7c
diff --git a/packages/docs/docs/studio-protocol/add-element-library-to-studio.mdx b/packages/docs/docs/studio-protocol/add-element-library-to-studio.mdxindex 01ead40fa1..ca43236cc6 100644--- a/packages/docs/docs/studio-protocol/add-element-library-to-studio.mdx+++ b/packages/docs/docs/studio-protocol/add-element-library-to-studio.mdx@@ -57,6 +57,10 @@ const isCaptionPicker =Preserve these query parameters when navigating within your library. The context is a display hint, not an authorization signal. Selecting a style sends its Element payload through [`installInStudio()`](/docs/studio-protocol/install-in-studio); Studio uses it for captions instead of installing it immediately.+### Selected caption style<AvailableFrom v="4.0.535" />++Caption libraries can show Studio's current selection and update it when the user selects a style or clicks Reset. Use [`subscribeToCaptionStyleSelection()`](/docs/studio-protocol/subscribe-to-caption-style-selection) to receive the selected slug.+## Return valueReturns a promise with a discriminated union.diff --git a/packages/docs/docs/studio-protocol/subscribe-to-caption-style-selection.mdx b/packages/docs/docs/studio-protocol/subscribe-to-caption-style-selection.mdxnew file mode 100644index 0000000000..5ca81186f5--- /dev/null+++ b/packages/docs/docs/studio-protocol/subscribe-to-caption-style-selection.mdx@@ -0,0 +1,72 @@+---+image: /generated/articles-docs-studio-protocol-subscribe-to-caption-style-selection.png+title: 'subscribeToCaptionStyleSelection()'+crumb: '@remotion/studio-protocol'+---++# subscribeToCaptionStyleSelection()<AvailableFrom v="4.0.535" />++Studio's <kbd>Generate captions</kbd> flow lets users select caption styles from [third-party libraries](/docs/studio-protocol/add-element-library-to-studio#captionstylesurl). Studio displays the selected style in its modal, but your embedded library does not automatically know which style is selected.++Use `subscribeToCaptionStyleSelection()` to show the currently selected style in your library. It receives selection updates from Studio, so you can highlight the matching style on your side.++## Example++```ts twoslash title="caption-picker.ts"+import {subscribeToCaptionStyleSelection} from '@remotion/studio-protocol';++const unsubscribe = subscribeToCaptionStyleSelection((slug) => {+ console.log(slug); // string | null+});++// When your picker unmounts:+unsubscribe();+```++## React example++```tsx twoslash title="CaptionPicker.tsx"+import {useEffect, useState} from 'react';+import {subscribeToCaptionStyleSelection} from '@remotion/studio-protocol';++export const CaptionPicker = () => {+ const [selectedSlug, setSelectedSlug] = useState<string | null>(null);++ useEffect(() => subscribeToCaptionStyleSelection(setSelectedSlug), []);++ return <p>{selectedSlug ?? 'No style selected'}</p>;+};+```++## Arguments++### onChange++A callback receiving the current selection when Studio responds, then updates when the selection changes or is reset.++#### slug++The selected Element's slug, or `null` when no style from your website is selected. This includes Reset and styles selected from another origin. Matching the origin is handled for you.++The built-in Basic Captions fallback still applies when there is no explicit selection. Highlight your cards using the slug and expose the selected state with `aria-pressed`.++## Return value++Returns an unsubscribe function. Call it when your picker unmounts. Multiple listeners are supported; unsubscribing one does not affect the others.++The subscription reconnects automatically when the page is restored from the back-forward cache.++## Availability++Only active inside Studio's [caption picker context](/docs/studio-protocol/add-element-library-to-studio#iframe-context). Outside it, including Browse Elements, standalone pages, and server-side rendering, the function returns a no-op unsubscribe function without invoking the callback.++Studios older than v4.0.535 do not send selection updates. Selecting styles with [`installInStudio()`](/docs/studio-protocol/install-in-studio) still works.++## Compatibility++<CompatibilityTable chrome firefox safari nodejs="" bun="" serverlessFunctions="" clientSideRendering={false} serverSideRendering={false} player={false} studio={false} hideServers />++## See also++- [`addElementLibraryToStudio()`](/docs/studio-protocol/add-element-library-to-studio)+- [Studio Protocol security](/docs/studio-protocol/security)diff --git a/packages/docs/docs/studio-protocol/table-of-contents.tsx b/packages/docs/docs/studio-protocol/table-of-contents.tsxindex 60a6e47b12..7c09d7e4da 100644--- a/packages/docs/docs/studio-protocol/table-of-contents.tsx+++ b/packages/docs/docs/studio-protocol/table-of-contents.tsx@@ -25,6 +25,10 @@ export const TableOfContents: React.FC = () => {<strong>addElementLibraryToStudio()</strong><div>Add an Element Library to a Studio project</div></TOCItem>+ <TOCItem link="/docs/studio-protocol/subscribe-to-caption-style-selection">+ <strong>subscribeToCaptionStyleSelection()</strong>+ <div>Subscribe to your website’s selected caption style</div>+ </TOCItem><TOCItem link="/docs/studio-protocol/is-inside-studio"><strong>isInsideStudio()</strong><div>Check whether a library is embedded in Studio</div>diff --git a/packages/docs/sidebars.ts b/packages/docs/sidebars.tsindex 2d51feafea..d001b416a7 100644--- a/packages/docs/sidebars.ts+++ b/packages/docs/sidebars.ts@@ -851,6 +851,7 @@ const sidebars: SidebarsConfig = {'studio-protocol/set-studio-drag-data','studio-protocol/install-in-studio','studio-protocol/add-element-library-to-studio',+ 'studio-protocol/subscribe-to-caption-style-selection','studio-protocol/is-inside-studio','studio-protocol/security',],diff --git a/packages/docs/src/components/Elements/ElementLibrary.module.css b/packages/docs/src/components/Elements/ElementLibrary.module.cssindex a8efaac11f..c462763f7a 100644--- a/packages/docs/src/components/Elements/ElementLibrary.module.css+++ b/packages/docs/src/components/Elements/ElementLibrary.module.css@@ -90,6 +90,12 @@border-radius: 8px;}+.card[aria-pressed='true'] .previewMedia {+ border-radius: inherit;+ outline: 3px solid var(--ifm-color-primary);+ outline-offset: -3px;+}+.previewMedia {position: absolute;inset: 0;diff --git a/packages/docs/src/components/Elements/ElementLibrary.tsx b/packages/docs/src/components/Elements/ElementLibrary.tsxindex 9947546cb1..0bc51f22ab 100644--- a/packages/docs/src/components/Elements/ElementLibrary.tsx+++ b/packages/docs/src/components/Elements/ElementLibrary.tsx@@ -1,5 +1,9 @@import Link from '@docusaurus/Link';-import {isInsideStudio, setStudioDragData} from '@remotion/studio-protocol';+import {+ isInsideStudio,+ setStudioDragData,+ subscribeToCaptionStyleSelection,+} from '@remotion/studio-protocol';import React, {useEffect, useLayoutEffect, useRef, useState} from 'react';import {BlueButton} from '../../../components/layout/Button';import type {ElementDefinition} from './element-definitions';@@ -42,9 +46,16 @@ const usePrefersReducedMotion = () => {const ElementCard: React.FC<{readonly definition: ElementDefinition;readonly isCaptionPicker: boolean;+ readonly isSelected: boolean;readonly prefersReducedMotion: boolean;readonly sourceCode: string;-}> = ({definition, isCaptionPicker, prefersReducedMotion, sourceCode}) => {+}> = ({+ definition,+ isCaptionPicker,+ isSelected,+ prefersReducedMotion,+ sourceCode,+}) => {const [isFocused, setIsFocused] = useState(false);const [isPointerOver, setIsPointerOver] = useState(false);const [playbackFailed, setPlaybackFailed] = useState(false);@@ -128,6 +139,7 @@ const ElementCard: React.FC<{onClick: installElement,disabled: isInstalling,'aria-label': `Select ${definition.displayName}`,+ 'aria-pressed': isSelected,}: {to: getElementDocumentationUrl(definition)})}onBlur={() => setIsFocused(false)}@@ -212,11 +224,13 @@ const ElementCard: React.FC<{const ElementGrid: React.FC<{readonly definitions: readonly ElementDefinition[];readonly isCaptionPicker: boolean;+ readonly selectedSlug: string | null;readonly prefersReducedMotion: boolean;readonly sourceCodeBySlug: Readonly<Record<string, string>>;}> = ({definitions,isCaptionPicker,+ selectedSlug,prefersReducedMotion,sourceCodeBySlug,}) => {@@ -241,6 +255,7 @@ const ElementGrid: React.FC<{key={definition.slug}definition={definition}isCaptionPicker={isCaptionPicker}+ isSelected={isCaptionPicker && definition.slug === selectedSlug}prefersReducedMotion={prefersReducedMotion}sourceCode={sourceCode}/>@@ -257,6 +272,7 @@ export const ElementLibrary: React.FC<{const sections = getElementLibrarySections(category);const prefersReducedMotion = usePrefersReducedMotion();const [isCaptionPicker, setIsCaptionPicker] = useState(false);+ const [selectedSlug, setSelectedSlug] = useState<string | null>(null);useLayoutEffect(() => {setIsCaptionPicker(@@ -267,6 +283,8 @@ export const ElementLibrary: React.FC<{);}, []);+ useEffect(() => subscribeToCaptionStyleSelection(setSelectedSlug), []);+return (<div className={styles.library}>{sections.map((section) => {@@ -280,6 +298,7 @@ export const ElementLibrary: React.FC<{<ElementGriddefinitions={section.definitions}isCaptionPicker={isCaptionPicker}+ selectedSlug={selectedSlug}prefersReducedMotion={prefersReducedMotion}sourceCodeBySlug={sourceCodeBySlug}/>@@ -301,6 +320,7 @@ export const ElementLibrary: React.FC<{<ElementGriddefinitions={section.definitions}isCaptionPicker={isCaptionPicker}+ selectedSlug={selectedSlug}prefersReducedMotion={prefersReducedMotion}sourceCodeBySlug={sourceCodeBySlug}/>diff --git a/packages/docs/src/data/articles.ts b/packages/docs/src/data/articles.tsindex fb1004b52e..ec9e6b430a 100644--- a/packages/docs/src/data/articles.ts+++ b/packages/docs/src/data/articles.ts@@ -8678,6 +8678,17 @@ export const articles = [noAi: false,slug: 'studio-protocol/static-file-ref',},+ {+ id: 'studio-protocol/subscribe-to-caption-style-selection',+ title: 'subscribeToCaptionStyleSelection()',+ relativePath:+ 'docs/studio-protocol/subscribe-to-caption-style-selection.mdx',+ compId:+ 'articles-docs-studio-protocol-subscribe-to-caption-style-selection',+ crumb: '@remotion/studio-protocol',+ noAi: false,+ slug: 'studio-protocol/subscribe-to-caption-style-selection',+ },{id: 'studio/api',title: '@remotion/studio',diff --git a/packages/docs/static/generated/articles-docs-studio-protocol-subscribe-to-caption-style-selection.png b/packages/docs/static/generated/articles-docs-studio-protocol-subscribe-to-caption-style-selection.pngnew file mode 100644index 0000000000..0058294b05Binary files /dev/null and b/packages/docs/static/generated/articles-docs-studio-protocol-subscribe-to-caption-style-selection.png differdiff --git a/packages/studio-protocol/src/caption-style-selection.ts b/packages/studio-protocol/src/caption-style-selection.tsnew file mode 100644index 0000000000..e7a7269c26--- /dev/null+++ b/packages/studio-protocol/src/caption-style-selection.ts@@ -0,0 +1,48 @@+import * as z from 'zod/mini';+import {makeElementFileNameFromSlug} from './element-drag-data';+import {isAllowedStudioProtocolPageOrigin} from './install-in-studio';++const captionStyleSelectionSchema = z.nullable(+ z.object({+ slug: z+ .string()+ .check(z.refine((slug) => makeElementFileNameFromSlug(slug) !== null)),+ origin: z+ .string()+ .check(+ z.refine(+ (origin) =>+ isAllowedStudioProtocolPageOrigin(origin) &&+ new URL(origin).origin === origin,+ ),+ ),+ }),+);++export type StudioCaptionStyleSelection = z.infer<+ typeof captionStyleSelectionSchema+>;++const captionStyleSubscriptionSchema = z.object({+ operation: z.literal('subscribe-to-caption-style-selection'),+ protocol: z.literal('remotion-studio-protocol'),+ protocolVersion: z.literal(1),+});++const captionStyleSelectionMessageSchema = z.object({+ operation: z.literal('caption-style-selection'),+ protocol: z.literal('remotion-studio-protocol'),+ protocolVersion: z.literal(1),+ selection: captionStyleSelectionSchema,+});++export const isStudioProtocolCaptionStyleSubscription = (+ value: unknown,+): boolean => {+ return z.safeParse(captionStyleSubscriptionSchema, value).success;+};++export const parseStudioProtocolCaptionStyleSelection = (value: unknown) => {+ const parsed = z.safeParse(captionStyleSelectionMessageSchema, value);+ return parsed.success ? parsed.data : null;+};diff --git a/packages/studio-protocol/src/index.ts b/packages/studio-protocol/src/index.tsindex ce2d6533a8..d1c53040f8 100644--- a/packages/studio-protocol/src/index.ts+++ b/packages/studio-protocol/src/index.ts@@ -8,6 +8,10 @@ import {openInBrowserStudio,parseBrowserStudioHash,} from './browser-studio-link';+import {+ isStudioProtocolCaptionStyleSubscription,+ parseStudioProtocolCaptionStyleSelection,+} from './caption-style-selection';import {areComponentProps,isComponentIdentifier,@@ -44,6 +48,7 @@ export {type AddElementLibraryToStudioResult,} from './add-element-library-to-studio';export type {AssetDragData} from './asset-drag-data';+export type {StudioCaptionStyleSelection} from './caption-style-selection';export {buildOpenInRemotionNewUrl} from './browser-studio-link';export type {ComponentDimensions,@@ -101,6 +106,7 @@ export {type InstallInStudioResult,} from './install-in-studio';export {isInsideStudio} from './is-inside-studio';+export {subscribeToCaptionStyleSelection} from './subscribe-to-caption-style-selection';export type {RenderOutputDragData} from './render-output-drag-data';export type {SfxDragData} from './sfx-drag-data';export type {@@ -120,6 +126,7 @@ export const StudioProtocolInternals = {isComponentImportPath,installInStudioWithDependencies,isAllowedStudioProtocolPageOrigin,+ isStudioProtocolCaptionStyleSubscription,isValidPublicLicenseKey,makeBrowserStudioUrl,makeDragData,@@ -131,6 +138,7 @@ export const StudioProtocolInternals = {parseStudioProtocolAddElementLibraryRequest,parseStudioProtocolIframeAddElementLibraryRequest,parseStudioProtocolIframeInstallRequest,+ parseStudioProtocolCaptionStyleSelection,parseStudioProtocolDescriptor,parseStudioProtocolInstallRequest,parseStudioProtocolSetLicenseKeyRequest,diff --git a/packages/studio-protocol/src/subscribe-to-caption-style-selection.ts b/packages/studio-protocol/src/subscribe-to-caption-style-selection.tsnew file mode 100644index 0000000000..a184d2395f--- /dev/null+++ b/packages/studio-protocol/src/subscribe-to-caption-style-selection.ts@@ -0,0 +1,132 @@+import {parseStudioProtocolCaptionStyleSelection} from './caption-style-selection';+import {isAllowedStudioProtocolPageOrigin} from './install-in-studio';++type Listener = {onChange: (slug: string | null) => void};++type CaptionStyleSubscription = {+ listeners: Set<Listener>;+ slug: string | null;+ hasSelection: boolean;+ dispose: () => void;+};++let subscription: CaptionStyleSubscription | null = null;++export const subscribeToCaptionStyleSelection = (+ onChange: (slug: string | null) => void,+): (() => void) => {+ if (+ typeof window === 'undefined' ||+ window.parent === window ||+ typeof MessageChannel === 'undefined' ||+ !isAllowedStudioProtocolPageOrigin(window.location.origin) ||+ new URLSearchParams(window.location.search).get(+ 'remotion-studio-context',+ ) !== 'captions'+ ) {+ return () => {};+ }++ if (subscription === null) {+ const state: CaptionStyleSubscription = {+ listeners: new Set<Listener>(),+ slug: null,+ hasSelection: false,+ dispose: () => {},+ };+ let port: MessagePort | null = null;+ const disconnect = () => {+ if (port !== null) {+ port.onmessage = null;+ port.postMessage(null);+ port.close();+ port = null;+ }++ state.hasSelection = false;+ };++ const connect = () => {+ disconnect();+ const channel = new MessageChannel();+ port = channel.port1;+ port.onmessage = (event) => {+ if (port !== channel.port1) {+ return;+ }++ const message = parseStudioProtocolCaptionStyleSelection(event.data);+ if (message === null) {+ return;+ }++ state.slug =+ message.selection?.origin === window.location.origin+ ? message.selection.slug+ : null;+ state.hasSelection = true;+ for (const entry of [...state.listeners]) {+ if (!state.listeners.has(entry)) {+ continue;+ }++ try {+ entry.onChange(state.slug);+ } catch (error) {+ // One failing listener must not prevent other listeners receiving updates.+ queueMicrotask(() => {+ throw error;+ });+ }+ }+ };++ window.parent.postMessage(+ {+ operation: 'subscribe-to-caption-style-selection',+ protocol: 'remotion-studio-protocol',+ protocolVersion: 1,+ },+ '*',+ [channel.port2],+ );+ };++ const onPageShow = (event: PageTransitionEvent) => {+ if (event.persisted) {+ connect();+ }+ };++ state.dispose = () => {+ window.removeEventListener('pagehide', disconnect);+ window.removeEventListener('pageshow', onPageShow);+ disconnect();+ };++ subscription = state;+ window.addEventListener('pagehide', disconnect);+ window.addEventListener('pageshow', onPageShow);+ connect();+ }++ const current = subscription;+ const listener = {onChange};+ current.listeners.add(listener);+ if (current.hasSelection) {+ queueMicrotask(() => {+ if (current.listeners.has(listener) && current.hasSelection) {+ onChange(current.slug);+ }+ });+ }++ return () => {+ if (!current.listeners.delete(listener) || current.listeners.size > 0) {+ return;+ }++ current.dispose();+ subscription = null;+ };+};diff --git a/packages/studio/src/components/ElementLibraryFrame.tsx b/packages/studio/src/components/ElementLibraryFrame.tsxindex f77f6c1661..11498890b7 100644--- a/packages/studio/src/components/ElementLibraryFrame.tsx+++ b/packages/studio/src/components/ElementLibraryFrame.tsx@@ -1,3 +1,7 @@+import {+ StudioProtocolInternals,+ type StudioCaptionStyleSelection,+} from '@remotion/studio-protocol';import React, {useLayoutEffect, useRef, useState} from 'react';import {Spinner} from './Spinner';@@ -28,8 +32,17 @@ export const ElementLibraryFrame: React.FC<{readonly name: string;readonly url: string;readonly context: 'captions' | null;-}> = ({name, url, context}) => {+ readonly captionStyleSelection: StudioCaptionStyleSelection;+}> = ({name, url, context, captionStyleSelection}) => {const iframeRef = useRef<HTMLIFrameElement>(null);+ const selectionPortRef = useRef<MessagePort | null>(null);+ const selectionMessageRef = useRef({+ operation: 'caption-style-selection',+ protocol: 'remotion-studio-protocol',+ protocolVersion: 1,+ selection: captionStyleSelection,+ });+ selectionMessageRef.current.selection = captionStyleSelection;const [isLoaded, setIsLoaded] = useState(false);useLayoutEffect(() => {@@ -42,6 +55,42 @@ export const ElementLibraryFrame: React.FC<{const onLoad = () => setIsLoaded(true);iframe.addEventListener('load', onLoad);+ const onMessage = (event: MessageEvent) => {+ if (+ context !== 'captions' ||+ event.source !== iframe.contentWindow ||+ !StudioProtocolInternals.isAllowedStudioProtocolPageOrigin(+ event.origin,+ ) ||+ !StudioProtocolInternals.isStudioProtocolCaptionStyleSubscription(+ event.data,+ )+ ) {+ return;+ }++ const port = event.ports[0];+ if (port === undefined) {+ return;+ }++ selectionPortRef.current?.close();+ selectionPortRef.current = port;+ port.onmessage = (message) => {+ // The library sends null when its subscription ends.+ if (message.data === null) {+ port.close();+ if (selectionPortRef.current === port) {+ selectionPortRef.current = null;+ }+ }+ };++ port.postMessage(selectionMessageRef.current);+ };++ window.addEventListener('message', onMessage);+// Studio is cross-origin isolated. A credentialless iframe may embed a// library that does not set Cross-Origin-Resource-Policy headers.iframe.setAttribute('credentialless', '');@@ -58,9 +107,16 @@ export const ElementLibraryFrame: React.FC<{return () => {iframe.removeEventListener('load', onLoad);+ window.removeEventListener('message', onMessage);+ selectionPortRef.current?.close();+ selectionPortRef.current = null;};}, [context, url]);+ useLayoutEffect(() => {+ selectionPortRef.current?.postMessage(selectionMessageRef.current);+ }, [captionStyleSelection]);+return (<div style={contentStyle}><iframediff --git a/packages/studio/src/components/ElementLibraryModal.tsx b/packages/studio/src/components/ElementLibraryModal.tsxindex 72a4571d26..b3ad15d84f 100644--- a/packages/studio/src/components/ElementLibraryModal.tsx+++ b/packages/studio/src/components/ElementLibraryModal.tsx@@ -60,7 +60,12 @@ export const ElementLibraryModal: React.FC<{</ActionTooltip>}/>- <ElementLibraryFrame name={name} url={url} context={null} />+ <ElementLibraryFrame+ name={name}+ url={url}+ context={null}+ captionStyleSelection={null}+ />{installState === null ? null : (<ElementInstallConfirmation state={installState} />)}diff --git a/packages/studio/src/components/Transcription/TranscriptionModal.tsx b/packages/studio/src/components/Transcription/TranscriptionModal.tsxindex 2028d4f697..6a30f3280a 100644--- a/packages/studio/src/components/Transcription/TranscriptionModal.tsx+++ b/packages/studio/src/components/Transcription/TranscriptionModal.tsx@@ -721,6 +721,20 @@ export const TranscriptionModal: React.FC<TranscriptionModalState> = ({src,target,}) => {+ const captionStyleSelection = useMemo(() => {+ if (+ captionStyle === null ||+ !('origin' in captionStyle.source) ||+ captionStyle.source.origin === null+ ) {+ return null;+ }++ return {+ slug: captionStyle.element.slug,+ origin: captionStyle.source.origin,+ };+ }, [captionStyle]);const [libraryUrl, setLibraryUrl] = useState(REMOTION_CAPTION_STYLES_URL);const {studioRuntimeConfig} = useSettings();const libraryOptions: SegmentedControlItem[] = [@@ -1145,6 +1159,7 @@ export const TranscriptionModal: React.FC<TranscriptionModalState> = ({name="Caption styles"url={libraryUrl}context="captions"+ captionStyleSelection={captionStyleSelection}/></div>) : null}