MediaController

Media
stable

Universal media controls shell shared by OrigamAudio and OrigamVideo. Purely presentational — receives state and methods from useMediaPlayer() and emits playback intents (play, pause, seek, volume, loop, shuffle, quality, download) without owning the HTMLMediaElement.

Structure

Anatomie

Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.

Anatomy of OrigamMediaControllerSchematic of the media controller with 6 numbered parts: root, header slot, scrubber row, buttons row (left group and right group), footer slot. 1 #header slot 2 3 prev | play | next | volume | time shuffle | loop | cast | cog 4 5 #footer slot 6
Anatomy of <origam-media-controller> — 6 internal parts. Root flex column ①, header slot ②, scrubber row ③ (OrigamMediaScrubber), transport row with left button group ④ (prev/play/next/volume/time) and right button group ⑤ (shuffle/loop/cast/cog), footer slot ⑥.
1.origam-media-controller
Root div. display: flex; flex-direction: column; gap: 0. When inset=true, applies .origam-media-controller--inset (position: absolute, dark gradient overlay, opacity: 0 by default). .origam-media-controller--visible toggles opacity: 1 and pointer-events: auto.
2#header slot
Optional header region above the scrubber. OrigamAudio injects cover art + metadata strip here.
3.origam-media-controller__progress-row
Scrubber row — padding: 0 12px. Contains OrigamMediaScrubber by default; replaceable via the #waveform slot.
4.origam-media-controller__buttons-left
Left transport group: previous, play/pause, next, volume control, time display. Flex row; gap: 2px. Buttons use variant="text" density="compact".
5.origam-media-controller__buttons-right
Right transport group: shuffle, loop, cast, config cog menu. Same sizing as the left group.
6#footer slot
Optional footer region below the transport row. OrigamAudio injects the playlist here.

API

Props

Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et description.

state
requis
IMediaPlayerState
—
Reactive media state from useMediaPlayer() (or a specialisation: useVideoPlayer, useAudioPlayer). Contains refs for playing, currentTime, duration, volume, muted, buffered, playbackRate, remoteAvailable, remoteState.
methods
requis
IMediaPlayerMethods
—
Imperative methods from useMediaPlayer(). Provides play(), pause(), seek(), setVolume(), toggleMute(), setPlaybackRate(), requestRemotePlayback().
inset
boolean
false
YouTube-style overlay mode: the shell sits on top of the media surface with a dark gradient and auto-hides on visible=false. When false, renders as a regular always-on toolbar.
visible
boolean
true
Visibility flag driven by the parent autohide logic. Only meaningful when inset=true. When false, the shell is opacity: 0 and pointer-events: none.
playbackRates
ReadonlyArray<number>
[0.5, 0.75, 1, 1.25, 1.5, 2]
Available playback rates exposed via the config cog menu. When the array has more than 1 entry, a "Playback speed" drill-down appears.
allowRemotePlayback
boolean
false
Enable the Cast / AirPlay button (Remote Playback API). The button only appears when this flag is true AND state.remoteAvailable is true at runtime.
downloadable
boolean
false
Adds a "Download" row to the config cog menu when true. Requires downloadUrl to be set.
downloadUrl
string | null
null
URL surfaced to the consumer when the Download menu item is clicked. Supports same-origin, data: and blob: URLs natively; cross-origin URLs are routed through a fetch → blob pipeline.
downloadFilename
string
Suggested filename for the downloaded file (<a download="…"> attribute).
qualityOptions
ReadonlyArray<TQualityOption>
[]
Optional list of quality variants. When ≥ 2 entries are present, a "Quality" drill-down appears in the config menu. Each entry is { quality: string; label: string }.
currentQuality
string | null
null
Currently-active quality identifier displayed as the appendText in the Quality menu row.
showPrevious
boolean
false
Show the "previous track" transport button. The parent listens to the previous emit and decides the action (skip back 10s or jump to the previous playlist track).
showNext
boolean
false
Show the "next track" transport button. The parent owns the action.
showLoop
boolean
false
Show the tri-state loop button (none → all → one → none). Supports v-model:loopMode.
showShuffle
boolean
false
Show the shuffle toggle button. Supports v-model:shuffle.
loopMode
TAudioLoopMode
'none'
Current loop mode: "none" | "all" | "one". The Controller cycles on click and emits update:loopMode; the parent applies its playlist or <audio loop> policy.
shuffle
boolean
false
Current shuffle state. The Controller toggles on click and emits update:shuffle; the parent switches its next-track resolution.
id
string
class
string | Array<string> | object
style
string | Array<string> | object | StyleValue

