installInStudio()v4.0.502

Sends an Element payload to the containing Remotion Studio, or discovers a writable Studio when called outside one.

Example

install-element.ts
import {createElementPayload, installInStudio} from '@remotion/studio-protocol';

const elementSourceCode = `
export const MyElement = () => {
  return <div>Hello world</div>;
};
`;

const payload = createElementPayload({
  displayName: 'My Element',
  slug: 'my-element',
  sourceCode: elementSourceCode,
  dependencies: [],
  dimensions: {width: 900, height: 260},
  durationInFrames: 90,
});

const result = await installInStudio({payload});
if (!result.success) {
  console.error(result.code, result.message);
} else {
  console.log(result.status); // "awaiting-confirmation"
}

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.

When the library is embedded in Studio, the containing Studio is selected. Otherwise, local Studio ports are probed and the most recently focused compatible Studio tab is used. If only one writable tab is available, it can receive the request without having been focused v4.0.530. Also offer drag-and-drop with setStudioDragData() when possible so the user can choose a specific Studio tab, timeline position, and canvas position.

Installing without a selected compositionv4.0.530

A writable Studio can receive installation requests without a selected composition. The confirmation dialog defaults to New composition. This works both from an embedded Element Library and from an external website.

Arguments

payload

The value returned by createElementPayload(). For a component-owned-sequence Element with replaceable starter content, set initialProps when creating the payload.

Return value

Returns a promise with a discriminated union.

success

Indicates whether the request reached the exact selected Studio tab. The installation destination is chosen in Studio.

status

On success, the value is "awaiting-confirmation". Studio is showing or queuing a destination and installation confirmation dialog. No composition, dependency, or source-file installation is guaranteed yet.

target

On success, identifies the Studio that received the request.

projectName

The project name, or null if unavailable.

studioOrigin

The origin of the Studio that received the request.

studioVersion

The Remotion version running in that Studio.

compositionId

Deprecated

Deprecated since v4.0.530. Use projectName or studioOrigin to identify the receiving Studio. The installation destination is chosen in Studio.

Retained for compatibility. Contains the composition ID at the time of the request, or null when no composition is selected. It does not identify the final installation destination.

code

On failure, one of:

• unsupported-origin
• no-compatible-studio
• loopback-network-permission-denied v4.0.521
• studio-upgrade-required
• no-installable-target
• unsupported-protocol
• invalid-response
• target-expired
• request-rejected
• request-timed-out
• network-error

message

A human-readable failure message. Use code for application logic.

Discovery

When called outside Studio, ports 3000 through 3009 are probed in parallel. The most recently focused compatible tab is selected, or the only available writable tab if none has focus history v4.0.530. If multiple tabs are available and none has focus history, no tab is selected. A running Studio server without a connected, writable tab cannot receive a request. Discovery returns a short-lived, single-use token for the selected tab.

Supported origins

The function supports any HTTPS website. HTTP is supported only on localhost and 127.0.0.1 for local development.

Compatibility

Browsers			Environments
Chrome	Firefox	Safari	Client-side rendering	Server-side rendering	Player	Studio

See also

• Security