---
title: 'Music on hold'
summary: 'A music-on-hold file is what callers hear while they wait - in a queue, on a parked call, during a transfer. Upload audio tracks and reference them from queues, call flow steps, or the tenant-wide default.'
section: features
tags:
  - crud
  - telephony
  - audio
updated: '2026-06-17'
---

> A **music on hold** file is what callers hear while they wait - in a queue, on a parked call, during a transfer. Upload audio tracks and reference them from queues, call flow steps, or as the tenant-wide default.

## Overview

A music-on-hold record is a named audio file you can reference from three places, where more specific assignments override more general ones:

| Surface | What it controls |
|---|---|
| **PBX-wide default** | Played whenever no more-specific hold music is set. Configured on the [PBX settings](pbxes.md) page. |
| **Per queue** | Played to callers waiting in this specific queue. Set on the [Queue](queues.md) record's Music on hold field. |
| **Per call flow step** | Played during a specific routing step (Ring user, Dial group, Ring external number, Enter queue). |

## What it does

The file plays during every wait period: in a queue (on continuous loop between rings), during a transfer while the bridge is set up, and on a parked call until it is retrieved. Replacing the audio takes effect on the next call that uses it, with no preview or staging.

> [!WARNING]
> Hold music played in a commercial setting is generally a public performance under copyright law. Use royalty-free music or hold a performance license.

## See also

- [Queues](queues.md) - the most common consumer.
- [Announcements](announcements.md) - separate but related: spoken-word audio for IVRs and call flows.
- [Sound files](sound_files.md) - the dashboard that groups all three audio types.

```yaml fields
name:
  label: Name
  tab: General
  hint: 'Identifies the file in dropdowns wherever you assign hold music. Use descriptive names like "Lo-fi instrumental loop" or "Corporate ambient".'
comment:
  label: Comment
  tab: General
  hint: 'Optional note about this file for your own reference. Can record the music source, license, or expiry.'
audio_data:
  label: 'Sound file'
  tab: General
  hint: 'The audio file to upload. Accepted formats: MP3, WAV, FLAC, AAC. Maximum 20 MB. The system converts to telephony codecs automatically.'
current_audio:
  label: 'Current audio'
  tab: General
  hint: 'Plays back the currently uploaded audio file so you can preview it without downloading.'
```