Skip to main content


Table of Contents (click to expand)

0. About

This module allows one to play local and remote MP3 files at any sample rate.

This module also needs to be built (see 1. Build mod_shout section below) and loaded (in modules.conf.xml, see Modules) for other facilities (such as mod_dptools: playback, mod_conference, etc.) to be able to handle MP3 files.

1. Build mod_shout

1.1 Install dependencies

  • libvorbis and development libraries
  • libogg and development libraries

On Debian:

apt-get install libvorbis0a libogg0 libogg-dev libvorbis-dev 

On CentOS 5.x:

yum install libvorbis libvorbis-devel libogg libogg-devel

On CentOS 6.x:

yum install libshout-devel lame-devel libmpg123-devel

1.2 Enable module in build

Remove hash tag (#) in build/ source directory:

formats/mod_shout <--- NEW

1.3 Configure and make

./configure && make install

1.4 Debugging

If mod_shout is not working, try the following:

TODO These instructions may be outdated. For example, libshout is only included under the win32 directory.

1.4.1 Configure libshout directly

Rather than relying on the overall configure script to invoke this, go to the src/lib/libshout directory and run configure directly. If you get an error like:

checking for libogg... not found
checking for VORBIS... checking for libvorbis... not found
configure: error: requisite Ogg Vorbis library not found

1.4.2 Delete lib directories

Also, try deleting both the libs/libshout-2.2.2 and libs/lame-3.97 directory and rerunning make.

2. Load mod_shout

2.1 Enable module in runtime

Edit conf/autoload_configs/modules.conf.xml :

    <load module="mod_native_file"/>
<!--For icecast/mp3 streams/files-->
<load module="mod_shout"/> <------- NEW

conf/ refers to the main FreeSWITCH configuration directory. To find its exact location on your system:

$ fs_cli -x 'eval $${conf_dir}'

2.2 Load the Module

From the CLI, run load mod_shout

3. Capabilities

2.1 Play

Fast Forward / Rewind bugs

Certain things, such as fast-forward and rewind, might not work, especially if the MP3 is "badly encoded".

If these features are needed, one thing to try is to decode the MP3 to a WAV, and re-encode it back to an MP3, in order to cleanse it of errors. If this still does not work, consider converting it to a WAV, and using it in that format.

See Playing/Recording External Media for instructions on how to play an MP3 file into a conference call.

2.1.1 Local MP3 Files

Can play local MP3 files at any sample rate (8khz, 16khz, 44.5khz) in mono/stereo. Re-sampling happens on the fly.

Re-sampling can be very CPU-expensive.

2.1.2 Remote MP3 Files

session.streamFile("shout://", "")

2.1.3 Icecast Streams

Can play icecast streams.

TODO Add example.

2.1.4 Shoutcast streams

<extension name="shout">
<condition field="destination_number" expression="^750$">
<action application="answer"/>
<action application="playback" data="shout://"/>

<extension name="moh_for_bridges">
<condition field="destination_number" expression="^(15145555555)$">
<action application="set" data="hold_music=shout://"/>
<action application="bridge" data="sofia/default/$1@"/>
</extension> Using shoutcast stream for music-on-hold (MOH)

To use shoutcast for MOH, do the following:

If you just use hold_music=shout://<url> , you will have issues after the first time you place the call on hold.

  1. Create a folder that contains a single file called something.loc with the URL of the shoutcast stream
    (e.g., shout://theserver:8111/the_stream.mp3)
  2. Edit conf/autoload_configs/local_stream.conf.xml to contain a stream that points to the folder you just created.
  <directory name="moh/shout" path="$${base_dir}/sounds/music/shout">  
<param name="rate" value="8000"/>
<param name="shuffle" value="true"/>
<param name="channels" value="1"/>
<param name="interval" value="10"/>
<param name="timer-name" value="soft"/>
  1. Set your hold_music variable to point to the local stream that you just created.
    That is, from the above example, it will be local_stream://moh/shout in this case.
  2. Tweak the volume parameters if the hold music is too loud via conf/autoload_configs/shout.conf
<configuration name="shout.conf" description="mod shout config">  
<!-- Don't change these unless you are insane -->
<!--<param name="decoder" value="i586"/>-->
<param name="volume" value="0.7"/>
<!--<param name="outscale" value="8192"/>-->

2.1.5 Using mod_shout for TTS with online services

Using mod_shout for TTS is not recommend in a live environment due to lack of caching.

See Via mod_shout using online TTS section in TTS for examples.

2.2 Record

Can record to

  • local MP3 files
  • icecast and/or shoutcast streams.

2.2.1 Recording to Icecast server

To record to Icecast server from your conference or your call:

<action application="record" data="shout://source:pass@"/>

For conference, I do it from console:

conference 3001- record shout://source:pass@