@voipsdk/react-native-voipcloud 1.0.1 → 1.0.2

package/ios/VoipCloud.xcframework/ios-arm64/Headers/pjmedia/codec.h

@@ -0,0 +1,1192 @@
+/* 
+ * 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 is recommended not to be modified unless necessary.
+     * Note that application must be ready to handle cases when ptime
+     * denumerators are zero, since most codecs that only support integer
+     * ptime will leave these fields untouched.
+     */
+    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  */
+       unsigned    max_rx_frame_size;   /**< Maximum frame size             */
+       pj_uint16_t frm_ptime;           /**< Decoder frame ptime in msec.   */
+       pj_uint8_t  frm_ptime_denum;     /**< Decoder frame ptime denum, or
+                                             zero if ptime is integer.      */
+       pj_uint16_t enc_ptime;           /**< Encoder ptime, or zero if it's
+                                             equal to decoder ptime.        */
+       pj_uint8_t  enc_ptime_denum;     /**< Encoder frame ptime denum, or
+                                             zero if ptime is integer.      */
+       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 or modifying the codec.
+     */
+    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.         */
+        unsigned   packet_loss;     /**< Encoder's expected pkt loss %. */
+        unsigned   complexity;      /**< Encoder complexity, 0-10(max). */
+        pj_bool_t  cbr;             /**< Constant bit rate?             */
+    } setting;
+} pjmedia_codec_param;
+
+
+/**
+ * Duplicate codec parameter.
+ *
+ * @param pool      The pool.
+ * @param src       The codec parameter to be duplicated.
+ *
+ * @return          Duplicated codec parameter.
+ */
+PJ_DECL(pjmedia_codec_param*) pjmedia_codec_param_clone(
+                                        pj_pool_t *pool, 
+                                        const pjmedia_codec_param *src);
+
+
+/*
+ * 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/enc_ptime_denum,
+     * 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.
+     * Currently, only Opus codec supports changing key codec parameters
+     * such as bitrate and bandwidth, while other codecs may only be able to
+     * modify minor settings such as VAD or PLC.
+     *
+     * 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/info.frm_ptime_denum 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/info.frm_ptime_denum 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/info.frm_ptime_denum 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];
+
+    /** Number of codecs with dynamic PT. */
+    unsigned                     dyn_codecs_cnt;
+
+    /** Array of codec identifiers with dynamic PT. */
+    pj_str_t                     dyn_codecs[PJMEDIA_CODEC_MGR_MAX_CODECS];
+
+#if defined(PJMEDIA_RTP_PT_TELEPHONE_EVENTS) && \
+            PJMEDIA_RTP_PT_TELEPHONE_EVENTS != 0
+    /** Number of televent clockrates. */
+    unsigned                     televent_num;
+
+    /** Array of televent clockrates. */
+    unsigned                     televent_clockrates[8];
+#endif
+
+
+} 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.
+ * Currently, only Opus codec supports changing key codec parameters
+ * such as bitrate and bandwidth, while other codecs may only be able to
+ * modify minor settings such as VAD or PLC.
+ *
+ * @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/info.frm_ptime_denum 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/info.frm_ptime_denum 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/info.frm_ptime_denum 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.
+ */
+/**
+ * @}
+ */
+
+/*
+ * Internal functions.
+ */
+
+/**
+ * Internal: Get the array of codec identifiers that have dynamic PT.
+ * Note that the array also includes telephone events.
+ */
+pj_status_t pjmedia_codec_mgr_get_dyn_codecs(pjmedia_codec_mgr* mgr,
+                                             pj_int8_t *count,
+                                             pj_str_t dyn_codecs[]);
+
+/* Internal: Find a certain codec string in the dynamic codecs array.
+ * Return the index of the array if the string is found and set
+ * *found == PJ_TRUE. If the string is not found, returns -1 if found
+ * is specified, otherwise returns the index in the array where
+ * the particular string could be inserted so that the array remains
+ * sorted, and set *found == PJ_FALSE.
+ */
+int pjmedia_codec_mgr_find_codec(const pj_str_t dyn_codecs[],
+                                 unsigned count,
+                                 const pj_str_t *codec,
+                                 pj_bool_t *found);
+
+/* Internal: Insert a codec ID string into the dynamic codecs array and keep
+ * the array sorted.
+ */
+void pjmedia_codec_mgr_insert_codec(pj_pool_t *pool, pj_str_t dyn_codecs[],
+                                    unsigned *count, const pj_str_t *codec);
+
+PJ_END_DECL
+
+
+#endif  /* __PJMEDIA_CODEC_H__ */