VCS WebFrame component

Renders an embedded web page. Similar to <iframe> element in HTML, but with the following essential differences:

You can only use one WebFrame element inside a VCS composition. (In other words, WebFrame is a “singleton”.)
- Creating multiple WebFrame elements is undefined behavior. They will render the same content even if you set different source URLs. To avoid this, use only one WebFrame element in your composition.
The WebFrame element doesn’t update at a guaranteed frame rate. You should assume the content will be refreshed about two times per second (2 fps).
You can control the web page by sending keyboard events to it (see section below).

In practice, WebFrame behaves a lot like an image component that renders a live web page instead of a static image asset. You can use all the props that exist on <Image>.

WebFrame is ideal for displaying embedded documents or web-based live widgets, but it is not a media player. You shouldn’t use it for web pages that contain video or dynamic animated content because the frame rate is too low. (To play online video sources in a Daily room, you can use Remote Media Player, a beta feature. Remote Media Player behaves like a participant in the room so it doesn’t require any special handling in VCS. For more information about Remote Media Player,.)

The src prop sets the URL of the web page to be loaded. Note that VCS will load this URL on Daily’s cloud-based media servers, so the page must be publicly accessible. The viewportSize prop sets the size of the embedded browser window in pixels. The value must be an object containing properties w and h. You should always set this prop to a value that fits your content. If unset, WebFrame will use a default viewport size. The default size is currently 1280*720 pixels, but could change depending on rendering environment.

The choice of viewport size is very important to make your web page look good when embedded in a video stream. If you use a large viewport size, text within the web page may become too small to read after it’s been encoded into video. It’s usually better to use a smaller viewport to make the page elements more legible. Remember that the WebFrame element scales just like an image, so you don’t have to use a viewport size that matches your output video size exactly. (Your web browser’s Developer Tools can be useful in determining a suitable size: load up the page you want to embed, open Developer Tools, and resize the window; the viewport size will be displayed as you resize.)

Code example:

import * as React from 'react';
import { WebFrame } from '#vcs-react/components';

  const src = 'https://example.com';
  const size = { w: 960, h: 640 };
  const opacity = 0.9;
  return <WebFrame src={src} viewportSize={size} blend={{ opacity }} />;
}

Props

Properties specific to the <WebFrame> component:

Name	Type	Description	Default value
`src`	`String`	A URL to be loaded into the embedded web browser.	`null`
`viewportSize`	`Object`	The size of the viewport for the embedded web browser. See description above.	`null`
`keyPressAction`	`Object`	A simulated key press to be sent to the embedded web browser. See description above.	`null`

Properties shared with the <Image> component:

Name	Type	Description	Default value
`scaleMode`	`String`	Determines how the browser image should be rendered within its layout frame. Available values: `"fit"` — image is rendered without any cropping, centered inside its layout frame, scaled as needed, `"fill"` — image is cropped and scaled to fill its layout frame	`"fit"`
`transform`	`Object`	An object defining transformations to be applied at the compositing stage. Supported properties: `rotate_deg` (Number), which specifies the rotation of the component in degrees.	`null`
`blend`	`Object`	An object of compositing-related properties. Supported child properties: `opacity`: (Number), which can range from 0 to 1 (0 is fully transparent, 1 is fully opaque). If you don’t pass a value for `blend`, or the object you pass doesn’t include `opacity`, it defaults to full opacity.	`null`

Properties available to all VCS components, including this one.

Name	Type	Description	Default value
`id`	`String`	A name of your choice for the component instance. Works just like the “id” property in HTML. Primarily useful for debugging.	`null`
`key`	`String`, `Number`	This prop has a special meaning to the React runtime. When you render components inside an array (e.g. a list), each individual item in the array should have a different value for the key prop. React uses this internally to quickly compare the rendered array with its previous version.	`null`
`style`	`Object`	An object of style. Each component class has its own supported style properties. For example, the `Text` lets you select font styles and sizing using style, but these are not relevant to other components. Note: VCS style properties are not the same as CSS properties.	`{}`
`layout`	`Array`	Allows you to hook into your rendered components into the VCS layout system. After the React render cycle completes, the layout system computes final layout frames (coordinates within the output viewport). You can guide the layout process using callback functions and data you provide using the layout prop. The first value of the array must be a layout function. The second (optional) value can be a data object containing param values, which is passed to the layout function when computing the layout. See Layout API for more details.	`null`

`style` prop

The style prop accepts an object that can have the following values set:

Name	Type	Description
`cornerRadius_px`	`Number`	Apply a rounded mask to the corners of the component.

Sending events to the web page

You can interact with the page loaded into a WebFrame by sending it a key press action, a simulated keyboard event. This is particularly useful for document viewers. For example, if you’re embedding a Google Slides presentation, you might want to first send a key press to enter slideshow mode, then send arrow keys to navigate between slides. The key press action is described using a prop called keyPressAction, which is available on the WebFrame component. Its value must be an object with the following properties:

name - the name of the key to be pressed. (See below for list of key names.)
modifiers - a list of modifier keys to be activated for the key press.
- Possible values are: "Shift", "Control", "Alt", "Meta"
- On a Mac keyboard, "Alt" is equal to Option and "Meta" is equal to Command.
- You should combine the keys with a plus sign. E.g. "Shift+Meta"
key - a unique identifier for this specific key press.
- Should be an integer greater than zero.

The key property is required because a key press is functionally an event occurring at a specific moment in time (the simulated key is pressed and depressed). Because the same keys can be pressed over and over, we need a way to tell VCS when a key press has just happened. The key property accomplishes this. When you update key to a new value, VCS will send the simulated event to the embedded browser.

Note that ‘key’ in this context means something other than a key on the physical keyboard. We opted to follow the established convention of React, where ‘key’ means this kind of distinguishing unique identifier.

Key names

The following key names are supported:

Digits 0 - 9
Letters A - Z
ASCII special characters, e.g. !, @, +, >, etc.
Function keys F1 - F12
Enter
Escape
Backspace
Tab
Arrow keys ArrowUp, ArrowDown, ArrowLeft, ArrowRight
PageDown, PageUp

You can combine these with the modifiers listed previously.

Code example

The following example functions create key press actions to control a Google Slides document.

let kpkey = 0;

export function makeKeyPressAction_StartSlideShow() {
  return {
    name: 'Enter',
    modifiers: 'Shift+Meta',
    key: ++kpkey,
  };
}

export function makeKeyPressAction_NextSlide() {
  return {
    name: 'ArrowRight',
    modifiers: '',
    key: ++kpkey,
  };
}

Note that the returned object from these functions would be used as the keyPressAction prop value for a WebFrame component. (In a real application, you’d probably want to store kpkey in a React ref within the component that contains the WebFrame.)

Getting Started

Core Concepts

Components

Custom React Hooks

Tools

VCS WebFrame component

Props

`style` prop

Sending events to the web page

Key names

Code example

​Props

​style prop

​Sending events to the web page

​Key names

​Code example

Props

`style` prop

Sending events to the web page

Key names

Code example