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

[classes]
classname => mode:directory,application

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

[classname]
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)

[default]
mode=custom
application=/usr/sbin/streamplayer 192.168.100.52 888
format=ulaw

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 issues.asterisk.org/view.php?id=18276 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.

madplay

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.
musiconhold.conf

 [default]
 mode=custom
 dir=/var/lib/asterisk/mohmp3-empty
 application=/etc/asterisk/mohstream.sh

mohstream.sh
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.

 #!/bin/bash
 #Uncomment one of the lines below, they both sound great:
 /usr/bin/ogg123 -q -b 128 -p 32 -d wav -f - typical.icecast.net:80/moo.ogg| sox -r 16000 -t wav - -r 8000 -c 1 -t raw - vol 0.10
 #/usr/bin/wget -q -O - another.icecast.net:8001/somemusic.mp3 | /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 192.168.1.1:8000/ to connect to the stream, but no filename, it is imperative that the trailing slash is removed.

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!

mohstream.sh

#!/bin/bash
if -n "`ls /tmp/mayakpipe`" ; then
     rm /tmp/mayakpipe
fi 
PIPE="/tmp/mayakpipe" 
mkfifo $PIPE
cat $PIPE &
sleep 3
mplayer -cache 8192 -cache-min 4 mms://stream.rfn.ru/mayak -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://stream.rfn.ru/mayak -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 www.mpg123.de/cgi-bin/sitexplorer.cgi?/mpg123/ 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:

[classes]
;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 www.dakotacom.net/~donut/programs/id3ed.html.

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: bugs.digium.com/bug_view_page.php?bug_id=0002379

Error in MusicOnHold - -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 : en.wikipedia.org/wiki/Chiptune
For this you will need DUMB from dumb.sourceforge.net/index.php?page=downloads.
In musiconhold.conf, you'll need a section

[dumbout]
mode=custom
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
<">