VideoPlayer

The VideoPlayer component renders a fully self-contained video player inside a Shadow DOM — styles are isolated so they never conflict with the host page.

Installation

pnpm add @seeen/player

Basic usage

import { VideoPlayer } from "@seeen/player";

<VideoPlayer
  src="https://example.com/video.m3u8"
  poster="https://example.com/thumb.jpg"
  title="My Video"
/>

Autoplay

Browsers block autoplay with sound. Set both autoplay and muted to satisfy browser policies.

<VideoPlayer src="..." autoplay muted />

Moments (chapters)

Pass a moments array to enable chapter navigation. A scrollable nav strip renders above or below the video (momentsNavPosition), and chapter markers appear on the progress rail.

<VideoPlayer
  src="https://example.com/video.m3u8"
  moments={[
    { id: "1", title: "Intro",     startTimestamp: 0,     endTimestamp: 30000,  duration: 30000 },
    { id: "2", title: "Chapter 2", startTimestamp: 30000, endTimestamp: 120000, duration: 90000 },
  ]}
  momentsNavPosition="below"
/>

Props

Prop	Type	Required	Description
activeMoment	Moment	optional	Pre-selects a moment by object, seeking to it on first play. Takes precedence over `activeMomentId`.
activeMomentId	string	optional	Pre-selects a moment by ID, resolved against the `moments` array. Ignored when `activeMoment` is set.
aspectRatio	string	optional	Aspect ratio of the video, e.g. `"16:9"` or `"9:16"`. Defaults to `"16:9"`.
autoplay	boolean	optional	Start playing automatically on load. Most browsers require `muted` for autoplay to work.
captions	Caption[]	optional	Closed-caption tracks added to the `<video>` element.
ctaTimestamps	CtaTimestamp[]	optional	Timestamped CTA banners that appear at specific points during playback.
endCard	EndCardType	optional	End card shown when playback finishes. Overrides `sponsor`.
gaMeasurementId	string	optional	Google Analytics 4 measurement ID (e.g. `"G-XXXXXXXXXX"`). Enables play/pause/complete event tracking.
momentEndSplash	boolean	optional	Show a "Watch Again / Resume Video" splash when the `activeMoment` ends. Requires `activeMoment`.
momentNavBehavior	"seek" | "moment"	optional	What clicking a card in `MomentsNav` does. `"moment"` (default) jumps to the moment's start and makes it the active moment, as if it were passed via `activeMomentId`: playback stops at the moment's end and the end splash is shown (when `momentEndSplash` is enabled). `"seek"` only jumps to the start and keeps playing.
moments	Moment[]	optional	Moments (chapters) displayed in the `MomentsNav` strip and `MomentsBar` progress indicator.
momentsNavPosition	"above" | "below" | "none"	optional	Where the `MomentsNav` strip is rendered relative to the video. Defaults to `"above"`.
muted	boolean	optional	Mute the video. Set alongside `autoplay` to satisfy browser autoplay policies.
overlays	CtaOverlay[]	optional	CTA image overlays displayed at fixed positions over the video.
poster	string	optional	URL of the poster image shown before playback begins.
shareSocialMediaIcons	SocialMediaIcon[]	optional	Social share icons shown in the share popover.
sponsor	Sponsor	optional	Sponsor shown on the end card when no explicit `endCard` is provided.
src	string	required	URL of the video source. HLS (`.m3u8`) and MP4 are supported.
startTime	number	optional	Seek to this position (in seconds) on first play. Ignored when `activeMoment` is set.
structuredData	Record	optional	Parsed schema.org `VideoObject` — moments are merged in as `hasPart` Clips and injected as a `<script type="application/ld+json">`.
thumbnailStoryboardUrl	string	optional	URL of a WebVTT thumbnail storyboard used for scrubber previews.
title	string	optional	Video title shown as an overlay in the top-left corner.
videoId	string	optional	Video ID reported on all analytics events.