Using Intel Integrated Performance Primitive (IPP) with PJMEDIA

Table of Contents

1. Requirements
2. Installation
   1. Windows Instructions
   2. Linux Instructions
3. PJMEDIA Configuration
   1. Enable IPP Support
   2. Enable/Disable? Individual IPP Codec
4. Static Linking
   1. Windows Instructions
   2. Linux Instructions
5. Using in Application
   1. Codec Registration
   2. Codec Settings
6. Setting DLL/Shared Library Path
   1. Setting up DLL Path
   2. Setting up LD_LIBRARY_PATH
7. Open Issues
   1. Bitrate Selection
   2. Bitrate negotiation for G.722.1 and G.726
   3. G.729 Annex B
   4. AMR Options
   5. MacOS X Support

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/ frame ptime	default frames/pkt	default 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. 2) Annex D and Annex E is supported for receive direction.

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.

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
2. 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.
3. 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).
2. Go to speech-codecs folder.
3. 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
2. 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

Linux 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
2. Extract the archive to a temporary folder and run the installer (e.g. ./install.sh). The default installation options will install it to "/opt/intel/ipp/" directory (e.g. "/opt/intel/ipp/5.3.1.062/ia32/").
3. Extract IPP samples to a directory (e.g. to "~/Desktop/ipp-samples").

Build the IPP samples

1. Go to the directory where IPP samples have been extracted (e.g. ~/Desktop/ipp-samples).
2. Go to speech-codecs folder.
3. 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 libusc.a file somewhere inside speech-codecs\bin directory (in my case, it's in ~/Desktop/ipp-samples/speech-codecs/bin/linux32_gcc3/lib directory).

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

Running "configure" with IPP support

The configure script needs to be invoked with IPP options in order to set up IPP include and library paths.

For this tutorial, we'll use two environment variables to hold the location of IPP and IPP samples. Sample bash session to run the configure script:

$ cd /your/pjproject/directory
$ export IPPROOT=/opt/intel/ipp/5.3.1.062/ia32/
$ export IPPSAMPLES=~/Desktop/ipp-samples
$ ./configure --enable-ipp --with-ipp=$IPPROOT --with-ipp-samples=$IPPSAMPLES

Note that you still need to enable IPP support in your config_site.h in order to use the IPP features. This will be explained in the next section.

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

Note that you still need to set this macro even after IPP has been enabled with the configure command.

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

Static Linking

Windows Instructions

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

Linux Instructions

By default, the configuration and build system will link with Intel IPP shared libraries. This is controlled by the IPP_LIBS setting in the auto-generated build.mak file:

export IPP_LIBS=-lusc -lippsc -lipps -lippsr -lippcore -lguide

If you want to configure static linking, you can override this variable in your user.mak file, or change the value in the build.mak. The later is not recommended since the build.mak file will be overwritten everytime configure is run.

Sample to override the variable in user.mak:

export IPP_LIBS=-lusc -lippscmerged ..

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 ​PJSUA-LIB, this will be done automatically by PJSUA-LIB. If application is using ​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 ​pjmedia_codec_param as usual.

Setting DLL/Shared Library Path

By default, the build process links with the IPP dynamic libraries. Because of this, you'd need to set the DLL/shared library path before running PJSIP application that links with Intel IPP.

Setting up DLL Path

On Windows, you'd need to add Intel IPP's DLL location to your PATH variable.

Setting up LD_LIBRARY_PATH

On Linux, you'd need to add Intel IPP shared library location to your LD_LIBRARY_PATH environment variable:

$ export LD_LIBRARY_PATH="$IPPROOT/sharedlib:$LD_LIBRARY_PATH"

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

MacOS X Support

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