---
title: "Music on Hold Sources Module Documentation"
description: "Documentation for Music & Hold"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [Module Overview (Technical)](#1-module-overview-technical)
4. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
5. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
6. [User Roles & Key Capabilities](#-user-roles--key-capabilities)
7. [Configuration Sections](#4-configuration-sections)
8. [Settings Reference](#5-settings-reference)
9. [Model Context Protocol (MCP) AI Integration](#model-context-protocol-mcp-ai-integration)
10. [Common Scenarios & Examples](#6-common-scenarios--examples)
11. [Limitations & Important Notes](#7-limitations--important-notes)
12. [Troubleshooting Tips](#8-troubleshooting-tips)
13. [Glossary](#9-glossary)
---

## Navigation & Access

To access the Music & Hold configuration module:
1. Log in to the Ring2All Web Portal (`https://<domain-or-ip>/login`).
2. In the left navigation sidebar, expand **Settings**.
3. Under **Voice Prompts**, click **Music & Hold** (`/settings/voice-prompts/music-hold`).
4. To add a new music-on-hold class or streaming source, click **+ Add MOH Source** (`/settings/voice-prompts/music-hold/new`). To edit an existing audio stream or directory mapping, click on the row or the **Edit** action button.

---

## Screenshots & Visual Interface

### Music & Hold Sources Directory
Overview of tenant audio hold sources showing playlist name, audio class, source type (local file playlist vs Shoutcast/Icecast web stream), sound path, priority ranking, and default assignment.
![Music on Hold List](/screenshots/settings/voice/music-on-hold-list.png)

### Music & Hold Configuration Form
Form for creating and modifying MOH stream classes, configuring local storage directories, Icecast/Shoutcast stream URLs, periodic chime comfort intervals, audio sampling rates, and shuffle/random playback modes.
![Music on Hold Form](/screenshots/settings/voice/music-on-hold-form.png)

---

## 1. Module Overview (Technical)

### What Are Music on Hold Sources?

Music on Hold (MOH) Sources is a **hold music configuration module** that manages audio played when callers are placed on hold. It supports uploaded files, external streams, and chime intervals with configurable play modes.

### Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│              Music on Hold Sources Architecture                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Admin Panel                                                    │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        MOH Sources                                       │   │
│  │                                                          │   │
│  │  Source Types:                                           │   │
│  │  ├─ File: Upload audio files (.wav, .mp3, .ogg)         │   │
│  │  ├─ Music: Multiple files with play modes               │   │
│  │  ├─ Stream: External HTTP/Icecast/Shoutcast             │   │
│  │  └─ Chime: Jingle insertions at intervals               │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Stored per domain                                      │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Audio Storage                                     │   │
│  │                                                          │   │
│  │  /var/lib/freeswitch/storage/domains/{domain}/moh/      │   │
│  │  ├─ sales_jingle.wav                                    │   │
│  │  ├─ support_music.mp3                                   │   │
│  │  └─ corporate_stream                                    │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Accessed via local_stream                              │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Telephony Server mod_local_stream                       │   │
│  │                                                          │   │
│  │  local_stream://domains/${domain}/${class}              │   │
│  │                                                          │   │
│  │  Call on hold → Play MOH source                         │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 2. Module Overview (Commercial/Business)

### Business Value

MOH Sources provides **customized hold experience**:

| Without MOH Sources | With MOH Sources |
|---------------------|-----------------|
| Default silence | Custom music |
| No branding | Branded audio |
| Single track | Multiple playlists |
| No announcements | Chime intervals |

### Use Cases

1. **Branded Hold Music**
   - Upload company jingles
   - Professional image

2. **Multiple Playlists**
   - Different music per queue
   - Various customer segments

3. **Announcement Chimes**
   - Periodic messages
   - Wait time updates

4. **External Streams**
   - Internet radio
   - Live content

### Feature Highlights

| Feature | Benefit |
|---------|---------|
| **File Upload** | Custom audio files |
| **External Streams** | Live radio/podcast |
| **Chime Intervals** | Periodic announcements |
| **Play Modes** | Linear, shuffle, random |
| **Priority** | Source ordering |
| **Multi-format** | WAV, MP3, OGG |

---

## 3. Module Overview (End User/Administrator)

### What Can You Do?

- Upload audio files (WAV, MP3, OGG)
- Configure external stream URLs
- Set chime intervals for announcements
- Choose play modes (linear, shuffle, random)
- Set source priority
- Enable/disable sources
- Test streams in browser

### MOH Sources Interface

```
┌─────────────────────────────────────────────────────────────────┐
│              Music on Hold Sources                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Manage Music on Hold (MOH) sources for your domain. Upload    │
│  audio files, configure streams, or set up chime intervals.    │
│                                                                 │
│  [+ Create MOH Source]                                          │
│                                                                 │
│  [🔍 Search MOH sources...]                                     │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Name            │ Class     │ Type   │ Priority │ Status │  │
│  ├─────────────────┼───────────┼────────┼──────────┼────────┤  │
│  │ Sales Music     │ sales     │ Music  │ 1        │ ✓      │  │
│  │ Support Hold    │ support   │ File   │ 2        │ ✓      │  │
│  │ Radio Stream    │ radio     │ Stream │ 3        │ ✓      │  │
│  │ Position Chime  │ announce  │ Chime  │ 1        │ ✓      │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Create/Edit View

```
┌─────────────────────────────────────────────────────────────────┐
│              Create MOH Source                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ▼ Basic Information                                            │
│                                                                 │
│  Name: [Sales Music                   ]                        │
│  Class Name: [sales                    ]                       │
│    Used in local_stream://domains/${domain}/${class}            │
│                                                                 │
│  Description: [Hold music for sales queue]                     │
│  Priority: [1                  ]                               │
│  Enabled: ✓                                                     │
│                                                                 │
│  Source Type: [Music ▼]                                        │
│    ├─ File (single uploaded audio)                             │
│    ├─ Music (multiple files with play mode)                    │
│    ├─ Stream (external URL)                                    │
│    └─ Chime (jingle interval)                                  │
│                                                                 │
│  ──────────────────────────────────────────────────────────────│
│                                                                 │
│  ▼ Source Configuration                                         │
│                                                                 │
│  [Music Playlist] [Chime & Announcements]                       │
│                                                                 │
│  Mode: [Shuffle (Random Order) ▼]                              │
│                                                                 │
│  Audio Files:                                                   │
│  [+ Add Files]                                                  │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ ⋮⋮ │ File Name           │ Size  │ Status  │ ▶ │ Actions  ││
│  ├────┼─────────────────────┼───────┼─────────┼───┼──────────┤│
│  │ ⋮⋮ │ corporate_jingle.mp3│ 2.3MB │ ✓ Saved │ ▶ │ 🗑       ││
│  │ ⋮⋮ │ jazz_loop.wav       │ 5.1MB │ ✓ Saved │ ▶ │ 🗑       ││
│  │ ⋮⋮ │ classical.ogg       │ 3.8MB │ ✓ Saved │ ▶ │ 🗑       ││
│  └─────────────────────────────────────────────────────────────┘│
│  Drag to reorder                                                │
│                                                                 │
│  Interval (seconds): [30              ]                        │
│    Time before switching to next track                          │
│                                                                 │
│  [Save] [Cancel]                                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Quick Tips

> [!TIP]
> **Class Name**: Use in `local_stream://domains/${domain}/${class}`.

> [!TIP]
> **Shuffle Mode**: Randomly orders playlist on each call.

> [!NOTE]
> **File Limits**: Max 100MB per file, WAV/MP3/OGG formats.

---

## 🎯 User Roles & Key Capabilities

| Role | Key Capabilities & Permissions | Operational Scope |
| :--- | :--- | :--- |
| **PBX Super Administrator** | • Global Music on Hold storage allocation and sampling rate governance<br>• Core `local_stream.conf.xml` Telephony Server stream class reload orchestration<br>• System fallback playlist designation (`default`) and deletion protection enforcement<br>• External Icecast/Shoutcast network bandwidth and port access control | Full Platform Scope |
| **Tenant Administrator** | • Custom domain hold music playlist creation and audio upload (WAV, MP3, OGG)<br>• Periodic comfort chime interval and announcement frequency configuration<br>• External radio stream integration and playback mode selection (linear, shuffle, loop)<br>• Assignment of MOH classes to ring groups, ACD queues, and parking lots | Domain Scope |
| **Call Center Supervisor** | • Read-only inspection of active MOH playlists and queue hold audio<br>• Real-time stream testing and periodic chime message audit<br>• Request submission for custom campaign wait-time audio messages | Supervised Queues |
| **AI Copilot / MCP Agent** | • Real-time playlist and stream query (`list_moh_sources`)<br>• Diagnostic inspection of audio directory contents and play modes (`get_moh_source_status`)<br>• Autonomous creation/updating of campaign hold streams (`create_moh_source`, `update_moh_source`)<br>• Safe deletion with dependency safeguards (`delete_moh_source`) | Autonomous Assistant |

---

## 4. Configuration Sections

### Basic Information

| Field | Description |
|-------|-------------|
| **Name** | Friendly display name |
| **Class Name** | Stream identifier |
| **Description** | Optional notes |
| **Priority** | Lower = plays first |
| **Enabled** | Active/inactive |
| **Source Type** | File, Music, Stream, Chime |

### Source Types

| Type | Description |
|------|-------------|
| **File** | Single uploaded audio file |
| **Music** | Multiple files with play mode |
| **Stream** | External HTTP/Icecast/Shoutcast |
| **Chime** | Periodic jingle insertions |

### Play Modes

| Mode | Description |
|------|-------------|
| **Linear** | Play in order |
| **Shuffle** | Random order per session |
| **Random** | Random each play |

---

## 5. Settings Reference

### File/Music Source

| Setting | Description |
|---------|-------------|
| **Audio Files** | Uploaded audio files |
| **Mode** | Linear, Shuffle, Random |
| **Interval** | Seconds per track (1-120) |

### Stream Source

| Setting | Description |
|---------|-------------|
| **Stream URL** | HTTP/HTTPS/Icecast URL |
| **Test Stream** | Browser playback test |

### Chime Source

| Setting | Description |
|---------|-------------|
| **Chime List** | Comma-separated jingle files |
| **Chime Frequency** | Seconds between chimes (10-600) |

### Supported Formats

| Format | Extension | Notes |
|--------|-----------|-------|
| WAV | .wav | Best quality |
| MP3 | .mp3 | Compressed |
| OGG | .ogg | Open format |

---

## Model Context Protocol (MCP) AI Integration

The **Music & Hold** module provides dedicated Model Context Protocol (MCP) tools enabling AI Copilots, autonomous call center managers, and voice assistants to query, configure, and maintain tenant hold music playlists and live audio streams.

### Available MCP Telephony Tools

| Tool Name | Action Type | Access Level | Description |
| :--- | :--- | :--- | :--- |
| `list_moh_sources` | `READ` | `Read-Only` | Lists all Music on Hold playlists, sound directories, and live stream sources in the active PBX domain. |
| `get_moh_source_status` | `READ` | `Read-Only` | Retrieves detailed configuration, file paths, sample rates, and play mode (linear/shuffle) of a specific MOH source. |
| `create_moh_source` | `WRITE` | `Admin` | Creates a new Music on Hold playlist, sound directory, or live stream class in Telephony Server. |
| `update_moh_source` | `WRITE` | `Admin` | Modifies playlist settings, audio stream URLs, sample rate, or periodic chime intervals. |
| `delete_moh_source` | `DESTRUCTIVE`| `Admin` | Removes a custom MOH source with automated dependency protection guards. |

### Tool Schemas & Input Parameters

#### `list_moh_sources`
```json
{
  "name": "list_moh_sources",
  "description": "List all Music on Hold (MOH) playlists, sound directories, and live stream sources in the PBX.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "search": {
        "type": "string",
        "description": "Filter by MOH playlist or class name."
      }
    }
  }
}
```

#### `get_moh_source_status`
```json
{
  "name": "get_moh_source_status",
  "description": "Get configuration, audio files, and play mode (linear/shuffle) of a specific Music on Hold playlist.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "Name of the MOH source / playlist (e.g. 'default' or 'Rock Hold Music')."
      }
    },
    "required": ["name"]
  }
}
```

#### `create_moh_source`
```json
{
  "name": "create_moh_source",
  "description": "Create a new Music on Hold playlist or audio stream source in Telephony Server.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name": { "type": "string", "description": "Name of the MOH source playlist." },
      "className": { "type": "string", "description": "Telephony Server MOH class identifier (e.g. 'sales_hold', 'jazz')." },
      "sourceType": { "type": "string", "enum": ["file", "stream", "chime"], "description": "Audio source type." },
      "streamUrl": { "type": "string", "description": "HTTP/HTTPS Icecast or Shoutcast stream URL (if sourceType is stream)." },
      "rate": { "type": "number", "description": "Audio sample rate in Hz (8000, 16000, 32000, 48000). Default: 16000." },
      "shuffle": { "type": "boolean", "description": "Whether to randomize track playback order." }
    },
    "required": ["name"]
  }
}
```

### Natural Language AI Copilot Prompts

#### English Prompts
- *"List all Music on Hold sources configured in our PBX and show their stream types."*
- *"Check the configuration details and sample rate of the 'default' hold music playlist."*
- *"Create a new MOH source named 'Corporate Jazz' with sample rate 16000 Hz and shuffle enabled."*
- *"Update the streaming URL for our external radio hold source to the new HTTPS endpoint."*

#### Spanish Prompts
- *"Lista todas las fuentes de música en espera configuradas en el PBX y sus tipos de origen."*
- *"Muestra la configuración y la lista de archivos de la lista de reproducción 'default'."*
- *"Crea una nueva fuente de música en espera llamada 'Ventas Hold' con reproducción aleatoria y 16000 Hz."*
- *"Verifica si la fuente de espera 'Musica Clásica' está asociada a alguna cola de atención antes de eliminarla."*

### Enterprise Safeguards & Multi-Tenant Isolation
1. **Domain Isolation**: Every MOH query and mutation is strictly partitioned by `domain_id`, preventing cross-tenant access to proprietary corporate audio tracks or live streams.
2. **Deletion Protection Guard**: System-critical sources like the `default` MOH class and any playlist currently bound to active ACD Queues, Ring Groups, or IVRs are shielded from deletion by `assertCanDeleteMohSource()`.
3. **Stream Protocol Sanitization**: Stream URLs must start with `http://` or `https://` to prevent command injection into underlying audio relay subprocesses.

---

## 6. Common Scenarios & Examples

### Scenario 1: Simple Hold Music

1. Create new MOH source
2. Name = "Default Hold"
3. Class = "default"
4. Type = File
5. Upload audio file
6. Enable and save

### Scenario 2: Music Playlist

1. Create new MOH source
2. Name = "Sales Playlist"
3. Class = "sales"
4. Type = Music
5. Upload multiple files
6. Mode = Shuffle
7. Interval = 30 seconds
8. Save

### Scenario 3: Internet Radio

1. Create new MOH source
2. Name = "Jazz Radio"
3. Class = "radio"
4. Type = Stream
5. Stream URL = http://example.com/stream.mp3
6. Test stream
7. Enable and save

### Scenario 4: Position Announcements

1. Create new MOH source
2. Name = "Queue Position"
3. Class = "announce"
4. Type = Chime
5. Chime List = position.wav,thankyou.wav
6. Chime Frequency = 60 seconds
7. Save

---

## 7. Limitations & Important Notes

### Technical Notes

> [!NOTE]
> **Stream Address**: `local_stream://domains/${domain}/${class}`

> [!NOTE]
> **mod_local_stream**: Uses Telephony Server local stream module.

> [!WARNING]
> **File Size**: Maximum 100MB per file.

### Best Practices

1. **Optimize Audio**: Convert to 8kHz mono for bandwidth
2. **Test Streams**: Verify external URLs work
3. **Reasonable Intervals**: 15-60 seconds typical
4. **Priority Planning**: Lower numbers play first
5. **Backup Files**: Keep originals

### Stream URL Formats

| Type | Example |
|------|---------|
| **HTTP** | http://server.com/stream.mp3 |
| **HTTPS** | https://server.com/stream.mp3 |
| **Icecast** | http://icecast.server:8000/stream |
| **Shoutcast** | http://shout.server:8000/stream |

---

## 8. Troubleshooting Tips

### Common Issues

| Symptom | Possible Cause | Solution |
|---------|---------------|----------|
| No audio | Source disabled | Enable source |
| Wrong music | Wrong class | Check class name |
| Upload fails | File too large | Reduce file size |
| Stream fails | Bad URL | Test stream in browser |
| Silence | Invalid format | Convert to WAV/MP3 |

### Test MOH Stream

```bash
# Test in Telephony Server
fs_cli -x "originate loopback/1000 &playback(local_stream://domains/example.com/default)"

# Check local_stream status
fs_cli -x "local_stream status"
```

### Check Uploaded Files

```bash
# List MOH files
ls -la /var/lib/freeswitch/storage/domains/{domain}/moh/

# Test audio file
aplay /path/to/file.wav
```

---

## 9. Glossary

| Term | Definition |
|------|------------|
| **MOH** | Music on Hold |
| **Class** | Stream identifier |
| **local_stream** | Telephony Server streaming module |
| **Chime** | Periodic announcement |
| **Shuffle** | Random play order |
| **Icecast** | Open source streaming server |

---

*Documentation last updated: January 2026*