Changeset 3083 for pjproject


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

Ticket #1028:

  • Updated codecs docs, more detail info about codec settings.
Location:
pjproject/trunk/pjmedia/include
Files:
9 edited

Legend:

Unmodified
Added
Removed

  • pjproject/trunk/pjmedia/include/pjmedia-codec/g722.h

    r2875 r3083  
    3434 * @{ 
    3535 * 
    36  * This section describes functions to register and register G.722 codec 
     36 * This section describes functions to initialize and register G.722 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. 
    3939 * 
     40 * The G.722 implementation uses 16-bit PCM with sampling rate 16000Hz and  
     41 * 20ms frame length resulting in 64kbps bitrate. 
     42 * 
    4043 * The G.722 codec implementation is provided as part of pjmedia-codec 
    4144 * library, and does not depend on external G.722 codec implementation. 
     45 * 
     46 * \section codec_setting Codec Settings 
     47 * 
     48 * \subsection general_setting General Settings 
     49 * 
     50 * General codec settings for this codec such as VAD and PLC can be  
     51 * manipulated through the <tt>setting</tt> field in #pjmedia_codec_param.  
     52 * Please see the documentation of #pjmedia_codec_param for more info. 
     53 * 
     54 * \subsection specific_setting Codec Specific Settings 
     55 * 
     56 * Currently none. 
    4257 */ 
    4358 

  • pjproject/trunk/pjmedia/include/pjmedia-codec/g7221.h

    r2875 r3083  
    2929 
    3030/** 
    31  * @defgroup PJMED_G7221_CODEC G722.1 Codec 
     31 * @defgroup PJMED_G7221_CODEC G.722.1 Codec (Siren7/Siren14) 
    3232 * @ingroup PJMEDIA_CODEC_CODECS 
    33  * @brief Implementation of G722.1 codec 
     33 * @brief Implementation of G.722.1 codec 
    3434 * @{ 
    3535 * 
    36  * <b>G722.1 licensed from Polycom®</b> 
    37  * <b>G722.1 Annex C licensed from Polycom®</b> 
     36 * <b>G.722.1 licensed from Polycom®</b><br /> 
     37 * <b>G.722.1 Annex C licensed from Polycom®</b> 
    3838 * 
    39  * This section describes functions to register and register G722.1 codec 
     39 * This section describes functions to initialize and register G.722.1 codec 
    4040 * factory to the codec manager. After the codec factory has been registered, 
    4141 * application can use @ref PJMEDIA_CODEC API to manipulate the codec. 
    … …  
    4444 * G.722.1 (05/2005) C fixed point implementation including its Annex C. 
    4545 * 
    46  * G722.1 is a low complexity codec that supports for 7kHz and 14kHz bandwidth 
    47  * audio signals working at bitrates ranging from 16kbps to 48kbps. It may be 
     46 * G.722.1 is a low complexity codec that supports 7kHz and 14kHz audio  
     47 * bandwidth working at bitrates ranging from 16kbps to 48kbps. It may be 
    4848 * used with speech or music inputs. 
    4949 * 
    50  * The codec implementation supports for standard and non-standard bitrates. 
    51  * By default, the standard bitrates are enabled upon initialization, i.e.: 
    52  * - 24kbps and 32kbps for audio bandwidth 7 kHz (16kHz sampling rate), 
    53  * - 24kbps, 32kbps, and 48kbps for audio bandwidth 14 kHz (32kHz sampling  
    54  *   rate). 
    55  * The usage of non-standard bitrates must follow this requirements: 
    56  * - for sampling rate 16kHz: 16000 to 32000 bps, it must be a multiple of 400 
    57  * - for sampling rate 32kHz: 24000 to 48000 bps, it must be a multiple of 400 
    58  * Note that currently it is only up to two non-standard modes can be enabled 
    59  * at one time. 
     50 * 
     51 * \section codec_setting Codec Settings 
     52 * 
     53 * \subsection general_setting General Settings 
     54 * 
     55 * General codec settings for this codec such as VAD and PLC can be  
     56 * manipulated through the <tt>setting</tt> field in #pjmedia_codec_param.  
     57 * Please see the documentation of #pjmedia_codec_param for more info. 
     58 * 
     59 * \subsection specific_setting Codec Specific Settings 
     60 * 
     61 * The following settings are applicable for this codec. 
     62 * 
     63 * \subsubsection bitrate Bitrate 
     64 * 
     65 * The codec implementation supports standard and non-standard bitrates. 
     66 * Use #pjmedia_codec_g7221_set_mode() to enable or disable the bitrates. 
     67 * 
     68 * By default, only standard bitrates are enabled upon initialization: 
     69 * - for 7kHz audio bandwidth (16kHz sampling rate): 24kbps and 32kbps, 
     70 * - for 14kHz audio bandwidth (32kHz sampling rate): 24kbps, 32kbps, and 
     71 *   48kbps. 
     72 * 
     73 * The usage of non-standard bitrates must follow these requirements: 
     74 * - for 7kHz audio bandwidth (16kHz sampling rate): 16000 to 32000 bps,  
     75 *   multiplication of 400 
     76 * - for 14kHz audio bandwidth (32kHz sampling rate): 24000 to 48000 bps, 
     77 *   multiplication of 400 
     78 * 
     79 * \note 
     80 * Currently only up to two non-standard modes can be enabled. 
     81 * 
     82 * \remark 
     83 * There is a flaw in the codec manager as currently it could not 
     84 * differentiate G.722.1 codecs by bitrates, hence invoking  
     85 * #pjmedia_codec_mgr_set_default_param() may only affect a G.722.1 codec 
     86 * with the highest priority (or first index found in codec enumeration  
     87 * when they have same priority) and invoking 
     88 * #pjmedia_codec_mgr_set_codec_priority() will set priority of all G.722.1 
     89 * codecs with sampling rate as specified. 
    6090 */ 
    6191 
    … …  
    6393 
    6494/** 
    65  * Initialize and register G722.1 codec factory to pjmedia endpoint. 
     95 * Initialize and register G.722.1 codec factory to pjmedia endpoint. 
    6696 * 
    6797 * @param endpt     The pjmedia endpoint. 
    … …  
    73103 
    74104/** 
    75  * Enable and disable G722.1 mode. By default, the standard modes are  
     105 * Enable and disable G.722.1 mode. By default, the standard modes are  
    76106 * enabled upon initialization, i.e.: 
    77107 * - sampling rate 16kHz, bitrate 24kbps and 32kbps. 
    78108 * - sampling rate 32kHz, bitrate 24kbps, 32kbps, and 48kbps. 
    79109 * This function can also be used for enabling non-standard modes. 
    80  * Note that currently it is only up to two non-standard modes can be  
    81  * enabled at one time. 
     110 * Note that currently only up to two non-standard modes can be enabled 
     111 * at one time. 
    82112 * 
    83113 * @param sample_rate   PCM sampling rate, in Hz, valid values are only  
    … …  
    111141 
    112142/** 
    113  * Unregister G722.1 codecs factory from pjmedia endpoint. 
     143 * Unregister G.722.1 codecs factory from pjmedia endpoint. 
    114144 * 
    115145 * @return          PJ_SUCCESS on success. 

  • pjproject/trunk/pjmedia/include/pjmedia-codec/gsm.h

    r2875 r3083  
    3434 * @{ 
    3535 * 
    36  * This section describes functions to register and register GSM codec 
     36 * This section describes functions to initialize and register GSM 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 * 
     40 * The GSM codec supports 16-bit PCM with sampling rate of 8000Hz resulting 
     41 * in 13.2kbps bitrate. 
     42 * 
     43 * \section codec_setting Codec Settings 
     44 * 
     45 * \subsection general_setting General Settings 
     46 * 
     47 * General codec settings for this codec such as VAD and PLC can be  
     48 * manipulated through the <tt>setting</tt> field in #pjmedia_codec_param.  
     49 * Please see the documentation of #pjmedia_codec_param for more info. 
     50 * 
     51 * \subsection specific_setting Codec Specific Settings 
     52 * 
     53 * Currently none. 
    3954 */ 
    4055 

  • pjproject/trunk/pjmedia/include/pjmedia-codec/ilbc.h

    r2875 r3083  
    3434 * @{ 
    3535 * 
    36  * This section describes functions to register and register iLBC codec 
     36 * This section describes functions to initialize and register iLBC 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 * 
     40 * The iLBC codec is developed by Global IP Solutions (GIPS), formerly  
     41 * Global IP Sound. The iLBC offers low bitrate and graceful audio quality  
     42 * degradation on frame losses. 
     43 * 
     44 * The iLBC codec supports 16-bit PCM audio signal with sampling rate of  
     45 * 8000Hz operating at two modes: 20ms and 30ms frame length modes, resulting 
     46 * in bitrates of 15.2kbps for 20ms mode and 13.33kbps for 30ms mode. 
     47 * 
     48 * 
     49 * \section codec_setting Codec Settings 
     50 * 
     51 * \subsection general_setting General Settings 
     52 * 
     53 * General codec settings for this codec such as VAD and PLC can be  
     54 * manipulated through the <tt>setting</tt> field in #pjmedia_codec_param.  
     55 * Please see the documentation of #pjmedia_codec_param for more info. 
     56 * 
     57 * \subsection specific_setting Codec Specific Settings 
     58 * 
     59 * The following settings are applicable for this codec. 
     60 * 
     61 * \subsubsection mode Mode 
     62 * 
     63 * The default mode should be set upon initialization, see 
     64 * #pjmedia_codec_ilbc_init(). After the codec is initialized, the default 
     65 * mode can be modified using #pjmedia_codec_mgr_set_default_param(). 
     66 * 
     67 * In #pjmedia_codec_param, iLBC mode can be set by specifying SDP 
     68 * format parameter "mode" in the SDP "a=fmtp" attribute for decoding 
     69 * direction. Valid values are "20" and "30" (for 20ms and 30ms mode  
     70 * respectively). 
     71 * 
     72 * Here is an example to set up #pjmedia_codec_param to use mode 20ms: 
     73 *  \code 
     74    pjmedia_codec_param param; 
     75    ... 
     76    // setting iLBC mode in SDP 
     77    param.setting.dec_fmtp.cnt = 1; 
     78    param.setting.dec_fmtp.param[0].name = pj_str("mode"); 
     79    param.setting.dec_fmtp.param[0].val  = pj_str("20"); 
     80    ... 
     81 \endcode 
    3982 */ 
    4083 

  • 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 

  • pjproject/trunk/pjmedia/include/pjmedia-codec/l16.h

    r2875 r3083  
    2727 * @defgroup PJMED_L16 L16 Codec Family 
    2828 * @ingroup PJMEDIA_CODEC_CODECS 
    29  * @brief PCM/16bit/linear codecs 
     29 * @brief Implementation of PCM/16bit/linear codecs 
    3030 * @{ 
    3131 * 
    32  * This section describes functions to register and register L16 codec 
     32 * This section describes functions to initialize and register L16 codec 
    3333 * factory to the codec manager. After the codec factory has been registered, 
    3434 * application can use @ref PJMEDIA_CODEC API to manipulate the codec. 
    … …  
    3737 * L16 codec types to codec manager (different combinations of clock 
    3838 * rate and number of channels). 
     39 * 
     40 * \section codec_setting Codec Settings 
     41 * 
     42 * \subsection general_setting General Settings 
     43 * 
     44 * General codec settings for this codec such as VAD and PLC can be  
     45 * manipulated through the <tt>setting</tt> field in #pjmedia_codec_param.  
     46 * Please see the documentation of #pjmedia_codec_param for more info. 
     47 * 
     48 * \subsection specific_setting Codec Specific Settings 
     49 * 
     50 * Currently none. 
    3951 */ 
    4052 

  • 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. 

  • pjproject/trunk/pjmedia/include/pjmedia-codec/speex.h

    r2875 r3083  
    3434 * @{ 
    3535 * 
    36  * This section describes functions to register and register speex codec 
     36 * This section describes functions to initialize and register speex 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 * 
     40 * The Speex codec uses multiple bit rates, and supports ultra-wideband  
     41 * (32 kHz sampling rate), wideband (16 kHz sampling rate) and narrowband  
     42 * (telephone quality, 8 kHz sampling rate) 
    3943 * 
    4044 * By default, the speex codec factory registers three Speex codecs: 
    … …  
    4246 * "speex/32000" ultra-wideband codec. This behavior can be changed by 
    4347 * specifying #pjmedia_speex_options flags during initialization. 
     48 * 
     49 * 
     50 * \section codec_setting Codec Settings 
     51 * 
     52 * \subsection general_setting General Settings 
     53 * 
     54 * General codec settings for this codec such as VAD and PLC can be  
     55 * manipulated through the <tt>setting</tt> field in #pjmedia_codec_param.  
     56 * Please see the documentation of #pjmedia_codec_param for more info. 
     57 * 
     58 * \subsection specific_setting Codec Specific Settings 
     59 * 
     60 * The following settings are applicable for this codec. 
     61 * 
     62 * \subsubsection quality_vs_complexity Quality vs Complexity 
     63 * 
     64 * The Speex codec quality versus computational complexity and bandwidth 
     65 * requirement can be adjusted by modifying the quality and complexity 
     66 * setting, by calling #pjmedia_codec_speex_set_param(). The RFC 5574 
     67 * Section 5 shows the relationship between quality setting and the 
     68 * resulting bitrate. 
     69 * 
     70 * The default setting of quality is specified in  
     71 * #PJMEDIA_CODEC_SPEEX_DEFAULT_QUALITY. And the default setting of 
     72 * complexity is specified in #PJMEDIA_CODEC_SPEEX_DEFAULT_COMPLEXITY. 
    4473 */ 
    4574 

  • pjproject/trunk/pjmedia/include/pjmedia/g711.h

    r2875 r3083  
    2929 
    3030/** 
    31  * @defgroup PJMED_G711 G711 G.711 Codec 
     31 * @defgroup PJMED_G711 G.711 Codec 
    3232 * @ingroup PJMEDIA_CODEC_CODECS 
    3333 * @brief Standard G.711/PCMA and PCMU codec. 
    3434 * @{ 
    35  * This section describes functions to register and register G.711 codec 
     35 * 
     36 * This section describes functions to initialize and register G.711 codec 
    3637 * factory to the codec manager. After the codec factory has been registered, 
    3738 * application can use @ref PJMEDIA_CODEC API to manipulate the codec. 
     39 * 
     40 * The G.711 is an ultra low complexity codecs and in trade-off it results 
     41 * in high bitrate, i.e: 64kbps for 16-bit PCM with sampling rate 8000Hz. 
     42 * 
     43 * The factory contains two main compression algorithms, PCMU/u-Law and  
     44 * PCMA/A-Law. 
     45 * 
     46 * \section codec_setting Codec Settings 
     47 * 
     48 * \subsection general_setting General Settings 
     49 * 
     50 * General codec settings for this codec such as VAD and PLC can be  
     51 * manipulated through the <tt>setting</tt> field in #pjmedia_codec_param.  
     52 * Please see the documentation of #pjmedia_codec_param for more info. 
     53 * 
     54 * \subsection specific_setting Codec Specific Settings 
     55 * 
     56 * Currently none. 
    3857 */ 
    3958 
Note: See TracChangeset for help on using the changeset viewer.