From 5c0c3716b89c6779e20c175d2e13cf9c4c9de8f2 Mon Sep 17 00:00:00 2001
From: Gav Richards <gav@aiir.com>
Date: Wed, 19 Aug 2026 15:36:40 +0100
Subject: [PATCH 1/5] feat: buffering/loading state for AudioFileSourceNode and
 <Audio>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the buffering/stall signal identified as missing during aiirmobile's
react-native-audio-api evaluation: the audio-tag state model previously
exposed only 'idle' | 'playing' | 'paused', with no way to tell a genuine
network/decoder stall apart from normal playback, and no onWaiting/onStalled-
style event.

- Native (shared C++ core, both platforms): detects render-thread frame
  starvation directly in AudioFileSourceNode::processDecodedOutput() (the
  single choke point both direct and MediaElementAudioSourceNode-routed
  playback go through), debounced against normal decode-ahead jitter via a
  new ON_BUFFERING_STATE_DEBOUNCE_INTERVAL (150ms) threshold. Recovery is
  reported immediately, with no symmetric debounce. pause()/disable() reset
  the state so a deliberate pause never leaves a stale 'buffering' reading.
- New AudioEvent::BUFFERING_STATE_CHANGE + BoolValuePayload, wired through
  the existing EventCaller/HostObject/JsEnumParser plumbing exactly like the
  other AudioFileSourceNode events (onPositionChanged, onEnded).
- JS: AudioTagPlaybackState gains a 'buffering' sub-state (derived, not a
  parallel piece of state, so a stall starting/ending doesn't tear down the
  effect watching it), and <Audio> gains onWaiting/onPlaying props mirroring
  the HTML <audio>/<video> spec events of the same name. Wired for both the
  native (Audio.tsx) and web (Audio.web.tsx) implementations.
- New AudioFileSourceNodeTest.cpp covers the debounce state machine directly
  (crossing/not crossing threshold, immediate recovery, no-op without a
  listener, intermittent-jitter not tripping it, pause() resetting stale
  state) rather than racing the real decoder daemon thread for genuine
  starvation.

Verified: yarn typecheck, yarn lint:js, yarn lint:cpp, yarn
format:check:common all clean; full C++ suite (394 tests, was 387) passes
including the 7 new tests.

Not yet verified: on a real device against real network stalls — the debounce
threshold (150ms) is a starting point, not tuned against real-world Icecast/
HLS stall behavior.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../sources/AudioFileSourceNodeHostObject.cpp |  14 +-
 .../sources/AudioFileSourceNodeHostObject.h   |   2 +
 .../HostObjects/utils/JsEnumParser.cpp        |   2 +
 .../core/sources/AudioFileSourceNode.cpp      |  37 ++-
 .../core/sources/AudioFileSourceNode.h        |  36 +++
 .../common/cpp/audioapi/events/AudioEvent.h   |   1 +
 .../cpp/audioapi/events/AudioEventPayload.h   |  11 +
 .../events/AudioEventPayloadMapping.hpp       |   1 +
 .../core/sources/AudioFileSourceNodeTest.cpp  | 234 ++++++++++++++++++
 .../cpp/test/src/events/EventCallerTest.cpp   |   2 +
 .../src/Audio/Audio.tsx                       |  43 +++-
 .../src/Audio/Audio.web.tsx                   |  28 ++-
 .../src/Audio/AudioFileSourceNode.ts          |  28 +++
 .../react-native-audio-api/src/Audio/types.ts |  20 +-
 .../react-native-audio-api/src/Audio/utils.ts |   8 +
 .../src/events/types.ts                       |  12 +
 .../src/jsi-interfaces.ts                     |   7 +
 17 files changed, 479 insertions(+), 7 deletions(-)
 create mode 100644 packages/react-native-audio-api/common/cpp/test/src/core/sources/AudioFileSourceNodeTest.cpp

diff --git a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/sources/AudioFileSourceNodeHostObject.cpp b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/sources/AudioFileSourceNodeHostObject.cpp
index f1c028981..4b8adf11e 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/sources/AudioFileSourceNodeHostObject.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/sources/AudioFileSourceNodeHostObject.cpp
@@ -35,9 +35,11 @@ AudioFileSourceNodeHostObject::AudioFileSourceNodeHostObject(
       JSI_EXPORT_PROPERTY_GETTER(AudioFileSourceNodeHostObject, loop),
       JSI_EXPORT_PROPERTY_GETTER(AudioFileSourceNodeHostObject, currentTime),
       JSI_EXPORT_PROPERTY_GETTER(AudioFileSourceNodeHostObject, duration),
-      JSI_EXPORT_PROPERTY_GETTER(AudioFileSourceNodeHostObject, routedThroughMediaElement));
+      JSI_EXPORT_PROPERTY_GETTER(AudioFileSourceNodeHostObject, routedThroughMediaElement),
+      JSI_EXPORT_PROPERTY_GETTER(AudioFileSourceNodeHostObject, buffering));
   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),
@@ -51,6 +53,7 @@ AudioFileSourceNodeHostObject::AudioFileSourceNodeHostObject(
 
 AudioFileSourceNodeHostObject::~AudioFileSourceNodeHostObject() {
   audioFileSourceNode_->assignOnPositionChangedCallbackId(0);
+  audioFileSourceNode_->assignOnBufferingStateChangeCallbackId(0);
 }
 
 JSI_PROPERTY_GETTER_IMPL(AudioFileSourceNodeHostObject, volume) {
@@ -119,6 +122,10 @@ JSI_PROPERTY_GETTER_IMPL(AudioFileSourceNodeHostObject, routedThroughMediaElemen
   return {audioFileSourceNode_->isRoutedThroughMediaElement()};
 }
 
+JSI_PROPERTY_GETTER_IMPL(AudioFileSourceNodeHostObject, buffering) {
+  return {audioFileSourceNode_->isBuffering()};
+}
+
 JSI_HOST_FUNCTION_IMPL(AudioFileSourceNodeHostObject, pause) {
   auto event = [node = audioFileSourceNode_](BaseAudioContext &) {
     node->pause();
@@ -146,4 +153,9 @@ JSI_PROPERTY_SETTER_IMPL(AudioFileSourceNodeHostObject, onPositionChanged) {
       std::stoull(value.getString(runtime).utf8(runtime)));
 }
 
+JSI_PROPERTY_SETTER_IMPL(AudioFileSourceNodeHostObject, onBufferingStateChanged) {
+  audioFileSourceNode_->assignOnBufferingStateChangeCallbackId(
+      std::stoull(value.getString(runtime).utf8(runtime)));
+}
+
 } // namespace audioapi
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/sources/AudioFileSourceNodeHostObject.h b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/sources/AudioFileSourceNodeHostObject.h
index 9292f83cf..1e859e8e5 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/sources/AudioFileSourceNodeHostObject.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/sources/AudioFileSourceNodeHostObject.h
@@ -25,12 +25,14 @@ class AudioFileSourceNodeHostObject : public AudioScheduledSourceNodeHostObject
   JSI_PROPERTY_GETTER_DECL(currentTime);
   JSI_PROPERTY_GETTER_DECL(duration);
   JSI_PROPERTY_GETTER_DECL(routedThroughMediaElement);
+  JSI_PROPERTY_GETTER_DECL(buffering);
 
   JSI_PROPERTY_SETTER_DECL(volume);
   JSI_PROPERTY_SETTER_DECL(playbackRate);
   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);
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/JsEnumParser.cpp b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/JsEnumParser.cpp
index bcfa85d5b..05cb454c6 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/JsEnumParser.cpp
+++ b/packages/react-native-audio-api/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);
 }
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.cpp b/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.cpp
index c98b2936c..8b74c96ac 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.cpp
@@ -34,7 +34,10 @@ AudioFileSourceNode::AudioFileSourceNode(
       positionChanged_(
           context->getAudioEventHandlerRegistry(),
           static_cast<int>(context->getSampleRate() * ON_POSITION_CHANGED_INTERVAL),
-          true) {
+          true),
+      onBufferingStateChangeEvent_(context->getAudioEventHandlerRegistry()),
+      bufferingStartThresholdFrames_(
+          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);
 
@@ -85,6 +88,31 @@ void AudioFileSourceNode::assignOnPositionChangedCallbackId(uint64_t callbackId)
   positionChanged_.assignCallbackId(callbackId);
 }
 
