Docs: Clarify decibel usage

acidanthera · Jan 10, 2022 · b530a29 · b530a29
1 parent 6ec820f
commit b530a29
Show file tree

Hide file tree

Showing 6 changed files with 41 additions and 25 deletions.
diff --git a/Docs/Configuration.md5 b/Docs/Configuration.md5
@@ -1 +1 @@
-7f0394c82af0c441234551173401619a
+7e44657f61acfb35ec0173d872b832a9
diff --git a/Docs/Configuration.pdf b/Docs/Configuration.pdf
diff --git a/Docs/Configuration.tex b/Docs/Configuration.tex
@@ -4876,7 +4876,7 @@ \subsection{Other Variables}\label{nvramvarsother}
 \item
   \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:SystemAudioVolume}
   \break
-  System audio volume level for firmware audio support. 8-bit integer.
+  System audio volume level for firmware audio support. 8-bit unsigned integer.
   The bit of \texttt{0x80} means muted. The remaining bits are used
   to encode the raw amplifier gain setting to be applied to the audio
   amplifier in use. Exactly what this value means depends on the codec
@@ -4886,8 +4886,8 @@ \subsection{Other Variables}\label{nvramvarsother}
   \item
   \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:SystemAudioVolumeDB}
   \break
-  Current system audio volume level in decibels (dB). The value
-  is a signed byte representing the audio offset (gain if positive,
+  Current system audio volume level in decibels (dB).  8-bit signed integer.
+  The value represents the audio offset (gain if positive,
   attenuation if negative) in dB relative to the amplifier reference value
   of 0 dB. Exactly which volume level is represented by 0 dB depends on the
   codec (and potentially on the specific amplifier within the codec)
@@ -7112,13 +7112,16 @@ \subsection{Audio Properties}\label{uefiaudioprops}
   NVRAM variable is higher than this. This is to avoid over-loud UEFI audio when the system volume is set very high,
   or the \texttt{SystemAudioVolumeDB} NVRAM value has been misconfigured.
 
-  \emph{Note 1}: A typical range of system gain values is from roughly -60 dB to exactly 0 dB, where 0 dB represents the
-  amplifier maximum volume. However these values depend on the hardware and may be different,
-  including gain levels above zero (therefore 0 dB is not the amplifier maximum volume) on non-standard hardware.
-  On any hardware, following the Intel HDA specification, the range will always include 0 dB somewere
-  (at either end or somewhere in between).
+  \emph{Note 1}: Decibels (dB) specify gain (postive values; increase in volume) or attenuation (negative values; decrease
+  in volume) compared to some reference level. When you hear the sound level of a jet plane expressed as 120 decibels, say,
+  the reference level is the sound level just audible to an average human. However generally
+  in acoustic science and computer audio any reference level can be specified. Intel HDA and macOS natively use
+  decibels to specify volume level. On most Intel HDA hardware the reference level of 0 dB is the
+  \emph{loudest} volume of the hardware, and all lower volumes are therefore negative numbers. The quietest volume
+  on typical sound hardware is around -55 dB to -60 dB.
 
-  \emph{Note 2}: Values outside $-128$ dB to $+127$ dB (which are well beyond physically plausible decibel values) are not allowed.
+  \emph{Note 2}: Matching how macOS handles decibel values, this value is converted to a signed byte; therefore values
+  outside $-128$ dB to $+127$ dB (which are well beyond physically plausible volume levels) are not allowed.
 
   \emph{Note 3}: Digital audio output -- which does not have a volume slider in-OS -- ignores this and all other gain settings,
   only mute settings are relevant.
@@ -7132,9 +7135,11 @@ \subsection{Audio Properties}\label{uefiaudioprops}
   The screen reader will use this amplifier gain if the system amplifier gain read from the \texttt{SystemAudioVolumeDB}
   NVRAM variable is lower than this.
 
-  \emph{Note}: In addition to this setting, because audio assist must be audible to serve its function, audio assist
+  \emph{Note 1}: In addition to this setting, because audio assist must be audible to serve its function, audio assist
   is not muted even if the OS sound is muted or the \texttt{StartupMute} NVRAM variable is set.
 
+  \emph{Note 2}: See \texttt{MaximumGain} for an explanation of decibel volume levels.
+
   \item
   \texttt{MinimumAudibleGain}\\
   \textbf{Type}: \texttt{plist\ integer}\\
@@ -7144,12 +7149,14 @@ \subsection{Audio Properties}\label{uefiaudioprops}
   The boot chime will not play if the system amplifier gain level in the
   \texttt{SystemAudioVolumeDB} NVRAM variable is lower than this.
 
-  \emph{Note}: This setting is designed to save unecessary pauses due to audio setup at inaudible volume
+  \emph{Note 1}: This setting is designed to save unecessary pauses due to audio setup at inaudible volume
   levels, when no sound will be heard anyway. Whether there are inaudible volume levels depends on the
   hardware. On some hardware (including Apple) the audio values are well enough matched to the hardware
   that the lowest volume levels available are very quiet but audible, whereas on some other hardware combinations,
   the lowest part of the volume range may not be audible at all.
 
+  \emph{Note 2}: See \texttt{MaximumGain} for an explanation of decibel volume levels.
+
 \item
   \texttt{PlayChime}\\
   \textbf{Type}: \texttt{plist\ string}\\

diff --git a/Docs/Differences/Differences.pdf b/Docs/Differences/Differences.pdf
diff --git a/Docs/Differences/Differences.tex b/Docs/Differences/Differences.tex
@@ -1,7 +1,7 @@
 \documentclass[]{article}
 %DIF LATEXDIFF DIFFERENCE FILE
-%DIF DEL PreviousConfiguration.tex   Wed Dec  8 21:04:04 2021
-%DIF ADD ../Configuration.tex        Tue Jan 11 01:59:39 2022
+%DIF DEL PreviousConfiguration.tex   Sun Jan  9 22:59:35 2022
+%DIF ADD ../Configuration.tex        Mon Jan 10 23:09:59 2022
 
 \usepackage{lmodern}
 \usepackage{amssymb,amsmath}
@@ -4944,7 +4944,7 @@ \subsection{Other Variables}\label{nvramvarsother}
 \item
   \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:SystemAudioVolume}
   \break
