Media
Universal media controls shell (controller, scrubber, volume) consumed by OrigamAudio and OrigamVideo. Headless and media-agnostic — drives any HTMLMediaElement via state + methods refs from useMediaPlayer().
Structure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-media-controller> — 6 internal zones: header slot, progress row (scrubber), transport row (buttons), footer slot, plus prepend/append transport injection points.- 1.origam-media-controller
- Root container. When inset=true, overlays the media surface with a gradient.
- 2.origam-media-controller__progress-row
- Hosts the OrigamMediaScrubber timeline (or the #waveform slot override).
- 3.origam-media-controller__buttons-row
- Transport row: play/pause, previous/next, time display, volume, config menu.
- 4.origam-media-controller__time
- Current time / total duration display. Children: __time-current, __time-sep, __time-total.
- 5.origam-media-controller__buttons-left
- Left side of transport row. Hosts #prepend-transport slot, play/pause, previous/next, time.
- 6.origam-media-controller__buttons-right
- Right side of transport row. Hosts #extraControlsRight slot, volume control, config menu.
API
Props
All props accepted by this component, with their type, default value and description.
- staterequiredIMediaPlayerState—
- Reactive media state from useMediaPlayer() (or a specialisation). Required.
- methodsrequiredIMediaPlayerMethods—
- Imperative methods from useMediaPlayer(). Required.
- insetbooleanfalse
- Overlay mode: the shell sits on top of the media surface with a dark gradient and auto-hides. When false, renders as an always-on toolbar.
- visiblebooleantrue
- Visibility flag driven by the parent's autohide logic.
- playbackRatesReadonlyArray<number>[0.5, 0.75, 1, 1.25, 1.5, 2]
- Available playback rates exposed via the config menu.
- allowRemotePlaybackbooleanfalse
- Enables the cast / AirPlay button (Remote Playback API).
- downloadablebooleanfalse
- Adds a "Download" row to the config menu.
- downloadUrlstring | nullnull
- URL surfaced to the consumer when "Download" is clicked.
- downloadFilenamestring
- Suggested filename written to the <a download="…"> attribute.
- qualityOptionsReadonlyArray<TQualityOption>[]
- Quality variants list. When ≥ 2 entries, a "Quality" drill-down appears in the config menu.
- currentQualitystring | nullnull
- Currently-active quality identifier.
- showPreviousbooleanfalse
- Show the "previous" transport button.
- showNextbooleanfalse
- Show the "next" transport button.
- showLoopbooleanfalse
- Show the tri-state loop button (none → all → one → none).
- showShufflebooleanfalse
- Show the shuffle toggle button.
- Current loop mode (v-model:loopMode). Cycles none → all → one → none on click.
- shufflebooleanfalse
- Current shuffle state (v-model:shuffle). Toggled on click.
API
Slots
Content slots exposed by this component.
- #header
- Block rendered above the scrubber row. OrigamAudio injects cover + metadata here.
- #waveform
- Replaces the default OrigamMediaScrubber scrubber row. Receives state + methods to route seeks.
- #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 rendered on the left side of the toolbar, after the time display.
- #extraControlsRight
- Additional buttons on the right side of the toolbar, before the config menu. OrigamVideo injects captions / PiP / fullscreen here.
- #configExtra
- Extra rows in the config menu (audio output device, subtitle track selector…).
API
Emits
Events emitted by this component.
- @quality-changestring
- Fired when the user picks a quality option from the config menu. Parent owns the <source> swap.
- @downloadvoid
- Fired when the user clicks the Download button in the config menu.
- @previousvoid
- Fired when the previous transport button is clicked. Parent decides skip-back vs playlist jump.
- @nextvoid
- Fired when the next transport button is clicked. Parent owns the playlist action.
- @update:loopModeTAudioLoopMode
- Two-way binding for the loop mode. Emitted when the user cycles the loop button.
- @update:shuffleboolean
- Two-way binding for shuffle state. Emitted on shuffle toggle click.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- Color of the filled progress track and thumb.
- Border-radius of the track and progress bar (pill shape by default).
- Color of the volume level bar inside the tooltip.
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
Keyboard interactions
| Key | Action |
|---|---|
| Space / K | Toggle play / pause. |
| ArrowLeft / J | Seek backward (scrubber step or 5 s). |
| ArrowRight / L | Seek forward (scrubber step or 5 s). |
| ArrowUp / ArrowDown | Adjust volume (vertical scrubber when focused). |
| M | Toggle mute. |
Notes
- OrigamMediaScrubber sets role="slider", aria-valuemin, aria-valuemax, aria-valuenow and aria-valuetext on the track element. Keyboard users can seek using ArrowLeft/ArrowRight.
- OrigamMediaVolumeControl mute button receives an aria-label from the muteLabel / unmuteLabel props. These must be translated strings passed by the parent.
- Scrubber transitions and controller fade-in are suppressed under prefers-reduced-motion: reduce.
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.
- color{color.action.primary.bg}
- Fill color of the scrubber progress bar and thumb.
- dimension{radius.full}
- Border-radius of the track, progress and thumb (pill by default).
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.
MediaController usage
MediaScrubber standalone
Ecosystem
Family
Components from the same folder that share conventions and often compose together.