wiki:Intel_IPP_Codecs

Version 15 (modified by nanang, 11 years ago) (diff)

--

Using Intel Integrated Performance Primitive (IPP) with PJMEDIA


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 Bitrates (Kbps) Clock rate/
samples per frame
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 internal internal 1) Annex D and Annex E is supported for receive direction.


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
    3. Verifying Intel IPP Codecs Support
    4. Manipulating IPP Codecs
  4. Static Linking
    1. Windows Instructions
    2. Linux Instructions
  5. Using in Applications
    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. AMR Options
    3. MacOS X Support
    4. Visual Studio 6 Support



Requirements

The following are required:

  • PJSIP version 1.0-rc1 or above
  • Intel IPP library for your platform
  • Intel IPP samples for your platform

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

Note that the use of Intel IPP requires a license from Intel, and in addition a license from the parties who own the royalty of the codec(s) may also be required.



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, but it can be installed anywhere else with some modifications to the instructions below.

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 in a directory inside speech-codecs\bin directory (in my case, it's in C:\ipp-samples\speech-codecs\bin\win32_cl9\lib folder). The directory name corresponds to the platform where the samples are built for.

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

Configure Visual Studio

  1. Add Intel IPP include and library paths 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 VS include path
    • add C:\Program Files\Intel\IPP\5.3.3.082\ia32\stublib to the VS library path
  2. Add Intel IPP samples include and library path to Visual Studio paths. For example, if Intel IPP samples are located 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. Please replace win32_cl9 with the actual directory name where the file usc.lib is found. Please see the IPP build instructions above.

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

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/" in my case).
  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 to (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 in a directory inside speech-codecs\bin directory (in my case, it's in ~/Desktop/ipp-samples/speech-codecs/bin/linux32_gcc3/lib directory). The directory name corresponds to the platform where the samples are built for.

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

Running "configure" with IPP support

The configure script needs to be invoked with the appropriate 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 at compile time, 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

You can also enable/disable the individual IPP codec at run-time by setting the particular codec priority to zero.

Verifying Intel IPP Codecs Support

To verify that Intel IPP codecs supports are present, you can run pjsua and enter "Cp" (codec priority) command from the menu. It should display all IPP codecs that are enabled at compile time, e.g.:

>>> Cp
List of codecs:
  130   speex/16000/1
  129   speex/8000/1
  128   speex/32000/1
  128   iLBC/8000/1
  128   GSM/8000/1
  128   PCMU/8000/1
  128   PCMA/8000/1
  128   G722/16000/1
  128   AMR/8000/1
  128   AMR-WB/16000/1
  128   G729/8000/1
  128   G723/8000/1
  128   G726-32/8000/1
  128   G728/8000/1
  128   G7221/16000/1
  128   G7221/16000/1
  0     L16/44100/1
  0     L16/44100/2
  0     L16/8000/1
  0     L16/8000/2
  0     L16/11025/1
  0     L16/11025/2
  0     L16/16000/1
  0     L16/16000/2
  0     L16/22050/1
  0     L16/22050/2
  0     L16/32000/1
  0     L16/32000/2
  0     L16/48000/1
  0     L16/48000/2

Enter codec id and its new priority (e.g. "speex/16000 200"), empty to cancel:
Codec name ("*" for all) and priority:

Manipulating IPP Codecs

To change the IPP codec properties at run-time (e.g. to enable/disable, change the priority, bitrate, vad/plc setting, etc.), use the usual codec manipulation API that is available from both PJSUA-LIB or PJMEDIA.

More information is available in Using in Application section below.



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:

  1. Disable default automatic linking:
    #define PJMEDIA_AUTO_LINK_IPP_LIBS  0
    
  2. Add C:\Program Files\Intel\IPP\5.3.3.082\ia32\lib to the VS library path
  3. Include the following libraries
    ippsmerged.lib ippsemerged.lib ippscmerged.lib ippscemerged.lib ippsrmerged.lib ippsremerged.lib ippcorel.lib usc.lib
    
    in the application project setting.
  4. Insert IPP static initialization function, i.e: ippStaticInit() declared in ippcore.h, into the startup point of the application, e.g:
    #include <ippcore.h>
    main() {
        /* Init IPP before calling any IPP functions. */
        ippStaticInit();
        ...
    }
    

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


Additional Information on IPP Linkage Models:



Using in Applications

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

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.

Visual Studio 6 Support

Visual Studio 6 is not supported by the Intel IPP samples build system. If you wish to use Visual Studio 6 to build the samples, replace the search_compilers.bat in the tools\env directory under the IPP samples directory with the one from the attachment of this page below.

Attachments (1)

Download all attachments as: .zip