doc: clarify the dither.noise

Fixes #4057

doc/dox/config/pipewire-client.conf.5.md

@@ -460,10 +460,21 @@ This is only active when the `psd` up-mix method is used.
 \endparblock
 
 @PAR@ client.conf  dither.noise = 0
-This option will add N bits of random data to the signal. This can be used
+\parblock
-to keep some amplifiers alive during silent periods. This is usually used together with
+This option will add N bits of random data to the signal. When no dither.method is
+specified, the random data will flip between [-(1<<(N-1)), 0] every 1024 samples. With
+a dither.method, the dither noise is amplified with 1<<(N-1) bits.
+
+This can be used to keep some amplifiers alive during silent periods. One or two bits of noise is
+usually enough, otherwise the noise will become audible. This is usually used together with
 `session.suspend-timeout-seconds` to disable suspend in the session manager.
 
+Note that PipeWire uses floating point operations with 24 bits precission for all of the audio
+processing. Conversion to 24 bits integer sample formats is lossless and conversion to 32 bits
+integer sample formats are simply padded with 0 bits at the end. This means that the dither noise
+is always only in the 24 most significant bits.
+\endparblock
+
 @PAR@ client.conf  dither.method = none
 \parblock
 Optional [dithering](https://en.wikipedia.org/wiki/Dither) can be done on the quantized
@@ -472,8 +483,11 @@ output signal.
 There are 6 modes available:
 
 1. none           No dithering is done.
-2. rectangular    Dithering with a rectangular noise distribution.
+2. rectangular    Dithering with a rectangular noise distribution. This adds random
-3. triangular     Dithering with a triangular noise distribution.
+                  bits in the [-0.5, 0.5] range to the signal with even distribution.
+3. triangular     Dithering with a triangular noise distribution. This add random
+                  bits in the [-1.0, 1.0] range to the signal with triangular distribution
+                  around 0.0.
 4. triangular-hf  Dithering with a sloped triangular noise distribution.
 5. wannamaker3    Additional noise shaping is performed on the sloped triangular
                   dithering to move the noise to the more inaudible range. This is using

spa/plugins/audioconvert/fmt-ops.c

@@ -468,6 +468,8 @@ int convert_init(struct convert *conv)
 	const struct noise_info *ninfo;
 	uint32_t i, conv_flags, data_size[3];
 
+	/* we generate int32 bits of random values. With this scale
+	 * factor, we bring this in the [-1.0, 1.0] range */
 	conv->scale = 1.0f / (float)(INT32_MAX);
 
 	/* disable dither if not needed */
@@ -483,6 +485,9 @@ int convert_init(struct convert *conv)
 		switch (conv->noise_method) {
 		case NOISE_METHOD_NONE:
 			conv->noise_method = NOISE_METHOD_PATTERN;
+			/* the pattern method does not use a random number
+			 * but flips the noise between [-(1<<(N-1)), 0] every
+			 * 1024 samples. */
 			conv->scale = -1.0f * (1 << (conv->noise_bits-1));
 			break;
 		case NOISE_METHOD_RECTANGULAR:
@@ -490,10 +495,13 @@ int convert_init(struct convert *conv)
 			SPA_FALLTHROUGH;
 		case NOISE_METHOD_TRIANGULAR:
 		case NOISE_METHOD_TRIANGULAR_HF:
+			/* Amplify the random noise, with additional
+			 * N-1 bits of noise. */
 			conv->scale *= (1 << (conv->noise_bits-1));
 			break;
 		}
 	}
+	/* RECTANGULAR dither goes from [-0.5, 0.5] */
 	if (conv->noise_method < NOISE_METHOD_TRIANGULAR)
 		conv->scale *= 0.5f;