// It works like this: There is a general interface for accessing an "integrated" audio clip - IAudioSample.

interface IAudioSample {

  int channels(); // 1 for mono, 2 for left+right, 3 for center+left+right... or whatever channel model you prefer

  DoubleRange bounds(); // our bounding box in samples according to sampleRate

  double sampleRate(); // in hertz

  default double start() { ret bounds().start(); }

  default double end() { ret bounds().end(); }

  default double length() { ret l(bounds()); }

  delegate Gain to AudioSampleOps.

  delegate SpeedUp to AudioSampleOps.

  delegate TimeShift to AudioSampleOps.

  // Query the integral.

  // Result is in the range -32768*(end-start) to 32767*(end-start)...

  // unless you applied too much gain (there is no clipping).

  // channel is between 0 and channels()-1 from here on out

  default double sampleSum(int channel, double start, double end) {

    ret readSumTable(channel, end-1) - readSumTable(channel, start-1);

  }

  default double readSumTable(int channel, double t) {

    int tFloor = ifloor(t);

    double val = readSumTable(channel, tFloor);

    if (tFloor == t)

      ret val;

    double next = readSumTable(channel, tFloor+1);

    ret blend(val, next, t-tFloor);

  }

  default double readSumTable(int channel, int position) {

    throw unimplemented(this);

  }

  // Here the range is -1 to 1 just to spice things up

  default double getPixel(int channel, double start, double end) {

    ret doubleRatio(sampleSum(channel, start, end), (end-start)*32768);

  }

  // RENDERING FUNCTIONS (visualize audio as BufferedImage)

  // [also "acoustic" rendering]

  // render audio as black-and-white (grayscale) stripes

  // h = height per channel

  default BufferedImage stripes(int h default 50) {

    int w = iceil(length());

    int channels = channels();

    ret imageFromFunction(w, h*channels, (x, y) -> {

      int channel = y/h;

      double value = sampleSum(channel, x, x+1);

      // lose lower 8 bits and shift to 0 to 255

      int digital = ifloor(value/256)+128;

      ret rgbIntFullAlpha(digital, digital, digital);

    });

  }

  // render audio as graph

  // h = height per channel

  default BufferedImage graph(int h default 100) {

    int w = iceil(length());

    ret mergeBufferedImagesVertically(

      countIteratorToList(channels(), c ->

        simpleGraph(w, h, x -> sampleSum(c, x, x+1), -32768, 32767)));

  }

  // render audio as stripes + graph (best way to look at it)

  default BufferedImage render(int h default 100) {

    ret mergeBufferedImagesVertically(stripes(h/2), graph(h));

  }

  // in bounds

  // all channels

  default short[] toShortArray() {

    DoubleRange r = bounds();

    int i = ifloor(r.start()), j = ifloor(r.end());

    int n = max(0, j-i);

    var channels = channels();

    short[] array = new[n*channels];

    int iArray = 0;

    for (; i < j; i++)

      for c to channels:

        array[iArray++] = clampToShort(iround(sampleSum(c, i, i+1)));

    ret array;

  }

  // END OF RENDERING FUNCTIONS

  // find maximum amplitude, going pixel-by-pixel

  // (remember: This clip may already have been temporally

  // scaled with speedUp(), so a "pixel" may represent the average

  // of multiple audio samples.)

  default double maxAmplitude() {

    int n = iceil(length()), channels = channels();

    double max = 0;

    for i to n:

      for c to channels: 

        max = max(max, abs(sampleSum(c, i, i+1)));

    ret min(32767, max);

  }

  // There are various non-destructive virtual transformations

  // which you can do on the audio clip (gain, speed-up and time-shift).

  // All transformations are affine in time and amplitude and thus

  // preserve the "integral image" property.

  default IAudioSample gain(double factor) {

    ret factor == 1 ? this : new Gain(factor, this);

  }

  // gain to maximum volume possible without clipping

  // (even though clipping isn't even a thing in integral audio wonderland,

  // so we just define "clipping" as exceeding the 32767 value we are used to from real audio.)

  default IAudioSample normalize() {

    ret gain(doubleRatio(32767, maxAmplitude()));

  }

  // resample with a factor

  public default IAudioSample speedUp(double factor) {

    ret factor == 1 ? this : new SpeedUp(factor, this);

  }

  // resample to a target frequency

  public default IAudioSample sampleAt(double freq) {

    ret speedUp(sampleRate()/freq);

  }

  public default IAudioSample timeShift aka shift(double shift) {

    ret shift == 0 ? this : new TimeShift(shift, this);

  }

  // For debug-printing. Valued from 0 to 1 this time because why not. First channel only

  default L<Double> firstPixels(int n default 20) {

    double[] pixels = new[n];

    for i to n:

      pixels[i] = sampleSum(0, i, i+1)/32768;

    ret wrapDoubleArrayAsList(pixels);

  }

  // also first channel only

  default double[] toDoubleArray() {

    int iStart = ifloor(start()), iEnd = iceil(end());

    double[] d = new[iEnd-iStart];

    for i over d:

      d[i] = sampleSum(0, i, i+1);

    ret d;

  }

} // end of IAudioSample