diff options
author | Benny Prijono <bennylp@teluu.com> | 2006-06-20 15:39:07 +0000 |
---|---|---|
committer | Benny Prijono <bennylp@teluu.com> | 2006-06-20 15:39:07 +0000 |
commit | e03158426d316085bbec3088f3a54004dc832a0e (patch) | |
tree | bf745f7af641d801e7bc9cd8857da6d63ab22cd1 /pjmedia/include | |
parent | e120cd2fd516294025fb23da7403ceac296e2411 (diff) |
Yet again large diffs because of documentation/doxygen update
git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@531 74dad513-b988-da41-8d7b-12977e46ad98
Diffstat (limited to 'pjmedia/include')
-rw-r--r-- | pjmedia/include/pjmedia-codec.h | 5 | ||||
-rw-r--r-- | pjmedia/include/pjmedia-codec/gsm.h | 2 | ||||
-rw-r--r-- | pjmedia/include/pjmedia-codec/l16.h | 2 | ||||
-rw-r--r-- | pjmedia/include/pjmedia-codec/speex.h | 2 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/doxygen.h | 193 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/plc.h | 2 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/rtp.h | 3 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/sdp_neg.h | 3 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/sound.h | 2 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/splitcomb.h | 24 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/wav_port.h | 92 |
11 files changed, 312 insertions, 18 deletions
diff --git a/pjmedia/include/pjmedia-codec.h b/pjmedia/include/pjmedia-codec.h index f160edef..3658cb10 100644 --- a/pjmedia/include/pjmedia-codec.h +++ b/pjmedia/include/pjmedia-codec.h @@ -19,6 +19,11 @@ #ifndef __PJMEDIA_CODEC_PJMEDIA_CODEC_H__ #define __PJMEDIA_CODEC_PJMEDIA_CODEC_H__ +/** + * @file pjmedia-codec.h + * @brief Include all codecs API in PJMEDIA-CODEC + */ + #include <pjmedia-codec/l16.h> #include <pjmedia-codec/gsm.h> #include <pjmedia-codec/speex.h> diff --git a/pjmedia/include/pjmedia-codec/gsm.h b/pjmedia/include/pjmedia-codec/gsm.h index 04f526ad..f6d0e99f 100644 --- a/pjmedia/include/pjmedia-codec/gsm.h +++ b/pjmedia/include/pjmedia-codec/gsm.h @@ -27,7 +27,7 @@ #include <pjmedia-codec/types.h> /** - * @defgroup PJMED_GSM GSM 06.10 + * @defgroup PJMED_GSM GSM 06.10 Codec * @ingroup PJMEDIA_CODEC * @brief Implementation of GSM FR based on GSM 06.10 library * @{ diff --git a/pjmedia/include/pjmedia-codec/l16.h b/pjmedia/include/pjmedia-codec/l16.h index 225c0929..59e222e1 100644 --- a/pjmedia/include/pjmedia-codec/l16.h +++ b/pjmedia/include/pjmedia-codec/l16.h @@ -23,7 +23,7 @@ /** - * @defgroup PJMED_L16 L16 Family + * @defgroup PJMED_L16 L16 Codec Family * @ingroup PJMEDIA_CODEC * @brief 16bit linear codecs (useful for debugging) * @{ diff --git a/pjmedia/include/pjmedia-codec/speex.h b/pjmedia/include/pjmedia-codec/speex.h index a773b39e..51b6931c 100644 --- a/pjmedia/include/pjmedia-codec/speex.h +++ b/pjmedia/include/pjmedia-codec/speex.h @@ -27,7 +27,7 @@ #include <pjmedia-codec/types.h> /** - * @defgroup PJMED_SPEEX Speex + * @defgroup PJMED_SPEEX Speex Codec Family * @ingroup PJMEDIA_CODEC * @brief Implementation of Speex codecs (narrow/wide/ultrawide-band). * @{ diff --git a/pjmedia/include/pjmedia/doxygen.h b/pjmedia/include/pjmedia/doxygen.h index 9ebd27e6..c9bef719 100644 --- a/pjmedia/include/pjmedia/doxygen.h +++ b/pjmedia/include/pjmedia/doxygen.h @@ -61,9 +61,63 @@ * PJMEDIA-CODEC. * * \n + * @section main_page_get_start_sec Getting Started + * + * For those who likes to just get start coding, the @ref getting_started_pjmedia + * may be a good place to start. + * + * The @ref page_pjmedia_samples page describes some examples that are available + * in the source tree. + * + * + * \n * @section pjmedia_lic Copying and Acknowledgements * - * Please see @ref lic_stuffs page for the details. + * PJMEDIA and PJMEDIA-CODEC contains various parts obtained from other + * places, and each of these would have their own licensing terms. + * Please see @ref lic_stuffs page for details. + * + */ + +/** + * @page pjmed_keywords_page Features Index + * @section pjmed_keywords Features Index + * + * <b>PJMEDIA features</b>, in no particular order (click to go to the relevant + * documentation): + * @ref lic_stuffs "Open Source media stack", + * @ref PJMEDIA_CLOCK, + * @ref PJMEDIA_CODEC, + * @ref enc_dec_codec, + * @ref plc_codec, + * @ref PJMEDIA_CONF, + * @ref PJMED_G711 "G711/G.711 (PCMA/PCMU) codec with PLC", + * @ref PJMED_GSM "GSM codec with PLC", + * @ref PJMED_L16 "linear codecs (multiple clockrate, stereo support, etc)", + * @ref PJMED_SPEEX "Speex codec (narrowband, wideband, ultra-wideband)", + * @ref PJMED_JBUF "portable, adaptive jitter buffer with PLC support", + * @ref PJMEDIA_MASTER_PORT, + * @ref PJMEDIA_NULL_PORT, + * @ref PJMED_PLC, + * @ref PJMEDIA_PORT_CONCEPT, + * @ref PJMEDIA_PORT_CLOCK, + * @ref PJMEDIA_RESAMPLE "high quality resampling/sampling rate conversion", + * @ref PJMEDIA_RESAMPLE_PORT, + * @ref PJMED_RTCP "small footprint, portable RTCP with media quality statistics", + * @ref PJMED_RTP "very small footprint, modular, DSP ready RTP implementation", + * @ref PJMEDIA_SDP "modular, small footprint, open source SDP implementation", + * @ref PJMEDIA_SDP_NEG "modular SDP negotiation/negotiator abstraction", + * @ref PJMED_SES "media session abstraction", + * @ref PJMEDIA_SILENCEDET, + * @ref PJMED_SND "portable audio/sound hardware/device abstraction for Linux, Unix, Windows, DirectSound, WinCE, Windows Mobile, MacOS X, etc.", + * @ref PJMED_SND_PORT, + * @ref PJMEDIA_SPLITCOMB, + * @ref PJMED_STRM "remote stream", + * @ref PJMEDIA_TRANSPORT_H "custom media transport abstraction", + * @ref PJMEDIA_TRANSPORT_UDP, + * @ref PJMEDIA_FILE_PLAY "WAV/WAVE file playback", + * @ref PJMEDIA_FILE_REC "WAV/WAVE file recording/capture", + * @ref PJMEDIA_WAVE "portable WAV/WAVE header manipulation" */ @@ -325,4 +379,141 @@ * */ + +/** + @page getting_started_pjmedia Getting Started with PJMEDIA + + @section getstart_init_setup_build Setting-up the Build System + + @subsection subsec_build_pjmedia Building PJMEDIA and PJMEDIA-CODEC + + The PJMEDIA and PJMEDIA-CODEC libraries are normally bundled in PJPROJECT + source tarball, and they are located in <tt><b>pjmedia</b></tt> sub-directory + tree. + + Please follow the instructions in <tt><b>INSTALL.txt</b></tt> in the root + PJPROJECT directory to build all projects, including PJMEDIA and PJMEDIA-CODEC. + + @subsection subsec_config_build Setting Up the Build Environment + + In your project, you will need to configure the following. + - Add <tt><b>$pjproject/pjmedia/include</b></tt> in the search path for + include files. + - Add <tt><b>$pjproject/pjmedia/lib</b></tt> in the search path for + library files. + - Add PJMEDIA and PJMEDIA static libraries in the link command. + + @subsection subsec_inc_pjmedia Include PJMEDIA and PJMEDIA-CODEC in Source Files + + To include all features from PJMEDIA and PJMEDIA-CODEC, use the following: + + \code + #include <pjlib.h> + #include <pjmedia.h> + #include <pjmedia-codec.h> + \endcode + + Alternatively, you may include only specific parts of the library (for example + to speed up compilation by just a fraction), for example: + + \code + #include <pjmedia/conference.h> + #include <pjmedia/jbuf.h> + #include <pjmedia-codec/speex.h> + \endcode + + Note that you need to give <b>"pjmedia/"</b> and <b>"pjmedia-codec/"</b> + prefix to include specific files. + + + @section getstart_using Using PJMEDIA + + I wish I could explain more, but for now, please have a look at the + @ref page_pjmedia_samples page on some examples. + */ + +/** + @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_CONCEPT, + as it shows that @ref PJMEDIA_PORT_CONCEPT 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_CONCEPT (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" + + */ + +/** + * \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__ */ + diff --git a/pjmedia/include/pjmedia/plc.h b/pjmedia/include/pjmedia/plc.h index 6b80d18a..6a4be4d2 100644 --- a/pjmedia/include/pjmedia/plc.h +++ b/pjmedia/include/pjmedia/plc.h @@ -27,7 +27,7 @@ #include <pjmedia/types.h> /** - * @defgroup PJMED_PLC Packet Lost Concealment + * @defgroup PJMED_PLC Packet Lost Concealment (PLC) * @ingroup PJMEDIA_FRAME_OP * @{ * This section describes PJMEDIA's implementation of Packet Lost diff --git a/pjmedia/include/pjmedia/rtp.h b/pjmedia/include/pjmedia/rtp.h index edad178a..220a8634 100644 --- a/pjmedia/include/pjmedia/rtp.h +++ b/pjmedia/include/pjmedia/rtp.h @@ -37,7 +37,8 @@ PJ_BEGIN_DECL * * The RTP module is designed to be dependent only to PJLIB, it does not depend * on any other parts of PJMEDIA library. The RTP module does not even depend - * on any transports (sockets), to promote even more use. + * on any transports (sockets), to promote even more use, such as in DSP + * development (where transport may be handled by different processor). * * An RTCP implementation is available, in separate module. Please see * @ref PJMED_RTCP. diff --git a/pjmedia/include/pjmedia/sdp_neg.h b/pjmedia/include/pjmedia/sdp_neg.h index f105c42f..4a07cfe6 100644 --- a/pjmedia/include/pjmedia/sdp_neg.h +++ b/pjmedia/include/pjmedia/sdp_neg.h @@ -25,8 +25,9 @@ * @brief SDP negotiator header file. */ /** - * @defgroup PJMEDIA_SDP_NEG SDP Negotiator + * @defgroup PJMEDIA_SDP_NEG SDP Negotiation * @ingroup PJMEDIA_SESSION + * @brief Abstraction to perform SDP negotiation * @{ * * The header file <b><pjmedia/sdp_neg.h></b> contains the declaration diff --git a/pjmedia/include/pjmedia/sound.h b/pjmedia/include/pjmedia/sound.h index b09d69d3..9cd2bbca 100644 --- a/pjmedia/include/pjmedia/sound.h +++ b/pjmedia/include/pjmedia/sound.h @@ -30,7 +30,7 @@ PJ_BEGIN_DECL /** - * @defgroup PJMED_SND Sound Hardware Abstraction + * @defgroup PJMED_SND Portable Sound Hardware Abstraction * @ingroup PJMED_SND_PORT * @brief PJMEDIA abstraction for sound device hardware * @{ diff --git a/pjmedia/include/pjmedia/splitcomb.h b/pjmedia/include/pjmedia/splitcomb.h index 1bd1bd23..d1104488 100644 --- a/pjmedia/include/pjmedia/splitcomb.h +++ b/pjmedia/include/pjmedia/splitcomb.h @@ -21,6 +21,25 @@ /** + * @file splitcomb.h + * @brief Media channel splitter/combiner port. + */ +#include <pjmedia/types.h> + + +/** + * @addtogroup PJMEDIA_SPLITCOMB Media channel splitter/combiner + * @ingroup PJMEDIA_PORT + * @brief Split and combine media channels in media streams + * @{ + * This section describes media port to split and combine media + * channels in the stream. + */ + +PJ_BEGIN_DECL + + +/** * Create a media splitter/combiner with the specified parameters. * A splitter/combiner splits a single stereo/multichannel audio frame into * multiple mono audio frames to each channel when put_frame() is called, @@ -107,6 +126,11 @@ pjmedia_splitcomb_create_rev_channel( pj_pool_t *pool, +PJ_END_DECL + +/** + * @} + */ #endif /* __PJMEDIA_SPLITCOMB_H__ */ diff --git a/pjmedia/include/pjmedia/wav_port.h b/pjmedia/include/pjmedia/wav_port.h index 6806f33f..99de617b 100644 --- a/pjmedia/include/pjmedia/wav_port.h +++ b/pjmedia/include/pjmedia/wav_port.h @@ -31,7 +31,7 @@ PJ_BEGIN_DECL /** - * @defgroup PJMEDIA_FILE_PLAY File Player + * @defgroup PJMEDIA_FILE_PLAY WAV File Player * @ingroup PJMEDIA_PORT * @brief WAV File Player * @{ @@ -77,18 +77,52 @@ PJ_DECL(pj_status_t) pjmedia_wav_player_port_create( pj_pool_t *pool, /** - * Set the play position of WAV player. + * Set the file play position of WAV player. * * @param port The file player port. - * @param samples Sample position (zero as start of file). + * @param offset Playback position in bytes, relative to the start of + * the payload. * * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjmedia_wav_player_port_set_pos( pjmedia_port *port, - pj_uint32_t samples ); + pj_uint32_t offset ); /** + * Get the file play position of WAV player. + * + * @param port The file player port. + * + * @return PJ_SUCCESS on success. + */ +PJ_DECL(pj_ssize_t) pjmedia_wav_player_port_get_pos( pjmedia_port *port ); + + +/** + * Register a callback to be called when the file reading has reached the + * end of file. If the file is set to play repeatedly, then the callback + * will be called multiple times. Note that only one callback can be + * registered for each file port. + * + * @param port The file player port. + * @param user_data User data to be specified in the callback. Note that + * this overwrites the user data previously set when + * the file port is created. + * @param cb Callback to be called. If the callback returns non- + * PJ_SUCCESS, the playback will stop. Note that if + * application destroys the file port in the callback, + * it must return non-PJ_SUCCESS here. + * + * @return PJ_SUCCESS on success. + */ +PJ_DECL(pj_status_t) +pjmedia_wav_player_set_eof_cb( pjmedia_port *port, + void *user_data, + pj_status_t (*cb)(pjmedia_port *port, + void *usr_data)); + +/** * @} */ @@ -114,13 +148,13 @@ PJ_DECL(pj_status_t) pjmedia_wav_player_port_set_pos( pjmedia_port *port, * @param samples_per_frame Number of samples per frame. * @param bits_per_sample Number of bits per sample (eg 16). * @param flags Port creation flags (must be 0 at present). - * @param buff_size Buffer size to be allocated. If the value is zero or - * negative, the port will use default buffer size (which - * is about 4KB). - * @param user_data User data to be associated with the file writer port. - * @param p_port Pointer to receive the file port instance. + * @param buff_size Buffer size to be allocated. If the value is + * zero or negative, the port will use default buffer + * size (which is about 4KB). + * @param user_data User data to be associated with the file port. + * @param p_port Pointer to receive the file port instance. * - * @return PJ_SUCCESS on success. + * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjmedia_wav_writer_port_create(pj_pool_t *pool, const char *filename, @@ -134,6 +168,44 @@ PJ_DECL(pj_status_t) pjmedia_wav_writer_port_create(pj_pool_t *pool, pjmedia_port **p_port ); +/** + * Get current writing position. Note that this does not necessarily match + * the size written to the file, since the WAV writer employs some internal + * buffering. Also the value reported here only indicates the payload size + * (it does not include the size of the WAV header), + * + * @param port The file writer port. + * + * @return Positive value to indicate the position (in bytes), + * or negative value containing the error code. + */ +PJ_DECL(pj_ssize_t) pjmedia_wav_writer_port_get_pos( pjmedia_port *port ); + + +/** + * Register the callback to be called when the file writing has reached + * certain size. Application can use this callback, for example, to limit + * the size of the output file. + * + * @param port The file writer port. + * @param pos The file position on which the callback will be called. + * @param user_data User data to be specified in the callback. Note that + * this overwrites the user data previously set when + * the file port is created. + * @param cb Callback to be called. If the callback returns non- + * PJ_SUCCESS, the writing will stop. Note that if + * application destroys the port in the callback, it must + * return non-PJ_SUCCESS here. + * + * @return PJ_SUCCESS on success. + */ +PJ_DECL(pj_status_t) +pjmedia_wav_writer_port_set_cb( pjmedia_port *port, + pj_size_t pos, + void *user_data, + pj_status_t (*cb)(pjmedia_port *port, + void *usr_data)); + /** * @} |