Audio

Media
stable

Full-featured audio player with waveform visualisation, playlist management, transport controls and a scoped-slot API.

Aperçu

Rendu de l’aperçu en cours…

expanded

Rendu de l’aperçu en cours…

compact

Rendu de l’aperçu en cours…

primary

Structure

Anatomie

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

Anatomy of OrigamAudioSchematic of the Audio component with 6 numbered internal parts. cover title / artist / album metadata waveform scrubber OrigamMediaController (transport) playlist list (optional) 1 2 3 4 5
Anatomy of <origam-audio> — 5 internal parts. The hidden <audio> element (⓪) drives state; the visual shell is a flex column: cover ①, metadata header ②, waveform ③, transport controller ④, optional playlist ⑤.
1.origam-audio__cover
Album cover image rendered as
. 96 px in expanded, 48 px in compact.
2.origam-audio__header
Metadata strip: title, artist and album. Hidden when all three are absent.
3.origam-audio__waveform
Waveform visualiser — decoded peaks painted via SVG bars. Visible only when waveform prop is truthy.
4.origam-audio__controller
shell housing the transport row (play/pause, scrubber, volume, playback-rate menu).
5.origam-audio__playlist
Ordered list of tracks shown below the transport when playlist prop is set.

API

Props

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

variant
'expanded'
Visual layout: "expanded" shows a 96 px cover + waveform + full transport; "compact" shows a 48 px cover + inline metadata + transport only.
coverPosition
'left'
Side where the album cover is painted. The controller column sits on the opposite side.
src
requis
string | IAudioSource | Array<IAudioSource>
Audio source URL, a single {src,type} descriptor, or an array for codec fallback. When playlist is set, src is ignored.
tracks
Array<IVideoTrack>
[]
Optional captions/chapters tracks. Reuses the video track shape (kind/src/srclang/label/default).
title
string
Track title displayed in the metadata strip.
artist
string
Artist / author name shown below the title.
album
string
Album name displayed below the artist.
cover
string | ISrcObject
Cover image URL shown alongside the metadata. Accepts ISrcObject for srcset / lazy-src support.
waveform
boolean | 'auto'
false
Render a waveform above the controls. "auto" activates only when OfflineAudioContext is available.
waveformColor
string
'currentColor'
Stroke color for the played portion of the waveform bars.
autoplay
boolean
false
Start playback as soon as loadedmetadata fires. Suppressed under prefers-reduced-motion.
muted
boolean
false
Start the player muted.
loop
boolean
false
Deprecated. Use loopMode instead. Maps to loopMode="one" at runtime.
loopMode
'none'
Tri-state loop strategy: "none" stops after last track, "all" wraps playlist, "one" loops current track.
shuffle
boolean
false
Shuffle playlist order using Fisher-Yates. Has no effect without a playlist.
playlist
Array<IAudioTrack>
Optional list of tracks. When set, prev/next navigate the list instead of skipping 10 s.
currentTrackIndex
number
0
Active track index in playlist. Supports v-model:currentTrackIndex.
preload
'none' | 'metadata' | 'auto'
'metadata'
Buffering hint: "metadata" loads duration only; "none" defers; "auto" lets the browser pre-buffer.
crossorigin
string
Mirrors the native crossorigin attribute. Required for WebAudio access to CORS-served media.
controls
'custom'
"custom" paints OrigamMediaController; "native" exposes the browser built-in controls attribute.
playbackRates
ReadonlyArray<number>
[0.5, 0.75, 1, 1.25, 1.5, 2]
Available playback rates exposed in the config menu.
playbackRate
number
1
Initial playback rate. Exposed via update:playbackRate.
allowRemotePlayback
boolean
false
Show cast/AirPlay button (Remote Playback API). Renders only when a cast-capable device is detected.
downloadable
boolean
false
Adds a Download row in the cog menu letting the listener save the current audio file.
downloadFilename
string
Override the downloaded file name. Defaults to the trailing segment of the source URL.
id
string
class
string | Array<string> | object
style
string | Array<string> | object | StyleValue
tag
string
Border-radius token or boolean.
roundedTopRight
boolean | number | string
roundedTopLeft
boolean | number | string
roundedBottomLeft
boolean | number | string
roundedBottomRight
boolean | number | string
roundedStartStart
boolean | number | string
roundedStartEnd
boolean | number | string
roundedEndStart
boolean | number | string
roundedEndEnd
boolean | number | string
border
boolean | number | string | TDirectionBoth | Array<TDirectionBoth>
false
Applies a border to the player container.
borderTop
boolean | number | string
borderLeft
boolean | number | string
borderBottom
boolean | number | string
borderRight
boolean | number | string
borderBlock
boolean | number | string
borderInline
boolean | number | string
borderInlineStart
boolean | number | string
borderInlineEnd
boolean | number | string
borderBlockStart
boolean | number | string
borderBlockEnd
boolean | number | string
borderColor
string
borderStyle
string
borderTopColor
TColor
borderRightColor
TColor
borderBottomColor
TColor
borderLeftColor
TColor
borderInlineStartColor
TColor
borderInlineEndColor
TColor
borderBlockStartColor
TColor
borderBlockEndColor
TColor
height
number | string
Player height override.
maxHeight
number | string
maxWidth
number | string
minHeight
number | string
minWidth
number | string
width
number | string
Player width override.
margin
boolean | number | string
marginTop
boolean | number | string
marginLeft
boolean | number | string
marginBottom
boolean | number | string
marginRight
boolean | number | string
marginBlock
boolean | number | string
marginInline
boolean | number | string
marginInlineStart
boolean | number | string
marginInlineEnd
boolean | number | string
marginBlockStart
boolean | number | string
marginBlockEnd
boolean | number | string
padding
boolean | number | string
paddingTop
boolean | number | string
paddingLeft
boolean | number | string
paddingBottom
boolean | number | string
paddingRight
boolean | number | string
paddingBlock
boolean | number | string
paddingInline
boolean | number | string
paddingInlineStart
boolean | number | string
paddingInlineEnd
boolean | number | string
paddingBlockStart
boolean | number | string
paddingBlockEnd
boolean | number | string
elevation
TElevation
Box-shadow elevation token.
position
TPosition
top
number | string
bottom
number | string
left
number | string
right
number | string
color
Intent or custom color applied to the player surface.
bgColor
Background color override.
fontSize
TFontSize
fontWeight
TFontWeight
lineHeight
TLineHeight

