Freeswitch Module

Revision as of 06:56, 13 November 2010

 

Home

 

Download

 

News

 

Support

 

Admin

 

Dev

 

Screen Shots

 

Grid List

 

Bugs

Languages:

English    Deutsch    Français

The FreeSWITCH module enables voice in OpenSim with no changes required to the Linden Labs Second Life viewer (must be between 1.22 and 1.23.5 - 2.x viewers do not work at present), Hippo viewer (0.5 or after), and perhaps others using SLvoice.exe module.

A little history on the development of the FreeSWITCH module is given here:

• http://zaki.asia/2009/04/28/freeswitch-module-in-opensim/

FreeSwitch Install

Follow the instructions here on how to compile from source. We need to enable two specific modules. Please ensure you compile from the freeswitch trunk for now until we can post a minimum version number (there are known issues with older versions)

When you get to the part in the instructions where it says "Edit modules.conf so that it will build the modules you desire." edit the modules.conf file and uncomment to make active the entries for xml_curl and the siren14 codec

   codecs/mod_siren
 and
 xml_int/mod_xml_curl

• You can also use this guide for setting it up in a quick way -- Fly-man-

FreeSwitch Config

Install and compile Freeswitch, making sure you enable the xml_curl module and also the siren14 codec.

enable mod_xml_curl

Next, do not forget to activate mod_xml_curl in /usr/local/freeswitch/conf/autoload_configs/modules.conf.xml. mod_xml_curl is disabled by default on fresh install.

uncomment the lines...

   <load module="mod_xml_curl"/>

and

   <load module="mod_siren"/>

configure mod_xml_curl

mod_xml_curl is a freeswitch module which enables dynamic configuration of freeswitch from a web server. In this case, it is the opensim region server.

The xml_curl module configuration should point to an opensim region that has the Freeswitch voice module enabled (voice also needs to be enabled in the estate setting for all regions you wish to be supported).

example xml_curl.conf.xml found in /usr/local/freeswitch/conf/autoload_configs

 <configuration name="xml_curl.conf" description="cURL XML Gateway">
<bindings>
   <binding name="example">
           <param name="gateway-url" value="http://youropensimregionip:9000/api/freeswitch-config" bindings="directory"/>
           <param name="gateway-credentials" value="freeswitch:password"/>
           <param name="disable-100-continue" value="true"/>
   </binding>
   <binding name="local">
           <param name="gateway-url" value="http://youropensimregionip:9000/api/freeswitch-config" bindings="dialplan"/>
           <param name="gateway-credentials" value="freeswitch:password"/>
           <param name="disable-100-continue" value="true"/>
   </binding>
</bindings>
</configuration>

This configuration instructs freeswitch to obtain the "dialplan" and "directory" configuration from opensim (as mentioned by the bindings attributes). For the rest of the configuration, freeswitch will consult it's static xml files. More details on mod_xml_curl module can be found here.

The /usr/local/freeswitch/conf/vars.xml requires modification to enable the siren14 codec

search within vars.xml for the global_codec_prefs and change the line to read

   <X-PRE-PROCESS cmd="set" data="global_codec_prefs=G7221@32000h,G722,PCMU,PCMA,GSM"/> 

or

   <X-PRE-PROCESS cmd="set" data="global_codec_prefs=G7221@32000h,G7221@16000h,G722,PCMU,PCMA,GSM"/>

G7221@32000h is the siren14 codec

configure conference.conf.xml

By default, FreeSwitch plays hold music when there is only one avatar in the conference and beeps for everyone when avatars arrive and leave. To disable, edit /usr/local/freeswitch/conf/autoload_configs/conference.conf.xml. Locate the "default" profile and comment out the following lines as shown below:

      [...]
    <!-- File to play if you are alone in the conference -->
    <!-- <param name="alone-sound" value="conference/conf-alone.wav"/> -->
    [...]
    <!-- File to play when you're alone (music on hold)-->
    <!-- <param name="moh-sound" value="$${hold_music}"/> -->
    <!-- File to play when you join the conference -->
    <!-- <param name="enter-sound" value="tone_stream://%(200,0,500,600,700)"/> [^] -->
    <!-- File to play when you leave the conference -->
    <!-- <param name="exit-sound" value="tone_stream://%(500,0,300,200,100,50,25)"/> [^] -->
    <!-- File to play when you ae ejected from the conference -->
    <!-- <param name="kicked-sound" value="conference/conf-kicked.wav"/> -->
    [...]

OpenSim Config

