path: root/pjmedia/include/pjmedia/codec.h

/* $Id: codec.h 3664 2011-07-19 03:42:28Z nanang $ */
/* 
 * 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_CODEC_H__
#define __PJMEDIA_CODEC_H__


/**
 * @file codec.h
 * @brief Codec framework.
 */

#include <pjmedia/port.h>
#include <pj/errno.h>
#include <pj/list.h>
#include <pj/pool.h>

PJ_BEGIN_DECL


/**
 * @defgroup PJMEDIA_CODEC Codec Framework
 * @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_G721 = 2,	    /**< audio G721 (old def for G726-32)   */
    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;

/** 
 * Structure of codec specific parameters which contains name=value pairs.
 * The codec specific parameters are to be used with SDP according to 
 * the standards (e.g: RFC 3555) in SDP 'a=fmtp' attribute.
 */
typedef struct pjmedia_codec_fmtp
{
    pj_uint8_t	    cnt;	    /**< Number of parameters.		*/
    struct param {
	pj_str_t    name;	    /**< Parameter name.		*/
	pj_str_t    val;	    /**< Parameter value.		*/
    } param [PJMEDIA_CODEC_MAX_FMTP_CNT]; /**< The parameters.		*/
} pjmedia_codec_fmtp;

/** 
 * Detailed codec attributes used in configuring a codec and in querying
 * the capability of codec factories. Default attributes of any codecs could
 * be queried using #pjmedia_codec_mgr_get_default_param() and modified
 * using #pjmedia_codec_mgr_set_default_param().
 *
 * Please note that codec parameter also contains SDP specific setting, 
 * #dec_fmtp and #enc_fmtp, which may need to be set appropriately based on
 * the effective setting. See each codec documentation for more detail.
 */
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_uint32_t max_bps;		/**< Maximum 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.		    */
       pjmedia_format_id fmt_id;	/**< Source format, it's format of
					     encoder input and decoder 
					     output.			    */
    } 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.	*/
	pjmedia_codec_fmtp enc_fmtp;/**< Encoder's fmtp params.		*/
	pjmedia_codec_fmtp dec_fmtp;/**< Decoder's fmtp params.		*/
    } 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.
     *
     * Application should call #pjmedia_codec_init() instead of 
     * calling this function directly.
     *
     * @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).
     *
     * Application should call #pjmedia_codec_open() instead of 
     * calling this function directly.
     *
     * @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.
     *
     * Application should call #pjmedia_codec_close() instead of 
     * calling this function directly.
     *
     * @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.
     *
     * Application should call #pjmedia_codec_modify() instead of 
     * calling this function directly.
     *
     * @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).
     *
     * Application should call #pjmedia_codec_parse() instead of 
     * calling this function directly.
     *
     * @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 multiplication of base frame
     * ptime (i.e. the value of info.frm_ptime in #pjmedia_codec_param).
     *
     * Application should call #pjmedia_codec_encode() instead of 
     * calling this function directly.
     *
     * @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.
     *
     * Application should call #pjmedia_codec_decode() instead of 
     * calling this function directly.
     *
     * @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.
     *
     * Application should call #pjmedia_codec_recover() instead of 
     * calling this function directly.
     *
     * @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,
			   struct pjmedia_frame *output);
} pjmedia_codec_op;



/*
 * Forward declaration for pjmedia_codec_factory.
 */
typedef struct pjmedia_codec_factory pjmedia_codec_factory;


/**
 * This structure describes a codec instance. 
 */
struct pjmedia_codec
{
    /** Entries to put this codec instance in codec factory's list. */
    PJ_DECL_LIST_MEMBER(struct pjmedia_codec);

    /** Codec's private data. */
    void		    *codec_data;

    /** Codec factory where this codec was allocated. */
    pjmedia_codec_factory   *factory;

    /** Operations to codec. */
    pjmedia_codec_op	    *op;
};



/**
 * This structure describes operations that must be supported by codec 
 * factories.
 */
