@nextgensoftwares/folio-plugin-player

Folio's own video and audio players for resizableMedia. Guide: Media player.

Plugin

Export	Signature	Description
`playerPlugin`	`(options?: PlayerPluginOptions) => PlayerPlugin`	`media:video` / `media:audio` painters, the schema extension, commands, the Playback UI item and PDF/DOCX cards. List it after `mediaPlugin`
`type PlayerPluginOptions`		`media?` (a `MediaPlugin`: `resolveSrc` + placeholder painters), `resolveSrc?`, `video?` / `audio?` (default variant), `types?`, `exclusive?` (true), `rememberPosition?` (false), `waveform?` (true), `autoHideMs?` (2500), `icons?`, `ui?` (true), `prompt?`
`type PlayerPlugin`		`FolioPlugin` plus `painters`, `commands`, `settings`
`type PlayerSettings`		the resolved options every player reads from `PlayerSettingsContext`
`PlayerSettingsContext`, `DEFAULT_SETTINGS`		React context (and its default) for rendering players outside a page
`type PlayerIcons`, `type PlayerIconName`		host icon overrides: `Partial<Record<PlayerIconName, ReactNode>>`

Components

Export	Description
`VideoPlayer` / `type VideoPlayerProps`	`{ attrs: PlayerAttrs, variant? }`; fills its parent
`AudioPlayer` / `type AudioPlayerProps`	same for audio (`minimal` / `standard` / `full`)
`Scrubber` / `type ScrubberProps`	seek slider: buffered ranges, hover preview, chapters, optional waveform `peaks`
`createPlayerPainter(kind, settings, fallback?)`	the painter: selection, resize handles, editor-safe pointer/key handling
`type PlayerPainter`	`ComponentType<PainterProps>`
`selectMediaNode(editor, path)`	NodeSelection on a fragment's node
`playerCss`, `injectPlayerStyles(doc?)`	the stylesheet (injected once automatically)

Attributes and validation

Export	Description
`playerAttrs`, `playerSchema`	attr specs (`controls`, `tracks`, `chapters`, `autoplay`, `loop`, `startAt`, `artist`) and the `globalAttrs` extension for `resizableMedia`
`type MediaTrack`, `type TrackKind`	`{ src, label?, srclang?, kind?: 'captions' \| 'subtitles' \| 'descriptions', default? }`
`isValidTrack`, `isValidTracks`, `MAX_TRACKS`	strict track validation (safe src, no extra keys, ≤ 16)
`isSafeTrackSrc(src)`	plugin-media's safe-URL rules plus inline `data:text/vtt`
`isVariant`, `VARIANTS`, `type PlayerVariant`	`'minimal' \| 'standard' \| 'full'`
`readPlayerAttrs(attrs)`, `type PlayerAttrs`	defensive, typed read of a node's attrs (unsafe srcs dropped)

Commands and UI

Export	Description
`setPlayerAttrs(patch)`	sets validated player attrs (and `poster`, `title`, `height`) on the selected video/audio
`setPlayerVariant(variant)`	sets `controls`; for audio also the box height (`AUDIO_CARD_HEIGHT`)
`addTrack(track)`, `clearTracks()`	caption tracks
`validPatch(patch)`	the validation `setPlayerAttrs` uses
`playerCommands`, `type PlayerCommands`	`player.setAttrs`, `player.setVariant`, `player.addTrack`, `player.clearTracks`
`AUDIO_CARD_HEIGHT`	`{ card: 140, transcript: 300 }` px
`createPlaybackItems(prompt, defaults)`, `PLAYBACK_GROUP`	the routed "Playback" `UIItem` (group `media.playback`)
`playerPrintFallback(attrs)`	PDF/DOCX card: plugin-media's card plus poster/cover image and artist

Playback internals

Export	Description
`usePlayer(ref, behaviour)`, `type PlayerControls`, `type PlayerBehaviour`	wires a media element: src lifecycle/release, startAt/resume, muted autoplay, exclusive playback, actions
`useMediaState(ref, key)`, `type MediaState`	element state mirrored into React (rAF while playing)
`keyAction(event, target?)`, `keyTargetOf(el)`	the key map → `PlayerAction` (pure)
`type PlayerAction`, `type KeyTarget`, `type KeyLike`
`SEEK_SMALL`, `SEEK_LARGE`, `VOLUME_STEP`	5 s, 10 s, 0.05
`claimPlayback(el, exclusive)`, `releasePlayback(el)`	single active player
`loadPosition(id)`, `savePosition(id, time, duration)`	sessionStorage resume positions
`formatTime(s, reference?)`, `spokenTime(s)`, `parseTime(text)`, `SPEEDS`	clock text, aria text, "1:30" / "90" / "1m30s" parsing, 0.5–2×

WebVTT and waveform

Export	Description
`parseVtt(text)`, `type Cue`	WebVTT (and lenient SRT) → sorted `{ start, end, text }`; text only, capped
`cueText(raw)`, `vttTimestamp(s)`, `activeCue(cues, t)`	payload → plain text, timestamps, current cue (binary search)
`loadCues(src, resolveSrc)`, `MAX_VTT_BYTES`	safe, size-capped fetch + parse (cached; failures → `[]`)
`peaksFrom(samples, buckets?)`	normalized per-bucket peaks
`loadWaveform(url, buckets?)`, `MAX_WAVEFORM_BYTES`	lazy decode (Web Audio, 16 MB cap) → peaks or null