API

Slots

Emplacements de contenu exposés par ce composant.

#header
Override the entire cover + metadata + header strip.
#metadata
Override the title/artist/cover metadata block.
#cover
Override the cover image or placeholder.
#title
Override the title rendering.
#waveform
Override the waveform canvas. Receives peaks array + playhead context for custom rendering.
#controls
Override the entire transport controls replacing OrigamMediaController.
#playlist
#loading
Overlay rendered while media is loading.
#error
Overlay rendered when an error occurred.

API

Emits

Événements émis par ce composant.

@play
void
Fired when playback starts.
@pause
void
Fired when playback is paused.
@ended
void
Fired when playback ends. Auto-advances to next track when playlist is active.
@timeupdate
Event
Fired periodically as the playhead advances.
@volumechange
Event
Fired when volume or muted state changes.
@loadedmetadata
Event
Fired when duration and basic metadata are available.
@error
Event | MediaError | Error
Fired when the audio element encounters an error.
@update:playbackRate
number
Two-way binding for the playback rate.
@download
string
Fired when the listener clicks Download. Payload is the file URL.
@waveform
Array<number>
Fired on waveform recomputation. Payload is downsampled peaks (0..1 amplitudes).
@previous
void
Fired when the user clicks the previous-track button.
@next
void
Fired when the user clicks the next-track button.
@update:currentTrackIndex
number
Two-way binding for the active playlist index.
@update:loopMode
TAudioLoopMode
Two-way binding for the loop mode.
@update:shuffle
boolean
Two-way binding for the shuffle flag.
@track-change
IAudioTrack, number
Fires whenever the active track changes. Payload: new track descriptor + index.

API

Membres exposés

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

Ref<HTMLAudioElement | null>
Reference to the underlying <audio> element.
IMediaPlayerState
Reactive playback state object: playing, paused, currentTime, duration, buffered, volume, muted, playbackRate, loading, error.
IMediaPlayerMethods
Imperative player methods: play(), pause(), seek(t), setVolume(v), setMuted(b), setPlaybackRate(r).

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.

Player surface background.
Default foreground color (text and icons).
Accent color driving scrubbers, play-button surface and active-loop pill.
Player container border color.
Player container border-radius.
Gap between header, waveform and controller sections.
Padding of the player container.
Cover image size in expanded variant. 48 px in compact.
Played waveform bar color.

Inclusion

Accessibilité

Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.

Rôles ARIA

article
application

Interactions clavier

Interactions clavier
ToucheAction
SpacePlay / Pause toggle via the transport button.
Arrow Left / RightSeek backward / forward on the scrubber slider.
Arrow Up / DownIncrease / decrease volume on the volume slider.
TabNavigate between transport controls.

Notes

  • Autoplay is suppressed when prefers-reduced-motion: reduce is set.
  • The waveform scrubber has aria-label="Seek" pointing to the useLocale translation.
  • When controls="native", the browser's native audio controls are used, which include keyboard support by default.

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__surface---raised)
Player background.
color
var(--origam-color__action--primary---bg)
Accent color for scrubbers and the play button.
dimension
96px
Cover size in expanded variant.
dimension
48px
Play button size.
dimension
48px
Waveform visualiser height.
dimension
var(--origam-radius---lg)
Player container border-radius.

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 player

vue

Playlist with loop

vue

Compact dock variant

vue