useMediaPlayer
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.
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
API
Parameters
Input parameters accepted by this composable.
- optionsIUseMediaPlayerOptions{}
- 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