Changeset 2473


Ignore:
Timestamp:
Feb 23, 2009 9:55:52 AM (10 years ago)
Author:
bennylp
Message:
  • Added main doxygen documentations for audiodev
  • Added include/pjmedia_audiodev.h
  • Fix include sound.h in pjmedia.h
Location:
pjproject/branches/projects/aps-direct/pjmedia/include
Files:
1 added
2 edited

Legend:

Unmodified
Added
Removed
  • pjproject/branches/projects/aps-direct/pjmedia/include/pjmedia-audiodev/config.h

    r2470 r2473  
    106106 - Built-in features: 
    107107\n 
    108    The device capabilities framework enables applications to use audio features 
    109    built-in in the device, such as: 
     108   The device capabilities framework enables applications to use and control  
     109   audio features built-in in the device, such as: 
    110110    - echo cancellation,  
    111111    - built-in codecs,  
    112     - audio routing, and  
    113     - volume control.  
     112    - audio routing (e.g. to earpiece or loudspeaker), 
     113    - volume control, 
     114    - etc. 
    114115 
    115116 - Codec support: 
     
    125126   the code) to be active simultaneously, and audio backends may be added or  
    126127   removed during run-time.  
    127  */ 
     128 
     129 
     130@section using Overview on using the API 
     131 
     132@subsection getting_started Getting started 
     133 
     134 -# <b>Configure the application's project settings</b>.\n 
     135    Add the following  
     136    include: 
     137    \code 
     138    #include <pjmedia_audiodev.h>\endcode\n 
     139    And add <b>pjmedia-audiodev</b> library to your application link  
     140    specifications.\n 
     141 -# <b>Compile time settings</b>.\n 
     142    Use the compile time settings to enable or 
     143    disable specific audio drivers. For more information, please see 
     144    \ref s1_audio_device_config. 
     145 -# <b>API initialization and cleaning up</b>.\n 
     146    Before anything else, application must initialize the API by calling: 
     147    \code 
     148    pjmedia_aud_subsys_init(pf);\endcode\n 
     149    And add this in the application cleanup sequence 
     150    \code 
     151    pjmedia_aud_subsys_shutdown();\endcode 
     152 
     153@subsection devices Working with devices 
     154 
     155 -# The following code prints the list of audio devices detected 
     156    in the system. 
     157    \code 
     158    int dev_count; 
     159    pjmedia_aud_dev_index dev_idx; 
     160    pj_status_t status; 
     161 
     162    dev_count = pjmedia_aud_dev_count(); 
     163    printf("Got %d audio devices\n", dev_count); 
     164 
     165    for (dev_idx=0; dev_idx<dev_count; ++i) { 
     166        pjmedia_aud_dev_info info; 
     167 
     168        status = pjmedia_aud_dev_get_info(dev_idx, &info); 
     169        printf("%d. %s (in=%d, out=%d)\n", 
     170               dev_idx, info.name,  
     171               info.input_count, info.output_count); 
     172    } 
     173    \endcode\n 
     174 -# Info: The #PJMEDIA_AUD_DEFAULT_CAPTURE_DEV and #PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV 
     175    constants are used to denote default capture and playback devices 
     176    respectively. 
     177 -# Info: You may save the device and driver's name in your application 
     178    setting, for example to specify the prefered devices to be 
     179    used by your application. You can then retrieve the device index 
     180    for the device by calling: 
     181    \code 
     182        const char *drv_name = "WMME"; 
     183        const char *dev_name = "Wave mapper"; 
     184        pjmedia_aud_dev_index dev_idx; 
     185 
     186        status = pjmedia_aud_dev_lookup(drv_name, dev_name, &dev_idx); 
     187        if (status==PJ_SUCCESS) 
     188            printf("Device index is %d\n", dev_idx); 
     189    \endcode 
     190 
     191@subsection caps Device capabilities 
     192 
     193Capabilities are encoded as #pjmedia_aud_dev_cap enumeration. Please see 
     194#pjmedia_aud_dev_cap enumeration for more information. 
     195 
     196 -# The following snippet prints the capabilities supported by the device: 
     197    \code 
     198    pjmedia_aud_dev_info info; 
     199    pj_status_t status; 
     200 
     201    status = pjmedia_aud_dev_get_info(PJMEDIA_AUD_DEFAULT_CAPTURE_DEV, &info); 
     202    if (status == PJ_SUCCESS) { 
     203        unsigned i; 
     204        // Enumerate capability bits 
     205        printf("Device capabilities: "); 
     206        for (i=0; i<32; ++i) { 
     207            if (info.caps & (1 << i)) 
     208                printf("%s ", pjmedia_aud_dev_cap_name(1 << i, NULL)); 
     209        } 
     210    } 
     211    \endcode\n 
     212 -# Info: You can set the device settings when opening audio stream by setting 
     213    the flags and the appropriate setting in #pjmedia_aud_param when calling 
     214    #pjmedia_aud_stream_create()\n 
     215 -# Info: Once the audio stream is running, you can retrieve or change the stream  
     216    setting by specifying the capability in #pjmedia_aud_stream_get_cap() 
     217    and #pjmedia_aud_stream_set_cap() respectively. 
     218 
     219 
     220@subsection creating_stream Creating audio streams 
     221 
     222The audio stream enables audio streaming to capture device, playback device, 
     223or both. 
     224 
     225 -# It is recommended to initialize the #pjmedia_aud_param with its default 
     226    values before using it: 
     227    \code 
     228    pjmedia_aud_param param; 
     229    pjmedia_aud_dev_index dev_idx; 
     230    pj_status_t status; 
     231 
     232    dev_idx = PJMEDIA_AUD_DEFAULT_CAPTURE_DEV; 
     233    status = pjmedia_aud_dev_default_param(dev_idx, &param); 
     234    \endcode\n 
     235 -# Configure the mandatory parameters: 
     236    \code 
     237    param.dir = PJMEDIA_DIR_CAPTURE_PLAYBACK; 
     238    param.rec_id = PJMEDIA_AUD_DEFAULT_CAPTURE_DEV; 
     239    param.play_id = PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV; 
     240    param.clock_rate = 8000; 
     241    param.channel_count = 1; 
     242    param.samples_per_frame = 160; 
     243    param.bits_per_sample = 16; 
     244    \endcode\n 
     245 -# If you want the audio stream to use the device's built-in codec, specify 
     246    the codec in the #pjmedia_aud_param. You must make sure that the codec 
     247    is supported by the device, by looking at its supported format list in 
     248    the #pjmedia_aud_dev_info.\n 
     249    The snippet below sets the audio stream to use G.711 ULAW encoding: 
     250    \code 
     251    unsigned i; 
     252 
     253    // Make sure Ulaw is supported 
     254    if ((info.caps & PJMEDIA_AUD_DEV_CAP_EXT_FORMAT) == 0) 
     255        error("Device does not support extended formats"); 
     256    for (i = 0; i < info.ext_fmt_cnt; ++i) { 
     257        if (info.ext_fmt[i].id == PJMEDIA_FORMAT_ULAW) 
     258            break; 
     259    } 
     260    if (i == info.ext_fmt_cnt) 
     261        error("Device does not support Ulaw format"); 
     262 
     263    // Set Ulaw format 
     264    param.flags |= PJMEDIA_AUD_DEV_CAP_EXT_FORMAT; 
     265    param.ext_fmt.id = PJMEDIA_FORMAT_ULAW; 
     266    param.ext_fmt.bitrate = 64000; 
     267    param.ext_fmt.vad = PJ_FALSE; 
     268    \endcode\n 
     269 -# Note that if non-PCM format is configured on the audio stream, the 
     270    capture and/or playback functions (#pjmedia_aud_rec_cb and  
     271    #pjmedia_aud_play_cb respectively) will report the audio frame as 
     272    #pjmedia_frame_ext structure instead of the #pjmedia_frame. 
     273 -# Optionally configure other device's capabilities. The following snippet 
     274    shows how to enable echo cancellation on the device (note that this 
     275    snippet may not be necessary since the setting may have been enabled  
     276    when calling #pjmedia_aud_dev_default_param() above): 
     277    \code 
     278    if (info.caps & PJMEDIA_AUD_DEV_CAP_EC) { 
     279        param.flags |= PJMEDIA_AUD_DEV_CAP_EC; 
     280        param.ec_enabled = PJ_TRUE; 
     281    } 
     282    \endcode 
     283 -# Open the audio stream, specifying the capture and/or playback callback 
     284    functions: 
     285    \code 
     286       pjmedia_aud_stream *stream; 
     287 
     288       status = pjmedia_aud_stream_create(&param, &rec_cb, &play_cb,  
     289                                          user_data, &stream); 
     290    \endcode 
     291 
     292@subsection working_with_stream Working with audio streams 
     293 
     294 -# To start the audio stream: 
     295    \code 
     296        status = pjmedia_aud_stream_start(stream); 
     297    \endcode\n 
     298    To stop the stream: 
     299    \code 
     300        status = pjmedia_aud_stream_stop(stream); 
     301    \endcode\n 
     302    And to destroy the stream: 
     303    \code 
     304        status = pjmedia_aud_stream_destroy(stream); 
     305    \endcode\n 
     306 -# Info: The following shows how to retrieve the capability value of the 
     307    stream (in this case, the current output volume setting). 
     308    \code 
     309    // Volume setting is an unsigned integer showing the level in percent. 
     310    unsigned vol; 
     311    status = pjmedia_aud_stream_get_cap(stream,  
     312                                        PJMEDIA_AUD_DEV_CAP_OUTPUT_VOLUME_SETTING, 
     313                                        &vol); 
     314    \endcode 
     315 -# Info: And following shows how to modify the capability value of the 
     316    stream (in this case, the current output volume setting). 
     317    \code 
     318    // Volume setting is an unsigned integer showing the level in percent. 
     319    unsigned vol = 50; 
     320    status = pjmedia_aud_stream_set_cap(stream,  
     321                                        PJMEDIA_AUD_DEV_CAP_OUTPUT_VOLUME_SETTING, 
     322                                        &vol); 
     323    \endcode 
     324 
     325 
     326*/ 
     327 
    128328 
    129329/** 
  • pjproject/branches/projects/aps-direct/pjmedia/include/pjmedia.h

    r2468 r2473  
    5555/* This sound API is deprecated. Please see: 
    5656http://trac.pjsip.org/repos/wiki/Audio_Dev_API 
     57*/ 
     58#if PJMEDIA_AUDIO_API != PJMEDIA_AUDIO_API_NEW_ONLY 
    5759#include <pjmedia/sound.h> 
    58 */ 
     60#endif 
    5961#include <pjmedia/sound_port.h> 
    6062#include <pjmedia/splitcomb.h> 
Note: See TracChangeset for help on using the changeset viewer.