Comments to clarify sample layout and counting

rubberband/RubberBandStretcher.h

@@ -462,11 +462,17 @@ public:
     void setPitchOption(Options options);
 
     /**
-     * Tell the stretcher exactly how many input samples it will
+     * Tell the stretcher exactly how many input sample frames it will
      * receive.  This is only useful in Offline mode, when it allows
      * the stretcher to ensure that the number of output samples is
      * exactly correct.  In RealTime mode no such guarantee is
      * possible and this value is ignored.
+     *
+     * Note that the value of "samples" refers to the number of audio
+     * sample frames, which may be multi-channel, not the number of
+     * individual samples. (For example, one second of stereo audio
+     * sampled at 44100Hz yields a value of 44100 sample frames, not
+     * 88200.)  This rule applies throughout the Rubber Band API.
      */
     void setExpectedInputDuration(size_t samples);
 
@@ -492,6 +498,12 @@ public:
      * Note that this value is only relevant to process(), not to
      * study() (to which you may pass any number of samples at a time,
      * and from which there is no output).
+     *
+     * Note that the value of "samples" refers to the number of audio
+     * sample frames, which may be multi-channel, not the number of
+     * individual samples. (For example, one second of stereo audio
+     * sampled at 44100Hz yields a value of 44100 sample frames, not
+     * 88200.)  This rule applies throughout the Rubber Band API.
      */
     void setMaxProcessSize(size_t samples);
 
@@ -512,6 +524,12 @@ public:
      * Note that this value is only relevant to process(), not to
      * study() (to which you may pass any number of samples at a time,
      * and from which there is no output).
+     *
+     * Note that the return value refers to the number of audio sample
+     * frames, which may be multi-channel, not the number of
+     * individual samples. (For example, one second of stereo audio
+     * sampled at 44100Hz yields a value of 44100 sample frames, not
+     * 88200.)  This rule applies throughout the Rubber Band API.
      */
      size_t getSamplesRequired() const;
 
@@ -553,9 +571,14 @@ public:
      * "input" should point to de-interleaved audio data with one
      * float array per channel. Sample values are conventionally
      * expected to be in the range -1.0f to +1.0f.  "samples" supplies
-     * the number of audio sample frames available in "input" (that
-     * is, the number of possibly multi-channel frames rather than of
-     * individual samples). If "samples" is zero, "input" may be NULL.
+     * the number of audio sample frames available in "input". If
+     * "samples" is zero, "input" may be NULL.
+     *
+     * Note that the value of "samples" refers to the number of audio
+     * sample frames, which may be multi-channel, not the number of
+     * individual samples. (For example, one second of stereo audio
+     * sampled at 44100Hz yields a value of 44100 sample frames, not
+     * 88200.)  This rule applies throughout the Rubber Band API.
      * 
      * Set "final" to true if this is the last block of data that will
      * be provided to study() before the first process() call.
@@ -569,9 +592,13 @@ public:
      * "input" should point to de-interleaved audio data with one
      * float array per channel. Sample values are conventionally
      * expected to be in the range -1.0f to +1.0f.  "samples" supplies
-     * the number of audio sample frames available in "input" (that
-     * is, the number of possibly multi-channel frames rather than of
-     * individual samples).
+     * the number of audio sample frames available in "input".
+     *
+     * Note that the value of "samples" refers to the number of audio
+     * sample frames, which may be multi-channel, not the number of
+     * individual samples. (For example, one second of stereo audio
+     * sampled at 44100Hz yields a value of 44100 sample frames, not
+     * 88200.)  This rule applies throughout the Rubber Band API.
      *
      * Set "final" to true if this is the last block of input data.
      */
@@ -587,6 +614,12 @@ public:
      * enough data has yet been processed.  Call getSamplesRequired()
      * to discover whether more input is needed.
      *
+     * Note that the return value refers to the number of audio sample
+     * frames, which may be multi-channel, not the number of
+     * individual samples. (For example, one second of stereo audio
+     * sampled at 44100Hz yields a value of 44100 sample frames, not
+     * 88200.)  This rule applies throughout the Rubber Band API.
+     *
      * This function returns -1 if all data has been fully processed
      * and all output read, and the stretch process is now finished.
      */
@@ -598,6 +631,13 @@ public:
      * channel for de-interleaved audio data) pointed to by "output".
      * The return value is the actual number of sample frames
      * retrieved.
+     *
+     * Note that the value of "samples" and the return value refer to
+     * the number of audio sample frames, which may be multi-channel,
+     * not the number of individual samples. (For example, one second
+     * of stereo audio sampled at 44100Hz yields a value of 44100
+     * sample frames, not 88200.)  This rule applies throughout the
+     * Rubber Band API.
      */
     size_t retrieve(float *const *output, size_t samples) const;