BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJMEDIA Reference

Audio Device API

PJMEDIA audio device abstraction API. More...

Modules

 Audio Device API Reference
 Documentation and API Reference.
 
 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.
 

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:

  • PortAudio back-end for Win32, Windows Mobile, Linux, Unix, dan MacOS X.
  • native WMME audio for Win32 and Windows Mobile devices
  • native Symbian audio streaming/multimedia framework (MMF) implementation
  • native 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:

    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:
    And add this in the application cleanup sequence

Working with devices

  1. The following code prints the list of audio devices detected in the system.
    int dev_count;
    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) {
    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";
    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:
    pj_status_t status;
    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:
  2. Configure the mandatory parameters:
  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
    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.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):
  6. Open the audio stream, specifying the capture and/or playback callback functions:
    status = pjmedia_aud_stream_create(&param, &rec_cb, &play_cb,

Working with audio streams

  1. To start the audio stream:
    To stop the stream:
    And to destroy the 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;
    &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;
    &vol);
unsigned pjmedia_aud_dev_count(void)
@ PJMEDIA_AUD_DEV_CAP_EC
Definition: audiodev.h:212
pjmedia_aud_dev_index play_id
Definition: audiodev.h:405
unsigned clock_rate
Definition: audiodev.h:410
pj_status_t pjmedia_aud_stream_start(pjmedia_aud_stream *strm)
pjmedia_format ext_fmt
Definition: audiodev.h:437
@ PJMEDIA_FORMAT_ULAW
Definition: format.h:77
PJMEDIA main header file.
pj_status_t pjmedia_aud_stream_create(const pjmedia_aud_param *param, pjmedia_aud_rec_cb rec_cb, pjmedia_aud_play_cb play_cb, void *user_data, pjmedia_aud_stream **p_strm)
Definition: audiodev.h:388
pj_int32_t pjmedia_aud_dev_index
Definition: audiodev.h:61
const char * pjmedia_aud_dev_cap_name(pjmedia_aud_dev_cap cap, const char **p_desc)
pj_status_t pjmedia_aud_stream_get_cap(pjmedia_aud_stream *strm, pjmedia_aud_dev_cap cap, void *value)
void * user_data
pj_status_t pjmedia_aud_stream_stop(pjmedia_aud_stream *strm)
pj_status_t pjmedia_aud_subsys_init(pj_pool_factory *pf)
unsigned samples_per_frame
Definition: audiodev.h:420
pj_status_t pjmedia_aud_stream_set_cap(pjmedia_aud_stream *strm, pjmedia_aud_dev_cap cap, const void *value)
#define PJMEDIA_AUD_DEFAULT_CAPTURE_DEV
Definition: audiodev.h:70
pj_status_t pjmedia_aud_dev_default_param(pjmedia_aud_dev_index id, pjmedia_aud_param *param)
pj_uint32_t id
Definition: format.h:302
Definition: audiodev.h:293
int pj_status_t
unsigned channel_count
Definition: audiodev.h:415
@ PJMEDIA_AUD_DEV_CAP_EXT_FORMAT
Definition: audiodev.h:150
pj_status_t pjmedia_aud_subsys_shutdown(void)
PJ_SUCCESS
#define PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV
Definition: audiodev.h:75
pjmedia_dir dir
Definition: audiodev.h:393
@ PJMEDIA_AUD_DEV_CAP_OUTPUT_VOLUME_SETTING
Definition: audiodev.h:178
PJ_TRUE
pj_bool_t ec_enabled
Definition: audiodev.h:483
unsigned bits_per_sample
Definition: audiodev.h:425
pj_str_t info
pjmedia_aud_dev_index rec_id
Definition: audiodev.h:399
PJ_FALSE
pj_status_t pjmedia_aud_stream_destroy(pjmedia_aud_stream *strm)
pj_status_t pjmedia_aud_dev_lookup(const char *drv_name, const char *dev_name, pjmedia_aud_dev_index *id)
pj_status_t pjmedia_aud_dev_get_info(pjmedia_aud_dev_index id, pjmedia_aud_dev_info *info)
Definition: audiodev_imp.h:167
unsigned flags
Definition: audiodev.h:431
Definition: jbsim.c:72
@ PJMEDIA_DIR_CAPTURE_PLAYBACK
Definition: types.h:176

 


PJMEDIA small footprint Open Source media stack
Copyright (C) 2006-2008 Teluu Inc.