Skip to content

🎥 Make videos programmatically with React

Docs: Clarify Studio Protocol usage (#10569)

Igor Samokhovets7bcdb4e83f73
diff --git a/packages/docs/docs/studio-protocol/create-element-payload.mdx b/packages/docs/docs/studio-protocol/create-element-payload.mdx
index 8ac31047a6..21b624ad08 100644
--- a/packages/docs/docs/studio-protocol/create-element-payload.mdx
+++ b/packages/docs/docs/studio-protocol/create-element-payload.mdx
@@ -8,13 +8,16 @@ crumb: '@remotion/studio-protocol'
Creates a validated, versioned Element payload for [`setStudioDragData()`](/docs/studio-protocol/set-studio-drag-data) and [`installInStudio()`](/docs/studio-protocol/install-in-studio).
-```ts twoslash title="element-payload.ts"
+## Example
+
+```ts title="element-payload.ts"
import {createElementPayload} from '@remotion/studio-protocol';
+import elementSourceCode from './MyElement.tsx?raw'; // Import the source code as text
const payload = createElementPayload({
- displayName: 'Lower Third',
- slug: 'lower-third',
- sourceCode: 'export const LowerThird = () => null;',
+ displayName: 'My Element',
+ slug: 'my-element',
+ sourceCode: elementSourceCode,
dependencies: [
{name: '@remotion/google-fonts', version: null},
{name: 'color-namer', version: '1.4.0'},
@@ -40,6 +43,8 @@ A lowercase Element identifier. Its final path segment is used to create the `.e
The complete Element source code. It must contain exactly one exported named component.
+With Vite, use the [`?raw` import suffix](https://vite.dev/guide/assets#importing-asset-as-string) to import the component file as a string. Other build tools may provide an equivalent raw-text import.
+
### dependencies
An array of npm packages needed by the Element. Declare each dependency as an object with `name` and `version` properties. Duplicate names are removed.
diff --git a/packages/docs/docs/studio-protocol/index.mdx b/packages/docs/docs/studio-protocol/index.mdx
index 3b16adb299..ab9019a74f 100644
--- a/packages/docs/docs/studio-protocol/index.mdx
+++ b/packages/docs/docs/studio-protocol/index.mdx
@@ -6,36 +6,27 @@ crumb: '@remotion/studio-protocol'
# Remotion Studio Protocol<AvailableFrom v="4.0.502" />
-A versioned protocol for connecting websites to Remotion Studio.
-
-Protocol v1 supports [Remotion Elements](/elements) from the official Remotion Elements library. It provides one Element payload that can be delivered by dragging it into Studio or by requesting installation into the active composition.
+A versioned protocol for providing content to Remotion Studio.
<Installation pkg="@remotion/studio-protocol" />
-## Usage
+## Capabilities
+
+### Installing Remotion Elements
+
+A **Remotion Element** is a reusable React component distributed as source code, together with the metadata and dependencies needed to add it to a composition. Because its source code becomes part of the project, it can be edited and remixed by the user.
-```ts twoslash title="element.ts"
-import {
- createElementPayload,
- installInStudio,
-} from '@remotion/studio-protocol';
+Websites can provide Remotion Elements by drag-and-drop or request their installation into the active composition.
-const payload = createElementPayload({
- displayName: 'Lower Third',
- slug: 'lower-third',
- sourceCode: 'export const LowerThird = () => null;',
- dependencies: [],
- dimensions: {width: 900, height: 260},
- durationInFrames: 90,
-});
+- <Step>1</Step> Create an Element payload with [`createElementPayload()`](/docs/studio-protocol/create-element-payload).
+- <Step>2</Step> Provide the payload to Studio: put it on a drag event with [`setStudioDragData()`](/docs/studio-protocol/set-studio-drag-data), or request installation into the active composition with [`installInStudio()`](/docs/studio-protocol/install-in-studio).
-const result = await installInStudio({payload});
-if (result.success) {
- console.log(result.status); // "awaiting-confirmation"
-}
-```
+Offer both delivery methods when possible. They use the same Element payload but suit different workflows.
-A successful request means Studio received the Element and is awaiting confirmation. It does not mean dependencies or source files were installed.
+| Method | Benefits | Tradeoffs |
+| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [Drag-and-drop](/docs/studio-protocol/set-studio-drag-data) | The user chooses the exact Studio tab, timeline position, and canvas position. | Drag data has no reliable website provenance, so Studio labels the source as [unverified](/docs/studio-protocol/security#confirmation-boundary). |
+| [Installation request](/docs/studio-protocol/install-in-studio) | The requesting website is shown in Studio. On macOS, Studio attempts to bring the target tab to the foreground. | Local Studio ports are probed and the most recently focused compatible Studio is selected automatically. |
## APIs
@@ -43,13 +34,9 @@ import {TableOfContents} from './table-of-contents';
<TableOfContents />
-## Supported origins
-
-Any HTTPS website can request an Element installation confirmation. HTTP is supported on `localhost` and `127.0.0.1` for local development.
-
-## Compatibility
+## Security
-Remotion Studio 4.0.502 or newer is required. Browser Studio is not supported in protocol v1.
+Learn about the [confirmation and origin policy](/docs/studio-protocol/security).
## License
diff --git a/packages/docs/docs/studio-protocol/install-in-studio.mdx b/packages/docs/docs/studio-protocol/install-in-studio.mdx
index 7e3e49e9eb..765e96c0bf 100644
--- a/packages/docs/docs/studio-protocol/install-in-studio.mdx
+++ b/packages/docs/docs/studio-protocol/install-in-studio.mdx
@@ -8,16 +8,19 @@ crumb: '@remotion/studio-protocol'
Discovers a recently focused Remotion Studio and sends it an Element payload.
-```ts twoslash title="install-element.ts"
+## Example
+
+```ts title="install-element.ts"
import {
createElementPayload,
installInStudio,
} from '@remotion/studio-protocol';
+import elementSourceCode from './MyElement.tsx?raw'; // Import the source code as text
const payload = createElementPayload({
- displayName: 'Lower Third',
- slug: 'lower-third',
- sourceCode: 'export const LowerThird = () => null;',
+ displayName: 'My Element',
+ slug: 'my-element',
+ sourceCode: elementSourceCode,
dependencies: [],
dimensions: {width: 900, height: 260},
durationInFrames: 90,
@@ -31,6 +34,12 @@ if (!result.success) {
}
```
+## When to use an installation request
+
+An installation request provides a one-click flow and shows the requesting website in Studio. On macOS, Studio attempts to bring the selected Studio tab to the foreground after delivering the request.
+
+The target is selected automatically: local Studio ports are probed and the most recently focused compatible Studio is used. Also offer drag-and-drop with [`setStudioDragData()`](/docs/studio-protocol/set-studio-drag-data) when possible so the user can choose a specific Studio tab, timeline position, and canvas position.
+
## Arguments
### payload
diff --git a/packages/docs/docs/studio-protocol/security.mdx b/packages/docs/docs/studio-protocol/security.mdx
index f983077142..7213a96f79 100644
--- a/packages/docs/docs/studio-protocol/security.mdx
+++ b/packages/docs/docs/studio-protocol/security.mdx
@@ -4,23 +4,23 @@ title: 'Studio Protocol security'
crumb: '@remotion/studio-protocol'
---
-# Studio Protocol security<AvailableFrom v="4.0.503" />
+# Studio Protocol security
-An Element contains executable React source code and may declare npm dependencies. Studio requires confirmation before applying every installation request.
+An Element contains executable React source code and may declare npm dependencies. Studio requires confirmation before applying an Element delivered through drag-and-drop or an installation request.
-## Confirmation boundary
+## Allowed origins
-A successful [`installInStudio()`](/docs/studio-protocol/install-in-studio) result only means the request reached Studio and is awaiting confirmation.
+Any HTTPS website can request an Element installation confirmation. HTTP is supported only for local development pages on `localhost` or `127.0.0.1`.
-Before confirming, Studio shows the requesting website, target composition and destination file, source code, and every declared dependency with its installation status. Source code and package lifecycle scripts run with the project's file and network access.
+Studio reflects only the requesting allowed origin in CORS. It does not use wildcard CORS or cross-origin credentials.
-Declining the confirmation does not write source files or install packages. Drag-and-drop Element data has no reliable website provenance and is labeled as unverified.
+## Confirmation boundary
-## Allowed origins
+Elements delivered using [`setStudioDragData()`](/docs/studio-protocol/set-studio-drag-data) or [`installInStudio()`](/docs/studio-protocol/install-in-studio) require confirmation in Studio. A successful `installInStudio()` result only means the request reached Studio and is awaiting confirmation.
-Any HTTPS website can request an Element installation confirmation. HTTP is supported only for local development pages on `localhost` or `127.0.0.1`.
+Before confirming, Studio shows the target composition and destination file, source code, and every declared dependency with its installation status. For an installation request, Studio also shows the requesting website. Drag-and-drop data has no reliable website provenance and is labeled as unverified. Source code and package lifecycle scripts run with the project's file and network access.
-Studio reflects only the requesting allowed origin in CORS. It does not use wildcard CORS or cross-origin credentials.
+Declining the confirmation does not write source files or install packages.
## Target information
diff --git a/packages/docs/docs/studio-protocol/set-studio-drag-data.mdx b/packages/docs/docs/studio-protocol/set-studio-drag-data.mdx
index 4d6c55106a..2a67c43777 100644
--- a/packages/docs/docs/studio-protocol/set-studio-drag-data.mdx
+++ b/packages/docs/docs/studio-protocol/set-studio-drag-data.mdx
@@ -8,16 +8,19 @@ crumb: '@remotion/studio-protocol'
Writes an Element payload and its preview metadata to a browser `DataTransfer` object.
+## Example
+
```tsx title="DraggableElement.tsx"
import {
createElementPayload,
setStudioDragData,
} from '@remotion/studio-protocol';
+import elementSourceCode from './MyElement.tsx?raw'; // Import the source code as text
const payload = createElementPayload({
- displayName: 'Lower Third',
- slug: 'lower-third',
- sourceCode: 'export const LowerThird = () => null;',
+ displayName: 'My Element',
+ slug: 'my-element',
+ sourceCode: elementSourceCode,
dependencies: [],
dimensions: {width: 900, height: 260},
durationInFrames: 90,
@@ -38,6 +41,12 @@ export const DraggableElement = () => (
);
```
+## When to use drag-and-drop
+
+Drag-and-drop lets the user choose the exact Studio tab, timeline position, and canvas position. It is useful when multiple Studio tabs are open or placement should be decided visually.
+
+A drag event has no reliable website provenance. Studio therefore labels the Element source as unverified. Also offer [`installInStudio()`](/docs/studio-protocol/install-in-studio) when possible so the user can choose between precise placement and an installation request with a displayed source.
+
## Arguments
Pass an object with the following properties.
diff --git a/packages/docs/docs/studio-protocol/table-of-contents.tsx b/packages/docs/docs/studio-protocol/table-of-contents.tsx
index 51aaec559a..d9e60ef5c3 100644
--- a/packages/docs/docs/studio-protocol/table-of-contents.tsx
+++ b/packages/docs/docs/studio-protocol/table-of-contents.tsx
@@ -17,10 +17,6 @@ export const TableOfContents: React.FC = () => {
<strong>installInStudio()</strong>
<div>Request installation into the active Studio</div>
</TOCItem>
- <TOCItem link="/docs/studio-protocol/security">
- <strong>Security</strong>
- <div>Confirmation and origin policy</div>
- </TOCItem>
</Grid>
);
};