Audio Device API

PJMEDIA audio device abstraction API. More...

Modules
	Audio Device Implementors API
	API for audio device implementors.
	Audio tests utility.
	Audio test utility.
	Compile time configurations
	Compile time configurations.
	Error Codes
	Audio devive library specific error codes.
	Audio Device API Reference
	Documentation and API Reference.

Detailed Description

PJMEDIA Audio Device API is a cross-platform audio API appropriate for use with VoIP applications and many other types of audio streaming applications.

The API abstracts many different audio API's on various platforms, such as:

• WMME audio for Windows and Windows Mobile devices
• Windows Audio Session API (WASAPI)
• CoreAudio for Mac and iPhone
• ALSA for Linux
• Android OpenSL
• Android JNI
• Android Oboe
• PortAudio for Windows, Windows Mobile, Linux, Unix, dan MacOS X.
• BDIMAP
• Blackberry BB10
• Symbian audio streaming/multimedia framework (MMF) implementation
• Nokia Audio Proxy Server (APS) implementation
• null-audio implementation
• and more to be implemented in the future

The Audio Device API/library is an evolution from PJMEDIA Portable Sound Hardware Abstraction and contains many enhancements:

• 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 as well as compatibility with existing device implementations.
• 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 and control audio features built-in in the device, such as:
  • echo cancellation,
  • built-in codecs,
  • audio routing (e.g. to earpiece or loudspeaker),
  • volume control,
  • etc.
• 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 application can use the sound device in encoded mode to make use of these hardware codecs.
• Multiple backends:
  The new API supports multiple audio backends (called factories or drivers in the code) to be active simultaneously, and audio backends may be added or removed during run-time.

Overview on using the API

Getting started

1. Configure the application's project settings.
   Add the following include:

   #include <pjmedia_audiodev.h>

   
   And add pjmedia-audiodev library to your application link specifications.
   
2. Compile time settings.
   Use the compile time settings to enable or disable specific audio drivers. For more information, please see Compile time configurations.
3. API initialization and cleaning up.
   Before anything else, application must initialize the API by calling:

   pjmedia_aud_subsys_init(pf);

   
   And add this in the application cleanup sequence

   pjmedia_aud_subsys_shutdown();

Working with devices

1. The following code prints the list of audio devices detected in the system.

   int dev_count;
   pjmedia_aud_dev_index dev_idx;
   pj_status_t status;
    
   dev_count = pjmedia_aud_dev_count();
   printf("Got %d audio devices\n", dev_count);
    
   for (dev_idx=0; dev_idx<dev_count; ++i) {
       pjmedia_aud_dev_info info;
    
       status = pjmedia_aud_dev_get_info(dev_idx, &info);
       printf("%d. %s (in=%d, out=%d)\n",
              dev_idx, info.name, 
              info.input_count, info.output_count);
   }

   
   
2. Info: The PJMEDIA_AUD_DEFAULT_CAPTURE_DEV and PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV constants are used to denote default capture and playback devices respectively.
3. Info: You may save the device and driver's name in your application setting, for example to specify the prefered devices to be used by your application. You can then retrieve the device index for the device by calling:

   const char *drv_name = "WMME";
   const char *dev_name = "Wave mapper";
   pjmedia_aud_dev_index dev_idx;
    
   status = pjmedia_aud_dev_lookup(drv_name, dev_name, &dev_idx);
   if (status==PJ_SUCCESS)
       printf("Device index is %d\n", dev_idx);

Device capabilities

Capabilities are encoded as pjmedia_aud_dev_cap enumeration. Please see pjmedia_aud_dev_cap enumeration for more information.

1. The following snippet prints the capabilities supported by the device:

   pjmedia_aud_dev_info info;
   pj_status_t status;
    
   status = pjmedia_aud_dev_get_info(PJMEDIA_AUD_DEFAULT_CAPTURE_DEV, &info);
   if (status == PJ_SUCCESS) {
       unsigned i;
       // Enumerate capability bits
       printf("Device capabilities: ");
       for (i=0; i<32; ++i) {
           if (info.caps & (1 << i))
               printf("%s ", pjmedia_aud_dev_cap_name(1 << i, NULL));
       }
   }

   
   