typedef struct pjmedia_codec_factory_op
{
    /** 
     * Check whether the factory can create codec with the specified 
     * codec info.
     *
     * @param factory	The codec factory.
     * @param info	The codec info.
     *
     * @return		PJ_SUCCESS if this factory is able to create an
     *			instance of codec with the specified info.
     */
    pj_status_t	(*test_alloc)(pjmedia_codec_factory *factory, 
			      const pjmedia_codec_info *info );

    /** 
     * Create default attributes for the specified codec ID. This function
     * can be called by application to get the capability of the codec.
     *
     * @param factory	The codec factory.
     * @param info	The codec info.
     * @param attr	The attribute to be initialized.
     *
     * @return		PJ_SUCCESS if success.
     */
    pj_status_t (*default_attr)(pjmedia_codec_factory *factory, 
    				const pjmedia_codec_info *info,
    				pjmedia_codec_param *attr );

    /** 
     * Enumerate supported codecs that can be created using this factory.
     * 
     *  @param factory	The codec factory.
     *  @param count	On input, specifies the number of elements in
     *			the array. On output, the value will be set to
     *			the number of elements that have been initialized
     *			by this function.
     *  @param info	The codec info array, which contents will be 
     *			initialized upon return.
     *
     *  @return		PJ_SUCCESS on success.
     */
    pj_status_t (*enum_info)(pjmedia_codec_factory *factory, 
			     unsigned *count, 
			     pjmedia_codec_info codecs[]);

    /** 
     * Create one instance of the codec with the specified codec info.
     *
     * @param factory	The codec factory.
     * @param info	The codec info.
     * @param p_codec	Pointer to receive the codec instance.
     *
     * @return		PJ_SUCCESS on success.
     */
    pj_status_t (*alloc_codec)(pjmedia_codec_factory *factory, 
			       const pjmedia_codec_info *info,
			       pjmedia_codec **p_codec);

    /** 
     * This function is called by codec manager to return a particular 
     * instance of codec back to the codec factory.
     *
     * @param factory	The codec factory.
     * @param codec	The codec instance to be returned.
     *
     * @return		PJ_SUCCESS on success.
     */
    pj_status_t (*dealloc_codec)(pjmedia_codec_factory *factory, 
				 pjmedia_codec *codec );

    /**
     * This callback will be called to deinitialize and destroy this factory.
     */
    pj_status_t (*destroy)(void);

} pjmedia_codec_factory_op;



/**
 * Codec factory describes a module that is able to create codec with specific
 * capabilities. These capabilities can be queried by codec manager to create
 * instances of codec.
 */
struct pjmedia_codec_factory
{
    /** Entries to put this structure in the codec manager list. */
    PJ_DECL_LIST_MEMBER(struct pjmedia_codec_factory);

    /** The factory's private data. */
    void		     *factory_data;

    /** Operations to the factory. */
    pjmedia_codec_factory_op *op;

};


/**
 * Declare maximum codecs
 */
#define PJMEDIA_CODEC_MGR_MAX_CODECS	    32


/**
 * Specify these values to set the codec priority, by calling
 * #pjmedia_codec_mgr_set_codec_priority().
 */
typedef enum pjmedia_codec_priority
{
    /**
     * This priority makes the codec the highest in the order.
     * The last codec specified with this priority will get the
     * highest place in the order, and will change the priority
     * of previously highest priority codec to NEXT_HIGHER.
     */
    PJMEDIA_CODEC_PRIO_HIGHEST = 255,

    /**
     * This priority will put the codec as the next codec after
     * codecs with this same priority.
     */
    PJMEDIA_CODEC_PRIO_NEXT_HIGHER = 254,

    /**
     * This is the initial codec priority when it is registered to
     * codec manager by codec factory.
     */
    PJMEDIA_CODEC_PRIO_NORMAL = 128,

    /**
     * This priority makes the codec the lowest in the order.
     * The last codec specified with this priority will be put
     * in the last place in the order.
     */
    PJMEDIA_CODEC_PRIO_LOWEST = 1,

    /**
     * This priority will prevent the codec from being listed in the
     * SDP created by media endpoint, thus should prevent the codec
     * from being used in the sessions. However, the codec will still
     * be listed by #pjmedia_codec_mgr_enum_codecs() and other codec
     * query functions.
     */
    PJMEDIA_CODEC_PRIO_DISABLED = 0

} pjmedia_codec_priority;


