a4700ea47b20778e4d0161f8b3370920edf82986
[sip-router] / doc / seruser / voicemail.sgml
1 <para>
2         The voicemail system provides <application>ser</application>
3         with voice announcement and recording capabilities. Voice
4         messages may then be mailed to the called user. The system
5         relies on <application>ser</application> for implementing
6         the <acronym>SIP</acronym> stack and communicate with it
7         through <acronym>FIFO</acronym>. It implements the dialog and media
8         handling as described in RFC 3264 (An Offer/Answer Model with
9         the Session Description Protocol) and RFC 1889 (Real time
10         transport protocol) to realize its goal.
11
12 </para>
13 <section>
14 <title>Advantages</title>
15         <para>
16             Anyone deploying <application>ser</application> and
17             <acronym>VoIP</acronym> should profit from this 'ready-to-run'
18             application. It plugs into <application>ser</application> as
19             easy as configuring the database location, announce file path
20             and SMTP server address. 
21         </para>
22         <para>
23             Further,
24             <application>voicemail</application>
25             integrates the most popular free codecs
26             (G.711ulaw, G.711alaw and GSM 06.10) and
27             its own SMTP client, which means that you
28             don't need to install anything else as
29             <application>ser</application> and
30             <application>voicemail</application>. 
31         </para>
32         <para>
33             If you want your voicemail system to support
34             other codecs, a simple plugin system with
35             SDK alows you to integrate them fast and
36             simply (see the basis plugins for examples). 
37         </para>
38 </section>
39 <section>
40 <title>Technical limitations</title>
41         <para>
42             The sound conversion engine doesn't
43             support yet resampling. It means that
44             input and output files have to be
45             compatible with the sampling rate of the
46             codec. All codecs included with the
47             distribution work at 8kHz, which means
48             that all the input and output files MUST
49             be sampled at the rate of 8kHz.
50         </para>
51         <para>
52             At the moment, voicemail only support the
53             Microsoft Wav file format with PCM 16 bit,
54             Mu-law and A-law 8 bit encoding.
55         </para>
56 </section>
57
58
59 <section>
60 <title>Compilation and installation</title>
61         <para>
62             First, you need to compile Ser with voicemail
63             support. Therefore, you must edit Ser's
64             Makefile.defs file and uncomment the line with
65             '-DVOICE_MAIL' and '-D_TOTAG'.
66         </para>
67         <para>
68             Then do 'make all' in Ser's root directory.
69         </para>
70         <para>
71             Configure Ser to fit your needs. You can
72             report to voicemail example config file to
73             know what your configuration file should
74             include. Note that voicemail
75             only needs to know the user database location
76             in order to work. Report to the README file in
77             the vm module directory for description of the
78             functions and variable that are used by
79             voicemail and how they work.
80         </para>
81         <para>
82             Finally, compile the voicemail application:
83         </para>
84         <para>
85             <programlisting>
86                 [~/voicemail]$ cd ortp-0.5.0
87                 [~/voicemail/ortp-0.5.0]$ ./configure
88                 [~/voicemail/ortp-0.5.0]$ make all
89                 [~/voicemail/ortp-0.5.0]$ cd ..
90                 [~/voicemail]$ cd plug-in/gsm/gsm-????
91                 [~/voicemail/plug-in/gsm/gsm-????]$ make all
92                 [~/voicemail/plug-in/gsm/gsm-????]$ cd ../..
93                 [~/voicemail]$ make all
94             </programlisting>
95         </para>
96         <para>
97                 You can then start voicemail with following
98                 command <command>ans_machine</command> and
99                 look if the default fit your needs. If not,
100                 type <command>ans_machine -h</command> to see
101                 how to change the default parameters.
102         </para>
103         <para>
104                 If <application>ans_machine</application> is
105                 not started or can't be joined while
106                 <application>ser</application> tries to
107                 communicate with it, the caller will become
108                 a '500 internal server error' with a comment
109                 saying what the trouble is.
110         </para>
111         <example>
112                 <title>Example ser Config File</title>
113                 <programlisting>
114 &voicemailcfg;
115                 </programlisting>
116         </example>
117 </section>
118 <section>
119 <title>Availability, report bugs, contact the author</title>
120 <para>
121         Ser's Voicemail is hosted at
122         <ulink
123         url="http://developer.berlios.de/projects/sems">http://developer.berlios.de/projects/sems</ulink>.
124         A snapshot may be downloaded directly from the CVS tree. A
125         pre-configured version of <application>ser</application>
126         including <application>voicemail</application> will be soon
127         available (starting from version 0.8.11). 
128 </para>
129 <para>
130         Bugs can be directly reported at the voicemail's project page. If you
131         want to contact the author, use the contact email at the
132         project's web page.
133 </para>
134 </section>