Group PJMEDIA_VID_CODEC

group PJMEDIA_VID_CODEC

Defines

PJMEDIA_VID_CODEC_MAX_DEC_FMT_CNT
PJMEDIA_VID_CODEC_MAX_FPS_CNT
PJMEDIA_VID_CODEC_MGR_MAX_CODECS

Declare maximum codecs

Typedefs

typedef struct pjmedia_vid_codec_mgr pjmedia_vid_codec_mgr

Opaque declaration for codec manager.

Enums

enum pjmedia_vid_packing

This enumeration specifies the packetization property of video encoding process. The value is bitmask, and smaller value will have higher priority to be used.

Values:

enumerator PJMEDIA_VID_PACKING_UNKNOWN

This specifies that the packetization is unknown, or if nothing is supported.

enumerator PJMEDIA_VID_PACKING_PACKETS

This specifies that the result of video encoding process will be segmented into packets, which is suitable for RTP transmission. The maximum size of the packets is set in enc_mtu field of pjmedia_vid_codec_param.

enumerator PJMEDIA_VID_PACKING_WHOLE

This specifies that video encoding function will produce a whole or full frame from the source frame. This is normally used for encoding video for offline storage such as to an AVI file. The maximum size of the packets is set in enc_mtu field of pjmedia_vid_codec_param.

enum pjmedia_vid_frm_bit_info

Enumeration of video frame info flag for the bit_info field in the pjmedia_frame.

Values:

enumerator PJMEDIA_VID_FRM_KEYFRAME

The video frame is keyframe.

Functions

pjmedia_vid_codec_param *pjmedia_vid_codec_param_clone(pj_pool_t *pool, const pjmedia_vid_codec_param *src)

Duplicate video codec parameter.

Parameters:

  • pool – The pool.

  • src – The video codec parameter to be duplicated.

Returns:

Duplicated codec parameter.

pj_status_t pjmedia_vid_codec_mgr_create(pj_pool_t *pool, pjmedia_vid_codec_mgr **mgr)

Initialize codec manager. If there is no the default video codec manager, this function will automatically set the default video codec manager to the new codec manager instance. Normally this function is called by pjmedia endpoint’s initialization code.

Parameters:

  • pool – The pool instance.

  • mgr – The pointer to the new codec manager instance.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_vid_codec_mgr_destroy(pjmedia_vid_codec_mgr *mgr)

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

Parameters:

mgr – Codec manager instance. If NULL, it is the default codec manager instance will be destroyed.

Returns:

PJ_SUCCESS on success.

pjmedia_vid_codec_mgr *pjmedia_vid_codec_mgr_instance(void)

Get the default codec manager instance.

Returns:

The default codec manager instance or NULL if none.

void pjmedia_vid_codec_mgr_set_instance(pjmedia_vid_codec_mgr *mgr)

Set the default codec manager instance.

Parameters:

mgr – The codec manager instance.

