MediaController
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.
<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.
- staterequisIMediaPlayerState—
- Reactive media state from useMediaPlayer() (or a specialisation: useVideoPlayer, useAudioPlayer). Contains refs for playing, currentTime, duration, volume, muted, buffered, playbackRate, remoteAvailable, remoteState.
- methodsrequisIMediaPlayerMethods—
- Imperative methods from useMediaPlayer(). Provides play(), pause(), seek(), setVolume(), toggleMute(), setPlaybackRate(), requestRemotePlayback().
- insetbooleanfalse
- 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.
- visiblebooleantrue
- Visibility flag driven by the parent autohide logic. Only meaningful when inset=true. When false, the shell is opacity: 0 and pointer-events: none.
- playbackRatesReadonlyArray<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.
- allowRemotePlaybackbooleanfalse
- Enable the Cast / AirPlay button (Remote Playback API). The button only appears when this flag is true AND state.remoteAvailable is true at runtime.
- downloadablebooleanfalse
- Adds a "Download" row to the config cog menu when true. Requires downloadUrl to be set.
- downloadUrlstring | nullnull
- 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.
- downloadFilenamestring
- Suggested filename for the downloaded file (<a download="…"> attribute).
- qualityOptionsReadonlyArray<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 }.
- currentQualitystring | nullnull
- Currently-active quality identifier displayed as the appendText in the Quality menu row.
- showPreviousbooleanfalse
- 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).
- showNextbooleanfalse
- Show the "next track" transport button. The parent owns the action.
- showLoopbooleanfalse
- Show the tri-state loop button (none → all → one → none). Supports v-model:loopMode.
- showShufflebooleanfalse
- Show the shuffle toggle button. Supports v-model:shuffle.
- loopModeTAudioLoopMode'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.
- shufflebooleanfalse
- Current shuffle state. The Controller toggles on click and emits update:shuffle; the parent switches its next-track resolution.
- idstring
- classstring | Array<string> | object
- stylestring | 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-changestring
- 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.
- @downloadvoid
- Fired when the Download menu item is clicked (before the anchor / fetch pipeline runs). Lets the parent observe the download intent immediately.
- @previousvoid
- Fired when the previous transport button is clicked. Parent decides whether to skip back 10s or navigate to the previous playlist track.
- @nextvoid
- Fired when the next transport button is clicked. Parent owns the navigation action.
- @update:loopModeTAudioLoopMode
- Emitted after each loop mode cycle. Use v-model:loopMode for two-way binding.
- @update:shuffleboolean
- 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
Interactions clavier
| Touche | Action |
|---|---|
| Tab | Moves focus sequentially through all transport buttons (previous, play/pause, next, mute, volume slider, shuffle, loop, cast, cog). |
| Enter / Space | Activates the focused transport button. Native <button> behaviour via OrigamBtn. |
| ArrowLeft / ArrowRight | When the scrubber is focused: seeks backward/forward by step (default 0.1 s or 5 % of duration). |
| Home / End | When 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.
- colorvar(--origam-color__text---primary)
- Default text/icon color for the controller bar.
- colorvar(--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
Inset / overlay mode (YouTube-style)