Asterisk config musiconhold.conf

MusicOnHold Configuration

Asterisk 1.2

In Asterisk 1.2.x and above you no longer need to use the mpg123 player to play mp3 files, you can use the asterisk addon "format_mp3". mpg123 or something similar is still required for mp3 streams.

Achtung!: In 1.2.17 (mb other versions too) usage of older mpg123 version (pre-October 2007) with some mp3 formats (probably with new ID3 tags) causes Asterisk to close itself while reloading MOH without any error messages. On restart it closes itself again (because on restart it reloads MOH too).

Note (rchadwel): Format_MP3, Asterisk's mpg123 replacement, will play the MOH file from the beginning each time a caller is put on hold or each time the musiconhold command is invoked from extension.conf. If you have one file (mp3, ul, wav, raw, etc) as your source, they will hear the first part of it over and over again - driving them insane.

In order to use Asterisk's built in MOH playback support with the default MOH mp3 files (fpm-calm-river.mp3, fpm-sunshine.mp3, fpm-world-mix.mp3) you must have installed the asterisk-addons package! It contains a utility called format_mp3 which is required for mp3 playback.
Note: in Asterisk 1.4 the default file format is changed to wav which does not require format_mp3

File format

The format for this file has changed in Asterisk 1.2.
The format up to Asterisk 1.0 was with one line per class under the [classes] section

classname => mode:directory,application

The new format in Asterisk 1.2 and above is with each class in it's own section, like this

mode => mode
directory => directory
application => application

For using a streaming source, use the "streamplayer" tool that comes with Asterisk (see musiconhold.conf.sample for more info)

application=/usr/sbin/streamplayer 888

Note (rchadwel): Streamplayer only works with a RAW TCP stream and will not stream from Shoutcast or Slimserver. For those you need to continue to use mpg123 or madplay.
Note (malaiwah): If you still want to use mpg123 or madplay like I do, you can use the streamnoblock utility from that will effectively get rid of the "res_musiconhold.c: Request to schedule in the past?!?!" error you would have in your error logs. It's a "streamplayer-like" utility that works with shell pipes instead of raw TCP streams. Just add streamnoblock as a last pipe to your chain; you can see an usage example in the bugtracker link below.

Volume Adjustment

Lately I've received a number of complaints that the native music on hold is too loud when the system is connected to the PSTN through TDM equipment. Easy problem to resolve with sox. Here's the command:

sox -v {level} {input file} {output file} - Where level is basically the percentage of volume of the input file. i.e. 1 = 100 percent = same outpufile volume as the input volume. .5 = 50 percent = output volume is roughly half of the volume of the input file. 2 = 200 percent = output file is twice as loud as input file.

Asterisk 1.2 Custom Applications

If you are using a custom application, you will need to ensure it outputs in mono, at 8kHz (samples/second), 8 bits per sample, in ulaw format.


application=/usr/bin/madplay -Qzr -o raw:- --mono -R 8000 -a -12

Note: you need to specify the full path to madplay (this may be /usr/local/bin/madplay on some systems)

Some users report success with snd (ulaw) output:

application=/usr/bin/madplay --mono -R 8000 --output=snd:-

madplay parameter meaning
-Q quiet mode
-z shuffle
-r repeat forever
-o raw:- 'raw' output to stdout
--mono convert to mono
-R 8000 8kHz sample rate
-a -12 amplify -12dB

Example using icecast & shoutcast streams

I use a one-line shell-script to run the stream. This has the advantage of being able to make changes without reloading or restarting Asterisk. Simply do a 'killall -9 ogg123 sox madplay' and the stream will restart automatically. I've also tested network interruption... the stream restarts automatically.

Note: If you use the sox example, the first sampling rate (shown below as "-r 16000" ) will have to match the input stream rate. It's trivial to tweak this.

 #Uncomment one of the lines below, they both sound great:
 /usr/bin/ogg123 -q -b 128 -p 32 -d wav -f -| sox -r 16000 -t wav - -r 8000 -c 1 -t raw - vol 0.10
 #/usr/bin/wget -q -O - | /usr/local/bin/madplay -Q -z -o raw:- --mono -R 8000 -a -12 -