+void AudioFileSourceNode::assignOnBufferingStateChangeCallbackId(uint64_t callbackId) {
+  onBufferingStateChangeEvent_.assignCallbackId(callbackId);
+}
+
+void AudioFileSourceNode::updateBufferingState(bool hasData, int framesToProcess) {
+  if (!onBufferingStateChangeEvent_.hasCallback()) {
+    return;
+  }
+
+  if (hasData) {
+    starvedFrames_ = 0;
+    if (isBuffering_.exchange(false, std::memory_order_acq_rel)) {
+      onBufferingStateChangeEvent_.dispatchFromAudioThread(BoolValuePayload{.value = false});
+    }
+    return;
+  }
+
+  starvedFrames_ += framesToProcess;
+  if (!isBuffering_.load(std::memory_order_acquire) &&
+      starvedFrames_ >= bufferingStartThresholdFrames_) {
+    isBuffering_.store(true, std::memory_order_release);
+    onBufferingStateChangeEvent_.dispatchFromAudioThread(BoolValuePayload{.value = true});
+  }
+}
+
 bool AudioFileSourceNode::initDecoder(
     const std::shared_ptr<BaseAudioContext> &context,
     AudioFileSourceOptions &options) {
@@ -434,6 +462,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.
+  updateBufferingState(/* hasData */ true, 0);
 }
 
 void AudioFileSourceNode::disable() {
@@ -441,6 +472,7 @@ void AudioFileSourceNode::disable() {
   filePaused_ = false;
   endOfStreamStopPending_ = false;
   endOfStreamDrainPending_ = false;
+  updateBufferingState(/* hasData */ true, 0);
 
   AudioScheduledSourceNode::disable();
 }
@@ -721,10 +753,13 @@ void AudioFileSourceNode::processDecodedOutput(
   const bool hasFreshChunk = needsFreshDecoderChunk && readNextFrameChunk(incoming);
 
   if (!hasFreshChunk && pendingDecoderChunk_.size == 0) {
+    updateBufferingState(/* hasData */ false, framesToProcess);
     processingBuffer->zero();
     return;
   }
 
+  updateBufferingState(/* hasData */ true, framesToProcess);
+
   if (hasFreshChunk && incoming.state == StreamState::END_OF_STREAM) {
     currentTime_.store(duration_, std::memory_order_release);
     sendOnPositionChangedEvent(0);
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.h b/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.h
index 495217328..3d35dfdb8 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.h
@@ -5,6 +5,7 @@
 #include <audioapi/decoding/SeekDecoderDaemon.h>
 #include <audioapi/decoding/backends/AudioDecoderBackend.h>
 #include <audioapi/dsp/WsolaTimeStretcher.h>
+#include <audioapi/events/EventCaller.hpp>
 #include <audioapi/types/NodeOptions.h>
 #include <audioapi/utils/events/PositionChangedDispatcher.h>
 #include <cstddef>
@@ -25,6 +26,12 @@ class MediaElementAudioSourceNode;
 
 inline constexpr auto ON_POSITION_CHANGED_INTERVAL = 0.25f;
 
+/// @brief How long the render thread must go without a decoded frame before a
+/// buffering-state-change event fires. Debounces normal decode-ahead jitter
+/// (a single starved quantum is common and not a real stall) from a genuine
+/// network/decoder stall a UI would want to show a spinner for.
+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 {
@@ -122,9 +129,28 @@ class AudioFileSourceNode : public AudioScheduledSourceNode {
 
   void assignOnPositionChangedCallbackId(uint64_t callbackId);
 
+  /// @brief Registers the JS callback for buffering-state-change events (see
+  /// @ref updateBufferingState). 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.
+  [[nodiscard]] bool isBuffering() const {
+    return isBuffering_.load(std::memory_order_acquire);
+  }
+
  protected:
   void processNode(int framesToProcess) override;
 
+  /// @brief Debounces render-thread frame starvation into a buffering-state
+  /// event. @p hasData is true whenever this render quantum had a decoded
+  /// chunk available (fresh or previously stashed) to play; false when the
+  /// decoder daemon has nothing ready yet. Protected (rather than private)
+  /// so tests can drive it directly without racing the real decoder daemon
+  /// thread for genuine starvation — see AudioFileSourceNodeTest.cpp.
+  /// @note Audio thread only.
+  void updateBufferingState(bool hasData, int framesToProcess);
+
  private:
   std::shared_ptr<AudioFileDecoderState> decoderState_;
   /// @brief Decodes and mixes samples for direct or media-element playback.
@@ -178,6 +204,16 @@ class AudioFileSourceNode : public AudioScheduledSourceNode {
 
   PositionChangedDispatcher positionChanged_;
 
+  /// @brief Fired (audio thread) when the render thread starts/stops going
+  /// without decoded frames for longer than the debounce interval. See
+  /// @ref updateBufferingState.
+  EventCaller<AudioEvent::BUFFERING_STATE_CHANGE> onBufferingStateChangeEvent_;
+  std::atomic<bool> isBuffering_{false};
+  /// @brief Frames accumulated (at context sample rate) since the last frame
+  /// chunk was available. Reset whenever a chunk is obtained.
+  int starvedFrames_{0};
+  const int bufferingStartThresholdFrames_;
+
   /// @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(
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/events/AudioEvent.h b/packages/react-native-audio-api/common/cpp/audioapi/events/AudioEvent.h
index 2f669d76a..e11dc5262 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/events/AudioEvent.h
+++ b/packages/react-native-audio-api/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
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/events/AudioEventPayload.h b/packages/react-native-audio-api/common/cpp/audioapi/events/AudioEventPayload.h
index a7b9e6e20..f2d9a4059 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/events/AudioEventPayload.h
+++ b/packages/react-native-audio-api/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,
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/events/AudioEventPayloadMapping.hpp b/packages/react-native-audio-api/common/cpp/audioapi/events/AudioEventPayloadMapping.hpp
index 747b0c419..bf26da887 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/events/AudioEventPayloadMapping.hpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/events/AudioEventPayloadMapping.hpp
@@ -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
 
diff --git a/packages/react-native-audio-api/common/cpp/test/src/core/sources/AudioFileSourceNodeTest.cpp b/packages/react-native-audio-api/common/cpp/test/src/core/sources/AudioFileSourceNodeTest.cpp
new file mode 100644
index 000000000..a84a20db6
--- /dev/null
+++ b/packages/react-native-audio-api/common/cpp/test/src/core/sources/AudioFileSourceNodeTest.cpp
@@ -0,0 +1,234 @@
+#include <audioapi/core/OfflineAudioContext.h>
+#include <audioapi/core/destinations/AudioDestinationNode.h>
+#include <audioapi/core/sources/AudioFileSourceNode.h>
+#include <audioapi/events/AudioEventPayload.h>
+#include <audioapi/types/NodeOptions.h>
+#include <gmock/gmock.h>
+#include <gtest/gtest.h>
+#include <test/src/MockAudioEventHandlerRegistry.h>
+
+#include <cstdint>
+#include <memory>
+#include <vector>
+
+using namespace audioapi;
+
+// NOLINTBEGIN
+
+namespace {
+void appendU16LE(std::vector<uint8_t> &bytes, uint16_t value) {
+  bytes.push_back(static_cast<uint8_t>(value & 0xFF));
+  bytes.push_back(static_cast<uint8_t>((value >> 8) & 0xFF));
+}
+
+void appendU32LE(std::vector<uint8_t> &bytes, uint32_t value) {
+  bytes.push_back(static_cast<uint8_t>(value & 0xFF));
+  bytes.push_back(static_cast<uint8_t>((value >> 8) & 0xFF));
+  bytes.push_back(static_cast<uint8_t>((value >> 16) & 0xFF));
+  bytes.push_back(static_cast<uint8_t>((value >> 24) & 0xFF));
+}
+
+// Same fixture as MediaElementAudioSourceNodeTest.cpp — a tiny in-memory
+// PCM16 mono WAV, just enough for AudioFileSourceNode's decoder to open
+// successfully. The tests below exercise updateBufferingState() directly
+// rather than through real playback, since forcing genuine decoder-daemon
+// starvation deterministically would mean racing a real background thread.
+std::vector<uint8_t> makeTestWavPcm16Mono() {
+  constexpr uint16_t channels = 1;
+  constexpr uint32_t sampleRate = 44100;
+  constexpr uint16_t bitsPerSample = 16;
+  constexpr uint16_t bytesPerSample = bitsPerSample / 8;
+  constexpr uint16_t blockAlign = channels * bytesPerSample;
+  constexpr uint32_t byteRate = sampleRate * blockAlign;
+
+  const std::vector<int16_t> samples = {0, 16384, -16384, 8192};
+  const uint32_t dataChunkSize = static_cast<uint32_t>(samples.size() * sizeof(int16_t));
+  const uint32_t riffChunkSize = 36 + dataChunkSize;
+
+  std::vector<uint8_t> wav;
+  wav.reserve(44 + dataChunkSize);
+
+  wav.insert(wav.end(), {'R', 'I', 'F', 'F'});
+  appendU32LE(wav, riffChunkSize);
+  wav.insert(wav.end(), {'W', 'A', 'V', 'E'});
+
+  wav.insert(wav.end(), {'f', 'm', 't', ' '});
+  appendU32LE(wav, 16);
+  appendU16LE(wav, 1);
+  appendU16LE(wav, channels);
+  appendU32LE(wav, sampleRate);
+  appendU32LE(wav, byteRate);
+  appendU16LE(wav, blockAlign);
+  appendU16LE(wav, bitsPerSample);
+
+  wav.insert(wav.end(), {'d', 'a', 't', 'a'});
+  appendU32LE(wav, dataChunkSize);
+
+  const auto *sampleBytes = reinterpret_cast<const uint8_t *>(samples.data());
+  wav.insert(wav.end(), sampleBytes, sampleBytes + dataChunkSize);
+
+  return wav;
+}
+} // namespace
+
+class TestableAudioFileSourceNode : public AudioFileSourceNode {
+ public:
+  using AudioFileSourceNode::AudioFileSourceNode;
+
+  void callUpdateBufferingState(bool hasData, int framesToProcess) {
+    updateBufferingState(hasData, framesToProcess);
+  }
+};
+
+class AudioFileSourceNodeTest : public ::testing::Test {
+ protected:
+  static constexpr int kSampleRate = 44100;
+  // Mirrors ON_BUFFERING_STATE_DEBOUNCE_INTERVAL in AudioFileSourceNode.h.
+  static constexpr int kThresholdFrames =
+      static_cast<int>(kSampleRate * ON_BUFFERING_STATE_DEBOUNCE_INTERVAL);
+
+  std::shared_ptr<MockAudioEventHandlerRegistry> eventRegistry;
+  std::shared_ptr<OfflineAudioContext> context;
+  std::shared_ptr<AudioDestinationNode> destination;
+
+  void SetUp() override {
+    eventRegistry = std::make_shared<MockAudioEventHandlerRegistry>();
+    context = std::make_shared<OfflineAudioContext>(2, 5 * kSampleRate, kSampleRate, eventRegistry);
+    destination = std::make_shared<AudioDestinationNode>(context);
+    context->initialize(destination.get());
+  }
+
+  std::shared_ptr<TestableAudioFileSourceNode> createFileSource() {
+    AudioFileSourceOptions options;
+    options.data = makeTestWavPcm16Mono();
+    auto fileSource = std::make_shared<TestableAudioFileSourceNode>(context, options);
+    EXPECT_NE(fileSource, nullptr);
+    return fileSource;
+  }
+
+  static constexpr uint64_t kCallbackId = 42;
+};
+
+TEST_F(AudioFileSourceNodeTest, NoCallbackMeansNoDispatchRegardlessOfStarvation) {
+  auto fileSource = createFileSource();
+
+  EXPECT_CALL(*eventRegistry, dispatchEventFromAudioThread(testing::_, testing::_, testing::_))
+      .Times(0);
+
+  // Well past the debounce threshold, but no listener is registered.
+  fileSource->callUpdateBufferingState(false, kThresholdFrames * 2);
+
+  EXPECT_FALSE(fileSource->isBuffering());
+}
+
+TEST_F(AudioFileSourceNodeTest, StarvationBelowThresholdDoesNotDispatch) {
+  auto fileSource = createFileSource();
+  fileSource->assignOnBufferingStateChangeCallbackId(kCallbackId);
+
+  EXPECT_CALL(
+      *eventRegistry,
+      dispatchEventFromAudioThread(AudioEvent::BUFFERING_STATE_CHANGE, kCallbackId, testing::_))
+      .Times(0);
+
+  fileSource->callUpdateBufferingState(false, kThresholdFrames - 1);
+
+  EXPECT_FALSE(fileSource->isBuffering());
+}
+
+TEST_F(AudioFileSourceNodeTest, StarvationCrossingThresholdDispatchesTrueExactlyOnce) {
+  auto fileSource = createFileSource();
+  fileSource->assignOnBufferingStateChangeCallbackId(kCallbackId);
+
+  EXPECT_CALL(
+      *eventRegistry,
+      dispatchEventFromAudioThread(AudioEvent::BUFFERING_STATE_CHANGE, kCallbackId, testing::_))
+      .Times(1)
+      .WillOnce(testing::Invoke([](AudioEvent, uint64_t, AudioEventPayload payload) {
+        auto *boolPayload = std::get_if<BoolValuePayload>(&payload);
+        EXPECT_NE(boolPayload, nullptr);
+        EXPECT_TRUE(boolPayload->value);
+        return true;
+      }));
+
+  // Accumulates across calls, like consecutive starved render quanta would.
+  fileSource->callUpdateBufferingState(false, kThresholdFrames / 2);
+  fileSource->callUpdateBufferingState(false, kThresholdFrames / 2);
+  fileSource->callUpdateBufferingState(false, kThresholdFrames / 2);
+
+  EXPECT_TRUE(fileSource->isBuffering());
+}
+
+TEST_F(AudioFileSourceNodeTest, RecoveryDispatchesFalseImmediatelyWithNoDebounce) {
+  auto fileSource = createFileSource();
+  fileSource->assignOnBufferingStateChangeCallbackId(kCallbackId);
+
+  EXPECT_CALL(
+      *eventRegistry,
+      dispatchEventFromAudioThread(AudioEvent::BUFFERING_STATE_CHANGE, kCallbackId, testing::_))
+      .WillOnce(testing::Return(true))
+      .WillOnce(testing::Invoke([](AudioEvent, uint64_t, AudioEventPayload payload) {
+        auto *boolPayload = std::get_if<BoolValuePayload>(&payload);
+        EXPECT_NE(boolPayload, nullptr);
+        EXPECT_FALSE(boolPayload->value);
+        return true;
+      }));
+
+  fileSource->callUpdateBufferingState(false, kThresholdFrames * 2);
+  ASSERT_TRUE(fileSource->isBuffering());
+
+  // A single frame of real data recovers immediately — no symmetric debounce.
+  fileSource->callUpdateBufferingState(true, 1);
+
+  EXPECT_FALSE(fileSource->isBuffering());
+}
+
+TEST_F(AudioFileSourceNodeTest, HasDataWhileNotBufferingNeverDispatches) {
+  auto fileSource = createFileSource();
+  fileSource->assignOnBufferingStateChangeCallbackId(kCallbackId);
+
+  EXPECT_CALL(*eventRegistry, dispatchEventFromAudioThread(testing::_, testing::_, testing::_))
+      .Times(0);
+
+  for (int i = 0; i < 10; ++i) {
+    fileSource->callUpdateBufferingState(true, RENDER_QUANTUM_SIZE);
+  }
+
+  EXPECT_FALSE(fileSource->isBuffering());
+}
+
+TEST_F(AudioFileSourceNodeTest, IntermittentDataResetsStarvationCounter) {
+  auto fileSource = createFileSource();
+  fileSource->assignOnBufferingStateChangeCallbackId(kCallbackId);
+
+  EXPECT_CALL(*eventRegistry, dispatchEventFromAudioThread(testing::_, testing::_, testing::_))
+      .Times(0);
+
+  // Never accumulates enough consecutive starvation to cross the threshold,
+  // because a data quantum resets the counter each time — mirrors ordinary
+  // decode-ahead jitter rather than a real stall.
+  for (int i = 0; i < 20; ++i) {
+    fileSource->callUpdateBufferingState(false, kThresholdFrames - 1);
+    fileSource->callUpdateBufferingState(true, RENDER_QUANTUM_SIZE);
+  }
+
+  EXPECT_FALSE(fileSource->isBuffering());
+}
+
+TEST_F(AudioFileSourceNodeTest, PauseClearsBufferingStateWithoutStaleTrue) {
+  auto fileSource = createFileSource();
+  fileSource->assignOnBufferingStateChangeCallbackId(kCallbackId);
+
+  EXPECT_CALL(
+      *eventRegistry,
+      dispatchEventFromAudioThread(AudioEvent::BUFFERING_STATE_CHANGE, kCallbackId, testing::_))
+      .Times(2); // one true (starvation), one false (pause() resetting it)
+
+  fileSource->callUpdateBufferingState(false, kThresholdFrames * 2);
+  ASSERT_TRUE(fileSource->isBuffering());
+
+  fileSource->pause();
+
+  EXPECT_FALSE(fileSource->isBuffering());
+}
+
+// NOLINTEND
diff --git a/packages/react-native-audio-api/common/cpp/test/src/events/EventCallerTest.cpp b/packages/react-native-audio-api/common/cpp/test/src/events/EventCallerTest.cpp
index e78ede522..feb8a086c 100644
--- a/packages/react-native-audio-api/common/cpp/test/src/events/EventCallerTest.cpp
+++ b/packages/react-native-audio-api/common/cpp/test/src/events/EventCallerTest.cpp
@@ -17,8 +17,10 @@ constexpr uint64_t POSITION_CALLBACK_ID = 19;
 static_assert(EventPayloadFor<AudioEvent::ENDED, EmptyPayload>);
 static_assert(EventPayloadFor<AudioEvent::POSITION_CHANGED, DoubleValuePayload>);
 static_assert(EventPayloadFor<AudioEvent::RECORDER_ERROR, StringPayload>);
+static_assert(EventPayloadFor<AudioEvent::BUFFERING_STATE_CHANGE, BoolValuePayload>);
 static_assert(!EventPayloadFor<AudioEvent::ENDED, StringPayload>);
 static_assert(!EventPayloadFor<AudioEvent::RECORDER_ERROR, EmptyPayload>);
+static_assert(!EventPayloadFor<AudioEvent::BUFFERING_STATE_CHANGE, EmptyPayload>);
 } // namespace
 
 TEST(EventCallerTest, AssignAndGetCallbackId) {
diff --git a/packages/react-native-audio-api/src/Audio/Audio.tsx b/packages/react-native-audio-api/src/Audio/Audio.tsx
index a8895e575..138e91e88 100644
--- a/packages/react-native-audio-api/src/Audio/Audio.tsx
+++ b/packages/react-native-audio-api/src/Audio/Audio.tsx
@@ -42,14 +42,30 @@ const Audio = React.memo(
       onPlay,
       onPause,
       onVolumeChange,
+      onWaiting,
+      onPlaying,
     } = useStableAudioProps(props);
     const [volumeState, setVolumeState] = useState<number | null>(null);
     const [mutedState, setMutedState] = useState<boolean | null>(null);
     const [ready, setReady] = useState(false);
     const [playbackState, setPlaybackState] =
       useState<AudioTagPlaybackState>('idle');
+    const [isBuffering, setIsBuffering] = useState(false);
     const [currentTime, setCurrentTime] = useState(0);
 
+    // 'buffering' is a UI-facing overlay on top of the 'playing' intent, not a
+    // fourth state tracked alongside it — see AudioTagPlaybackState's doc
+    // comment. Keeping it derived (rather than folding it into playbackState
+    // directly) avoids the buffering-subscription effect below tearing itself
+    // down every time a stall starts/ends.
+    const publicPlaybackState = useMemo<AudioTagPlaybackState>(
+      () =>
+        playbackState === 'playing' && isBuffering
+          ? 'buffering'
+          : playbackState,
+      [playbackState, isBuffering]
+    );
+
     const path = useMemo(() => resolveSourcePath(source), [source]);
 
     const lastEffectiveVolumeRef = useRef(muted ? 0 : volume);
@@ -207,6 +223,29 @@ const Audio = React.memo(
       };
     }, [onPositionChange, playbackState, fileSourceRef]);
 
+    useEffect(() => {
+      if (playbackState !== 'playing') {
+        // Not an active stall (paused/idle/ended) — clear any stale flag from
+        // a stall that was in progress when playback stopped.
+        setIsBuffering(false);
+        return;
+      }
+
+      const fileSource = fileSourceRef.current;
+      fileSource?.startBufferingTracking((buffering) => {
+        setIsBuffering(buffering);
+        if (buffering) {
+          onWaiting();
+        } else {
+          onPlaying();
+        }
+      });
+
+      return () => {
+        fileSource?.stopBufferingTracking();
+      };
+    }, [onWaiting, onPlaying, playbackState, fileSourceRef]);
+
     useImperativeHandle(
       ref,
       () => ({
@@ -240,7 +279,7 @@ const Audio = React.memo(
         ready,
         setMuted: setMutedState,
         muted: effectiveMutedState,
-        playbackState,
+        playbackState: publicPlaybackState,
         currentTime,
         duration,
         autoPlay,
@@ -261,7 +300,7 @@ const Audio = React.memo(
         ready,
         setMutedState,
         effectiveMutedState,
-        playbackState,
+        publicPlaybackState,
         currentTime,
         duration,
         autoPlay,
diff --git a/packages/react-native-audio-api/src/Audio/Audio.web.tsx b/packages/react-native-audio-api/src/Audio/Audio.web.tsx
index e7bc1e37e..aaf4bf26a 100644
--- a/packages/react-native-audio-api/src/Audio/Audio.web.tsx
+++ b/packages/react-native-audio-api/src/Audio/Audio.web.tsx
@@ -37,6 +37,8 @@ const Audio = React.memo(
       onPlay,
       onPause,
       onVolumeChange,
+      onWaiting,
+      onPlaying,
     } = useStableAudioProps(props);
 
     const audioRef = useRef<HTMLAudioElement>(null);
@@ -45,8 +47,20 @@ const Audio = React.memo(
     const [ready, setReady] = useState(false);
     const [playbackState, setPlaybackState] =
       useState<AudioTagPlaybackState>('idle');
+    const [isBuffering, setIsBuffering] = useState(false);
     const [currentTime, setCurrentTime] = useState(0);
     const [duration, setDuration] = useState(0);
+
+    // See the native Audio.tsx's identical comment: kept derived rather than
+    // folded into playbackState so a stall starting/ending doesn't have to
+    // tear down whatever effect is watching playbackState.
+    const publicPlaybackState = useMemo<AudioTagPlaybackState>(
+      () =>
+        playbackState === 'playing' && isBuffering
+          ? 'buffering'
+          : playbackState,
+      [playbackState, isBuffering]
+    );
     const lastElementVolumeRef = useRef(muted ? 0 : volume);
 
     const effectiveMutedState = useMemo(() => {
@@ -205,7 +219,7 @@ const Audio = React.memo(
         volume: reportedVolumeState,
         setMuted,
         muted: effectiveMutedState,
-        playbackState,
+        playbackState: publicPlaybackState,
         currentTime,
         duration,
         autoPlay,
@@ -225,7 +239,7 @@ const Audio = React.memo(
         reportedVolumeState,
         setMuted,
         effectiveMutedState,
-        playbackState,
+        publicPlaybackState,
         currentTime,
         duration,
         autoPlay,
@@ -264,17 +278,27 @@ const Audio = React.memo(
               setPlaybackState((state) =>
                 state === 'playing' ? 'paused' : state
               );
+              setIsBuffering(false);
               onPause();
             }}
             onEnded={() => {
               setPlaybackState('idle');
               setCurrentTime(duration);
+              setIsBuffering(false);
               onEndedCallback();
             }}
             onError={() => {
               setReady(false);
               onError(new Error('Failed to load audio element source'));
             }}
+            onWaiting={() => {
+              setIsBuffering(true);
+              onWaiting();
+            }}
+            onPlaying={() => {
+              setIsBuffering(false);
+              onPlaying();
+            }}
           />
           {children}
         </View>
diff --git a/packages/react-native-audio-api/src/Audio/AudioFileSourceNode.ts b/packages/react-native-audio-api/src/Audio/AudioFileSourceNode.ts
index f6b90ebeb..9f3d9015a 100644
--- a/packages/react-native-audio-api/src/Audio/AudioFileSourceNode.ts
+++ b/packages/react-native-audio-api/src/Audio/AudioFileSourceNode.ts
@@ -106,9 +106,37 @@ export class AudioFileSourceNode extends AudioScheduledSourceNode {
     }
   }
 
+  startBufferingTracking(
+    onBufferingChange: (buffering: boolean) => void
+  ): void {
+    if (!this.node) {
+      return;
+    }
+    this.stopBufferingTracking();
+    const sub = this.emitter.addAudioEventListener(
+      'bufferingStateChanged',
+      (event) => {
+        onBufferingChange(event.value);
+      }
+    );
+    (this.node as IAudioFileSourceNode).onBufferingStateChanged =
+      sub.subscriptionId;
+  }
+
+  stopBufferingTracking(): void {
+    if (this.node) {
+      (this.node as IAudioFileSourceNode).onBufferingStateChanged = '0';
+    }
+  }
+
+  isBuffering(): boolean {
+    return (this.node as IAudioFileSourceNode).buffering;
+  }
+
   private resetNodeAndSubscriptions(): void {
     if (this.node) {
       (this.node as IAudioFileSourceNode).onPositionChanged = '0';
+      (this.node as IAudioFileSourceNode).onBufferingStateChanged = '0';
       (this.node as IAudioFileSourceNode).onEnded = '0';
       this.node.disconnect(undefined);
     }
diff --git a/packages/react-native-audio-api/src/Audio/types.ts b/packages/react-native-audio-api/src/Audio/types.ts
index b732e6c4c..e8c1786de 100644
--- a/packages/react-native-audio-api/src/Audio/types.ts
+++ b/packages/react-native-audio-api/src/Audio/types.ts
@@ -23,7 +23,13 @@ export type AudioSource = AudioURISource | AudioRequireSource | string;
 
 export type PreloadType = 'auto' | 'metadata' | 'none';
 
-export type AudioTagPlaybackState = 'idle' | 'playing' | 'paused';
+/**
+ * `'buffering'` is a sub-state of `'playing'`: playback was started and hasn't
+ * been paused/stopped, but the render thread is currently stalled waiting on
+ * decoded data (a real network/decoder stall, debounced natively against normal
+ * decode-ahead jitter — see `onWaiting`/`onPlaying`).
+ */
+export type AudioTagPlaybackState = 'idle' | 'playing' | 'paused' | 'buffering';
 
 export interface AudioTagHandle {
   play: () => void;
@@ -83,6 +89,18 @@ interface AudioEventProps {
   onPlay: TMPEmptyEventHandler;
   onPause: TMPEmptyEventHandler;
   onVolumeChange: TMPNumberEventHandler;
+  /**
+   * Fires when playback stalls waiting on decoded data — mirrors the HTML
+   * `<audio>`/`<video>` `waiting` event. Not fired for a deliberate pause/seek,
+   * only for a genuine stall while `playbackState === 'playing'`.
+   */
+  onWaiting: TMPEmptyEventHandler;
+  /**
+   * Fires when playback resumes after a stall reported via `onWaiting` —
+   * mirrors the HTML `<audio>`/`<video>` `playing` event. Not fired for the
+   * initial `play()` call — see `onPlay` for that.
+   */
+  onPlaying: TMPEmptyEventHandler;
 }
 
 export interface AudioPropsBase
diff --git a/packages/react-native-audio-api/src/Audio/utils.ts b/packages/react-native-audio-api/src/Audio/utils.ts
index 43486c7a4..801e79b8b 100644
--- a/packages/react-native-audio-api/src/Audio/utils.ts
+++ b/packages/react-native-audio-api/src/Audio/utils.ts
@@ -38,6 +38,8 @@ export function withPropsDefaults(
     onPlay: props.onPlay ?? noop,
     onPause: props.onPause ?? noop,
     onVolumeChange: props.onVolumeChange ?? noopNumber,
+    onWaiting: props.onWaiting ?? noop,
+    onPlaying: props.onPlaying ?? noop,
   };
 }
 
@@ -72,6 +74,8 @@ export function useStableAudioProps(props: AudioProps): AudioPropsBase {
     onPlay,
     onPause,
     onVolumeChange,
+    onWaiting,
+    onPlaying,
   } = withPropsDefaults(props, resolvedContext);
 
   return useMemo(
@@ -98,6 +102,8 @@ export function useStableAudioProps(props: AudioProps): AudioPropsBase {
       onPlay,
       onPause,
       onVolumeChange,
+      onWaiting,
+      onPlaying,
     }),
     [
       autoPlay,
@@ -119,6 +125,8 @@ export function useStableAudioProps(props: AudioProps): AudioPropsBase {
       onPlay,
       onPause,
       onVolumeChange,
+      onWaiting,
+      onPlaying,
     ]
   );
 }
diff --git a/packages/react-native-audio-api/src/events/types.ts b/packages/react-native-audio-api/src/events/types.ts
index 894b95877..2046821c7 100644
--- a/packages/react-native-audio-api/src/events/types.ts
+++ b/packages/react-native-audio-api/src/events/types.ts
@@ -7,6 +7,10 @@ export interface EventTypeWithValue {
   value: number;
 }
 
+export interface EventTypeWithBool {
+  value: boolean;
+}
+
 export type InterruptionType = 'began' | 'ended';
 
 export interface OnInterruptionEventType {
@@ -75,6 +79,14 @@ interface AudioAPIEvents {
   positionChanged: EventTypeWithValue;
   bufferEnded: OnBufferEndEventType;
   recorderError: OnRecorderErrorEventType;
+  /**
+   * Fires when an `<Audio>` source starts or stops stalling on decoded data — a
+   * real network/decoder stall (debounced natively against normal decode-ahead
+   * jitter), not a deliberate pause. `value` is true while stalled. See
+   * `AudioTagPlaybackState`'s `'buffering'` state and the
+   * `onWaiting`/`onPlaying` props on `<Audio>`.
+   */
+  bufferingStateChanged: EventTypeWithBool;
 }
 
 type AudioEvents = SystemEvents & AudioAPIEvents & NotificationEvents;
diff --git a/packages/react-native-audio-api/src/jsi-interfaces.ts b/packages/react-native-audio-api/src/jsi-interfaces.ts
index 6fb1e6d05..add528b12 100644
--- a/packages/react-native-audio-api/src/jsi-interfaces.ts
+++ b/packages/react-native-audio-api/src/jsi-interfaces.ts
@@ -243,11 +243,18 @@ export interface IAudioFileSourceNode extends IAudioScheduledSourceNode {
   readonly currentTime: number;
   readonly duration: number;
   readonly routedThroughMediaElement: boolean;
+  /**
+   * True once the render thread has gone without a decoded frame for longer
+   * than the native debounce interval — i.e. genuinely stalled, not just normal
+   * decode-ahead jitter. See `onBufferingStateChanged`.
+   */
+  readonly buffering: boolean;
   pause: () => void;
   seekToTime: (seconds: number) => void;
 
   // passing subscriptionId(uint_64 in cpp, string in js) to the cpp
   onPositionChanged: string;
+  onBufferingStateChanged: string;
 }
 
 export interface IMediaElementAudioSourceNode extends IAudioNode {}

From b34c0a635c03e26b2365c445e989a249ebce7a60 Mon Sep 17 00:00:00 2001
From: Gav Richards <gav@aiir.com>
Date: Wed, 19 Aug 2026 15:50:49 +0100
Subject: [PATCH 2/5] fix: keep Android AudioEvent.kt in sync with the C++ enum
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

android/.../AudioEvent.kt is a hand-maintained mirror of AudioEvent.h,
crossed via .ordinal at the JNI boundary (see PlaybackNotification.kt)
rather than referenced directly the way the iOS .mm files can. Missed
this when adding BUFFERING_STATE_CHANGE — caught by CI's
check-audio-enum-sync job.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../src/main/java/com/swmansion/audioapi/system/AudioEvent.kt    | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/react-native-audio-api/android/src/main/java/com/swmansion/audioapi/system/AudioEvent.kt b/packages/react-native-audio-api/android/src/main/java/com/swmansion/audioapi/system/AudioEvent.kt
index 72e02d5f0..398a93c0f 100644
--- a/packages/react-native-audio-api/android/src/main/java/com/swmansion/audioapi/system/AudioEvent.kt
+++ b/packages/react-native-audio-api/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,
 }

From c5f22ce98a7cca8e3363fdde523596e2c0f00ed8 Mon Sep 17 00:00:00 2001
From: michal <dydmichal@gmail.com>
Date: Thu, 20 Aug 2026 12:45:37 +0200
Subject: [PATCH 3/5] feat: docs, slight controls improvement

---
 .../src/examples/AudioTag/AudioTag.tsx        | 20 ++++++-
 packages/audiodocs/docs/sources/audio-tag.mdx | 17 ++++++
 .../src/Audio/controls/AudioControls.tsx      | 56 +++++++++++++++---
 .../src/Audio/controls/audioControlUtils.ts   | 57 ++++++++++++++++++-
 .../react-native-audio-api/src/Audio/index.ts |  1 +
 .../react-native-audio-api/src/Audio/utils.ts | 11 +++-
 6 files changed, 148 insertions(+), 14 deletions(-)

diff --git a/apps/common-app/src/examples/AudioTag/AudioTag.tsx b/apps/common-app/src/examples/AudioTag/AudioTag.tsx
index ad4d4ab6b..bd93eb055 100644
--- a/apps/common-app/src/examples/AudioTag/AudioTag.tsx
+++ b/apps/common-app/src/examples/AudioTag/AudioTag.tsx
@@ -16,8 +16,8 @@ import {
 
 import { Button, Container, Slider, Spacer } from '../../components';
 
-const DEMO_AUDIO_URL = 'https://filesamples.com/samples/audio/m4a/sample4.m4a';
-// const DEMO_AUDIO_URL = 'https://liveradio.timesa.pl/2980-1.aac/playlist.m3u8';
+// const DEMO_AUDIO_URL = 'https://filesamples.com/samples/audio/m4a/sample4.m4a';
+const DEMO_AUDIO_URL = 'https://liveradio.timesa.pl/2980-1.aac/playlist.m3u8';
 // const DEMO_AUDIO_URL = 'https://filesamples.com/samples/audio/mp3/sample4.mp3';
 
 const AudioTag: React.FC = () => {
@@ -96,6 +96,12 @@ const AudioTag: React.FC = () => {
   const handleVolumeEvent = useCallback((volume: number) => {
     // console.log('onVolumeChange', volume);
   }, []);
+  const handleWaiting = useCallback(() => {
+    console.log('onWaiting');
+  }, []);
+  const handlePlaying = useCallback(() => {
+    console.log('onPlaying');
+  }, []);
 
   const audioTagElement = useMemo(
     () => (
@@ -113,6 +119,8 @@ const AudioTag: React.FC = () => {
         onPlay={handlePlay}
         onPause={handlePause}
         onVolumeChange={handleVolumeEvent}
+        onWaiting={handleWaiting}
+        onPlaying={handlePlaying}
       />
     ),
     [
@@ -122,8 +130,10 @@ const AudioTag: React.FC = () => {
       handleLoadStart,
       handlePause,
       handlePlay,
+      handlePlaying,
       handlePositionChange,
       handleVolumeEvent,
+      handleWaiting,
     ]
   );
 
@@ -156,7 +166,11 @@ const AudioTag: React.FC = () => {
         </View>
         <Spacer.Vertical size={12} />
         <Button
-          title={!mediaElementRoute ? 'Route via MediaElement node' : 'Route without MediaElement node'}
+          title={
+            !mediaElementRoute
+              ? 'Route via MediaElement node'
+              : 'Route without MediaElement node'
+          }
           onPress={handleMediaElementRouteChange}
           width={screenWidth * 0.8}
         />
diff --git a/packages/audiodocs/docs/sources/audio-tag.mdx b/packages/audiodocs/docs/sources/audio-tag.mdx
index c4518aaf7..fd04764b1 100644
--- a/packages/audiodocs/docs/sources/audio-tag.mdx
+++ b/packages/audiodocs/docs/sources/audio-tag.mdx
@@ -58,6 +58,8 @@ Only **required** field is a `source`. Callbacks default to no-ops if omitted.
 | `onPlay` | `() => void` | no-op | After `play()`. |
 | `onPause` | `() => void` | no-op | After `pause()`. |
 | `onVolumeChange` | `(volume: number) => void` | no-op | When effective volume changes. |
+| `onWaiting` | `() => void` | no-op | Playback stalled waiting on decoded data (network/decoder). Mirrors the HTML `waiting` event — not fired for a deliberate pause or seek. |
+| `onPlaying` | `() => void` | no-op | Playback resumed after a stall reported by `onWaiting`. Mirrors the HTML `playing` event — not fired for the initial `play()`, see `onPlay`. |
 
 ### `AudioSource`
 
@@ -135,6 +137,21 @@ type AudioComponentContextType = {
 
 Useful for creating your custom UI component. Must be used under `<Audio>`. Throws an `Error` if used outside the provider.
 
+### `playbackState`
+
+`'idle' | 'playing' | 'paused' | 'buffering'`.
+
+`'buffering'` is a stall **during** playback, not a resting state: the user's play intent is still in effect, and playback resumes on its own once data arrives. A play/pause control must therefore treat it like `'playing'` — comparing against `'playing'` alone flips the button back to a play affordance mid-track. Use the exported `isPlaybackActive` helper instead of a direct comparison:
+
+```tsx
+import { isPlaybackActive } from 'react-native-audio-api';
+
+const { playbackState, play, pause } = useAudioTagContext();
+const isPlaying = isPlaybackActive(playbackState); // true while buffering too
+```
+
+The built-in `AudioControls` additionally runs an indeterminate sweep across the progress track while `playbackState === 'buffering'`.
+
 ```tsx
 import React from 'react';
 import { Button } from 'react-native';
diff --git a/packages/react-native-audio-api/src/Audio/controls/AudioControls.tsx b/packages/react-native-audio-api/src/Audio/controls/AudioControls.tsx
index 07043d25f..ac9e86eb1 100644
--- a/packages/react-native-audio-api/src/Audio/controls/AudioControls.tsx
+++ b/packages/react-native-audio-api/src/Audio/controls/AudioControls.tsx
@@ -8,15 +8,18 @@ import {
   Text,
   View,
 } from 'react-native';
+import type { LayoutChangeEvent } from 'react-native';
 import { Gesture, GestureDetector } from 'react-native-gesture-handler';
 import Animated, {
   useAnimatedRef,
   useSharedValue,
 } from 'react-native-reanimated';
 import { useAudioTagContext } from '../AudioTagContext';
+import { isPlaybackActive } from '../utils';
 import {
   formatTime,
   timeFromLocationX,
+  useBufferingSweep,
   useExpandableTrackHeight,
 } from './audioControlUtils';
 
@@ -29,6 +32,12 @@ const TRACK_BAR_HEIGHT = 12;
 const TRACK_BAR_HEIGHT_PRESSED = 18;
 const TRACK_BAR_ANIM_MS = 150;
 const SCRUB_PAN_MIN_DISTANCE = 8;
+const BUFFERING_SWEEP_MS = 1100;
+const BUFFERING_SWEEP_WIDTH_RATIO = 0.35;
+// Opacity ramp faking a soft-edged gradient band
+const BUFFERING_SWEEP_SLICE_OPACITIES = [
+  0.04, 0.18, 0.45, 0.6, 0.45, 0.18, 0.04,
+];
 
 const AudioControls: React.FC = () => {
   const {
@@ -52,6 +61,13 @@ const AudioControls: React.FC = () => {
   const [scrubTime, setScrubTime] = useState<number | null>(null);
   const progressTrackRef = useAnimatedRef<View>();
   const progressMetricsWidth = useSharedValue(0);
+  const isBuffering = playbackState === 'buffering';
+  const bufferingSweepStyle = useBufferingSweep(
+    isBuffering,
+    progressMetricsWidth,
+    BUFFERING_SWEEP_WIDTH_RATIO,
+    BUFFERING_SWEEP_MS
+  );
   const durationRef = useRef(duration);
   durationRef.current = duration;
 
@@ -141,20 +157,19 @@ const AudioControls: React.FC = () => {
   }, [onStart, onUpdate, onEnd, onCancel, onTapSeek]);
 
   const onPlayPausePress = useCallback(() => {
-    if (playbackState === 'playing') {
+    if (isPlaybackActive(playbackState)) {
       pause();
     } else {
       play();
     }
   }, [playbackState, pause, play]);
 
-  const onProgressTrackLayout = useCallback(() => {
-    progressTrackRef.current?.measureInWindow(
-      (_left: number, _y: number, width: number, _h: number) => {
-        progressMetricsWidth.value = width;
-      }
-    );
-  }, [progressMetricsWidth, progressTrackRef]);
+  const onProgressTrackLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      progressMetricsWidth.value = event.nativeEvent.layout.width;
+    },
+    [progressMetricsWidth]
+  );
 
   if (!ready) {
     return (
@@ -171,7 +186,7 @@ const AudioControls: React.FC = () => {
     <View style={styles.container}>
       <View style={styles.topRow}>
         <Pressable style={styles.playPause} onPress={onPlayPausePress}>
-          {playbackState === 'playing' ? (
+          {isPlaybackActive(playbackState) ? (
             <Image source={PauseIcon} style={{ width: 24, height: 24 }} />
           ) : (
             <Image source={PlayIcon} style={{ width: 24, height: 24 }} />
@@ -195,6 +210,18 @@ const AudioControls: React.FC = () => {
               <View
                 style={[styles.trackFill, { width: `${progress * 100}%` }]}
               />
+              {isBuffering && (
+                <Animated.View
+                  pointerEvents="none"
+                  style={[styles.bufferingSweep, bufferingSweepStyle]}>
+                  {BUFFERING_SWEEP_SLICE_OPACITIES.map((opacity, index) => (
+                    <View
+                      key={index}
+                      style={[styles.bufferingSweepSlice, { opacity }]}
+                    />
+                  ))}
+                </Animated.View>
+              )}
             </Animated.View>
           </View>
         </GestureDetector>
@@ -263,6 +290,17 @@ const styles = StyleSheet.create({
     height: '100%',
     backgroundColor: '#000',
   },
+  bufferingSweep: {
+    position: 'absolute',
+    top: 0,
+    bottom: 0,
+    left: 0,
+    flexDirection: 'row',
+  },
+  bufferingSweepSlice: {
+    flex: 1,
+    backgroundColor: '#000',
+  },
   volumeIcon: {
     padding: 4,
     marginRight: 12,
diff --git a/packages/react-native-audio-api/src/Audio/controls/audioControlUtils.ts b/packages/react-native-audio-api/src/Audio/controls/audioControlUtils.ts
index 7d758d8f3..fbc7aecc2 100644
--- a/packages/react-native-audio-api/src/Audio/controls/audioControlUtils.ts
+++ b/packages/react-native-audio-api/src/Audio/controls/audioControlUtils.ts
@@ -1,9 +1,13 @@
-import { useMemo } from 'react';
+import { useEffect, useMemo } from 'react';
 import {
+  cancelAnimation,
+  Easing,
   useSharedValue,
   useAnimatedStyle,
+  withRepeat,
   withTiming,
 } from 'react-native-reanimated';
+import type { SharedValue } from 'react-native-reanimated';
 
 export function formatTime(seconds: number): string {
   if (!Number.isFinite(seconds) || seconds < 0) {
@@ -65,3 +69,54 @@ export function useExpandableTrackHeight(
     ]
   );
 }
+
+/**
+ * Indeterminate buffering sweep: a highlight that repeatedly travels the width
+ * of the progress track while playback is stalled. It says "still waiting", not
+ * "this much is buffered" — there is no buffered-ahead figure behind it.
+ *
+ * `trackWidth` is a shared value because the track is measured on layout, after
+ * the first render.
+ */
+export function useBufferingSweep(
+  isBuffering: boolean,
+  trackWidth: SharedValue<number>,
+  sweepWidthRatio: number,
+  sweepDurationMs: number
+) {
+  const sweepProgress = useSharedValue(0);
+
+  useEffect(() => {
+    if (!isBuffering) {
+      return;
+    }
+
+    sweepProgress.value = withRepeat(
+      withTiming(1, {
+        duration: sweepDurationMs,
+        easing: Easing.inOut(Easing.quad),
+      }),
+      -1,
+      false
+    );
+
+    return () => {
+      cancelAnimation(sweepProgress);
+      sweepProgress.value = 0;
+    };
+  }, [isBuffering, sweepDurationMs, sweepProgress]);
+
+  return useAnimatedStyle(() => {
+    const sweepWidth = trackWidth.value * sweepWidthRatio;
+    // Travel the track plus the sweep's own width, starting one width off the
+    // left edge, so it slides fully in and fully out instead of popping.
+    const travelDistance = trackWidth.value + sweepWidth;
+
+    return {
+      width: sweepWidth,
+      transform: [
+        { translateX: -sweepWidth + sweepProgress.value * travelDistance },
+      ],
+    };
+  });
+}
diff --git a/packages/react-native-audio-api/src/Audio/index.ts b/packages/react-native-audio-api/src/Audio/index.ts
index 3bb1ba80a..7891d8abf 100644
--- a/packages/react-native-audio-api/src/Audio/index.ts
+++ b/packages/react-native-audio-api/src/Audio/index.ts
@@ -1,5 +1,6 @@
 export { default } from './Audio';
 export { useAudioTagContext } from './AudioTagContext';
+export { isPlaybackActive } from './utils';
 
 export type {
   AudioTagHandle,
diff --git a/packages/react-native-audio-api/src/Audio/utils.ts b/packages/react-native-audio-api/src/Audio/utils.ts
index 801e79b8b..37e7f7283 100644
--- a/packages/react-native-audio-api/src/Audio/utils.ts
+++ b/packages/react-native-audio-api/src/Audio/utils.ts
@@ -2,7 +2,16 @@ import { useMemo } from 'react';
 import { Image, Platform } from 'react-native';
 import AudioContext from '../core/AudioContext';
 import type BaseAudioContext from '../core/BaseAudioContext';
-import { AudioProps, AudioPropsBase, AudioSource } from './types';
+import {
+  AudioProps,
+  AudioPropsBase,
+  AudioSource,
+  AudioTagPlaybackState,
+} from './types';
+
+export function isPlaybackActive(state: AudioTagPlaybackState): boolean {
+  return state === 'playing' || state === 'buffering';
+}
 
 const noop = () => {};
 const noopError = (_error: Error) => {};

From f876cedaae93198fa3ceaaf09a2f696364793706 Mon Sep 17 00:00:00 2001
From: Gav Richards <gav@aiir.com>
Date: Thu, 20 Aug 2026 12:16:15 +0100
Subject: [PATCH 4/5] =?UTF-8?q?refactor:=20address=20review=20=E2=80=94=20?=
 =?UTF-8?q?extract=20BufferingStateDispatcher,=20drop=20unused=20poll=20ge?=
 =?UTF-8?q?tter?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per @mdydek's review on #1243:

- Extract the buffering-state debounce/dispatch logic out of
  AudioFileSourceNode into its own BufferingStateDispatcher class, mirroring
  PositionChangedDispatcher — AudioFileSourceNode now just calls
  bufferingStateDispatcher_.advance(hasData, framesToProcess) at each call
  site and no longer owns the EventCaller/atomic-bool/counter/threshold
  fields or the decision logic itself.
- Remove the buffering readonly getter end-to-end (jsi-interfaces.ts's
  IAudioFileSourceNode, the AudioFileSourceNodeHostObject JSI getter, and
  AudioFileSourceNode.ts's isBuffering()) since nothing consumed it — the
  design is event-driven (onWaiting/onPlaying), not poll-based. Kept
  AudioFileSourceNode::isBuffering() (C++-only, not JS-exposed) for tests.
- Tightened the JSDoc comments added in Audio/types.ts (and matching ones in
  events/types.ts) down to one line each.
- Replaced AudioFileSourceNodeTest.cpp (which drove the debounce logic
  through a test-only protected hook on the node) with
  BufferingStateDispatcherTest.cpp, testing the extracted class directly —
  same 7 cases, now against the class that actually owns the logic.

Verified: yarn typecheck, lint:js, lint:cpp, format:check:common all clean;
full C++ suite passes (394 tests, same count as before — 7
BufferingStateDispatcherTest cases replacing the 7 removed
AudioFileSourceNodeTest cases).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../sources/AudioFileSourceNodeHostObject.cpp |   7 +-
 .../sources/AudioFileSourceNodeHostObject.h   |   1 -
 .../core/sources/AudioFileSourceNode.cpp      |  35 +--
 .../core/sources/AudioFileSourceNode.h        |  37 +--
 .../utils/events/BufferingStateDispatcher.cpp |  49 ++++
 .../utils/events/BufferingStateDispatcher.h   |  42 ++++
 .../core/sources/AudioFileSourceNodeTest.cpp  | 234 ------------------
 .../utils/BufferingStateDispatcherTest.cpp    | 141 +++++++++++
 .../src/Audio/Audio.tsx                       |   7 +-
 .../src/Audio/AudioFileSourceNode.ts          |   4 -
 .../react-native-audio-api/src/Audio/types.ts |  16 +-
 .../src/events/types.ts                       |   8 +-
 .../src/jsi-interfaces.ts                     |   6 -
 13 files changed, 259 insertions(+), 328 deletions(-)
 create mode 100644 packages/react-native-audio-api/common/cpp/audioapi/utils/events/BufferingStateDispatcher.cpp
 create mode 100644 packages/react-native-audio-api/common/cpp/audioapi/utils/events/BufferingStateDispatcher.h
 delete mode 100644 packages/react-native-audio-api/common/cpp/test/src/core/sources/AudioFileSourceNodeTest.cpp
 create mode 100644 packages/react-native-audio-api/common/cpp/test/src/utils/BufferingStateDispatcherTest.cpp

diff --git a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/sources/AudioFileSourceNodeHostObject.cpp b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/sources/AudioFileSourceNodeHostObject.cpp
index 4b8adf11e..dba472257 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/sources/AudioFileSourceNodeHostObject.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/sources/AudioFileSourceNodeHostObject.cpp
@@ -35,8 +35,7 @@ AudioFileSourceNodeHostObject::AudioFileSourceNodeHostObject(
       JSI_EXPORT_PROPERTY_GETTER(AudioFileSourceNodeHostObject, loop),
       JSI_EXPORT_PROPERTY_GETTER(AudioFileSourceNodeHostObject, currentTime),
       JSI_EXPORT_PROPERTY_GETTER(AudioFileSourceNodeHostObject, duration),
-      JSI_EXPORT_PROPERTY_GETTER(AudioFileSourceNodeHostObject, routedThroughMediaElement),
-      JSI_EXPORT_PROPERTY_GETTER(AudioFileSourceNodeHostObject, buffering));
+      JSI_EXPORT_PROPERTY_GETTER(AudioFileSourceNodeHostObject, routedThroughMediaElement));
   addSetters(
       JSI_EXPORT_PROPERTY_SETTER(AudioFileSourceNodeHostObject, onPositionChanged),
       JSI_EXPORT_PROPERTY_SETTER(AudioFileSourceNodeHostObject, onBufferingStateChanged),
@@ -122,10 +121,6 @@ JSI_PROPERTY_GETTER_IMPL(AudioFileSourceNodeHostObject, routedThroughMediaElemen
   return {audioFileSourceNode_->isRoutedThroughMediaElement()};
 }
 
-JSI_PROPERTY_GETTER_IMPL(AudioFileSourceNodeHostObject, buffering) {
-  return {audioFileSourceNode_->isBuffering()};
-}
-
 JSI_HOST_FUNCTION_IMPL(AudioFileSourceNodeHostObject, pause) {
   auto event = [node = audioFileSourceNode_](BaseAudioContext &) {
     node->pause();
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/sources/AudioFileSourceNodeHostObject.h b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/sources/AudioFileSourceNodeHostObject.h
index 1e859e8e5..7d1997a93 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/sources/AudioFileSourceNodeHostObject.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/sources/AudioFileSourceNodeHostObject.h
@@ -25,7 +25,6 @@ class AudioFileSourceNodeHostObject : public AudioScheduledSourceNodeHostObject
   JSI_PROPERTY_GETTER_DECL(currentTime);
   JSI_PROPERTY_GETTER_DECL(duration);
   JSI_PROPERTY_GETTER_DECL(routedThroughMediaElement);
-  JSI_PROPERTY_GETTER_DECL(buffering);
 
   JSI_PROPERTY_SETTER_DECL(volume);
   JSI_PROPERTY_SETTER_DECL(playbackRate);
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.cpp b/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.cpp
index 8b74c96ac..1accdb7ea 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.cpp
@@ -35,8 +35,8 @@ AudioFileSourceNode::AudioFileSourceNode(
           context->getAudioEventHandlerRegistry(),
           static_cast<int>(context->getSampleRate() * ON_POSITION_CHANGED_INTERVAL),
           true),
-      onBufferingStateChangeEvent_(context->getAudioEventHandlerRegistry()),
-      bufferingStartThresholdFrames_(
+      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);
@@ -89,28 +89,7 @@ void AudioFileSourceNode::assignOnPositionChangedCallbackId(uint64_t callbackId)
 }
 
 void AudioFileSourceNode::assignOnBufferingStateChangeCallbackId(uint64_t callbackId) {
-  onBufferingStateChangeEvent_.assignCallbackId(callbackId);
-}
-
-void AudioFileSourceNode::updateBufferingState(bool hasData, int framesToProcess) {
-  if (!onBufferingStateChangeEvent_.hasCallback()) {
-    return;
-  }
-
-  if (hasData) {
-    starvedFrames_ = 0;
-    if (isBuffering_.exchange(false, std::memory_order_acq_rel)) {
-      onBufferingStateChangeEvent_.dispatchFromAudioThread(BoolValuePayload{.value = false});
-    }
-    return;
-  }
-
-  starvedFrames_ += framesToProcess;
-  if (!isBuffering_.load(std::memory_order_acquire) &&
-      starvedFrames_ >= bufferingStartThresholdFrames_) {
-    isBuffering_.store(true, std::memory_order_release);
-    onBufferingStateChangeEvent_.dispatchFromAudioThread(BoolValuePayload{.value = true});
-  }
+  bufferingStateDispatcher_.assignCallbackId(callbackId);
 }
 
 bool AudioFileSourceNode::initDecoder(
@@ -464,7 +443,7 @@ 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.
-  updateBufferingState(/* hasData */ true, 0);
+  bufferingStateDispatcher_.advance(/* hasData */ true, 0);
 }
 
 void AudioFileSourceNode::disable() {
@@ -472,7 +451,7 @@ void AudioFileSourceNode::disable() {
   filePaused_ = false;
   endOfStreamStopPending_ = false;
   endOfStreamDrainPending_ = false;
-  updateBufferingState(/* hasData */ true, 0);
+  bufferingStateDispatcher_.advance(/* hasData */ true, 0);
 
   AudioScheduledSourceNode::disable();
 }
@@ -753,12 +732,12 @@ void AudioFileSourceNode::processDecodedOutput(
   const bool hasFreshChunk = needsFreshDecoderChunk && readNextFrameChunk(incoming);
 
   if (!hasFreshChunk && pendingDecoderChunk_.size == 0) {
-    updateBufferingState(/* hasData */ false, framesToProcess);
+    bufferingStateDispatcher_.advance(/* hasData */ false, framesToProcess);
     processingBuffer->zero();
     return;
   }
 
-  updateBufferingState(/* hasData */ true, framesToProcess);
+  bufferingStateDispatcher_.advance(/* hasData */ true, framesToProcess);
 
   if (hasFreshChunk && incoming.state == StreamState::END_OF_STREAM) {
     currentTime_.store(duration_, std::memory_order_release);
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.h b/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.h
index 3d35dfdb8..48561858a 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.h
@@ -5,8 +5,8 @@
 #include <audioapi/decoding/SeekDecoderDaemon.h>
 #include <audioapi/decoding/backends/AudioDecoderBackend.h>
 #include <audioapi/dsp/WsolaTimeStretcher.h>
-#include <audioapi/events/EventCaller.hpp>
 #include <audioapi/types/NodeOptions.h>
+#include <audioapi/utils/events/BufferingStateDispatcher.h>
 #include <audioapi/utils/events/PositionChangedDispatcher.h>
 #include <cstddef>
 #include <thread>
@@ -26,10 +26,7 @@ class MediaElementAudioSourceNode;
 
 inline constexpr auto ON_POSITION_CHANGED_INTERVAL = 0.25f;
 
-/// @brief How long the render thread must go without a decoded frame before a
-/// buffering-state-change event fires. Debounces normal decode-ahead jitter
-/// (a single starved quantum is common and not a real stall) from a genuine
-/// network/decoder stall a UI would want to show a spinner for.
+/// @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.
@@ -129,28 +126,20 @@ class AudioFileSourceNode : public AudioScheduledSourceNode {
 
   void assignOnPositionChangedCallbackId(uint64_t callbackId);
 
-  /// @brief Registers the JS callback for buffering-state-change events (see
-  /// @ref updateBufferingState). Pass 0 to unregister.
+  /// @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.
+  /// 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 isBuffering_.load(std::memory_order_acquire);
+    return bufferingStateDispatcher_.isBuffering();
   }
 
  protected:
   void processNode(int framesToProcess) override;
 
-  /// @brief Debounces render-thread frame starvation into a buffering-state
-  /// event. @p hasData is true whenever this render quantum had a decoded
-  /// chunk available (fresh or previously stashed) to play; false when the
-  /// decoder daemon has nothing ready yet. Protected (rather than private)
-  /// so tests can drive it directly without racing the real decoder daemon
-  /// thread for genuine starvation — see AudioFileSourceNodeTest.cpp.
-  /// @note Audio thread only.
-  void updateBufferingState(bool hasData, int framesToProcess);
-
  private:
   std::shared_ptr<AudioFileDecoderState> decoderState_;
   /// @brief Decodes and mixes samples for direct or media-element playback.
@@ -204,15 +193,9 @@ class AudioFileSourceNode : public AudioScheduledSourceNode {
 
   PositionChangedDispatcher positionChanged_;
 
-  /// @brief Fired (audio thread) when the render thread starts/stops going
-  /// without decoded frames for longer than the debounce interval. See
-  /// @ref updateBufferingState.
-  EventCaller<AudioEvent::BUFFERING_STATE_CHANGE> onBufferingStateChangeEvent_;
-  std::atomic<bool> isBuffering_{false};
-  /// @brief Frames accumulated (at context sample rate) since the last frame
-  /// chunk was available. Reset whenever a chunk is obtained.
-  int starvedFrames_{0};
-  const int bufferingStartThresholdFrames_;
+  /// @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_.
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/utils/events/BufferingStateDispatcher.cpp b/packages/react-native-audio-api/common/cpp/audioapi/utils/events/BufferingStateDispatcher.cpp
new file mode 100644
index 000000000..356b13dc6
--- /dev/null
+++ b/packages/react-native-audio-api/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
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/utils/events/BufferingStateDispatcher.h b/packages/react-native-audio-api/common/cpp/audioapi/utils/events/BufferingStateDispatcher.h
new file mode 100644
index 000000000..3ababb45b
--- /dev/null
+++ b/packages/react-native-audio-api/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
diff --git a/packages/react-native-audio-api/common/cpp/test/src/core/sources/AudioFileSourceNodeTest.cpp b/packages/react-native-audio-api/common/cpp/test/src/core/sources/AudioFileSourceNodeTest.cpp
deleted file mode 100644
index a84a20db6..000000000
--- a/packages/react-native-audio-api/common/cpp/test/src/core/sources/AudioFileSourceNodeTest.cpp
+++ /dev/null
@@ -1,234 +0,0 @@
-#include <audioapi/core/OfflineAudioContext.h>
-#include <audioapi/core/destinations/AudioDestinationNode.h>
-#include <audioapi/core/sources/AudioFileSourceNode.h>
-#include <audioapi/events/AudioEventPayload.h>
-#include <audioapi/types/NodeOptions.h>
-#include <gmock/gmock.h>
-#include <gtest/gtest.h>
-#include <test/src/MockAudioEventHandlerRegistry.h>
-
-#include <cstdint>
-#include <memory>
-#include <vector>
-
-using namespace audioapi;
-
-// NOLINTBEGIN
-
-namespace {
-void appendU16LE(std::vector<uint8_t> &bytes, uint16_t value) {
-  bytes.push_back(static_cast<uint8_t>(value & 0xFF));
-  bytes.push_back(static_cast<uint8_t>((value >> 8) & 0xFF));
-}
-
-void appendU32LE(std::vector<uint8_t> &bytes, uint32_t value) {
-  bytes.push_back(static_cast<uint8_t>(value & 0xFF));
-  bytes.push_back(static_cast<uint8_t>((value >> 8) & 0xFF));
-  bytes.push_back(static_cast<uint8_t>((value >> 16) & 0xFF));
-  bytes.push_back(static_cast<uint8_t>((value >> 24) & 0xFF));
-}
-
-// Same fixture as MediaElementAudioSourceNodeTest.cpp — a tiny in-memory
-// PCM16 mono WAV, just enough for AudioFileSourceNode's decoder to open
-// successfully. The tests below exercise updateBufferingState() directly
-// rather than through real playback, since forcing genuine decoder-daemon
-// starvation deterministically would mean racing a real background thread.
-std::vector<uint8_t> makeTestWavPcm16Mono() {
-  constexpr uint16_t channels = 1;
-  constexpr uint32_t sampleRate = 44100;
-  constexpr uint16_t bitsPerSample = 16;
-  constexpr uint16_t bytesPerSample = bitsPerSample / 8;
-  constexpr uint16_t blockAlign = channels * bytesPerSample;
-  constexpr uint32_t byteRate = sampleRate * blockAlign;
-
-  const std::vector<int16_t> samples = {0, 16384, -16384, 8192};
-  const uint32_t dataChunkSize = static_cast<uint32_t>(samples.size() * sizeof(int16_t));
-  const uint32_t riffChunkSize = 36 + dataChunkSize;
-
-  std::vector<uint8_t> wav;
-  wav.reserve(44 + dataChunkSize);
-
-  wav.insert(wav.end(), {'R', 'I', 'F', 'F'});
-  appendU32LE(wav, riffChunkSize);
-  wav.insert(wav.end(), {'W', 'A', 'V', 'E'});
-
-  wav.insert(wav.end(), {'f', 'm', 't', ' '});
-  appendU32LE(wav, 16);
-  appendU16LE(wav, 1);
-  appendU16LE(wav, channels);
-  appendU32LE(wav, sampleRate);
-  appendU32LE(wav, byteRate);
-  appendU16LE(wav, blockAlign);
-  appendU16LE(wav, bitsPerSample);
-
-  wav.insert(wav.end(), {'d', 'a', 't', 'a'});
-  appendU32LE(wav, dataChunkSize);
-
-  const auto *sampleBytes = reinterpret_cast<const uint8_t *>(samples.data());
-  wav.insert(wav.end(), sampleBytes, sampleBytes + dataChunkSize);
-
-  return wav;
-}
-} // namespace
-
-class TestableAudioFileSourceNode : public AudioFileSourceNode {
- public:
-  using AudioFileSourceNode::AudioFileSourceNode;
-
-  void callUpdateBufferingState(bool hasData, int framesToProcess) {
-    updateBufferingState(hasData, framesToProcess);
-  }
-};
-
-class AudioFileSourceNodeTest : public ::testing::Test {
- protected:
-  static constexpr int kSampleRate = 44100;
-  // Mirrors ON_BUFFERING_STATE_DEBOUNCE_INTERVAL in AudioFileSourceNode.h.
-  static constexpr int kThresholdFrames =
-      static_cast<int>(kSampleRate * ON_BUFFERING_STATE_DEBOUNCE_INTERVAL);
-
-  std::shared_ptr<MockAudioEventHandlerRegistry> eventRegistry;
-  std::shared_ptr<OfflineAudioContext> context;
-  std::shared_ptr<AudioDestinationNode> destination;
-
-  void SetUp() override {
-    eventRegistry = std::make_shared<MockAudioEventHandlerRegistry>();
-    context = std::make_shared<OfflineAudioContext>(2, 5 * kSampleRate, kSampleRate, eventRegistry);
-    destination = std::make_shared<AudioDestinationNode>(context);
-    context->initialize(destination.get());
-  }
-
-  std::shared_ptr<TestableAudioFileSourceNode> createFileSource() {
-    AudioFileSourceOptions options;
-    options.data = makeTestWavPcm16Mono();
-    auto fileSource = std::make_shared<TestableAudioFileSourceNode>(context, options);
-    EXPECT_NE(fileSource, nullptr);
-    return fileSource;
-  }
-
-  static constexpr uint64_t kCallbackId = 42;
-};
-
-TEST_F(AudioFileSourceNodeTest, NoCallbackMeansNoDispatchRegardlessOfStarvation) {
-  auto fileSource = createFileSource();
-
-  EXPECT_CALL(*eventRegistry, dispatchEventFromAudioThread(testing::_, testing::_, testing::_))
-      .Times(0);
-
-  // Well past the debounce threshold, but no listener is registered.
-  fileSource->callUpdateBufferingState(false, kThresholdFrames * 2);
-
-  EXPECT_FALSE(fileSource->isBuffering());
-}
-
-TEST_F(AudioFileSourceNodeTest, StarvationBelowThresholdDoesNotDispatch) {
-  auto fileSource = createFileSource();
-  fileSource->assignOnBufferingStateChangeCallbackId(kCallbackId);
-
-  EXPECT_CALL(
-      *eventRegistry,
-      dispatchEventFromAudioThread(AudioEvent::BUFFERING_STATE_CHANGE, kCallbackId, testing::_))
-      .Times(0);
-
-  fileSource->callUpdateBufferingState(false, kThresholdFrames - 1);
-
-  EXPECT_FALSE(fileSource->isBuffering());
-}
-
-TEST_F(AudioFileSourceNodeTest, StarvationCrossingThresholdDispatchesTrueExactlyOnce) {
-  auto fileSource = createFileSource();
-  fileSource->assignOnBufferingStateChangeCallbackId(kCallbackId);
-
-  EXPECT_CALL(
-      *eventRegistry,
-      dispatchEventFromAudioThread(AudioEvent::BUFFERING_STATE_CHANGE, kCallbackId, testing::_))
-      .Times(1)
-      .WillOnce(testing::Invoke([](AudioEvent, uint64_t, AudioEventPayload payload) {
-        auto *boolPayload = std::get_if<BoolValuePayload>(&payload);
-        EXPECT_NE(boolPayload, nullptr);
-        EXPECT_TRUE(boolPayload->value);
-        return true;
-      }));
-
-  // Accumulates across calls, like consecutive starved render quanta would.
-  fileSource->callUpdateBufferingState(false, kThresholdFrames / 2);
-  fileSource->callUpdateBufferingState(false, kThresholdFrames / 2);
-  fileSource->callUpdateBufferingState(false, kThresholdFrames / 2);
-
-  EXPECT_TRUE(fileSource->isBuffering());
-}
-
-TEST_F(AudioFileSourceNodeTest, RecoveryDispatchesFalseImmediatelyWithNoDebounce) {
-  auto fileSource = createFileSource();
-  fileSource->assignOnBufferingStateChangeCallbackId(kCallbackId);
-
-  EXPECT_CALL(
-      *eventRegistry,
-      dispatchEventFromAudioThread(AudioEvent::BUFFERING_STATE_CHANGE, kCallbackId, testing::_))
-      .WillOnce(testing::Return(true))
-      .WillOnce(testing::Invoke([](AudioEvent, uint64_t, AudioEventPayload payload) {
-        auto *boolPayload = std::get_if<BoolValuePayload>(&payload);
-        EXPECT_NE(boolPayload, nullptr);
-        EXPECT_FALSE(boolPayload->value);
-        return true;
-      }));
-
-  fileSource->callUpdateBufferingState(false, kThresholdFrames * 2);
-  ASSERT_TRUE(fileSource->isBuffering());
-
-  // A single frame of real data recovers immediately — no symmetric debounce.
-  fileSource->callUpdateBufferingState(true, 1);
-
-  EXPECT_FALSE(fileSource->isBuffering());
-}
-
-TEST_F(AudioFileSourceNodeTest, HasDataWhileNotBufferingNeverDispatches) {
-  auto fileSource = createFileSource();
-  fileSource->assignOnBufferingStateChangeCallbackId(kCallbackId);
-
-  EXPECT_CALL(*eventRegistry, dispatchEventFromAudioThread(testing::_, testing::_, testing::_))
-      .Times(0);
-
-  for (int i = 0; i < 10; ++i) {
-    fileSource->callUpdateBufferingState(true, RENDER_QUANTUM_SIZE);
-  }
-
-  EXPECT_FALSE(fileSource->isBuffering());
-}
-
-TEST_F(AudioFileSourceNodeTest, IntermittentDataResetsStarvationCounter) {
-  auto fileSource = createFileSource();
-  fileSource->assignOnBufferingStateChangeCallbackId(kCallbackId);
-
-  EXPECT_CALL(*eventRegistry, dispatchEventFromAudioThread(testing::_, testing::_, testing::_))
-      .Times(0);
-
-  // Never accumulates enough consecutive starvation to cross the threshold,
-  // because a data quantum resets the counter each time — mirrors ordinary
-  // decode-ahead jitter rather than a real stall.
-  for (int i = 0; i < 20; ++i) {
-    fileSource->callUpdateBufferingState(false, kThresholdFrames - 1);
-    fileSource->callUpdateBufferingState(true, RENDER_QUANTUM_SIZE);
-  }
-
-  EXPECT_FALSE(fileSource->isBuffering());
-}
-
-TEST_F(AudioFileSourceNodeTest, PauseClearsBufferingStateWithoutStaleTrue) {
-  auto fileSource = createFileSource();
-  fileSource->assignOnBufferingStateChangeCallbackId(kCallbackId);
-
-  EXPECT_CALL(
-      *eventRegistry,
-      dispatchEventFromAudioThread(AudioEvent::BUFFERING_STATE_CHANGE, kCallbackId, testing::_))
-      .Times(2); // one true (starvation), one false (pause() resetting it)
-
-  fileSource->callUpdateBufferingState(false, kThresholdFrames * 2);
-  ASSERT_TRUE(fileSource->isBuffering());
-
-  fileSource->pause();
-
-  EXPECT_FALSE(fileSource->isBuffering());
-}
-
-// NOLINTEND
diff --git a/packages/react-native-audio-api/common/cpp/test/src/utils/BufferingStateDispatcherTest.cpp b/packages/react-native-audio-api/common/cpp/test/src/utils/BufferingStateDispatcherTest.cpp
new file mode 100644
index 000000000..f085d155f
--- /dev/null
+++ b/packages/react-native-audio-api/common/cpp/test/src/utils/BufferingStateDispatcherTest.cpp
@@ -0,0 +1,141 @@
+#include <audioapi/events/AudioEventPayload.h>
+#include <audioapi/utils/events/BufferingStateDispatcher.h>
+#include <gmock/gmock.h>
+#include <gtest/gtest.h>
+#include <test/src/MockAudioEventHandlerRegistry.h>
+
+#include <memory>
+
+using namespace audioapi;
+
+// NOLINTBEGIN
+
+namespace {
+constexpr uint64_t kCallbackId = 42;
+constexpr int kThresholdFrames = 6615; // 150ms @ 44100Hz, matching production usage
+} // namespace
+
+TEST(BufferingStateDispatcherTest, NoCallbackMeansNoDispatchRegardlessOfStarvation) {
+  auto registry = std::make_shared<MockAudioEventHandlerRegistry>();
+  BufferingStateDispatcher dispatcher(registry, kThresholdFrames);
+
+  EXPECT_CALL(*registry, dispatchEventFromAudioThread(testing::_, testing::_, testing::_)).Times(0);
+
+  // Well past the debounce threshold, but no listener is registered.
+  dispatcher.advance(/* hasData */ false, kThresholdFrames * 2);
+
+  EXPECT_FALSE(dispatcher.isBuffering());
+}
+
+TEST(BufferingStateDispatcherTest, StarvationBelowThresholdDoesNotDispatch) {
+  auto registry = std::make_shared<MockAudioEventHandlerRegistry>();
+  BufferingStateDispatcher dispatcher(registry, kThresholdFrames);
+  dispatcher.assignCallbackId(kCallbackId);
+
+  EXPECT_CALL(
+      *registry,
+      dispatchEventFromAudioThread(AudioEvent::BUFFERING_STATE_CHANGE, kCallbackId, testing::_))
+      .Times(0);
+
+  dispatcher.advance(/* hasData */ false, kThresholdFrames - 1);
+
+  EXPECT_FALSE(dispatcher.isBuffering());
+}
+
+TEST(BufferingStateDispatcherTest, StarvationCrossingThresholdDispatchesTrueExactlyOnce) {
+  auto registry = std::make_shared<MockAudioEventHandlerRegistry>();
+  BufferingStateDispatcher dispatcher(registry, kThresholdFrames);
+  dispatcher.assignCallbackId(kCallbackId);
+
+  EXPECT_CALL(
+      *registry,
+      dispatchEventFromAudioThread(AudioEvent::BUFFERING_STATE_CHANGE, kCallbackId, testing::_))
+      .Times(1)
+      .WillOnce(testing::Invoke([](AudioEvent, uint64_t, AudioEventPayload payload) {
+        auto *boolPayload = std::get_if<BoolValuePayload>(&payload);
+        EXPECT_NE(boolPayload, nullptr);
+        EXPECT_TRUE(boolPayload->value);
+        return true;
+      }));
+
+  // Accumulates across calls, like consecutive starved render quanta would.
+  dispatcher.advance(false, kThresholdFrames / 2);
+  dispatcher.advance(false, kThresholdFrames / 2);
+  dispatcher.advance(false, kThresholdFrames / 2);
+
+  EXPECT_TRUE(dispatcher.isBuffering());
+}
+
+TEST(BufferingStateDispatcherTest, RecoveryDispatchesFalseImmediatelyWithNoDebounce) {
+  auto registry = std::make_shared<MockAudioEventHandlerRegistry>();
+  BufferingStateDispatcher dispatcher(registry, kThresholdFrames);
+  dispatcher.assignCallbackId(kCallbackId);
+
+  EXPECT_CALL(
+      *registry,
+      dispatchEventFromAudioThread(AudioEvent::BUFFERING_STATE_CHANGE, kCallbackId, testing::_))
+      .WillOnce(testing::Return(true))
+      .WillOnce(testing::Invoke([](AudioEvent, uint64_t, AudioEventPayload payload) {
+        auto *boolPayload = std::get_if<BoolValuePayload>(&payload);
+        EXPECT_NE(boolPayload, nullptr);
+        EXPECT_FALSE(boolPayload->value);
+        return true;
+      }));
+
+  dispatcher.advance(false, kThresholdFrames * 2);
+  ASSERT_TRUE(dispatcher.isBuffering());
+
+  // A single frame of real data recovers immediately — no symmetric debounce.
+  dispatcher.advance(true, 1);
+
+  EXPECT_FALSE(dispatcher.isBuffering());
+}
+
+TEST(BufferingStateDispatcherTest, HasDataWhileNotBufferingNeverDispatches) {
+  auto registry = std::make_shared<MockAudioEventHandlerRegistry>();
+  BufferingStateDispatcher dispatcher(registry, kThresholdFrames);
+  dispatcher.assignCallbackId(kCallbackId);
+
+  EXPECT_CALL(*registry, dispatchEventFromAudioThread(testing::_, testing::_, testing::_)).Times(0);
+
+  for (int i = 0; i < 10; ++i) {
+    dispatcher.advance(true, 128);
+  }
+
+  EXPECT_FALSE(dispatcher.isBuffering());
+}
+
+TEST(BufferingStateDispatcherTest, IntermittentDataResetsStarvationCounter) {
+  auto registry = std::make_shared<MockAudioEventHandlerRegistry>();
+  BufferingStateDispatcher dispatcher(registry, kThresholdFrames);
+  dispatcher.assignCallbackId(kCallbackId);
+
+  EXPECT_CALL(*registry, dispatchEventFromAudioThread(testing::_, testing::_, testing::_)).Times(0);
+
+  // Never accumulates enough consecutive starvation to cross the threshold,
+  // because a data quantum resets the counter each time — mirrors ordinary
+  // decode-ahead jitter rather than a real stall.
+  for (int i = 0; i < 20; ++i) {
+    dispatcher.advance(false, kThresholdFrames - 1);
+    dispatcher.advance(true, 128);
+  }
+
+  EXPECT_FALSE(dispatcher.isBuffering());
+}
+
+TEST(BufferingStateDispatcherTest, AssignCallbackIdUnregistersPreviousCallback) {
+  auto registry = std::make_shared<MockAudioEventHandlerRegistry>();
+  BufferingStateDispatcher dispatcher(registry, kThresholdFrames);
+
+  testing::InSequence sequence;
+  EXPECT_CALL(*registry, unregisterHandler(AudioEvent::BUFFERING_STATE_CHANGE, kCallbackId))
+      .Times(1);
+  EXPECT_CALL(*registry, unregisterHandler(AudioEvent::BUFFERING_STATE_CHANGE, kCallbackId + 1))
+      .Times(1);
+
+  dispatcher.assignCallbackId(kCallbackId);
+  dispatcher.assignCallbackId(kCallbackId + 1);
+  EXPECT_EQ(dispatcher.getCallbackId(), kCallbackId + 1);
+}
+
+// NOLINTEND
diff --git a/packages/react-native-audio-api/src/Audio/Audio.tsx b/packages/react-native-audio-api/src/Audio/Audio.tsx
index 138e91e88..c78fea4ac 100644
--- a/packages/react-native-audio-api/src/Audio/Audio.tsx
+++ b/packages/react-native-audio-api/src/Audio/Audio.tsx
@@ -53,11 +53,8 @@ const Audio = React.memo(
     const [isBuffering, setIsBuffering] = useState(false);
     const [currentTime, setCurrentTime] = useState(0);
 
-    // 'buffering' is a UI-facing overlay on top of the 'playing' intent, not a
-    // fourth state tracked alongside it — see AudioTagPlaybackState's doc
-    // comment. Keeping it derived (rather than folding it into playbackState
-    // directly) avoids the buffering-subscription effect below tearing itself
-    // down every time a stall starts/ends.
+    // Derived rather than folded into playbackState directly, so the
+    // buffering-subscription effect below isn't torn down on every stall.
     const publicPlaybackState = useMemo<AudioTagPlaybackState>(
       () =>
         playbackState === 'playing' && isBuffering
diff --git a/packages/react-native-audio-api/src/Audio/AudioFileSourceNode.ts b/packages/react-native-audio-api/src/Audio/AudioFileSourceNode.ts
index 9f3d9015a..d8c97698f 100644
--- a/packages/react-native-audio-api/src/Audio/AudioFileSourceNode.ts
+++ b/packages/react-native-audio-api/src/Audio/AudioFileSourceNode.ts
@@ -129,10 +129,6 @@ export class AudioFileSourceNode extends AudioScheduledSourceNode {
     }
   }
 
-  isBuffering(): boolean {
-    return (this.node as IAudioFileSourceNode).buffering;
-  }
-
   private resetNodeAndSubscriptions(): void {
     if (this.node) {
       (this.node as IAudioFileSourceNode).onPositionChanged = '0';
diff --git a/packages/react-native-audio-api/src/Audio/types.ts b/packages/react-native-audio-api/src/Audio/types.ts
index e8c1786de..c77d18c30 100644
--- a/packages/react-native-audio-api/src/Audio/types.ts
+++ b/packages/react-native-audio-api/src/Audio/types.ts
@@ -24,10 +24,8 @@ export type AudioSource = AudioURISource | AudioRequireSource | string;
 export type PreloadType = 'auto' | 'metadata' | 'none';
 
 /**
- * `'buffering'` is a sub-state of `'playing'`: playback was started and hasn't
- * been paused/stopped, but the render thread is currently stalled waiting on
- * decoded data (a real network/decoder stall, debounced natively against normal
- * decode-ahead jitter — see `onWaiting`/`onPlaying`).
+ * `'buffering'` is a sub-state of `'playing'` — stalled on decoded data. See
+ * `onWaiting`/`onPlaying`.
  */
 export type AudioTagPlaybackState = 'idle' | 'playing' | 'paused' | 'buffering';
 
@@ -90,15 +88,13 @@ interface AudioEventProps {
   onPause: TMPEmptyEventHandler;
   onVolumeChange: TMPNumberEventHandler;
   /**
-   * Fires when playback stalls waiting on decoded data — mirrors the HTML
-   * `<audio>`/`<video>` `waiting` event. Not fired for a deliberate pause/seek,
-   * only for a genuine stall while `playbackState === 'playing'`.
+   * Fires on a genuine stall (not a deliberate pause) — mirrors HTML media's
+   * `waiting`.
    */
   onWaiting: TMPEmptyEventHandler;
   /**
-   * Fires when playback resumes after a stall reported via `onWaiting` —
-   * mirrors the HTML `<audio>`/`<video>` `playing` event. Not fired for the
-   * initial `play()` call — see `onPlay` for that.
+   * Fires when playback resumes after `onWaiting` — mirrors HTML media's
+   * `playing`.
    */
   onPlaying: TMPEmptyEventHandler;
 }
diff --git a/packages/react-native-audio-api/src/events/types.ts b/packages/react-native-audio-api/src/events/types.ts
index 2046821c7..34aff0d1a 100644
--- a/packages/react-native-audio-api/src/events/types.ts
+++ b/packages/react-native-audio-api/src/events/types.ts
@@ -79,13 +79,7 @@ interface AudioAPIEvents {
   positionChanged: EventTypeWithValue;
   bufferEnded: OnBufferEndEventType;
   recorderError: OnRecorderErrorEventType;
-  /**
-   * Fires when an `<Audio>` source starts or stops stalling on decoded data — a
-   * real network/decoder stall (debounced natively against normal decode-ahead
-   * jitter), not a deliberate pause. `value` is true while stalled. See
-   * `AudioTagPlaybackState`'s `'buffering'` state and the
-   * `onWaiting`/`onPlaying` props on `<Audio>`.
-   */
+  /** `value` is true while an `<Audio>` source is stalled on decoded data. */
   bufferingStateChanged: EventTypeWithBool;
 }
 
diff --git a/packages/react-native-audio-api/src/jsi-interfaces.ts b/packages/react-native-audio-api/src/jsi-interfaces.ts
index f3f7ce06e..9a9a2a552 100644
--- a/packages/react-native-audio-api/src/jsi-interfaces.ts
+++ b/packages/react-native-audio-api/src/jsi-interfaces.ts
@@ -241,12 +241,6 @@ export interface IAudioFileSourceNode extends IAudioScheduledSourceNode {
   readonly currentTime: number;
   readonly duration: number;
   readonly routedThroughMediaElement: boolean;
-  /**
-   * True once the render thread has gone without a decoded frame for longer
-   * than the native debounce interval — i.e. genuinely stalled, not just normal
-   * decode-ahead jitter. See `onBufferingStateChanged`.
-   */
-  readonly buffering: boolean;
   pause: () => void;
   seekToTime: (seconds: number) => void;
 

From 8c4caeaf1badce813c708e2888dd26547b16cec8 Mon Sep 17 00:00:00 2001
From: michal <dydmichal@gmail.com>
Date: Thu, 20 Aug 2026 14:13:05 +0200
Subject: [PATCH 5/5] feat: final polish

---
 apps/common-app/src/examples/AudioTag/AudioTag.tsx        | 8 ++++----
 .../src/Audio/AudioFileSourceNode.ts                      | 2 ++
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/apps/common-app/src/examples/AudioTag/AudioTag.tsx b/apps/common-app/src/examples/AudioTag/AudioTag.tsx
index bd93eb055..42ad9806f 100644
--- a/apps/common-app/src/examples/AudioTag/AudioTag.tsx
+++ b/apps/common-app/src/examples/AudioTag/AudioTag.tsx
@@ -16,8 +16,8 @@ import {
 
 import { Button, Container, Slider, Spacer } from '../../components';
 
-// const DEMO_AUDIO_URL = 'https://filesamples.com/samples/audio/m4a/sample4.m4a';
-const DEMO_AUDIO_URL = 'https://liveradio.timesa.pl/2980-1.aac/playlist.m3u8';
+const DEMO_AUDIO_URL = 'https://filesamples.com/samples/audio/m4a/sample4.m4a';
+// const DEMO_AUDIO_URL = 'https://liveradio.timesa.pl/2980-1.aac/playlist.m3u8';
 // const DEMO_AUDIO_URL = 'https://filesamples.com/samples/audio/mp3/sample4.mp3';
 
 const AudioTag: React.FC = () => {
@@ -97,10 +97,10 @@ const AudioTag: React.FC = () => {
     // console.log('onVolumeChange', volume);
   }, []);
   const handleWaiting = useCallback(() => {
-    console.log('onWaiting');
+    // console.log('onWaiting');
   }, []);
   const handlePlaying = useCallback(() => {
-    console.log('onPlaying');
+    // console.log('onPlaying');
   }, []);
 
   const audioTagElement = useMemo(
diff --git a/packages/react-native-audio-api/src/Audio/AudioFileSourceNode.ts b/packages/react-native-audio-api/src/Audio/AudioFileSourceNode.ts
index d8c97698f..2f82eccac 100644
--- a/packages/react-native-audio-api/src/Audio/AudioFileSourceNode.ts
+++ b/packages/react-native-audio-api/src/Audio/AudioFileSourceNode.ts
@@ -42,7 +42,9 @@ export class AudioFileSourceNode extends AudioScheduledSourceNode {
     if (!(this.node as IAudioFileSourceNode).routedThroughMediaElement) {
       this.connect(this.context.destination);
     }
+    // copied from audioscheduledsourcenode, so it can bypass requirement of being started only once
     (this.node as IAudioScheduledSourceNode).start(this.context.currentTime);
+    this.context.markRunningOnSourceStart();
   }
 
   pause(): void {