> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/core-components/audio-player.md).

# Audio Player

`avonni-audio-player`

An audio player that lets users play, pause and control playback of an audio file, with optional custom 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.

```html
<!-- 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.

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

```js
// 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.                        |

## 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 <support@avonni.app> for assistance.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avonnicomponents.com/lwc-components/core-components/audio-player.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.