Layer Types

When using scene composition, we provide a number of layout types you can choose to render in your layout.

Supported types

• Media
  • Image
  • Video
  • Source
  • WebRTC
  • Webpage
• Shapes
  • Square

Properties

All layers in a layout support the following positioning and appearance properties:

• x
• y
• width
• height
• scale: This scales the entirety of a layer up, following CSS transform rules. The layer will be scaled up from the x/y position. At scale 2 the set width and height would be doubled when rendered.
• opacity: An opacity between 0 and 1, 0.5 being half opacity.
• rotation: Rotation from the center of layer, between -360 and 360.
• hidden: Whether the layer is hidden in a layout. If a layer is hidden, any sound produced by the layer will be muted (consider using opacity if this isn't the wanted behavior).

Using these types

Using the Layout API, you can insert a layer into the Layout by calling create. The type field of the layer specifies what type (defined below) to display and the data field contains any custom configuration. The following example represents how to add an image to a layout, this is implemented using our SDK but the same concepts apply when using the REST API or GRPC bindings.

Keep in mind all layers must be a child of the root layer.

import { ApiStream } from '@api.stream/sdk';

const client = new ApiStream({ /* .. */ });
const LAYOUT_ID = 'fake-layout-42fa-be5f-addd9d14641e';

// List all existing layers within the layout.
const response = await api.LayoutApi().layer.listLayers({ layoutId: LAYOUT_ID });

// When a layout is created with the "scene" type, a layer with type "root" will be automatically created. Any 
// layers should be assigned as children to that.
const rootLayer = response.layers.find(layer => layer.type === 'root');


// Create the layer
client.LayoutApi().layer.createLayer({
    layoutId: LAYOUT_ID,
    layer: {
        type: 'image',
        x: 15,
        y: 15,
        height: 50,
        scale: 0.5,
        parentId: rootLayer.id,
        data: { media: { url: 'https://api.stream/img/Horizontal-Logo-Primary-Color.svg' } },
    },
});

Media Types

Image

Type: image

The image type enables you to display an image from an external location.

Data Payload:

field	type	required	description	example
media.url	string	✅	The URL to an externally hosted image. Any image format that is supported by modern browsers will work.	"https://api.stream/img/Horizontal-Logo-Primary-Color.svg"

Example

{
    "type": "image",
    "data": {
        "media": {
            "url": "https://api.stream/img/Horizontal-Logo-Primary-Color.svg"
        }
    }
}

Video

Type: video

The video type enables you to display an video from an external location. Any video format that is supported by modern browsers is supported here.

Data Payload:

field	type	required	description	example
video.url	string	✅	The URL to an externally hosted video.	"https://example.org/video.mp4"
video.volume	number		The volume play audio at. The range is 0 - 1, 0.5 being half volume. Defaults to 1	0.5

Example

{
    "type": "video",
    "data": {
        "media": {
            "url": "https://example.org/test.mp4",
            "volume": 0.5
        }
    }
}

Source

Type: source

The source type enables you to display an RTMP video source into.

note

You must register the source with the Live API and register it to the project prior to adding to a layout.

Data Payload:

field	type	required	description	example
source.id	string	✅	The Live API identifier for a video source.	"sourceid"
source.volume	number		The volume play associated audio at. The range is 0 - 1, 0.5 being half volume. Defaults to 1	0.5
onDisconnect	'remain', 'slate', 'hide'		Action to take when the source disconnects. 'remain' will leave the frozen source, 'slate' will display a customizable overlay image and 'hide' will hide the source from the render. Defaults to 'slate'	"slate"
disconnectedSlate.url	string		Customizes the image displayed when a source is disconnected. This requires onDisconnect to be set to 'slate'	"https://api.stream/img/Horizontal-Logo-Primary-Color.svg"

WebRTC

Type: webrtc

The webrtc type enables you to pull in sources from our hosted WebRTC offering.

Data Payload:

field	type	required	description	example
webrtc.id	string	✅	The participant ID of the user.	"apistream"
webrtc.type	"webcam", "screenshare"		Type of media to display. Defaults to webcam.	"webcam"
webrtc.volume	number		The volume play associated audio at. The range is 0 - 1, 0.5 being half volume. Defaults to 1.	0.5
onDisconnect	'slate', 'hide'		Action to take when the WebRTC participant disconnects. 'slate' will display a customizable overlay image while 'hide' will hide the source from the render. Defaults to 'slate'	"slate"
disconnectedSlate.url	string		Customizes the image displayed when the WebRTC participant is disconnected. This requires onDisconnect to be set to 'slate'	"https://api.stream/img/Horizontal-Logo-Primary-Color.svg"

Example

{
    "type": "webrtc",
    "data": {
        "webrtc": {
            "id": "apistream",
            "type": "screenshare",
            "volume": 0.5
        }
    }
}

Webpage

Type: webpage

The webpage layer type enables you to load an externally hosted webpage within a layout.

Data Payload:

field	type	required	description	example
url	string	✅	An externally hosted URL to load. Note: the webpage in question must not have a strict CSP nor serve a strict x-frame-options headers	"https://example.org"

Example

{
    "type": "webpage",
    "data": {
        "url": "https://example.org"
    }
}

Shapes

Square

Type: square

Displays a square.

Data Payload:

field	type	required	description	example
backgroundColor	string	✅	A CSS background-color value. This can be HEX, RGBA (or any supported CSS value)	"#FFF000"

Example

{
    "type": "square",
    "data": {
        "backgroundColor": "red"
    }
}