feat: audio node options in ctor #807

mdydek · 2025-11-13T17:13:29Z

Closes RNAA-297, RNAA-293

⚠️ Breaking changes ⚠️

Introduced changes

LIST:

Checklist

Copilot

Pull Request Overview

This PR adds support for passing audio node options (channel configuration) in the GainNode constructor, aligning with the Web Audio API specification. The implementation spans TypeScript and C++ layers, introducing new type definitions and updating constructors to accept optional configuration parameters.

Introduces TAudioNodeOptions and TGainOptions types for channel configuration
Updates GainNode constructor to accept optional configuration parameters
Adds C++ parsing logic for audio node options from JavaScript

Reviewed Changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/react-native-audio-api/src/types.ts	Adds new type definitions `TAudioNodeOptions` and `TGainOptions` for audio node configuration
packages/react-native-audio-api/src/interfaces.ts	Updates `createGain` method signature in `IBaseAudioContext` to accept `TGainOptions` parameter
packages/react-native-audio-api/src/defaults.ts	Defines default values for audio node and gain options
packages/react-native-audio-api/src/core/GainNode.ts	Refactors constructor to accept and merge options with defaults before creating the native node
packages/react-native-audio-api/src/core/BaseAudioContext.ts	Simplifies `createGain` method to delegate parameter handling to GainNode constructor
packages/react-native-audio-api/common/cpp/audioapi/core/effects/GainNode.h	Updates constructor signature to accept `GainOptions` parameter
packages/react-native-audio-api/common/cpp/audioapi/core/effects/GainNode.cpp	Updates constructor implementation to use options for initializing gain parameter and audio node properties
packages/react-native-audio-api/common/cpp/audioapi/core/BaseAudioContext.h	Updates `createGain` method signature to accept `GainOptions` parameter
packages/react-native-audio-api/common/cpp/audioapi/core/BaseAudioContext.cpp	Updates `createGain` implementation to pass options to GainNode constructor
packages/react-native-audio-api/common/cpp/audioapi/core/AudioNode.h	Updates constructor to accept optional `AudioNodeOptions` parameter
packages/react-native-audio-api/common/cpp/audioapi/core/AudioNode.cpp	Implements conditional initialization of channel properties from options
packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/NodeOptionsParser.h	Adds parsing functions to convert JavaScript option objects to C++ structs
packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/NodeOptions.h	Defines C++ structs for `AudioNodeOptions` and `GainOptions`
packages/react-native-audio-api/common/cpp/audioapi/HostObjects/BaseAudioContextHostObject.cpp	Updates JSI binding to parse options from JavaScript before calling `createGain`

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/react-native-audio-api/src/interfaces.ts

packages/react-native-audio-api/common/cpp/audioapi/HostObjects/BaseAudioContextHostObject.cpp

packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/NodeOptionsParser.h

maciejmakowski2003

looks promising, @michalsek wdyt?

poneciak57 · 2025-12-05T10:38:52Z

packages/react-native-audio-api/common/cpp/audioapi/core/effects/IIRFilterNode.cpp

