Skip to content

Audio Widget

The audio widget plays a sound file from a URL. It can autoplay a sound without a play button UI or it can display a play/pause button to control the audio playback.

Audio Widget

The audio URL can take one of three formats:

  • A string URL
  • Map of URL candidates
  • List of URL candidates

String URL

If it is a simple URL string, that audio file will be played. Any ${var} references will be expanded at run-time.

js
url: 'https://example.com/audio/hot-${temp}.mp3',

Map of URLs

If it is a map, the widget value is used as a key to the map to select a corresponding URL. A key of * will be used if there is no better match.

js
url: {
    sunny: 'https://example.com/audio/sunny.mp3',
    cloudy: 'https://example.com/audio/cloudy.mp3',
    '*': 'https://example.com/audio/rainy.mp3',
}

List of URLs

If the URL value is a list, the list contains candidate URLs with expressions that are evaluated at run-time to select the best match. For example:

js
[
    { 
        expression: 'temp > 40', 
        value: 'https://example.com/audio/hot.mp3',
    },
    {
        expression: true,
        value: 'https://example.com/audio/temperate.mp3'
    }
]

Auto Play

Autoplay of audio is typically prevented by the browser. To enable, you may need to invoke your browser with a specific flag. For example:

bash
chrome.exe --autoplay-policy=no-user-gesture-required

Configurable components

Class NameDescription
cardAudio widget card component
primaryPrimary audio player component

Widget Properties

NameDescription
prefixOptional prefix icon (defaults to "$play" and "$pause")
textPlay button text (defaults to "Play")
urlURL string, map or list of URLs
valueWidget data value used to select the audio from the URL map or list

Common CSS Properties

CategoryCSS Property / TechniquePurposeExample

Custom CSS Properties

NameDescription
--w-autoplaySet to true to autoplay the audio file. Defaults to false.
--w-durationDuration to play the audio file. Set to a number of seconds or repeat to loop the audio file. Defaults to no limit
--w-loopSet to true to loop the audio file. Defaults to false.