/* $Id: codec.h 974 2007-02-19 01:13:53Z bennylp $ *//*  * Copyright (C) 2003-2007 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_CODEC_H__#define __PJMEDIA_CODEC_H__/** * @file codec.h * @brief Codec framework. */#include <pjmedia/port.h>#include <pj/list.h>PJ_BEGIN_DECL/** * @defgroup PJMEDIA_CODEC Codec Framework * @ingroup PJMEDIA * @brief Media codec framework and management * @{ * * @section codec_mgmt_sec Codec Management * @subsection codec_fact_sec Codec Manager * * The codec manager is used to manage all codec capabilities in the endpoint. * When used with media endpoint (pjmedia_endpt), application can retrieve * the codec manager instance by calling #pjmedia_endpt_get_codec_mgr(). * * @subsection reg_new_codec Registering New Codec * * New codec types can be registered to PJMEDIA (or to be precise, to the  * codec manager) during run-time.  * To do this, application needs to initialize an instance of * codec factory (#pjmedia_codec_factory) and registers this codec factory * by calling #pjmedia_codec_mgr_register_factory(). * * For codecs implemented/supported by PJMEDIA, this process is normally * concealed in an easy to use function such as #pjmedia_codec_g711_init(). * * @subsection codec_factory Codec Factory * * A codec factory (#pjmedia_codec_factory) is registered to codec manager,  * and it is used to create and release codec instance. * * The most important member of the codec factory is the "virtual" function * table #pjmedia_codec_factory_op, where it contains, among other thing,  * pointer to functions to allocate and deallocate codec instance. * * @subsection codec_inst Codec Instance * * Application allocates codec instance by calling #pjmedia_codec_mgr_alloc_codec(). * One codec instance (#pjmedia_codec) can be used for simultaneous encoding * and decoding. * * The most important member of the codec instance is the "virtual" function * table #pjmedia_codec_op, where it holds pointer to functions to * encode/decode media frames. * * @subsection codec_ident Codec Identification * * A particular codec type in PJMEDIA can be uniquely identified by two * keys: by #pjmedia_codec_info, or by #pjmedia_codec_id string. A fully * qualified codec ID string consists of codec name, sampling rate, and * number of channels. However, application may use only first parts of * the tokens as long as it will make to codec ID unique. For example, "gsm" * is a fully qualified codec name, since it will always have 8000 clock * rate and 1 channel. Other examples of fully qualified codec ID strings * are "pcma", "speex/8000", "speex/16000", and "L16/16000/1". A codec * id "speex" (without clock rate) is not fully qualified, since it will * match the narrowband, wideband, and ultrawideband Speex codec. * * The two keys can be converted to one another, with * #pjmedia_codec_info_to_id() and #pjmedia_codec_mgr_find_codecs_by_id() * functions. * * Codec ID string is not case sensitive. * * * @section using_codec Using the Codec Framework * @subsection init_alloc_codec Allocating Codec * * Application needs to allocate one codec instance for encoding and decoding * media frames. One codec instance can be used to perform both encoding * and decoding. * * Application allocates codec by calling #pjmedia_codec_mgr_alloc_codec(). * This function takes #pjmedia_codec_info argument, which is used to locate * the particular codec factory to be used to allocate the codec. * * Application can build #pjmedia_codec_info structure manually for * the specific codec, or alternatively it may get the #pjmedia_codec_info * from the codec ID string, by using #pjmedia_codec_mgr_find_codecs_by_id() * function. * * The following snippet shows an example to allocate a codec: * \code    pj_str_t codec_id;    pjmedia_codec_info *codec_info;    unsigned count = 1;    pjmedia_codec *codec;    codec_id = pj_str("pcma");    // Find codec info for the specified coded ID (i.e. "pcma").    status = pjmedia_codec_mgr_find_codecs_by_id( codec_mgr, &codec_id,						  &count, &codec_info, NULL);    // Allocate the codec.    status = pjmedia_codec_mgr_alloc_codec( codec_mgr, codec_info, &codec ); \endcode * * * @subsection opening_codec Initializing Codec * * Once codec is allocated, application needs to initialize the codec * by calling <b><tt>open</tt></b> member of the codec. This function * takes #pjmedia_codec_param as the argument, which contains the * settings for the codec. * * Application shoud use #pjmedia_codec_mgr_get_default_param() function * to initiaize #pjmedia_codec_param. The <tt>setting</tt> part of * #pjmedia_codec_param then can be tuned to suit the application's * requirements. * * The following snippet shows an example to initialize codec: * \code    pjmedia_codec_param param;    // Retrieve default codec param for the specified codec.    pjmedia_codec_mgr_get_default_param(codec_mgr, codec_info					&param);    // Application may change the "settings" part of codec param,    // for example, to disable VAD    param.setting.vad = 0;    // Open the codec using the specified settings.    codec->op->open( codec, &param ); \endcode * * * @subsection enc_dec_codec Encoding and Decoding Media Frames * * Application encodes and decodes media frames by calling * <tt>encode</tt> and <tt>decode</tt> member of the codec's "virtual" * function table (#pjmedia_codec_op). * * @subsection plc_codec Concealing Lost Frames * * All codecs has Packet Lost Concealment (PLC) feature, and application * can activate the PLC to conceal lost frames by calling <tt>recover</tt> * member of the codec's "virtual" function table (#pjmedia_codec_op). * * If the codec's algorithm supports PLC, the <tt>recover</tt> function * will use the codec's PLC. Otherwise for codecs that don't have * intrinsic PLC, PJMEDIA will suply the PLC implementation from the * @ref PJMED_PLC implementation. * * @subsection close_codec Closing and Releasing the Codec * * The codec must be closed by calling <tt>close</tt> member of the codec's * operation. Then it must be released by calling  * #pjmedia_codec_mgr_dealloc_codec(). *//**  * Standard RTP static payload types, as defined by RFC 3551.  * The header file <pjmedia-codec/types.h> also declares dynamic payload * type numbers that are used by PJMEDIA when advertising the capability * for example in SDP message. */enum pjmedia_rtp_pt{    PJMEDIA_RTP_PT_PCMU = 0,	    /**< audio PCMU			    */    PJMEDIA_RTP_PT_GSM  = 3,	    /**< audio GSM			    */    PJMEDIA_RTP_PT_G723 = 4,	    /**< audio G723			    */    PJMEDIA_RTP_PT_DVI4_8K = 5,	    /**< audio DVI4 8KHz		    */    PJMEDIA_RTP_PT_DVI4_16K = 6,    /**< audio DVI4 16Khz		    */    PJMEDIA_RTP_PT_LPC = 7,	    /**< audio LPC			    */    PJMEDIA_RTP_PT_PCMA = 8,	    /**< audio PCMA			    */    PJMEDIA_RTP_PT_G722 = 9,	    /**< audio G722			    */    PJMEDIA_RTP_PT_L16_2 = 10,	    /**< audio 16bit linear 44.1KHz stereo  */    PJMEDIA_RTP_PT_L16_1 = 11,	    /**< audio 16bit linear 44.1KHz mono    */    PJMEDIA_RTP_PT_QCELP = 12,	    /**< audio QCELP			    */    PJMEDIA_RTP_PT_CN = 13,	    /**< audio Comfort Noise		    */    PJMEDIA_RTP_PT_MPA = 14,	    /**< audio MPEG1/MPEG2 elemetr. streams */    PJMEDIA_RTP_PT_G728 = 15,	    /**< audio G728			    */    PJMEDIA_RTP_PT_DVI4_11K = 16,   /**< audio DVI4 11.025KHz mono	    */    PJMEDIA_RTP_PT_DVI4_22K = 17,   /**< audio DVI4 22.050KHz mono	    */    PJMEDIA_RTP_PT_G729 = 18,	    /**< audio G729			    */    PJMEDIA_RTP_PT_CELB = 25,	    /**< video/comb Cell-B by Sun (RFC2029) */    PJMEDIA_RTP_PT_JPEG = 26,	    /**< video JPEG			    */    PJMEDIA_RTP_PT_NV = 28,	    /**< video NV  by nv program by Xerox   */    PJMEDIA_RTP_PT_H261 = 31,	    /**< video H261			    */    PJMEDIA_RTP_PT_MPV = 32,	    /**< video MPEG1 or MPEG2 elementary    */    PJMEDIA_RTP_PT_MP2T = 33,	    /**< video MPEG2 transport		    */    PJMEDIA_RTP_PT_H263 = 34,	    /**< video H263			    */    PJMEDIA_RTP_PT_DYNAMIC = 96     /**< start of dynamic RTP payload	    */};/**  * Identification used to search for codec factory that supports specific  * codec specification.  */typedef struct pjmedia_codec_info{    pjmedia_type    type;	    /**< Media type.			*/    unsigned	    pt;		    /**< Payload type (can be dynamic). */    pj_str_t	    encoding_name;  /**< Encoding name.			*/    unsigned	    clock_rate;	    /**< Sampling rate.			*/    unsigned	    channel_cnt;    /**< Channel count.			*/} pjmedia_codec_info;/**  * Detailed codec attributes used both to configure a codec and to query * the capability of codec factories. */typedef struct pjmedia_codec_param{    /**     * The "info" part of codec param describes the capability of the codec,     * and the value should NOT be changed by application.     */    struct {       unsigned	   clock_rate;		/**< Sampling rate in Hz	    */       unsigned	   channel_cnt;		/**< Channel count.		    */       pj_uint32_t avg_bps;		/**< Average bandwidth in bits/sec  */       pj_uint16_t frm_ptime;		/**< Decoder frame ptime in msec.   */       pj_uint16_t enc_ptime;		/**< Encoder ptime, or zero if it's					     equal to decoder ptime.	    */       pj_uint8_t  pcm_bits_per_sample;	/**< Bits/sample in the PCM side    */       pj_uint8_t  pt;			/**< Payload type.		    */    } info;    /**     * The "setting" part of codec param describes various settings to be     * applied to the codec. When the codec param is retrieved from the codec     * or codec factory, the values of these will be filled by the capability     * of the codec. Any features that are supported by the codec (e.g. vad     * or plc) will be turned on, so that application can query which      * capabilities are supported by the codec. Application may change the     * settings here before instantiating the codec/stream.     */    struct {	pj_uint8_t  frm_per_pkt;    /**< Number of frames per packet.	*/	unsigned    vad:1;	    /**< Voice Activity Detector.	*/	unsigned    cng:1;	    /**< Comfort Noise Generator.	*/	unsigned    penh:1;	    /**< Perceptual Enhancement		*/	unsigned    plc:1;	    /**< Packet loss concealment	*/	unsigned    reserved:1;	    /**< Reserved, must be zero.	*/	pj_uint8_t  enc_fmtp_mode;  /**< Mode param in fmtp (def:0)	*/	pj_uint8_t  dec_fmtp_mode;  /**< Mode param in fmtp (def:0)	*/    } setting;} pjmedia_codec_param;/* * Forward declaration for pjmedia_codec. */typedef struct pjmedia_codec pjmedia_codec;/** * This structure describes codec operations. Each codec MUST implement * all of these functions. */typedef struct pjmedia_codec_op{    /**      * Initialize codec using the specified attribute.     *     * @param codec	The codec instance.     * @param pool	Pool to use when the codec needs to allocate     *			some memory.     *     * @return		PJ_SUCCESS on success.     */    pj_status_t	(*init)(pjmedia_codec *codec, 			pj_pool_t *pool );    /**      * Open the codec and initialize with the specified parameter.     * Upon successful initialization, the codec may modify the parameter     * and fills in the unspecified values (such as enc_ptime, when     * encoder ptime is different than decoder ptime).     *     * @param codec	The codec instance.     * @param param	Codec initialization parameter.     *     * @return		PJ_SUCCESS on success.     */    pj_status_t	(*open)(pjmedia_codec *codec, 			pjmedia_codec_param *param );    /**      * Close and shutdown codec, releasing all resources allocated by     * this codec, if any.     *     * @param codec	The codec instance.     *     * @return		PJ_SUCCESS on success.     */    pj_status_t (*close)(pjmedia_codec *codec);    /**      * Modify the codec parameter after the codec is open.      * Note that not all codec parameters can be modified during run-time.      * When the parameter cannot be changed, this function will return      * non-PJ_SUCCESS, and the original parameters will not be changed.     *     * Application can expect changing trivial codec settings such as     * changing VAD setting to succeed.     *     * @param codec	The codec instance.     * @param param	The new codec parameter.     *     * @return		PJ_SUCCESS on success.     */    pj_status_t	(*modify)(pjmedia_codec *codec, 			  const pjmedia_codec_param *param );    /**     * Instruct the codec to inspect the specified payload/packet and     * split the packet into individual base frames. Each output frames will     * have ptime that is equal to basic frame ptime (i.e. the value of     * info.frm_ptime in #pjmedia_codec_param).     *     * @param codec	The codec instance     * @param pkt	The input packet.     * @param pkt_size	Size of the packet.     * @param timestamp	The timestamp of the first sample in the packet.     * @param frame_cnt	On input, specifies the maximum number of frames     *			in the array. On output, the codec must fill     *			with number of frames detected in the packet.     * @param frames	On output, specifies the frames that have been     *			detected in the packet.     *     * @return		PJ_SUCCESS on success.     */    pj_status_t (*parse)( pjmedia_codec *codec,			  void *pkt,			  pj_size_t pkt_size,			  const pj_timestamp *timestamp,			  unsigned *frame_cnt,			  pjmedia_frame frames[]);    /**      * Instruct the codec to encode the specified input frame. The input     * PCM samples MUST have ptime that is exactly equal to base frame     * ptime (i.e. the value of info.frm_ptime in #pjmedia_codec_param).     *     * @param codec	The codec instance.     * @param input	The input frame.     * @param out_size	The length of buffer in the output frame.     * @param output	The output frame.     *     * @return		PJ_SUCCESS on success;     */    pj_status_t (*encode)(pjmedia_codec *codec, 			  const struct pjmedia_frame *input,			  unsigned out_size, 			  struct pjmedia_frame *output);    /**      * Instruct the codec to decode the specified input frame. The input     * frame MUST have ptime that is exactly equal to base frame     * ptime (i.e. the value of info.frm_ptime in #pjmedia_codec_param).     * Application can achieve this by parsing the packet into base     * frames before decoding each frame.     *     * @param codec	The codec instance.     * @param input	The input frame.     * @param out_size	The length of buffer in the output frame.     * @param output	The output frame.     *     * @return		PJ_SUCCESS on success;     */    pj_status_t (*decode)(pjmedia_codec *codec, 			  const struct pjmedia_frame *input,			  unsigned out_size, 			  struct pjmedia_frame *output);    /**     * Instruct the codec to recover a missing frame.     *     * @param codec	The codec instance.     * @param out_size	The length of buffer in the output frame.     * @param output	The output frame where generated signal     *			will be placed.     *     * @return		PJ_SUCCESS on success;     */    pj_status_t (*recover)(pjmedia_codec *codec,			   unsigned out_size,