Page tree
Skip to end of metadata
Go to start of metadata


The Music on Hold module is intended to reassure callers that they are still connected to their calls. The PBX comes with 11 built in songs that are the default hold music. You can easily add your own music or sound files to the system by uploading them in .wav or .mp3 format, or stream a live feed. Adding custom music on hold is a great way to bring personality to your phone system. The PBX allows two styles of music on hold – static files and streaming. Static files are audio files (WAV or MP3 files) that are uploaded to the server and played back when a caller is placed on hold. Streaming audio is used to connect to a live audio feed from a particular source. This could be an Internet stream, or a stream from a sound card or other audio device. MoH categories can be applied to inbound routes as well as to queues, ring groups, outbound routes and conferences. Categories assigned at the call level will override the MOH category for that target only. Once a call leaves that target, it will fall back into the category specified in the inbound route it was matched against.

Licensing Considerations

In the past, it was common to plug a radio or CD player into your phone system. In reality, most copyright and music licenses do not actually allow you to do this. There are two legal ways to acquire music on hold content – pay for a license from the copyright holder or find a source of music released under a license suitable for your PBX. We are not providing legal advice; you are responsible for understanding what is required of you in order to use a particular piece of music as your hold source.

BMI - MoH Licencing

ASCAP - MoH Licencing

Creative Commons Search on Sound Cloud

Note: that soundcloud depends on user honesty. Users without license to do so may upload content under a different license. When using sites like this it may be a good idea to verify the uploader is the actual content creator.

Logging In

  • From the top menu click Settings
  • In the drop down click Music on Hold

Adding Music Categories

The PBX has one category, which is “default.” You can create additional categories by clicking on the “Add Music Category” in the top right hand side of the screen.

You will be brought to the following

Category Name

Enter a category name, then submit changes to save your new category.

Adding Static Music

In the right side navigation menu click the category you wish to add music to.

Upload a WAV or MP3 File

Here you can use the file section box to upload a WAV or MP3 from your computer.

You will click Choose File

You will then be prompted to specify the location on your local computer where the sound file is located. Depending on your browser, you may be able to drag and drop the file directly to the “Choose File” box.

Volume Adjustment

Here you can increase or decrease the volume of this specific MoH file before uploading it. Once the file has been uploaded, you cannot make changes to the volume without deleting the file and uploading it again with the adjusted levels.


Press this button to actually upload your MoH file. If you’re uploading an MP3 file, you will need to wait for the page to completely load after submitting because the system is converting the MP3 to WAV format.

Disable/Enable Random Play

Selecting this option will either toggle random play on or off. Random play picks a random file each time to play when a caller is put in the MoH category. Disabling random play will have each caller start with the first MoH file and work their way down the list in the order in which they are uploaded.

MoH List

A list of MoH files in this category. You can click the red “Delete” button on the right of each file to remove a specific MoH file.

Adding Streaming Music

Streaming categories can be used to capture audio from a line-in or an online audio stream.

Using an audio stream for MoH is more complicated than using static audio files and the results can be unpredictable depending on the source and type of the stream.


The instructions are provided as a how-to only, not as a recommendation for use.

Category Name

Category name for this streaming category.

Application path

This can be used to define an online stream or map to a script for use with a line-in port on a sound card.

Application example:
/usr/bin/mpg123 -q -s --mono -r 8000 -f 8192 -b 1024 http://urlofyourlivestream/

Optional Format

Format, such as “ULAW,” that the PBX will use for this stream.

Streaming MoH can negatively impact the performance of the PBX due to bandwidth usage or transcoding issues. Multiple callers placed on hold will be connecting to the same stream and each streaming class should be streamed only once at any given time. If multiple streams are created, it is possible for them to be active at the same time. PBX requires that the stream be in ULAW format, so calls already using this codec will be able to listen to the stream without any transcoding. A call that is using a different codec, such as G.722, would force the stream to be transcoded for the caller to hear it. This places a processing load on the PBX and may require additional licenses for the concurrent caller if using a licensed codec. It may be beneficial to avoid streaming MoH for system performance issues. Unless you are streaming audio on your private LAN, the streaming audio will be using the same bandwidth that you need to support incoming and outgoing calls. Anything streamed over 24k is a waste of bandwidth.

Additional notes

Incorrect streaminig sources or settings in the MoH custom application can cause increased warning messages in asterisk CLI as well as in the full log. Messages have a format similar to this one

[2017-10-19 12:10:42] WARNING[19746]: res_musiconhold.c:719 monmp3thread: poll() failed: Interrupted system call

Removing streams with invalid URLs, IPs pointing to un-existent resourece will stop these messages from appearing and filling btoh CLI and full log. 


  • No labels

1 Comment

  1. It would be very beneficial to have more elaboration on the streaming statement format. Each of the groups of information should have a statement of reason for inclusion and range of effect or options to choose from. The http: statement would be great if it included some description and examples that come from the real world. One item missing is the port number of the protocol stream.