docs: explain forward and inverse normalization

README.md

@@ -44,6 +44,29 @@ You can do other cool stuff with the extras you'll find in tools/
 The core fft and most tools/ code can be compiled to use float, double,
  Q15 short or Q31 samples. The default is float.
 
+### Forward and inverse scaling
+
+For floating-point builds (`float` or `double`), neither direction is
+normalized. A forward transform followed by an inverse transform returns
+`nfft` times the original input. Divide each inverse output sample by
+`nfft` to recover the input:
+
+```c
+    /* After kiss_fft(inverse_cfg, spectrum, recovered): */
+    for (int k = 0; k < nfft; ++k) {
+        recovered[k].r /= nfft;
+        recovered[k].i /= nfft;
+    }
+```
+
+The same convention applies to `kiss_fft_stride()` and the real transform
+pair `kiss_fftr()` / `kiss_fftri()`. For the real pair, divide the `nfft`
+real output samples by the original real transform length, not by the
+number of complex frequency bins (`nfft / 2 + 1`).
+
+Fixed-point builds scale internally in both directions to prevent overflow;
+do not apply the floating-point normalization recipe to them.
+
 ## BUILDING:
 
 There are two functionally-equivalent build systems supported by kissfft:

kiss_fft.h

@@ -147,6 +147,10 @@ kiss_fft_cfg KISS_FFT_API kiss_fft_alloc(int nfft,int inverse_fft,void * mem,siz
  * for a forward FFT,
  * fin should be  f[0] , f[1] , ... ,f[nfft-1]
  * fout will be   F[0] , F[1] , ... ,F[nfft-1]
+ * Floating-point transforms are unnormalized in both directions: a forward
+ * transform followed by an inverse yields nfft times the original input.
+ * Divide the inverse output by nfft to recover the input. Fixed-point builds
+ * instead scale internally in both directions to prevent overflow.
  * Note that each element is complex and can be accessed like
     f[k].r and f[k].i
  * */

kiss_fftr.h

@@ -44,6 +44,9 @@ void KISS_FFT_API kiss_fftri(kiss_fftr_cfg cfg,const kiss_fft_cpx *freqdata,kiss
 /*
  input freqdata has  nfft/2+1 complex points
  output timedata has nfft scalar points
+ For floating-point builds, a kiss_fftr / kiss_fftri round trip returns
+ nfft times the input; divide timedata by nfft to recover the input.
+ Fixed-point builds scale internally and use a different convention.
 */
 
 #define kiss_fftr_free KISS_FFT_FREE