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/ipp_codecs.h

    r2875 r3083  
    3434 * @{ 
    3535 * 
    36  * This section describes functions to register and register IPP codec 
     36 * This section describes functions to initialize and register IPP codec 
    3737 * factory to the codec manager. After the codec factory has been registered, 
    3838 * application can use @ref PJMEDIA_CODEC API to manipulate the codec. 
    39  * This codec factory contains various codecs, e.g: G.729, G.723.1, G.726,  
    40  * G.728, G.722.1, AMR. 
     39 * 
     40 * This codec factory contains various codecs, i.e: G.729, G.723.1, G.726,  
     41 * G.728, G.722.1, AMR, and AMR-WB. 
     42 * 
     43 * 
     44 * \section pjmedia_codec_ipp_g729 IPP G.729 
     45 * 
     46 * IPP G.729 is compliant with ITU-T G.729 and Annexes A, B, C, C+, D,  
     47 * E, I specifications. However, currently the pjmedia implementation is 
     48 * using Annexes A and B only. 
     49 * 
     50 * IPP G.729 supports 16-bit PCM audio signal with sampling rate 8000Hz,  
     51 * frame length 10ms, and resulting in bitrate 8000bps (annexes D and E 
     52 * introduce bitrates 6400bps and 11800bps). 
     53 * 
     54 * \subsection codec_setting Codec Settings 
     55 * 
     56 * General codec settings for this codec such as VAD and PLC can be  
     57 * manipulated through the <tt>setting</tt> field in #pjmedia_codec_param.  
     58 * Please see the documentation of #pjmedia_codec_param for more info. 
     59 * 
     60 * Note that G.729 VAD status should be signalled in SDP, see more 
     61 * description below. 
     62 * 
     63 * \subsubsection annexb Annex B 
     64 * 
     65 * The capability of VAD/DTX is specified in Annex B. 
     66 * 
     67 * By default, Annex B is enabled. This default setting of Annex B can  
     68 * be modified using #pjmedia_codec_mgr_set_default_param(). 
     69 * 
     70 * In #pjmedia_codec_param, Annex B is configured via VAD setting and 
     71 * format parameter "annexb" in the SDP "a=fmtp" attribute in 
     72 * decoding fmtp field. Valid values are "yes" and "no", 
     73 * the implementation default is "yes". When this parameter is omitted 
     74 * in the SDP, the value will be "yes" (RFC 4856 Section 2.1.9). 
     75 * 
     76 * Here is an example of modifying default setting of Annex B to 
     77 * be disabled using #pjmedia_codec_mgr_set_default_param(): 
     78 \code 
     79    pjmedia_codec_param param; 
     80 
     81    pjmedia_codec_mgr_get_default_param(.., &param); 
     82    ... 
     83    // Set VAD 
     84    param.setting.vad = 0; 
     85    // Set SDP format parameter 
     86    param.setting.dec_fmtp.cnt = 1; 
     87    param.setting.dec_fmtp.param[0].name = pj_str("annexb"); 
     88    param.setting.dec_fmtp.param[0].val  = pj_str("no"); 
     89    ... 
     90    pjmedia_codec_mgr_set_default_param(.., &param); 
     91 \endcode 
     92 * 
     93 * \note 
     94 * The difference of Annex B status in SDP offer/answer may be considered as  
     95 * incompatible codec in SDP negotiation. 
     96 * 
     97 *  
     98 * \section pjmedia_codec_ipp_g7231 IPP G.723.1 
     99 * 
     100 * IPP G.723.1 speech codec is compliant with ITU-T G.723.1 and Annex A 
     101 * specifications. 
     102 * 
     103 * IPP G.723.1 supports 16-bit PCM audio signal with sampling rate 8000Hz,  
     104 * frame length 30ms, and resulting in bitrates 5300bps and 6300bps. 
     105 * 
     106 * By default, pjmedia implementation uses encoding bitrate of 6300bps. 
     107 * The bitrate is signalled in-band in G.723.1 frames and interoperable. 
     108 * 
     109 * \subsection codec_setting Codec Settings 
     110 * 
     111 * General codec settings for this codec such as VAD and PLC can be  
     112 * manipulated through the <tt>setting</tt> field in #pjmedia_codec_param.  
     113 * Please see the documentation of #pjmedia_codec_param for more info. 
     114 * 
     115 * 
     116 * \section pjmedia_codec_ipp_g726 IPP G.726 
     117 * 
     118 * IPP G.726 is compliant with ITU-T G.726 and G.726 Annex A specifications. 
     119 * 
     120 * IPP G.726 supports 16-bit PCM audio signal with sampling rate 8000Hz, 
     121 * 10ms frame length and producing 16kbps, 24kbps, 32kbps, 48kbps bitrates. 
     122 * The bitrate is specified explicitly in its encoding name, i.e: G726-16, 
     123 * G726-24, G726-32, G726-48. 
     124 * 
     125 * \subsection codec_setting Codec Settings 
     126 * 
     127 * General codec settings for this codec such as VAD and PLC can be  
     128 * manipulated through the <tt>setting</tt> field in #pjmedia_codec_param.  
     129 * Please see the documentation of #pjmedia_codec_param for more info. 
     130 * 
     131 * 
     132 * \section pjmedia_codec_ipp_g728 IPP G.728 
     133 * 
     134 * IPP G.728 is compliant with ITU-T G.728 with I, G, H Appendixes  
     135 * specifications for Low-Delay CELP coder. 
     136 *  
     137 * IPP G.728 supports 16-bit PCM audio signal with sampling rate 8000Hz, 
     138 * 20ms frame length and producing 9.6kbps, 12.8kbps, and 16kbps bitrates. 
     139 * 
     140 * The pjmedia implementation currently uses 16kbps bitrate only. 
     141 * 
     142 * \subsection codec_setting Codec Settings 
     143 * 
     144 * General codec settings for this codec such as VAD and PLC can be  
     145 * manipulated through the <tt>setting</tt> field in #pjmedia_codec_param.  
     146 * Please see the documentation of #pjmedia_codec_param for more info. 
     147 * 
     148 * 
     149 * \section pjmedia_codec_ipp_g7221 IPP G.722.1 
     150 * 
     151 * The pjmedia implementation of IPP G.722.1 supports 16-bit PCM audio  
     152 * signal with sampling rate 16000Hz, 20ms frame length and producing  
     153 * 16kbps, 24kbps, and 32kbps bitrates. 
     154 * 
     155 * \subsection codec_setting Codec Settings 
     156 * 
     157 * General codec settings for this codec such as VAD and PLC can be  
     158 * manipulated through the <tt>setting</tt> field in #pjmedia_codec_param.  
     159 * Please see the documentation of #pjmedia_codec_param for more info. 
     160 * 
     161 * \subsubsection bitrate Bitrate 
     162 * 
     163 * The codec implementation supports only standard bitrates, i.e: 
     164 * 24kbps and 32kbps. Both are enabled by default. 
     165 * 
     166 * \remark 
     167 * There is a flaw in the codec manager as currently it could not  
     168 * differentiate G.722.1 codecs by bitrates, hence invoking  
     169 * #pjmedia_codec_mgr_set_default_param() may only affect a G.722.1 codec 
     170 * with the highest priority (or first index found in codec enumeration  
     171 * when they have same priority) and invoking 
     172 * #pjmedia_codec_mgr_set_codec_priority() will set priority of all G.722.1 
     173 * codecs with sampling rate as specified. 
     174 * 
     175 * 
     176 * \section pjmedia_codec_ipp_amr IPP AMR 
     177 * 
     178 * The IPP AMR is compliant with GSM06.90-94 specifications for GSM Adaptive 
     179 * Multi-Rate codec. 
     180 * 
     181 * IPP AMR supports 16-bit PCM audio signal with sampling rate 8000Hz, 
     182 * 20ms frame length and producing various bitrates that ranges from 4.75kbps 
     183 * to 12.2kbps. 
     184 * 
     185 * \subsection codec_setting Codec Settings 
     186 * 
     187 * General codec settings for this codec such as VAD and PLC can be  
     188 * manipulated through the <tt>setting</tt> field in #pjmedia_codec_param.  
     189 * Please see the documentation of #pjmedia_codec_param for more info. 
     190 * 
     191 * \subsubsection bitrate Bitrate 
     192 * 
     193 * By default, encoding bitrate is 7400bps. This default setting can be  
     194 * modified using #pjmedia_codec_mgr_set_default_param() by specifying  
     195 * prefered AMR bitrate in field <tt>info::avg_bps</tt> of  
     196 * #pjmedia_codec_param. Valid bitrates could be seen in  
     197 * #pjmedia_codec_amrnb_bitrates. 
     198 * 
     199 * \subsubsection payload_format Payload Format 
     200 * 
     201 * There are two AMR payload format types, bandwidth-efficient and 
     202 * octet-aligned. Default setting is using octet-aligned. This default payload 
     203 * format can be modified using #pjmedia_codec_mgr_set_default_param(). 
     204 * 
     205 * In #pjmedia_codec_param, payload format can be set by specifying SDP  
     206 * format parameters "octet-align" in the SDP "a=fmtp" attribute for  
     207 * decoding direction. Valid values are "0" (for bandwidth efficient mode) 
     208 * and "1" (for octet-aligned mode). 
     209 * 
     210 * \subsubsection mode_set Mode-Set 
     211 *  
     212 * Mode-set is used for restricting AMR modes in decoding direction. 
     213 * 
     214 * By default, no mode-set restriction applied. This default setting can be  
     215 * be modified using #pjmedia_codec_mgr_set_default_param(). 
     216 * 
     217 * In #pjmedia_codec_param, mode-set could be specified via format parameters 
     218 * "mode-set" in the SDP "a=fmtp" attribute for decoding direction. Valid  
     219 * value is a comma separated list of modes from the set 0 - 7, e.g:  
     220 * "4,5,6,7". When this parameter is omitted, no mode-set restrictions applied. 
     221 * 
     222 * Here is an example of modifying AMR default codec param: 
     223 \code 
     224    pjmedia_codec_param param; 
     225 
     226    pjmedia_codec_mgr_get_default_param(.., &param); 
     227    ... 
     228    // set default encoding bitrate to the highest 12.2kbps 
     229    param.info.avg_bps = 12200; 
     230 
     231    // restrict decoding bitrate to 10.2kbps and 12.2kbps only 
     232    param.setting.dec_fmtp.param[0].name = pj_str("mode-set"); 
     233    param.setting.dec_fmtp.param[0].val  = pj_str("6,7"); 
     234 
     235    // also set to use bandwidth-efficient payload format 
     236    param.setting.dec_fmtp.param[1].name = pj_str("octet-align"); 
     237    param.setting.dec_fmtp.param[1].val  = pj_str("0"); 
     238 
     239    param.setting.dec_fmtp.cnt = 2; 
     240    ... 
     241    pjmedia_codec_mgr_set_default_param(.., &param); 
     242 \endcode 
     243 *  
     244 * 
     245 * \section pjmedia_codec_ipp_amrwb IPP AMR-WB 
     246 * 
     247 * The IPP AMR-WB is compliant with 3GPP TS 26.190-192, 194, 201  
     248 * specifications for Adaptive Multi-Rate WideBand codec. 
     249 * 
     250 * IPP AMR-WB supports 16-bit PCM audio signal with sampling rate 16000Hz, 
     251 * 20ms frame length and producing various bitrates. Valid bitrates could be 
     252 * seen in #pjmedia_codec_amrwb_bitrates. The pjmedia implementation default 
     253 * bitrate is 15850bps. 
     254 * 
     255 * \subsection codec_setting Codec Settings 
     256 * 
     257 * General codec settings for this codec such as VAD and PLC can be  
     258 * manipulated through the <tt>setting</tt> field in #pjmedia_codec_param.  
     259 * Please see the documentation of #pjmedia_codec_param for more info. 
     260 * 
     261 * \subsubsection bitrate Bitrate 
     262 * 
     263 * By default, encoding bitrate is 15850bps. This default setting can be  
     264 * modified using #pjmedia_codec_mgr_set_default_param() by specifying  
     265 * prefered AMR bitrate in field <tt>info::avg_bps</tt> of  
     266 * #pjmedia_codec_param. 
     267 * 
     268 * \subsubsection payload_format Payload Format 
     269 * 
     270 * There are two AMR payload format types, bandwidth-efficient and 
     271 * octet-aligned. Default setting is using octet-aligned. This default payload 
     272 * format can be modified using #pjmedia_codec_mgr_set_default_param(). 
     273 * 
     274 * In #pjmedia_codec_param, payload format can be set by specifying SDP  
     275 * format parameters "octet-align" in the SDP "a=fmtp" attribute for  
     276 * decoding direction. Valid values are "0" (for bandwidth efficient mode) 
     277 * and "1" (for octet-aligned mode). 
     278 * 
     279 * \subsubsection mode_set Mode-Set 
     280 *  
     281 * Mode-set is used for restricting AMR modes in decoding direction. 
     282 * 
     283 * By default, no mode-set restriction applied. This default setting can be  
     284 * be modified using #pjmedia_codec_mgr_set_default_param(). 
     285 * 
     286 * In #pjmedia_codec_param, mode-set could be specified via format parameters 
     287 * "mode-set" in the SDP "a=fmtp" attribute for decoding direction. Valid  
     288 * value is a comma separated list of modes from the set 0 - 7, e.g:  
     289 * "4,5,6,7". When this parameter is omitted, no mode-set restrictions applied. 
    41290 */ 
    42291 
Note: See TracChangeset for help on using the changeset viewer.