/** 
 * Codec identification (e.g. "pcmu/8000/1").
 * See @ref codec_ident for more info.
 */
typedef char pjmedia_codec_id[32];


/**
 * Opaque declaration of default codecs parameters.
 */
typedef struct pjmedia_codec_default_param pjmedia_codec_default_param;

/** 
 * Codec manager maintains array of these structs for each supported
 * codec.
 */
struct pjmedia_codec_desc
{
    pjmedia_codec_info	    info;	/**< Codec info.	    */
    pjmedia_codec_id	    id;		/**< Fully qualified name   */
    pjmedia_codec_priority  prio;	/**< Priority.		    */
    pjmedia_codec_factory  *factory;	/**< The factory.	    */
    pjmedia_codec_default_param *param; /**< Default codecs 
					     parameters.	    */
};


/**
 * The declaration for codec manager. Application doesn't normally need
 * to see this declaration, but nevertheless this declaration is needed
 * by media endpoint to instantiate the codec manager.
 */
typedef struct pjmedia_codec_mgr
{
    /** Media endpoint instance. */
    pj_pool_factory		*pf;

    /** Codec manager pool. */
    pj_pool_t			*pool;

    /** Codec manager mutex. */
    pj_mutex_t			*mutex;

    /** List of codec factories registered to codec manager. */
    pjmedia_codec_factory	 factory_list;

    /** Number of supported codecs. */
    unsigned			 codec_cnt;

    /** Array of codec descriptor. */
    struct pjmedia_codec_desc	 codec_desc[PJMEDIA_CODEC_MGR_MAX_CODECS];

} pjmedia_codec_mgr;



/**
 * Initialize codec manager. Normally this function is called by pjmedia
 * endpoint's initialization code.
 *
 * @param mgr	    Codec manager instance.
 * @param pf	    Pool factory instance.
 *
 * @return	    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) pjmedia_codec_mgr_init(pjmedia_codec_mgr *mgr, 
					    pj_pool_factory *pf);


/**
 * Destroy codec manager. Normally this function is called by pjmedia
 * endpoint's deinitialization code.
 *
 * @param mgr	    Codec manager instance.
 *
 * @return	    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) pjmedia_codec_mgr_destroy(pjmedia_codec_mgr *mgr);


/** 
 * Register codec factory to codec manager. This will also register
 * all supported codecs in the factory to the codec manager.
 *
 * @param mgr	    The codec manager instance. Application can get the
 *		    instance by calling #pjmedia_endpt_get_codec_mgr().
 * @param factory   The codec factory to be registered.
 *
 * @return	    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) 
pjmedia_codec_mgr_register_factory( pjmedia_codec_mgr *mgr,
				    pjmedia_codec_factory *factory);

/**
 * Unregister codec factory from the codec manager. This will also
 * remove all the codecs registered by the codec factory from the
 * codec manager's list of supported codecs. This function should
 * only be called by the codec implementers and not by application.
 *
 * @param mgr	    The codec manager instance, use
 * 			#pjmedia_endpt_get_codec_mgr().
 * @param factory   The codec factory to be unregistered.
 *
 * @return	    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) 
pjmedia_codec_mgr_unregister_factory( pjmedia_codec_mgr *mgr, 
				      pjmedia_codec_factory *factory);

/**
 * Enumerate all supported codecs that have been registered to the
 * codec manager by codec factories.
 *
 * @param mgr	    The codec manager instance. Application can get the
 *		    instance by calling #pjmedia_endpt_get_codec_mgr().
 * @param count	    On input, specifies the number of elements in
 *		    the array. On output, the value will be set to
 *		    the number of elements that have been initialized
 *		    by this function.
 * @param info	    The codec info array, which contents will be 
 *		    initialized upon return.
 * @param prio	    Optional pointer to receive array of codec priorities.
 *
 * @return	    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) pjmedia_codec_mgr_enum_codecs( pjmedia_codec_mgr *mgr, 
						    unsigned *count, 
						    pjmedia_codec_info info[],
						    unsigned *prio);

/**
 * Get codec info for the specified static payload type. Note that
 * this can only find codec with static payload types. This function can
 * be used to find codec info for a payload type inside SDP which doesn't
 * have the corresponding rtpmap attribute.
 *
 * @param mgr	    The codec manager instance. Application can get the
 *		    instance by calling #pjmedia_endpt_get_codec_mgr().
 * @param pt	    Static payload type/number.
 * @param inf	    Pointer to receive codec info.
 *
 * @return	    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) 
pjmedia_codec_mgr_get_codec_info( pjmedia_codec_mgr *mgr,
				  unsigned pt,
				  const pjmedia_codec_info **inf);

/**
 * Convert codec info struct into a unique codec identifier.
 * A codec identifier looks something like "L16/44100/2".
 *
 * @param info	    The codec info
 * @param id	    Buffer to put the codec info string.
 * @param max_len   The length of the buffer.
 *
 * @return	    The null terminated codec info string, or NULL if
 *		    the buffer is not long enough.
 */
