PJSIP Version 2.0 Release Notes
Table of Contents
- New Features
This document explains in brief the new features, changes, and porting guide in/for PJSIP version 2.0. For a complete ticket list applicable to 2.0 see the following milestones:
Video support is a new major feature. For this release it is available on Windows, Mac OS X, and Linux.
- Supported video devices:
- Simple Direct Media Layer (SDL) (Windows, Mac OS X, Linux, etc.)
- DirectShow (Windows)
- QuickTime (MacOS X)
- Video4Linux4 (Linux)
- DirectShow (Windows)
- Color bar (all platforms)
- Supported codecs:
- H.263-1998 (with ffmpeg)
- H.264 (with ffmpeg or libx264
- video device port to provide timing for video devices (analogous to sound device port)
- media format conversion framework (converter.h) supporting multiple backend APIs:
- ffmpeg's libswscale backend API implementation
- video codec framework (vid_codec.h) supporting multiple backend APIs:
- ffmpeg's libavcodec backend API implementation
- AVI file splitter/reader component (aviplayer.h)
On Demand Media Transport
Media transports are now created on demand. Rationale is given in #539. Media transport setting is now part of account setting (instead of global setting). Idle timer is used to keep media transports alive and close them after idling for some time. The idle period and number of transports that are allowed to be idling are settable.
For incoming calls, the "on_incoming_call()" callback is now called before media transport is created, to allow application to reject the call cheaply. The media transport will be created as soon as the callback returns, as long as the call is not disconnected. The media transport creation may take a while to complete (for example, waiting for candidates gathering for ICE media transports). If application sends 183/Progress or 200/OK to the call while the media transport creation is in progress, the response will be queued internally.
For outgoing calls, the INVITE request will be delayed until media transport is ready.
Third Party Media Support
Starting with PJSIP 2.0, support for integrating third party media stack into PJSUA-LIB was added. By following the steps outlined in Integrating Third Party Media Stack into PJSUA-LIB, application can use third party media stack to perform audio and video functionality while still making use of the full SIP, NAT, and security (including SRTP) features provided by PJSUA-LIB API.
- Event framework
- sipecho: Loops back peer's media (audio and/or video), and supports call hold too. It also works as a simple registrar, if peer needs it.
- vidgui: Qt based video GUI sample, to illustrate integration of PJSIP video framework to GUI apps.
Major changes are listed below. There also various header file changes, especially in PJMEDIA.
- Dynamically create media transports
- Support for multiple medias in call,
- Support for video (preview, windows ops, devs, etc.)
- Refactor source code to support third party media library
- Internal PJSUA call & media structures and algorithms have been refactored.
- Changed: As now call can have multiple media streams, e.g: M audio streams and N video streams, pjsua_call_info also has array of media info. Check the call info documentation here for details.
SRTP optional mode with duplicated media
- Deprecated: pjsua_acc_config::srtp_optional_dup_offer and pjsua_config::srtp_optional_dup_offer, these settings have been deprecated and will be ignored (if it is set).
- Removed: pjsua_media_transports_create and pjsua_media_transports_attach, due to dynamic media transport creation (see #539).
- Removed: pjsua_call_get_media_transport().
- New: pjsua_call_get_med_transport_info().
- Removed: pjsua_call_get_media_session().
- Changed: "session" parameter in on_stream_created() and on_stream_destroyed() callbacks has been replaced by "stream".
New PJSUA APIs for video
- New: pjsua_call_setting.
- New: PJSUA-API Video,
- New: PJSUA call APIs for video stream manipulation such as pjsua_call_set_vid_strm(), pjsua_call_vid_stream_is_running(), pjsua_call_get_vid_stream_idx()
See also PJSUA-LIB documentation.
Containing all information needed to completely describe a media.
- Changed: pjmedia_format — it is now virtually able to describe any media types (in 1.x it was containing extended info for audio format). Here are the core contents:
- Format ID — Specifies the audio sample or video pixel format. Enumeration of some well known formats IDs is defined in pjmedia_format_id.
- Media type — The top-most type of the media, as an information.
- Format detail — Detail section to describe the media. As the details are different among media types, this field is declared as union and pjmedia_format_detail_type is introduced to recognize the content. Currently there are two predefined structures:
- New: Video format helper:
- pjmedia_video_format_info — Information to describe a raw video format, such as RGB/YUV color model, number of bits per pixel, planar/packed data representation, and pointer to function to get real-time information of a raw video format (such as buffer size needed for a picture, byte size of a picture line, pointer and buffer size of each plane).
- pjmedia_video_apply_fmt_param — Information to apply a raw video format against size and buffer information, and get additional information from it. To do that, application fills up the input fields of this structure, and give this structure to apply_fmt() function of pjmedia_video_format_info structure.
Check the media format documentation here for details.
New video components in PJMEDIA
See also PJMEDIA documentation.
- Removed: samples_per_frame, which was used in many PJMEDIA components and functions. Generally, application can now use PJMEDIA_AFD_SAMPLES_PER_FRAME(audio-format-detail) to get the same result.
- Changed: All fields in the port info that desribe the media format have been removed and replaced by pjmedia_format. Check the port info documentation here for details.
put_frame() callback of pjmedia_port
- Changed: Removed const qualifier from the frame argument, this is to accomodate in-place media processing by PJMEDIA port.
- Sample warnings in building application after upgrading from 1.x to 2.0:
../src/pjmedia/bidirectional.c: In function ‘put_frame’: ../src/pjmedia/bidirectional.c:39: warning: passing argument 2 of ‘pjmedia_port_put_frame’ discards qualifiers from pointer target type ../include/pjmedia/port.h:334: note: expected ‘struct pjmedia_frame *’ but argument is of type ‘const struct pjmedia_frame *’ ../src/pjmedia/bidirectional.c:70: warning: assignment from incompatible pointer type
- Removed: pjmedia_session. Now media streams must be managed directly by application.
.. --disable-video Disable video feature --disable-sdl Disable SDL (default: not disabled) --disable-ffmpeg Disable ffmpeg (default: not disabled) --disable-v4l2 Disable Video4Linux2 (default: not disabled) --with-sdl=DIR Specify alternate libSDL prefix --with-ffmpeg=DIR Specify alternate FFMPEG prefix --with-ipp=DIR Specify the Intel IPP location ..
Visual Studio 6
Support for Visual Studio 6 has been removed.