+    : AudioNode(context, options), feedforward_(options.feedforward), feedback_(options.feedback) {
  isInitialized_ = true;


here you copy possibly large vector

poneciak57 · 2025-12-05T10:57:48Z

packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/NodeOptions.h

+struct AudioNodeOptions {
+  int channelCount = 2;
+  ChannelCountMode channelCountMode = ChannelCountMode::MAX;
+  ChannelInterpretation channelInterpretation = ChannelInterpretation::SPEAKERS;
+};
+
+struct GainOptions : AudioNodeOptions {
+  float gain = 1.0f;
+};


That is not a change per se but just a quick reminder.
Remember when you have method

void method(AudioNodeOptions opts) { // } // and you call it with type extending the node options like so GainOptions opts; method(opts);

This type is sliced so it is copied here and it copies only part of AudioNodeOptions. Everything is fine with it but it is worth noting as it has some limitations and in future someone might not know this. So like leave some explanation here on how it works or in AudioNode.

poneciak57 · 2025-12-05T11:00:19Z

packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/NodeOptions.h

+#include <audioapi/core/types/OscillatorType.h>
+
+namespace audioapi {
+struct AudioNodeOptions {


you can make all types extend some empty base like

struct BaseOption {}

it does not cost anything compilers optimize this and might be helpfull in the future if all options types can be virtualized

I don't like writing features "for the future". Adding some complexity because "maybe someday something will change and it will be helpful" for me should not be done.

poneciak57 · 2025-12-05T11:02:58Z

packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioBufferBaseSourceNode.h

-  explicit AudioBufferBaseSourceNode(BaseAudioContext *context, bool pitchCorrection);
+  explicit AudioBufferBaseSourceNode(
+      BaseAudioContext *context,
+      BaseAudioBufferSourceOptions options);


here type gets sliced as explained before maybe const & ?

poneciak57 · 2025-12-05T11:11:42Z

packages/react-native-audio-api/src/core/AnalyserNode.ts

+    if (!AnalyserNode.allowedFFTSize.includes(finalOptions.fftSize!)) {
+      throw new IndexSizeError(
+        `fftSize must be one of the following values: ${AnalyserNode.allowedFFTSize.join(
+          ', '
+        )}`
+      );
+    }
+    const analyserNode: IAnalyserNode =
+      context.context.createAnalyser(finalOptions);


when you have base option interface might be a good idea to add some virtual method validate so option type would be responsible for its validation that might be helpfull if you need to validate like a base type or something and is a good principle

poneciak57 · 2025-12-05T11:12:28Z

packages/react-native-audio-api/src/core/ConvolverNode.ts

+    if (finalOptions.buffer) {
+      const numberOfChannels = finalOptions.buffer.numberOfChannels;
+      if (
+        numberOfChannels !== 1 &&
+        numberOfChannels !== 2 &&
+        numberOfChannels !== 4
+      ) {
+        throw new NotSupportedError(
+          `The number of channels provided (${numberOfChannels}) in impulse response for ConvolverNode buffer must be 1 or 2 or 4.`
+        );
+      }
+    }
+    const convolverNode: IConvolverNode =
+      context.context.createConvolver(finalOptions);


same here validation should be implemented for option type

poneciak57 · 2025-12-05T11:12:43Z

packages/react-native-audio-api/src/core/OscillatorNode.ts

+    const finalOptions: TOscillatorOptions = {
+      ...OscillatorOptions,
+      ...options,
+    };
+
+    if (finalOptions.type === 'custom' && !finalOptions.periodicWave) {
+      throw new InvalidStateError(
+        "'type' cannot be set to 'custom' without providing a 'periodicWave'."
+      );
+    }
+
+    if (finalOptions.periodicWave) {
+      finalOptions.type = 'custom';
+    }
+
+    const node = context.context.createOscillator(finalOptions);


same here validation should be implemented for option type

poneciak57 · 2025-12-05T11:12:53Z

packages/react-native-audio-api/src/core/PeriodicWave.ts

+): TPeriodicWaveOptions {
+  let real: Float32Array | undefined;
+  let imag: Float32Array | undefined;
+  if (!options || (!options.real && !options.imag)) {
+    // default to a sine wave
+    if (sampleRate < 24000) {
+      real = new Float32Array(2048);
+      imag = new Float32Array(2048);
+    } else if (sampleRate < 88200) {
+      real = new Float32Array(4096);
+      imag = new Float32Array(4096);
+    } else {
+      real = new Float32Array(16384);
+      imag = new Float32Array(16384);
+    }
+    imag[1] = 1;
+  } else {


same here validation should be implemented for option type

poneciak57

Great job overall but i see some possible improvements

feat: gain impl

d74dee6

mdydek requested a review from Copilot November 13, 2025 17:13

Copilot started reviewing on behalf of mdydek November 13, 2025 17:14 View session

Copilot finished reviewing on behalf of mdydek November 13, 2025 17:17

Copilot AI reviewed Nov 13, 2025

View reviewed changes

feat: better consistency

62ae75f

maciejmakowski2003 reviewed Nov 14, 2025

View reviewed changes

mdydek added 20 commits November 14, 2025 12:49

docs: docs proposition

5790ce5

feat: stereo panner options

4fd5487

feat: added web

5d7cc69

feat: convolver options

add1958

test: tests

022683b

feat: constant source options

0a539d1

Merge branch 'main' into feat/audio-node-options-in-ctor

a90f428

feat: web for convolver

a052c45

feat: periodic wave

a47447b

feat: analyser node

1aa6443

feat: biquad filter

3b0b1b7

feat: oscillator

1dcdaa6

feat: mobile audio buffer sources

1f62ba8

feat: streamer node options

f80292a

feat: recorder adapter

67df87d

feat: worklets

617188a

feat: audiobuffer

0a6f8d8

feat: audiobuffer on web

f074c12

docs: documentation for new constructors

4617720

feat: absn on web

002b5c3

mdydek marked this pull request as ready for review December 3, 2025 10:03

mdydek added 2 commits December 3, 2025 11:33

Merge branch 'main' into feat/audio-node-options-in-ctor

25c9327

feat: delay node

829c019

mdydek added 7 commits December 3, 2025 12:14

feat: iirfilter

2c6a512

test: test fix

e487709

feat: better absn for web

bf1ad3d

feat: reverted pitch correction option in factory method for absn

5632d68

feat: slowly removing shared ptr in options

97eb239

feat: removed options as shared ptr

7a99505

test: test fix

b19e1fd

poneciak57 requested changes Dec 5, 2025

View reviewed changes

feat: changes after review

e12c3da

		: AudioNode(context, options), feedforward_(options.feedforward), feedback_(options.feedback) {
		isInitialized_ = true;

Uh oh!

feat: audio node options in ctor #807

Are you sure you want to change the base?

feat: audio node options in ctor #807

Uh oh!

Conversation

mdydek commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ Breaking changes ⚠️

Introduced changes

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

maciejmakowski2003 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

poneciak57 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mdydek commented Nov 13, 2025 •

edited

Loading