Skip to main content

mod_shout

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/modules.conf.in source directory:

formats/mod_sndfile
formats/mod_shout    <--- NEW
#languages/mod_perl

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}'
/etc/freeswitch_

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://some.server.com/file.mp3", "")

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://scfire-dll-aa02.stream.aol.com:80/stream/1074"/>
  </condition>
</extension>


<extension name="moh_for_bridges">
  <condition field="destination_number" expression="^(15145555555)$">
   <action application="set" data="hold_music=shout://scfire-dll-aa01.stream.aol.com:80/stream/1018"/>
   <action application="bridge" data="sofia/default/$1@1.2.3.4"/>
  </condition>
</extension>
2.1.4.1 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"/>  
  </directory>
  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">  
  <settings>  
    <!-- Don't change these unless you are insane -->  
    <!--<param name="decoder" value="i586"/>-->  
    <param name="volume" value="0.7"/>  
    <!--<param name="outscale" value="8192"/>-->  
  </settings>  
</configuration>

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@10.10.10.10:8000/stream.mp3"/>

For conference, I do it from console:

conference 3001-10.10.10.10 record shout://source:pass@10.10.10.10:8000/stream.mp3