PJ_DECL(char*) pjmedia_codec_info_to_id(const pjmedia_codec_info *info,
				        char *id, unsigned max_len );


/**
 * Find codecs by the unique codec identifier. This function will find
 * all codecs that match the codec identifier prefix. For example, if
 * "L16" is specified, then it will find "L16/8000/1", "L16/16000/1",
 * and so on, up to the maximum count specified in the argument.
 *
 * @param mgr	    The codec manager instance. Application can get the
 *		    instance by calling #pjmedia_endpt_get_codec_mgr().
 * @param codec_id  The full codec ID or codec ID prefix. If an empty
 *		    string is given, it will match all codecs.
 * @param count	    Maximum number of codecs to find. On return, it
 *		    contains the actual number of codecs found.
 * @param p_info    Array of pointer to codec info to be filled. This
 *		    argument may be NULL, which in this case, only
 *		    codec count will be returned.
 * @param prio	    Optional array of codec priorities.
 *
 * @return	    PJ_SUCCESS if at least one codec info is found.
 */
PJ_DECL(pj_status_t) 
pjmedia_codec_mgr_find_codecs_by_id( pjmedia_codec_mgr *mgr,
				     const pj_str_t *codec_id,
				     unsigned *count,
				     const pjmedia_codec_info *p_info[],
				     unsigned prio[]);


/**
 * Set codec priority. The codec priority determines the order of
 * the codec in the SDP created by the endpoint. If more than one codecs
 * are found with the same codec_id prefix, then the function sets the
 * priorities of all those codecs.
 *
 * @param mgr	    The codec manager instance. Application can get the
 *		    instance by calling #pjmedia_endpt_get_codec_mgr().
 * @param codec_id  The full codec ID or codec ID prefix. If an empty
 *		    string is given, it will match all codecs.
 * @param prio	    Priority to be set. The priority can have any value
 *		    between 1 to 255. When the priority is set to zero,
 *		    the codec will be disabled.
 *
 * @return	    PJ_SUCCESS if at least one codec info is found.
 */
PJ_DECL(pj_status_t)
pjmedia_codec_mgr_set_codec_priority(pjmedia_codec_mgr *mgr, 
				     const pj_str_t *codec_id,
				     pj_uint8_t prio);


