Refactor/communication between audio and js thread

.gitignore

@@ -98,4 +98,5 @@ packages/react-native-audio-api/common/cpp/audioapi/external/**/*.a
 packages/react-native-audio-api/common/cpp/audioapi/external/*.xcframework
 packages/react-native-audio-api/common/cpp/audioapi/external/ffmpeg_ios/
 
+# Clangd cache
 .cache

apps/common-app/src/examples/Streaming/Streaming.tsx

@@ -30,11 +30,8 @@ const Streaming: FC = () => {
       console.error('StreamerNode is already initialized');
       return;
     }
-    streamerRef.current = aCtxRef.current.createStreamer();
+    streamerRef.current = aCtxRef.current.createStreamer('https://liveradio.timesa.pl/2980-1.aac/playlist.m3u8');
 
-    streamerRef.current.initialize(
-      'https://liveradio.timesa.pl/2980-1.aac/playlist.m3u8'
-    );
     streamerRef.current.connect(gainRef.current);
     gainRef.current.connect(aCtxRef.current.destination);
     streamerRef.current.start(aCtxRef.current.currentTime);

apps/fabric-example/ios/FabricExample.xcodeproj/project.pbxproj

@@ -191,14 +191,10 @@
 			inputFileListPaths = (
 				"${PODS_ROOT}/Target Support Files/Pods-FabricExample/Pods-FabricExample-frameworks-${CONFIGURATION}-input-files.xcfilelist",
 			);
-			inputPaths = (
-			);
 			name = "[CP] Embed Pods Frameworks";
 			outputFileListPaths = (
 				"${PODS_ROOT}/Target Support Files/Pods-FabricExample/Pods-FabricExample-frameworks-${CONFIGURATION}-output-files.xcfilelist",
 			);
-			outputPaths = (
-			);
 			runOnlyForDeploymentPostprocessing = 0;
 			shellPath = /bin/sh;
 			shellScript = "\"${PODS_ROOT}/Target Support Files/Pods-FabricExample/Pods-FabricExample-frameworks.sh\"\n";
@@ -234,14 +230,10 @@
 			inputFileListPaths = (
 				"${PODS_ROOT}/Target Support Files/Pods-FabricExample/Pods-FabricExample-resources-${CONFIGURATION}-input-files.xcfilelist",
 			);
-			inputPaths = (
-			);
 			name = "[CP] Copy Pods Resources";
 			outputFileListPaths = (
 				"${PODS_ROOT}/Target Support Files/Pods-FabricExample/Pods-FabricExample-resources-${CONFIGURATION}-output-files.xcfilelist",
 			);
-			outputPaths = (
-			);
 			runOnlyForDeploymentPostprocessing = 0;
 			shellPath = /bin/sh;
 			shellScript = "\"${PODS_ROOT}/Target Support Files/Pods-FabricExample/Pods-FabricExample-resources.sh\"\n";
@@ -424,7 +416,10 @@
 					"-DFOLLY_HAVE_CLOCK_GETTIME=1",
 					"-DRCT_REMOVE_LEGACY_ARCH=1",
 				);
-				OTHER_LDFLAGS = "$(inherited)  ";
+				OTHER_LDFLAGS = (
+					"$(inherited)",
+					" ",
+				);
 				REACT_NATIVE_PATH = "${PODS_ROOT}/../../../../node_modules/react-native";
 				SDKROOT = iphoneos;
 				SWIFT_ACTIVE_COMPILATION_CONDITIONS = "$(inherited) DEBUG";
@@ -512,7 +507,10 @@
 					"-DFOLLY_HAVE_CLOCK_GETTIME=1",
 					"-DRCT_REMOVE_LEGACY_ARCH=1",
 				);
-				OTHER_LDFLAGS = "$(inherited)  ";
+				OTHER_LDFLAGS = (
+					"$(inherited)",
+					" ",
+				);
 				REACT_NATIVE_PATH = "${PODS_ROOT}/../../../../node_modules/react-native";
 				SDKROOT = iphoneos;
 				SWIFT_ENABLE_EXPLICIT_MODULES = NO;

apps/fabric-example/ios/Podfile.lock

@@ -2553,7 +2553,7 @@ SPEC CHECKSUMS:
   React-microtasksnativemodule: d1956f0eec54c619b63a379520fb4c618a55ccb9
   react-native-background-timer: 4638ae3bee00320753647900b21260b10587b6f7
   react-native-safe-area-context: ae7587b95fb580d1800c5b0b2a7bd48c2868e67a
-  react-native-skia: 268f7c9942c00dcecc58fae9758b7833e3d246f2
+  react-native-skia: 5f68d3c3749bfb4f726e408410b8be5999392cd9
   React-NativeModulesApple: 5ba0903927f6b8d335a091700e9fda143980f819
   React-networking: 3a4b7f9ed2b2d1c0441beacb79674323a24bcca6
   React-oscompat: ff26abf0ae3e3fdbe47b44224571e3fc7226a573

ghdocs/audio-node.md

@@ -0,0 +1,280 @@
+# How to create new AudioNode
+
+In this docs we present recommended patterns for creating new AudioNodes.
+
+## Layers
+
+Ususally, each AudioNode has three layers:
+
+- Core (C++)
+
+  Class implementing core audio processing logic. Should be implemented in highly performant manner using internal data structures (if possible).
+
+```cpp
+class GainNode : public AudioNode {
+ public:
+  explicit GainNode(const std::shared_ptr<BaseAudioContext> &context, const GainOptions &options);
+
+  [[nodiscard]] std::shared_ptr<AudioParam> getGainParam() const;
+
+ protected:
+  std::shared_ptr<AudioBuffer> processNode(
+      const std::shared_ptr<AudioBuffer> &processingBuffer,
+      int framesToProcess) override;
+
+ private:
+  std::shared_ptr<AudioParam> gainParam_;
+};
+```
+
+- Host Object (HO)
+
+  Interop class between C++ and JS, implemented on C++ side. HO is returned from C++ to JS from BaseAudioContext factory methods. JS has its own interfaces that works as a counterpart of C++ HO. There is no strong typing mechanism between C++ and JS. Implementation is based on the alignment between C++ HO and JS interface.
+
+```cpp
+class GainNodeHostObject : public AudioNodeHostObject {
+ public:
+  explicit GainNodeHostObject(
+      const std::shared_ptr<BaseAudioContext> &context,
+      const GainOptions &options);
+
+  JSI_PROPERTY_GETTER_DECL(gain);
+
+ private:
+  std::shared_ptr<AudioParamHostObject> gainParam_;
+};
+```
+```ts
+export interface IGainNode extends IAudioNode {
+  readonly gain: IAudioParam;
+}
+```
+
+- Typescript (JS)
+
+  Elegant typescript wrapper around JS HO interface.
+
+```ts
+class GainNode extends AudioNode {
+  readonly gain: AudioParam;
+
+  constructor(context: BaseAudioContext, options?: TGainOptions) {
+    const gainNode: IGainNode = context.context.createGain(options || {}); // context.context is C++ HO
+    super(context, gainNode);
+    this.gain = new AudioParam(gainNode.gain, context);
+  }
+}
+```
+
+## Core (C++) implementation
+
+Each AudioNode should implement one virtual method:
+```cpp
+std::shared_ptr<AudioBuffer> processNode(
+      const std::shared_ptr<AudioBuffer> &processingBuffer,
+      int framesToProcess)
+```
+
+It is responsible for AudioNode's processing logic. It gets input buffer as argument - `processingBus` and should return processed buffer.
+
+```cpp
+std::shared_ptr<AudioBuffer> GainNode::processNode(
+    const std::shared_ptr<AudioBuffer> &processingBuffer,
+    int framesToProcess) {
+  std::shared_ptr<BaseAudioContext> context = context_.lock();
+  if (context == nullptr)
+    return processingBuffer;
+  double time = context->getCurrentTime();
+  auto gainParamValues = gainParam_->processARateParam(framesToProcess, time);
+  auto gainValues = gainParamValues->getChannel(0);
+
+  for (size_t i = 0; i < processingBuffer->getNumberOfChannels(); i++) {
+    auto channel = processingBuffer->getChannel(i);
+    channel->multiply(*gainValues, framesToProcess);
+  }
+
+  return processingBuffer;
+}
+```
+
+There are a few rules that should be followed when implementing C++ AudioNode core.
+
+- **Thread safety**: Each AudioNode should be created in thread safe manner.
+
+- **Heap allocations**: Heap allocations are not allowed on the Audio Thread, so all necessary data should be allocated in constructor, or pre-allocated on other thread and passed to AudioNode.
+
+- **Destructions** No destructions are allowed to happen on the Audio Thread. AudioNode destruction are handled by already active AudioDestructor. If you need to perform some cleanup, you have to delegate it to AudioDestructor.
+
+- **No locks on Audio Thread**: Locks are not allowed on the Audio Thread. Audio procssing have to be highly performant and efficient.
+
+- **No syscalls** Syscalls are not allowed on the Audio Thread, so if you need to perform some work that requires syscalls, you have to delegate it to other thread.
+
+## HostObject implementation
+
+We can distinguish three types of AudioNode's JS methods:
+
+1. **getter**
+
+```ts
+const fftSize = analyserNode.fftSize;
+```
+
+C++ counter part is `JSI_PROPERTY_GETTER`. It just returns some value.
+
+```cpp
+JSI_PROPERTY_GETTER_IMPL(AnalyserNodeHostObject, fftSize) {
+  return {fftSize_};
+}
+```
+
+2. **setter**
+
+C++ counterpart is `JSI_PROPERTY_SETTER`. It just receives some value.
+
+```ts
+analyserNode.fftSize = 2048;
+```
+
+```cpp
+JSI_PROPERTY_SETTER_IMPL(AnalyserNodeHostObject, minDecibels) {
+  auto analyserNode = std::static_pointer_cast<AnalyserNode>(node_);
+  auto minDecibels = static_cast<float>(value.getNumber());
+  auto event = [analyserNode, minDecibels](BaseAudioContext&) {
+    analyserNode->setMinDecibels(minDecibels);
+  };
+    analyserNode->scheduleAudioEvent(std::move(event));
+    minDecibels_ = minDecibels;
+}
+```
+
+
+3. **function**
+
+C++ counterpart is `JSI_HOST_FUNCTION`. It is a common function that can receive arguments and return some value.
+
+```ts
+const fftOutput = new Uint8Array(analyser.frequencyBinCount);
+analyserNode.getByteFrequencyData(fftOutput);
+```
+
+```cpp
+JSI_HOST_FUNCTION_IMPL(AnalyserNodeHostObject, getByteFrequencyData) {
+  auto arrayBuffer =
+      args[0].getObject(runtime).getPropertyAsObject(runtime, "buffer").getArrayBuffer(runtime);
+  auto data = arrayBuffer.data(runtime);
+  auto length = static_cast<int>(arrayBuffer.size(runtime));
+
+  auto analyserNode = std::static_pointer_cast<AnalyserNode>(node_);
+  analyserNode->getByteFrequencyData(data, length);
+
+  return jsi::Value::undefined();
+}
+```
+
+All methods should be registerd in C++ HO constructor:
+
+```cpp
+AnalyserNodeHostObject::AnalyserNodeHostObject(const std::shared_ptr<BaseAudioContext>& context, const AnalyserOptions &options)
+    : /* ... */ {
+  addGetters(JSI_EXPORT_PROPERTY_GETTER(AnalyserNodeHostObject, fftSize));
+  addSetters(JSI_EXPORT_PROPERTY_SETTER(AnalyserNodeHostObject, fftSize));
+  addFunctions(JSI_EXPORT_FUNCTION(AnalyserNodeHostObject, getByteFrequencyData),);
+}
+```
+
+#### Shadow state (C++)
+
+Shadow state is a mechanism introduced in order to make communication between JS and the Audio Thread lock-free. AudioNodeHostObject stores the set of properties, which are  modified only by JS thread (the same set C++ AudioNode has). Everytime we want to access some property from JS, we can just return property from shadow state, when we modify some property we have to update shadow state and schedule update event on Audio Event Loop (SPSC). By following that manner we can skip accessing AudioNode state, that is also accessed by the Audio Thread - no need to lock or use atomic variables.
+
+```cpp
+class OscillatorNodeHostObject : public AudioScheduledSourceNodeHostObject {
+ public:
+  /* ... */
+
+  JSI_PROPERTY_GETTER_DECL(type);
+  JSI_PROPERTY_SETTER_DECL(type);
+
+ private:
+  /* ... */
+  OscillatorType type_;
+};
+```
+
+```cpp
+JSI_PROPERTY_GETTER_IMPL(OscillatorNodeHostObject, type) {
+  return jsi::String::createFromUtf8(runtime, js_enum_parser::oscillatorTypeToString(type_));
+}
+
+JSI_PROPERTY_SETTER_IMPL(OscillatorNodeHostObject, type) {
+  auto oscillatorNode = std::static_pointer_cast<OscillatorNode>(node_);
+  auto type = js_enum_parser::oscillatorTypeFromString(value.asString(runtime).utf8(runtime));
+
+  auto event = [oscillatorNode, type](BaseAudioContext &) {
+    oscillatorNode->setType(type);
+  };
+  type_ = type;
+
+  oscillatorNode->scheduleAudioEvent(std::move(event));
+}
+```
+
+#### Communication between JS Thread and Audio Thread
+
+**getters** and **setters**
+
+1. Property is primitive and is not modified by the Audio Thread.
+
+   Shadow state design pattern should be followed.
+
+2. Property is not primitive and is not modified by the Audio Thread.
+
+  It should be stored in TS layer and copied to AudioNode
+
+3. Property is primitive and can be modified by the Audio Thread.
+
+  In C++ core it should be an atomic variable that allows to access it in thread-safe manner from both threads.
+
+```cpp
+class AudioParam {
+public:
+  /* ... */
+
+  [[nodiscard]] inline float getValue() const noexcept {
+    return value_.load(std::memory_order_relaxed);
+  }
+
+  inline void setValue(float value) {
+    value_.store(std::clamp(value, minValue_, maxValue_), std::memory_order_release);
+  }
+
+  /* ... */
+
+private:
+  std::atomic<float> value_;
+
+  /* ... */
+};
+```
+
+```cpp
+JSI_PROPERTY_GETTER_IMPL(AudioParamHostObject, value) {
+  return {param_->getValue()};
+}
+
+JSI_PROPERTY_SETTER_IMPL(AudioParamHostObject, value) {
+    auto event = [param = param_, value = static_cast<float>(value.getNumber())](BaseAudioContext &) {
+        param->setValue(value);
+    };
+
+    param_->scheduleAudioEvent(std::move(event));
+}
+```
+
+4. Property is not primitive and can be modified by the Audio Thread.
+  In C++ core triple buffer pattern should be followed. It allows to have one copy of property for reader, one for writer and one for pending update. On each update we just swap pending update with writer, and on each read we just read from reader. In that manner we can skip locks and just operate on atomic indices.
+
+  Check AnalyserNode implementation for example or this [article](https://medium.com/@sgn00/triple-buffer-lock-free-concurrency-primitive-611848627a1e) for more details.
+
+**functions**
+
+Function's should follow the same thread-safe lock-free patterns as getters/setters. Set of properties read/write by the function determines mechanisms that should be used in implementation.

packages/audiodocs/docs/analysis/analyser-node.mdx

@@ -51,15 +51,8 @@ It inherits all properties from [`AudioNode`](/docs/core/audio-node#properties).
 | `minDecibels` | `number` | Float value representing the minimum value for the range of results from [`getByteFrequencyData()`](/docs/analysis/analyser-node#getbytefrequencydata). |
 | `maxDecibels` | `number` | Float value representing the maximum value for the range of results from [`getByteFrequencyData()`](/docs/analysis/analyser-node#getbytefrequencydata). |
 | `smoothingTimeConstant` | `number` | Float value representing averaging constant with the last analysis frame. In general the higher value the smoother is the transition between values over time. |
-| `window` | [`WindowType`](/docs/types/window-type) | Enumerated value that specifies the type of window function applied when extracting frequency data. |
 | `frequencyBinCount` | `number` | Integer value representing amount of the data obtained in frequency domain, half of the `fftSize` property. | <ReadOnly /> |
 
-:::caution
-
-On `Web`, the value of `window` is permanently `'blackman'`, and it cannot be set like on the `Android` or `iOS`.
-
-:::
-
 ## Methods
 
 It inherits all methods from [`AudioNode`](/docs/core/audio-node#methods).
@@ -128,6 +121,3 @@ Each value in the array is within the range 0 to 255, where value of 127 indicat
 - Nominal range is 0 to 1.
 - 0 means no averaging, 1 means "overlap the previous and current buffer quite a lot while computing the value".
 - Throws `IndexSizeError` if set value is outside the allowed range.
-
-#### `window`
-- Default value is `'blackman'`

packages/audiodocs/docs/core/base-audio-context.mdx

@@ -172,6 +172,10 @@ Creates [`StereoPannerNode`](/docs/effects/stereo-panner-node).
 
 Creates [`StreamerNode`](/docs/sources/streamer-node).
 
+| Parameter | Type | Description |
+| :---: | :---: | :---- |
+| `options` <Optional /> | [`StreamerOptions`](/docs/sources/streamer-node#streameroptions) | Streamer options to initialize. |
+
 #### Returns `StreamerNode`.
 
 ### `createWaveShaper`