-  System audio volume level for firmware audio support. 8-bit integer.
+  System audio volume level for firmware audio support. 8-bit \DIFaddbegin \DIFadd{unsigned }\DIFaddend integer.
   The bit of \texttt{0x80} means muted. \DIFdelbegin \DIFdel{Lower }\DIFdelend \DIFaddbegin \DIFadd{The remaining }\DIFaddend bits are used
   to encode \DIFdelbegin \DIFdel{volume range specific to installed audio
   codec. The }\DIFdelend \DIFaddbegin \DIFadd{the raw amplifier gain setting to be applied to the audio
@@ -4956,8 +4956,8 @@ \subsection{Other Variables}\label{nvramvarsother}
   \item
   \DIFaddbegin \texttt{\DIFadd{7C436110-AB2A-4BBB-A880-FE41995C9F82:SystemAudioVolumeDB}}
   \break
-  \DIFadd{Current system audio volume level in decibels (dB). The value
-  is a signed byte representing the audio offset (gain if positive,
+  \DIFadd{Current system audio volume level in decibels (dB).  8-bit signed integer.
+  The value represents the audio offset (gain if positive,
   attenuation if negative) in dB relative to the amplifier reference value
   of 0 dB. Exactly which volume level is represented by 0 dB depends on the
   codec (and potentially on the specific amplifier within the codec)
@@ -7219,14 +7219,17 @@ \subsection{Audio Properties}\label{uefiaudioprops}
   \DIFaddbegin \DIFadd{NVRAM variable is higher than this. This is to avoid over-loud UEFI audio when the system volume is set very high,
   or the }\texttt{\DIFadd{SystemAudioVolumeDB}} \DIFadd{NVRAM value has been misconfigured}\DIFaddend .
 
-  \DIFaddbegin \emph{\DIFadd{Note 1}}\DIFadd{: A typical range of system gain values is from roughly -60 dB to exactly 0 dB, where 0 dB represents the
-  amplifier maximum volume. However these values depend on the hardware and may be different,
-  including gain levels above zero (therefore 0 dB is not the amplifier maximum volume) on non-standard hardware.
-  On any hardware, following the Intel HDA specification, the range will always include 0 dB somewere
-  (at either end or somewhere in between).
+  \DIFaddbegin \emph{\DIFadd{Note 1}}\DIFadd{: Decibels (dB) specify gain (postive values; increase in volume) or attenuation (negative values; decrease
+  in volume) compared to some reference level. When you hear the sound level of a jet plane expressed as 120 decibels, say,
+  the reference level is the sound level just audible to an average human. However generally
+  in acoustic science and computer audio any reference level can be specified. Intel HDA and macOS natively use
+  decibels to specify volume level. On most Intel HDA hardware the reference level of 0 dB is the
+  }\emph{\DIFadd{loudest}} \DIFadd{volume of the hardware, and all lower volumes are therefore negative numbers. The quietest volume
+  on typical sound hardware is around -55 dB to -60 dB.
   }
 
-  \emph{\DIFadd{Note 2}}\DIFadd{: Values outside $-128$ dB to $+127$ dB (which are well beyond physically plausible decibel values) are not allowed.
+  \emph{\DIFadd{Note 2}}\DIFadd{: Matching how macOS handles decibel values, this value is converted to a signed byte; therefore values
+  outside $-128$ dB to $+127$ dB (which are well beyond physically plausible volume levels) are not allowed.
 }
 
   \emph{\DIFadd{Note 3}}\DIFadd{: Digital audio output -- which does not have a volume slider in-OS -- ignores this and all other gain settings,
@@ -7245,10 +7248,13 @@ \subsection{Audio Properties}\label{uefiaudioprops}
 \DIFdel{and the }\DIFdelend \DIFaddbegin \DIFadd{this.
 }
 
-  \emph{\DIFadd{Note}}\DIFadd{: In addition to this setting, because audio assist must be audible to serve its function, audio assist
+  \emph{\DIFadd{Note 1}}\DIFadd{: In addition to this setting, because audio assist must be audible to serve its function, audio assist
   is not muted even if the OS sound is muted or the }\texttt{\DIFadd{StartupMute}} \DIFadd{NVRAM variable is set.
 }
 
+  \emph{\DIFadd{Note 2}}\DIFadd{: See }\texttt{\DIFadd{MaximumGain}} \DIFadd{for an explanation of decibel volume levels.
+}
+
   \item
   \texttt{\DIFadd{MinimumAudibleGain}}\\
   \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ integer}}\\
@@ -7261,13 +7267,16 @@ \subsection{Audio Properties}\label{uefiaudioprops}
   }\texttt{\DIFadd{SystemAudioVolumeDB}} \DIFadd{NVRAM variable }\DIFaddend is lower than \DIFdelbegin \texttt{\DIFdel{MinimumVolume}}%DIFAUXCMD
 \DIFdelend \DIFaddbegin \DIFadd{this}\DIFaddend .
 
-  \DIFaddbegin \emph{\DIFadd{Note}}\DIFadd{: This setting is designed to save unecessary pauses due to audio setup at inaudible volume
+  \DIFaddbegin \emph{\DIFadd{Note 1}}\DIFadd{: This setting is designed to save unecessary pauses due to audio setup at inaudible volume
   levels, when no sound will be heard anyway. Whether there are inaudible volume levels depends on the
   hardware. On some hardware (including Apple) the audio values are well enough matched to the hardware
   that the lowest volume levels available are very quiet but audible, whereas on some other hardware combinations,
   the lowest part of the volume range may not be audible at all.
 }
 
+  \emph{\DIFadd{Note 2}}\DIFadd{: See }\texttt{\DIFadd{MaximumGain}} \DIFadd{for an explanation of decibel volume levels.
+}
+
 \DIFaddend \item
   \texttt{PlayChime}\\
   \textbf{Type}: \texttt{plist\ string}\\

diff --git a/Docs/Errata/Errata.pdf b/Docs/Errata/Errata.pdf