Having used Broadsoft’s BroadWorks for many years I can’t tell you how many times I’ve been asked “How can callers hear different music each time they are placed on hold?” This is something the BroadWorks platform does not easily provide for end customers. Every time a caller is placed on hold, they hear the beginning of whatever song or sequence of songs is configured for that business. While music on hold is something that most callers may not find particularly entertaining, what if we could have listeners hear a variety of songs, and just “tune-in” to wherever the music sequence is (as if you just turned the radio on, or resumed playing your iPod)? That’s when the light bulb lit up – we can use Asterisk complement the Broadworks platform and provide a flexible music on hold server!
Asterisk is an open source implementation of a PBX created by Digium. When I think of Asterisk, I think of it as the canvas that enables the artist creatively express their vision. Asterisk provides a framework for us to develop custom telephony applications within our telephony network while Broadworks is the workhorse that provides carrier class VoIP service levels.
What’s needed to get the job done?
- Server running Asterisk
- Fixed IP address on Asterisk Server
- DRM-Free Music files (can be MP3, WAV, or internet streaming URL)
- About an hour to set up everything
Step 1: Install Asterisk
Install Asterisk on your server. There are many ways this can be done, depending on your OS choice. We will be using the SIP protocol to communicate to your Asterisk server. Make sure your firewall allows port 5060/udp into your Asterisk server. Start Asterisk, most binary installations provide a system script for starting/stopping Asterisk.
Step 2: Setup Asterisk/BroadWorks SIP Peering
Set up a SIP peer in Asterisk sip.conf. You should use the hostname of either your BroadWorks Application Server DNS, or your session border controller (depending on BWorks network). See example below.
code:
/etc/asterisk/sip.conf
[broadworks]
type=peer
host=broadworks-as.yourdomain.net
dtmfmode=auto
insecure=port
context=music-on-hold
Step 3: Asterisk Dial Plan
code:
/etc/asterisk/extensions.conf
[music-on-hold]
; Music On Hold Inbound Context from BroadWorks
exten => music1,1,Set(CHANNEL(musicclass)=music1)
exten => music1,n,Answer
exten => music1,n,MusicOnHold(music1)
exten => music1,n,HangUp
The above code is an example you’ll want to add to your Asterisk extensions.conf file. [music-on-hold] is the name of your Asterisk Dial Plan Context, which must match the SIP context= parameter from Step 2. Extensions can be numbers, words, or a combination of the two. For simplicity, I’ve used the extension music1. If you want to create multiple configurations for Music On Hold, you’ll want an extension created for each music configuration (up next).
Step 4: Asterisk Music On Hold
The musiconhold.conf configuration file defines the various music configurations. In the above example I used extension music1 and routed it to music class music1.
code:
/etc/asterisk/musiconhold.conf
[music1]
; Music On Hold for BroadWorks
mode=custom
application=/usr/bin/mpg123 -q -r 8000 -f 8192 -b 2048 --mono -s --list /var/lib/asterisk/moh/music1/music1.pls
The music on hold class example uses the music1 name and a custom mode. The custom mode gives us the ability to specify a music playlist. This allows you to define how the various files get played. If you don’t want to manage the playlist, you can have the server generate the list automatically using a script and the crontab for automatic updates.
The audio files in my example are saved in the directory /var/lib/asterisk/moh/music1/ This is also the same folder where the playlist file is saved. You can copy your files to the server whichever way works best for you. Most systems have FTP and SFTP/SCP available for remote file copying.
I thought an FTP server would handle this well, and other admins can easily use FTP to manage all the music files. To do this, I first created a user that has a custom home-directory. The home-directory is the same directory I configured for music1 music on hold class /var/lib/asterisk/moh/music1/
code:
groupadd music1
useradd -c "Music1 User - MOH" -d /var/lib/asterisk/moh/music1/ -s /bin/false -g music1 music1
passwd music1
chown -R music1:music1 ~music1
chmod -R g=rwxs ~music1
The above commands create a local user called music1 and assigned home-directory is that of the music1 music on hold class. Then we set the password (this is an interactive step that prompts for password). Following the password are file ownership and permissions (just in case directories already exist and are pre-populated). The ~music1 is short-hand for e
code:
ls /var/lib/asterisk/moh/music1/
Bach Brandenburg Concerto 1 (1st movement).mp3
Bach Brandenburg Concerto 1 (2nd movement).mp3
Bach Brandenburg Concerto 1 (3rd movement).mp3
Bach Brandenburg Concerto 1 (4th movement).mp3
Bach Brandenburg Concerto 2 (1st movement).mp3
Bach Brandenburg Concerto 2 (2nd movement).mp3
Bach Brandenburg Concerto 2 (3rd movement).mp3
Ever Softer Grows My Slumber.mp3
Mendelssohn Fingels Cave Overture.mp3
Mendelssohn Wedding March (from Midsummer Nights Dream).mp3
music1.pls
Restart Asterisk if you haven’t by now, It needs to re-read the configuration files.
code:
/etc/init.d/asterisk restart
Step 5: Custom Asterisk Server Script for Music On Hold Playlist Files
I wrote a script that looks for files and inserts their names into a playlist file, that way I can organize my music files by sub-folders. The sub-folders (optional) allows me arrange my music files into folders however I see fit.
code:
/etc/asterisk/moh-scrub-playlists.sh
#!/bin/bash
#
# Collect the list of folders
# This could also be static via config file
#
# ./$0
#
moh_parent=/var/lib/asterisk/moh
for cheeseburger in `find ${moh_parent} -maxdepth 1 -type d -print | grep -v ${moh_parent}
do
group_name=`echo ${cheeseburger} | awk -F/ '{print $NF}'`
# First Level "Group"
find ${moh_parent}/${group_name} -maxdepth 1 -type f -not -name '*.pls' -print > ${moh_parent}/${group_name}/${group_name}.pls
#
# Look for sub-dirs "Department"
#
cd ${moh_parent}/${group_name} && for hamburger in `find ${moh_parent}/${group_name}/* -maxdepth 1 -type d -print`
do
moh_stub=`echo ${hamburger} | awk -F/ '{print $NF}'`
find ${moh_parent}/${group_name}/${moh_stub} -type f -not -name '*.pls' -print > ${moh_parent}/${group_name}/${moh_stub}/${moh_stub}.pls
done
done
Save the script to /etc/asterisk/moh-scrub-playlists.sh. To automate the script process we use crontab:
code:
as root user: crontab -e
#
# Music On Hold Auto-Reload Cron
# -Jessie Bryan 09/15/2010
#
#
*/15 * * * * (/etc/asterisk/moh-scrub-playlists.sh ; sleep 1 ; /usr/sbin/asterisk -r -x "reload res_musiconhold.so") > /dev/null 2>&1
The above crontab entry will run the moh-scrub-playlists.sh script four times an hour, then tell the Asterisk server to reload the music on hold driver. Once you have calls on the Asterisk server, the server will not disconnect any connected callers while the Asterisk reload process runs.
Step 6: Configuring BroadWorks to use Asterisk for Music On Hold
* Login to your BroadWorks Application Server (using an Administrator-level user)
* Select the BroadWorks Group that you want to use for Music On Hold
* Click on “Resources”
* Click “Identify/Device Profile” in the right pane
* Click the Add button to add your new MOH device profile
** Set the “Identity/Device Profile Name” with the FQDN or IP address of your Asterisk server
** Set the “Identity/Device Profile Type” to “Unlimited MOH Device”
*** If you don’t have this device, you can always create one manually, or try the SIP generic.
** Set the “Host Name/IP Address” also to the Asterisk FQDN or IP address
** Set the port to “5060”
** Set the Transport to “UDP”
** When done properly, it should look like this:
** Click OK
* Go to Services (Group Level).
* Click on “Music/Video on Hold” in the right pane
* Choose the group or specific department that you want to use the new Music On Hold source
** Check: “Enable music/video during Call Hold”
** Check: “Enable music/video during Call Park”
** Select “External Source” radio button
*** Select the “Identity/Device Profile” radio button
*** In the “Identify/Device Profile Name” drop-down, choose the new asterisk.example.net device profile. Only Music On Hold device types will show up here, so the list will be very short.
*** The “Line/Port” must be the Asterisk Server extension created in Step 3. Example: music1
** Click OK in the “Music/Video on Hold Modify” page
** All set!
Step 7: Wrapping Up
So that’s it! Asterisk is using it’s built-in Music On Hold application to playback audio files that you uploaded. BroadWorks is configured to play this music each time a caller is placed on hold. The caller will hear music playing from where Asterisk is currently at in the playlist.