7760aeee56a68b24a0b44f40ddfd0b1d2e177469
[sems] / README
1
2           +------------------------------------+
3           | SIP Express Media Server  - README |
4           +------------------------------------+
5
6
7 Introduction:
8
9  SEMS is a free, high performance, extensible media server 
10  for SIP (RFC3261) based VoIP services. 
11
12  It is intended to complement proxy/registrar servers
13  in VoIP networks for all applications where server-
14  side processing of audio is required, for example away 
15  or pre-call announcements, voicemail, or network side 
16  conferencing. Another use case is for interconnecting
17  SIP networks, where a back-to-back user agent (B2BUA)
18  is required.
19
20  SEMS can be used to implement simple high performance 
21  components like announcement servers as building 
22  blocks of more complex applications, or, using its powerful 
23  framework for application development including back-to-back 
24  user agent (B2BUA) and state machine scripting functionality, 
25  complex VoIP services can be realized completely in SEMS. 
26  
27  SEMS supports all important patent free codecs out of the
28  box (g711u, g711a, GSM06.10, speex, G.726, L16 and iLBC).
29  There is a wrapper for the IPP G.729 codec implementation
30  available. Integrating other codecs in SEMS is very simple
31  (patented or not).
32
33  SEMS shows very good performance on current standard
34  PC architecture based server systems. It has sucessfully
35  been run with 1200 G.711 conference channels on a quad-core
36  Intel(R) Xeon at 2GHz (700 GSM, 280 iLBC channels), and up to 
37  5000 channels on a dual quad Xeon at 2.9GHz. Its back-to-back
38  user agent has been run with up to 19000 TPS on the latter
39  machine. On the other hand it also runs on very small devices -
40  for example small embedded systems like routers running OpenWRT,
41  for which of course the achievable channel count is not that
42  high.
43
44 License:
45
46  SEMS is free (speech+beer) software. It is licensed under dual 
47  license terms, the GPL (v2+) and proprietary license. This
48  program is released under the GPL with the additional exemption
49  that compiling, linking, and/or using OpenSSL is allowed.
50
51  See doc/COPYING for details.
52
53 Applications:
54
55  The following applications are shipped with SEMS :
56
57  Announcements (Prompts, Ringbacktones, Pre-call-prompts):
58   * announcement   plays an announcement
59
60
61   * ann_b2b        pre-call-announcement, plays announcement 
62                    before connecting the callee in B2BUA mode
63  
64   * announce_transfer  pre-call-announcement, plays announcement 
65                    and then transfers the caller to the callee 
66                    using REFER
67
68   * early_announce (pre-call) announcement using early media (183),
69                    optionally continues the call in B2BUA mode
70
71   * precoded_announce plays preencoded announcements
72
73
74  Voicemail/Mailbox
75   * voicebox       users can dial in to the voicebox to check
76                    their messages
77
78   * annrecorder    users can record their personal greeting 
79                    message
80
81   * mailbox        auto-attendant that saves voicemails into
82                    an IMAP server. Users can dial in to check
83                    their messages (simpler version)
84
85   * voicemail      records voice messages and sends them 
86                    as email, saves them to a voicebox, or
87                    both
88
89
90  Conferencing
91
92   * conference     enables many people to talk together 
93                    at the same time
94
95   * webconference  conference application that can be 
96                    controlled from an external program, 
97                    e.g. a website 
98
99   * conf_auth      collect a PIN number, verify it against an 
100                    XMLRPC authentication server and connects in 
101                    B2BUA mode
102
103   * pin_collect    collect a PIN, optionally verify it, and transfer
104                    the call into a conference
105
106  Back-to-back User Agent
107   
108   * sbc            flexible SBC application, supports
109                     - identity change
110                     - header manipulation (filter etc)
111                     - (multihomed) RTP relay
112                     - SIP authentication 
113                     - Session timer, call timer, prepaid
114                     etc
115  App development
116
117   * dsm            DSM state machine scripting (use this)
118
119   * ivr            embedded Python interpreter for simple apps
120   
121   * py_sems        another embedded Python interpreter
122
123  Misc
124   * echo           test module to echo the caller's voice
125  
126
127   * callback       reject the call, call back caller later and have 
128                    her enter a number to call in b2bua with media relay
129                    mode
130
131   * reg_agent     SIP REGISTER to register SEMS' contact to an aor
132
133
134 Developing and customizing Applications and services:
135
136  SEMS comes with a set of example applications intended to help 
137  development of custom services, including a calling card 
138  application, a traffic generator, a component to control the 
139  media server via XMLRPC, and announcements played from DB.
140
141  DSM state machine scripting is a powerful yet simple method
142  to rapidly implement custom applications. With this method,
143  the service logic is written as an easy to understand 
144  textual definition of a state machine, which is interpreted
145  and executed for every call. The (domain specific) language 
146  for defining state machines can be extended by implementing
147  modules. A set of useful modules are shipped with SEMS, 
148  including MySQL database access module, Python module, 
149  conference support, Amazon AWS and more. 
150
151  SEMS' core implements basic call and audio processing, 
152  and loads plug-ins which extend the system. Audio
153  plug-ins enable new codecs and file formats, 
154  application plug-ins implement the services' logic.
155  Other modules called component modules provide 
156  functionality for other modules to use.
157
158  You can easily extend SEMS by creating your own plug-ins.
159  Applications can be written using the SEMS framework API 
160  in C++, or in Python using an embedded python interpreter 
161  of the ivr or py_sems modules, or the DSM.
162
163 Requirements:
164
165  All requirements are optional.
166
167  o Python version >= 2.3 for the ivr (embedded python interpreter)
168     and py_sems
169  o flite speech synthesizer for TTS in the ivr
170  o lame >= 3.95 for mp3 file output, mpg123 for mp3 playback
171  o spandsp library for DTMF detection and PLC
172     (SEMS has its own implementations for both)
173  o libZRTP SDK (http://zfoneproject.com) for ZRTP
174  o libev for jsonrpc
175
176 How to get started with SEMS:
177
178   To try out SEMS, the easiest is to get a release from 
179   http://ftp.iptel.org/pub/sems/, unpack and install it 
180   using the usual make && make install. After installation, the 
181   configuration file /usr/local/etc/sems/sems.conf needs to be 
182   adapted, especially the parameters "sip_ip", "media_ip",
183   "load_plugins", "application".
184
185   On Debian and Ubuntu, add the SEMS repository from OBS to 
186   /etc/apt/sources.list:
187      deb http://download.opensuse.org/repositories/home:/team-sems/Debian_5.0 ./
188   and install SEMS packages with: 
189    wget http://download.opensuse.org/repositories/home:/team-sems/Debian_5.0/Release.key \
190         -O - |apt-key add -   
191    apt-get update && apt-get install sems
192   If you want to build SEMS from source on debian/derivatives, see below.
193
194   On Fedora/CentOS, simply do 
195    $ sudo yum install sems
196   and sems package will be installed.
197  
198   You can also follow one of the tutorials linked from the SEMS homepage
199   (e.g. http://ftp.iptel.org/pub/sems/doc/current/howtostart_noproxy.html).
200   The Application Modules Documentation page then gives an 
201   overview of the application modules that come with SEMS 
202   (http://ftp.iptel.org/pub/sems/doc/current/AppDoc.html).
203   
204   If you are interested in writing your own applications, the 
205   application development tutorial is a good start 
206   (http://www.iptel.org/sems/sems_application_development_tutorial),
207   together with the design overview 
208   (http://www.iptel.org/files/semsng-designoverview.pdf) and the example
209   applications (apps/examples/).
210    
211   SEMS needs to be told from the many possible applications that are
212   loaded which one to run. You can simply set the application 
213   in sems.conf, e.g. application=conference. You can also define an
214   application mapping, i.e. numbers (R-URIs) that will be mapped to
215   applications, see the explanation of 'application' parameter in 
216   sems.conf.
217
218 Creating packages on debian (ubuntu, ...), here for wheezy:
219
220    install debian package build tools:
221    $ sudo apt-get install debhelper devscripts
222
223    install dependencies:
224    $  sudo apt-get install g++ make libspandsp-dev flite-dev libspeex-dev \
225          libssl-dev python-dev python-sip-dev openssl libev-dev \
226          libmysql++-dev libevent-dev libxml2-dev libcurl4-openssl-dev
227    
228    get the source: 
229    $ wget ftp.iptel.org/pub/sems/sems-x.y.z.tar.gz ; tar xzvf sems-x.y.z.tar.gz
230    or, for git master:
231    $ git clone git://git.sip-router.org/sems
232
233    $ cd sems-x.y.z ; ln -s pkg/deb/debian .
234
235    set version in changelog if not correct
236    $ dch -v x.y.z "SEMS x.y.z release"
237    or:
238    $ dch -b -v `git describe --always` "sems git master"
239    
240    build package:
241    $ dpkg-buildpackage -rfakeroot -us -uc
242
243    install sems and sems-python-modules packages in .. using dpkg.
244
245 Installed files using 'make install':
246
247     /usr/local/sbin/sems                 : SEMS executable
248     /usr/local/lib/sems/plug-in/*        : plug-ins
249     /usr/local/lib/sems/audio/*          : default path for audio files
250     /usr/local/lib/sems/ivr/*            : precompiled IVR scripts
251     /usr/local/etc/sems/sems.conf        : configuration file
252     /usr/local/etc/sems/etc/*            : modules configuration files
253     /usr/local/share/doc/sems/README     : this README.
254
255     source_path/scripts/sems[.redhat]    : example start-up scripts.
256     source_path/sems.conf.example        : example configuration file.
257
258 Documentation:
259
260   In the doc/ directory there is a set of files describing the
261   applications shipped with SEMS, alongside some more documentation.
262   Generate the doxygen documentation with 'make doc' in doc/doxygen_doc,
263   that contains all these files as well.
264
265   All this and more documentation is available online linked from 
266   the SEMS homepage: 
267     http://www.iptel.org/sems.
268
269 Support, mailing lists, bugs and contact:
270
271   Please have a look at the documentation and other information on 
272   the SEMS homepage (www.iptel.org/sems). 
273
274   Best-effort support is given through the mailing lists for SEMS,
275   sems@iptel.org and semsdev@iptel.org, which are the first address 
276   to ask for help, report bugs and improvements. You need to be 
277   subscribed to be able to post to the lists: http://lists.iptel.org.
278   The mailing list archives at   http://lists.iptel.org/pipermail/sems/ 
279   and http://lists.iptel.org/pipermail/semsdev/ can be a great help as
280   well (especially with google site search on lists.iptel.org, e.g.
281   http://www.google.com/coop/cse?cx=006590474108803368786%3A158hxzctv4u ). 
282
283   The bug tracker for SEMS is at http://tracker.iptel.org/browse/SEMS
284   Please submit all bugs, crashes and feature requests you encounter.
285
286 Authors:
287
288   Raphael Coeffic (rco@iptel.org), the father of SEMS, 
289   Stefan Sayer (stefan.sayer@gmail.com), current lead developer,
290   and all contributors:
291     Alex Gradinar
292     Alfred E Heggestad
293     Andreas Granig
294     Andrey Samusenko
295     Andriy I Pylypenko
296     Anton Zagorskiy
297     B. Oldenburg
298     Balint Kovacs
299     Bogdan Pintea
300     Greger Viken Teigre
301     Grzegorz Stanislawski
302     Helmut Kuper
303     Jeremy A
304     Jiri Kuthan
305     Juha Heinanen
306     Matthew Williams
307     Ovidiu Sas
308     Peter Lemenkov
309     Peter Loeppky
310     Richard Newman
311     Robert Szokovacs
312     Rui Jin Zheng
313     Tom van der Geer
314     Ulrich Abend
315    (if you feel you should be on this list, please mail to stefan.sayer@gmail.com)
316  
317   Special thanks to IPTEGO GmbH, iptelorg GmbH and TelTech Systems Inc. for 
318   sponsoring development of SEMS.
319
320 Contributions:
321
322   All kinds of contributions and bug fixes are very welcome, for 
323   example new application or codec modules, documentation pages, howtos
324   etc. Please email one of the lists or the authors.
325
326   Please also have a look at the contributions license policy 
327   (see doc/COPYING).
328   
329 SEMS - the media-S in the SLAMP.