Group PJMEDIA_CODEC

group PJMEDIA_CODEC

Media codec framework and management.

Codec Management

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().

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().

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.

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.

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.

Using the Codec Framework

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:

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 );

Initializing Codec

Once codec is allocated, application needs to initialize the codec by calling 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:

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 );

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).

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 Packet Lost Concealment (PLC) implementation.

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().

Defines

PJMEDIA_CODEC_MGR_MAX_CODECS

Declare maximum codecs

Typedefs

typedef char pjmedia_codec_id[32]

Codec identification (e.g. “pcmu/8000/1”). See Codec Identification for more info.

typedef struct pjmedia_codec_default_param pjmedia_codec_default_param

Opaque declaration of default codecs parameters.

Enums

enum pjmedia_rtp_pt

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.

Values:

enumerator PJMEDIA_RTP_PT_PCMU

audio PCMU

enumerator PJMEDIA_RTP_PT_G721

audio G721 (old def for G726-32)

enumerator PJMEDIA_RTP_PT_GSM

audio GSM

enumerator PJMEDIA_RTP_PT_G723

audio G723

enumerator PJMEDIA_RTP_PT_DVI4_8K

audio DVI4 8KHz

enumerator PJMEDIA_RTP_PT_DVI4_16K

audio DVI4 16Khz

enumerator PJMEDIA_RTP_PT_LPC

audio LPC

enumerator PJMEDIA_RTP_PT_PCMA

audio PCMA

enumerator PJMEDIA_RTP_PT_G722

audio G722

enumerator PJMEDIA_RTP_PT_L16_2

audio 16bit linear 44.1KHz stereo

enumerator PJMEDIA_RTP_PT_L16_1

audio 16bit linear 44.1KHz mono

enumerator PJMEDIA_RTP_PT_QCELP

audio QCELP

enumerator PJMEDIA_RTP_PT_CN

audio Comfort Noise

enumerator PJMEDIA_RTP_PT_MPA

audio MPEG1/MPEG2 elemetr. streams

enumerator PJMEDIA_RTP_PT_G728

audio G728

enumerator PJMEDIA_RTP_PT_DVI4_11K

audio DVI4 11.025KHz mono

enumerator PJMEDIA_RTP_PT_DVI4_22K

audio DVI4 22.050KHz mono

enumerator PJMEDIA_RTP_PT_G729

audio G729

enumerator PJMEDIA_RTP_PT_CELB

video/comb Cell-B by Sun (RFC2029)

enumerator PJMEDIA_RTP_PT_JPEG

video JPEG

enumerator PJMEDIA_RTP_PT_NV

video NV by nv program by Xerox

enumerator PJMEDIA_RTP_PT_H261

video H261

enumerator PJMEDIA_RTP_PT_MPV

video MPEG1 or MPEG2 elementary

enumerator PJMEDIA_RTP_PT_MP2T

video MPEG2 transport

enumerator PJMEDIA_RTP_PT_H263

video H263

enumerator PJMEDIA_RTP_PT_DYNAMIC

start of dynamic RTP payload

enum pjmedia_codec_priority

Specify these values to set the codec priority, by calling pjmedia_codec_mgr_set_codec_priority().

Values:

enumerator PJMEDIA_CODEC_PRIO_HIGHEST

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.

enumerator PJMEDIA_CODEC_PRIO_NEXT_HIGHER

This priority will put the codec as the next codec after codecs with this same priority.

enumerator PJMEDIA_CODEC_PRIO_NORMAL

This is the initial codec priority when it is registered to codec manager by codec factory.

enumerator PJMEDIA_CODEC_PRIO_LOWEST

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.

enumerator PJMEDIA_CODEC_PRIO_DISABLED

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.

Functions

pjmedia_codec_param *pjmedia_codec_param_clone(pj_pool_t *pool, const pjmedia_codec_param *src)

Duplicate codec parameter.

Parameters

  • pool – The pool.

  • src – The codec parameter to be duplicated.

Returns

Duplicated codec parameter.

pj_status_t pjmedia_codec_mgr_init(pjmedia_codec_mgr *mgr, pj_pool_factory *pf)

Initialize codec manager. Normally this function is called by pjmedia endpoint’s initialization code.

Parameters

  • mgr – Codec manager instance.

  • pf – Pool factory instance.

Returns

PJ_SUCCESS on success.

pj_status_t pjmedia_codec_mgr_destroy(pjmedia_codec_mgr *mgr)

Destroy codec manager. Normally this function is called by pjmedia endpoint’s deinitialization code.

Parameters

mgr – Codec manager instance.

Returns

PJ_SUCCESS on success.

pj_status_t pjmedia_codec_mgr_register_factory(pjmedia_codec_mgr *mgr, pjmedia_codec_factory *factory)

Register codec factory to codec manager. This will also register all supported codecs in the factory to the codec manager.

Parameters

  • mgr – The codec manager instance. Application can get the instance by calling pjmedia_endpt_get_codec_mgr().

  • factory – The codec factory to be registered.

Returns

PJ_SUCCESS on success.

pj_status_t pjmedia_codec_mgr_unregister_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.

Parameters
Returns

