Ctrl K
ring2all.com

Music on Hold Sources Module Documentation

Table of Contents

  1. Module Overview (Technical)
  2. Module Overview (Commercial/Business)
  3. Module Overview (End User/Administrator)
  4. Configuration Sections
  5. Settings Reference
  6. Common Scenarios & Examples
  7. Limitations & Important Notes
  8. Troubleshooting Tips
  9. Glossary

---

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

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│              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                              │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        FreeSWITCH mod_local_stream                       │   │
│  │                                                          │   │
│  │  local_stream://domains/${domain}/${class}              │   │
│  │                                                          │   │
│  │  Call on hold → Play MOH source                         │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

TablePurpose
public.moh_sourcesMOH source definitions

Key Files

FileDescription
modules/mohSources/Frontend module
/var/lib/freeswitch/storage/...Uploaded audio files
---

2. Module Overview (Commercial/Business)

Business Value

MOH Sources provides customized hold experience:

Without MOH SourcesWith MOH Sources
Default silenceCustom music
No brandingBranded audio
Single trackMultiple playlists
No announcementsChime intervals

Use Cases

  1. Branded Hold Music

- Upload company jingles

- Professional image

  1. Multiple Playlists

- Different music per queue

- Various customer segments

  1. Announcement Chimes

- Periodic messages

- Wait time updates

  1. External Streams

- Internet radio

- Live content

Feature Highlights

FeatureBenefit
File UploadCustom audio files
External StreamsLive radio/podcast
Chime IntervalsPeriodic announcements
Play ModesLinear, shuffle, random
PrioritySource ordering
Multi-formatWAV, 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

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│              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

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│              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.

---

4. Configuration Sections

Basic Information

FieldDescription
NameFriendly display name
Class NameStream identifier
DescriptionOptional notes
PriorityLower = plays first
EnabledActive/inactive
Source TypeFile, Music, Stream, Chime

Source Types

TypeDescription
FileSingle uploaded audio file
MusicMultiple files with play mode
StreamExternal HTTP/Icecast/Shoutcast
ChimePeriodic jingle insertions

Play Modes

ModeDescription
LinearPlay in order
ShuffleRandom order per session
RandomRandom each play
---

5. Settings Reference

File/Music Source

SettingDescription
Audio FilesUploaded audio files
ModeLinear, Shuffle, Random
IntervalSeconds per track (1-120)

Stream Source

SettingDescription
Stream URLHTTP/HTTPS/Icecast URL
Test StreamBrowser playback test

Chime Source

SettingDescription
Chime ListComma-separated jingle files
Chime FrequencySeconds between chimes (10-600)

Supported Formats

FormatExtensionNotes
WAV.wavBest quality
MP3.mp3Compressed
OGG.oggOpen format
---

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 FreeSWITCH 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

TypeExample
HTTPhttp://server.com/stream.mp3
HTTPShttps://server.com/stream.mp3
Icecasthttp://icecast.server:8000/stream
Shoutcasthttp://shout.server:8000/stream
---

8. Troubleshooting Tips

Common Issues

SymptomPossible CauseSolution
No audioSource disabledEnable source
Wrong musicWrong classCheck class name
Upload failsFile too largeReduce file size
Stream failsBad URLTest stream in browser
SilenceInvalid formatConvert to WAV/MP3

Test MOH Stream

Bash
# Test in FreeSWITCH
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

TermDefinition
MOHMusic on Hold
ClassStream identifier
local_streamFreeSWITCH streaming module
ChimePeriodic announcement
ShuffleRandom play order
IcecastOpen source streaming server
---

Lua Script Status ℹ️

Configuration Module

ComponentStatus
MOH Sourcesℹ️ Configuration module - audio played via local_stream
MOH Sources is a configuration module. Audio files and stream configurations are used by FreeSWITCH mod_local_stream when calls are placed on hold.

---

Documentation last updated: January 2026
AI Assistant

👋 Hello! I'm your Ring2All documentation assistant. I can help you find information about configuring and using the Ring2All PBX platform.

How can I help you today?