Using the VCS web renderer in your app
You've seen how the VCS simulator enables live testing of compositions within a web browser.
Using the VCS web renderer library, you can integrate that same capability into your own app. This is useful whenever you want to render live views that match how the VCS composition gets rendered on Daily's cloud. For example, you can offer your app's users a preview of the various layout and graphics options. It's much easier for users to understand how these options work if there's a live preview, and it's much easier for you to develop this live preview by using the VCS web renderer because it takes care of all the hard work of matching rendering.
It's even possible to use the VCS web renderer on its own, without using Daily's cloud VCS capabilities. One such scenario would be an Interactive Live Streaming type of application. These apps usually have a "main view" or "main stage" which should be shared by all viewers and participants. There is also typically a producer or host role who controls what appears on the stage. You can use the VCS web renderer to ensure that everyone has the same rendering which is driven by the VCS commands sent by the producer/host. All the clients will render their own views locally, but they're all guaranteed to match because they're using the same VCS composition and same control data.
In effect, the VCS web renderer on the client is like an advanced multi-track video player for a Daily room (or other media streams). You can configure it with all the rich options available in the VCS baseline composition, or you can even load your own composition with custom code. We'll look at these two options next, starting with the common ground they share.
These are the basic steps for rendering a VCS composition in the browser:
- Load the VCS web renderer library.
- Create an instance of the renderer by pointing it to a DOM element (usually an empty
<div>) which should contain the live content.
- Feed your renderer instance with input data like video tracks and param value updates.
The VCS web renderer instance will play on its own until you call
stop(). It takes care of managing display updates and all internal state. In that sense, it's a "black box" player. There are no requirements or mandatory dependencies imposed on the web app that contains the VCS web renderer.
Even though VCS uses React internally, your web app doesn't need to use React. But if you do use React in your web app, it won't conflict with the internal React state of VCS because they are kept entirely separate. So it also doesn't matter which version of React you're using in your app.
You can also create multiple VCS renderer instances if needed. For example, the producer view of a "Live Studio" style application might show two live views next to each other: one labeled Preview, the other Output. The user would be able to test layout and graphics changes that only affect the preview, then click a button to commit those changes to the output (which is the stream that viewers receive). This kind of two-step setup needs separate VCS renderer instances for the Preview and Output views.
There are two ways to use the VCS web renderer library:
- Load it from Daily's pre-built npm packages.
- Build your own composition and include it directly in your app.
If you are using a custom composition (i.e. you've written your own VCS React components or integrated other custom code), then you must choose the second option. Please see Building a JS package for more information.
If you're using Daily's baseline composition, we provide a pre-built version in the npm package
Note that this pre-built package is just the VCS composition and the web renderer library. It's quite low-level because it's independent of any web framework or even the Daily.js library. This means you don't need any other dependencies, but it can be somewhat laborious to integrate this low-level package in your app because you need to explicitly manage things like passing media streams to the renderer (so that it can play video tracks).
To help with integrating the VCS web renderer into an app that's using Daily.js and React, we are working on providing a high-level library that takes care of all the details.
We intend to release this Daily-VCS-React library and associated sample code as part of the VCS 1.0 launch.
@daily-co/vcs-composition-daily-baseline-web to your web app project. Then import the package:
import * as vcsComp from '@daily-co/vcs-composition-daily-rundown-web';
(If you're using your own custom composition, the instructions in Building a JS package will show you how to load
vcsComp from a custom-built JS library.)
vcsComp library object exposes a single function named
rootDOMElement must be a
<div> or other empty HTML element which will contain the VCS renderer's output.
viewportHeight must specify the viewport size, i.e. the resolution at which the VCS renderer will produce images.
initialSources must be an object with two properties,
imageAssets. These specify the initial inputs for the composition. See below for details on specifying composition input data.
Supported properties for
updateCb(function) - a callback that gets triggered when the composition is updated.
errorCb(function) - an error callback.
getAssetUrlCb(function) - a callback that gets called to load asset URLs requested by the composition.
fps(number) - the suggested frame rate for the VCS player (defaults to 30).
scaleFactor(number) - a display scale factor applied to the output within the given DOM element (defaults to 1).
enablePreload(boolean) - if true, the composition's image preloads are completed before
The API object returned by
startDOMOutputAsync() offers a number of methods.
The following are essential for controlling the renderer and settings its inputs:
stop()- stops the VCS renderer playback immediately.
setParamValue(paramId: string, value: any)- sets a value for param
setActiveVideoInputSlots(slots: Array)- sets the current video inputs.
The following additional methods provide information about the composition, let you provide optional room metadata, and send messages of known types like "chat" or "emoji reaction" (these are called standard sources):
getCompositionInterface()— returns the composition interface object which describes the params and other input types supported by the composition.
setRoomPeerDescriptionsById(peersById: Map)- sets room peer descriptions associated with video inputs (or audio-only participants who don't have a video input).
addStandardSourceMessage(sourceId: string, data: any)- adds a standard source message of type
To learn more about this API, you can read the VCS Simulator's source code. The simulator makes use of all these methods to create its UI and send data to the composition. The VCS Simulator is a single-file HTML+JS application without a build step, so its source is entirely in