idnits 2.17.1 draft-ietf-avtext-mixer-to-client-audio-level-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 16, 2011) is 4537 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'ITU.P56.1993' is defined on line 553, but no explicit reference was found in the text ** Obsolete normative reference: RFC 5285 (Obsoleted by RFC 8285) == Outdated reference: A later version (-05) exists of draft-ietf-avtcore-srtp-encrypted-header-ext-01 == Outdated reference: A later version (-04) exists of draft-ietf-avtcore-srtp-vbr-audio-03 == Outdated reference: A later version (-06) exists of draft-ietf-avtext-client-to-mixer-audio-level-05 Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Ivov, Ed. 3 Internet-Draft Jitsi 4 Intended status: Standards Track E. Marocco, Ed. 5 Expires: May 19, 2012 Telecom Italia 6 J. Lennox 7 Vidyo, Inc. 8 November 16, 2011 10 A Real-Time Transport Protocol (RTP) Header Extension for Mixer-to- 11 Client Audio Level Indication 12 draft-ietf-avtext-mixer-to-client-audio-level-06 14 Abstract 16 This document describes a mechanism for RTP-level mixers in audio 17 conferences to deliver information about the audio level of 18 individual participants. Such audio level indicators are transported 19 in the same RTP packets as the audio data they pertain to. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on May 19, 2012. 38 Copyright Notice 40 Copyright (c) 2011 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 3. Protocol Operation . . . . . . . . . . . . . . . . . . . . . . 4 58 4. Audio Levels . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 5. Signaling Information . . . . . . . . . . . . . . . . . . . . 7 60 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 61 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 62 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 63 9. Changes From Earlier Versions . . . . . . . . . . . . . . . . 11 64 9.1. Changes From Draft -05 . . . . . . . . . . . . . . . . . . 11 65 9.2. Changes From Draft -04 . . . . . . . . . . . . . . . . . . 12 66 9.3. Changes From Draft -03 . . . . . . . . . . . . . . . . . . 12 67 9.4. Changes From Draft -02 . . . . . . . . . . . . . . . . . . 12 68 9.5. Changes From Draft -01 . . . . . . . . . . . . . . . . . . 12 69 9.6. Changes From Draft -00 . . . . . . . . . . . . . . . . . . 13 70 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 71 10.1. Normative References . . . . . . . . . . . . . . . . . . . 13 72 10.2. Informative References . . . . . . . . . . . . . . . . . . 13 73 Appendix A. Reference Implementation . . . . . . . . . . . . . . 14 74 A.1. AudioLevelCalculator.java . . . . . . . . . . . . . . . . 14 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17 77 1. Introduction 79 The Framework for Conferencing with the Session Initiation Protocol 80 (SIP) defined in RFC 4353 [RFC4353] presents an overall architecture 81 for multi-party conferencing. Among others, the framework borrows 82 from RTP [RFC3550] and extends the concept of a mixer entity 83 "responsible for combining the media streams that make up a 84 conference, and generating one or more output streams that are 85 delivered to recipients". Every participant would hence receive, in 86 a flat single stream, media originating from all the others. 88 Using such centralized mixer-based architectures simplifies support 89 for conference calls on the client side since they would hardly 90 differ from one-to-one conversations. However, the method also 91 introduces a few limitations. The flat nature of the streams that a 92 mixer would output and send to participants makes it difficult for 93 users to identify the original source of what they are hearing. 95 Mechanisms that allow the mixer to send to participants cues on 96 current speakers (e.g. the CSRC fields in RTP [RFC3550]) only work 97 for speaking/silent binary indications. There are, however, a number 98 of use cases where one would require more detailed information. 99 Possible examples include the presence of background chat/noise/ 100 music/typing, someone breathing noisily in their microphone, or other 101 cases where identifying the source of the disturbance would make it 102 easy to remove it (e.g. by sending a private IM to the concerned 103 party asking them to mute their microphone). A more advanced 104 scenario could involve an intense discussion between multiple 105 participants that the user does not personally know. Audio level 106 information would help better recognize the speakers by associating 107 with them complex (but still human readable) characteristics like 108 loudness and speed for example. 110 One way of presenting such information in a user friendly manner 111 would be for a conferencing client to attach audio level indicators 112 to the corresponding participant related components in the user 113 interface. One possible example is displayed in Figure 1 where 114 levels can help users determine that Alice is currently the active 115 speaker, Carol is mute, and Bob and Dave are sending some background 116 noise. 118 ________________________ 119 | | 120 | 00:42 | Weekly Call | 121 |________________________| 122 | | 123 | | 124 | Alice |====== | (S) | 125 | | 126 | Bob |= | | 127 | | 128 | Carol | | (M) | 129 | | 130 | Dave |=== | | 131 | | 132 |________________________| 134 Figure 1: Displaying detailed speaker information to the user by 135 including audio level for every participant. 137 Implementing a user interface like the above requires analysis of the 138 media sent from other participants. In a conventional audio 139 conference this is only possible for the mixer since all other 140 conference participants are generally receiving a single, flat audio 141 stream and have therefore no immediate way of determining individual 142 audio levels. 144 This document specifies an RTP extension header that allows such 145 mixers to deliver audio level information to conference participants 146 by including it directly in the RTP packets transporting the 147 corresponding audio data. 149 2. Terminology 151 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 152 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 153 document are to be interpreted as described in RFC 2119 [RFC2119]. 155 3. Protocol Operation 157 According to RFC 3550 [RFC3550] a mixer is expected to include in 158 outgoing RTP packets a list of identifiers (CSRC IDs) indicating the 159 sources that contributed to the resulting stream. The presence of 160 such CSRC IDs allows RTP clients to determine, in a binary way, the 161 active speaker(s) in any given moment. RTCP also provides a basic 162 mechanism to map the CSRC IDs to user identities through the CNAME 163 field. More advanced mechanisms can exist depending on the signaling 164 protocol used to establish and control a conference. In the case of 165 the Session Initiation Protocol [RFC3261] for example, the Event 166 Package for Conference State [RFC4575] defines a tag which 167 binds CSRC IDs to media streams and SIP URIs. 169 This document describes an RTP header extension that allows mixers to 170 indicate the audio-level of every contributing conference participant 171 (CSRC) in addition to simply indicating their on/off status. This 172 new header extension uses "General Mechanism for RTP Header 173 Extensions" described in [RFC5285]. 175 Each instance of this header contains a list of one-octet audio 176 levels expressed in -dBov, with values from 0 to 127 representing 0 177 to -127 dBov(see Figure 2 and Figure 3). Appendix A provides a 178 reference implementation indicating one way of obtaining such values 179 from raw audio samples. 181 Every audio level value pertains to the CSRC identifier located at 182 the corresponding position in the CSRC list. In other words, the 183 first value would indicate the audio level of the conference 184 participant represented by the first CSRC identifier in that packet 185 and so forth. The number and order of these values MUST therefore 186 match the number and order of the CSRC IDs present in the same 187 packet. 189 When encoding audio level information, a mixer SHOULD include in a 190 packet information that corresponds to the audio data being 191 transported in that same packet. It is important that these values 192 follow the actual stream as closely as possible. Therefore a mixer 193 SHOULD also calculate the values after the original contributing 194 stream has undergone possible processing such as level normalization, 195 and noise reduction for example. 197 It can sometimes happen that a conference involves more than a single 198 mixer. In such cases each of the mixers MAY choose to relay the CSRC 199 list and audio-level information they receive from peer mixers (as 200 long as the total CSRC count remains below 16). Given that the 201 maximum audio level is not precisely defined by this specification, 202 it is likely that in such situations average audio levels would be 203 perceptibly different for the participants located behind the 204 different mixers. 206 4. Audio Levels 208 The audio level header extension carries the level of the audio in 209 the RTP payload of the packet it is associated with. This 210 information is carried in an RTP header extension element as defined 211 by the "General Mechanism for RTP Header Extensions" [RFC5285]. 213 The payload of the audio level header extension element can be 214 encoded using the one-byte or the two-byte header defined in 215 [RFC5285]. Figure 2 and Figure 3 show sample audio level encodings 216 with each of them. 218 0 1 2 3 219 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 220 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 221 | ID | len=2 |0| level 1 |0| level 2 |0| level 3 | 222 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 224 Sample audio level encoding using the one-byte header format 226 Figure 2 228 0 1 2 3 229 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 230 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 231 | ID | len=3 |0| level 1 |0| level 2 | 232 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 233 |0| level 3 | 0 (pad) | ... 234 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 236 Sample audio level encoding using the two-byte header format 238 Figure 3 240 In the case of the one-byte header format, the 4-bit len field is the 241 number minus one of data bytes (i.e. audio level values) transported 242 in this header extension element following the one-byte header. 243 Therefore, the value zero in this field indicates that one byte of 244 data follows. In the case of the two-byte header format the 8-bit 245 len field contains the exact number of audio levels carried in the 246 extension. RFC 3550 [RFC3550] only allows RTP packets to carry a 247 maximum of 15 CSRC IDs. Given that audio levels directly refer to 248 CSRC IDs, implementations MUST NOT include more than 15 audio level 249 values. The maximum value allowed in the len field is therefore 14 250 for one-byte header format and 15 for two-byte header format. 252 Audio levels in this document are defined in the same manner as is 253 audio noise level in the RTP Payload Comfort Noise specification 254 [RFC3389]. In the comfort noise specification, the overall magnitude 255 of the noise level in comfort noise is encoded into the first byte of 256 the payload, with spectral information about the noise in subsequent 257 bytes. This specification's audio level parameter is defined so as 258 to be identical to the comfort noise payload's noise-level byte. 260 The magnitude of the audio level itself is packed into the seven 261 least significant bits of the single byte of the header extension, 262 shown in Figure 2 and Figure 3. The least significant bit of the 263 audio level magnitude is packed into the least significant bit of the 264 byte. The most significant bit of the byte is unused and always set 265 to 0. 267 The audio level is expressed in -dBov, with values from 0 to 127 268 representing 0 to -127 dBov. dBov is the level, in decibels, relative 269 to the overload point of the system, i.e. the highest-intensity 270 signal encodable by the payload format. (Note: Representation 271 relative to the overload point of a system is particularly useful for 272 digital implementations, since one does not need to know the relative 273 calibration of the analog circuitry.) For example, in the case of 274 u-law (audio/pcmu) audio [ITU.G.711], the 0 dBov reference would be a 275 square wave with values +/- 8031. (This translates to 6.18 dBm0, 276 relative to u-law's dBm0 definition in Table 6 of G.711.) 278 The audio level for digital silence, for example for a muted audio 279 source, MUST be represented as 127 (-127 dBov), regardless of the 280 dynamic range of the encoded audio format. 282 The audio level header extension only carries the level of the audio 283 in the RTP payload of the packet it is associated with, with no long- 284 term averaging or smoothing applied. That level is measured as a 285 root mean square of all the samples in the measured range. 287 To simplify implementation of the encoding procedures described here, 288 this specification provides a sample Java implementation (Appendix A) 289 of an audio level calculator that helps obtain such values from raw 290 linear PCM audio samples. 292 5. Signaling Information 294 The URI for declaring the audio level header extension in an SDP 295 extmap attribute and mapping it to a local extension header 296 identifier is "urn:ietf:params:rtp-hdrext:csrc-audio-level". There 297 is no additional setup information needed for this extension (i.e. no 298 extensionattributes). 300 An example attribute line in the SDP, for a conference might be: 302 a=extmap:7 urn:ietf:params:rtp-hdrext:csrc-audio-level 304 The above mapping will most often be provided per media stream (in 305 the media-level section(s) of SDP, i.e., after an "m=" line) or 306 globally if there is more than one stream containing audio level 307 indicators in a session. 309 Presence of the above attribute in the SDP description of a media 310 stream indicates that RTP packets in that stream, which contain the 311 level extension defined in this document, will be carrying them with 312 an ID of 7. 314 Conferencing clients that support audio level indicators and have no 315 mixing capabilities would not be able to provide content for this 316 audio level extension and would hence have to always include the 317 direction parameter in the "extmap" attribute with a value of 318 "recvonly". Conference focus entities with mixing capabilities can 319 omit the direction or set it to "sendrecv" in SDP offers. Such 320 entities would need to set it to "sendonly" in SDP answers to offers 321 with a "recvonly" parameter and to "sendrecv" when answering other 322 "sendrecv" offers. 324 This specification only defines use of the audio level extensions in 325 audio streams. They MUST NOT be advertised with other media types 326 such as video or text for example. 328 The following Figure 4 and Figure 5 show two example offer/answer 329 exchanges between a conferencing client and a focus, and between two 330 conference focus entities. 332 SDP Offer: 334 v=0 335 o=alice 2890844526 2890844526 IN IP6 host.example.com 336 s=- 337 c=IN IP6 host.example.com 338 t=0 0 339 m=audio 49170 RTP/AVP 0 4 340 a=rtpmap:0 PCMU/8000 341 a=rtpmap:4 G723/8000 342 a=extmap:1/recvonly urn:ietf:params:rtp-hdrext:csrc-audio-level 344 SDP Answer: 346 v=0 347 i=A Seminar on the session description protocol 348 o=conf-focus 2890844730 2890844730 IN IP6 focus.example.net 349 s=- 350 c=IN IP6 focus.example.net 351 t=0 0 352 m=audio 52544 RTP/AVP 0 353 a=rtpmap:0 PCMU/8000 354 a=extmap:1/sendonly urn:ietf:params:rtp-hdrext:csrc-audio-level 356 A client-initiated example SDP offer/answer exchange negotiating an 357 audio stream with one-way flow of audio level information. 359 Figure 4 361 SDP Offer: 363 v=0 364 i=Un seminaire sur le protocole de description des sessions 365 o=fr-focus 2890844730 2890844730 IN IP6 focus.fr.example.net 366 s=- 367 c=IN IP6 focus.fr.example.net 368 t=0 0 369 m=audio 49170 RTP/AVP 0 370 a=rtpmap:0 PCMU/8000 371 a=extmap:1/sendrecv urn:ietf:params:rtp-hdrext:csrc-audio-level 373 SDP Answer: 375 v=0 376 i=A Seminar on the session description protocol 377 o=us-focus 2890844526 2890844526 IN IP6 focus.us.example.net 378 s=- 379 c=IN IP6 focus.us.example.net 380 t=0 0 381 m=audio 52544 RTP/AVP 0 382 a=rtpmap:0 PCMU/8000 383 a=extmap:1/sendrecv urn:ietf:params:rtp-hdrext:csrc-audio-level 385 An example SDP offer/answer exchange between two conference focus 386 entities with mixing capabilities negotiating an audio stream with 387 bidirectional flow of audio level information. 389 Figure 5 391 6. Security Considerations 393 1. This document defines a means of attributing audio level to a 394 particular participant in a conference. An attacker may try to 395 modify the content of RTP packets in a way that would make audio 396 activity from one participant appear as coming from another. 397 2. Furthermore, the fact that audio level values would not be 398 protected even in an SRTP session might be of concern in some 399 cases where the activity of a particular participant in a 400 conference is confidential. Also, as discussed in 401 [I-D.ietf-avtcore-srtp-vbr-audio], an attacker might be able to 402 infer information about the conversation, possibly with phoneme- 403 level resolution. 404 3. Both of the above are concerns that stem from the design of the 405 RTP protocol itself and they would probably also apply when using 406 CSRC identifiers the way they were specified in RFC 3550 407 [RFC3550]. It is therefore important that according to the needs 408 of a particular scenario, implementors and deployers consider use 409 of header extension encryption 410 [I-D.ietf-avtcore-srtp-encrypted-header-ext] or a lower level 411 security and authentication mechanism such as IPsec [RFC4301] for 412 example. 414 7. IANA Considerations 416 This document defines a new extension URI in the RTP Compact Header 417 Extensions sub-registry of the Real-Time Transport Protocol (RTP) 418 Parameters registry, according to the following data: 420 Extension URI: urn:ietf:params:rtp-hdrext:csrc-audio-level 421 Description: Mixer-to-client audio level indicators 422 Contact: emcho@jitsi.org 423 Reference: RFC XXXX 425 Note to the RFC-Editor: please replace "RFC XXXX" by the number of 426 this RFC. 428 8. Acknowledgments 430 Lyubomir Marinov contributed level measurement and rendering code. 432 Keith Drage, Roni Even, Miguel A. Garcia, John Elwell, Kevin P. 433 Fleming, Ingemar Johansson, Michael Ramalho, Magnus Westerlund and 434 several others provided helpful feedback over the avt and avtext 435 mailing lists. 437 Jitsi's participation in this specification is funded by the NLnet 438 Foundation. 440 9. Changes From Earlier Versions 442 Note to the RFC-Editor: please remove this section prior to 443 publication as an RFC. 445 9.1. Changes From Draft -05 447 o Added proper licensing to the code samples. (Brought up by Sean 448 Turner). 449 o Added an informative reference to RFC 4301 (IPsec). (Brought up 450 by Stephen Farrell) 452 o Briefly explained the meaning of the (S) and (M) symbols in the 453 introductory UI example. Added "SDP Offer" and "SDP Answer" 454 subtitles in the SDP examples. Fixed typos. Removed conditional 455 language in the IANA considerations section (Brought up by Dan 456 Romascanu, Lionel Morand and others). 457 o Clarified the meaning of "overload point of the system". (Brought 458 up by Robert Sparks). 459 o Corrected sample source code to return the level value relative to 460 the overload point, as specified, rather than a level relative to 461 a reference sound pressure level; also to use round-to-nearest 462 rather than truncate to calculate the integer return value. 463 (Brought up by Michael Ramalho.) 464 o Updated reference to [I-D.ietf-avtcore-srtp-vbr-audio]. 466 9.2. Changes From Draft -04 468 o Fixed problems with missing "s=" attributes and odd RTP port 469 numbers in the SDP examples. 471 9.3. Changes From Draft -03 473 o Addressed editorial comments made on the mailing list. 475 9.4. Changes From Draft -02 477 o Removed the no-data use case that allowed sending levels in RTP 478 packets. Choosing the right RTP payload type for this use case 479 would have incurred complexity without bringing any real value. 480 o Merged the "Header Format" and the "Audio level encoding" sections 481 into a single "Audio Levels" section. 482 o Changed encoding related text so that it would cover both the one- 483 byte and the two-byte header formats. 484 o Clarified use of root mean square for dBov calculation 485 o Added a reference to [I-D.ietf-avtcore-srtp-vbr-audio] to better 486 explain some "Security Considerations" . 487 o Other minor editorial changes. 489 9.5. Changes From Draft -01 491 o Removed code related the AudioLevelRenderer from "APPENDIX A. 492 Reference Implementation" as it was considered an implementation 493 matter by the working group. 494 o Modified the AudioLevelCalculator in "APPENDIX A. Reference 495 Implementation" to take overload as a parameter. 496 o Clarified non-use of audio levels in video streams 497 o Closed the P.56 open issue. It was agreed on IETF 80 that P.56 is 498 mostly about speech levels and the levels transported by the 499 extension defined here should also be able to serve as an 500 indication for noise. 501 o The Open Issues section has been removed as all issues that were 502 in there are now resolved or clarified. 503 o Editorial changes for consistency with 504 [I-D.ietf-avtext-client-to-mixer-audio-level]. 506 9.6. Changes From Draft -00 508 o Added code for sound pressure calculation and measurement in 509 "APPENDIX A. Reference Implementation". 510 o Changed affiliation for Emil Ivov. 511 o Removed "Appendix: Design choices". 513 10. References 515 10.1. Normative References 517 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 518 Requirement Levels", BCP 14, RFC 2119, March 1997. 520 [RFC3550] Schulzrinne, H., Casner, S., Frederick, R., and V. 521 Jacobson, "RTP: A Transport Protocol for Real-Time 522 Applications", STD 64, RFC 3550, July 2003. 524 [RFC5285] Singer, D. and H. Desineni, "A General Mechanism for RTP 525 Header Extensions", RFC 5285, July 2008. 527 10.2. Informative References 529 [I-D.ietf-avtcore-srtp-encrypted-header-ext] 530 Lennox, J., "Encryption of Header Extensions in the Secure 531 Real-Time Transport Protocol (SRTP)", 532 draft-ietf-avtcore-srtp-encrypted-header-ext-01 (work in 533 progress), October 2011. 535 [I-D.ietf-avtcore-srtp-vbr-audio] 536 Perkins, C. and J. Valin, "Guidelines for the use of 537 Variable Bit Rate Audio with Secure RTP", 538 draft-ietf-avtcore-srtp-vbr-audio-03 (work in progress), 539 July 2011. 541 [I-D.ietf-avtext-client-to-mixer-audio-level] 542 Lennox, J., Ivov, E., and E. Marocco, "A Real-Time 543 Transport Protocol (RTP) Header Extension for Client-to- 544 Mixer Audio Level Indication", 545 draft-ietf-avtext-client-to-mixer-audio-level-05 (work in 546 progress), September 2011. 548 [ITU.G.711] 549 International Telecommunications Union, "Pulse Code 550 Modulation (PCM) of Voice Frequencies", ITU- 551 T Recommendation G.711, November 1988. 553 [ITU.P56.1993] 554 International Telecommunications Union, "Objective 555 Measurement of Active Speech Level", ITU-T Recommendation 556 P.56, March 1988. 558 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 559 A., Peterson, J., Sparks, R., Handley, M., and E. 560 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 561 June 2002. 563 [RFC3389] Zopf, R., "Real-time Transport Protocol (RTP) Payload for 564 Comfort Noise (CN)", RFC 3389, September 2002. 566 [RFC4301] Kent, S. and K. Seo, "Security Architecture for the 567 Internet Protocol", RFC 4301, December 2005. 569 [RFC4353] Rosenberg, J., "A Framework for Conferencing with the 570 Session Initiation Protocol (SIP)", RFC 4353, 571 February 2006. 573 [RFC4575] Rosenberg, J., Schulzrinne, H., and O. Levin, "A Session 574 Initiation Protocol (SIP) Event Package for Conference 575 State", RFC 4575, August 2006. 577 Appendix A. Reference Implementation 579 This appendix contains Java code for a reference implementation of 580 the level calculation and rendering methods.The code is not normative 581 and by no means the only possible implementation. Its purpose is to 582 help implementors add audio level support to mixers and clients. 584 The Java code contains an AudioLevelCalculator class that calculates 585 the sound pressure level of a signal with specific samples. It can 586 be used in mixers to generate values suitable for the level extension 587 headers. 589 The implementation is provided in Java but does not rely on any of 590 the language specific and can be easily ported to another. 592 A.1. AudioLevelCalculator.java 593 /* 594 Copyright (c) 2011 IETF Trust and the persons identified 595 as authors of the code. All rights reserved. 597 Redistribution and use in source and binary forms, with 598 or without modification, is permitted pursuant to, and subject 599 to the license terms contained in, the Simplified BSD License 600 set forth in Section 4.c of the IETF Trust's Legal Provisions 601 Relating to IETF Documents (http://trustee.ietf.org/license-info). 602 */ 604 /** 605 * Calculates the audio level of specific samples of a signal relative 606 * to overload. 607 */ 608 public class AudioLevelCalculator 609 { 611 /** 612 * Calculates the audio level of a signal with specific 613 * samples. 614 * 615 * @param samples the samples of the signal to calculate the audio 616 * level of. The samples are specified as an int 617 * array starting at offset, extending length 618 * number of elements and each int element in the specified 619 * range representing a sample of the signal to calculate the audio 620 * level of. Though a sample is provided in the form of an 621 * int value, the sample size in bits is determined by the 622 * caller via overload. 623 * 624 * @param offset the offset in samples at which the samples 625 * start 626 * 627 * @param length the length of the signal specified in 628 * samples starting at offset 629 * 630 * @param overload the overload (point) of signal. 631 * For example, overload can be {@link Byte#MAX_VALUE} 632 * for 8-bit signed samples or {@link Short#MAX_VALUE} for 633 * 16-bit signed samples. 634 * 635 * @return the audio level of the specified signal 636 */ 637 public static int calculateAudioLevel( 638 int[] samples, int offset, int length, 639 int overload) 640 { 641 /* 642 * Calcuate the root mean square of the signal. 643 */ 644 double rms = 0; 646 for (; offset < length; offset++) 647 { 648 double sample = samples[offset]; 650 sample /= overload; 651 rms += sample * sample; 652 } 653 rms = (length == 0) ? 0 : Math.sqrt(rms / length); 655 /* 656 * The audio level is a logarithmic measure of the 657 * rms level of an audio sample relative to a reference 658 * value and is measured in decibels. 659 */ 660 double db; 662 /* 663 * The minimum audio level permitted. 664 */ 665 final double MIN_AUDIO_LEVEL = -127; 666 /* 667 * The maximum audio level permitted. 668 */ 669 final double MAX_AUDIO_LEVEL = 0; 671 if (rms > 0) 672 { 673 /* 674 * The "zero" reference level is the overload level, which 675 * corresponds to 1.0 in this calculation, because the 676 * samples are normalized in calculating the RMS. 677 */ 678 db = 20 * Math.log10(rms); 680 /* 681 * Ensure that the calculated level is within the minimum 682 * and maximum range permitted. 683 */ 684 if (db < MIN_AUDIO_LEVEL) 685 db = MIN_AUDIO_LEVEL; 686 else if (db > MAX_AUDIO_LEVEL) 687 db = MAX_AUDIO_LEVEL; 688 } 689 else 690 { 691 db = MIN_AUDIO_LEVEL; 692 } 694 return (int)Math.round(db); 695 } 696 } 698 AudioLevelCalculator.java 700 Authors' Addresses 702 Emil Ivov (editor) 703 Jitsi 704 Strasbourg 67000 705 France 707 Email: emcho@jitsi.org 709 Enrico Marocco (editor) 710 Telecom Italia 711 Via G. Reiss Romoli, 274 712 Turin 10148 713 Italy 715 Email: enrico.marocco@telecomitalia.it 717 Jonathan Lennox 718 Vidyo, Inc. 719 433 Hackensack Avenue 720 Seventh Floor 721 Hackensack, NJ 07601 722 US 724 Email: jonathan@vidyo.com