AudioWorkletProcessor: метод process()

Метод process() класса, производного от AudioWorkletProcessor, реализует алгоритм обработки аудио для аудиопроцессора worklet.

Хотя метод не является частью интерфейса AudioWorkletProcessor, любая реализация AudioWorkletProcessor должна предоставить метод process().

Метод вызывается синхронно из потока рендеринга аудио один раз для каждого блока аудио (также известного как квант рендеринга), направляемого через соответствующий AudioWorkletNode процессора. Другими словами, каждый раз, когда новый блок аудио готов для обработки вашим процессором, ваша функция process() вызывается для этого.

inputs

Массив входов, подключенных к узлу, каждый элемент которого, в свою очередь, является массивом каналов. Каждый канал — это Float32Array, содержащий 128 образцов. Например, inputs[n][m][i] будет обращаться к n-му входу, m-му каналу этого входа и i-му образцу этого канала.

Каждое значение образца находится в диапазоне [-1 .. 1].

Количество входов, а значит, и длина этого массива, фиксируется при создании узла (см. AudioWorkletNode). Если к n-му входу узла нет активного узла, inputs[n] будет пустым массивом (нет каналов ввода).

Количество каналов в каждом входе может варьироваться в зависимости от свойств channelCount и channelCountMode.

outputs

Массив выходов, структура которого аналогична параметру inputs. Он предназначен для заполнения во время выполнения метода process(). Каждый канал вывода по умолчанию заполняется нулями — процессор выведет тишину, если массивы вывода не изменены.

parameters

Объект, содержащий строковые ключи и Float32Array значения. Для каждого настраиваемого AudioParam, определенного с помощью геттера parameterDescriptors, ключом в объекте является name этого AudioParam, а значением — Float32Array. Значения массива вычисляются с учетом запланированных событий автоматизации.

Если скорость автоматизации параметра является "a-rate", массив будет содержать 128 значений — по одному для каждого кадра в текущем блоке аудио. Если в течение времени, представленного текущим блоком, автоматизация не происходит, массив может содержать одно значение, постоянное для всего блока, вместо 128 одинаковых значений.

Если скорость автоматизации является "k-rate", массив будет содержать одно значение, которое должно использоваться для каждого из 128 кадров.

Булево значение, указывающее, следует ли заставлять AudioWorkletNode оставаться активным, даже если внутренняя логика агента пользователя иначе решит, что можно безопасно выключить узел.

Возвращаемое значение позволяет вашему процессору влиять на политику жизненного цикла AudioWorkletProcessor и узла, который его владеет. Если комбинация возвращаемого значения и состояния узла заставит браузер остановить узел, process() больше не будет вызываться.

Возвращение true заставляет Web Audio API сохранить узел активным, в то время как возвращение false позволяет браузеру завершить узел, если он не генерирует новые данные аудио и не получает данные через входы, которые он обрабатывает.

Три наиболее распространённых типа узлов аудио:

1. Источник вывода. AudioWorkletProcessor, реализующий такой узел, должен возвращать true из метода process до тех пор, пока он производит вывод. Метод должен возвращать false как только станет известно, что он больше не будет производить вывод. Например, рассмотрим AudioBufferSourceNode — процессор за таким узлом должен возвращать true из метода process во время воспроизведения буфера и начать возвращать false после завершения воспроизведения буфера (нет способа вызвать play на том же AudioBufferSourceNode снова).
2. Узел, преобразующий свой вход. Процессор, реализующий такой узел, должен возвращать false из метода process для определения возможности удаления объекта из памяти на основании активности узлов ввода и ссылок на узел. Пример узла с таким поведением — GainNode. Как только нет подключенных входов и сохраненных ссылок, усиление больше не может применяться ни к чему, поэтому его можно безопасно удалить из памяти.
3. Узел, преобразующий свой вход, но имеющий так называемое время хвоста — это означает, что он будет производить вывод некоторое время даже после того, как его входы будут отключены или будут неактивны (производя нулевые каналы). Процессор, реализующий такой узел, должен возвращать true из метода process в течение периода времени хвоста, начиная с того момента, когда будут обнаружены входы, содержащие нулевые каналы. Примером такого узла является DelayNode — у него время хвоста равно его свойству delayTime.

Так как метод process() реализуется пользователем, он может вызывать любые исключения. Если возникнет необработанная ошибка, узел сгенерирует событие processorerror и будет выдавать тишину до конца своего жизненного цикла.

В этом примере мы создаём AudioWorkletProcessor, который выводит белый шум на свой первый выход. Усилие можно контролировать с помощью параметра customGain.

class WhiteNoiseProcessor extends AudioWorkletProcessor {
  process(inputs, outputs, parameters) {
    // take the first output
    const output = outputs[0];
    // fill each channel with random values multiplied by gain
    output.forEach((channel) => {
      for (let i = 0; i < channel.length; i++) {
        // generate random value for each sample
        // Math.random range is [0; 1); we need [-1; 1]
        // this won't include exact 1 but is fine for now for simplicity
        channel[i] =
          (Math.random() * 2 - 1) *
          // the array can contain 1 or 128 values
          // depending on if the automation is present
          // and if the automation rate is k-rate or a-rate
          (parameters["customGain"].length > 1
            ? parameters["customGain"][i]
            : parameters["customGain"][0]);
      }
    });
    // as this is a source node which generates its own output,
    // we return true so it won't accidentally get garbage-collected
    // if we don't have any references to it in the main thread
    return true;
  }
  // define the customGain parameter used in process method
  static get parameterDescriptors() {
    return [
      {
        name: "customGain",
        defaultValue: 1,
        minValue: 0,
        maxValue: 1,
        automationRate: "a-rate",
      },
    ];
  }
}

• Использование Web Audio API