Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Frontend Modules

Wix Design System (WDS)

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

import { Property, PropertyList, ExpandableSection } from "@wix/docs-ui/content";

# Audio

An audio track from Wix Media, carried at runtime as an object with the URL to play along
with its metadata. Use it for a field that plays sound the Wix user picks from the Media
Manager, such as a background track or a podcast episode.

## Component

In your component code, import the `Audio` type from `@wix/editor-react-types`:

```ts
import type { Audio } from '@wix/editor-react-types';
```

An `Audio` object has the following properties:

<PropertyList bordered>
  <Property
    name="url"
    type="string"
    required
    description="The fully resolved audio URL. Play this."
  />
  <Property
    name="artist"
    type="string"
    description="The audio artist name."
  />
  <Property
    name="title"
    type="string"
    description="The audio track title."
  />
  <Property
    name="duration"
    type="number"
    description="The audio duration in seconds."
  />
  <Property
    name="name"
    type="string"
    description="The audio file name."
  />
  <Property
    name="audio"
    type="AudioSource[]"
    description="All available sources at different quality levels and formats. Each is one file at a specific quality and format."
  >
    <ExpandableSection name="AudioSource properties">
      <PropertyList>
        <Property name="url" type="string" required description="The fully resolved audio URL." />
        <Property name="format" type="string" required>
          The audio format, such as `'mp3'` or `'ogg'`.
        </Property>
        <Property name="quality" type="string" required description="The audio quality label." />
        <Property name="audioBitrate" type="number" required description="The audio bitrate in kbps." />
      </PropertyList>
    </ExpandableSection>
  </Property>
</PropertyList>

### Usage

Your code either consumes a value of type `Audio` or produces one:

::::tabs
:::Consumers
In a component that receives an `Audio`, show its `title` and play its URL in an audio
element:

```tsx
import type { Audio } from '@wix/editor-react-types';

function Player({ track }: { track?: Audio }) {
  return (
    <figure>
      <figcaption>{track?.title}</figcaption>
      <audio src={track?.url} controls />
    </figure>
  );
}
```
:::
:::Producers
When your code produces an `Audio`, for a context or a function return, set `url` for the
consumer to play, along with the metadata and any additional `audio` sources:

```ts
import type { Audio } from '@wix/editor-react-types';

const track: Audio = {
  url: 'https://static.wixstatic.com/mp3/audio123.mp3',
  artist: 'The Example Trio',
  title: 'Background Music',
  duration: 180,
  name: 'background-music.mp3',
  audio: [
    {
      url: 'https://static.wixstatic.com/mp3/audio123.mp3',
      format: 'mp3',
      quality: 'high',
      audioBitrate: 320,
    },
  ],
};
```
:::
::::

## Manifest

In your manifest, declare the field with the `audio` dataType:

```json
{ "dataType": "audio" }
```

### Declaration

Declare an `audio` field in one of these ways, depending on where the value comes from:

::::tabs
:::Data-property
Declare it as a data property when the Wix user should pick the `track` in a panel. It takes
`dataType`, `displayName`, and an optional `defaultValue`:

```json
{
  "track": {
    "dataType": "audio",
    "displayName": "Background Track",
    "defaultValue": {
      "uri": "wix:audio://v1/audio123.mp3",
      "artist": "The Example Trio",
      "title": "Background Music",
      "duration": 180,
      "name": "background-music.mp3"
    }
  }
}
```

> **Your `defaultValue` sets a media reference, not the full object.** It provides a `uri`
> that points to an item in Wix Media. Before your component runs, the editor resolves that
> `uri` into the complete `Audio` object it receives, including the `url` and audio sources.
> Do not set `url` in your manifest.
:::
:::Context-item
Declare it as a context item when your component supplies the track to descendant
components. It takes just `dataType` and `displayName`:

```json
{
  "track": {
    "dataType": "audio",
    "displayName": "Background Track"
  }
}
```
:::
:::Function-parameter-and-return
Declare it on a function when the function accepts or returns an audio track. It takes
`dataType` and an optional `displayName`, and a parameter may also set `optional`:

```json
{
  "parameters": [
    {
      "dataType": "audio",
      "displayName": "Background Track"
    }
  ],
  "returns": {
    "dataType": "audio"
  }
}
```
:::
::::