react-native-audio-api 0.13.2 → 0.13.4

package/RNAudioAPI.podspec

@@ -18,7 +18,7 @@ worklets_preprocessor_flag = worklets_enabled ? '-DRN_AUDIO_API_ENABLE_WORKLETS=
 ffmpeg_flag = $RN_AUDIO_API_FFMPEG_DISABLED ? '-DRN_AUDIO_API_FFMPEG_DISABLED=1' : ''
 static_external_libs_flag = $RN_AUDIO_API_STATIC_EXTERNAL_LIBS_DISABLED ? '-DRN_AUDIO_API_STATIC_EXTERNAL_LIBS_DISABLED=1 -DMA_NO_LIBOPUS=1 -DMA_NO_LIBVORBIS=1' : ''
 skip_ffmpeg_argument = $RN_AUDIO_API_FFMPEG_DISABLED ? 'skipffmpeg' : ''
-prepare_command_prefix = $RN_AUDIO_API_STATIC_EXTERNAL_LIBS_DISABLED ? 'DISABLE_AUDIOAPI_STATIC_EXTERNAL_LIBS=1 ' : ''
+download_script_env_prefix = $RN_AUDIO_API_STATIC_EXTERNAL_LIBS_DISABLED ? 'DISABLE_AUDIOAPI_STATIC_EXTERNAL_LIBS=1 ' : ''
 
 Pod::Spec.new do |s|
   s.name         = "RNAudioAPI"
@@ -67,18 +67,60 @@ Pod::Spec.new do |s|
 
   s.prepare_command = <<-CMD
     chmod +x scripts/download-prebuilt-binaries.sh
-    #{prepare_command_prefix}scripts/download-prebuilt-binaries.sh ios #{skip_ffmpeg_argument}
+    #{download_script_env_prefix}scripts/download-prebuilt-binaries.sh ios #{skip_ffmpeg_argument}
   CMD
 
   external_dir_relative = "common/cpp/audioapi/external"
   lib_dir = "$(PODS_ROOT)/#{$audio_api_config[:dynamic_frameworks_audio_api_dir]}/#{external_dir_relative}/$(PLATFORM_NAME)"
+  ffmpeg_dir = "$(PODS_ROOT)/#{$audio_api_config[:dynamic_frameworks_audio_api_dir]}/#{external_dir_relative}/ffmpeg_ios"
+
+  ffmpeg_framework_names =  %w[libavcodec libavformat libavutil libswresample]
+  static_external_libs_names = %w[libopusfile libopus libogg libvorbis libvorbisenc libvorbisfile]
+
+  # `prepare_command` hydrates binaries on a fresh `pod install` so CocoaPods can
+  # register all vendored `.xcframework`s in `[CP] Copy XCFrameworks`. When `Pods/`
+  # is restored from cache while `node_modules/` is reinstalled, `prepare_command`
+  # does not re-run — the build-time phase below re-hydrates on every build.
+  #
+  # It must run at `:before_headers` so it lands ahead of CocoaPods' own
+  # `[CP] Copy XCFrameworks` phase, which consumes the FFmpeg xcframeworks. If it
+  # ran later (e.g. `:before_compile`, which is after Copy XCFrameworks), Xcode
+  # would reject the build when the xcframeworks are missing before we download.
+  #
+  # `output_files` declares everything the linker (`-force_load` static libs in
+  # `s.xcconfig`) and Copy XCFrameworks (FFmpeg) consume, so Xcode's build graph
+  # knows this phase produces them.
+  unless $RN_AUDIO_API_STATIC_EXTERNAL_LIBS_DISABLED && $RN_AUDIO_API_FFMPEG_DISABLED
+    download_output_files = []
+
+    unless $RN_AUDIO_API_STATIC_EXTERNAL_LIBS_DISABLED
+      static_external_libs_names.each do |lib|
+        download_output_files << "#{lib_dir}/#{lib}.a"
+      end
+    end
+
+    unless $RN_AUDIO_API_FFMPEG_DISABLED
+      ffmpeg_framework_names.each do |framework|
+        download_output_files << "#{ffmpeg_dir}/#{framework}.xcframework"
+      end
+    end
 
