> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: AudioPlayer Component

## Article: AudioPlayer Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/media/audio-player-component.md

## Article Content:

# AudioPlayer

_Components/Media_

Interactive docs page: <https://wix-pages.com/design-system-documentation/#/component/audioplayer>

## Overview

```jsx
<AudioPlayer src="AudioTrack1.mp3" />;
```

Audio player lets users play an uploaded audio file.

### Do

- Use it to play audio files, such as songs or voice messages.

### Don't

- Don't use it to compose a video player. Use wix.github.io/playable/ instead.

### Feature examples

#### Source

Pass a link to the audio file source with `src` prop. Component detects your file `format` from the extension.

In situations where extraction does not work, specify a file format with `format` prop.

```jsx
<AudioPlayer src="AudioTrack1.mp3" />;
```

#### Preload

Specify what to download when component is rendered with a `preload` prop. It supports 3 values:

- `auto` downloads the full file.
- `metadata` downloads the file's metadata only. The full file will be downloaded when play is clicked.
- `none` is used when nothing should be preloaded. The file and its data will be downloaded when the user clicks play.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <AudioPlayer preload="auto" src="AudioTrack2.mp3" />
  <AudioPlayer preload="metadata" src="AudioTrack2.mp3" />
  <AudioPlayer preload="none" src="AudioTrack2.mp3" />
</StorybookComponents.Stack>;
```

#### Autoplay

Use `autoplay` prop to start playback automatically when audio is loaded.

```jsx
() => {
  const [src, setSrc] = React.useState(null);
  return (
    <StorybookComponents.Stack>
      <StorybookComponents.Stack flexDirection="row">
        <Button onClick={() => setSrc('AudioTrack1.mp3')}>Play Audio</Button>
        <Button skin="inverted" onClick={() => setSrc(null)}>
          Stop Audio
        </Button>
      </StorybookComponents.Stack>
      {src && <AudioPlayer autoplay src={src} />}
    </StorybookComponents.Stack>
  );
};
```

### Common use case examples

#### Form

Let users listen to audio files.

```jsx
<Card>
  <Card.Header title="Track info" />
  <Card.Divider />
  <Card.Content>
    <Layout>
      <Cell span={4}>
        <FormField label="Cover image">
          <ImageViewer
            addImageInfo="Add track cover. Recommended size 3000x3000px."
            height="214px"
            tooltipProps={{
              textAlign: 'center',
            }}
          />
        </FormField>
      </Cell>
      <Cell span={8}>
        <Box gap="24px" direction="vertical">
          <FormField
            label="Track file"
            suffix={
              <TextButton prefixIcon={<Icons.Refresh />}>
                Change File
              </TextButton>
            }
          >
            <AudioPlayer src="AudioTrack1.mp3" />
          </FormField>
          <FormField label="Track name">
            <Input placeholder="e.g., Audio 1" />
          </FormField>
          <FormField label="Genre (pick up to 3)">
            <MultiSelect
              options={[
                { id: '1', value: 'Alternative' },
                { id: '2', value: 'Blues' },
                { id: '3', value: 'R&B/Soul' },
                { id: '4', value: 'Classical' },
                { id: '5', value: 'Country' },
                { id: '6', value: 'Dance' },
                { id: '7', value: 'Electronic' },
                { id: '8', value: 'Hip Hop' },
                { id: '9', value: 'Jazz' },
              ]}
              placeholder="Start typing to search the list"
            />
          </FormField>
        </Box>
      </Cell>
    </Layout>
  </Card.Content>
