shithub: sox

Download patch

ref: 07a813e5fbfa132bb7cbf9d2545711a22f33d2f5
parent: 9191cec9babef8179e4345354cbf4eda77e7b183
author: robs <robs>
date: Mon Mar 24 16:41:04 EDT 2008

add some comments

--- a/src/example1.c
+++ b/src/example1.c
@@ -1,7 +1,7 @@
 /*
  * Simple example of using SoX libraries
  *
- * Copyright (c) 2007 robs@users.sourceforge.net
+ * Copyright (c) 2007-8 robs@users.sourceforge.net
  *
  * This program is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the
@@ -25,31 +25,61 @@
 #endif
 #include <assert.h>
 
-static sox_format_t * in, * out;
+static sox_format_t * in, * out; /* input and output files */ 
 
-static int input_drain(sox_effect_t *effp, sox_sample_t * obuf, sox_size_t * osamp)
+/* The function that will be called to input samples into the effects chain.
+ * In this example, we get samples to process from a SoX-openned audio file.
+ * In a different application, they might be generated or come from a different
+ * part of the application. */
+static int input_drain(
+    sox_effect_t * effp, sox_sample_t * obuf, sox_size_t * osamp)
 {
+  (void)effp;   /* This parameter is not needed in this example */
+
+  /* ensure that *osamp is a multiple of the number of channels. */
   *osamp -= *osamp % effp->out_signal.channels;
+
+  /* Read up to *osamp samples into obuf; store the actual number read
+   * back to *osamp */
   *osamp = sox_read(in, obuf, *osamp);
-  *osamp -= *osamp % effp->out_signal.channels;
+
+  /* sox_read may return a number that is less than was requested; only if 
+   * 0 samples is returned does it indicate that end-of-file has been reached
+   * or an error has occurred */
   if (!*osamp && in->sox_errno)
     fprintf(stderr, "%s: %s\n", in->filename, in->sox_errstr);
   return *osamp? SOX_SUCCESS : SOX_EOF;
 }
 
+/* The function that will be called to output samples from the effects chain.
+ * In this example, we store the samples in a SoX-openned audio file.
+ * In a different application, they might perhaps be analysed in some way, 
+ * or displayed as a wave-form */
 static int output_flow(sox_effect_t *effp UNUSED, sox_sample_t const * ibuf,
     sox_sample_t * obuf UNUSED, sox_size_t * isamp, sox_size_t * osamp)
 {
+  /* Write out *isamp samples */
   size_t len = sox_write(out, ibuf, *isamp);
 
-  *osamp = 0;
+  /* len is the number of samples that were actually written out; if this is
+   * different to *isamp, then something has gone wrong--most often, it's
+   * out of disc space */
   if (len != *isamp) {
     fprintf(stderr, "%s: %s\n", out->filename, out->sox_errstr);
     return SOX_EOF;
   }
-  return SOX_SUCCESS;
+
+  /* Outputting is the last `effect' in the effect chain so always passes
+   * 0 samples on to the next effect (as there isn't one!) */
+  *osamp = 0;
+
+  (void)effp;   /* This parameter is not needed in this example */
+
+  return SOX_SUCCESS; /* All samples output successfully */
 }
 
