AudioWorkletProcessor: process()-Methode

inputs

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

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

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

Die Anzahl der Kanäle in jedem Eingang kann je nach den Eigenschaften channelCount und channelCountMode variieren.

outputs

Ein Array von Ausgängen, das in seiner Struktur dem Parameter inputs ähnelt. Es soll während der Ausführung der process()-Methode gefüllt werden. Jeder der Ausgabekanäle wird standardmäßig mit Nullen gefüllt—der Prozessor gibt Stille aus, es sei denn, die Ausgabearrays werden modifiziert.

parameters

Ein Objekt, das Zeichenketten als Schlüssel und Float32Array als Werte enthält. Für jeden benutzerdefinierten AudioParam, der mit dem parameterDescriptors-Getter definiert wurde, ist der Schlüssel im Objekt ein name dieses AudioParam, und der Wert ist ein Float32Array. Die Werte des Arrays werden unter Berücksichtigung geplanter Automatisierungsereignisse berechnet.

Wenn die Automatisierungsrate des Parameters "a-rate" ist, enthält das Array 128 Werte—einen für jeden Frame im aktuellen Audioblock. Wenn während der durch den aktuellen Block dargestellten Zeit keine Automatisierung stattfindet, kann das Array einen einzigen Wert enthalten, der für den gesamten Block konstant ist, anstatt 128 identische Werte.

Wenn die Automatisierungsrate "k-rate" ist, enthält das Array einen einzigen Wert, der für jeden der 128 Frames verwendet werden soll.

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

Der zurückgegebene Wert ermöglicht es Ihrem Prozessor, die Lebenszykluspolitik des AudioWorkletProcessor und des ihn besitzenden Knotens zu beeinflussen. Wenn die Kombination aus Rückgabewert und Zustand des Knotens dazu führt, dass der Browser entscheidet, den Knoten zu stoppen, wird process() nicht erneut aufgerufen.

Durch die Rückgabe von true wird die Web Audio API gezwungen, den Knoten am Leben zu halten, während die Rückgabe von false dem Browser ermöglicht, den Knoten zu beenden, wenn er weder neue Audiodaten erzeugt noch Daten durch seine Eingänge empfängt, die er verarbeitet.

Die 3 häufigsten Typen von Audioknoten sind:

1. Eine Ausgabequelle. Ein AudioWorkletProcessor, der einen solchen Knoten implementiert, sollte true von der process-Methode zurückgeben, solange er eine Ausgabe erzeugt. Die Methode sollte false zurückgeben, sobald bekannt ist, dass sie keine Ausgabe mehr erzeugen wird. Zum Beispiel sollte der Prozessor hinter einem AudioBufferSourceNode true von der process-Methode zurückgeben, während der Puffer abgespielt wird, und false zurückgeben, wenn das Abspielen des Puffers beendet ist (es gibt keine Möglichkeit, play auf demselben AudioBufferSourceNode erneut zu rufen).
2. Ein Knoten, der seine Eingabe transformiert. Ein Prozessor, der einen solchen Knoten implementiert, sollte false von der process-Methode zurückgeben, um das Vorhandensein aktiver Eingangsknoten und Verweise auf den Knoten zu erlauben, die bestimmen, ob er gesammelt werden kann. Ein Beispiel für einen Knoten mit diesem Verhalten ist der GainNode. Sobald keine Eingänge mehr verbunden sind und Verweise beibehalten werden, kann kein Gain mehr auf irgendetwas angewendet werden, sodass er sicher gesammelt werden kann.
3. Ein Knoten, der seine Eingabe transformiert, aber eine sogenannte Nachlaufzeit hat—das bedeutet, dass er eine Ausgabe für einige Zeit erzeugen wird, selbst nachdem seine Eingänge getrennt oder inaktiv sind (Null-Kanäle erzeugend). Ein Prozessor, der einen solchen Knoten implementiert, sollte true von der process-Methode für die Dauer der Nachlaufzeit zurückgeben, beginnend, sobald Eingänge gefunden werden, die Null-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 emittieren und für den Rest seines Lebens Stille ausgeben.

In diesem Beispiel erstellen wir einen AudioWorkletProcessor, der weißes Rauschen an seinen ersten Ausgang ausgibt. Der Gain kann durch den Parameter customGain 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.

• Die Web Audio API verwenden