biquad.c: Add macro for Butterworth Q-factors.

Author: bmc0

README.md

@@ -186,15 +186,15 @@ Example:
 	Second-order lowshelf filter.
 * `highshelf f0[k] width[q|s|d|o|h|k] gain`  
 	Second-order highshelf filter.
-* `lowpass_transform fz[k] qz fp[k] qp`  
+* `lowpass_transform fz[k] width_z[q] fp[k] width_p[q]`  
 	Second-order lowpass transformation filter. Cancels the poles defined by
-	`fz` and `qz` and replaces them with new poles defined by `fp` and `qp`.
-	Gain is unity at DC.
-* `highpass_transform fz[k] qz fp[k] qp`  
+	`fz` and `width_z` and replaces them with new poles defined by `fp` and
+	`width_p`. Gain is unity at DC.
+* `highpass_transform fz[k] width_z[q] fp[k] width_p[q]`  
 	Second-order highpass transformation filter. Also known as a Linkwitz
 	transform (see http://www.linkwitzlab.com/filters.htm#9). Same as
 	`lowpass_transform` except the gain is unity at Fs/2.
-* `linkwitz_transform fz[k] qz fp[k] qp`  
+* `linkwitz_transform fz[k] width_z[q] fp[k] width_p[q]`  
 	Alias for `highpass_transform`.
 * `deemph`  
 	Compact Disc de-emphasis filter.
@@ -425,7 +425,9 @@ Example    | Description
 **Note:** There is no difference between `1,3` and `3,1`. Order is not
 preserved.
 
-#### Filter width suffixes
+#### Filter width
+
+The following suffixes are supported:
 
 Suffix | Description
 ------ | ------------------------------
@@ -439,6 +441,18 @@ Suffix | Description
 **Note:** The `d` width suffix also changes the definition of `f0` from center
 frequency to corner frequency (like Room EQ Wizard and the Behringer DCX2496).
 
+Additionally, a macro is provided for constructing arbitrary-order Butterworth
+filters from cascaded second-order sections: `bw<order>[.n]`, where `<order>` is
+the filter order and `n` is an index corresponding to a particular pair of
+poles. The Q-factors are always in ascending order. For example,
+
+	lowpass 1k bw6.0 lowpass 1k bw6.1 lowpass 1k bw6.2
+
+creates a 6th-order Butterworth lowpass filter. Odd-order filters require an
+additional first-order section:
+
+	lowpass_1 1k lowpass 1k bw5.0 lowpass 1k bw5.1
+
 #### File paths
 
 On the command line, relative paths are relative to `$PWD`. Within an effects

biquad.c

@@ -25,35 +25,66 @@
 
 static double parse_width(const char *s, int *type, char **endptr)
 {
-	double w = strtod(s, endptr);
-	if (*endptr != NULL && *endptr != s) {
-		switch(**endptr) {
-		case 'q':
-			*type = BIQUAD_WIDTH_Q;
-			++(*endptr);
-			break;
-		case 's':
-			*type = BIQUAD_WIDTH_SLOPE;
-			++(*endptr);
-			break;
-		case 'd':
-			*type = BIQUAD_WIDTH_SLOPE_DB;
-			++(*endptr);
-			break;
-		case 'o':
-			*type = BIQUAD_WIDTH_BW_OCT;
-			++(*endptr);
-			break;
-		case 'k':
-			w *= 1000.0;
-		case 'h':
-			*type = BIQUAD_WIDTH_BW_HZ;
-			++(*endptr);
-			break;
+	*type = BIQUAD_WIDTH_Q;
+	double w = M_SQRT1_2;
+	if (s[0] == 'b' && s[1] == 'w' && s[2] != '\0') {
+		const char *s_ptr = s + 2;
+		const int order = strtol(s_ptr, endptr, 10);
+		if (*endptr == s_ptr || (**endptr != '\0' && **endptr != '.'))
+			goto fail;  /* failed to parse order */
+		if (order < 2) {
+			LOG_FMT(LL_ERROR, "%s(): filter order must be >= 2", __func__);
+			goto fail;
+		}
+		const int n_biquads = order / 2;
+		int p_idx = 0;
+		if (**endptr == '.') {
+			s_ptr = *endptr + 1;
+			p_idx = strtol(s_ptr, endptr, 10);
+			if (*endptr == s_ptr || **endptr != '\0')
+				goto fail;  /* failed to parse index */
+			if (p_idx < 0 || p_idx >= n_biquads) {
+				LOG_FMT(LL_ERROR, "%s(): filter index out of range", __func__);
+				goto fail;
+			}
+		}
+		p_idx = n_biquads - p_idx;  /* index from outermost conjugate pair */
+		w = 1.0/(2.0*sin(M_PI/order*(p_idx-0.5)));
+	}
+	else {
+		w = strtod(s, endptr);
+		if (*endptr != s) {
+			switch(**endptr) {
+			case 'q':
+				*type = BIQUAD_WIDTH_Q;
+				++(*endptr);
+				break;
+			case 's':
+				*type = BIQUAD_WIDTH_SLOPE;
+				++(*endptr);
+				break;
+			case 'd':
+				*type = BIQUAD_WIDTH_SLOPE_DB;
+				++(*endptr);
+				break;
+			case 'o':
+				*type = BIQUAD_WIDTH_BW_OCT;
+				++(*endptr);
+				break;
+			case 'k':
+				w *= 1000.0;
+			case 'h':
+				*type = BIQUAD_WIDTH_BW_HZ;
+				++(*endptr);
+				break;
+			}
+			if (**endptr != '\0') LOG_FMT(LL_ERROR, "%s(): trailing characters: %s", __func__, *endptr);
 		}
-		if (**endptr != '\0') LOG_FMT(LL_ERROR, "%s(): trailing characters: %s", __func__, *endptr);
 	}
 	return w;
+	fail:
+	*endptr = (char *) s;
+	return w;
 }
 
 void biquad_init(struct biquad_state *state, double b0, double b1, double b2, double a0, double a1, double a2)
@@ -427,11 +458,11 @@ struct effect * biquad_effect_init(const struct effect_info *ei, const struct st
 	case BIQUAD_HIGHPASS_TRANSFORM:
 		INIT_COMMON(4, ei->effect_number);
 		GET_FREQ_ARG(arg0, argv[1], "fz");
-		GET_ARG(arg1, argv[2], "qz");
-		CHECK_RANGE(arg1 > 0.0, "qz", return NULL);
+		GET_WIDTH_ARG(arg1, argv[2], "width_z");
+		CHECK_WIDTH_TYPE(width_type == BIQUAD_WIDTH_Q);
 		GET_FREQ_ARG(arg2, argv[3], "fp");
-		GET_ARG(arg3, argv[4], "qp");
-		CHECK_RANGE(arg3 > 0.0, "qp", return NULL);
+		GET_WIDTH_ARG(arg3, argv[4], "width_p");
+		CHECK_WIDTH_TYPE(width_type == BIQUAD_WIDTH_Q);
 		break;
 	case BIQUAD_DEEMPH:
 		INIT_COMMON(0, BIQUAD_HIGHSHELF);

dsp.1

@@ -170,17 +170,17 @@ Second-order lowshelf filter.
 \fBhighshelf\fR \fIf0\fR[\fBk\fR] \fIwidth\fR[\fBq\fR|\fBs\fR|\fBd\fR|\fBo\fR|\fBh\fR|\fBk\fR] \fIgain\fR
 Second-order highshelf filter.
 .TP
-\fBlowpass_transform\fR \fIfz\fR[\fBk\fR] \fIqz\fR \fIfp\fR[\fBk\fR] \fIqp\fR
+\fBlowpass_transform\fR \fIfz\fR[\fBk\fR] \fIwidth_z\fR[\fBq\fR] \fIfp\fR[\fBk\fR] \fIwidth_p\fR[\fBq\fR]
 Second-order lowpass transformation filter. Cancels the poles defined by
-\fIfz\fR and \fIqz\fR and replaces them with new poles defined by \fIfp\fR and \fIqp\fR.
-Gain is unity at DC.
+\fIfz\fR and \fIwidth_z\fR and replaces them with new poles defined by \fIfp\fR and
+\fIwidth_p\fR. Gain is unity at DC.
 .TP
-\fBhighpass_transform\fR \fIfz\fR[\fBk\fR] \fIqz\fR \fIfp\fR[\fBk\fR] \fIqp\fR
+\fBhighpass_transform\fR \fIfz\fR[\fBk\fR] \fIwidth_z\fR[\fBq\fR] \fIfp\fR[\fBk\fR] \fIwidth_p\fR[\fBq\fR]
 Second-order highpass transformation filter. Also known as a Linkwitz
 transform (see http://www.linkwitzlab.com/filters.htm#9). Same as
 \fBlowpass_transform\fR except the gain is unity at Fs/2.
 .TP
-\fBlinkwitz_transform\fR \fIfz\fR[\fBk\fR] \fIqz\fR \fIfp\fR[\fBk\fR] \fIqp\fR
+\fBlinkwitz_transform\fR \fIfz\fR[\fBk\fR] \fIwidth_z\fR[\fBq\fR] \fIfp\fR[\fBk\fR] \fIwidth_p\fR[\fBq\fR]
 Alias for \fBhighpass_transform\fR.
 .TP
 \fBdeemph\fR
@@ -467,7 +467,9 @@ _
 .PP
 Note: There is no difference between `1,3' and `3,1'. Order is not
 preserved.
-.SS Filter width suffixes
+.SS Filter width
+The following suffixes are supported:
+
 .TS
 tab (|);
 lB lB
@@ -484,6 +486,19 @@ k|Bandwidth in kHz.
 .PP
 Note: The `\fBd\fR' width suffix also changes the definition of \fIf0\fR from center
 frequency to corner frequency (like Room EQ Wizard and the Behringer DCX2496).
+.PP
+Additionally, a macro is provided for constructing arbitrary-order Butterworth
+filters from cascaded second-order sections: `bw<\fIorder\fR>[.\fIn\fR]', where `<\fIorder\fR>' is
+the filter order and `\fIn\fR' is an index corresponding to a particular pair of
+poles. The Q-factors are always in ascending order. For example,
+.EX
+	lowpass 1k bw6.0 lowpass 1k bw6.1 lowpass 1k bw6.2
+.EE
+creates a 6th-order Butterworth lowpass filter. Odd-order filters require an
+additional first-order section:
+.EX
+	lowpass_1 1k lowpass 1k bw5.0 lowpass 1k bw5.1
+.EE
 .SS File paths
 On the command line, relative paths are relative to `$PWD'. Within an effects
 file, relative paths are relative to the directory containing said effects

effect.c

@@ -62,9 +62,9 @@ static const struct effect_info effects[] = {
 	{ "eq",                 "eq f0[k] width[q|o|h|k] gain",            biquad_effect_init,    BIQUAD_PEAK },
 	{ "lowshelf",           "lowshelf f0[k] width[q|s|d|o|h|k] gain",  biquad_effect_init,    BIQUAD_LOWSHELF },
 	{ "highshelf",          "highshelf f0[k] width[q|s|d|o|h|k] gain", biquad_effect_init,    BIQUAD_HIGHSHELF },
-	{ "lowpass_transform",  "lowpass_transform fz[k] qz fp[k] qp",     biquad_effect_init,    BIQUAD_LOWPASS_TRANSFORM },
-	{ "highpass_transform", "highpass_transform fz[k] qz fp[k] qp",    biquad_effect_init,    BIQUAD_HIGHPASS_TRANSFORM },
-	{ "linkwitz_transform", "linkwitz_transform fz[k] qz fp[k] qp",    biquad_effect_init,    BIQUAD_HIGHPASS_TRANSFORM },
+	{ "lowpass_transform",  "lowpass_transform fz[k] width_z[q] fp[k] width_p[q]",  biquad_effect_init, BIQUAD_LOWPASS_TRANSFORM },
+	{ "highpass_transform", "highpass_transform fz[k] width_z[q] fp[k] width_p[q]", biquad_effect_init, BIQUAD_HIGHPASS_TRANSFORM },
+	{ "linkwitz_transform", "linkwitz_transform fz[k] width_z[q] fp[k] width_p[q]", biquad_effect_init, BIQUAD_HIGHPASS_TRANSFORM },
 	{ "deemph",             "deemph",                                  biquad_effect_init,    BIQUAD_DEEMPH },
 	{ "biquad",             "biquad b0 b1 b2 a0 a1 a2",                biquad_effect_init,    BIQUAD_BIQUAD },
 	{ "gain",               "gain gain_dB",                            gain_effect_init,      GAIN_EFFECT_NUMBER_GAIN },