wiki:Audio_Dev_API

Version 3 (modified by bennylp, 11 years ago) (diff)

--

PJMEDIA Audio Device API

Table of Contents

  1. Background
  2. Features
  3. Migration Path
    1. Common Tasks
    2. Ported Devices
    3. Compatibility settings

The PJMEDIA Audio Device API is a new sound device abstraction API/library in PJMEDIA, introduced in PJSIP version 1.1, deprecating the existing sound device API.

Background

The PJMEDIA Audio Device API was introduced as part of the implementation of APS-Direct implementation in PJSIP version 1.1. During the design and implementation of APS-Direct project, it was clear that the existing sound device API lacks many features that are needed to support the project. We had the choice to either patch the existing API with new features that are specific to Nokia APS, and potentially break existing applications anyway, or design a new sound device API to support all these new features as well as future enhancements, while providing some support for the old sound API and a clear migration path to the new API.

Features

The new audio device API contains the following major features.

Forward compatibility:
The new API has been designed to be extensible, it will support new API's as well as new features that may be introduced in the future without breaking compatibility with applications that use this API.
Device capabilities:
At the heart of the API is device capabilities management, where all possible audio capabilities of audio devices should be able to be handled in a generic manner. With this framework, new capabilities that may be discovered in the future can be handled in manner without breaking existing applications.
Built-in features:
The device capabilities framework enables applications to use audio features built-in in the device, such as echo cancellation, built-in codecs, audio routing, and volume control.
Codec support:
Some audio devices such as Nokia/Symbian? Audio Proxy Server (APS) and Nokia VoIP Audio Services (VAS) support built-in hardware audio codecs (e.g. G.729, iLBC, and AMR), and this feature is supported by the new audio device API.
Multiple backends:
The new API supports multiple audio backends (may be called factories or drivers in the code) to be active simultaneously, and audio backends may be added or removed during run-time.

Migration Path

Common Tasks

  1. The Audio Device API is implemented as a new (static) library called pjmedia-audiodev, under pjmedia directory. Please add this library into link specifications of your application.

Ported Devices

The following audio device backends have been ported to the new API:

  • PortAudio (previously pasound.c)
  • WMME (previously wmme_sound.c)
  • Null implementation (previously nullsound.c)
  • APS (previously symbian_sound_aps.cpp)

Compatibility settings

The following compile time settings/macros have introduced to manage compatibility between old and new API and to assist migration of application and/or sound device implementation to the new API.

Setting 1) PJMEDIA_AUDIO_API = PJMEDIA_AUDIO_API_NEW_ONLY

This setting will completely deprecate the use of old API, and inclusion of <pjmedia/sound.h> in the code will raise compilation error.

Use this setting if:

  • you are accessing sound devices which have been implemented using the new API
  • you have completely ported your application to use the new API
Setting 2) PJMEDIA_AUDIO_API = PJMEDIA_AUDIO_API_OLD_ONLY

With this setting, only old sound API is supported. This is useful for applications that implement their own sound device abstraction and wishes to continue to use old API to access the sound device.

Use this setting if:

  • you have your own sound device implementation, using the old API
  • you have application which uses the old API to access the sound device
Setting 3) PJMEDIA_AUDIO_API = PJMEDIA_AUDIO_API_HAS_OLD_API

With this setting (this is the default setting), application can use the old sound device API to access audio devices provided by the new audio device API.

Use this setting if:

  • you are accessing sound devices which have been implemented using new API
  • you want to access the sound device using both old or new API's.
Setting 4) PJMEDIA_AUDIO_API = PJMEDIA_AUDIO_API_HAS_OLD_DEVICE

This setting enables old sound device implementation to be accessed via both old and new API's.

Use this setting if:

  • you have your own sound device implementation, using the old API
  • you want to access the sound device using both old or new API's.