> 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/dynamic-components/components/audio-player.md).

# Audio Player

The Audio Player provides robust audio playback with extensive customization options for sources, playback controls, volume, and visual styling.

The Avonni Audio Player component plays a single audio source with configurable playback behavior such as autoplay, volume, looping, playback speed, and control visibility.

## Overview

To start with the Avonni Audio Player component, you'll first need to provide an audio source and configure how it plays back. The sections below follow the configuration panel from top to bottom, so you can read along as you build.

### Example Use Cases

* **Background Music:** Set the mood with ambient music.
* **Sound Effects:** Enhance interactions with sound effects.
* **Audio Instructions:** Provide clear audio guidance to users.
* **Accessibility:** Offer audio descriptions for users with visual impairments.

{% hint style="info" %}
**File Formats:** The **Select Audio** picker accepts `.mp3`, `.wav`, `.ogg`, `.opus`, `.m4a`, `.aac`, `.flac`, `.webm`, `.mp4`, `.m4v` and `.ogv`.

**User Experience:** Use audio thoughtfully. Too much or overly loud audio can be disruptive.
{% endhint %}

## Configuration

To configure the Audio Player, select it on the canvas. The **Edit Audio Player** panel opens on the right with two tabs: **Properties** and **Style**. The sections below mirror the Properties tab.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FN7bqlcEIYPUG2uvur7ER%2Faudio-player-builder-properties.png?alt=media" alt="The Properties tab of the Edit Audio Player panel" width="320"><figcaption><p>The whole Properties tab, in the order the sections below follow it.</p></figcaption></figure>

### Properties

#### Source

Provide the audio that your player will use. This is a required step — without an audio source, the player will not function.

* **How to Add:** Paste a URL to an audio file, or click **Select Audio** to upload one from your computer. You can also type the ID of a Content Document that is already in Salesforce.
* **Source** accepts the URL or Content Document ID of the audio to play.

Leaving **Source** empty does not leave the page blank. The component renders a built-in card reading "No audio source provided." where the player would be, and the **Placeholder** section below replaces that card with an illustration and a message of your choosing.

#### Autoplay

Decide whether the audio should start playing automatically when the page loads, or whether the user should click a play button.

* **Autoplay On:** The audio will begin playing once the page loads.
* **Autoplay Off:** The user must click the play button to start the audio.

When **Autoplay** is enabled, the audio automatically starts playing once it loads, and it starts **muted**. Browsers refuse to autoplay audio with sound, so the component mutes the player to let it start at all. The listener unmutes it from the controls, which is a reason to leave **Hide Controls** off whenever you rely on autoplay.

#### Volume

Set the starting volume level for the audio. **Volume** accepts a number between 1 and 100, and falls back to 100 when it is left empty.

* **How to Adjust:** Type the starting level in the **Volume** field.
* **Consider User Experience:** Avoid setting the initial volume too high, as it might startle users.
* **0 does not mute the player.** The component reads 0 as "no value set" and falls back to 100. To start quiet, use a low value such as 5. To start silent, enable **Autoplay**, which mutes the player.

#### Hide Controls

If you want a cleaner, more minimalist look, you can hide the standard player controls (play/pause, volume, etc.). When **Hide Controls** is enabled, the player renders nothing at all: without its controls the audio element has no height, so nothing marks its place on the page.

Choose this option only when the audio is meant to play on its own. Enable **Autoplay**, or give users another way to start and stop it.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FmSURFu0sZDCoQtQb8mPB%2Faudio-player-controls.png?alt=media" alt="The Audio Player with Hide Controls off and on"><figcaption><p>With <strong>Hide Controls</strong> off, the browser's own player. With it on, nothing renders.</p></figcaption></figure>

#### Loop

Enable **Loop** to repeat the audio continuously after it finishes.

#### Playback Rate

Adjust the playback rate to make the audio play faster or slower than the normal speed. **Playback Rate** is the playback speed multiplier: 0.5 for slower, 1 (the default) for normal, and 2 for faster.

Accepted values run from 0.1 to 16. Anything outside that range, or anything that is not a number, falls back to 1.

Use this sparingly, as it can affect the audio quality.

### Placeholder

The Placeholder section controls what the Audio Player displays when no audio source is loaded.

* **Show Placeholder:** Show a placeholder when the source is empty.
* **Placeholder Message:** The message to display when the source is empty. Requires **Show Placeholder** to be enabled.
* **Placeholder Illustration:** The illustration shown when no media is loaded (default: **No Preview**). Requires **Show Placeholder** to be enabled.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2F1Xx0uxNYxLoLaoU693dd%2Faudio-player-placeholder.png?alt=media" alt="The Audio Player with no source, with Show Placeholder off and on"><figcaption><p>With no source set: the built-in card above, and the configured placeholder below.</p></figcaption></figure>

### Set Component Visibility

All components support conditional visibility — see [Component Visibility](/dynamic-components/core-concepts/component-visibility.md).

## Styling

Configure the Audio Player's appearance from the **Style** tab of the Edit Audio Player panel.

{% tabs %}
{% tab title="Margin" %}
Controls the *outer* spacing around the player.

* **Top / Right / Bottom / Left:** Adjust the space on each side of the player.
  {% endtab %}

{% tab title="Padding" %}
Controls the *inner* spacing between the player's content and its border.

* **Top / Right / Bottom / Left:** Adjust the inner spacing on each side.
  {% endtab %}

{% tab title="Size" %}
Controls the player's dimensions.

* **Width / Height:** Set fixed dimensions for the player.
  {% endtab %}

{% tab title="Border" %}
Customizes the border surrounding the player.

* **Color:** Set the border color.
* **Size:** Set the border thickness.
* **Style:** Set the border style (solid, dashed, dotted, etc.).
* **Radius:** Round the corners of the border.
  {% endtab %}
  {% endtabs %}

## Output Variables

The Audio Player exposes these output variables you can reference elsewhere on the page after the user interacts with it.

### Playback State

These variables reflect the current state of the audio as it plays.

| Output variable        | Type   | What it returns                                                       |
| ---------------------- | ------ | --------------------------------------------------------------------- |
| **Current Time Stamp** | Number | The current playback position in seconds. Updates as the audio plays. |
| **Duration**           | Number | The total duration of the loaded audio file in seconds.               |

> **Example:** Use **Current Time Stamp** alongside **Duration** in a formula to display a progress percentage, or trigger a page action when the user reaches a specific point in the audio.


---

# 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/dynamic-components/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.