2. Info: You can set the device settings when opening audio stream by setting the flags and the appropriate setting in pjmedia_aud_param when calling pjmedia_aud_stream_create()
   
3. Info: Once the audio stream is running, you can retrieve or change the stream setting by specifying the capability in pjmedia_aud_stream_get_cap() and pjmedia_aud_stream_set_cap() respectively.

Creating audio streams

The audio stream enables audio streaming to capture device, playback device, or both.

1. It is recommended to initialize the pjmedia_aud_param with its default values before using it:

   pjmedia_aud_param param;
   pjmedia_aud_dev_index dev_idx;
   pj_status_t status;
    
   dev_idx = PJMEDIA_AUD_DEFAULT_CAPTURE_DEV;
   status = pjmedia_aud_dev_default_param(dev_idx, &param);

   
   
2. Configure the mandatory parameters:

   param.dir = PJMEDIA_DIR_CAPTURE_PLAYBACK;
   param.rec_id = PJMEDIA_AUD_DEFAULT_CAPTURE_DEV;
   param.play_id = PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV;
   param.clock_rate = 8000;
   param.channel_count = 1;
   param.samples_per_frame = 160;
   param.bits_per_sample = 16;

   
   
3. If you want the audio stream to use the device's built-in codec, specify the codec in the pjmedia_aud_param. You must make sure that the codec is supported by the device, by looking at its supported format list in the pjmedia_aud_dev_info.
   The snippet below sets the audio stream to use G.711 ULAW encoding:

   unsigned i;
    
   // Make sure Ulaw is supported
   if ((info.caps & PJMEDIA_AUD_DEV_CAP_EXT_FORMAT) == 0)
       error("Device does not support extended formats");
   for (i = 0; i < info.ext_fmt_cnt; ++i) {
       if (info.ext_fmt[i].id == PJMEDIA_FORMAT_ULAW)
           break;
   }
   if (i == info.ext_fmt_cnt)
       error("Device does not support Ulaw format");
    
   // Set Ulaw format
   param.flags |= PJMEDIA_AUD_DEV_CAP_EXT_FORMAT;
   param.ext_fmt.id = PJMEDIA_FORMAT_ULAW;
   param.ext_fmt.bitrate = 64000;
   param.ext_fmt.vad = PJ_FALSE;

   
   
4. Note that if non-PCM format is configured on the audio stream, the capture and/or playback functions (pjmedia_aud_rec_cb and pjmedia_aud_play_cb respectively) will report the audio frame as pjmedia_frame_ext structure instead of the pjmedia_frame.
5. Optionally configure other device's capabilities. The following snippet shows how to enable echo cancellation on the device (note that this snippet may not be necessary since the setting may have been enabled when calling pjmedia_aud_dev_default_param() above):

   if (info.caps & PJMEDIA_AUD_DEV_CAP_EC) {
       param.flags |= PJMEDIA_AUD_DEV_CAP_EC;
       param.ec_enabled = PJ_TRUE;
   }

6. Open the audio stream, specifying the capture and/or playback callback functions:

   pjmedia_aud_stream *stream;
    
   status = pjmedia_aud_stream_create(&param, &rec_cb, &play_cb, 
                                      user_data, &stream);

Working with audio streams

1. To start the audio stream:

   status = pjmedia_aud_stream_start(stream);

   
   To stop the stream:

   status = pjmedia_aud_stream_stop(stream);

   
   And to destroy the stream:

   status = pjmedia_aud_stream_destroy(stream);

   
   
2. Info: The following shows how to retrieve the capability value of the stream (in this case, the current output volume setting).

   // Volume setting is an unsigned integer showing the level in percent.
   unsigned vol;
   status = pjmedia_aud_stream_get_cap(stream, 
                                       PJMEDIA_AUD_DEV_CAP_OUTPUT_VOLUME_SETTING,
                                       &vol);

3. Info: And following shows how to modify the capability value of the stream (in this case, the current output volume setting).

   // Volume setting is an unsigned integer showing the level in percent.
   unsigned vol = 50;
   status = pjmedia_aud_stream_set_cap(stream, 
                                       PJMEDIA_AUD_DEV_CAP_OUTPUT_VOLUME_SETTING,
                                       &vol);