shithub: sox

Download patch

ref: 70663ccd02f7a5179faaaf56fcbe8ccca5549927
parent: df7401008cc1746a9329af3dd0ca4bb89624698c
author: Ulrich Klauer <ulrich@chirlu.de>
date: Wed Jan 4 14:34:10 EST 2012

Deprecate the mixer effect

--- a/ChangeLog
+++ b/ChangeLog
@@ -17,7 +17,7 @@
   14.3.0   E norm -b, norm -i      gain -B, gain -en
   14.3.0   PLAY_RATE_ARG           SOX_OPTS
   14.2.0   E key alias             pitch
-  14.2.0   E pan                   ~= mixer/remix
+  14.2.0   E pan                   ~= remix
   14.1.0   E resample alias        rate
   14.1.0   E polyphase alias       rate
   14.1.0   E rabbit alias          rate
@@ -24,6 +24,13 @@
   14.3.1   F sndfile: sndfile 1.0.11 sndfile > 1.0.11
   14.3.0   F flac: libFLAC < 1.1.3 libFLAC >= 1.1.3
   14.3.1   F mp3: lame 3.97        lame > 3.97
+
+Newly deprecated features (to be removed in future):
+
+  Deprec-  Feature    [O(ption)]                           Removal
+  ated in  [F(ormat)] [E(ffect)]   Replacement             due after
+  -------  ----------------------  ----------------------  -------
+  14.4.0   E mixer                 remix                   14.4.0 + 1 year
 
 Previously deprecated features (to be removed in future):
 
--- a/FEATURES.in
+++ b/FEATURES.in
@@ -99,7 +99,6 @@
 * Mixing effects
 ** channels: Auto mix or duplicate to change number of channels
 ** divide+: Divide sample values by those in the 1st channel (W.I.P.)
-** mixer: Mix up to 4 channels in certain ways
 ** remix: Produce arbitrarily mixed output channels
 ** swap: Swap stereo channels
 
--- a/sox.1
+++ b/sox.1
@@ -2420,62 +2420,6 @@
 .B compand
 for a single-band companding effect.
 .TP
