From c93a18535ffea1ca7b18eb41c34064b77f8419e3 Mon Sep 17 00:00:00 2001 From: Chris Cannam Date: Fri, 5 Feb 2016 15:14:46 +0000 Subject: [PATCH] Comments to clarify sample layout and counting --- rubberband/RubberBandStretcher.h | 54 +++++++++++++++++++++++++++----- 1 file changed, 47 insertions(+), 7 deletions(-) diff --git a/rubberband/RubberBandStretcher.h b/rubberband/RubberBandStretcher.h index b680e8c..fc9fe4d 100644 --- a/rubberband/RubberBandStretcher.h +++ b/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;