PJ_SUCCESS on success.

pj_status_t pjmedia_codec_mgr_enum_codecs(pjmedia_codec_mgr *mgr, unsigned *count, pjmedia_codec_info info[], unsigned *prio)

Enumerate all supported codecs that have been registered to the codec manager by codec factories.

Parameters

  • mgr – The codec manager instance. Application can get the instance by calling pjmedia_endpt_get_codec_mgr().

  • 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.

  • info – The codec info array, which contents will be initialized upon return.

  • prio – Optional pointer to receive array of codec priorities.

Returns

PJ_SUCCESS on success.

pj_status_t pjmedia_codec_mgr_get_codec_info(pjmedia_codec_mgr *mgr, unsigned pt, const pjmedia_codec_info **inf)

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.

Parameters

  • mgr – The codec manager instance. Application can get the instance by calling pjmedia_endpt_get_codec_mgr().

  • pt – Static payload type/number.

  • inf – Pointer to receive codec info.

Returns

PJ_SUCCESS on success.

char *pjmedia_codec_info_to_id(const pjmedia_codec_info *info, char *id, unsigned max_len)

Convert codec info struct into a unique codec identifier. A codec identifier looks something like “L16/44100/2”.

Parameters

  • info – The codec info

  • id – Buffer to put the codec info string.

  • max_len – The length of the buffer.

Returns

The null terminated codec info string, or NULL if the buffer is not long enough.

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[])

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.

Parameters

  • mgr – The codec manager instance. Application can get the instance by calling pjmedia_endpt_get_codec_mgr().

  • codec_id – The full codec ID or codec ID prefix. If an empty string is given, it will match all codecs.

  • count – Maximum number of codecs to find. On return, it contains the actual number of codecs found.

  • 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.

  • prio – Optional array of codec priorities.

Returns

PJ_SUCCESS if at least one codec info is found.

pj_status_t pjmedia_codec_mgr_set_codec_priority(pjmedia_codec_mgr *mgr, const pj_str_t *codec_id, pj_uint8_t 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.

Parameters

  • mgr – The codec manager instance. Application can get the instance by calling pjmedia_endpt_get_codec_mgr().

  • codec_id – The full codec ID or codec ID prefix. If an empty string is given, it will match all codecs.

  • 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.

Returns

PJ_SUCCESS if at least one codec info is found.

pj_status_t pjmedia_codec_mgr_get_default_param(pjmedia_codec_mgr *mgr, const pjmedia_codec_info *info, pjmedia_codec_param *param)

Get default codec param for the specified codec info.

Parameters

  • mgr – The codec manager instance. Application can get the instance by calling pjmedia_endpt_get_codec_mgr().

  • info – The codec info, which default parameter’s is being queried.

  • param – On return, will be filled with the default codec parameter.

Returns

PJ_SUCCESS on success.

pj_status_t pjmedia_codec_mgr_set_default_param(pjmedia_codec_mgr *mgr, const pjmedia_codec_info *info, const pjmedia_codec_param *param)

Set default codec param for the specified codec info.

Parameters

  • mgr – The codec manager instance. Application can get the instance by calling pjmedia_endpt_get_codec_mgr().

  • info – The codec info, which default parameter’s is being updated.

  • param – The new default codec parameter. Set to NULL to reset codec parameter to library default settings.

Returns

PJ_SUCCESS on success.

pj_status_t pjmedia_codec_mgr_alloc_codec(pjmedia_codec_mgr *mgr, const pjmedia_codec_info *info, pjmedia_codec **p_codec)

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.

Parameters

  • mgr – The codec manager instance. Application can get the instance by calling pjmedia_endpt_get_codec_mgr().

  • info – The information about the codec to be created.

  • p_codec – Pointer to receive the codec instance.

Returns

PJ_SUCCESS on success.

pj_status_t pjmedia_codec_mgr_dealloc_codec(pjmedia_codec_mgr *mgr, pjmedia_codec *codec)

Deallocate the specified codec instance. The codec manager will return the instance of the codec back to its factory.

Parameters
Returns

PJ_SUCESS on success.

pj_status_t pjmedia_codec_init(pjmedia_codec *codec, pj_pool_t *pool)

Initialize codec using the specified attribute.

Parameters

  • codec – The codec instance.

  • pool – Pool to use when the codec needs to allocate some memory.

Returns

PJ_SUCCESS on success.

pj_status_t pjmedia_codec_open(pjmedia_codec *codec, pjmedia_codec_param *param)

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).

Parameters

  • codec – The codec instance.

  • param – Codec initialization parameter.

Returns

PJ_SUCCESS on success.

pj_status_t pjmedia_codec_close(pjmedia_codec *codec)

Close and shutdown codec, releasing all resources allocated by this codec, if any.

Parameters

codec – The codec instance.

Returns

PJ_SUCCESS on success.

pj_status_t pjmedia_codec_modify(pjmedia_codec *codec, const pjmedia_codec_param *param)

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.

Parameters

  • codec – The codec instance.

  • param – The new codec parameter.

Returns

PJ_SUCCESS on success.

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[])

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).

