About

This module allow one to play local and remote mp3 files at any sample rate.

Click here to expand ToC

- 1.1Configure and Install
2Overview
- 2.1Play Capabilities
  - 2.1.1Using shoutcast stream for MOH
  - 2.1.2Using mod_shout for TTS with online services
  - 2.1.3Record Capabilities
- 2.2Caveats
  - 2.2.1Fast Forwarding / Rewind Bugs
  - 2.2.2Enable module in runtime
  - 2.2.3Load the Module
  - 2.2.4Verifying
  - 2.2.5Debugging Problems
- 2.3Recording to Icecast server

Configure and Install

Install Dependencies

libvorbis
libogg
development libraries for both

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

Enable module in build.

Edit modules.conf in source directory to add mod_shout.

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

Configure/Make:

./configure && make install

Overview

Play Capabilities

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. (note: re-sampling can be expensive for the CPU)

Remote MP3 Files

session.streamFile("shout://some.server.com/file.mp3", "")

Icecast Streams

Can play icecast streams. TODO: example

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 
            > 
           

Using shoutcast stream for MOH

To use shoutcast for moh you have to do three things.

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

You have to create a folder that contains a single file called "something.loc" with the url of the shoutcast stream. (shout://theserver:8111/the_stream.mp3)
You have to edit "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>

You have to set your "hold_music" variable to point to the local_stream that you just created. In this case that would be local_stream://moh/shout.

You may have to tweak the volume parameters if the hold music is too loud via 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>

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. For setup examples see http://wiki.freeswitch.org/wiki/Category:TTS#Via_mod_shout_using_online_TTS

Record Capabilities

Can record to local MP3 files.

Can record to icecast and/or shoutcast streams.

Caveats

Fast Forwarding / Rewind Bugs

Certain things like fast-forwarding and rewinding might not work especially if the mp3 is "badly encoded". If you need those features, one thing to try is to decode the mp3 to a wave, 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 wave and using it in that format.

Enable module in runtime

Edit /usr/local/freeswitch/conf/autoload_configs/modules.conf.xml to add mod_shout to the list.

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

Load the Module

from the CLI, run "load mod_shout"

Verifying

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

Debugging Problems

If its not working, try the following:

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

Delete lib directories

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

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

mod_shout