</Card>;
```

#### Inbox

Use audio player to display received voice messages in the inbox. Provide an option to download a message by displaying the icon button inline to the player.

```jsx
<Card>
  <Box verticalAlign="middle" align="space-between" padding="SP2 SP3">
    <Box gap="SP2" verticalAlign="middle">
      <Avatar name="Sam Lee" size="size30" />
      <Text>Sam Lee</Text>
    </Box>
    <Box gap="SP2">
      <IconButton skin="inverted">
        <Icons.More />
      </IconButton>
      <Button skin="inverted">Archive</Button>
    </Box>
  </Box>
  <Divider />
  <Card.Content>
    <Box
      border="1px solid"
      borderColor="D60"
      borderRadius={12}
      verticalAlign="middle"
      padding="3px SP2 3px SP1"
      width="fit-content"
      gap="6px"
      marginBottom="SP2"
    >
      <Icons.Phone />
      <Heading size="extraTiny">Missed call</Heading>
    </Box>
    <Box
      backgroundColor="D70"
      padding="SP3"
      borderRadius={12}
      width="45%"
      direction="vertical"
      gap="6px"
    >
      <Box marginBottom="SP2" direction="horizontal" verticalAlign="middle">
        <AudioPlayer src="AudioTrack1.mp3" />
        <Box marginLeft="18px">
          <IconButton size="medium" skin="inverted">
            <Icons.Download />
          </IconButton>
        </Box>
      </Box>
      <Text size="small">Message Transcript:</Text>
      <Text size="small">
        “Hey i know you are busy right now could you give me a call back whan
        you have a chance”
      </Text>
      <Box verticalAlign="middle" gap="6px" marginTop="SP1">
        <Icons.PhoneFilledSmall />
        <Text size="tiny">Voicemail</Text>
      </Box>
    </Box>
  </Card.Content>
</Card>;
```

## Code

```jsx
import { AudioPlayer } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `autoplay` | `boolean` | — | Start playback automatically when audio is loaded. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `format` | `string` | — | Specifies a file format in situations where extraction doesn't work (such as a SoundCloud stream).<br/> By default, AudioPlayer detects your file format from the extension. |
| `onEnd` | `() => void` | — | Will be called when audio is ended. |
| `onLoad` | `() => void` | — | Defines a callback function which is called when audio is loaded. |
| `onLoadError` | `(errorMsg: string) => void` | — | Defines a callback function which is called every time audio fails to load. |
| `onPause` | `() => void` | — | Defines a callback function which is called when audio is paused. |
| `onPlay` | `() => void` | — | Defines a callback function which is called when audio is played. |
| `onSeek` | `() => void` | — | Defines a callback function which is called when audio is sought explicitly (i.e. when user drags the slider). |
| `preload` | `"metadata" \| "none" \| "auto"` | — | Determines what to download when the component is rendered: full file, its metadata or nothing at all. When webAudioAPI = true you can only set it to either 'auto' or 'none'. When webAudioAPI = false you can set it to 'auto', 'metadata' or 'none'. |
| `ref` | `null \| string \| (instance: AudioPlayerImperativeActions \| null) => void \| RefObject<AudioPlayerImperativeActions>` | — | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
| `src` *(required)* | `string` | — | Specifies a link to the source of the track to be loaded for the sound (URL or base64 data URI). If a file has no extension, you need to specify the extension using the format property. |
| `volume` | `number` | — | Volume level from 0 (muted) to 1 (full volume). When not provided, defaults to Howler's default (1). |
| `webAudioAPI` | `boolean` | — | Specifies whether to force the browser's Web Audio API, which allows advanced audio processing. Use it only for relatively small audio files, because the full file has to download and decode before playback starts. |

## Testkit

No testkit for this component — it doesn't expose a unidriver testkit.

## Changelog

- **1.339.0** (2026-10-19) — maintenance release, no component-specific changes
- **1.338.0** (2026-10-15) — maintenance release, no component-specific changes
- **1.336.0** (2026-10-13) — maintenance release, no component-specific changes
- **1.330.3** (2026-09-29) — maintenance release, no component-specific changes
- **1.329.0** (2026-09-24) — maintenance release, no component-specific changes
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.310.0** (2026-08-10) — maintenance release, no component-specific changes
- **1.295.0** (2026-07-03) — maintenance release, no component-specific changes
- **1.292.0** (2026-06-22) — maintenance release, no component-specific changes
- **1.291.0** (2026-06-19) — maintenance release, no component-specific changes
- **1.273.0** (2026-04-30) — feat: add volume prop ECL-17203 ([#16214](invalid-url))
- **1.266.0** (2026-04-07) — maintenance release, no component-specific changes
- **1.260.0** (2026-03-17) — maintenance release, no component-specific changes
- **1.250.0** (2026-01-27) — maintenance release, no component-specific changes
- **1.242.0** (2025-12-19) — maintenance release, no component-specific changes
- **1.212.0** (2025-08-11) — maintenance release, no component-specific changes
- **1.165.0** (2025-02-27) — maintenance release, no component-specific changes
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.115.0** (2024-07-17) — maintenance release, no component-specific changes
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes