Video

Configure video source, poster, preload, autoplay, loop, muted, volume, and playback options.

Video configuration controls the underlying <video> element — its source, poster image, autoplay behavior, looping, volume, and more. Only src is required; all other fields have sensible defaults that work out of the box.

import { useScena } from '@retoo/scena';

import '@retoo/scena/styles';

const scena = useScena();

await scena.mount({
  video: {
    src: '/video.mp4',
    poster: '/poster.jpg',
    autoplay: false,
    loop: true,
    muted: true,
  },
});

Properties

Property	Type	Default	Description
`src`	`string`	—	Video file URL. Required.
`poster`	`string`	—	Image shown before playback starts
`type`	`string`	—	MIME type hint (e.g. `video/mp4`)
`autoplay`	`boolean`	`true`	Start playing automatically on mount
`loop`	`boolean`	`true`	Restart playback when the video ends
`muted`	`boolean`	`true`	Start with audio muted
`volume`	`number`	`1`	Initial volume level (0.0 to 1.0)
`startTime`	`number`	`0`	Start playback from this time in seconds
`preload`	`string`	`metadata`	Preload strategy — `none`, `auto`, `metadata`
`crossorigin`	`string`	—	CORS setting — `anonymous`, `use-credentials`
`playsinline`	`boolean`	`true`	Play inline on mobile instead of fullscreen
`controls`	`boolean`	`false`	Show native browser video controls

Autoplay

Most mobile browsers block autoplay with sound. Set both autoplay: true and muted: true to ensure autoplay works across all devices — this is the default configuration.

Unmuting after a user interaction is allowed by all browsers:

import { ScenaEvent } from '@retoo/scena';

instance.api.events.on(ScenaEvent.ON_VIDEO_CONTAINER_CLICK, () => {
  instance.api.controller.unmute();
});

Poster image

The poster is displayed before playback starts and while the video is loading. With autoplay: false, the poster stays visible until the user initiates playback.

import { useScena } from '@retoo/scena';

import '@retoo/scena/styles';

const scena = useScena();

await scena.mount({
  video: {
    src: '/video.mp4',
    poster: '/poster.jpg',
    autoplay: false,
  },
});

Preload strategy

Controls how much video data the browser downloads before playback:

Value	Behavior
`none`	No data preloaded — minimal bandwidth
`metadata`	Duration, dimensions, and first frame only (default)
`auto`	Browser decides how much to buffer

Runtime

Swap the source or change playback settings without remounting:

import { useScena } from '@retoo/scena';

import '@retoo/scena/styles';

const scena = useScena();

const instance = await scena.mount({
  video: { src: '/video.mp4' },
});

instance.config.mergeConfig({
  video: { src: '/new-video.mp4', poster: '/new-poster.jpg' },
});

Customization

import { useScena } from '@retoo/scena';

import '@retoo/scena/styles';

const scena = useScena();

await scena.mount({
  video: {
    src: '/video.mp4',
    customClasses: { root: 'rounded-none' },
    customStyles: {
      root: { objectFit: 'contain' },
    },
  },
});

Placement

Anchor the widget within the viewport or container using a 3x3 grid model.

Styles

Customize the widget appearance with CSS custom properties (variables).