Tunes the audio levels based on sound pressure levels and their ranges a bit. Fixes an inaccuracy in the audio levels being sent to conference members.

2 files changed, 41 insertions, 12 deletions

diff --git a/src/net/java/sip/communicator/service/neomedia/event/SimpleAudioLevelListener.java b/src/net/java/sip/communicator/service/neomedia/event/SimpleAudioLevelListener.java
index 2a4f91c..3d14def 100644
--- a/src/net/java/sip/communicator/service/neomedia/event/SimpleAudioLevelListener.java
+++ b/src/net/java/sip/communicator/service/neomedia/event/SimpleAudioLevelListener.java
@@ -16,15 +16,29 @@ public interface SimpleAudioLevelListener
 {
     /**
      * The maximum level that can be reported for a participant in a conference.
-     * Level values should be distributed among MAX_LEVEL and MIN_LEVEL in a
-     * way that would appear uniform to users.
+     * Level values should be distributed between <tt>MAX_LEVEL</tt> and
+     * {@link #MIN_LEVEL} in a way that would appear uniform to users.
+     * <p>
+     * <b>Note</b>: The value of <tt>127</tt> is specifically chosen as the
+     * value of <tt>MAX_LEVEL</tt> because (1) we transport the levels within
+     * RTP and it gives us a signed <tt>byte</tt> for it, and (2) the range of
+     * <code>[0, 127]</tt> is pretty good to directly express the sound pressure
+     * level decibels as heard by humans in Earth's atmosphere.
+     * </p>
      */
-    public static final int MAX_LEVEL = 255;
+    public static final int MAX_LEVEL = 127;
 
     /**
      * The maximum (zero) level that can be reported for a participant in a
-     * conference. Level values should be distributed among MAX_LEVEL and
-     * MIN_LEVEL in a way that would appear uniform to users.
+     * conference. Level values should be distributed among {@link #MAX_LEVEL}
+     * and <tt>MIN_LEVEL</tt> in a way that would appear uniform to users.
+     * <p>
+     * <b>Note</b>: The value of <tt>0</tt> is specifically chosen as the value
+     * of <tt>MIN_LEVEL</tt> because (1) we transport the levels within RTP and
+     * it gives us a signed <tt>byte</tt> for it, and (2) the range of
+     * <code>[0, 127]</tt> is pretty good to directly express the sound pressure
+     * level decibels as heard by humans in Earth's atmosphere.
+     * </p>
      */
     public static final int MIN_LEVEL = 0;
 
diff --git a/src/net/java/sip/communicator/service/protocol/event/SoundLevelChangeEvent.java b/src/net/java/sip/communicator/service/protocol/event/SoundLevelChangeEvent.java
index c27956f..8e9aa65 100644
--- a/src/net/java/sip/communicator/service/protocol/event/SoundLevelChangeEvent.java
+++ b/src/net/java/sip/communicator/service/protocol/event/SoundLevelChangeEvent.java
@@ -33,16 +33,30 @@ public class SoundLevelChangeEvent
     private static final long serialVersionUID = 0L;
 
     /**
-     * The maximum level that can be reported for a participant.
-     * Level values should be distributed among MAX_LEVEL and MIN_LEVEL in a
-     * way that would appear uniform to users.
+     * The maximum level that can be reported for a participant. Level values
+     * should be distributed among <tt>MAX_LEVEL</tt> and {@link #MIN_LEVEL} in
+     * a way that would appear uniform to users.
+     * <p>
+     * <b>Warning</b>: The value should be equal to
+     * <tt>net.java.sip.communicator.service.neomedia.event.SimpleAudioLevelListener#MAX_VALUE</tt>
+     * because we do not currently perform a conversion from the
+     * <tt>SimpleAudioLevelListener</tt> range to the
+     * <tt>SoundLevelChangeEvent</tt> range when we fire the event.
+     * </p>
      */
-    public static final int MAX_LEVEL = 255;
+    public static final int MAX_LEVEL = 127;
 
     /**
-     * The maximum (zero) level that can be reported for a participant.
-     * Level values should be distributed among MAX_LEVEL and
-     * MIN_LEVEL in a way that would appear uniform to users.
+     * The maximum (zero) level that can be reported for a participant. Level
+     * values should be distributed among {@link #MAX_LEVEL} and
+     * <tt>MIN_LEVEL</tt> in a way that would appear uniform to users.
+     * <p>
+     * <b>Warning</b>: The value should be equal to
+     * <tt>net.java.sip.communicator.service.neomedia.event.SimpleAudioLevelListener#MIN_VALUE</tt>
+     * because we do not currently perform a conversion from the
+     * <tt>SimpleAudioLevelListener</tt> range to the
+     * <tt>SoundLevelChangeEvent</tt> range when we fire the event.
+     * </p>
      */
     public static final int MIN_LEVEL = 0;
 
@@ -68,6 +82,7 @@ public class SoundLevelChangeEvent
 
     /**
      * Returns the current sound level of the audio stream.
+     *
      * @return the current sound level of the audio stream
      */
     public int getLevel()