Player
A web component that plays a rendered video or a live project, with chapters.
Coming in the next release
@miraiclip/player is built and tested, and ships in the next SDK release.
<miraiclip-player> plays a rendered MP4 or WebM file, or a Miraiclip project live, with a scrubber, chapters and keyboard control. It is a web component, so it works on any page and with any framework.
npm install @miraiclip/player<script type="module">import "@miraiclip/player/define";</script>
<!-- A rendered file, with chapters from a WebVTT (or JSON) file -->
<miraiclip-player src="launch.mp4" chapters="launch.chapters.vtt" controls></miraiclip-player>
<!-- A project, played live. Chapters come from its markers -->
<miraiclip-player document="video.miraiclip.json" controls></miraiclip-player>Playing a file needs nothing else. Playing a project live also needs @miraiclip/core and @miraiclip/renderer installed; the player loads them only when it plays a project.
Attributes
| Attribute | What it does |
|---|---|
src | URL of a rendered video file |
document | URL of a project JSON file, played live |
chapters | URL of a WebVTT chapters file or a JSON list. Overrides the project's markers |
controls | Show the control bar (hidden while playing until hovered or focused) |
poster | Poster image for a file |
loop, muted | As on <video> |
assets-base | Base URL for a project's relative asset paths (default: the project file's URL) |
plugins | Load the project's plugins, for custom kinds |
The player sizes itself to the video's or project's aspect ratio.
Chapters
Chapters show as ticks on the scrubber, the current chapter's name in the control bar, and a chapter menu.
| Source | Format |
|---|---|
| A project's markers | Used automatically for document |
| WebVTT | A file that starts with WEBVTT, one cue per chapter |
| JSON | [{ "label", "start", "end"? }] in seconds, or [{ "label", "timeUs", "durationUs"? }] |
The chapters property | An array of { id, label, start, end } in seconds |
A chapter without an end runs until the next one.
JavaScript API
const player = document.querySelector("miraiclip-player")!;
player.addEventListener("chapterchange", (e) => console.log((e as CustomEvent).detail.chapter?.label));
player.goToChapter("step-2");
player.play();| Member | What it does |
|---|---|
play(), pause(), toggle() | Playback |
seek(seconds) | Jump to a time |
goToChapter(idOrIndex) | Jump to a chapter's start |
currentTime | Get or set the time in seconds |
duration, paused | Read-only state |
chapters | Get or set the chapter list |
currentChapterInfo | The chapter playing now |
document | Get or set a project document to play live, instead of a URL |
| Event | detail |
|---|---|
ready | none |
play, pause, ended | none |
timeupdate | none. Doesn't bubble |
chapterchange | { chapter } (null between chapters) |
error | { message } |
Keyboard
| Key | Action |
|---|---|
Space, K | Play or pause |
Right / L, Left / J | Forward or back 5 s (10 s with Shift) |
| Home, End | Start, end |
], [ | Next or previous chapter |
| Esc | Close the chapter menu |
Styling
Set these CSS variables on the element:
| Variable | Default |
|---|---|
--mc-accent | #22d3ee |
--mc-bg | #000 |
--mc-fg | #fff |
--mc-radius | 12px |
--mc-font | Inter, system-ui, sans-serif |
The parts frame, stage, big-play, controls, time, scrubber, chapter-label, chapters and error can be styled with ::part().
Register under another name
import { defineMiraiclipPlayer } from "@miraiclip/player";
defineMiraiclipPlayer("acme-player");The package also exports the chapter helpers it uses: parseVttChapters, normalizeChapters, chaptersFromMarkers, chapterAt and formatTime.