-  s.ios.vendored_frameworks = $RN_AUDIO_API_FFMPEG_DISABLED ? [] : [
-    'common/cpp/audioapi/external/ffmpeg_ios/libavcodec.xcframework',
-    'common/cpp/audioapi/external/ffmpeg_ios/libavformat.xcframework',
-    'common/cpp/audioapi/external/ffmpeg_ios/libavutil.xcframework',
-    'common/cpp/audioapi/external/ffmpeg_ios/libswresample.xcframework'
-  ]
+    s.script_phase = {
+      :name => 'Download RNAudioAPI prebuilt binaries',
+      :execution_position => :before_headers,
+      :always_out_of_date => '1',
+      :output_files => download_output_files,
+      :script => <<-SCRIPT
+        cd "$PODS_TARGET_SRCROOT"
+        chmod +x scripts/download-prebuilt-binaries.sh
+        #{download_script_env_prefix}scripts/download-prebuilt-binaries.sh ios #{skip_ffmpeg_argument}
+      SCRIPT
+    }
+  end
+
+  s.ios.vendored_frameworks = $RN_AUDIO_API_FFMPEG_DISABLED ? [] : ffmpeg_framework_names.map { |framework|
+    "common/cpp/audioapi/external/ffmpeg_ios/#{framework}.xcframework"
+  }
 
   s.pod_target_xcconfig = {
     "USE_HEADERMAP" => "YES",
@@ -133,14 +175,9 @@ Pod::Spec.new do |s|
     'OTHER_LDFLAGS' => %W[
       $(inherited)
     ]
-    .concat($RN_AUDIO_API_STATIC_EXTERNAL_LIBS_DISABLED ? [] : %W[
-      -force_load #{lib_dir}/libopusfile.a
-      -force_load #{lib_dir}/libopus.a
-      -force_load #{lib_dir}/libogg.a
-      -force_load #{lib_dir}/libvorbis.a
-      -force_load #{lib_dir}/libvorbisenc.a
-      -force_load #{lib_dir}/libvorbisfile.a
-    ])
+    .concat($RN_AUDIO_API_STATIC_EXTERNAL_LIBS_DISABLED ? [] : static_external_libs_names.flat_map { |lib|
+      ['-force_load', "#{lib_dir}/#{lib}.a"]
+    })
     .join(" "),
   }
   # Use install_modules_dependencies helper to install the dependencies if React Native version >=0.71.0.

package/android/src/main/java/com/swmansion/audioapi/system/AudioEvent.kt

@@ -25,4 +25,5 @@ enum class AudioEvent {
   POSITION_CHANGED,
   BUFFER_ENDED,
   RECORDER_ERROR,
+  BUFFERING_STATE_CHANGE,
 }

package/common/cpp/audioapi/HostObjects/sources/AudioFileSourceNodeHostObject.cpp

@@ -33,6 +33,7 @@ AudioFileSourceNodeHostObject::AudioFileSourceNodeHostObject(
       JSI_EXPORT_PROPERTY_GETTER(AudioFileSourceNodeHostObject, routedThroughMediaElement));
   addSetters(
       JSI_EXPORT_PROPERTY_SETTER(AudioFileSourceNodeHostObject, onPositionChanged),
+      JSI_EXPORT_PROPERTY_SETTER(AudioFileSourceNodeHostObject, onBufferingStateChanged),
       JSI_EXPORT_PROPERTY_SETTER(AudioFileSourceNodeHostObject, volume),
       JSI_EXPORT_PROPERTY_SETTER(AudioFileSourceNodeHostObject, playbackRate),
       JSI_EXPORT_PROPERTY_SETTER(AudioFileSourceNodeHostObject, preservesPitch),
@@ -45,8 +46,8 @@ AudioFileSourceNodeHostObject::AudioFileSourceNodeHostObject(
 }
 
 AudioFileSourceNodeHostObject::~AudioFileSourceNodeHostObject() {
-  auto node = std::static_pointer_cast<AudioFileSourceNode>(node_);
-  node->assignOnPositionChangedCallbackId(0);
+  getAudioFileSourceNode()->assignOnPositionChangedCallbackId(0);
+  getAudioFileSourceNode()->assignOnBufferingStateChangeCallbackId(0);
 }
 
 JSI_PROPERTY_GETTER_IMPL(AudioFileSourceNodeHostObject, volume) {
@@ -149,4 +150,9 @@ JSI_PROPERTY_SETTER_IMPL(AudioFileSourceNodeHostObject, onPositionChanged) {
       std::stoull(value.getString(runtime).utf8(runtime)));
 }
 
+JSI_PROPERTY_SETTER_IMPL(AudioFileSourceNodeHostObject, onBufferingStateChanged) {
+  getAudioFileSourceNode()->assignOnBufferingStateChangeCallbackId(
+      std::stoull(value.getString(runtime).utf8(runtime)));
+}
+
 } // namespace audioapi