-\fBmixer\fR [ \fB\-l\fR\^|\^\fB\-r\fR\^|\^\fB\-f\fR\^|\^\fB\-b\fR\^|\^\fB\-1\fR\^|\^\fB\-2\fR\^|\^\fB\-3\fR\^|\^\fB\-4\fR\^|\^\fIn\fR{\fB,\fIn\fR} ]
-Reduce the number of audio channels by mixing or selecting channels,
-or increase the number of channels by duplicating channels.
-Note: this effect operates on the audio
-.I channels
-within the SoX effects processing chain; it should not be confused with the
-.B \-m
-global option (where multiple
-.I files
-are mix-combined before entering the effects chain).
-.SP
-When reducing the number of channels it is possible to
-use the \fB\-l\fR, \fB\-r\fR, \fB\-f\fR, \fB\-b\fR,
-\fB\-1\fR, \fB\-2\fR, \fB\-3\fR, \fB\-4\fR, options to select only
-the left, right, front, back channel(s) or specific channel
-for the output instead of averaging the channels.
-The \fB\-l\fR, and \fB\-r\fR options will do averaging
-in quad-channel files so select the exact channel to prevent this.
-.SP
-The
-.B mixer
-effect can also be invoked with up to 16
-numbers, separated by commas, which specify the proportion (0 = 0% and 1 = 100%)
-of each input channel that is to be mixed into each output channel.
-In two-channel mode, 4 numbers are given: l \*(RA l, l \*(RA r, r \*(RA l, and r \*(RA r,
-respectively.
-In four-channel mode, the first 4 numbers give the proportions for the
-left-front output channel, as follows: lf \*(RA lf, rf \*(RA lf, lb \*(RA lf, and
-rb \*(RA rf.
-The next 4 give the right-front output in the same order, then
-left-back and right-back.
-.SP
-It is also possible to use the 16 numbers to expand or reduce the
-channel count; just specify 0 for unused channels.
-.SP
-Finally, certain reduced combination of numbers can be specified
-for certain input/output channel combinations.
-.ne 7
-.TS
-center;
-cI cI cI lI
-c c c l .
-In Ch	Out Ch	Num	Mappings
-2	1	2	l \*(RA l, r \*(RA l
-2	2	1	adjust balance
-4	1	4	lf \*(RA l, rf \*(RA l, lb \*(RA l, rb \*(RA l
-4	2	2	lf \*(RA l&rf \*(RA r, lb \*(RA l&rb \*(RA r
-4	4	1	adjust balance
-4	4	2	front balance, back balance
-.TE
-.DT
-.SP
-See also
-.B remix
-for a mixing effect that handles any number of channels.
-.TP
 \fBnoiseprof\fR [\fIprofile-file\fR]
 Calculate a profile of the audio for use in noise reduction.  See the
 description of the \fBnoisered\fR effect for details.
@@ -2954,11 +2898,7 @@
 \fIinput-02.wav\fR, ...,
 .IR input-06.wav .
 .SP
-See also
-.B mixer
-and
-.B swap
-for similar effects.
+See also the \fBswap\fR effect.
 .TP
 \fBrepeat\fR [\fIcount\fR (1)]
 Repeat the entire audio \fIcount\fR times, or once if \fIcount\fR is not given.
@@ -4185,6 +4125,66 @@
 for a volume-changing effect with different capabilities, and
 .B compand
 for a dynamic-range compression/expansion/limiting effect.
+.SS Deprecated Effects
+The following effects have been renamed or have their functionality
+included in another effect; they continue to work in this version of
+SoX but may be removed in future.
+.TP
+\fBmixer\fR [ \fB\-l\fR\^|\^\fB\-r\fR\^|\^\fB\-f\fR\^|\^\fB\-b\fR\^|\^\fB\-1\fR\^|\^\fB\-2\fR\^|\^\fB\-3\fR\^|\^\fB\-4\fR\^|\^\fIn\fR{\fB,\fIn\fR} ]
+Reduce the number of audio channels by mixing or selecting channels,
+or increase the number of channels by duplicating channels.
+Note: this effect operates on the audio
+.I channels
+within the SoX effects processing chain; it should not be confused with the
+.B \-m
+global option (where multiple
+.I files
+are mix-combined before entering the effects chain).
+.SP
+When reducing the number of channels it is possible to
+use the \fB\-l\fR, \fB\-r\fR, \fB\-f\fR, \fB\-b\fR,
+\fB\-1\fR, \fB\-2\fR, \fB\-3\fR, \fB\-4\fR, options to select only
+the left, right, front, back channel(s) or specific channel
+for the output instead of averaging the channels.
+The \fB\-l\fR, and \fB\-r\fR options will do averaging
+in quad-channel files so select the exact channel to prevent this.
+.SP
+The
+.B mixer
+effect can also be invoked with up to 16
+numbers, separated by commas, which specify the proportion (0 = 0% and 1 = 100%)
+of each input channel that is to be mixed into each output channel.
+In two-channel mode, 4 numbers are given: l \*(RA l, l \*(RA r, r \*(RA l, and r \*(RA r,
+respectively.
+In four-channel mode, the first 4 numbers give the proportions for the
+left-front output channel, as follows: lf \*(RA lf, rf \*(RA lf, lb \*(RA lf, and
+rb \*(RA rf.
+The next 4 give the right-front output in the same order, then
+left-back and right-back.
+.SP
+It is also possible to use the 16 numbers to expand or reduce the
+channel count; just specify 0 for unused channels.
+.SP
+Finally, certain reduced combination of numbers can be specified
+for certain input/output channel combinations.
+.ne 7
+.TS
+center;
+cI cI cI lI
+c c c l .
+In Ch	Out Ch	Num	Mappings
+2	1	2	l \*(RA l, r \*(RA l
+2	2	1	adjust balance
+4	1	4	lf \*(RA l, rf \*(RA l, lb \*(RA l, rb \*(RA l
+4	2	2	lf \*(RA l&rf \*(RA r, lb \*(RA l&rb \*(RA r
+4	4	1	adjust balance
+4	4	2	front balance, back balance
+.TE
+.DT
+.SP
+This effect has been superseded by the
+.B remix
+effect that handles any number of channels.
 .SH DIAGNOSTICS
 Exit status is 0 for no error, 1 if there is a problem with the
 command-line parameters, or 2 if an error occurs during file processing.
--- a/src/mixer.c
+++ b/src/mixer.c
@@ -546,7 +546,7 @@
   static sox_effect_handler_t handler = {
     "mixer",
     "[ -l | -r | -f | -b | -1 | -2 | -3 | -4 | n,n,n...,n ]",
-    SOX_EFF_MCHAN | SOX_EFF_CHAN | SOX_EFF_GAIN,
+    SOX_EFF_MCHAN | SOX_EFF_CHAN | SOX_EFF_GAIN | SOX_EFF_DEPRECATED,
     getopts, start, flow, 0, 0, 0, sizeof(priv_t)
   };
   return &handler;
@@ -567,6 +567,7 @@
   handler = *lsx_mixer_effect_fn();
   handler.name = "oops";
   handler.usage = NULL;
+  handler.flags &= ~SOX_EFF_DEPRECATED;
   handler.getopts = oops_getopts;
   return &handler;
 }