AudioWorkletProcessor: process()-Methode

inputs

Ein Array von Eingaben, die mit dem Knoten verbunden sind, wobei jedes Element seinerseits ein Array von Kanälen ist. Jeder Kanal ist ein Float32Array, das 128 Samples enthält. Zum Beispiel wird inputs[n][m][i] den n-ten Eingang, den m-ten Kanal dieses Eingangs und das i-te Sample dieses Kanals aufrufen.

Jeder Sample-Wert liegt im Bereich von [-1 .. 1].

Die Anzahl der Eingaben und somit die Länge dieses Arrays wird bei der Konstruktion des Knotens festgelegt (siehe AudioWorkletNode). Wenn kein aktiver Knoten mit der n-ten Eingabe des Knotens verbunden ist, wird inputs[n] ein leeres Array sein (keine Eingabekanäle verfügbar).

Die Anzahl der Kanäle in jeder Eingabe kann variieren, abhängig von den Eigenschaften channelCount und channelCountMode.

outputs

Ein Array von Ausgaben, das der Struktur des inputs-Parameters ähnlich ist. Es soll während der Ausführung der process()-Methode gefüllt werden. Jeder der Ausgabekanäle ist standardmäßig mit Nullen gefüllt — der Prozessor wird Stille ausgeben, es sei denn, die Ausgabe-Arrays werden modifiziert.

parameters

Ein Objekt, das Zeichenketten-Schlüssel und Float32Array-Werte enthält. Für jedes benutzerdefinierte AudioParam, das unter Verwendung des parameterDescriptors-Getters definiert wurde, ist der Schlüssel im Objekt ein name dieses AudioParam, und der Wert ist ein Float32Array. Die Werte des Arrays werden berechnet, indem geplante Automatisierungsereignisse berücksichtigt werden.

Wenn die Automatisierungsrate des Parameters "a-rate" ist, wird das Array 128 Werte enthalten — einen für jedes Frame im aktuellen Audio-Block. Wenn keine Automatisierung während der durch den aktuellen Block dargestellten Zeit stattfindet, kann das Array einen einzelnen Wert enthalten, der für den gesamten Block konstant ist, anstelle von 128 identischen Werten.

Wenn die Automatisierungsrate "k-rate" ist, wird das Array einen einzelnen Wert enthalten, der für alle 128 Frames verwendet werden soll.

Ein Boolean-Wert, der angibt, ob der AudioWorkletNode aktiv bleiben soll, selbst wenn die interne Logik des Benutzeragenten andernfalls entscheiden würde, dass es sicher ist, den Knoten herunterzufahren.

Der zurückgegebene Wert ermöglicht es Ihrem Prozessor, Einfluss auf die Lebensdauer-Richtlinie des AudioWorkletProcessor und des Knotens, der ihn besitzt, zu nehmen. Wenn die Kombination aus dem Rückgabewert und dem Zustand des Knotens den Browser dazu veranlasst, den Knoten zu beenden, wird process() nicht erneut aufgerufen.

Die Rückgabe von true zwingt die Web Audio API, den Knoten am Leben zu halten, während die Rückgabe von false dem Browser erlaubt, den Knoten zu beenden, wenn er weder neue Audiodaten generiert noch Daten über seine Eingänge empfängt, die er verarbeitet.

Die 3 häufigsten Arten von Audioknoten sind:

1. Eine Quelle eines Ausgabes. Ein AudioWorkletProcessor, der einen solchen Knoten implementiert, sollte true von der process-Methode zurückgeben, solange er eine Ausgabe produziert. Die Methode sollte false zurückgeben, sobald bekannt ist, dass sie keine Ausgabe mehr produzieren wird. Zum Beispiel sollte der Prozessor hinter einem AudioBufferSourceNode true von der process-Methode zurückgeben, während der Puffer abgespielt wird, und anfangen, false zurückzugeben, wenn das Abspielen des Puffers beendet ist (es gibt keine Möglichkeit, play auf dem gleichen AudioBufferSourceNode erneut aufzurufen).
2. Ein Knoten, der seinen Eingang transformiert. Ein Prozessor, der einen solchen Knoten implementiert, sollte false von der process-Methode zurückgeben, um die Präsenz von aktiven Eingabeknoten und Referenzen zum Knoten zu verwenden, um zu bestimmen, ob er vom Garbage-Collector entfernt werden kann. Ein Beispiel für einen Knoten mit diesem Verhalten ist der GainNode. Sobald keine Eingaben mehr verbunden und keine Referenzen mehr vorhanden sind, kann der Gain nicht mehr auf etwas angewendet werden, sodass er sicher vom Garbage-Collector entfernt werden kann.
3. Ein Knoten, der seinen Eingang transformiert, aber eine sogenannte Nachlaufzeit hat — das bedeutet, dass er für einige Zeit noch eine Ausgabe produzieren wird, selbst nachdem seine Eingaben getrennt oder inaktiv (keine Kanäle produzierend) sind. Ein Prozessor, der einen solchen Knoten implementiert, sollte während der Nachlaufzeit true von der process-Methode zurückgeben, beginnend sobald Eingaben gefunden werden, die keine Kanäle enthalten. Ein Beispiel für einen solchen Knoten ist der DelayNode — er hat eine Nachlaufzeit, die seiner delayTime-Eigenschaft entspricht.

Da die process()-Methode vom Benutzer implementiert wird, kann sie alles werfen. Wenn ein nicht abgefangener Fehler geworfen wird, wird der Knoten ein processorerror Ereignis auslösen und für den Rest seiner Lebensdauer Stille ausgeben.

In diesem Beispiel erstellen wir einen AudioWorkletProcessor, der weißes Rauschen auf seiner ersten Ausgabe ausgibt. Die Verstärkung kann durch den customGain-Parameter gesteuert werden.

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",
      },
    ];
  }
}

Dies ist keine Methode, die von Browsern bereitgestellt wird, sondern eine Callback-Methode, die im Client-Code geschrieben werden muss.

• Verwendung der Web Audio API