package/common/cpp/audioapi/HostObjects/sources/AudioFileSourceNodeHostObject.h

@@ -31,6 +31,7 @@ class AudioFileSourceNodeHostObject : public AudioScheduledSourceNodeHostObject
   JSI_PROPERTY_SETTER_DECL(preservesPitch);
   JSI_PROPERTY_SETTER_DECL(loop);
   JSI_PROPERTY_SETTER_DECL(onPositionChanged);
+  JSI_PROPERTY_SETTER_DECL(onBufferingStateChanged);
 
   JSI_HOST_FUNCTION_DECL(pause);
   JSI_HOST_FUNCTION_DECL(seekToStart);

package/common/cpp/audioapi/HostObjects/utils/JsEnumParser.cpp

@@ -148,6 +148,8 @@ AudioEvent audioEventFromString(const std::string &event) {
     return AudioEvent::BUFFER_ENDED;
   if (event == "recorderError")
     return AudioEvent::RECORDER_ERROR;
+  if (event == "bufferingStateChanged")
+    return AudioEvent::BUFFERING_STATE_CHANGE;
 
   throw std::invalid_argument("Unknown audio event: " + event);
 }

package/common/cpp/audioapi/core/sources/AudioFileSourceNode.cpp

@@ -37,7 +37,10 @@ AudioFileSourceNode::AudioFileSourceNode(
       positionChanged_(
           context->getAudioEventHandlerRegistry(),
           static_cast<int>(context->getSampleRate() * ON_POSITION_CHANGED_INTERVAL),
-          true) {
+          true),
+      bufferingStateDispatcher_(
+          context->getAudioEventHandlerRegistry(),
+          static_cast<int>(context->getSampleRate() * ON_BUFFERING_STATE_DEBOUNCE_INTERVAL)) {
   decoderState_->playbackRate.store(options.playbackRate, std::memory_order_release);
   decoderState_->preservesPitch.store(options.preservesPitch, std::memory_order_release);
 
@@ -90,6 +93,10 @@ void AudioFileSourceNode::assignOnPositionChangedCallbackId(uint64_t callbackId)
   positionChanged_.assignCallbackId(callbackId);
 }
 
+void AudioFileSourceNode::assignOnBufferingStateChangeCallbackId(uint64_t callbackId) {
+  bufferingStateDispatcher_.assignCallbackId(callbackId);
+}
+
 bool AudioFileSourceNode::initDecoder(
     const std::shared_ptr<BaseAudioContext> &context,
     AudioFileSourceOptions &options) {
@@ -433,6 +440,9 @@ bool AudioFileSourceNode::isCurrentMediaElementSource(uint64_t bindingId) const
 
 void AudioFileSourceNode::pause() {
   filePaused_ = true;
+  // A deliberate pause is not a stall — don't leave a stale "buffering" state
+  // observed by JS once processDecodedOutput() stops being called below.
+  bufferingStateDispatcher_.advance(/* hasData */ true, 0);
 }
 
 void AudioFileSourceNode::disable() {
@@ -440,6 +450,7 @@ void AudioFileSourceNode::disable() {
   filePaused_ = false;
   endOfStreamStopPending_ = false;
   endOfStreamDrainPending_ = false;
+  bufferingStateDispatcher_.advance(/* hasData */ true, 0);
 
   AudioScheduledSourceNode::disable();
 }
@@ -719,10 +730,13 @@ std::shared_ptr<DSPAudioBuffer> AudioFileSourceNode::processDecodedOutput(
   const bool hasFreshChunk = needsFreshDecoderChunk && readNextFrameChunk(incoming);
 
   if (!hasFreshChunk && pendingDecoderChunk_.size == 0) {
+    bufferingStateDispatcher_.advance(/* hasData */ false, framesToProcess);
     processingBuffer->zero();
     return processingBuffer;
   }
 
+  bufferingStateDispatcher_.advance(/* hasData */ true, framesToProcess);
+
   if (hasFreshChunk && incoming.state == StreamState::END_OF_STREAM) {
     currentTime_.store(duration_, std::memory_order_release);
     sendOnPositionChangedEvent(0);

package/common/cpp/audioapi/core/sources/AudioFileSourceNode.h

@@ -6,6 +6,7 @@
 #include <audioapi/dsp/WsolaTimeStretcher.h>
 #include <audioapi/libs/decoding/IncrementalAudioDecoder.h>
 #include <audioapi/types/NodeOptions.h>
+#include <audioapi/utils/events/BufferingStateDispatcher.h>
 #include <audioapi/utils/events/PositionChangedDispatcher.h>
 #include <cstddef>
 #include <thread>
@@ -29,6 +30,9 @@ class MediaElementAudioSourceNode;
 
 inline constexpr auto ON_POSITION_CHANGED_INTERVAL = 0.25f;
 
+/// @brief Debounce interval for BufferingStateDispatcher — see its header.
+inline constexpr auto ON_BUFFERING_STATE_DEBOUNCE_INTERVAL = 0.15f;
+
 /// @brief Decodes a file or in-memory buffer and plays it as a scheduled source.
 /// @note When routed through MediaElementAudioSourceNode, this node outputs silence and the media node pulls decoded audio.
 class AudioFileSourceNode : public AudioScheduledSourceNode {
@@ -125,6 +129,17 @@ class AudioFileSourceNode : public AudioScheduledSourceNode {
 
   void assignOnPositionChangedCallbackId(uint64_t callbackId);
 
+  /// @brief Registers the JS callback for buffering-state-change events.
+  /// Pass 0 to unregister.
+  void assignOnBufferingStateChangeCallbackId(uint64_t callbackId);
+
+  /// @brief True while the render thread has been unable to obtain a decoded
+  /// frame for longer than @ref ON_BUFFERING_STATE_DEBOUNCE_INTERVAL. Not
+  /// exposed to JS (event-driven there); kept for tests.
+  [[nodiscard]] bool isBuffering() const {
+    return bufferingStateDispatcher_.isBuffering();
+  }
+
  protected:
   /// @brief Outputs silence when media-routed; otherwise decodes into @p processingBuffer.
   std::shared_ptr<DSPAudioBuffer> processNode(
@@ -183,6 +198,10 @@ class AudioFileSourceNode : public AudioScheduledSourceNode {
 
   PositionChangedDispatcher positionChanged_;
 
+  /// @brief Owns the buffering-state debounce/dispatch logic; see
+  /// BufferingStateDispatcher.h for the policy.
+  BufferingStateDispatcher bufferingStateDispatcher_;
+
   /// @brief Sets up SPSC channels, constructs the SeekDecoderDaemon, and initialises metadata from the opened decoder.
   /// @return false if the source could not be opened; caller must not set isInitialized_.
   [[nodiscard]] bool initDecoder(

package/common/cpp/audioapi/core/sources/RecorderAdapterNode.cpp

@@ -2,12 +2,14 @@
 #include <audioapi/core/sources/RecorderAdapterNode.h>
 #include <audioapi/core/types/ChannelInterpretation.h>
 #include <audioapi/core/utils/Constants.h>
+#include <audioapi/core/utils/CurrentRenderScope.h>
 #include <audioapi/utils/AudioArray.hpp>
 
 #include <algorithm>
 #include <cmath>
 #include <cstring>
 #include <memory>
+#include <thread>
 #include <vector>
 
 namespace audioapi {
@@ -59,17 +61,26 @@ void RecorderAdapterNode::init(size_t bufferSize, int channelCount, float sample
 }
 
 void RecorderAdapterNode::adapterCleanup() {
+  isInitialized_.store(false, std::memory_order_release);
+  waitForProcessQuiescence();
+
   needsResampling_ = false;
   buff_.clear();
   resampler_.reset();
   overflowSize_ = 0;
+}
 
-  isInitialized_.store(false, std::memory_order_release);
+void RecorderAdapterNode::waitForProcessQuiescence() const {
+  while (currentProcesses_.load(std::memory_order_acquire) != 0) {
+    std::this_thread::yield();
+  }
 }
 
 std::shared_ptr<DSPAudioBuffer> RecorderAdapterNode::processNode(
     const std::shared_ptr<DSPAudioBuffer> &processingBuffer,
     int framesToProcess) {
+  const CurrentRenderScope processScope(currentProcesses_);
+
   if (!isInitialized_.load(std::memory_order_acquire)) {
     processingBuffer->zero();
     return processingBuffer;

package/common/cpp/audioapi/core/sources/RecorderAdapterNode.h

@@ -7,6 +7,8 @@
 #include <audioapi/dsp/r8brain/Resampler.hpp>
 #include <audioapi/utils/AudioBuffer.hpp>
 #include <audioapi/utils/CircularOverflowableAudioArray.h>
+#include <atomic>
+#include <cstdint>
 #include <memory>
 #include <vector>
 
@@ -41,6 +43,7 @@ class RecorderAdapterNode : public AudioNode {
  private:
   void readFrames(AudioBuffer &target, size_t framesToRead);
   void processResampled(int framesToProcess);
+  void waitForProcessQuiescence() const;
 
   std::unique_ptr<r8b::MultiChannelResampler> resampler_;
   bool needsResampling_ = false;
@@ -53,6 +56,10 @@ class RecorderAdapterNode : public AudioNode {
   // Accumulates resampled output across calls
   AudioBuffer overflowBuffer_;
   size_t overflowSize_ = 0;
+
+  std::atomic<bool> isInitialized_{false};
+  /// Incremented around each processNode() call; adapterCleanup waits for quiescence.
+  std::atomic<uint32_t> currentProcesses_{0};
 };
 
 } // namespace audioapi

package/common/cpp/audioapi/core/utils/param/ParamQueueBase.hpp

@@ -20,7 +20,7 @@ class ParamQueueBase {
 
   /// @brief Cancel scheduled parameter changes at or after the given time.
   /// @param cancelTime The time at which to cancel scheduled changes.
-  void cancelScheduledValues(double cancelTime) {
+  virtual void cancelScheduledValues(double cancelTime) {
     eventQueue_.erase(eventQueue_.lowerBound(cancelTime), eventQueue_.end());
   }
 

package/common/cpp/audioapi/core/utils/param/ParamRenderQueue.cpp

@@ -9,10 +9,10 @@
 namespace audioapi {
 
 std::optional<float> ParamRenderQueue::computeValueAtTime(double time) {
-  while (
-      !eventQueue_.isEmpty() &&
+  while (!eventQueue_.isEmpty() &&
       (!currentEvent_ ||
-       (time >= currentEvent_->getEndTime() && eventQueue_.peekFront().getStartTime() <= time))) {
+          (time >= currentEvent_->getEndTime() &&
+              eventQueue_.peekFront().getStartTime() <= time))) {
     RenderParamEvent next;
     eventQueue_.pop(next);
     currentEvent_ = std::move(next);
@@ -93,8 +93,38 @@ float ParamRenderQueue::getValueOfPreviousEventAt(const RenderParamEvent &event,
   return event.getEndValue();
 }
 
+void ParamRenderQueue::cancelScheduledValues(double cancelTime) {
+  ParamQueueBase::cancelScheduledValues(cancelTime);
+
+  // An event may already have been promoted out of the queue; the erase above cannot see it
+  if (currentEvent_ && currentEvent_->getAutomationTime() >= cancelTime) {
+    // restore value from before currentEvent_ and discard it
+    currentEvent_ = ParamRenderEventFactory::createSetValueEvent(
+        currentEvent_->getStartValue(), currentEvent_->getStartTime());
+  }
+}
+
+void ParamRenderQueue::truncateCurrentEventAt(double holdTime) {
+  float holdValue = currentEvent_->getCalculateValue()(
+      currentEvent_->getStartTime(),
+      currentEvent_->getEndTime(),
+      currentEvent_->getStartValue(),
+      currentEvent_->getEndValue(),
+      holdTime);
+  currentEvent_->setEndTime(holdTime);
+  currentEvent_->setEndValue(holdValue);
+}
+
 void ParamRenderQueue::cancelAndHoldAtTime(double cancelTime) {
-  // E2: first event with automationTime strictly after cancelTime
+  // E2: handle the case with currentEvent_ first, since it is no longer in queue
+  if (currentEvent_ && currentEvent_->isRampType() && cancelTime < currentEvent_->getEndTime()) {
+    truncateCurrentEventAt(cancelTime);
+    // Step 5: remove everything strictly after cancelTime
+    eventQueue_.erase(eventQueue_.upperBound(cancelTime), eventQueue_.end());
+    return;
+  }
+
+  // E2: find the first event with automationTime > cancelTime
   auto e2It = eventQueue_.upperBound(cancelTime);
 
   if (e2It != eventQueue_.end() && e2It->isRampType()) {
@@ -154,14 +184,7 @@ void ParamRenderQueue::cancelAndHoldAtTime(double cancelTime) {
 
     if (currentEvent_->getType() == ParamEventType::SET_VALUE_CURVE &&
         cancelTime <= currentEvent_->getEndTime()) {
-      float holdValue = currentEvent_->getCalculateValue()(
-          currentEvent_->getStartTime(),
-          currentEvent_->getEndTime(),
-          currentEvent_->getStartValue(),
-          currentEvent_->getEndValue(),
-          cancelTime);
-      currentEvent_->setEndTime(cancelTime);
-      currentEvent_->setEndValue(holdValue);
+      truncateCurrentEventAt(cancelTime);
       // fall through to step 5
     }
   }

package/common/cpp/audioapi/core/utils/param/ParamRenderQueue.h

@@ -22,6 +22,12 @@ class ParamRenderQueue : public ParamQueueBase<RenderParamEvent> {
   /// @return True if the event was successfully added, false if the queue is full.
   bool push(RenderParamEvent &&event) override;
 
+  /// @brief Cancel scheduled parameter changes at or after the given time.
+  /// Also cancels the already-promoted @c currentEvent_ when its automation time is at or after
+  /// @p cancelTime (an in-flight ramp), restoring the value from before that automation as the spec requires.
+  /// @param cancelTime The time at which to cancel scheduled changes.
+  void cancelScheduledValues(double cancelTime) override;
+
   /// @brief Cancel scheduled parameter changes and hold the current value at the given time.
   /// @param cancelTime The time at which to cancel scheduled changes.
   void cancelAndHoldAtTime(double cancelTime);
@@ -29,6 +35,9 @@ class ParamRenderQueue : public ParamQueueBase<RenderParamEvent> {
  private:
   float defaultValue_;
 
+  /// @brief Truncate @c currentEvent_ at @p holdTime, freezing it at its value there.
+  void truncateCurrentEventAt(double holdTime);
+
   /// @brief Resolve new event's startValue and startTime based on the previous event in the queue,
   /// and adjust neighboring events to maintain the invariant of non-overlapping events in the queue.
   /// @param event The new event to resolve around.

package/common/cpp/audioapi/core/utils/worklets/SafeIncludes.h

@@ -47,13 +47,13 @@ class WorkletRuntime {
   [[nodiscard]] jsi::Runtime &getJSIRuntime() const {
     throw RN_AUDIO_API_WORKLETS_DISABLED_ERROR
   }
-  [[nodiscard]] jsi::Value executeSync(jsi::Runtime &rt, const jsi::Value &worklet) const {
+  [[nodiscard]] jsi::Value runSync(jsi::Runtime &rt, const jsi::Value &worklet) const {
     throw RN_AUDIO_API_WORKLETS_DISABLED_ERROR
   }
-  [[nodiscard]] jsi::Value executeSync(std::function<jsi::Value(jsi::Runtime &)> &&job) const {
+  [[nodiscard]] jsi::Value runSync(std::function<jsi::Value(jsi::Runtime &)> &&job) const {
       // NOLINT(cppcoreguidelines-rvalue-reference-param-not-moved)
       throw RN_AUDIO_API_WORKLETS_DISABLED_ERROR} jsi::Value
-      executeSync(const std::function<jsi::Value(jsi::Runtime &)> &job) const {
+      runSync(const std::function<jsi::Value(jsi::Runtime &)> &job) const {
     throw RN_AUDIO_API_WORKLETS_DISABLED_ERROR
   }
 };

package/common/cpp/audioapi/core/utils/worklets/WorkletsRunner.cpp

@@ -15,7 +15,7 @@ WorkletsRunner::WorkletsRunner(
   }
 #if RN_AUDIO_API_ENABLE_WORKLETS
   unsafeRuntimePtr = &strongRuntime->getJSIRuntime();
-  strongRuntime->executeSync([this, shareableWorklet](jsi::Runtime &rt) -> jsi::Value {
+  strongRuntime->runSync([this, shareableWorklet](jsi::Runtime &rt) -> jsi::Value {
     /// Placement new to avoid dynamic memory allocation
     new (reinterpret_cast<jsi::Function *>(&unsafeWorklet))
         jsi::Function(shareableWorklet->toJSValue(*unsafeRuntimePtr)
@@ -62,7 +62,7 @@ std::optional<jsi::Value> WorkletsRunner::executeOnRuntimeGuarded(
     return std::nullopt;
   }
 #if RN_AUDIO_API_ENABLE_WORKLETS
-  return strongRuntime->executeSync(std::move(job));
+  return strongRuntime->runSync(std::move(job));
 #else
   return std::nullopt;
 #endif

package/common/cpp/audioapi/events/AudioEvent.h

@@ -28,5 +28,6 @@ enum class AudioEvent : uint8_t {
   POSITION_CHANGED,
   BUFFER_ENDED,
   RECORDER_ERROR,
+  BUFFERING_STATE_CHANGE,
 };
 } // namespace audioapi

package/common/cpp/audioapi/events/AudioEventPayload.h

@@ -27,6 +27,16 @@ struct DoubleValuePayload {
   }
 };
 
+struct BoolValuePayload {
+  bool value;
+
+  facebook::jsi::Object toJsiObject(facebook::jsi::Runtime &rt) const {
+    facebook::jsi::Object obj(rt);
+    obj.setProperty(rt, "value", value);
+    return obj;
+  }
+};
+
 struct InterruptionPayload {
   std::string type;
   bool shouldResume;
@@ -90,6 +100,7 @@ struct AudioReadyPayload {
 using AudioEventPayload = std::variant<
     EmptyPayload,
     DoubleValuePayload,
+    BoolValuePayload,
     InterruptionPayload,
     StringPayload,
     BufferEndedPayload,

package/common/cpp/audioapi/events/AudioEventPayloadMapping.h

@@ -40,6 +40,7 @@ AUDIOAPI_DEFINE_EVENT_PAYLOAD(AudioEvent::AUDIO_READY, AudioReadyPayload);
 AUDIOAPI_DEFINE_EVENT_PAYLOAD(AudioEvent::POSITION_CHANGED, DoubleValuePayload);
 AUDIOAPI_DEFINE_EVENT_PAYLOAD(AudioEvent::BUFFER_ENDED, BufferEndedPayload);
 AUDIOAPI_DEFINE_EVENT_PAYLOAD(AudioEvent::RECORDER_ERROR, StringPayload);
+AUDIOAPI_DEFINE_EVENT_PAYLOAD(AudioEvent::BUFFERING_STATE_CHANGE, BoolValuePayload);
 
 #undef AUDIOAPI_DEFINE_EVENT_PAYLOAD
 

package/common/cpp/audioapi/utils/events/BufferingStateDispatcher.cpp

@@ -0,0 +1,49 @@
+#include <audioapi/utils/events/BufferingStateDispatcher.h>
+
+#include <memory>
+
+namespace audioapi {
+
+BufferingStateDispatcher::BufferingStateDispatcher(
+    const std::shared_ptr<IAudioEventHandlerRegistry> &audioEventHandlerRegistry,
+    int startThresholdFrames)
+    : bufferingStateChangeEvent_(audioEventHandlerRegistry),
+      startThresholdFrames_(startThresholdFrames) {}
+
+void BufferingStateDispatcher::assignCallbackId(uint64_t callbackId) noexcept {
+  bufferingStateChangeEvent_.assignCallbackId(callbackId);
+}
+
+uint64_t BufferingStateDispatcher::getCallbackId() const noexcept {
+  return bufferingStateChangeEvent_.getCallbackId();
+}
+
+bool BufferingStateDispatcher::hasCallback() const noexcept {
+  return bufferingStateChangeEvent_.hasCallback();
+}
+
+bool BufferingStateDispatcher::isBuffering() const noexcept {
+  return isBuffering_.load(std::memory_order_acquire);
+}
+
+void BufferingStateDispatcher::advance(bool hasData, int framesToProcess) {
+  if (!bufferingStateChangeEvent_.hasCallback()) {
+    return;
+  }
+
+  if (hasData) {
+    starvedFrames_ = 0;
+    if (isBuffering_.exchange(false, std::memory_order_acq_rel)) {
+      bufferingStateChangeEvent_.dispatchFromAudioThread(BoolValuePayload{.value = false});
+    }
+    return;
+  }
+
+  starvedFrames_ += framesToProcess;
+  if (!isBuffering_.load(std::memory_order_acquire) && starvedFrames_ >= startThresholdFrames_) {
+    isBuffering_.store(true, std::memory_order_release);
+    bufferingStateChangeEvent_.dispatchFromAudioThread(BoolValuePayload{.value = true});
+  }
+}
+
+} // namespace audioapi

package/common/cpp/audioapi/utils/events/BufferingStateDispatcher.h

@@ -0,0 +1,42 @@
+#pragma once
+
+#include <audioapi/events/EventCaller.hpp>
+
+#include <atomic>
+#include <cstdint>
+#include <memory>
+
+namespace audioapi {
+
+/// @brief Debounces render-thread frame starvation into a buffering-state
+/// event. A single starved render quantum is normal decode-ahead jitter, not
+/// a real stall — only sustained starvation past @p startThresholdFrames is
+/// reported. Recovery is reported immediately, with no symmetric debounce.
+class BufferingStateDispatcher {
+ public:
+  BufferingStateDispatcher(
+      const std::shared_ptr<IAudioEventHandlerRegistry> &audioEventHandlerRegistry,
+      int startThresholdFrames);
+
+  void assignCallbackId(uint64_t callbackId) noexcept;
+  [[nodiscard]] uint64_t getCallbackId() const noexcept;
+  [[nodiscard]] bool hasCallback() const noexcept;
+
+  /// @brief True once sustained starvation has been reported and no
+  /// recovery has fired yet.
+  [[nodiscard]] bool isBuffering() const noexcept;
+
+  /// @brief Call once per render quantum. @p hasData is true when the
+  /// quantum had a decoded chunk available (fresh or previously stashed) to
+  /// play; false when the decoder daemon has nothing ready yet.
+  /// @note Audio thread only.
+  void advance(bool hasData, int framesToProcess);
+
+ private:
+  EventCaller<AudioEvent::BUFFERING_STATE_CHANGE> bufferingStateChangeEvent_;
+  std::atomic<bool> isBuffering_{false};
+  int starvedFrames_ = 0;
+  const int startThresholdFrames_;
+};
+
+} // namespace audioapi

package/ios/audioapi/ios/core/IOSAudioRecorder.h

@@ -1,12 +1,13 @@
 #pragma once
 
 #ifdef __OBJC__ // when compiled as Objective-C
-#import <NativeAudioRecorder.h>
+#import <audioapi/ios/core/NativeAudioRecorder.h>
 #else
 typedef struct objc_object NSURL;
 typedef struct objc_object AVAudioFile;
 typedef struct objc_object AudioBufferList;
 typedef struct objc_object NativeAudioRecorder;
+typedef struct objc_object AVAudioFormat;
 #endif // __OBJC__
 
 #include <audioapi/core/inputs/AudioRecorder.h>
@@ -59,6 +60,16 @@ class IOSAudioRecorder : public AudioRecorder {
       const std::shared_ptr<AudioFileProperties> &properties,
       const std::string &fileNameOverride = "");
   void rollbackFailedStart();
+  Result<NoneType, std::string> reprepareForLiveInput();
+  void handleInputConfigurationChange();
+  Result<NoneType, std::string> reprepareFileWriter(
+      AVAudioFormat *inputFormat,
+      int maxInputBufferLength);
+  Result<NoneType, std::string> reprepareCallback(
+      AVAudioFormat *inputFormat,
+      int maxInputBufferLength);
+  void reprepareAdapter(AVAudioFormat *inputFormat, int maxInputBufferLength);
+  void runSideEffects(const AudioBufferList *inputBuffer, int numFrames);
 
   std::vector<std::string> recordingSegmentPaths_;
 };