Note: When using the madplay method, if the stream you are using has something like to connect to the stream, but no filename, it is imperative that the trailing slash is removed.

Stream radio using MPlayer for MOH

I've finally setup this to work on my CentOS 6.6 installed from atrpms REPO. Mplayer version is SVN-r37150-snapshot-4.4.6

The script that I've used is modified script that you can find here. Here is the script (I've putted it on /usr/sbin/


if -n "`ls /tmp/asterisk-moh-pipe.*`" ; then
rm /tmp/asterisk-moh-pipe.*

mknod $PIPE p

mplayer http://address_of_radio_station -really-quiet -quiet -ao pcm:file=$PIPE -af resample=8000,channels=1,format=mulaw 2>/dev/null | cat $PIPE 2>/dev/null
rm $PIPE

And in musiconhold.conf:


This finally works for me and now I have radio station as MOH.

Example using asx (mms://)(.wmv) streams. (or "anything" that mplayer can play).

Here is the script to play mms:// stream for MOH in Asterisk PBX (needs mplayer to be installed)
Thanks to Steve!

if -n "`ls /tmp/mayakpipe`" ; then
     rm /tmp/mayakpipe
mkfifo $PIPE
cat $PIPE &
sleep 3
mplayer -cache 8192 -cache-min 4 mms:// -really-quiet -quiet -ao pcm:fast -af resample=8000,channels=1,format=mulaw -ao pcm:file=$PIPE
rm $PIPE

Servers using newer versions of mplayer, might have better luck using this to invoke mplayer:

mplayer mms:// -really-quiet -quiet -ao pcm:nowaveheader,file=$PIPE -af resample=8000,channels=1,format=mulaw  | cat $PIPE

It's seems the format of command line arguments have changed with newever versions.

Pre-Asterisk 1.2 Information Below

Using madplay

If you want to keep the original distributed mpg321, you can use madplay to generate the mp3 in the same way that mpg123 does.

Just use a custom player like this one and you are done:
default => custom:/var/lib/asterisk/mohmp3/,/usr/bin/madplay --mono -R 8000 --output=raw:-

Installing mpg123

You must first compile and install mpg123. Make sure that you don't previously have mpg321 installed. You can do a "whereis mpg321" and an "rpm -q mpg321" if you are using RedHat.

  • Download a copy of mpg123 at and download the newest non-development version. Vesion 0.59r is known to work with Asterisk.

--Edit Note(rchadwel): Version 0.59r is the best version to use with Asterisk - don't be tempted by 0.60x versions.

  • tar -zxvf mpg123-<version>.tar.gz
  • cd mpg123
  • as of May 2004 this note from the site front page seems to apply the current version, so you may want to make the suggested edit:
    • 16. Jan. 2003
    • Important information about the Gobble Exploit: It seems, that only the pre0.59s version is vulnerable. The hotfix is to increase the MAX_INPUT_FRAMESIZE to a big value. Ie 4096. I will review the whole code this weekend. I will also try to supply an mp3 checker this weekend. So it is not necessary to remove all your mp3s. Just do not play them with a potentially vulnerable player and check them later. Thanx.
  • type "make" to see a list of supported hardware platforms and operating systems, then type the make command that best fits your system.
    • If your make fails, try a "make clean" first. Also note that there is a "make linux-devel" which I needed to use to make it work (on debian 2.4.26-1-686 against devel sources) , YMMV.
  • If compilation was successful, type "make install" to install the binary and the manual page in /usr/local
  • ln -s /usr/local/bin/mpg123 /usr/bin/mpg123 << this creates a symlink in the /usr/bin directory, which is where asterisk searches for mpg123 (this should no longer be necessary as asterisk checks both)

Editing your files to enable MusicOnHold

  • In /etc/asterisk/zapata.conf, add the line "musiconhold=default" under [channels] context
  • In /etc/asterisk/musiconhold.conf, uncomment the line that says "default => mp3:/var/lib/asterisk/mohmp3"
  • You must restart Asterisk in order to reload the musiconhold.conf settings.

Specifying the Music

The sample music on hold file (/etc/asterisk/musiconhold.conf) will contain:

;default => quietmp3:/var/lib/asterisk/mohmp3
;loud => mp3:/var/lib/asterisk/mohmp3
;random => quietmp3:/var/lib/asterisk/mohmp3,-z

Uncommment the 'default =>' line.
Then MP3 files in the directory: /var/lib/asterisk/mohmp3 will be played for music on hold. If there are multiple files in the directory, they will be played sequentially. Strip out the ID3 tags from any files you add to this directory with

Defining Your Own Music for Music On Hold

If you would like to have music of your choosing available for music on hold, create a subdirectory in the path /var/lib/asterisk/mohmp3, named what you want your class name for this music to be.

For example: I would like make the tune "Tip Toe Through the Tulips" available as hold music. I would create a folder named "Tiny_Tim" in the path /var/lib/asterisk/mohmp3. In other words, I would create the path /var/lib/asterisk/mohmp3/Tiny_Tim. Next, add the line:
Tiny_Tim => quietmp3:/var/lib/asterisk/mohmp3/Tiny_Tim
to your musiconhold.conf file. Next, I would put the MP3 file "Tip Toe Through the Tulips" in my newly created "Tiny_Tim" folder. I could also put other MP3 files in my "Tiny_Tim" folder, and the files would be played in sequential order. If I also had "It's a Small World" in the "Tiny_Tim" folder, the music on hold system would first play "It's a Small World", then "Tip Toe Through the Tulips", then (assuming the victim - er caller - was still there), loop back around and play "It's a Small World". The way you would specify what hold music would be used is by calling SetMusicOnHold() before your Dial statement, like this:
exten => 100,1,SetMusicOnHold(Tiny_Tim)
Exten => 100,2,Dial(Zap/2)

You can define as many classes of music on hold as you want using the example above with different class names and subdirectory names.

There is a post-1.0 patch pending to allow support of native formats other than mp3. See:

Error in MusicOnHold - Warning, flexibel rate not heavily tested!
This warning shows due to the coding method of your MP3 music. Variable bitrate is not supported by Asterisk (infact sometimes it won't play ANY music and will just mute your speakers, while letting the other caller STILL hear you), so use your favorite MP3 editing tool and convert the file to constant bitrate encoding. And since you are going to play this music through the phone you for sure won't need anything higher than 128 bit/s ...

# lame -b 128 input.mp3 output.mp3

Realtime Configuration

You can also configure Asterisk to use the Realtime database for loading MOH classes (thanks, sergee!). The table for MySQL looks like this:

CREATE TABLE `bit_musiconhold` (
  `name` varchar(80) NOT NULL,
  `directory` varchar(255) NOT NULL default '',
  `application` varchar(255) NOT NULL default '',
  `mode` varchar(80) NOT NULL default '',
  `digit` char(1) NOT NULL default '',
  `sort` varchar(16) NOT NULL default '',
  `format` varchar(16) NOT NULL default '',
  PRIMARY KEY (`name`)

And the entry in extconfig.conf looks like this:

musiconhold => mysql,asterisk,[table name]

One thing to watch for is that you still have to define at least one class in musiconhold.conf or the res_musiconhold module won't be loaded when Asterisk starts up (and will be unloaded if you try to load it on the CLI, since Asterisk still doesn't see any classes defined).



Setup extension in extensions.conf to test MusicOnHold

; Answer required as Music On Hold does not answer the call (Updated By Matthew1471 to Answer)
exten => 6000,1,Answer 
exten => 6000,2,MusicOnHold() 

Shoutcast Music On Hold

You can have asterisk use a streaming source for on-hold music.

Make a directory and put a 0 size file ending in .mp3.
I called my directory: /var/lib/asterisk/mohmp3-empty

in musiconhold.conf, add a line such as:

default => mp3:/var/lib/asterisk/mohmp3-empty,

Alternative method --

The initial method seems to not work in 1.2 & +. You can use the method below, doing a custom application and calling mpg123, and specifying your shoutcast source.

dir=/var/lib/asterisk/mohmp3-empty {COMMENT}daab{/COMMENT} 
application=/usr/local/bin/mpg123 -q -r 8000 -f 8192 -s --mono

Using native Asterisk format_mp3 for Music on Hold*

* In my experiance this does not work with the stable 1.x tree. I could only get it working with the CVS Head (Umar)

You may also use the format_mp3 module available within the asterisk-addons package. Simply download asterisk-addons and do a make; make install of /usr/src/asterisk-addons/format_mp3.

Make a directory called /var/lib/asterisk/moh-native.

Drop your MP3 files into the new diretory you created above.

Put this in your musiconhold.conf file:

default => /var/lib/asterisk/moh-native

If you want random playback order, add ",r" to the end of your lines, like this:

default => /var/lib/asterisk/moh-native,r

Be sure to remove mpg123 from your system (this may attribute to 'Request to schedule in the past!?!?!' messages). Now you are set!

For Asterisk 1.2 or greater i suggest:


Note: It was previously required with format_mp3 that you convert your mp3 files as follows:

lame -q -p --mp3input -a --preset 8 -m mono in.mp3 8kout.mp3

It appears per bug report 3316 these audio format may actually be causing an Asterisk segmentation fault, this is being investigated. It appears that mp3 files not formatted in this way work fine and that the above conversion is no longer necessary.

Answer and then Hold IAX clients

After a bit of googling i figured out how to enable hold feature with music in asterisk. You need to open up the iax client library and send quelch/unquelch with music on hold.If you figure out what quelch is, it is easy to send the command. Once asterisk recieve the command it will put the channel in hold. The music is from the default context of musiconhold.conf.


Using a sound card as the source.

This is usefull for such things as FM tuners or other external audio feeds (XM Satellite Radio anyone?).

1. Add the following into musiconhold.conf:


In /var/lib/asterisk/mohmp3 there should be at least one mp3 file.

2. Create script file /usr/sbin/ast-playlinein and make it executable:

/usr/bin/arecord -q -c 1 -r 8000 --buffer-size=2048 -f S16_LE -t raw

3. Then you need to configure your mixer to turn on LINE-IN capturing.
You can then plug into the line-in port your FM-tuner or external audio player.

Don't forget to reload (should be enough) asterisk.

Additional note by crees (at) bearrivernet (dot) net
Trixbox users may notice that this does not work. Your MOH will start and stop immediatly. This is due to asterisk not having rights to the /dev/snd folder and files. You will need to create a new group (i called audio) and then allow root and asterisk to be part of it. then chmod the directory so everyone can have access to read and write these files. (in /dev/snd ) You then will need to adjust the mixer via alsamixer command. I ended up using the mic in on my sound card since line in on mine was not working. Look for the line in capt and line in or mic in , mic capture levels and adjust them accordingly. You may want to unmute (pushing m on slider) and move all sliders up and see which one controls the volume.

Using chiptunes (XM, IT, S3M and MOD files)

What are chiptunes you ask? Remembers those oldskool loop electronic music, 8-bit sounds, Nintendo, Atari and such? If you're too youg to remember that or have no idea what I'm talking about, wikipedia can help you :
For this you will need DUMB from
In musiconhold.conf, you'll need a section

application=/usr/bin/dumbout /var/lib/asterisk/moh/mod/music.s3m -m -s 8000 -o -

Now for the details: the section, mode and application are already defined quite througly on this page, so let's just skip to the dumbout params.
It seems asterisk expects a 8000 hz samplerate, monochannel and with ulaw (pcm) encoding. So obviously, the -m states that the output is mono (single channel), -s that the sample rate is 8000 hertz and the -o - (note the dash) that the preferred output is stdout (and not a file). You'll also have guessed that you need to change the /var/lib/asterisk/moh/mod/music.s3m part to point to your music. You could also write yourself a script to add random file selection and such, but you get the point.

Now you just need to change your extension.conf file to add a command somewhere that will look like this

exten => 6000,1,Answer
exten => 6000,2,MusicOnHold(dumbout)

... see above for more details on that. Tested on Asterisk 1.4.

See also

Asterisk | Configuration | FAQ
Created by: oej, Last modification: Thu 25 of Jun, 2015 (07:05 UTC) by bramar
Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - Find us on Google+