+/* A `stub' effect handler to handle inputting samples to the effects
+ * chain; the only function needed for this example is `drain' */
 static sox_effect_handler_t const * input_handler(void)
 {
   static sox_effect_handler_t handler = {
@@ -58,6 +88,8 @@
   return &handler;
 }
 
+/* A `stub' effect handler to handle outputting samples from the effects
+ * chain; the only function needed for this example is `flow' */
 static sox_effect_handler_t const * output_handler(void)
 {
   static sox_effect_handler_t handler = {
@@ -77,29 +109,51 @@
   char * vol[] = {"3dB"};
 
   assert(argc == 3);
+
+  /* All libSoX applications must start by initialising the SoX library */
   assert(sox_format_init() == SOX_SUCCESS);
 
+  /* Open the input file (with default parameters) */
   assert(in = sox_open_read(argv[1], NULL, NULL, NULL));
+
+  /* Open the output file; we must specify the output signal characteristics.
+   * Since we are using only simple effects, they are the same as the input
+   * file characteristics */
   assert(out = sox_open_write(NULL, argv[2], &in->signal, NULL, NULL, NULL, 0, NULL, 0));
 
+  /* Create an effects chain; some effects need to know about the input
+   * or output file encoding so we provide that information here */
   chain = sox_create_effects_chain(&in->encoding, &out->encoding);
 
+  /* The first effect in the effect chain must be something that can source
+   * samples; in this case, we have defined an input handler that inputs
+   * data from an audio file */
   sox_create_effect(&e, input_handler());
+  /* This becomes the first `effect' in the chain */
   assert(sox_add_effect(chain, &e, &in->signal, &in->signal) == SOX_SUCCESS);
 
+  /* Create the `vol' effect, and initialise it with the desired parameters: */
   sox_create_effect(&e, sox_find_effect("vol"));
   assert(e.handler.getopts(&e, 1, vol) == SOX_SUCCESS);
+  /* Add the effect to the end of the effects processing chain: */
   assert(sox_add_effect(chain, &e, &in->signal, &in->signal) == SOX_SUCCESS);
 
+  /* Create the `flanger' effect, and initialise it with default parameters: */
   sox_create_effect(&e, sox_find_effect("flanger"));
   assert(e.handler.getopts(&e, 0, NULL) == SOX_SUCCESS);
+  /* Add the effect to the end of the effects processing chain: */
   assert(sox_add_effect(chain, &e, &in->signal, &in->signal) == SOX_SUCCESS);
 
+  /* The last effect in the effect chain must be something that only consumes
+   * samples; in this case, we have defined an output handler that outputs
+   * data to an audio file */
   sox_create_effect(&e, output_handler());
   assert(sox_add_effect(chain, &e, &in->signal, &in->signal) == SOX_SUCCESS);
 
+  /* Flow samples through the effects processing chain until EOF is reached */
   sox_flow_effects(chain, NULL);
 
+  /* All done; tidy up: */
   sox_delete_effects(chain);
   sox_close(out);
   sox_close(in);
--- a/src/example2.c
+++ b/src/example2.c
@@ -27,7 +27,6 @@
 #endif
 #include <assert.h>
 
-
 /* 
  * Reads input file and displays a few seconds of wave-form, starting from
  * a given time through the audio.   E.g. example2 song2.au 30.75 1
@@ -37,39 +36,51 @@
   sox_format_t * in;
   sox_sample_t * buf;
   size_t blocks, block_size;
+  /* Period of audio over which we will measure its volume in order to
+   * display the wave-form: */
   static const double block_period = 0.025; /* seconds */
   double start_secs = 0, period = 2;
   char dummy;
   sox_size_t seek;
 
+  /* All libSoX applications must start by initialising the SoX library */
   assert(sox_format_init() == SOX_SUCCESS);
 
   assert(argc > 1);
-  ++argv, --argc;
+  ++argv, --argc; /* Move to 1st parameter */
 
+  /* Open the input file (with default parameters) */
   assert(in = sox_open_read(*argv, NULL, NULL, NULL));
-  ++argv, --argc;
+  ++argv, --argc; /* Move past this parameter */
 
-  if (argc) {
+  if (argc) { /* If given, read the start time: */
     assert(sscanf(*argv, "%lf%c", &start_secs, &dummy) == 1);
-    ++argv, --argc;
+    ++argv, --argc; /* Move past this parameter */
   }
 
-  if (argc) {
+  if (argc) { /* If given, read the period of time to display: */
     assert(sscanf(*argv, "%lf%c", &period, &dummy) == 1);
-    ++argv, --argc;
+    ++argv, --argc; /* Move past this parameter */
   }
 
+  /* Calculate the start position in number of samples: */
   seek = start_secs * in->signal.rate * in->signal.channels + .5;
+  /* Make sure that this is at a `wide sample' boundary: */
   seek -= seek % in->signal.channels;
+  /* Move the file pointer to the desired starting position */
   assert(sox_seek(in, seek, SOX_SEEK_SET) == SOX_SUCCESS);
 
+  /* Convert block size (in seconds) to a number of samples: */
   block_size = block_period * in->signal.rate * in->signal.channels + .5;
+  /* Make sure that this is at a `wide sample' boundary: */
   block_size -= block_size % in->signal.channels;
+  /* Allocate a block of memory to store the block of audio samples: */
   assert(buf = malloc(sizeof(sox_sample_t) * block_size));
 
+  /* This application requires that the audio has precisely 2 channels */
   assert(in->signal.channels == 2);
 
+  /* Read in and process blocks of audio for the selected period or until EOF: */
   for (blocks = 0; sox_read(in, buf, block_size) == block_size && blocks * block_period < period; ++blocks) {
     double left = 0, right = 0;
     size_t i, clips = 0;
@@ -77,17 +88,28 @@
     int l, r;
 
     for (i = 0; i < block_size; ++i) {
+      /* convert the sample from SoX's internal format to a `double' for
+       * processing in this application: */
       double sample = SOX_SAMPLE_TO_FLOAT_64BIT(buf[i], clips);
+
+      /* The samples for each channel are interleaved; in this example
+       * we allow only stereo audio, so the left channel audio can be found in
+       * even-numbered samples, and the right channel audio in odd-numbered
+       * samples: */
       if (i & 1)
-        right = max(right, fabs(sample));
+        right = max(right, fabs(sample)); /* Find the peak volume in the block */
       else
-        left = max(left, fabs(sample));
+        left = max(left, fabs(sample)); /* Find the peak volume in the block */
     }
-    l = (1 - left) * 35;
-    r = (1 - right) * 35;
+
+    /* Build up the wave form by displaying the left & right channel
+     * volume as a line length: */
+    l = (1 - left) * 35 + .5;
+    r = (1 - right) * 35 + .5;
     printf("%8.3f%36s|%s\n", start_secs + blocks * block_period, line + l, line + r);
   }
 
+  /* All done; tidy up: */
   free(buf);
   sox_close(in);
   sox_format_quit();