Add the following section to OpenSim.ini. You will also need to enable voice in the regions estate settings. Make sure the freeswitch server is started BEFORE bringing the region up.

   [FreeSwitchVoice]
 enabled = true
 ; FreeSwitch server is going to contact us and ask us all sorts of things.
 freeswitch_server_user = freeswitch
 freeswitch_server_pass = password
 freeswitch_api_prefix = /api
 ; IP address of an opensim region with voice enabled
 freeswitch_service_server = youropensimregionip
 ; the port your Opensim region is running on
 freeswitch_service_port = 9000 
 ; your freeswitch IP address
 freeswitch_realm = yourfreeswitchserverip
 freeswitch_sip_proxy = yourfreeswitchserverip:5060
 ; STUN = Simple Traversal of UDP through NATs
 ; See http://wiki.freeswitch.org/wiki/NAT_Traversal
 freeswitch_attempt_stun = false
 freeswitch_stun_server = stun.freeswitch.org
 ; Echo server MAY not used but information MAY be
 ; required to relay to Freeswitch server (TBC?)
 freeswitch_echo_server = yourfreeswitchserverip
 freeswitch_echo_port = 50505
 freeswitch_well_known_ip = yourfreeswitchserverip
 freeswitch_default_timeout = 5000
 freeswitch_subscribe_retry = 120
 ; freeswitch_password_reset_url =
 ; opensim_well_known_http_address = youropensimregionip
 ; CHECK THIS...  should be Address_Of_Your_SIM_HTTP_Server_Hostname_Allowed

Note that if you are running in Opensim grid mode, a single Freeswitch service on yourfreeswitchserverip can support multiple regions on one or more Opensim.exe running on one or more hosts. And the Freeswitch server need not be on the same host as the Opensim.exe used to anchor the connection.

Note STUN server "stun.freeswitch.org" is an example only, and its availability should not be relied upon for a service.

Firewall Config

Make sure that the ports used by Freeswitch are acessible though your firewall(s). In the example above the main port used is 5060 though other ports may be used for call initiation (port 1720 for H.323 Call Signaling) and dynamically assigned ports for specific call traffic. The usual H.323 and SIP traffic dynamic port handling on modern firewalls usually enables this.

Is port 50505 actually used, or is it just something that must be
reported by OpenSim when the Freeswitch service makes contact?

More details on the Freeswitch ports used and firewall configuration details are at http://wiki.freeswitch.org/wiki/Firewall

If you have problems with NAT/Routers look at using STUN (Simple Traversal of UDP through NATs). More information at http://wiki.freeswitch.org/wiki/NAT_Traversal

Issues & Solutions

NOTE: FreeSwitch is not a core module and help may not be forthcoming to handle issues.

MAKE SURE the OpenSim region you point Freeswitch at IS NOT running when you start FreeSwitch.

ALSO make sure that you have enabled voice in the "About Land"->"Voice" dialogue in the region, you will need to be a region admin to do this.

Check the plot also has voice enabled. You must be a plot owner or have suitable permisison to do this. Recent Linden Labs Second Life viewers do not offer this option, so use Hippo or another client which does.

Notes from Openvue Grid setup for FreeSwitch

Additional notes that might help:

1. We established a simple OpenSim.exe on the SAME host as the FreeSwitch.exe service and put a single simple island on that (we called it "Talk") as some folks observed that FreeSwitch had problems with connecting for its CONFIGURED server lin to another server, and use THAT OpenSim.exe instance for the config setup with FreeSwitch.. not the main regions we run on other servers.

2. FreeSwitch provides service to all OpenSim.ex instances on any servers you wish even though its only configured fro one.

3. There is one FreeSwitch channel per region, change regions and you change channel. So all users to talk must be on the same region. Plots on one region share the region channel we think.

4. You appear as one user in the SL Viewers, AL other users appear as a single "user" with a coded name for the channel.

5. You must have voice enabled at the region, AND the plot level. This is a pain, as the default setting in OpenSim is that PLOTS have voice turned off. The standard viewers 1.23 and 2.x do not allow you to turn this back on, so you must use a third party viewer to turn on PLOT voice. I have asked before that we change the default setting when a plot is created to have this on by default (or on if the region voice is on- which it is by default).

6. You definitely MUST start FreeSwitch.exe before the regions that you want voice to work on. It works fine over restarts without FreeSwitch being started again.

7. Remember to configure for EXTERNALLY accessible IP addressed. Use IP numbers fro FreeSwitch... and if there are 192.168.x.x style local net addresses in there you will not get FreeSwitch to work with external users.

8. There are some red errors on startup of FreeSwitch as noted by gregor.. at least in our setup which appears to be related to a missing config file that FreeSwitch tries to retrieve from OpenSim (opensim-region-server-url:port/api/freeswitch-config) that is not in the OpenSim setup... We have (safely?) ignored those without problems...

2010-11-13 14:42:55.252361 [ERR] mod_xml_curl.c:252 Received HTTP error 0 trying
to fetch http://129.215.219.143:9000/api/freeswitch-config
data: [hostname=shuna&section=directory&tag_name=domain&key_name=name&key_value=
129.215.219.143&Event-Name=GENERAL&Core-UUID=cb64ea40-aa92-494b-be13-65d9c468efe
c&FreeSWITCH-Hostname=shuna&FreeSWITCH-IPv4=129.215.219.143&FreeSWITCH-IPv6=2002
%3A81d7%3Adb8f%3A%3A81d7%3Adb8f&Event-Date-Local=2010-11-13%2014%3A42%3A54&Event
-Date-GMT=Sat,%2013%20Nov%202010%2014%3A42%3A54%20GMT&Event-Date-Timestamp=12896
59374247361&Event-Calling-File=switch_core.c&Event-Calling-Function=switch_load_
network_lists&Event-Calling-Line-Number=984&domain=129.215.219.143&purpose=network-list]