> 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 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:** Supported audio formats may vary, but standard formats like <mark style="color:red;">MP3, WAV, and OGG</mark> are usually well-supported.

**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. The sections below mirror the Properties tab.

### 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 upload an audio file directly from your computer. You can also reference a Content Document ID.
* The **`source`** property accepts the URL or Content Document ID of the audio to play.

#### 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 the **`autoplay`** property is present, the audio will automatically start to play when it loads.

#### Volume

Set the starting volume level for the audio. The **`volume`** property accepts a number between 0 and 100.

* **How to Adjust:** Use the volume slider or input field in the component's properties to choose an appropriate initial volume level.
* **Consider User Experience:** Avoid setting the initial volume too high, as it might startle users.

#### Hide Controls

If you want a cleaner, more minimalist look, you can hide the standard player controls (play/pause, volume, etc.). When the **`hideControls`** property is present, the audio controls are hidden.

If you choose this option, configure autoplay or provide another way for users to control the audio.

#### Loop

Enable the **`loop`** option to repeat the audio continuously after it finishes. When present, the audio being played loops again and again.

#### Playback Rate

Adjust the playback rate to make the audio play faster or slower than the normal speed. The **`playbackRate`** property is the playback speed multiplier — for example, 0.5 for slower, 1 (default) for normal, and 2 for faster.

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.
* **Placeholder Illustration:** The illustration shown when no media is loaded (default: **No Preview**).

### Set Component Visibility

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

## 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.