...
[speexdsp.git] / doc / draft-herlein-speex-rtp-profile-00.txt
1
2
3
4
5
6
7 Internet Engineering Task Force                          Greg Herlein
8 Internet Draft                                        Jean-Marc Valin
9 draft-herlein-speex-rtp-profile-00                       Simon Morlat
10 February, 2002
11 Expires: July, 2003
12
13
14              RTP Payload Format for the Speex Codec
15
16 Status of this Memo
17
18    This document is an Internet-Draft and is in full conformance with
19    all provisions of Section 10 of RFC2026.
20
21    Internet-Drafts are working documents of the Internet Engineering
22    Task Force (IETF), its areas, and its working groups.  Note that
23    other groups may also distribute working documents as Internet-
24    Drafts.
25
26    Internet-Drafts are draft documents valid for a maximum of six
27    months and may be updated, replaced, or obsoleted by other
28    documents at any time.  It is inappropriate to use Internet-Drafts
29    as reference material or to cite them other than as "work in
30    progress".
31
32    The list of current Internet-Drafts can be accessed at
33    http://www.ietf.org/ietf/1id-abstracts.txt
34
35    To view the list Internet-Draft Shadow Directories, see
36    http://www.ietf.org/shadow.html.
37
38 Copyright Notice
39
40    Copyright (C) The Internet Society (2002).  All Rights Reserved.
41
42
43 Abstract
44
45 Speex is an open-source, patent-free voice codec suitable for use in
46 Voice over IP (VoIP) type applications.  The Speex codec supports three
47 modes of operation: narrowband at a nominal 8kHz sample rate, 
48 wideband at a nominal 16kHz sample rate, and ultra-wideband at a
49 nominal 32kHz sample rate.  Speex supports Voice Activity Detection
50 (VAD)  and Variable Bit Rate (VBR).  This document describes the 
51 payload format for Speex generated bit streams within an RTP packet.  
52 Also included here are the necessary details for the use
53 of Speex with the Session Description Protocol (SDP) [4] and a preliminary
54 method of using Speex within H.323 applications.  Use of Speex with 
55 MIME will be covered as part of the Ogg Vorbis MIME definitions and is
56 covered only minimally here.
57
58 Herlein, Valin, etc                                         [Page 1]
59 ^L
60 Internet-Draft    RTP Payload Format for the Speex Codec    Nov 2002
61
62
63 1. Conventions used in this document
64
65    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
66    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
67    document are to be interpreted as described in RFC-2119 [5].
68
69 2. Overview of the Speex Codec
70
71 Speex is based on the CELP encoding technique with support for either
72 narrowband (nominal 8kHz), wideband (nominal 16kHz) or ultra-wideband
73 (nominal 32kHz) sampling.  The main characteristics can be summerized
74 as follows:
75
76    o  Free software/open-source, royalty-free
77    o  Integration of wideband and narrowband in the same bit-stream
78    o  Wide range of bit-rates available
79    o  Dynamic bit-rate switching and variable bit-rate (VBR)
80    o  Voice Activity Detection (VAD, integrated with VBR)
81    o  Variable complexity
82
83
84 3. RTP payload format for Speex
85
86    Speex uses 20 ms frames and a variable sampling rate clock.  The
87    RTP timestamp MUST be in units of 1/X of a second where X is the
88    sample rate used.  Speex uses a nominal 8kHz sampling rate for
89    narrowband use, a nominal 16kHz sampling rate for wideband use, and
90    a nominal 32kHz sampling rate for ultra-wideband use.
91
92    The RTP payload for Speex has the format shown in Figure 1.  No
93    additional header specific to this payload format is required.
94
95        0                   1                   2                   3
96        0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
97       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
98       |                      RTP Header [2]                           |
99       +=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+
100       |                                                               |
101       +                 one or more frames of Speex                   |
102       |                             ....                            |p|
103       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
104
105                      Figure 1: RTP payload for Speex
106
107    The encoding and decoding algorithm can change the bit rate at any
108    20ms frame boundary but the bit rate change notification is
109    provided in-band with the bit stream.  Each frame contains both
110    "mode" (narrowband,wideband or ultra-wideband) and "sub-mode"
111    (bit-rate) information in the bit stream.  No out-of-band
112    notification is required for the decoder to process changes in the
113    bit rate sent by the encoder.
114
115 Herlein, Valin, etc                                         [Page 2]
116 ^L
117 Internet-Draft    RTP Payload Format for the Speex Codec    Nov 2002
118
119
120    For the purposes of packetizing the bit stream in RTP, it is only
121    necessary to consider the sequence of bits as output by the Speex
122    encoder, and present the same sequence to the decoder.  The payload
123    format described here maintains this sequence.
124
125    An RTP packet MAY contain Speex frames of the same bit rate or of
126    varying bit rates, since the bit-rate for a frame is conveyed in
127    band with the signal.
128
129    It is RECOMMENDED that values of 8000 or 16000 be used for normal
130    internet telephony applications, though the sample rate is
131    supported at rates as low as 6000 Hz and as high as 32 kHz.
132
133    The RTP payload MUST be padded to provide an integer number of
134    octets as the payload length.  These padding bits MUST be all zero.
135    This padding is only required for the last frame in the packet, and
136    only to ensure the packet contents ends on an octet boundary.
137
138
139 3.1 RTP Payload Type Codes
140
141    The RTP Audio-Visual Working Group will no longer issue static
142    payload type codes for RTP (beyond those already assigned).
143    Dynamic payload type codes MUST be negotiated 'out-of-band'
144    for the assignment of a dynamic payload type from the
145    range of 96-127.  Examples of this are shown in the section
146    discussing the Session Description Protocol (SDP) below.
147
148
149 3.2 Multiple Speex frames in a RTP packet
150
151    By default only one Speex frame is permitted in a single RTP
152    packet.  When operating with multiple frames per packet then the
153    end points MUST use out-of-band negotiation to determine the number
154    of frames per packet.  See section 5 below for an example of how to
155    do this with SDP [4].
156   
157
158 3.3 Computing the number of Speex frames
159
160    If using SDP [4] (see section 5 below for an example) this can be
161    done using the "ptime" variable to denote the packetization
162    interval (ie, how many milliseconds of audio is encoded in a single
163    RTP packet).  Since Speex uses 20ms frames, ptime values of
164    multiples of 20 denote multiple Speex frames per packet.  Values of
165    ptime in other than multiples of 20 SHOULD be ignored and SHOULD
166    use the default value of one instead.
167
168
169 4. MIME registration of Speex
170
171    Full definition of the MIME type for Speex will be part of the Ogg
172    Vorbis MIME type definition application.  
173
174    MIME media type name: audio
175
176    MIME subtype: speex
177
178    Required parameters: to be included in the Ogg MIME specification.
179
180 Herlein, Valin, etc                                         [Page 3]
181 ^L
182 Internet-Draft    RTP Payload Format for the Speex Codec    Nov 2002
183
184
185    Optional parameters:
186
187    Encoding considerations:
188
189    Security Considerations:
190          See Section 6 of RFC 3047.
191
192    Interoperability considerations: none
193
194    Published specification:
195
196    Applications which use this media type:
197
198    Additional information: none
199
200    Person & email address to contact for further information:
201          Greg Herlein <gherlein@herlein.com>
202          Jean-Marc Valin <jean-marc.valin@hermes.usherb.ca>
203
204    Intended usage: COMMON
205
206    Author/Change controller:
207          Author:  Greg Herlein <gherlein@herlein.com>
208          Change controller: Greg Herlein <gherlein@herlein.com>
209
210
211 Herlein, Valin, etc                                         [Page 4]
212 ^L
213 Internet-Draft    RTP Payload Format for the Speex Codec    Nov 2002
214
215
216 5. SDP usage of Speex
217
218    When conveying information by SDP [4], the encoding name SHALL be
219    "speex".  An example of the media representation in SDP for
220    offering a single channel of Speex at 8000 samples per second might
221    be:
222
223         m=audio 8088 RTP/AVP 97
224         a=rtpmap:97 speex/8000
225
226    Note that the RTP payload type code of 97 is defined in this media
227    definition to be 'mapped' to the speex codec at an 8kHz sampling
228    frequency using the 'a=rtpmap' line.  Any number from 96 to 127
229    could have been chosen (the allowed range for dynamic types).  The
230    value of the sampling frequency is typically 8000 for narrow band
231    operation, 16000 for wide band operation, and 32000 for ultra-wide
232    band operation.
233
234    If for some reason the offerer has bandwith limitations, he may use
235    the "b=" header, as explained in SDP [4]. The following example
236    illustrates the case where the offerer cannot receive more than
237    10 kbit/s.
238
239         m=audio 8088 RTP/AVP 97
240         b=AS:10
241         a=rtmap:97 speex/8000
242
243    In this case, if the remote part agrees, it should configure its
244    speex encoder so that it does not use modes that produce more than
245    10 kbit/s. Note that the "b=" constraint also applies on all
246    payload types that may be proposed in the media line ("m=").
247
248    An other way to make recommendations to the remote speex encoder
249    is to use its specific parameters via the a=fmtp: directive.  The
250    following parameters are defined for use in this way:
251
252          ptime: duration of each packet in milliseconds.
253
254          sr:    actual sample rate in Hz.
255
256          ebw:   encoding bandwidth - either 'narrow' or 'wide' or 
257                 'ultra' (corresponds to nominal 8000, 16000, and
258                 32000 Hz sampling rates).
259
260          vbr:   variable bit rate  - either 'on' 'off' or 'vad'
261                 (defaults to off).  If on, variable bit rate is
262                 enabled.  If off, disabled.  If set to 'vad' then
263                 constant bit rate is used but silence will be encoded
264                 with special short frames to indicate a lack of voice
265                 for that period.
266
267          cng:   comfort noise generation - either 'on' or 'off'. If
268                 off then silence frames will be silent; if 'on' then
269                 those frames will be filled with comfort noise.
270
271          mode:  speex encoding mode. Can be {1,2,3,4,5,6,any}
272                 defaults to 3 in narrowband, 6 in wide and ultra-wide.
273
274          penh:  use of perceptual enhancement. 1 indicates 
275                 to the decoder that perceptual enhancement is recommended,
276                 0 indicates that it is not. Defaults to on (1).
277
278
279 Herlein, Valin, etc                                         [Page 5]
280 ^L
281 Internet-Draft    RTP Payload Format for the Speex Codec    Nov 2002
282
283
284    Examples:
285
286         m=audio 8008 RTP/AVP 97
287         a=rtpmap:97 speex/8000
288         a=fmtp:97 mode=4
289
290    This examples illustrate an offerer that wishes to receive
291    a speex stream at 8000Hz, but only using speex mode 3.
292    
293    The offerer may suggest to the remote decoder to activate
294    its perceptual enhancement filter like this:
295    
296         m=audio 8088 RTP/AVP 97
297         a=rtmap:97 speex/8000
298         a=fmtp:97 penh=1 
299         
300    Several speex specific parameters can be given in a single
301    a=fmtp line provided that they are separated by a semi-colon:
302    
303         a=fmtp:97 mode=any;penh=1
304
305    The offerer may indicate that it wishes to send variable bit rate
306    frames with comfort noise:
307
308         m=audio 8088 RTP/AVP 97
309         a=rtmap:97 speex/8000
310         a=fmtp:97 vbr=on;cng=on
311
312         
313    The use of a particular packetization interval may be
314    suggested to the remote encoder using the ptime parameter:
315    
316         m=audio 8008 RTP/AVP 97
317         a=rtpmap:97 speex/8000
318         a=ptime:40
319         
320    Note that the ptime parameter applies to all payloads listed
321    in the media line and is not used as part of an a=fmtp directive.
322
323    Speex can encode frames of 20 ms. Values of ptime not multiple
324    of 20 ms are meaningless, so the receiver of such ptime values
325    SHOULD ignore them.
326
327
328 Herlein, Valin, etc                                         [Page 6]
329 ^L
330 Internet-Draft    RTP Payload Format for the Speex Codec    Nov 2002
331
332 6. ITU H.323/H.245 Use of Speex
333
334    Application is underway to make Speex a standard ITU codec.
335    However, until that is finalized, Speex MAY be used in H.323 [6] by
336    using a non-standard codec block definition in the H.245 [7] codec
337    capability negotiations.  
338
339
340 6.1  NonStandardMessage format
341
342    For Speex use in H.245 [7] based systems, the fields in the
343    NonStandardMessage should be:
344
345    t35CountryCode   = Hex: B5
346    t35Extension     = Hex: 00
347    manufacturerCode = Hex: 0026
348    [Length of the Binary Sequence (8 bit number)]
349    [Binary Sequence consisting of an ASCII string, no NULL terminator]
350
351    The binary sequence is an ascii string merely for ease of use.
352    The string is not null terminated.  The format of this string is
353
354        speex [optional variables]
355    
356    The optional variables are identical to those used for the SDP
357    a=fmtp strings discussed in section 5 above.  The string is built
358    to be all on one line, each key-value pair seperated by a
359    semi-colon.  The optional variables MAY be ommited, which causes
360    the default values to be assumed.  They are:
361
362        ebw=narrow;mode=3;vbr=off;cng=off;ptime=20;sr=8000;penh=no;
363
364    The fifth byte of the block is the length of the binary sequence.
365
366    NOTE:  this method can result in the advertising of a large number
367    of Speex 'codecs' based on the number of variables possible.  For
368    most VoIP applications, use of the defailt binary sequence of
369    'speex' is RECOMMENDED to be used in addition to all other options.
370    This maximizes the chances that two H.323 based applications that
371    support Speex can find a mutual codec.   
372
373 6.2 RTP Payload Types
374
375    Dynamic payload type codes MUST be negotiated 'out-of-band'
376    for the assignment of a dynamic payload type from the
377    range of 96-127.  H.323 applications MUST use the H.245
378    H2250LogicalChannelParameters encoding to accomplish this.  
379
380
381 7. Security Considerations
382
383    RTP packets using the payload format defined in this specification
384    are subject to the security considerations discussed in the RTP
385    specification [2], and any appropriate RTP profile.  This implies
386    that confidentiality of the media streams is achieved by encryption.
387    Because the data compression used with this payload format is applied
388    end-to-end, encryption may be performed after compression so there is
389    no conflict between the two operations.
390
391    A potential denial-of-service threat exists for data encodings using
392    compression techniques that have non-uniform receiver-end
393    computational load.  The attacker can inject pathological datagrams
394    into the stream which are complex to decode and cause the receiver to
395    be overloaded.  However, this encoding does not exhibit any
396    significant non-uniformity.
397
398    As with any IP-based protocol, in some circumstances a receiver may
399    be overloaded simply by the receipt of too many packets, either
400    desired or undesired.  Network-layer authentication may be used to
401    discard packets from undesired sources, but the processing cost of
402    the authentication itself may be too high.  
403
404
405 8. References
406
407    1. Bradner, S., "The Internet Standards Process -- Revision 3", BCP
408       9, RFC 2026, October 1996.
409
410    2. Schulzrinne, H., Casner, S., Frederick, R. and V. Jacobson, "RTP:
411       A Transport Protocol for real-time applications", RFC 1889,
412       January 1996.  (Updated by a Work in Progress.)
413
414    3. Freed, N. and N. Borenstein, "Multipurpose Internet Mail
415       Extensions (MIME) Part One: Format of Internet Message Bodies",
416       RFC 2045, November 1996.
417
418    4. Handley, M. and V. Jacobson, "SDP: Session Description Protocol",
419       RFC 2327, April 1998.
420
421    5. Bradner, S., "Key words for use in RFCs to Indicate Requirement
422       Levels", BCP 14, RFC 2119, March 1997.
423
424    6. ITU-T Recommendation H.323.  "Packet-based Multimedia Communications
425      Systems," 1998.
426
427    7. ITU-T Recommendation H.245 (1998), "Control of communications
428       between Visual Telephone Systems and Terminal Equipment".
429
430 9. Acknowledgments
431
432    The authors would like to thank Equivalence Pty Ltd of Australia
433    for their assistance in attempting to standardize the use of Speex
434    in H.323 applications, and for implementing Speex in their open
435    source OpenH323 stack.  The authors would also like to thank Brian
436    C. Wiles <brian@streamcomm.com> of StreamComm for his assistance in
437    developing the proposed standard for Speex use in H.323
438    applications.
439
440
441 10. Author's Address
442
443    Greg Herlein <gherlein@herlein.com>
444    2034 Filbert Street
445    San Francisco, CA 
446    United States 94123
447    
448
449    Jean-Marc Valin <jean-marc.valin@hermes.usherb.ca>
450    Department of electrical and computer engineering
451    University of Sherbrooke
452    2500 blvd Universit√©
453    Sherbrooke, Quebec, Canada, J1K 2R1
454
455
456    Simon MORLAT <simon.morlat@linphone.org>
457    35, av de Vizille App 42
458    38000 GRENOBLE
459    FRANCE
460
461
462    Roger Hardiman <roger@freebsd.org>
463    49 Nettleton Road
464    Cheltenham
465    Gloucestershire
466    GL51 6NR
467    England
468
469
470 Herlein, Valin, etc                                         [Page 7]
471 ^L
472 Internet-Draft    RTP Payload Format for the Speex Codec    Nov 2002
473
474 10. Full Copyright Statement
475
476    Copyright (C) The Internet Society (2001).  All Rights Reserved.
477
478    This document and translations of it may be copied and furnished to
479    others, and derivative works that comment on or otherwise explain it
480    or assist in its implementation may be prepared, copied, published
481    and distributed, in whole or in part, without restriction of any
482    kind, provided that the above copyright notice and this paragraph are
483    included on all such copies and derivative works.  However, this
484    document itself may not be modified in any way, such as by removing
485    the copyright notice or references to the Internet Society or other
486    Internet organizations, except as needed for the purpose of
487    developing Internet standards in which case the procedures for
488    copyrights defined in the Internet Standards process must be
489    followed, or as required to translate it into languages other than
490    English.
491
492    The limited permissions granted above are perpetual and will not be
493    revoked by the Internet Society or its successors or assigns.
494
495    This document and the information contained herein is provided on an
496    "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
497    TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
498    BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
499    HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
500    MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
501
502 Acknowledgement
503
504    Funding for the RFC Editor function is currently provided by the
505    Internet Society.
506
507
508
509
510 Herlein, Valin, etc                                         [Page 8]
511 ^L