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
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<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
All props accepted by this component, with their type, default value and description.
- staterequiredIMediaPlayerState—
- Reactive media state from useMediaPlayer() (or a specialisation: useVideoPlayer, useAudioPlayer). Contains refs for playing, currentTime, duration, volume, muted, buffered, playbackRate, remoteAvailable, remoteState.
- methodsrequiredIMediaPlayerMethods—
- 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
Content slots exposed by this component.
- #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
Events emitted by this component.
- @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
Exposed members
Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.
- 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.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- 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
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
Keyboard interactions
| Key | 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.
Foundation
Design tokens
Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.
- 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.
Interactive
Playground
Edit props live and see the component update in real time. The generated code snippet updates as you change values.
Rendering the live preview…
Usage
Examples
Ready-to-paste code snippets for your templates.
Basic integration with useAudioPlayer
Inset / overlay mode (YouTube-style)