From 1acc8bcc050a7b8f427e04dcc457efa0fdbb9507 Mon Sep 17 00:00:00 2001
From: Andre Noll <maan@tuebingen.mpg.de>
Date: Sun, 15 Jul 2018 22:52:46 +0200
Subject: [PATCH] compress: Document and sanity-check command line options.

The arguments of most of the options to the compress filter are used
as shifts and therefore have rather tight requirements on the range of
admissible/useful values. Let's document these values and make sure
to print a meaningful error message if an argument is out of range.
---
 compress_filter.c          | 38 ++++++++++++++++++++++++++++++++++++++
 m4/lls/filter_cmd.suite.m4 | 28 ++++++++++++++++++++++++----
 2 files changed, 62 insertions(+), 4 deletions(-)

diff --git a/compress_filter.c b/compress_filter.c
index 69a982ef..d0132596 100644
--- a/compress_filter.c
+++ b/compress_filter.c
@@ -124,7 +124,45 @@ static void compress_open(struct filter_node *fn)
 	pcd->max_gain = 1U << (inertia + aggressiveness);
 }
 
+static void *compress_setup(const struct lls_parse_result *lpr)
+{
+	uint32_t val;
+
+	val = U32_OPTVAL(BLOCKSIZE, lpr);
+	if (val == 0 || val > 31) {
+		PARA_EMERG_LOG("blocksize (%u) out of range\n", val);
+		exit(EXIT_FAILURE);
+	}
+	val = U32_OPTVAL(AGGRESSIVENESS, lpr);
+	if (val == 0 || val > 15) {
+		PARA_EMERG_LOG("aggressiveness (%u) out of range\n", val);
+		exit(EXIT_FAILURE);
+	}
+	val = U32_OPTVAL(INERTIA, lpr);
+	if (val == 0 || val > 15) {
+		PARA_EMERG_LOG("inertia (%u) out of range\n", val);
+		exit(EXIT_FAILURE);
+	}
+	val = U32_OPTVAL(AGGRESSIVENESS, lpr) + U32_OPTVAL(INERTIA, lpr);
+	if (val > 16) {
+		PARA_EMERG_LOG("inertia + aggressiveness (%u) > 16\n", val);
+		exit(EXIT_FAILURE);
+	}
+	val = U32_OPTVAL(TARGET_LEVEL, lpr);
+	if (val > 32767) {
+		PARA_EMERG_LOG("target-level (%u) out of range\n", val);
+		exit(EXIT_FAILURE);
+	}
+	val = U32_OPTVAL(DAMP, lpr);
+	if (val > 16) {
+		PARA_EMERG_LOG("damp (%u) out of range\n", val);
+		exit(EXIT_FAILURE);
+	}
+	return NULL; /* no need for a config structure */
+}
+
 const struct filter lsg_filter_cmd_com_compress_user_data = {
+	.setup = compress_setup,
 	.open = compress_open,
 	.close = compress_close,
 	.pre_select = generic_filter_pre_select,
diff --git a/m4/lls/filter_cmd.suite.m4 b/m4/lls/filter_cmd.suite.m4
index ddc5f1cb..1399de62 100644
--- a/m4/lls/filter_cmd.suite.m4
+++ b/m4/lls/filter_cmd.suite.m4
@@ -25,7 +25,7 @@ caption = filters
 	purpose = dynamically adjust the volume of an audio stream
 	[option blocksize]
 		short_opt = b
-		summary = use blocks of size 2**bits
+		summary = adjust volume after each block of size 2**bits (1-31)
 		typestr = bits
 		arg_info = required_arg
 		arg_type = uint32
@@ -35,18 +35,26 @@ caption = filters
 		[/help]
 	[option aggressiveness]
 		short_opt = a
-		summary = controls the maximum amount to amplify by
+		summary = controls the maximum amount to amplify by (1-15)
 		typestr = bits
 		arg_info = required_arg
 		arg_type = uint32
 		default_val = 4
+		[help]
+			This caps the maximal gain factor to 2**bits. The sum of the arguments
+			to --aggressiveness and --inertia (see below) must not exceed 16.
+		[/help]
 	[option inertia]
 		short_opt = i
-		summary = how much inertia ramping has
+		summary = how much inertia ramping has (1-15)
 		typestr = bits
 		arg_info = required_arg
 		arg_type = uint32
 		default_val = 6
+		[help]
+			Larger values cause smaller volume adjustments. See --aggressiveness
+			above.
+		[/help]
 	[option target-level]
 		short_opt = t
 		summary = target signal level (0-32767)
@@ -54,13 +62,25 @@ caption = filters
 		arg_info = required_arg
 		arg_type = uint32
 		default_val = 20000
+		[help]
+			If the peak of the previous block is less than the target level,
+			volume is increased slightly for the next block. Otherwise it is
+			decreased. The default value is chosen to minimize clipping. There
+			is usually no reason to change it.
+		[/help]
 	[option damp]
 		short_opt = d
-		summary = if non-zero, scale down after normalizing
+		summary = if non-zero, scale down after normalizing (0-16)
 		typestr = bits
 		arg_info = required_arg
 		arg_type = uint32
 		default_val = 0
+		[help]
+			This scales down the volume of the audio stream by factor 2**bits.
+			This is mostly useful if another audio application (e.g., a video
+			game) is running in parallel and the relative volume of the audio
+			stream is too high.
+		[/help]
 [subcommand fecdec]
 	purpose = decode a (lossy) input stream using forward error correction
 [subcommand flacdec]
-- 
2.39.5