/* $Id$ */ /* * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) * Copyright (C) 2003-2008 Benny Prijono * * 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 #include #include #include 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 open 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 setting 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 ¶m); // 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, ¶m ); \endcode * * * @subsection enc_dec_codec Encoding and Decoding Media Frames * * Application encodes and decodes media frames by calling * encode and decode 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 recover * member of the codec's "virtual" function table (#pjmedia_codec_op). * * If the codec's algorithm supports PLC, the recover 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 close 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 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 */ unsigned max_rx_frame_size; /**< Maximum frame size */ 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; /** * 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, 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__ */