installInStudio()v4.0.502

Discovers a recently focused Remotion Studio and sends it an Element payload.

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.

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() when possible so the user can choose a specific Studio tab, timeline position, and canvas position.

Arguments

payload

The value returned by createElementPayload().

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
• 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

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.

Studios older than 4.0.502 are detected and return studio-upgrade-required. The Element is not sent through the legacy endpoint.

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