installInStudio()v4.0.502

Sends an Element payload to the containing Remotion Studio, or discovers a recently focused 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 is used. Also offer drag-and-drop with setStudioDragData() when possible so the user can choose a specific Studio tab, timeline position, and canvas position.

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 returned composition is the context for the request; the final 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, contains the project name, contextual composition ID, Studio origin, and Studio version.

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 target is selected. Discovery returns a short-lived, single-use token bound to that Studio tab and contextual composition.

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