Video Component

Type-safe video element component with browser policy enforcement.

Import

import codes.yousef.summon.components.media.Video
import codes.yousef.summon.components.media.VideoSource

Overview

The Video component provides a type-safe video element that maps Kotlin booleans to proper HTML5 video attributes and enforces browser policies (e.g., autoplay requires muted).

Function Signature

@Composable
fun Video(
    src: String? = null,
    sources: List<VideoSource> = emptyList(),
    poster: String? = null,
    autoplay: Boolean = false,
    muted: Boolean = false,
    loop: Boolean = false,
    controls: Boolean = true,
    playsInline: Boolean = true,
    preload: String = "metadata",
    crossorigin: String? = null,
    width: String? = null,
    height: String? = null,
    ariaLabel: String? = null,
    modifier: Modifier = Modifier()
)

Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | src | String? | null | Primary video source URL (ignored if sources is provided) | | sources | List<VideoSource> | emptyList() | List of video sources for format fallback | | poster | String? | null | URL to poster image displayed before playback | | autoplay | Boolean | false | Whether to start playing automatically (requires muted) | | muted | Boolean | false | Whether the video is muted | | loop | Boolean | false | Whether to loop the video | | controls | Boolean | true | Whether to show playback controls | | playsInline | Boolean | true | Whether to play inline on mobile (not fullscreen) | | preload | String | "metadata" | Preload strategy: "none", "metadata", or "auto" | | crossorigin | String? | null | CORS setting: "anonymous" or "use-credentials" | | width | String? | null | Video width (can also use modifier) | | height | String? | null | Video height (can also use modifier) | | ariaLabel | String? | null | Accessibility label for the video | | modifier | Modifier | Modifier() | Styling modifier for the video element |

Browser Autoplay Policy

Modern browsers require videos to be muted for autoplay to work. If you set autoplay = true with muted = false, the component will automatically set muted = true to comply with browser policies and log a warning.

VideoSource

Data class for defining multiple video sources with format fallback:

data class VideoSource(
    val src: String,   // URL to the video file
    val type: String   // MIME type (e.g., "video/mp4", "video/webm")
)

Examples

Basic Usage

Video(
    src = "https://example.com/video.mp4",
    modifier = Modifier().width("100%").maxWidth("800px")
)

Autoplay Hero Video

// Muted is auto-enforced for autoplay
Video(
    src = "https://example.com/hero.mp4",
    autoplay = true,
    loop = true,
    controls = false,
    poster = "https://example.com/poster.jpg"
)

Multiple Sources for Format Fallback

Video(
    sources = listOf(
        VideoSource("video.webm", "video/webm"),
        VideoSource("video.mp4", "video/mp4")
    ),
    controls = true
)

Responsive Video

Video(
    src = "video.mp4",
    modifier = Modifier()
        .responsiveMedia()
        .aspectRatio(16, 9)
)

Pause on Scroll

Box(modifier = Modifier().pauseOnScroll()) {
    Video(
        src = "hero-video.mp4",
        autoplay = true,
        muted = true,
        loop = true
    )
}

MIME Type Inference

When using src instead of sources, the component automatically infers the MIME type from the file extension:

| Extension | MIME Type | |-----------|-----------| | .mp4 | video/mp4 | | .webm | video/webm | | .ogg | video/ogg | | .mov | video/quicktime |

Accessibility

Use ariaLabel to provide descriptive text for screen readers
Always include controls = true unless the video is purely decorative
Consider providing captions for videos with spoken content