audio

The audio element embeds sound content with native playback controls and variants for different layout contexts.

Description

The <audio> element embeds audio content with native browser playback controls. Vanilla Breeze styles audio players to be block-level and full-width by default, with variants for compact and minimal layouts.

Like video, audio supports multiple <source> elements for format fallbacks and <track> elements for synchronized text content.

When to Use

  • Podcasts - Episode players with playback controls
  • Music players - Song or album playback
  • Sound effects - UI feedback or game audio
  • Voice recordings - Interviews, voicemail, audio messages
  • Audiobooks - Narrated content

When to Use Video Instead

  • Audio content with accompanying visuals
  • Content where a static image adds context (use video with poster)
  • Streaming services that provide video embeds

Variants

Default

Full-width audio player with native controls.

<audio controls> <source src="podcast.mp3" type="audio/mpeg" /> <source src="podcast.ogg" type="audio/ogg" /> Your browser does not support the audio element. </audio>

.compact

Reduced max-width for inline usage or sidebars.

<audio class="compact" controls>...</audio>

.minimal

Reduced height for tight layouts.

<audio class="minimal" controls>...</audio>

Compact + Minimal

Combine variants for the most compact player.

Audio Attributes

Attribute Description
controls Show native playback controls (required for user interaction)
autoplay Start playing automatically (discouraged - poor UX)
muted Start with audio muted
loop Restart audio when it ends
preload none, metadata, or auto

Preload Options

<!-- Don't preload - best for long content or many players --> <audio controls preload="none">...</audio> <!-- Preload metadata only - duration, dimensions --> <audio controls preload="metadata">...</audio> <!-- Preload entire file - small files, likely to play --> <audio controls preload="auto">...</audio>

Audio Formats

Provide multiple sources for maximum browser compatibility.

Format MIME Type Support
MP3 audio/mpeg Universal - best for compatibility
AAC audio/aac Good quality, wide support
Ogg Vorbis audio/ogg Open format, Firefox/Chrome
Opus audio/opus Best quality/size ratio, modern browsers
WAV audio/wav Uncompressed, large files
FLAC audio/flac Lossless, growing support
<audio controls> <!-- Best quality, modern browsers --> <source src="audio.opus" type="audio/opus" /> <!-- Good quality, open format --> <source src="audio.ogg" type="audio/ogg" /> <!-- Universal fallback --> <source src="audio.mp3" type="audio/mpeg" /> <p>Your browser doesn't support audio. <a href="audio.mp3">Download</a></p> </audio>

Live Examples

Podcast Player

Episode 42: Web Audio Fundamentals Duration: 45:32 | Published: January 8, 2026

Inline Audio

Listen to the pronunciation:

Audio in Figure

Interview with Jane Doe - Recorded December 2025

Fallback Content

Provide fallback for browsers that don't support audio.

<audio controls> <source src="podcast.mp3" type="audio/mpeg" /> <p> Your browser doesn't support HTML audio. <a href="podcast.mp3">Download the episode</a> (45 MB). </p> </audio>

Accessibility

Transcripts

Provide text transcripts for audio content so deaf users and those who can't play audio can access the information.

<figure> <audio controls> <source src="interview.mp3" type="audio/mpeg" /> </audio> <figcaption> Interview with Dr. Smith about climate change. <a href="transcript.html">Read the transcript</a> </figcaption> </figure>

Synchronized Text

Use <track> for synchronized captions (though browser support varies for audio).

<audio controls> <source src="podcast.mp3" type="audio/mpeg" /> <track kind="captions" src="captions.vtt" srclang="en" label="English" /> </audio>

Best Practices

  • Always provide a text transcript for important audio
  • Never autoplay audio - it's disruptive and inaccessible
  • Ensure controls are visible and keyboard accessible
  • Provide context about what the audio contains
  • Include duration information when available

Related Elements

  • <video> - Video content with similar API
  • <source> - Define multiple audio sources for format fallback
  • <track> - Synchronized text tracks (captions, descriptions)
  • <figure> - Wrap audio with caption information

CSS Reference

Styles defined in /src/native-elements/video/styles.css

Selector Properties
audio display: block; inline-size: 100%; max-inline-size: 100%;
audio.minimal block-size: 2.5rem;
audio.compact max-inline-size: 300px;