Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjmedia / include / pjmedia / doxygen.h
1 /* $Id$ */
2 /* 
3  * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4  * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
5  *
6  * This program is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software
18  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
19  */
20 #ifndef __PJMEDIA_DOXYGEN_H__
21 #define __PJMEDIA_DOXYGEN_H__
22
23 /**
24  * @file doxygen.h
25  * @brief Doxygen's mainpage.
26  */
27
28
29 /*////////////////////////////////////////////////////////////////////////// */
30 /*
31         INTRODUCTION PAGE
32  */
33
34 /**
35  * @mainpage PJMEDIA
36  *
37  * \n
38  * @section intro2 Introduction to PJMEDIA
39  *
40  * PJMEDIA is a fully featured media stack, distributed under Open Source/GPL
41  * terms, and featuring small footprint and good extensibility and excellent
42  * portability. Here are some brief overview of PJMEDIA benefits.
43  *
44  * @subsection benefit Benefits
45  * @subsubsection full_feature Many Features
46  * PJMEDIA has many features, and rather than to list them all here, please
47  * see the <A HREF="modules.htm"><b>Modules</b></A> page for more info.
48  *
49  * Video is planned to arrive at version 2.
50  *
51  * @subsubsection portable Excellent Portability
52  * It's been ported to all desktop systems and many mobile platforms including
53  * Symbian, Windows Mobile, iPhone, and Android. Thanks to its zero thread
54  * design, users have been able to run PJMEDIA on deeply embedded platforms,
55  * even without operating systems (those typically found in DSP platforms).
56  * Except the echo suppressor, all other PJMEDIA components have fixed point
57  * implementation, which makes it ideal for embedded systems which lack FPU.
58  * PJMEDIA also has tiny footprint, as explained below
59  *
60  * @subsubsection footprint Tiny Footprint
61  * Lets not talk about less meaningful and potentially misleading term such as
62  * core footprint, and instead here is the footprint of all components
63  * typically used to build a full streaming media:
64  *
65  * \verbatim
66 Category        Component       text    data    bss     dec     filename
67 -------------------------------------------------------------------------------
68 Core            Error subsystem 135     0       0       135     errno.o
69 Core            Endpoint        4210    4       4       4218    endpoint.o
70 Core            Port framework  652     0       0       652     port.o
71 Core            Codec framework 6257    0       0       6257    codec.o
72 Codec           Alaw/ulaw conv. 1060    16      0       1076    alaw_ulaw.o
73 Codec           G.711           3298    128     96      3522    g711.o
74 Codec           PLC             883     24      0       907     plc_common.o
75 Codec           PLC             7130    0       0       7130    wsola.o
76 Session         Stream          12222   0       1920    14142   stream.o
77 Transport       RTCP            3732    0       0       3732    rtcp.o
78 Transport       RTP             2568    0       0       2568    rtp.o
79 Transport       UDP             6612    96      0       6708    transport_udp.o
80 Transport       Jitter buffer   6473    0       0       6473    jbuf.o
81 -------------------------------------------------------------------------------
82 TOTAL                          55,232   268    2,020    57,520
83
84  \endverbatim
85  * The 56KB are for media streaming components, complete with codec, RTP, and
86  * RTCP. The footprint above was done for PJSIP version 1.8.2 on a Linux x86
87  * machine, using footprintopimization as explained in PJSIP FAQ. Numbers are
88  * in bytes.
89  *
90  * @subsubsection quality Good Quality
91  * PJMEDIA supports wideband, ultra-wideband, and beyond, as well as multiple
92  * audio channels. The jitter buffer has been proven to work on lower
93  * bandwidth links such as 3G, and to some extent, Edge and GPRS. We've grown
94  * our own algorithm to compensate for packet losses and clock drifts in audio
95  * transmission, as well as feature to use codec's built in PLC if available.
96  *
97  * @subsubsection hw Hardware Support
98  * PJMEDIA supports hardware, firmware, or other built-in feature that comes
99  * with the device. These are crucial for mobile devices to allow the best
100  * use of the very limited CPU and battery power of the device. Among other
101  * things, device's on-board codec and echo cancellation may be used if
102  * available.
103  *
104  * @subsubsection extensible Extensible
105  * Despite its tiny footprint, PJMEDIA uses a flexible port concept, which is
106  * adapted from filter based concept found in other media framework. It is not
107  * as flexible as those found in Direct Show or gstreamer (and that would be
108  * unnecessary since it serves different purpose), but it's flexible enough
109  * to allow components to be assembled one after another to achieve certain
110  * task, and easy creation of such components by application and interconnect
111  * them to the rest of the framework.
112  *
113  * @subsubsection doc (Fairly Okay) Documentation
114  * We understand that any documentation can always be improved, but we put
115  * a lot of efforts in creating and maintaining our documentation, because
116  * we know it matters.
117  *
118  * \n
119  * @subsection org1 Organization
120  *
121  * At the top-most level, PJMEDIA library suite contains the following
122  * libraries.
123  *
124  * @subsubsection libpjmedia PJMEDIA
125  * This contains all main media components. Please see the
126  * <A HREF="modules.htm"><b>Modules</b></A> page for complete list of
127  * components that PJMEDIA provides.
128  *
129  * @subsubsection libpjmediacodec PJMEDIA Codec
130  * PJMEDIA-CODEC is a static library containing various codec implementations,
131  * wrapped into PJMEDIA codec framework. The static library is designed as
132  * such so that only codecs that are explicitly initialized are linked with 
133  * the application, therefore keeping the application size in control.
134  *
135  * Please see @ref PJMEDIA_CODEC for more info.
136  *
137  * @subsubsection libpjmediaaudiodev PJMEDIA Audio Device
138  * PJMEDIA-Audiodev is audio device framework and abstraction library. Please
139  * see @ref audio_device_api for more info.
140  *
141  * \n
142  * @section pjmedia_concepts PJMEDIA Key Concepts
143  * Below are some key concepts in PJMEDIA:
144  *  - @ref PJMEDIA_PORT
145  *  - @ref PJMEDIA_PORT_CLOCK
146  *  - @ref PJMEDIA_TRANSPORT
147  *  - @ref PJMEDIA_SESSION
148  */
149
150
151 /**
152   @page page_pjmedia_samples PJMEDIA and PJMEDIA-CODEC Examples
153
154   @section pjmedia_samples_sec PJMEDIA and PJMEDIA-CODEC Examples
155
156   Please find below some PJMEDIA related examples that may help in giving
157   some more info:
158
159   - @ref page_pjmedia_samples_level_c\n
160     This is a good place to start learning about @ref PJMEDIA_PORT,
161     as it shows that @ref PJMEDIA_PORT are only "passive" objects
162     with <tt>get_frame()</tt> and <tt>put_frame()</tt> interface, and
163     someone has to call these to retrieve/store media frames.
164
165   - @ref page_pjmedia_samples_playfile_c\n
166     This example shows that when application connects a media port (in this
167     case a @ref PJMEDIA_FILE_PLAY) to @ref PJMED_SND_PORT, media will flow
168     automatically since the @ref PJMED_SND_PORT provides @ref PJMEDIA_PORT_CLOCK.
169
170   - @ref page_pjmedia_samples_recfile_c\n
171     Demonstrates how to capture audio from microphone to WAV file.
172
173   - @ref page_pjmedia_samples_playsine_c\n
174     Demonstrates how to create a custom @ref PJMEDIA_PORT (in this
175     case a sine wave generator) and integrate it to PJMEDIA.
176
177   - @ref page_pjmedia_samples_confsample_c\n
178     This demonstrates how to use the @ref PJMEDIA_CONF. The sample program can 
179     open multiple WAV files, and instruct the conference bridge to mix the
180     signal before playing it to the sound device.
181
182   - @ref page_pjmedia_samples_confbench_c\n
183     I use this to benchmark/optimize the conference bridge algorithm, but
184     readers may find the source useful.
185
186   - @ref page_pjmedia_samples_resampleplay_c\n
187     Demonstrates how to use @ref PJMEDIA_RESAMPLE_PORT to change the
188     sampling rate of a media port (in this case, a @ref PJMEDIA_FILE_PLAY).
189
190   - @ref page_pjmedia_samples_sndtest_c\n
191     This program performs some tests to the sound device to get some
192     quality parameters (such as sound jitter and clock drifts).\n
193     Screenshots on WinXP: \image html sndtest.jpg "sndtest screenshot on WinXP"
194
195   - @ref page_pjmedia_samples_streamutil_c\n
196     This example mainly demonstrates how to stream media (in this case a
197     @ref PJMEDIA_FILE_PLAY) to remote peer using RTP.
198
199   - @ref page_pjmedia_samples_siprtp_c\n
200     This is a useful program (integrated with PJSIP) to actively measure 
201     the network quality/impairment parameters by making one or more SIP 
202     calls (or receiving one or more SIP calls) and display the network
203     impairment of each stream direction at the end of the call.
204     The program is able to measure network quality parameters such as
205     jitter, packet lost/reorder/duplicate, round trip time, etc.\n
206     Note that the remote peer MUST support RTCP so that network quality
207     of each direction can be calculated. Using siprtp for both endpoints
208     is recommended.\n
209     Screenshots on WinXP: \image html siprtp.jpg "siprtp screenshot on WinXP"
210
211   - @ref page_pjmedia_samples_tonegen_c\n
212     This is a simple program to generate a tone and write the samples to
213     a raw PCM file. The main purpose of this file is to analyze the
214     quality of the tones/sine wave generated by PJMEDIA tone/sine wave
215     generator.
216
217   - @ref page_pjmedia_samples_aectest_c\n
218     Play a file to speaker, run AEC, and record the microphone input
219     to see if echo is coming.
220  */
221
222 /**
223  * \page page_pjmedia_samples_siprtp_c Samples: Using SIP and Custom RTP/RTCP to Monitor Quality
224  *
225  * This source is an example to demonstrate using SIP and RTP/RTCP framework
226  * to measure the network quality/impairment from the SIP call. This
227  * program can be used to make calls or to receive calls from other
228  * SIP endpoint (or other siprtp program), and to display the media
229  * quality statistics at the end of the call.
230  *
231  * Note that the remote peer must support RTCP.
232  *
233  * The layout of the program has been designed so that custom reporting
234  * can be generated instead of plain human readable text.
235  *
236  * The source code of the file is pjsip-apps/src/samples/siprtp.c
237  *
238  * Screenshots on WinXP: \image html siprtp.jpg
239  *
240  * \includelineno siprtp.c
241  */
242
243 #endif /* __PJMEDIA_DOXYGEN_H__ */
244