Early Media and Music on Hold

Early media refers to any media that is played to the initial caller’s phone before the remote party has picked up the phone. That “brrrrrrrring!” noise you hear before the person you called has picked up the phone is an example of early media.

That ringing noise is not actually the other person’s phone, but a tone that’s generated by the system that’s setting up the call. Theoretically that ring can be anything, including music or audio files.

Asterisk can set up calls while generating early media. In fact, the “r” flag in the Dial command tells asterisk to generate the necessary tones for the “rrrrring!” audio.

exten => s,1,Dial(SIP/flowroute/16466429000,30,r);  <--- that "r" flag will generate ringing while Asterisk is setting up the call.

One of the great things about Asterisk is that it tries to “abstract” out the notion of a phone call. In other words, virtually all of Asterisk’s commands work the same way regardless of whether the actual call was SIP, IAX, H323, SS7, or any other crazy VoIP protocol.

However, this doesn’t work perfectly in practice. Each VoIP protocol behaves in slightly different ways, and sometimes that conflicts with Asterisk commands. SIP and IAX will allow early media but others may not. Also, some VoIP providers will block early media and replace it with their own.

There are a couple of ways to use early media. The first way is to play a message before initiating the call. An example of this would be a message that says “please stay on the line while I complete that call” followed by ringing the other caller’s phone. The other way is to basically replace the preset ringing tone with an audio stream. An example might be to play music to the initial caller as the remote phone is ringing. As soon as the remote party picks up the phone the song would stop.

How to play early media to a caller before ringing the phone:

exten => _1NXXNXXXXXX,1,Progress()
exten => _1NXXNXXXXXX,n,Playback(demo-abouttotry,noanswer)
exten => _1NXXNXXXXXX,n,Dial(SIP/flowroute/${EXTEN},30,r)
  • Progress() will let the phone system know that we are about to forward the call to another line. This is important for SIP calls, but may be optional for IAX calls. Just to be on the safe side, use it whenever you are about to generate early media.
  • Playback() needs to include the “noanswer” flag so that it won’t automatically answer the channel when it plays the media. The remote phone won’t ring until this audio file has fully played.
  • Dial() works as you would expect.

How to play early media to a caller while ringing the phone:

exten => s,1,Progress()
exten => s,n,Dial(IAX2/ck987_iax,30,m(ck987_moh))
  • Progress() will let the phone system know that we are about to forward the call to another line. This is important for SIP calls, but may be optional for IAX calls. Just to be on the safe side, use it whenever you are about to generate early media.
  • Dial() uses the “m(music_on_hold_class)” flag to play back audio while generating the call. See below for information on how to set up Music On Hold.

More Information on Early Media

Music On Hold

The most obvious use for Music on Hold (or “moh”) is to give a caller something to listen to while they are on hold or in a queue. You can set up various Music On Hold “classes” in your musiconhold.conf files. Here’s what mine looks like:

[ck987_moh]
mode=files
directory=/home/ck987/asterisk_sounds/moh
sort=random
  • mode=files means that this moh class will use audio files as its source.
  • directory=/home/ck987/asterisk_sounds/moh tells asterisk to play any file that’s in this directory
  • sort=random will randomly play a file in this directory. The other option would be “alpha” which would go through the list in alphabetical order.

In your dialplan, you can set a channel’s music on hold like this:

exten => s,n,Set(CHANNEL(musicclass)=ck987_moh); <---replace ck987_moh with your moh class.

If a SIP or IAX phone is placed on hold, the other caller should start to hear the audio defined by the active moh class. There is a MusicOnHold() command which will force Music On Hold to start, but you really should avoid this command. If you want to play an audio file, use Playback or Background. Music on Hold is a service that other commands can use. For example, Music On Hold can be used to play “early media” to a phone while it tries to connect another phone. See above for more info.

ADVANCED: Streaming External Audio for Music On Hold
Don’t try this unless it all makes sense to you!
A music on hold class can accept properly formatted audio streams as input. The audio must be 8000 hz, 16 bit, mono, PCM (uncompressed). The data is streamed through “Standard Out” (STDOUT).

When you make a class that uses an external process and do “module reload”, it will start the process at that exact moment. This means that it is sitting in the background, using up resources on the system. That’s fine for a few streams, but may become an issue if there’s a lot of them.

Here’s a Music On Hold class where I use an app called mpg123 to reformat and output the NPR Radio MP3 stream. Feel free to use this class in your own dialplans:

[ck987_stream]
mode=custom
application=/usr/bin/mpg123 -q -r 8000 -0 -s http://nprdmp.ic.llnwd.net/stream/nprdmp_live01_mp3
  • -q stops the app from listing the name of the stream at the beginning of playback
  • -r 8000 resamples the audio to 8000Hz
  • -0 uses only the “left” channel, which is fine since we need mono and NPR isn’t in stereo. (-m would mix down a stereo stream to mono.)
  • -s sends the data to STDOUT
  • http://nprdmp.ic.llnwd.net/stream/nprdmp_live01_mp3 is the URL for National Public Radio’s realtime MP3 stream.