Video
Full-featured HTML5 video player with custom controls, picture-in-picture, fullscreen, captions, playback rate, cast/AirPlay and double-tap-to-skip. All browser native events are surfaced as Vue emits.
Structure
Anatomie
Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.
<origam-video> — 5 internal parts. The wrapper ① positions the native <video> with its poster overlay ②; the controls bar ③ overlays the bottom edge and contains the scrubber ④ and action buttons ⑤.- 1.origam-video
- Root wrapper. position: relative, aspect-ratio enforced, border-radius from rounded prop.
- 2.origam-video__poster
- Poster overlay rendered before playback starts. Hides on play. The #poster slot replaces it.
- 3.origam-video__controls
- Control bar. Overlaid (inset=true, default) or always-visible (inset=false). The #controls slot replaces the entire bar.
- 4.origam-video__scrubber
- Timeline scrubber — range input styled with CSS. Shows buffered region and playhead position.
- 5.origam-video__actions
- Trailing action buttons: volume, PIP, fullscreen, captions, cast, settings.
API
Props
Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et description.
- srcrequisstring | Array<IVideoSource>
- Media URL or an array of IVideoSource descriptors (for multi-codec fallback). The browser picks the first decodable source.
- posterstring
- Image shown before playback starts. Maps to the native poster attribute (or is used as background in the #poster slot).
- tracksArray<IVideoTrack>[]
- Caption/subtitle/chapter tracks. Each entry maps to a <track> element with kind, src, srclang and label.
- autoplaybooleanfalse
- Starts playback after loadedmetadata. Automatically sets muted=true (browser requirement). Suppressed when prefers-reduced-motion: reduce is active.
- mutedbooleanfalse
- Starts the player muted. Required alongside autoplay for unattended playback.
- loopbooleanfalse
- Restarts playback when the video ends.
- Control surface: custom (in-house toolbar), native (browser controls) or none (consumer drives via #controls slot or exposed methods).
- playsInlinebooleantrue
- Maps to the native playsinline attribute. Required on iOS to prevent the system hijacking playback.
- preload'none' | 'metadata' | 'auto''metadata'
- Buffering hint. metadata loads just enough to compute duration; auto pre-buffers aggressively.
- aspectRatiostring'16/9'
- CSS aspect-ratio applied to the wrapper. Prevents layout shift after metadata loads. Accepts presets (16/9, 4/3, 1/1, 21/9) or any raw value.
- crossoriginTCrossOrigin
- CORS crossorigin attribute. Required when the media is from a different origin and canvas/WebAudio access is needed.
- disablePictureInPicturebooleanfalse
- Hides the PIP button and its keyboard shortcut.
- skipSecondsnumber30
- Seconds skipped by the ±skip buttons and double-tap gesture. Pass 0 to hide skip buttons.
- showCenterControlsbooleantrue
- Shows centered ±skip and play/pause overlay on hover and while paused.
- playbackRatesReadonlyArray<number>[0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]
- Available playback rates exposed in the settings menu.
- playbackRatenumber1
- Initial playback rate (1 = normal). Synced via update:playbackRate.
- insetbooleantrue
- When true, the controls toolbar is overlaid on the video bottom edge and auto-hides during playback.
- allowRemotePlaybackbooleantrue
- Shows the cast/AirPlay button when the browser exposes the Remote Playback API and a device is available.
- doubleTapToSkipbooleantrue
- Double-tap left half = skip backward, right half = skip forward on touch devices.
- downloadablebooleanfalse
- Adds a Download row in the settings menu. Uses a native anchor with download attribute — no XHR.
- downloadFilenamestring
- Override for the downloaded file name. Useful when the URL is opaque (e.g. signed S3 URL).
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- colorTColor
- bgColorTColor
- heightnumber | string
- Overrides the wrapper height (normally driven by aspect-ratio).
- maxHeightnumber | string
- maxWidthnumber | string
- minHeightnumber | string
- minWidthnumber | string
- widthnumber | string
- Overrides the wrapper width. Default is 100%.
- Border-radius token applied to the video wrapper.
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>
- borderTopboolean | number | string
- borderLeftboolean | number | string
- borderBottomboolean | number | string
- borderRightboolean | number | string
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- elevationTElevation
- Box-shadow elevation applied to the video wrapper.
- fontSizeTFontSize
API
Slots
Emplacements de contenu exposés par ce composant.
- #controls
- Full toolbar replacement. Receives the complete IVideoScopedSlotBindings state + imperative methods. The built-in toolbar uses the same surface.
- #poster
- Overlay rendered before playback starts (currentTime===0 && paused). When absent, the poster prop is used as a background-image on the video element.
- #loading
- Custom overlay rendered while the media is buffering.
- #error
- Custom overlay rendered when a media error occurred. Receives the error object.
API
Emits
Événements émis par ce composant.
- @enterfullscreenvoid
- Fired when the player enters fullscreen.
- @exitfullscreenvoid
- Fired when the player exits fullscreen.
- @enterpipvoid
- Fired when picture-in-picture mode is entered.
- @exitpipvoid
- Fired when picture-in-picture mode is exited.
- @skipnumber
- Fired by skip buttons and double-tap gesture. Positive = forward, negative = backward (in seconds).
- @quality-changestring
- Fired when the viewer picks a different quality from the settings menu.
- @downloadstring
- Fired when the Download row is clicked. Payload is the file URL.
- @playvoid
- Fired when playback starts or resumes.
- @pausevoid
- Fired when playback is paused.
- @endedvoid
- Fired when the video reaches the end.
- @timeupdatenumber
- Fired periodically with the current playhead position in seconds.
- @volumechangenumber
- Fired when volume or muted state changes. Payload is the new volume (0–1).
- @loadedmetadata{ duration: number }
- @errorMediaError | Error
- @update:playbackRatenumber
API
Membres exposés
Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.
- Ref<HTMLVideoElement | null>
- Direct reference to the underlying HTMLVideoElement. Use for advanced integrations (WebGL, WebAudio, canvas).
- IVideoPlayerState
- Reactive state object: playing, paused, currentTime, duration, buffered, volume, muted, fullscreen, pip, loading, error, playbackRate.
- IVideoPlayerMethods
- Imperative methods: play, pause, togglePlay, seek, setVolume, toggleMute, enterFullscreen, exitFullscreen, toggleFullscreen, requestPip, exitPip, togglePip.
Personnalisation
Variables CSS
Propriétés CSS personnalisées exposées par ce composant. Surchargez-les pour personnaliser sans perdre la compatibilité avec le thème.
- Video wrapper background (black by default for letterboxing).
- Corner radius of the video wrapper.
- Controls bar background (very dark for legibility on any content).
- Size of control buttons in the toolbar.
- Accent color of the playhead/thumb on the scrubber.
- Font size for the current-time / duration display.
Inclusion
Accessibilité
Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.
Rôles ARIA
Interactions clavier
| Touche | Action |
|---|---|
| Space / K | Toggle play/pause (when focus is on the player or controls). |
| ArrowRight / ArrowLeft | Seek forward/backward by 5 seconds. |
| ArrowUp / ArrowDown | Increase/decrease volume by 10%. |
| M | Toggle mute. |
| F | Toggle fullscreen. |
Notes
- Subtitles/captions are provided via the tracks prop using WebVTT format. The captions button in the toolbar toggles the active track.
- Autoplay is suppressed when prefers-reduced-motion: reduce is active, respecting the user preference.
- The controls bar uses aria-label for icon-only buttons (play, mute, fullscreen). The scrubber is a range input with aria-label, aria-valuemin, aria-valuemax and aria-valuenow.
Fondation
Design tokens
Extrait des tokens de ce composant — les variables --origam-<composant>---<propriété>, déclarées dans sa feuille de tokens tenue à la main, sans étape de build.
- colorvar(--origam-color---black)
- Wrapper background.
- dimensionvar(--origam-radius---md)
- Corner radius.
- colorvar(--origam-color__neutral---950)
- Controls bar background.
- colorvar(--origam-color__primary---500)
- Scrubber accent color.
- dimensionvar(--origam-space---16)
- Size of the centered play button on the poster overlay.
Interactif
Playground
Modifiez les props en direct et observez le composant se mettre à jour. Le snippet de code généré suit vos changements.
Rendu de l’aperçu en cours…
Usage
Exemples
Extraits de code prêts à coller dans vos templates.
Basic player
Autoplay muted loop
Custom controls slot