= Using Intel Integrated Performance Primitive (IPP) with PJMEDIA =

'''Table of Contents'''
[[PageOutline(2-3,,inline)]]

Intel® Integrated Performance Primitives (Intel® IPP) is an extensive library of multi-core-ready, highly optimized software functions for multimedia data processing, and communications applications.

The Intel IPP can be used with PJMEDIA library to provide the following codecs:

 || '''Codec''' || '''Bitrate (Kbps)''' || '''Clock rate/'''[[BR]]'''frame ptime''' || '''default'''[[BR]]'''frames/pkt''' || '''default'''[[BR]]'''bitrate''' || '''VAD/DTX'''  || '''PLC'''      || '''Note''' ||
 || '''AMR NB'''     || 4.75 to 12.2           || 8000/160      || 4 || 5900  || internal       || internal       ||                  ||
 || '''AMR WB'''     || 6.6 to 23.85           || 16000/320     || 1 || 15850 || internal       || internal       ||                  ||
 || '''G.722.1'''    || 16, 24, 32, 40         || 16000/320     || 1 || 16000 || pjmedia        || internal       ||                  ||
 || '''G.723.1'''    || 5.3, 6.3               || 8000/240      || 1 || 5300  || internal       || internal       ||                  ||
 || '''G.726'''      || 16, 24, 32, 40         || 8000/80       || 2 || -     || pjmedia        || pjmedia        || The bitrate is negotiated in SDP ||
 || '''G.728'''      || 16                     || 8000/80       || 2 || 16000 || pjmedia        || internal       ||                  ||
 || '''G.729A'''     || 8                      || 8000/80       || 2 || 8000  || pjmedia        || internal       || 1) G.729 VAD (Annex B) is currently disabled.[[BR]] 2) Annex D and Annex E is supported for receive direction. ||

[[BR]]

== Requirements ==

The following are required:
 * PJSIP version 1.0-rc1 or above
 * Intel IPP library for your platform
 * Intel IPP samples

We tested with Intel IPP version 5.3. You may be able to use different Intel IPP version with PJMEDIA, however we have not tested this. 

Note that the use of Intel IPP may require license, both from Intel and the parties who own the royalty of the codec.

[[BR]]

== Installation ==

=== Windows Instructions ===

==== Download and install IPP and IPP samples ====

 1. Download Intel IPP and Intel IPP samples from http://www.intel.com/cd/software/products/asmo-na/eng/302910.htm
 1. Run the Intel IPP installer (e.g. ''w_ipp_ia32_p_5.3.3.082.exe''). The default installation will install it to {{{C:\Program Files\Intel\IPP\5.3.3.082}}} folder, and this is the folder that will be referred to by this tutorial.
 1. Unzip the Intel IPP samples (e.g. ''w_ipp-samples_p_5.3.095.zip'') to a folder. This tutorial assumes that the samples are installed in {{{C:\ipp-samples}}}.

==== Build the IPP samples ====
 1. Go to the IPP samples unzipped folder (e.g. {{{C:\ipp-samples}}}).
 1. Go to {{{speech-codecs}}} folder.
 1. Open the {{{readme.htm}}} file, and follow the instructions there to build the samples from the source.

