shithub: sox

Info  •  Files  •  Log  •  Branches

Extend upsample documentation

Write a bit more about upsample in the man page. Also remove the comment
regarding effp->out_signal.rate in src/upsample.c as it can't be
implemented: At this point, the input sample rate is unknown (zero);
since upsample (unlike rate) introduces a _relative_ sample rate change,
there is no meaningful value that can be written to out_signal.rate.

--- a/sox.1

+++ b/sox.1

@@ -1979,7 +1979,7 @@

 .SP

 See also the `Dithering' section above.

 .TP

-\fBdownsample [\fIfactor\fR(2)]

+\fBdownsample\fR [\fIfactor\fR(2)]

 Downsample the signal by an integer factor: Only the first out of

 each \fIfactor\fR samples is retained, the others are discarded.

 .SP

@@ -4005,10 +4005,16 @@

 it.  A value of 8000s for the \fIstart\fR parameter will wait until

 8000 samples are read before starting to process audio.

 .TP

-\fBupsample [\fIfactor\fR]

+\fBupsample\fR [\fIfactor\fR]

 Upsample the signal by an integer factor: \fIfactor\fR\-1 zero-value

-samples are inserted between each input sample.  Typically use is in

-combination with filtering effects.

+samples are inserted between each pair of input samples.  As a result, the

+original spectrum is replicated into the new frequency space (aliasing) and

+attenuated.  This attenuation can be compensated for by adding

+\fBvol \fIfactor\fR after any further processing.  The upsample effect is

+typically used in combination with filtering effects.

+.SP

+For a general resampling effect with anti-aliasing, see \fBrate\fR.  See

+also \fBdownsample\fR.

 .TP

 \fBvad \fR[\fIoptions\fR]

 Voice Activity Detector.  Attempts to trim silence and quiet

--- a/src/upsample.c

+++ b/src/upsample.c

@@ -28,9 +28,6 @@

   p->factor = 2;

   --argc, ++argv;

   do {NUMERIC_PARAMETER(factor, 1, 256)} while (0);

-  /* TODO: something like this may be needed here to inform libSoX client

-   * that the rate change indicated in start() is intended to be the final rate:

-  effp->out_signal.rate = effp->in_signal.rate * p->factor; */

   return argc? lsx_usage(effp) : SOX_SUCCESS;

 }

@@ -62,6 +59,6 @@

 sox_effect_handler_t const * lsx_upsample_effect_fn(void)

 {

   static sox_effect_handler_t handler = {"upsample", "[factor (2)]",

-    SOX_EFF_RATE, create, start, flow, NULL, NULL, NULL, sizeof(priv_t)};

+    SOX_EFF_RATE | SOX_EFF_MODIFY, create, start, flow, NULL, NULL, NULL, sizeof(priv_t)};

   return &handler;

 }