Audio Player

avonni-audio-player

An audio player that lets users play, pause and control playback of an audio file, with the option to show or hide the native playback controls.

Overview

Audio Player is a Lightning Web Component that plays an audio file with built-in playback controls, volume, speed, and looping.

Use it in your own Lightning Web Components to embed voice notes, recordings, or audio attachments. You control the source, autoplay, looping, playback speed, and volume through the component's attributes.

Use Cases

• Voice notes: Play back recorded notes attached to a record.
• Call recordings: Embed customer call audio in a service console.
• Training clips: Surface short audio lessons or instructions.
• Content document playback: Stream an audio file stored in Salesforce by ID.
• Background audio: Loop ambient or notification sounds in custom UI.

---

Use Case Examples

Example 1: Embedded voice note

Scenario: Play a voice note attached to a record using its public URL.

<!-- voiceNote.html -->
<template>
    <avonni-audio-player source="/sfc/audio/note.mp3" volume="90"></avonni-audio-player>
</template>

Result: A standard audio player with controls, ready to play the note at 90% volume.

Example 2: Looping clip with duration tracking

Scenario: Loop a clip and capture its duration when it loads.

<!-- loopingClip.html -->
<template>
    <avonni-audio-player
        source={source}
        playback-rate={playbackRate}
        volume={volume}
        loop
        ondurationchange={handleDurationChange}
    ></avonni-audio-player>
</template>

// loopingClip.js
import { LightningElement } from 'lwc';

export default class LoopingClip extends LightningElement {
    source = '/sfc/audio/ambient.mp3';
    playbackRate = 1;
    volume = 70;

    handleDurationChange(event) {
        const seconds = event.detail.value; // audio length in seconds
    }
}

Result: A looping audio player; when the clip loads, durationchange fires with the length in seconds.

---

Specifications

Attributes

Name	Description	Type	Default	Required
autoplay	If present, the audio will automatically start to play when it loads.	Boolean	false
hide-controls	If present, the audio controls are hidden.	Boolean	false
loop	If present, the audio being played loops again and again.	Boolean	false
playback-rate	Speed at which the audio is played. It has to be a number between 0.1 and 16.	Number	1
source	Source of the audio. It can be a URL or a Content Document ID.	String	—	Yes
volume	Volume of the audio. It has to be a number between 0 and 100.	Number	100

Methods

Name	Description	Argument Name	Argument Type	Argument Description
focus	Set the focus on the audio player.
getCurrentTime	Get the current current playback time of the audio player.

Custom Events

blur

The event fired when the focus is removed from the audio player.

The blur event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

durationchange

The event fired when the duration of the audio changes.

The durationchange event returns the following parameters.

Parameter	Type	Description
value	number	Duration of the audio in seconds.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

focus

The event fired when the focus is set on the audio player.

The focus event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

blur

The event fired when the focus is removed from the audio player.

The blur event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

durationchange

The event fired when the duration of the audio changes.

The durationchange event returns the following parameters.

Parameter	Type	Description
value	number	Duration of the audio in seconds.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

focus

The event fired when the focus is set on the audio player.

The focus event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

Key Considerations

• Source format: source accepts a URL or a Content Document ID—make sure the file is reachable by the running user.
• Autoplay caveats: Browsers often block autoplay with sound; pair autoplay with muted or low volume where supported.
• Playback rate bounds: Values outside 0.1–16 are invalid; stay within range.
• Volume bounds: volume is a 0–100 scale, not 0–1.
• Best Practice: Always provide a valid source. Avoid autoplay with audible volume unless the user expects it, and keep playback-rate near 1 for natural speech.

---

Troubleshooting Common Issues

• No audio plays: Verify source points to a reachable URL or valid Content Document ID and that the format is supported by the browser.
• Autoplay doesn't start: The browser may block autoplay with sound; lower the volume or require a user gesture.
• Controls missing: Confirm hide-controls is not set if you expect the playback UI.
• If issues persist: Contact our support team at [email protected] for assistance.