---
title: "Audio extension"
description: "Use the Audio extension in Tiptap to embed audio files in your documents. Learn more in our docs!"
canonical_url: "https://tiptap.dev/docs/editor/extensions/nodes/audio"
---

# Audio extension

Use the Audio extension in Tiptap to embed audio files in your documents. Learn more in our docs!

This extension adds support for native `<audio>` elements in the editor, allowing you to embed audio files directly into your documents.

> **Interactive demo:** [Audio](https://embed.tiptap.dev/preview/Nodes/Audio)

## Install

```bash
npm install @tiptap/extension-audio
```

## Settings

### addPasteHandler

Controls if the paste handler for audio sources should be added.

Default: `true`

```js
Audio.configure({
  addPasteHandler: false,
})
```

### autoplay

Controls if the audio should autoplay.

Default: `false`

```js
Audio.configure({
  autoplay: true,
})
```

### controls

Controls if the audio element should render the native controls.

Default: `true`

```js
Audio.configure({
  controls: false,
})
```

### loop

Controls if the audio should loop.

Default: `false`

```js
Audio.configure({
  loop: true,
})
```

### muted

Controls if the audio should be muted.

Default: `false`

```js
Audio.configure({
  muted: true,
})
```

### preload

The preload behavior for the audio element.

Default: `'metadata'`

```js
Audio.configure({
  preload: 'none',
})
```

### controlslist

Provides the controlslist attribute for the audio element.

Default: `undefined`

```js
Audio.configure({
  controlslist: 'nodownload',
})
```

### crossorigin

Sets the crossorigin attribute for the audio element.

Default: `undefined`

```js
Audio.configure({
  crossorigin: 'anonymous',
})
```

### disableRemotePlayback

Controls if remote playback should be disabled on the audio element.

Default: `false`

```js
Audio.configure({
  disableRemotePlayback: true,
})
```

### allowBase64

Allows data: URLs for audio sources.

Default: `false`

```js
Audio.configure({
  allowBase64: true,
})
```

### HTMLAttributes

Custom HTML attributes that should be added to the rendered HTML tag.

```js
Audio.configure({
  HTMLAttributes: {
    class: 'my-custom-class',
  },
})
```

### inline

Controls if the audio node should be inline or not.

Default: `false`

```js
Audio.configure({
  inline: true,
})
```

## Commands

### setAudio(options)

Inserts an audio element at the current position with the specified options. The audio element will be embedded as a block-level node by default, but can be configured to be inline.

```js
editor.commands.setAudio({
  src: 'https://example.com/audio.mp3',
  controls: true,
  autoplay: false,
})
```

#### Options

| Option                | Description                                                                | Optional | Default    |
| --------------------- | -------------------------------------------------------------------------- | -------- | ---------- |
| src                   | The URL of the audio file to embed                                         | ❌        | -          |
| controls              | Show native audio controls (play, pause, volume, etc.)                     | ✅        | true       |
| autoplay              | Automatically start playing the audio when the page loads                  | ✅        | false      |
| loop                  | Loop the audio playback continuously                                       | ✅        | false      |
| muted                 | Start the audio in a muted state                                           | ✅        | false      |
| preload               | How the audio should be loaded ('auto', 'metadata', 'none', or null)       | ✅        | 'metadata' |
| controlslist          | Comma-separated list of controls to hide (e.g., 'nodownload')              | ✅        | undefined  |
| crossorigin           | CORS setting for the audio element ('anonymous', 'use-credentials', or '') | ✅        | undefined  |
| disableRemotePlayback | Disable remote playback on supported devices                               | ✅        | false      |
| HTMLAttributes        | Additional HTML attributes to apply to the audio element                   | ✅        |            |

## Source code

[packages/extension-audio/](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-audio/)