useMediaPlayer

Media
stable

Headless media player engine shared by useAudioPlayer and useVideoPlayer. Owns all HTMLMediaElement event bindings (play, pause, ended, timeupdate, progress, volumechange, loadedmetadata, loadstart, canplay, waiting, error, ratechange) plus the Remote Playback API (cast / AirPlay). Suppresses autoplay when prefers-reduced-motion is active.

API

Signature

Full TypeScript signature sourced from the composable file.

typescript

useMediaPlayer is the single source of truth for HTMLMediaElement event wiring in origam. Specialised composables (useAudioPlayer, useVideoPlayer) layer type-narrowing and medium-specific features (fullscreen, PIP) on top of this base without duplicating the listener code.

Consumed interfaces

IUseMediaPlayerOptions
IMediaPlayerState
IMediaPlayerMethods

API

Parameters

Input parameters accepted by this composable.

options
IUseMediaPlayerOptions
{}
Accepts `mediaRef` (bring your own ref), `autoplay`, `muted`, `loop`, `preload`. All optional. When `autoplay` is true but the OS prefers-reduced-motion setting is active, a console warning is emitted and autoplay is suppressed.

API

Return values

Properties and methods exposed by the composable return object.

mediaRef
Template ref to bind to the native `<audio>` or `<video>` element. Reused from `options.mediaRef` when provided.
state
Reactive object: playing (Ref<boolean>), paused (Ref<boolean>), currentTime (Ref<number>), duration (Ref<number>), buffered (Ref<number>), volume (Ref<number>), muted (Ref<boolean>), ready (Ref<boolean>), loading (Ref<boolean>), error (Ref<MediaError | Error | null>), playbackRate (Ref<number>), remoteAvailable (Ref<boolean>), remoteState (Ref<"disconnected" | "connecting" | "connected">).
methods
Imperative controls: play(), pause(), toggle(), seek(seconds), setVolume(value), toggleMute(), load(), skipBackward(seconds), skipForward(seconds), setPlaybackRate(rate), requestRemotePlayback(), stopRemotePlayback(). All async methods swallow rejections into state.error.

Usage

Examples

Ready-to-paste usage snippets.

Custom video player UI

vue