correct volume control to match airplay spec, add a -db l:h option

README.html

@@ -9,13 +9,13 @@ href="https://github.com/FDH2/UxPlay">https://github.com/FDH2/UxPlay</a>
 (where ALL user issues should be posted, and latest versions can be
 found).</h3>
 <ul>
-<li><em><strong>NEW in v1.68</strong>: improved support for one-time
-Apple-style “pin” codes introduced in 1.67: a register of pin-registered
-clients is now optionally maintained to check returning clients; a
-simpler method for generating a persistent public key (based on the MAC
-address, which now can be set in the UxPlay startup file) is now the
-default. (The pem-file method introduced in 1.67 is still available with
-the ’-key” option.)</em></li>
+<li><em><strong>NEW in v1.68</strong>: Volume-control improvements, plus
+improved support for Apple-style one-time “pin” codes introduced in
+1.67: a register of pin-registered clients can now optionally be
+maintained to check returning clients; a simpler method for generating a
+persistent public key (based on the MAC address, which can be set in the
+UxPlay startup file) is now the default. (The OpenSSL “pem-file” method
+introduced in 1.67 is still available with the ’-key” option.)</em></li>
 </ul>
 <h2 id="highlights">Highlights:</h2>
 <ul>
@@ -517,6 +517,11 @@ on the client to match audio on the server, so leads to a slight delay
 before a pause or track-change initiated on the client takes effect on
 the audio played by the server.</li>
 </ul>
+<p>AirPlay volume-control attenuates volume (gain) by up to -30dB: the
+range -30dB:0dB can be rescaled from <em>Low</em>:0 (<em>Low</em> &lt;
+0), or <em>Low</em>:<em>High</em>, using the option
+“<code>-db _Low_</code>” or “<code>-db _Low_:_High_</code>” (Rescaling
+is linear in decibels).</p>
 <p>The -vsync and -async options also allow an optional positive (or
 negative) audio-delay adjustment in <em>milliseconds</em> for
 fine-tuning : <code>-vsync 20.5</code> delays audio relative to video by
@@ -941,6 +946,17 @@ have any effect</em>.</p>
 Audio-only mode, but this option may be useful as a command-line option
 to switch off a <code>-async</code> option set in a “uxplayrc”
 configuration file.</p>
+<p><strong>-db <em>low</em>[:<em>high</em>]</strong> Rescales the
+AirPlay volume-control attenuation (gain) from -30dB:0dB to
+<em>low</em>:0dB or <em>low</em>:<em>high</em>. The lower limit
+<em>low</em> must be negative (attenuation); the upper limit
+<em>high</em> can be either sign. (GStreamer restricts
+volume-augmentation by <em>high</em> so that it cannot exceed +20dB).
+The rescaling is “flat”, so that for -db -50:10, a change in Airplay
+attenuation by -7dB is translated to a -7 x (60/30) = -14dB attenuation,
+and the maximum volume (AirPlay 0dB) is a 10dB augmentation, and Airplay
+-30dB would become -50dB. Note that the minimum AirPlay value (-30dB
+exactly) is translated to “mute”.</p>
 <p><strong>-s wxh</strong> (e.g. -s 1920x1080 , which is the default )
 sets the display resolution (width and height, in pixels). (This may be
 a request made to the AirPlay client, and perhaps will not be the final
@@ -1494,11 +1510,13 @@ an AppleTV6,2 with sourceVersion 380.20.1 (an AppleTV 4K 1st gen,
 introduced 2017, running tvOS 12.2.1), so it does not seem to matter
 what version UxPlay claims to be.</p>
 <h1 id="changelog">Changelog</h1>
-<p>1.68 2023-12-25 Introduced a simpler (default) method for generating
+<p>1.68 2023-12-26 Introduced a simpler (default) method for generating
 a persistent public key from the server MAC address (which can now be
 set with the -m option). (The previous pem-file method is still
 available with -key option). New option -reg to maintain a register of
-pin-authenticated clients.</p>
+pin-authenticated clients. Corrected volume-control: now inteprets
+AirPlay volume range -30dB:0dB as (gain/amplitude) decibel attenuation,
+with new option -db low[:high] for “flat” rescaling of the dB range.</p>
 <p>1.67 2023-11-30 Add support for Apple-style one-time pin
 authentication of clients with option “-pin”: (uses SRP6a authentication
 protocol and public key persistence). Detection with error message of