API

Slots

Emplacements de contenu exposés par ce composant.

#header
Block rendered above the scrubber row. OrigamAudio injects the cover art + metadata strip here; OrigamVideo typically leaves it empty.
#waveform
Replaces the default OrigamMediaScrubber. Receives state and methods so a custom waveform scrubber can still route seeks through methods.seek().
#footer
Block rendered below the transport row. OrigamAudio injects the playlist list here.
#prepend-transport
Buttons rendered at the start of the transport row, before the play button.
#append-transport
Buttons rendered at the end of the transport row, after the config menu.
#extraControlsLeft
Additional buttons on the left side of the toolbar, after the time display. Prefer prepend-transport for new code.
#extraControlsRight
Additional buttons on the right side of the toolbar, before the config menu. OrigamVideo injects captions / PiP / fullscreen buttons here.
#configExtra
Extra rows in the config cog menu. Receives a closeMenu callback. Used for audio output device selectors, subtitle track selectors, etc.

API

Emits

Événements émis par ce composant.

@quality-change
string
Fired when the user selects a quality level from the config menu. Payload is the quality identifier string. The parent owns the <source> swap logic.
@download
void
Fired when the Download menu item is clicked (before the anchor / fetch pipeline runs). Lets the parent observe the download intent immediately.
@previous
void
Fired when the previous transport button is clicked. Parent decides whether to skip back 10s or navigate to the previous playlist track.
@next
void
Fired when the next transport button is clicked. Parent owns the navigation action.
@update:loopMode
TAudioLoopMode
Emitted after each loop mode cycle. Use v-model:loopMode for two-way binding.
@update:shuffle
boolean
Emitted when the shuffle button is toggled. Use v-model:shuffle for two-way binding.

API

Membres exposés

Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.

Ref<boolean>
Reactive flag controlling the cog config menu open/close state. Can be read or set externally to programmatically open or close the menu.
ComputedRef<TAudioLoopMode>
The currently active loop mode computed from the internal state. Reflects the prop value unless the user cycled it via the loop button.
Ref<boolean>
Internal shuffle toggle state. Mirrors the shuffle prop and updates when the button is clicked.

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.

Text and icon color for the entire controller bar. Inherits from the parent surface by default.
Accent color applied to active transport buttons (loop-active, shuffle-active, cast-active). Background is a 14% tint of this color.
Override for the inner MediaScrubber progress/thumb color. Falls through to the scrubber default when unset.
Color 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

navigation

Interactions clavier

Interactions clavier
ToucheAction
TabMoves focus sequentially through all transport buttons (previous, play/pause, next, mute, volume slider, shuffle, loop, cast, cog).
Enter / SpaceActivates the focused transport button. Native <button> behaviour via OrigamBtn.
ArrowLeft / ArrowRightWhen the scrubber is focused: seeks backward/forward by step (default 0.1 s or 5 % of duration).
Home / EndWhen the scrubber is focused: seeks to the start or end of the media.

Notes

  • The transport row is a <nav> element with aria-label set via the i18n key "origam.media.transport". This correctly marks the zone as a landmark region.
  • Toggle buttons (shuffle, loop, cast) use aria-pressed reflecting their active state. Screen readers announce "pressed" or "not pressed" on focus.
  • All icon-only buttons carry an aria-label (play, pause, previous, next, mute, unmute, shuffle, loop-all/one/off, cast, stop-cast, settings). Labels are i18n-translated strings computed in the script, not hardcoded strings in the template.
  • The inner OrigamMediaScrubber uses role="slider", aria-orientation="horizontal", aria-valuemin/max/now/text and aria-label. See MediaScrubber accessibility notes for the full keyboard matrix.

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.

Source
color
var(--origam-color__text---primary)
Default text/icon color for the controller bar.
color
var(--origam-color__action--primary---bg)
Override color for the inner MediaScrubber timeline bar.

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 integration with useAudioPlayer

vue

Inset / overlay mode (YouTube-style)

vue