Ignore:
Timestamp:
Jan 29, 2010 3:51:09 PM (10 years ago)
Author:
nanang
Message:

Ticket #1028:

  • Updated codecs docs, more detail info about codec settings.
File:
1 edited

Legend:

Unmodified
Added
Removed
  • pjproject/trunk/pjmedia/include/pjmedia-codec/passthrough.h

    r2875 r3083  
    3434 * @{ 
    3535 * 
    36  * This section describes functions to register and register passthrough  
     36 * This section describes functions to initialize and register passthrough  
    3737 * codecs factory to the codec manager. After the codec factory has been  
    3838 * registered, application can use @ref PJMEDIA_CODEC API to manipulate  
    39  * the codec. This codec factory contains various codecs, e.g: G.729, iLBC, 
    40  * AMR, and G.711. 
    41  * 
    42  * Passthrough codecs are codecs wrapper that does not perform encoding  
    43  * or decoding, it just pack and parse encoded audio data from/into RTP  
     39 * the codec. 
     40 * 
     41 * Passthrough codecs are codecs wrapper that does NOT perform encoding  
     42 * or decoding, it just PACK and PARSE encoded audio data from/into RTP  
    4443 * payload. This will accomodate pjmedia ports which work with encoded 
    4544 * audio data, e.g: encoded audio files, sound device with capability 
    4645 * of playing/recording encoded audio data. 
     46 * 
     47 * This codec factory contains various codecs, i.e: G.729, iLBC, 
     48 * AMR, and G.711. 
     49 * 
     50 * 
     51 * \section pjmedia_codec_passthrough_g729 Passthrough G.729 
     52 * 
     53 * G.729 supports 16-bit PCM audio signal with sampling rate 8000Hz,  
     54 * frame length 10ms, and resulting in bitrate 8000bps. 
     55 * 
     56 * \subsection codec_setting Codec Settings 
     57 * 
     58 * General codec settings for this codec such as VAD and PLC can be  
     59 * manipulated through the <tt>setting</tt> field in #pjmedia_codec_param.  
     60 * Please see the documentation of #pjmedia_codec_param for more info. 
     61 * 
     62 * Note that G.729 VAD status should be signalled in SDP, see more 
     63 * description below. 
     64 * 
     65 * \subsubsection annexb Annex B 
     66 * 
     67 * The capability of VAD/DTX is specified in Annex B. 
     68 * 
     69 * By default, Annex B is enabled. This default setting of Annex B can  
     70 * be modified using #pjmedia_codec_mgr_set_default_param(). 
     71 * 
     72 * In #pjmedia_codec_param, Annex B is configured via VAD setting and 
     73 * format parameter "annexb" in the SDP "a=fmtp" attribute in 
     74 * decoding fmtp field. Valid values are "yes" and "no", 
     75 * the implementation default is "yes". When this parameter is omitted 
     76 * in the SDP, the value will be "yes" (RFC 4856 Section 2.1.9). 
     77 * 
     78 * Here is an example of modifying default setting of Annex B to 
     79 * be disabled using #pjmedia_codec_mgr_set_default_param(): 
     80 \code 
     81    pjmedia_codec_param param; 
     82 
     83    pjmedia_codec_mgr_get_default_param(.., &param); 
     84    ... 
     85    // Set VAD 
     86    param.setting.vad = 0; 
     87    // Set SDP format parameter 
     88    param.setting.dec_fmtp.cnt = 1; 
     89    param.setting.dec_fmtp.param[0].name = pj_str("annexb"); 
     90    param.setting.dec_fmtp.param[0].val  = pj_str("no"); 
     91    ... 
     92    pjmedia_codec_mgr_set_default_param(.., &param); 
     93 \endcode 
     94 * 
     95 * \note 
     96 * The difference of Annex B status in SDP offer/answer may be considered as  
     97 * incompatible codec in SDP negotiation. 
     98 * 
     99 *  
     100 * \section pjmedia_codec_passthrough_ilbc Passthrough iLBC 
     101 * 
     102 * The iLBC codec is developed by Global IP Solutions (GIPS), formerly  
     103 * Global IP Sound. The iLBC offers low bitrate and graceful audio quality  
     104 * degradation on frame losses. 
     105 * 
     106 * The iLBC codec supports 16-bit PCM audio signal with sampling rate of  
     107 * 8000Hz operating at two modes: 20ms and 30ms frame length modes, resulting 
     108 * in bitrates of 15.2kbps for 20ms mode and 13.33kbps for 30ms mode. 
     109 * 
     110 * \subsection codec_setting Codec Settings 
     111 * 
     112 * General codec settings for this codec such as VAD and PLC can be  
     113 * manipulated through the <tt>setting</tt> field in #pjmedia_codec_param.  
     114 * Please see the documentation of #pjmedia_codec_param for more info. 
     115 * 
     116 * \subsubsection mode Mode 
     117 * 
     118 * The default mode should be set upon initialization, see 
     119 * #pjmedia_codec_passthrough_init2(). After the codec is initialized, the 
     120 * default mode can be modified using #pjmedia_codec_mgr_set_default_param(). 
     121 * 
     122 * In #pjmedia_codec_param, iLBC mode can be set by specifying SDP 
     123 * format parameter "mode" in the SDP "a=fmtp" attribute for decoding 
     124 * direction. Valid values are "20" and "30" (for 20ms and 30ms mode  
     125 * respectively). 
     126 * 
     127 * Here is an example to set up #pjmedia_codec_param to use mode 20ms: 
     128 *  \code 
     129    pjmedia_codec_param param; 
     130    ... 
     131    // setting iLBC mode in SDP 
     132    param.setting.dec_fmtp.cnt = 1; 
     133    param.setting.dec_fmtp.param[0].name = pj_str("mode"); 
     134    param.setting.dec_fmtp.param[0].val  = pj_str("20"); 
     135    ... 
     136 \endcode 
     137 * 
     138 * 
     139 * \section pjmedia_codec_passthrough_amr Passthrough AMR 
     140 * 
     141 * IPP AMR supports 16-bit PCM audio signal with sampling rate 8000Hz, 
     142 * 20ms frame length and producing various bitrates that ranges from 4.75kbps 
     143 * to 12.2kbps. 
     144 * 
     145 * \subsection codec_setting Codec Settings 
     146 * 
     147 * General codec settings for this codec such as VAD and PLC can be  
     148 * manipulated through the <tt>setting</tt> field in #pjmedia_codec_param.  
     149 * Please see the documentation of #pjmedia_codec_param for more info. 
     150 * 
     151 * \subsubsection bitrate Bitrate 
     152 * 
     153 * By default, encoding bitrate is 7400bps. This default setting can be  
     154 * modified using #pjmedia_codec_mgr_set_default_param() by specifying  
     155 * prefered AMR bitrate in field <tt>info::avg_bps</tt> of  
     156 * #pjmedia_codec_param. Valid bitrates could be seen in  
     157 * #pjmedia_codec_amrnb_bitrates. 
     158 * 
     159 * \subsubsection payload_format Payload Format 
     160 * 
     161 * There are two AMR payload format types, bandwidth-efficient and 
     162 * octet-aligned. Default setting is using octet-aligned. This default payload 
     163 * format can be modified using #pjmedia_codec_mgr_set_default_param(). 
     164 * 
     165 * In #pjmedia_codec_param, payload format can be set by specifying SDP  
     166 * format parameters "octet-align" in the SDP "a=fmtp" attribute for  
     167 * decoding direction. Valid values are "0" (for bandwidth efficient mode) 
     168 * and "1" (for octet-aligned mode). 
     169 * 
     170 * \subsubsection mode_set Mode-Set 
     171 *  
     172 * Mode-set is used for restricting AMR modes in decoding direction. 
     173 * 
     174 * By default, no mode-set restriction applied. This default setting can be  
     175 * be modified using #pjmedia_codec_mgr_set_default_param(). 
     176 * 
     177 * In #pjmedia_codec_param, mode-set could be specified via format parameters 
     178 * "mode-set" in the SDP "a=fmtp" attribute for decoding direction. Valid  
     179 * value is a comma separated list of modes from the set 0 - 7, e.g:  
     180 * "4,5,6,7". When this parameter is omitted, no mode-set restrictions applied. 
     181 * 
     182 * Here is an example of modifying AMR default codec param: 
     183 \code 
     184    pjmedia_codec_param param; 
     185 
     186    pjmedia_codec_mgr_get_default_param(.., &param); 
     187    ... 
     188    // set default encoding bitrate to the highest 12.2kbps 
     189    param.info.avg_bps = 12200; 
     190 
     191    // restrict decoding bitrate to 10.2kbps and 12.2kbps only 
     192    param.setting.dec_fmtp.param[0].name = pj_str("mode-set"); 
     193    param.setting.dec_fmtp.param[0].val  = pj_str("6,7"); 
     194 
     195    // also set to use bandwidth-efficient payload format 
     196    param.setting.dec_fmtp.param[1].name = pj_str("octet-align"); 
     197    param.setting.dec_fmtp.param[1].val  = pj_str("0"); 
     198 
     199    param.setting.dec_fmtp.cnt = 2; 
     200    ... 
     201    pjmedia_codec_mgr_set_default_param(.., &param); 
     202 \endcode 
     203 *  
     204 * 
     205 * \section pjmedia_codec_passthrough_g711 Passthrough G.711 
     206 * 
     207 * The G.711 is an ultra low complexity codecs and in trade-off it results 
     208 * in high bitrate, i.e: 64kbps for 16-bit PCM with sampling rate 8000Hz. 
     209 * 
     210 * The factory contains two main compression algorithms, PCMU/u-Law and  
     211 * PCMA/A-Law. 
     212 * 
     213 * \subsection codec_setting Codec Settings 
     214 * 
     215 * General codec settings for this codec such as VAD and PLC can be  
     216 * manipulated through the <tt>setting</tt> field in #pjmedia_codec_param.  
     217 * Please see the documentation of #pjmedia_codec_param for more info. 
    47218 */ 
    48219 
     
    79250 * 
    80251 * @param endpt     The pjmedia endpoint. 
    81  * @param setting   The settings, see @pjmedia_codec_passthrough_setting. 
     252 * @param setting   The settings. 
    82253 * 
    83254 * @return          PJ_SUCCESS on success. 
Note: See TracChangeset for help on using the changeset viewer.