Parameters

  • codec – The codec instance

  • pkt – The input packet.

  • pkt_size – Size of the packet.

  • timestamp – The timestamp of the first sample in the packet.

  • 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.

  • frames – On output, specifies the frames that have been detected in the packet.

Returns

PJ_SUCCESS on success.

pj_status_t pjmedia_codec_encode(pjmedia_codec *codec, const struct pjmedia_frame *input, unsigned out_size, struct pjmedia_frame *output)

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).

Parameters

  • codec – The codec instance.

  • input – The input frame.

  • out_size – The length of buffer in the output frame.

  • output – The output frame.

Returns

PJ_SUCCESS on success;

pj_status_t pjmedia_codec_decode(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.

Parameters

  • codec – The codec instance.

  • input – The input frame.

  • out_size – The length of buffer in the output frame.

  • output – The output frame.

Returns

PJ_SUCCESS on success;

pj_status_t pjmedia_codec_recover(pjmedia_codec *codec, unsigned out_size, struct pjmedia_frame *output)

Instruct the codec to recover a missing frame.

Parameters

  • codec – The codec instance.

  • out_size – The length of buffer in the output frame.

  • output – The output frame where generated signal will be placed.

Returns

PJ_SUCCESS on success;

struct pjmedia_codec_info
#include <codec.h>

Identification used to search for codec factory that supports specific codec specification.

Public Members

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.

struct pjmedia_codec_fmtp
#include <codec.h>

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.

Public Members

pj_uint8_t cnt

Number of parameters.

struct pjmedia_codec_fmtp::param param[PJMEDIA_CODEC_MAX_FMTP_CNT]

The parameters.

struct param

Public Members

pj_str_t name

Parameter name.

pj_str_t val

Parameter value.

struct pjmedia_codec_param
#include <codec.h>

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.

Public Members

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.

struct pjmedia_codec_param::[anonymous] info

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.

pj_uint8_t frm_per_pkt

Number of frames per packet.

unsigned vad

Voice Activity Detector.

unsigned cng

Comfort Noise Generator.

unsigned penh

Perceptual Enhancement

unsigned plc

Packet loss concealment

unsigned reserved

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?

struct pjmedia_codec_param::[anonymous] setting

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 pjmedia_codec_op
#include <codec.h>

This structure describes codec operations. Each codec MUST implement all of these functions.

Public Members

pj_status_t (*init)(pjmedia_codec *codec, pj_pool_t *pool)

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 (*open)(pjmedia_codec *codec, pjmedia_codec_param *param)

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 (*close)(pjmedia_codec *codec)

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 (*modify)(pjmedia_codec *codec, const pjmedia_codec_param *param)

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 (*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 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 (*encode)(pjmedia_codec *codec, const struct pjmedia_frame *input, unsigned out_size, struct pjmedia_frame *output)

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 (*decode)(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 (*recover)(pjmedia_codec *codec, 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;

struct pjmedia_codec
#include <codec.h>

This structure describes a codec instance.

Public Functions

PJ_DECL_LIST_MEMBER(struct pjmedia_codec)

Entries to put this codec instance in codec factory’s list.

Public Members

void *codec_data

Codec’s private data.

pjmedia_codec_factory *factory

Codec factory where this codec was allocated.

pjmedia_codec_op *op

Operations to codec.

struct pjmedia_codec_factory_op
#include <codec.h>

This structure describes operations that must be supported by codec factories.

Public Members

pj_status_t (*test_alloc)(pjmedia_codec_factory *factory, const pjmedia_codec_info *info)

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 (*default_attr)(pjmedia_codec_factory *factory, const pjmedia_codec_info *info, pjmedia_codec_param *attr)

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 (*enum_info)(pjmedia_codec_factory *factory, unsigned *count, pjmedia_codec_info codecs[])

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 (*alloc_codec)(pjmedia_codec_factory *factory, const pjmedia_codec_info *info, pjmedia_codec **p_codec)

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 (*dealloc_codec)(pjmedia_codec_factory *factory, pjmedia_codec *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 (*destroy)(void)

This callback will be called to deinitialize and destroy this factory.

struct pjmedia_codec_factory
#include <codec.h>

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.

Public Functions

PJ_DECL_LIST_MEMBER(struct pjmedia_codec_factory)

Entries to put this structure in the codec manager list.

Public Members

void *factory_data

The factory’s private data.

pjmedia_codec_factory_op *op

Operations to the factory.

struct pjmedia_codec_desc
#include <codec.h>

Codec manager maintains array of these structs for each supported codec.

Public Members

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.

struct pjmedia_codec_mgr
#include <codec.h>

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.

Public Members

pj_pool_factory *pf

Media endpoint instance.

pj_pool_t *pool

Codec manager pool.

pj_mutex_t *mutex

Codec manager mutex.

pjmedia_codec_factory factory_list

List of codec factories registered to codec manager.

unsigned codec_cnt

Number of supported codecs.

struct pjmedia_codec_desc codec_desc[32]

Array of codec descriptor.

unsigned dyn_codecs_cnt

Number of codecs with dynamic PT.

pj_str_t dyn_codecs[32]

Array of codec identifiers with dynamic PT.