<!doctype html>
<html>
  <head>
    <title>Test k-rate AudioParam Inputs for BiquadFilterNode</title>
    <script src="/resources/testharness.js"></script>
    <script src="/resources/testharnessreport.js"></script>
    <script src="/webaudio/resources/audit-util.js"></script>
    <script src="/webaudio/resources/audit.js"></script>
  </head>

  <body>
    <script>
      // sampleRate and duration are fairly arbitrary.  We use low values to
      // limit the complexity of the test.
      let sampleRate = 8192;
      let testDuration = 0.5;

      let audit = Audit.createTaskRunner();

      audit.define(
          {label: 'Frequency AudioParam', description: 'k-rate input works'},
          async (task, should) => {
            // Test frequency AudioParam using a lowpass filter whose bandwidth
            // is initially larger than the oscillator frequency.  Then automate
            // the frequency to 0 so that the output of the filter is 0 (because
            // the cutoff is 0).
            let oscFrequency = 440;

            let options = {
              sampleRate: sampleRate,
              paramName: 'frequency',
              oscFrequency: oscFrequency,
              testDuration: testDuration,
              filterOptions: {type: 'lowpass', frequency: 0},
              autoStart:
                  {method: 'setValueAtTime', args: [2 * oscFrequency, 0]},
              autoEnd: {
                method: 'linearRampToValueAtTime',
                args: [0, testDuration / 4]
              }
            };

            let buffer = await doTest(should, options);
            let expected = buffer.getChannelData(0);
            let actual = buffer.getChannelData(1);
            let halfLength = expected.length / 2;

            // Sanity check.  The expected output should not be zero for
            // the first half, but should be zero for the second half
            // (because the filter bandwidth is exactly 0).
            const prefix = 'Expected k-rate frequency with automation';

            should(
                expected.slice(0, halfLength),
                `${prefix} output[0:${halfLength - 1}]`)
                .notBeConstantValueOf(0);
            should(
                expected.slice(expected.length),
                `${prefix} output[${halfLength}:]`)
                .beConstantValueOf(0);

            // Outputs should be the same.  Break the message into two
            // parts so we can see the expected outputs.
            checkForSameOutput(should, options.paramName, actual, expected);

            task.done();
          });

      audit.define(
          {label: 'Q AudioParam', description: 'k-rate input works'},
          async (task, should) => {
            // Test Q AudioParam.  Use a bandpass filter whose center frequency
            // is fairly far from the oscillator frequency.  Then start with a Q
            // value of 0 (so everything goes through) and then increase Q to
            // some large value such that the out-of-band signals are basically
            // cutoff.
            let frequency = 440;
            let oscFrequency = 4 * frequency;

            let options = {
              sampleRate: sampleRate,
              oscFrequency: oscFrequency,
              testDuration: testDuration,
              paramName: 'Q',
              filterOptions: {type: 'bandpass', frequency: frequency, Q: 0},
              autoStart: {method: 'setValueAtTime', args: [0, 0]},
              autoEnd: {
                method: 'linearRampToValueAtTime',
                args: [100, testDuration / 4]
              }
            };

            const buffer = await doTest(should, options);
            let expected = buffer.getChannelData(0);
            let actual = buffer.getChannelData(1);

            // Outputs should be the same
            checkForSameOutput(should, options.paramName, actual, expected);

            task.done();
          });

      audit.define(
          {label: 'Gain AudioParam', description: 'k-rate input works'},
          async (task, should) => {
            // Test gain AudioParam.  Use a peaking filter with a large Q so the
            // peak is narrow with a center frequency the same as the oscillator
            // frequency.  Start with a gain of 0 so everything goes through and
            // then ramp the gain down to -100 so that the oscillator is
            // filtered out.
            let oscFrequency = 4 * 440;

            let options = {
              sampleRate: sampleRate,
              oscFrequency: oscFrequency,
              testDuration: testDuration,
              paramName: 'gain',
              filterOptions:
                  {type: 'peaking', frequency: oscFrequency, Q: 100, gain: 0},
              autoStart: {method: 'setValueAtTime', args: [0, 0]},
              autoEnd: {
                method: 'linearRampToValueAtTime',
                args: [-100, testDuration / 4]
              }
            };

            const buffer = await doTest(should, options);
            let expected = buffer.getChannelData(0);
            let actual = buffer.getChannelData(1);

            // Outputs should be the same
            checkForSameOutput(should, options.paramName, actual, expected);

            task.done();
          });

      audit.define(
          {label: 'Detune AudioParam', description: 'k-rate input works'},
          async (task, should) => {
            // Test detune AudioParam.  The basic idea is the same as the
            // frequency test above, but insteda of automating the frequency, we
            // automate the detune value so that initially the filter cutuff is
            // unchanged and then changing the detune until the cutoff goes to 1
            // Hz, which would cause the oscillator to be filtered out.
            let oscFrequency = 440;
            let filterFrequency = 5 * oscFrequency;

            // For a detune value d, the computed frequency, fc, of the filter
            // is fc = f*2^(d/1200), where f is the frequency of the filter.  Or
            // d = 1200*log2(fc/f).  Compute the detune value to produce a final
            // cutoff frequency of 1 Hz.
            let detuneEnd = 1200 * Math.log2(1 / filterFrequency);

            let options = {
              sampleRate: sampleRate,
              oscFrequency: oscFrequency,
              testDuration: testDuration,
              paramName: 'detune',
              filterOptions: {
                type: 'lowpass',
                frequency: filterFrequency,
                detune: 0,
                gain: 0
              },
              autoStart: {method: 'setValueAtTime', args: [0, 0]},
              autoEnd: {
                method: 'linearRampToValueAtTime',
                args: [detuneEnd, testDuration / 4]
              }
            };

            const buffer = await doTest(should, options);
            let expected = buffer.getChannelData(0);
            let actual = buffer.getChannelData(1);

            // Outputs should be the same
            checkForSameOutput(should, options.paramName, actual, expected);

            task.done();
          });

      audit.define('All k-rate inputs', async (task, should) => {
        // Test the case where all AudioParams are set to k-rate with an input
        // to each AudioParam.  Similar to the above tests except all the params
        // are k-rate.
        let testFrames = testDuration * sampleRate;
        let context = new OfflineAudioContext(
            {numberOfChannels: 2, sampleRate: sampleRate, length: testFrames});

        let merger = new ChannelMergerNode(
            context, {numberOfInputs: context.destination.channelCount});
        merger.connect(context.destination);

        let src = new OscillatorNode(context);

        // The peaking filter uses all four AudioParams, so this is the node to
        // test.
        let filterOptions =
            {type: 'peaking', frequency: 0, detune: 0, gain: 0, Q: 0};
        let refNode;
        should(
            () => refNode = new BiquadFilterNode(context, filterOptions),
            `Create: refNode = new BiquadFilterNode(context, ${
                JSON.stringify(filterOptions)})`)
            .notThrow();

        let tstNode;
        should(
            () => tstNode = new BiquadFilterNode(context, filterOptions),
            `Create: tstNode = new BiquadFilterNode(context, ${
                JSON.stringify(filterOptions)})`)
            .notThrow();
        ;

        // Make all the AudioParams k-rate.
        ['frequency', 'Q', 'gain', 'detune'].forEach(param => {
          should(
              () => refNode[param].automationRate = 'k-rate',
              `Set rate: refNode[${param}].automationRate = 'k-rate'`)
              .notThrow();
          should(
              () => tstNode[param].automationRate = 'k-rate',
              `Set rate: tstNode[${param}].automationRate = 'k-rate'`)
              .notThrow();
        });

        // One input for each AudioParam.
        let mod = {};
        ['frequency', 'Q', 'gain', 'detune'].forEach(param => {
          should(
              () => mod[param] = new ConstantSourceNode(context, {offset: 0}),
              `Create: mod[${
                  param}] = new ConstantSourceNode(context, {offset: 0})`)
              .notThrow();
          ;
          should(
              () => mod[param].offset.automationRate = 'a-rate',
              `Set rate: mod[${param}].offset.automationRate = 'a-rate'`)
              .notThrow();
        });

        // Set up automations for refNode.  We want to start the filter with
        // parameters that let the oscillator signal through more or less
        // untouched.  Then change the filter parameters to filter out the
        // oscillator.  What happens in between doesn't reall matter for this
        // test.  Hence, set the initial parameters with a center frequency well
        // above the oscillator and a Q and gain of 0 to pass everthing.
        [['frequency', [4 * src.frequency.value, 0]], ['Q', [0, 0]],
         ['gain', [0, 0]], ['detune', [4 * 1200, 0]]]
            .forEach(param => {
              should(
                  () => refNode[param[0]].setValueAtTime(...param[1]),
                  `Automate 0: refNode.${param[0]}.setValueAtTime(${
                      param[1][0]}, ${param[1][1]})`)
                  .notThrow();
              should(
                  () => mod[param[0]].offset.setValueAtTime(...param[1]),
                  `Automate 0: mod[${param[0]}].offset.setValueAtTime(${
                      param[1][0]}, ${param[1][1]})`)
                  .notThrow();
            });

        // Now move the filter frequency to the oscillator frequency with a high
        // Q and very low gain to remove the oscillator signal.
        [['frequency', [src.frequency.value, testDuration / 4]],
         ['Q', [40, testDuration / 4]], ['gain', [-100, testDuration / 4]], [
           'detune', [0, testDuration / 4]
         ]].forEach(param => {
          should(
              () => refNode[param[0]].linearRampToValueAtTime(...param[1]),
              `Automate 1: refNode[${param[0]}].linearRampToValueAtTime(${
                  param[1][0]}, ${param[1][1]})`)
              .notThrow();
          should(
              () => mod[param[0]].offset.linearRampToValueAtTime(...param[1]),
              `Automate 1: mod[${param[0]}].offset.linearRampToValueAtTime(${
                  param[1][0]}, ${param[1][1]})`)
              .notThrow();
        });

        // Connect everything
        src.connect(refNode).connect(merger, 0, 0);
        src.connect(tstNode).connect(merger, 0, 1);

        src.start();
        for (let param in mod) {
          should(
              () => mod[param].connect(tstNode[param]),
              `Connect: mod[${param}].connect(tstNode.${param})`)
              .notThrow();
        }

        for (let param in mod) {
          should(() => mod[param].start(), `Start: mod[${param}].start()`)
              .notThrow();
        }

        const buffer = await context.startRendering();
        let expected = buffer.getChannelData(0);
        let actual = buffer.getChannelData(1);

        // Sanity check that the output isn't all zeroes.
        should(actual, 'All k-rate AudioParams').notBeConstantValueOf(0);
        should(actual, 'All k-rate AudioParams').beCloseToArray(expected, {
          absoluteThreshold: 0
        });

        task.done();
      });

      audit.run();

      async function doTest(should, options) {
        // Test that a k-rate AudioParam with an input reads the input value and
        // is actually k-rate.
        //
        // A refNode is created with an automation timeline.  This is the
        // expected output.
        //
        // The testNode is the same, but it has a node connected to the k-rate
        // AudioParam.  The input to the node is an a-rate ConstantSourceNode
        // whose output is automated in exactly the same was as the refNode.  If
        // the test passes, the outputs of the two nodes MUST match exactly.

        // The options argument MUST contain the following members:
        //   sampleRate - the sample rate for the offline context
        //   testDuration - duration of the offline context, in sec.
        //   paramName  - the name of the AudioParam to be tested
        //   oscFrequency - frequency of oscillator source
        //   filterOptions - options used to construct the BiquadFilterNode
        //   autoStart     - information about how to start the automation
        //   autoEnd       - information about how to end the automation
        //
        //   The autoStart and autoEnd options are themselves dictionaries with
        //   the following required members:
        //     method - name of the automation method to be applied
        //     args   - array of arguments to be supplied to the method.
        let {
          sampleRate,
          paramName,
          oscFrequency,
          autoStart,
          autoEnd,
          testDuration,
          filterOptions
        } = options;

        let testFrames = testDuration * sampleRate;
        let context = new OfflineAudioContext(
            {numberOfChannels: 2, sampleRate: sampleRate, length: testFrames});

        let merger = new ChannelMergerNode(
            context, {numberOfInputs: context.destination.channelCount});
        merger.connect(context.destination);

        // Any calls to |should| are meant to be informational so we can see
        // what nodes are created and the automations used.
        let src;

        // Create the source.
        should(
            () => {
              src = new OscillatorNode(context, {frequency: oscFrequency});
            },
            `${paramName}: new OscillatorNode(context, {frequency: ${
                oscFrequency}})`)
            .notThrow();

        // The refNode automates the AudioParam with k-rate automations, no
        // inputs.
        let refNode;
        should(
            () => {
              refNode = new BiquadFilterNode(context, filterOptions);
            },
            `Reference BiquadFilterNode(c, ${JSON.stringify(filterOptions)})`)
            .notThrow();

        refNode[paramName].automationRate = 'k-rate';

        // Set up automations for the reference node.
        should(
            () => {
              refNode[paramName][autoStart.method](...autoStart.args);
            },
            `refNode.${paramName}.${autoStart.method}(${autoStart.args})`)
            .notThrow();
        should(
            () => {
              refNode[paramName][autoEnd.method](...autoEnd.args);
            },
            `refNode.${paramName}.${autoEnd.method}.(${autoEnd.args})`)
            .notThrow();

        // The tstNode does the same automation, but it comes from the input
        // connected to the AudioParam.
        let tstNode;
        should(
            () => {
              tstNode = new BiquadFilterNode(context, filterOptions);
            },
            `Test BiquadFilterNode(context, ${JSON.stringify(filterOptions)})`)
            .notThrow();
        tstNode[paramName].automationRate = 'k-rate';

        // Create the input to the AudioParam of the test node.  The output of
        // this node MUST have the same set of automations as the reference
        // node, and MUST be a-rate to make sure we're handling k-rate inputs
        // correctly.
        let mod = new ConstantSourceNode(context);
        mod.offset.automationRate = 'a-rate';
        should(
            () => {
              mod.offset[autoStart.method](...autoStart.args);
            },
            `${paramName}: mod.offset.${autoStart.method}(${autoStart.args})`)
            .notThrow();
        should(
            () => {
              mod.offset[autoEnd.method](...autoEnd.args);
            },
            `${paramName}: mod.offset.${autoEnd.method}(${autoEnd.args})`)
            .notThrow();

        // Create graph
        mod.connect(tstNode[paramName]);
        src.connect(refNode).connect(merger, 0, 0);
        src.connect(tstNode).connect(merger, 0, 1);

        // Run!
        src.start();
        mod.start();
        return context.startRendering();
      }

      function checkForSameOutput(should, paramName, actual, expected) {
        let halfLength = expected.length / 2;

        // Outputs should be the same.  We break the check into halves so we can
        // see the expected outputs.  Mostly for a simple visual check that the
        // output from the second half is small because the tests generally try
        // to filter out the signal so that the last half of the output is
        // small.
        should(
            actual.slice(0, halfLength),
            `k-rate ${paramName} with input: output[0,${halfLength}]`)
            .beCloseToArray(
                expected.slice(0, halfLength), {absoluteThreshold: 0});
        should(
            actual.slice(halfLength),
            `k-rate ${paramName} with input: output[${halfLength}:]`)
            .beCloseToArray(expected.slice(halfLength), {absoluteThreshold: 0});
      }
    </script>
  </body>
</html>