Tristan Matthews | 0a329cc | 2013-07-17 13:20:14 -0400 | [diff] [blame] | 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 | |