Group PJMEDIA_CODEC

group PJMEDIA_CODEC

Media codec framework and management.

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:

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

enum pjmedia_codec_priority

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

Values:

PJMEDIA_CODEC_PRIO_HIGHEST = 255

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_NEXT_HIGHER = 254

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

PJMEDIA_CODEC_PRIO_NORMAL = 128

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

PJMEDIA_CODEC_PRIO_LOWEST = 1

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_DISABLED = 0

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.

Return

Duplicated codec parameter.

Parameters
  • pool: The pool.

  • src: The codec parameter to be duplicated.

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.

Return

PJ_SUCCESS on success.

Parameters
  • mgr: Codec manager instance.

  • pf: Pool factory instance.

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.

Return

PJ_SUCCESS on success.

Parameters
  • mgr: Codec manager instance.

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.

Return

PJ_SUCCESS on success.

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.

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.

Return

PJ_SUCCESS on success.

Parameters

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.

Return

PJ_SUCCESS on success.

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.

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.

Return

PJ_SUCCESS on success.

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.

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

Return

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

Parameters
  • info: The codec info

  • id: Buffer to put the codec info string.

  • max_len: The length of the buffer.

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.

Return

PJ_SUCCESS if at least one codec info is found.

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.

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.

Return

PJ_SUCCESS if at least one codec info is found.

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.

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.

Return

PJ_SUCCESS on success.

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.

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.

Return

PJ_SUCCESS on success.

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.

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.

Return

PJ_SUCCESS on success.

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.

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.

Return

PJ_SUCESS on success.

Parameters

pj_status_t pjmedia_codec_init(pjmedia_codec *codec, pj_pool_t *pool)

Initialize codec using the specified attribute.

Return

PJ_SUCCESS on success.

Parameters
  • codec: The codec instance.

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

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

Return

PJ_SUCCESS on success.

Parameters
  • codec: The codec instance.

  • param: Codec initialization parameter.

pj_status_t pjmedia_codec_close(pjmedia_codec *codec)

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

Return

PJ_SUCCESS on success.

Parameters
  • codec: The codec instance.

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

Return

PJ_SUCCESS on success.

Parameters
  • codec: The codec instance.

  • param: The new codec parameter.

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

Return

PJ_SUCCESS on success.

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.

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

Return

PJ_SUCCESS on success;

Parameters
  • codec: The codec instance.

  • input: The input frame.

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

  • output: The output frame.

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 in pjmedia_codec_param). Application can achieve this by parsing the packet into base frames before decoding each frame.

Return

PJ_SUCCESS on success;

Parameters
  • codec: The codec instance.

  • input: The input frame.

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

  • output: The output frame.

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

Instruct the codec to recover a missing frame.

Return

PJ_SUCCESS on success;

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.

struct pjmedia_codec_info
#include <codec.h>

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

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.

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.

struct pjmedia_codec_op
#include <codec.h>

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

struct pjmedia_codec
#include <codec.h>

This structure describes a codec instance.

struct pjmedia_codec_factory_op
#include <codec.h>

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

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.

struct pjmedia_codec_desc
#include <codec.h>

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

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.