Asterisk Music on Hold: Classes, Formats and Streaming Sources

Classes are the unit of configuration

Music on hold in Asterisk is organised into classes, each defined in musiconhold.conf. A class names a source of audio, and different parts of your system can use different classes — one for the sales queue, another for support, a third for after-hours.

The most common form plays files from a directory:

[default]
mode = files
directory = /var/lib/asterisk/moh
random = yes

The realtime configuration exposes the same concepts as fields: name, directory, application, mode, digit, sort and format.

mode = files is what you want in almost every case: Asterisk reads audio files from a directory and streams them. random = yes shuffles rather than always starting from the first track, which matters more than it sounds — callers who hold repeatedly should not hear the same eight bars every time.

Creating your own class

Put the audio in its own directory and define a class pointing at it:

[sales]
mode = files
directory = /var/lib/asterisk/moh/sales
random = yes

[support]
mode = files
directory = /var/lib/asterisk/moh/support
sort = alpha

Then reference the class where you want it. On a queue:

[sales-queue]
strategy = rrmemory
musicclass = sales

Or per channel from the dialplan, which is how you vary hold music by time of day, caller, or route:

exten => _X.,1,Set(CHANNEL(musicclass)=support)
 same => n,Queue(support-queue)

If a class is not specified when music on hold is invoked, the channel's default music source is used — and that default is exactly what Set(CHANNEL(musicclass)=...) changes.

Reload and confirm Asterisk sees the class and its files:

asterisk -rx "moh reload"
asterisk -rx "moh show classes"
asterisk -rx "moh show files"

moh show files is the one that catches problems — a class with zero files is silently silent.

Convert your audio, for a real reason

This is where music on hold differs from ordinary prompts, and it is worth understanding rather than following as a rule.

A prompt plays occasionally, for a few seconds. Hold music plays continuously, to every waiting caller, for as long as they wait. If the file format does not match the codec in use, Asterisk transcodes it — and that transcoding happens per call, continuously. With twenty callers on hold, you are running twenty simultaneous transcodes for audio nobody is listening to attentively.

Converting MoH to a native format removes that cost almost entirely. The same rules apply as for prompts: 8 kHz, mono, 16-bit, in a format matching your calls — sln for no transcoding at all, or ulaw/alaw to match G.711.

sox input.wav -r 8000 -c 1 -t ul output.ulaw

As with prompts, keeping the same track in several formats lets Asterisk pick whichever needs least work for the current call.

And check ownership after copying files in — a directory the Asterisk user cannot read produces silence with no obvious error:

chown -R asterisk:asterisk /var/lib/asterisk/moh

Streaming and external sources

Beyond files, a class can run an external application that produces audio on standard output — the mechanism behind streaming an internet radio station or a live feed.

It works, and it is occasionally the right answer for a broadcast-style source. But weigh it carefully: the external process must keep running, a network stream can stall or die, and when it does your callers get silence rather than a fallback. For most businesses, local files are more reliable and the flexibility of streaming is not worth the failure mode.

Disabling music on hold

Sometimes you want ringing rather than music — many callers read silence-plus-music as "nobody is coming" while ringback reads as "it is still connecting". For a queue, the r option to Queue() plays ringing instead of hold music.

To disable MoH for a class entirely, the established trick is a class with no audio to find:

[silence]
mode = files
directory = /dev/null

Pointing a class at /dev/null gives you a class that plays nothing, which is cleaner than removing configuration that other parts of the system may still reference.

The licensing point

Obvious and routinely ignored: commercial music requires a licence to play to your callers. Putting a popular track on hold is a public performance, and businesses do get pursued for it.

Use royalty-free music licensed for the purpose, or commission something. The default Asterisk installation ships music that is licensed for this use, which is why so many systems keep it — it is not laziness, it is the safe option.

Frequently asked questions

Why is my hold music silent?

Check moh show files — an empty class plays nothing. Then check file permissions, since a directory the Asterisk user cannot read fails silently.

What format should music on hold be in?

8 kHz mono 16-bit, in a format matching your call codec — sln or ulaw/alaw. Because MoH plays continuously to every held caller, transcoding it is a genuine CPU cost.

How do I use different music for different queues?

Define a class per audio set in musiconhold.conf and set musicclass on each queue, or set CHANNEL(musicclass) in the dialplan for per-call control.

How do I turn music on hold off?

Use the r option to Queue() to play ringing instead, or define a class with directory = /dev/null so it has nothing to play.