Once the build process done, you should have '''{{{usc.lib}}}''' file somewhere inside {{{speech-codecs\bin}}} directory (in my case, it's in {{{C:\ipp-samples\speech-codecs\bin\win32_cl9\lib}}} folder).

If you have any problems with installing and/or building the IPP or IPP samples, please read the documentation or contact Intel for support.

==== Configure Visual Studio ====

 1. Add Intel IPP include and library path to Visual Studio paths. For example if 32bit Intel IPP is installed in {{{C:\Program Files\Intel\IPP\5.3.3.082\ia32}}} directory:
       - add {{{C:\Program Files\Intel\IPP\5.3.3.082\ia32\include}}} to the include path
       - add {{{C:\Program Files\Intel\IPP\5.3.3.082\ia32\stublib}}} to the library path
 1. Add Intel IPP samples include and library path to Visual Studio directory options. For example, if Intel IPP samples are in {{{C:\ipp-samples}}}:
    - add {{{C:\ipp-samples\speech-codecs\core\usc\include}}} to the include path
    - add {{{C:\ipp-samples\speech-codecs\bin\win32_cl9\lib}}} to the library path

[[BR]]

== PJMEDIA Configuration ==

=== Enable IPP Support ===

By default, IPP support is disabled in PJMEDIA. To enable IPP support, declare the following in your {{{config.site.h}}}:

 {{{
#define PJMEDIA_HAS_INTEL_IPP	1
 }}}

=== Enable/Disable Individual IPP Codec ===

Once IPP support is enabled, by default all IPP codecs are enabled. To disable parcular codecs, use the following constructs:

 {{{
#define PJMEDIA_HAS_INTEL_IPP_CODEC_AMR     0
#define PJMEDIA_HAS_INTEL_IPP_CODEC_AMRWB   0
#define PJMEDIA_HAS_INTEL_IPP_CODEC_G729    0
#define PJMEDIA_HAS_INTEL_IPP_CODEC_G723_1  0
#define PJMEDIA_HAS_INTEL_IPP_CODEC_G726    0
#define PJMEDIA_HAS_INTEL_IPP_CODEC_G728    0
#define PJMEDIA_HAS_INTEL_IPP_CODEC_G722_1  0
 }}}

=== Linking Options ===

By default, PJMEDIA will automatically link with Intel IPP libraries when Visual Studio is used. This is done by using using {{{#pragma comment(lib)}}} constructs in the source code. This is convenient, however it will only link with the stub libraries and the Intel IPP DLL's will be required when distributing the application.

If application wants to link with the different types of the Intel IPP libraries (for example, the static libraries), it must set {{{PJMEDIA_AUTO_LINK_IPP_LIBS}}} option to zero and specify the Intel IPP libraries in the application's input library specification manually.

Example:
 {{{
#define PJMEDIA_AUTO_LINK_IPP_LIBS  0
 }}}



[[BR]]

== Using in Application ==

=== Codec Registration ===

Before application can use any of the IPP codecs above, the IPP codec factory must be registered to the codec manager. If application is using [http://www.pjsip.org/pjsip/docs/html/group__PJSUA__LIB.htm PJSUA-LIB], this will be done automatically by PJSUA-LIB. If application is using [http://www.pjsip.org/pjmedia/docs/html/index.htm PJMEDIA] directly, then it must register the IPP codec factory by calling:

 {{{
     pjmedia_codec_ipp_init(media_endpt);
 }}}


=== Codec Settings ===

Codec settings are managed by setting the appropriate field in {{{settings}}} part of [http://www.pjsip.org/pjmedia/docs/html/structpjmedia__codec__param.htm pjmedia_codec_param] as usual.


[[BR]]

== Open Issues ==

=== Bitrate Selection ===

For codecs that support multiple bitrates (such as G.723.1 and AMR), the encoding bitrate is currently selected by setting [http://www.pjsip.org/pjmedia/docs/html/structpjmedia__codec__param.htm pjmedia_codec_param.info.avg_bps] field. This mechanism currently contradicts the normal convention of not modifying {{{pjmedia_codec_param.info}}} part.

=== Bitrate negotiation for G.722.1 and G.726 ===

SDP negotiation for selecting the appropriate bitrate for these codecs is currently not supported.

=== G.729 Annex B ===

This currently is not supported, and instead the usual PJMEDIA VAD/DTX is used. This should be compatible with G.729 though.

=== AMR Options ===

Negotiation of various AMR options in SDP is currently not supported. The AMR mode is locked to bandwidth-optimized, and when AMR with octet-aligned packet is received, the behavior is undefined.

=== Linux Support ===

Currently IPP integration is not supported by the autoconf script. You must add the appropriate CFLAGS and LDFLAGS in {{{user.mak}}} file in order to use IPP.

=== MacOS X Support ===

Although IPP is said to be supported for MacOS X (Intel), we don't know yet how to configure this support.