D-Modem/pjproject-2.11.1/pjmedia/include/pjmedia/doxygen.h
2021-10-29 14:41:03 -04:00

244 lines
10 KiB
C

/* $Id$ */
/*
* Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
* Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
#ifndef __PJMEDIA_DOXYGEN_H__
#define __PJMEDIA_DOXYGEN_H__
/**
* @file doxygen.h
* @brief Doxygen's mainpage.
*/
/*////////////////////////////////////////////////////////////////////////// */
/*
INTRODUCTION PAGE
*/
/**
* @mainpage PJMEDIA
*
* \n
* @section intro2 Introduction to PJMEDIA
*
* PJMEDIA is a fully featured media stack, distributed under Open Source/GPL
* terms, and featuring small footprint and good extensibility and excellent
* portability. Here are some brief overview of PJMEDIA benefits.
*
* @subsection benefit Benefits
* @subsubsection full_feature Many Features
* PJMEDIA has many features, and rather than to list them all here, please
* see the <A HREF="modules.htm"><b>Modules</b></A> page for more info.
*
* Video is planned to arrive at version 2.
*
* @subsubsection portable Excellent Portability
* It's been ported to all desktop systems and many mobile platforms including
* Symbian, Windows Mobile, iPhone, and Android. Thanks to its zero thread
* design, users have been able to run PJMEDIA on deeply embedded platforms,
* even without operating systems (those typically found in DSP platforms).
* Except the echo suppressor, all other PJMEDIA components have fixed point
* implementation, which makes it ideal for embedded systems which lack FPU.
* PJMEDIA also has tiny footprint, as explained below
*
* @subsubsection footprint Tiny Footprint
* Lets not talk about less meaningful and potentially misleading term such as
* core footprint, and instead here is the footprint of all components
* typically used to build a full streaming media:
*
* \verbatim
Category Component text data bss dec filename
-------------------------------------------------------------------------------
Core Error subsystem 135 0 0 135 errno.o
Core Endpoint 4210 4 4 4218 endpoint.o
Core Port framework 652 0 0 652 port.o
Core Codec framework 6257 0 0 6257 codec.o
Codec Alaw/ulaw conv. 1060 16 0 1076 alaw_ulaw.o
Codec G.711 3298 128 96 3522 g711.o
Codec PLC 883 24 0 907 plc_common.o
Codec PLC 7130 0 0 7130 wsola.o
Session Stream 12222 0 1920 14142 stream.o
Transport RTCP 3732 0 0 3732 rtcp.o
Transport RTP 2568 0 0 2568 rtp.o
Transport UDP 6612 96 0 6708 transport_udp.o
Transport Jitter buffer 6473 0 0 6473 jbuf.o
-------------------------------------------------------------------------------
TOTAL 55,232 268 2,020 57,520
\endverbatim
* The 56KB are for media streaming components, complete with codec, RTP, and
* RTCP. The footprint above was done for PJSIP version 1.8.2 on a Linux x86
* machine, using footprintopimization as explained in PJSIP FAQ. Numbers are
* in bytes.
*
* @subsubsection quality Good Quality
* PJMEDIA supports wideband, ultra-wideband, and beyond, as well as multiple
* audio channels. The jitter buffer has been proven to work on lower
* bandwidth links such as 3G, and to some extent, Edge and GPRS. We've grown
* our own algorithm to compensate for packet losses and clock drifts in audio
* transmission, as well as feature to use codec's built in PLC if available.
*
* @subsubsection hw Hardware Support
* PJMEDIA supports hardware, firmware, or other built-in feature that comes
* with the device. These are crucial for mobile devices to allow the best
* use of the very limited CPU and battery power of the device. Among other
* things, device's on-board codec and echo cancellation may be used if
* available.
*
* @subsubsection extensible Extensible
* Despite its tiny footprint, PJMEDIA uses a flexible port concept, which is
* adapted from filter based concept found in other media framework. It is not
* as flexible as those found in Direct Show or gstreamer (and that would be
* unnecessary since it serves different purpose), but it's flexible enough
* to allow components to be assembled one after another to achieve certain
* task, and easy creation of such components by application and interconnect
* them to the rest of the framework.
*
* @subsubsection doc (Fairly Okay) Documentation
* We understand that any documentation can always be improved, but we put
* a lot of efforts in creating and maintaining our documentation, because
* we know it matters.
*
* \n
* @subsection org1 Organization
*
* At the top-most level, PJMEDIA library suite contains the following
* libraries.
*
* @subsubsection libpjmedia PJMEDIA
* This contains all main media components. Please see the
* <A HREF="modules.htm"><b>Modules</b></A> page for complete list of
* components that PJMEDIA provides.
*
* @subsubsection libpjmediacodec PJMEDIA Codec
* PJMEDIA-CODEC is a static library containing various codec implementations,
* wrapped into PJMEDIA codec framework. The static library is designed as
* such so that only codecs that are explicitly initialized are linked with
* the application, therefore keeping the application size in control.
*
* Please see @ref PJMEDIA_CODEC for more info.
*
* @subsubsection libpjmediaaudiodev PJMEDIA Audio Device
* PJMEDIA-Audiodev is audio device framework and abstraction library. Please
* see @ref audio_device_api for more info.
*
* \n
* @section pjmedia_concepts PJMEDIA Key Concepts
* Below are some key concepts in PJMEDIA:
* - @ref PJMEDIA_PORT
* - @ref PJMEDIA_PORT_CLOCK
* - @ref PJMEDIA_TRANSPORT
* - @ref PJMEDIA_SESSION
*/
/**
@page page_pjmedia_samples PJMEDIA and PJMEDIA-CODEC Examples
@section pjmedia_samples_sec PJMEDIA and PJMEDIA-CODEC Examples
Please find below some PJMEDIA related examples that may help in giving
some more info:
- @ref page_pjmedia_samples_level_c\n
This is a good place to start learning about @ref PJMEDIA_PORT,
as it shows that @ref PJMEDIA_PORT are only "passive" objects
with <tt>get_frame()</tt> and <tt>put_frame()</tt> interface, and
someone has to call these to retrieve/store media frames.
- @ref page_pjmedia_samples_playfile_c\n
This example shows that when application connects a media port (in this
case a @ref PJMEDIA_FILE_PLAY) to @ref PJMED_SND_PORT, media will flow
automatically since the @ref PJMED_SND_PORT provides @ref PJMEDIA_PORT_CLOCK.
- @ref page_pjmedia_samples_recfile_c\n
Demonstrates how to capture audio from microphone to WAV file.
- @ref page_pjmedia_samples_playsine_c\n
Demonstrates how to create a custom @ref PJMEDIA_PORT (in this
case a sine wave generator) and integrate it to PJMEDIA.
- @ref page_pjmedia_samples_confsample_c\n
This demonstrates how to use the @ref PJMEDIA_CONF. The sample program can
open multiple WAV files, and instruct the conference bridge to mix the
signal before playing it to the sound device.
- @ref page_pjmedia_samples_confbench_c\n
I use this to benchmark/optimize the conference bridge algorithm, but
readers may find the source useful.
- @ref page_pjmedia_samples_resampleplay_c\n
Demonstrates how to use @ref PJMEDIA_RESAMPLE_PORT to change the
sampling rate of a media port (in this case, a @ref PJMEDIA_FILE_PLAY).
- @ref page_pjmedia_samples_sndtest_c\n
This program performs some tests to the sound device to get some
quality parameters (such as sound jitter and clock drifts).\n
Screenshots on WinXP: \image html sndtest.jpg "sndtest screenshot on WinXP"
- @ref page_pjmedia_samples_streamutil_c\n
This example mainly demonstrates how to stream media (in this case a
@ref PJMEDIA_FILE_PLAY) to remote peer using RTP.
- @ref page_pjmedia_samples_siprtp_c\n
This is a useful program (integrated with PJSIP) to actively measure
the network quality/impairment parameters by making one or more SIP
calls (or receiving one or more SIP calls) and display the network
impairment of each stream direction at the end of the call.
The program is able to measure network quality parameters such as
jitter, packet lost/reorder/duplicate, round trip time, etc.\n
Note that the remote peer MUST support RTCP so that network quality
of each direction can be calculated. Using siprtp for both endpoints
is recommended.\n
Screenshots on WinXP: \image html siprtp.jpg "siprtp screenshot on WinXP"
- @ref page_pjmedia_samples_tonegen_c\n
This is a simple program to generate a tone and write the samples to
a raw PCM file. The main purpose of this file is to analyze the
quality of the tones/sine wave generated by PJMEDIA tone/sine wave
generator.
- @ref page_pjmedia_samples_aectest_c\n
Play a file to speaker, run AEC, and record the microphone input
to see if echo is coming.
*/
/**
* \page page_pjmedia_samples_siprtp_c Samples: Using SIP and Custom RTP/RTCP to Monitor Quality
*
* This source is an example to demonstrate using SIP and RTP/RTCP framework
* to measure the network quality/impairment from the SIP call. This
* program can be used to make calls or to receive calls from other
* SIP endpoint (or other siprtp program), and to display the media
* quality statistics at the end of the call.
*
* Note that the remote peer must support RTCP.
*
* The layout of the program has been designed so that custom reporting
* can be generated instead of plain human readable text.
*
* The source code of the file is pjsip-apps/src/samples/siprtp.c
*
* Screenshots on WinXP: \image html siprtp.jpg
*
* \includelineno siprtp.c
*/
#endif /* __PJMEDIA_DOXYGEN_H__ */