/**
 * Get default codec param for the specified codec info.
 *
 * @param mgr	    The codec manager instance. Application can get the
 *		    instance by calling #pjmedia_endpt_get_codec_mgr().
 * @param info	    The codec info, which default parameter's is being
 *		    queried.
 * @param param	    On return, will be filled with the default codec
 *		    parameter.
 *
 * @return	    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) 
pjmedia_codec_mgr_get_default_param( pjmedia_codec_mgr *mgr,
				     const pjmedia_codec_info *info,
				     pjmedia_codec_param *param );


/**
 * Set default codec param for the specified codec info.
 *
 * @param mgr	    The codec manager instance. Application can get the
 *		    instance by calling #pjmedia_endpt_get_codec_mgr().
 * @param info	    The codec info, which default parameter's is being
 *		    updated.
 * @param param	    The new default codec parameter. Set to NULL to reset
 *		    codec parameter to library default settings.
 *
 * @return	    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) 
pjmedia_codec_mgr_set_default_param( pjmedia_codec_mgr *mgr,
				     const pjmedia_codec_info *info,
				     const pjmedia_codec_param *param );


/**
 * Request the codec manager to allocate one instance of codec with the
 * specified codec info. The codec will enumerate all codec factories
 * until it finds factory that is able to create the specified codec.
 *
 * @param mgr	    The codec manager instance. Application can get the
 *		    instance by calling #pjmedia_endpt_get_codec_mgr().
 * @param info	    The information about the codec to be created.
 * @param p_codec   Pointer to receive the codec instance.
 *
 * @return	    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) 
pjmedia_codec_mgr_alloc_codec( pjmedia_codec_mgr *mgr, 
			       const pjmedia_codec_info *info,
			       pjmedia_codec **p_codec);

/**
 * Deallocate the specified codec instance. The codec manager will return
 * the instance of the codec back to its factory.
 *
 * @param mgr	    The codec manager instance. Application can get the
 *		    instance by calling #pjmedia_endpt_get_codec_mgr().
 * @param codec	    The codec instance.
 *
 * @return	    PJ_SUCESS on success.
 */
PJ_DECL(pj_status_t) pjmedia_codec_mgr_dealloc_codec(pjmedia_codec_mgr *mgr, 
						     pjmedia_codec *codec);



/** 
 * 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_INLINE(pj_status_t) pjmedia_codec_init( pjmedia_codec *codec, 
					   pj_pool_t *pool )
{
    return (*codec->op->init)(codec, 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_INLINE(pj_status_t) pjmedia_codec_open( pjmedia_codec *codec, 
					   pjmedia_codec_param *param )
{
    return (*codec->op->open)(codec, 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_INLINE(pj_status_t) pjmedia_codec_close( pjmedia_codec *codec )
{
    return (*codec->op->close)(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_INLINE(pj_status_t) pjmedia_codec_modify(pjmedia_codec *codec, 
					    const pjmedia_codec_param *param)
{
    return (*codec->op->modify)(codec, 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_INLINE(pj_status_t) pjmedia_codec_parse( pjmedia_codec *codec,
					    void *pkt,
					    pj_size_t pkt_size,
					    const pj_timestamp *timestamp,
					    unsigned *frame_cnt,
					    pjmedia_frame frames[] )
{
    return (*codec->op->parse)(codec, pkt, pkt_size, timestamp,
			       frame_cnt, frames);
}


/** 
 * Instruct the codec to encode the specified input frame. The input
 * PCM samples MUST have ptime that is multiplication of 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_INLINE(pj_status_t) pjmedia_codec_encode( 
					pjmedia_codec *codec, 
					const struct pjmedia_frame *input,
					unsigned out_size, 
					struct pjmedia_frame *output )
{
    return (*codec->op->encode)(codec, input, out_size, 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_INLINE(pj_status_t) pjmedia_codec_decode( 
					pjmedia_codec *codec, 
					const struct pjmedia_frame *input,
					unsigned out_size, 
					struct pjmedia_frame *output )
{
    return (*codec->op->decode)(codec, input, out_size, 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_INLINE(pj_status_t) pjmedia_codec_recover( pjmedia_codec *codec,
					      unsigned out_size,
					      struct pjmedia_frame *output )
{
    if (codec->op && codec->op->recover)
	return (*codec->op->recover)(codec, out_size, output);
    else
	return PJ_ENOTSUP;
}


/**
 * @}
 */

/**
 * @defgroup PJMEDIA_CODEC_CODECS Supported codecs
 * @ingroup PJMEDIA_CODEC
 * @brief Documentation about individual codec supported by PJMEDIA
 * @{
 * Please see the APIs provided by the individual codecs below.
 */
/**
 * @}
 */




PJ_END_DECL


#endif	/* __PJMEDIA_CODEC_H__ */