pj_status_t pjmedia_vid_codec_mgr_register_factory(pjmedia_vid_codec_mgr *mgr, pjmedia_vid_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. If NULL, the default codec manager instance will be used.

  • factory – The codec factory to be registered.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_vid_codec_mgr_unregister_factory(pjmedia_vid_codec_mgr *mgr, pjmedia_vid_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.

Parameters:

  • mgr – The codec manager instance. If NULL, the default codec manager instance will be used.

  • factory – The codec factory to be unregistered.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_vid_codec_mgr_enum_codecs(pjmedia_vid_codec_mgr *mgr, unsigned *count, pjmedia_vid_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. If NULL, the default codec manager instance will be used.

  • 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_vid_codec_mgr_get_codec_info(pjmedia_vid_codec_mgr *mgr, unsigned pt, const pjmedia_vid_codec_info **info)

Get codec info for the specified payload type. The payload type must be static or locally defined in pjmedia_video_pt.

Parameters:

  • mgr – The codec manager instance. If NULL, the default codec manager instance will be used.

  • pt – The payload type/number.

  • info – Pointer to receive codec info.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_vid_codec_mgr_get_codec_info2(pjmedia_vid_codec_mgr *mgr, pjmedia_format_id fmt_id, const pjmedia_vid_codec_info **info)

Get codec info for the specified format ID.

Parameters:

  • mgr – The codec manager instance. If NULL, the default codec manager instance will be used.

  • fmt_id – Format ID. See pjmedia_format_id

  • info – Pointer to receive codec info.

Returns:

PJ_SUCCESS on success.

char *pjmedia_vid_codec_info_to_id(const pjmedia_vid_codec_info *info, char *id, unsigned max_len)

Convert codec info struct into a unique codec identifier. A codec identifier looks something like “H263/34”, where “H263” is the codec name and “34” is the (default) payload type.

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_vid_codec_mgr_find_codecs_by_id(pjmedia_vid_codec_mgr *mgr, const pj_str_t *codec_id, unsigned *count, const pjmedia_vid_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 “H26” is specified, then it will find “H263”, “H264”, and so on, up to the maximum count specified in the argument.

Parameters:

  • mgr – The codec manager instance. If NULL, the default codec manager instance will be used.

  • 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_vid_codec_mgr_set_codec_priority(pjmedia_vid_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. If NULL, the default codec manager instance will be used.

  • 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_vid_codec_mgr_get_default_param(pjmedia_vid_codec_mgr *mgr, const pjmedia_vid_codec_info *info, pjmedia_vid_codec_param *param)

Get default codec param for the specified codec info.

Parameters:

  • mgr – The codec manager instance. If NULL, the default codec manager instance will be used.

  • 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_vid_codec_mgr_set_default_param(pjmedia_vid_codec_mgr *mgr, const pjmedia_vid_codec_info *info, const pjmedia_vid_codec_param *param)

Set default codec param for the specified codec info.

Parameters:

  • mgr – The codec manager instance. If NULL, the default codec manager instance will be used.

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

  • param – The new default codec parameter. Note that encoding video codec resolution must be even numbers. Set to NULL to reset codec parameter to library default settings.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjmedia_vid_codec_mgr_alloc_codec(pjmedia_vid_codec_mgr *mgr, const pjmedia_vid_codec_info *info, pjmedia_vid_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. If NULL, the default codec manager instance will be used.

  • 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_vid_codec_mgr_dealloc_codec(pjmedia_vid_codec_mgr *mgr, pjmedia_vid_codec *codec)

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

Parameters:

  • mgr – The codec manager instance. If NULL, the default codec manager instance will be used.

  • codec – The codec instance.

Returns:

PJ_SUCESS on success.

pj_status_t pjmedia_vid_codec_init(pjmedia_vid_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_vid_codec_open(pjmedia_vid_codec *codec, pjmedia_vid_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 size or frame rate of the encoder format, as it may need to be negotiated with remote preferences via SDP fmtp).

Parameters:

  • codec – The codec instance.

  • param – Codec initialization parameter. Note that encoding video codec resolution must be even numbers.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjmedia_vid_codec_close(pjmedia_vid_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_vid_codec_modify(pjmedia_vid_codec *codec, const pjmedia_vid_codec_param *param)

Modify the codec parameter after the codec is opened. Note that not all codec backends support modifying parameters during runtime and only certain parameters can be changed.

Currently, only Video Toolbox and OpenH264 backends support runtime adjustment of encoding bitrate (avg_bps and max_bps).

Parameters:

  • codec – The codec instance.

  • param – The new codec parameter.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjmedia_vid_codec_get_param(pjmedia_vid_codec *codec, pjmedia_vid_codec_param *param)

Get the codec parameter after the codec is opened.

Parameters:

  • codec – The codec instance.

  • param – The codec parameter.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_vid_codec_encode_begin(pjmedia_vid_codec *codec, const pjmedia_vid_encode_opt *opt, const pjmedia_frame *input, unsigned out_size, pjmedia_frame *output, pj_bool_t *has_more)

Encode the specified input frame. The input MUST contain only one picture with the appropriate format as specified when opening the codec. Depending on the packing or packetization set in the packing param, the process may produce multiple encoded packets or payloads to represent the picture. This is true for example for PJMEDIA_VID_PACKING_PACKETS packing. In this case, the has_more field will be set to PJ_TRUE, and application should call pjmedia_vid_codec_encode_more() to get the remaining results from the codec.

Parameters:

  • codec – The codec instance.

  • opt – Optional encoding options.

  • input – The input frame.

  • out_size – The length of buffer in the output frame. This should be at least the same as the configured encoding MTU of the codec.

  • output – The output frame.

  • has_more – PJ_TRUE if more payloads are available; application should then call pjmedia_vid_codec_encode_more() to retrieve the remaining results.

Returns:

PJ_SUCCESS on success;

pj_status_t pjmedia_vid_codec_encode_more(pjmedia_vid_codec *codec, unsigned out_size, pjmedia_frame *output, pj_bool_t *has_more)

Retrieve more encoded packets/payloads from the codec. Application should call this function repeatedly until has_more flag is set to PJ_FALSE.

Parameters:

  • codec – The codec instance.

  • out_size – The length of buffer in the output frame. This should be at least the same as as the configured encoding MTU of the codec.

  • output – The output frame.

  • has_more – PJ_TRUE if more payloads are available, which in this case application should call encode_more() to retrieve them.

Returns:

PJ_SUCCESS on success;

pj_status_t pjmedia_vid_codec_decode(pjmedia_vid_codec *codec, pj_size_t pkt_count, pjmedia_frame packets[], unsigned out_size, pjmedia_frame *output)

Decode the input packets into one picture. If the packing is set to PJMEDIA_VID_PACKING_PACKETS when opening the codec, the codec is set to decode multiple encoded packets into one picture. These encoded packets are typically retrieved from the jitter buffer. If the packing is set to PJMEDIA_VID_PACKING_WHOLE, then this decode function can only accept one frame as the input.

Note that the decoded picture format may different to the configured setting (i.e. the format specified in the pjmedia_vid_codec_param when opening the codec), in this case the PJMEDIA_EVENT_FMT_CHANGED event will be emitted by the codec to notify the event. The codec parameter will also be updated, and application can query the format by using pjmedia_vid_codec_get_param().

Parameters:

  • codec – The codec instance.

  • pkt_count – Number of packets in the input.

  • packets – Array of input packets, each containing an encoded frame.

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

  • output – The output frame.

Returns:

PJ_SUCCESS on success;

pj_status_t pjmedia_vid_codec_recover(pjmedia_vid_codec *codec, unsigned out_size, pjmedia_frame *output)

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_vid_encode_opt
#include <vid_codec.h>

Encoding option.

Public Members

pj_bool_t force_keyframe

Flag to force the encoder to generate keyframe for the specified input frame. When this flag is set, application can verify the result by examining PJMEDIA_VID_FRM_KEYFRAME flag in the bit_info field of the output frame.

struct pjmedia_vid_codec_info
#include <vid_codec.h>

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

Public Members

pjmedia_format_id fmt_id

Encoded format ID

unsigned pt

Payload type

pj_str_t encoding_name

Encoding name

pj_str_t encoding_desc

Encoding desc

unsigned clock_rate

Clock rate

pjmedia_dir dir

Direction

unsigned dec_fmt_id_cnt

of supported encoding source

format IDs

pjmedia_format_id dec_fmt_id[8]

Supported encoding source format IDs

unsigned packings

Supported or requested packings, strategies, bitmask from pjmedia_vid_packing

unsigned fps_cnt

of supported frame-rates, can be

zero (support any frame-rate)

pjmedia_ratio fps[16]

Supported frame-rates

struct pjmedia_vid_codec_param
#include <vid_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_vid_codec_mgr_get_default_param() and modified using pjmedia_vid_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

pjmedia_dir dir

Direction

pjmedia_vid_packing packing

Packetization strategy.

pjmedia_format enc_fmt

Encoded format

pjmedia_codec_fmtp enc_fmtp

Encoder fmtp params

unsigned enc_mtu

MTU or max payload size setting

pjmedia_format dec_fmt

Decoded format

pjmedia_codec_fmtp dec_fmtp

Decoder fmtp params

pj_bool_t ignore_fmtp

Ignore fmtp params. If set to PJ_TRUE, the codec will apply format settings specified in enc_fmt and dec_fmt only.

struct pjmedia_vid_codec_op
#include <vid_codec.h>

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

Public Members

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

See pjmedia_vid_codec_init().

pj_status_t (*open)(pjmedia_vid_codec *codec, pjmedia_vid_codec_param *param)

See pjmedia_vid_codec_open().

pj_status_t (*close)(pjmedia_vid_codec *codec)

See pjmedia_vid_codec_close().

pj_status_t (*modify)(pjmedia_vid_codec *codec, const pjmedia_vid_codec_param *param)

See pjmedia_vid_codec_modify().

pj_status_t (*get_param)(pjmedia_vid_codec *codec, pjmedia_vid_codec_param *param)

See pjmedia_vid_codec_get_param().

pj_status_t (*encode_begin)(pjmedia_vid_codec *codec, const pjmedia_vid_encode_opt *opt, const pjmedia_frame *input, unsigned out_size, pjmedia_frame *output, pj_bool_t *has_more)

See pjmedia_vid_codec_encode_begin().

pj_status_t (*encode_more)(pjmedia_vid_codec *codec, unsigned out_size, pjmedia_frame *output, pj_bool_t *has_more)

See pjmedia_vid_codec_encode_more()

pj_status_t (*recover)(pjmedia_vid_codec *codec, unsigned out_size, pjmedia_frame *output)

See pjmedia_vid_codec_recover()

struct pjmedia_vid_codec
#include <vid_codec.h>

This structure describes a video codec instance. Codec implementers should use pjmedia_vid_codec_init() to initialize this structure with default values.

Forward declaration for video codec.

Public Functions

PJ_DECL_LIST_MEMBER(struct pjmedia_vid_codec)

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

Public Members

void *codec_data

Codec’s private data.

pjmedia_vid_codec_factory *factory

Codec factory where this codec was allocated.

pjmedia_vid_codec_op *op

Operations to codec.

struct pjmedia_vid_codec_factory_op
#include <vid_codec.h>

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

Public Members

pj_status_t (*test_alloc)(pjmedia_vid_codec_factory *factory, const pjmedia_vid_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_vid_codec_factory *factory, const pjmedia_vid_codec_info *info, pjmedia_vid_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_vid_codec_factory *factory, unsigned *count, pjmedia_vid_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_vid_codec_factory *factory, const pjmedia_vid_codec_info *info, pjmedia_vid_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_vid_codec_factory *factory, pjmedia_vid_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.

struct pjmedia_vid_codec_factory
#include <vid_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_vid_codec_factory)

Entries to put this structure in the codec manager list.

Public Members

void *factory_data

The factory’s private data.

pjmedia_vid_codec_factory_op *op

Operations to the factory.