fix: AudioContext::resume reanimates the failed Oboe stream due to the change in AudioPlayer::resume

.claude/skills/thread-safety-itc/SKILL.md

@@ -166,7 +166,9 @@ Control-plane synchronization uses two layers — both are non-recursive `std::m
 
 On Android, `AudioPlayer::onErrorAfterClose` also takes `driverMutex_` because Oboe error callbacks bypass `AudioContext`.
 
-**Live `AudioContext` render quiescence:** `currentRenders_` on `AudioContext` is incremented at the start of each platform I/O callback (`IOSAudioPlayer::deliverOutputBuffers` / `AudioPlayer::onAudioReady`) via a reference passed in `initialize()`, and decremented when the callback returns (RAII scope). `suspend()` and `close()` call `waitForRenderQuiescence()` (under `driverMutex_`) before `processAudioEvents()` / `cleanup()`. Platform drivers share the `CommonPlayer` abstract base (`common/cpp/audioapi/core/CommonPlayer.h`).
+**Live `AudioContext` render quiescence:** `currentRenders_` on `AudioContext` is incremented at the start of each platform I/O callback (`IOSAudioPlayer::deliverOutputBuffers` / `AudioPlayer::onAudioReady`) via a reference passed in `initialize()`, and decremented when the callback returns (RAII scope). `suspend()` and `close()` call `waitForRenderQuiescence()` (under `driverMutex_`) before `processAudioEvents()` / `cleanup()`. `NodeAudioPlayer` (WPT harness) receives the same reference but never opens a render scope.
+
+**Player base class:** all three drivers (`AudioPlayer` on Android, `IOSAudioPlayer`, `NodeAudioPlayer` in `wpt_tests/src/`) derive from `CommonPlayer` (`common/cpp/audioapi/core/CommonPlayer.h`). It owns the shared driver state as protected members: `renderAudio_`, `renderBuffer_` (one render quantum, allocated once in the constructor), `sampleRate_`, `channelCount_`, `currentRenders_`, `context_`, `driverMutex_`, and `isRunning_`. It also takes one constructor signature for every platform, so `AudioContext::initialize()` builds a single `PlatformAudioPlayer` alias. Render through `renderNormalizedQuantum()`, which keeps the output peak-limiting in the player so offline renders are never limited. `AudioPlayerTests.mm` (fabric-example XCTest) hand-copies `IOSAudioPlayer`'s member layout to reach its private members, so any change to `IOSAudioPlayer`'s data members must also be made there.
 
 **Graph producer self-drain:** `Graph::enableProducerSelfDrain()` makes producer threads drain the event channels themselves after each enqueue; `disableProducerSelfDrain()` hands consumption back to the audio/render thread. Both flush the channels internally (no separate `processEvents()` call needed) and serialize with in-flight drains via `selfDrainMutex_`, because two producers can drain concurrently: the JS thread (mutations) and the GC finalizer thread (`removeNode`, which self-drains after its Channel B orphan send — otherwise a finalizer burst with no consumer fills the bounded channel and blocks forever, e.g. at process exit). Enable only when there is no audio/render consumer (realtime: construction + after `suspend`/`close` quiescence; offline: before `startRendering` and after a scheduled suspend); disable *before* starting the audio/render consumer; re-enable if start/resume fails.
 

apps/fabric-example/ios/FabricExampleTests/AudioEngineTests.mm

@@ -329,7 +329,8 @@ - (NSString *)attachSourceNodeToAudioEngine {
   return [self.audioEngine
       attachSourceNodeWithRenderBlock:[self testSourceRenderBlock]
                            sampleRate:44100
-                         channelCount:2];
+                         channelCount:2
+             onOutputRecoveryFailed:nil];
 }
 
 - (void)testCleanupDestroysInternalEngineAndResetsStateAndDeactivatesSession {
@@ -370,7 +371,8 @@ - (void)testAttachSourceNodeStoresAndConnectsSource {
   NSString *sourceNodeId = [self.audioEngine
       attachSourceNodeWithRenderBlock:[self testSourceRenderBlock]
                            sampleRate:44100
-                         channelCount:2];
+                         channelCount:2
+             onOutputRecoveryFailed:nil];
   AVAudioSourceNode *sourceNode = self.audioEngine.sourceNodes[sourceNodeId];
   AVAudioFormat *format = self.audioEngine.sourceFormats[sourceNodeId];
 

apps/fabric-example/ios/FabricExampleTests/AudioPlayerTests.mm

@@ -12,6 +12,7 @@
 #include <cstddef>
 #include <functional>
 #include <memory>
+#include <mutex>
 #include <utility>
 #include <vector>
 
@@ -25,7 +26,9 @@
       const std::function<void(DSPAudioBuffer *, int)> &renderAudio,
       float sampleRate,
       int channelCount,
-      std::atomic<uint32_t> &currentRenders);
+      std::atomic<uint32_t> &currentRenders,
+      std::weak_ptr<AudioContext> context,
+      std::mutex *driverMutex);
   ~IOSAudioPlayer() override;
 
   bool start() override;
@@ -40,13 +43,7 @@
   [[nodiscard]] double getOutputLatency() const override;
 
  protected:
-  std::shared_ptr<DSPAudioBuffer> audioBuffer_;
   NativeAudioPlayer *audioPlayer_;
-  float sampleRate_;
-  std::function<void(DSPAudioBuffer *, int)> renderAudio_;
-  std::atomic<uint32_t> &currentRenders_;
-  int channelCount_;
-  std::atomic<bool> isRunning_;
   std::atomic<bool> flushOverflowNextPull_;
   int pendingSavedCount_;
   DSPAudioBuffer pendingSaved_;
@@ -159,6 +156,7 @@ - (void)stopIfPossible
 - (NSString *)attachSourceNodeWithRenderBlock:(AVAudioSourceNodeRenderBlock)renderBlock
                                    sampleRate:(float)sampleRate
                                  channelCount:(AVAudioChannelCount)channelCount
+                     onOutputRecoveryFailed:(OnOutputRecoveryFailedBlock)onOutputRecoveryFailed
 {
   self.attachSourceNodeCallCount += 1;
   self.lastAttachedRenderBlock = renderBlock;
@@ -235,7 +233,13 @@ - (void)cleanup
       float sampleRate,
       int channelCount)
       : currentRendersStorage_(0),
-        IOSAudioPlayer(renderAudio, sampleRate, channelCount, currentRendersStorage_) {}
+        IOSAudioPlayer(
+            renderAudio,
+            sampleRate,
+            channelCount,
+            currentRendersStorage_,
+            std::weak_ptr<AudioContext>{},
+            nullptr) {}
 
   NativeAudioPlayer *replaceAudioPlayer(NativeAudioPlayer *audioPlayer) {
     NativeAudioPlayer *previous = audioPlayer_;
@@ -248,7 +252,7 @@ - (void)cleanup
   }
 
   std::shared_ptr<DSPAudioBuffer> getAudioBuffer() const {
-    return audioBuffer_;
+    return renderBuffer_;
   }
 
   void setRunning(bool isRunning) {

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

@@ -75,3 +75,21 @@ Resumes a previously suspended audio context.
 
 Inherits [`onstatechange`](./base-audio-context.mdx#onstatechange) from [`BaseAudioContext`](./base-audio-context.mdx#events); `close`, `suspend` and `resume` each fire it once their returned promise has resolved.
 
+### `onerror`
+
+Sets (or removes, when `null` is assigned) a callback fired when the live output stream fails natively and cannot keep rendering — for example after the audio device disconnects or the OS audio service dies while the context is running.
+
+
+Typical recovery is to call [`resume`](./audio-context.mdx#resume) from the handler (or recreate the context). A short delay before `resume` gives the OS audio server time to recover from some errors, e.g. hardware errors, and prevents rapid retry loops.
+
+```tsx
+const audioContext = new AudioContext();
+
+audioContext.onerror = () => {
+  console.error('Audio output failed');
+  setTimeout(() => {
+    void audioContext.resume();
+  }, 2000);
+};
+```
+

packages/react-native-audio-api/android/src/main/cpp/audioapi/android/core/AudioPlayer.cpp

@@ -4,30 +4,17 @@
 #include <audioapi/core/utils/Constants.h>
 #include <audioapi/core/utils/CurrentRenderScope.h>
 #include <audioapi/utils/AudioArray.hpp>
+#include <audioapi/utils/Macros.h>
 
 #include <jni.h>
 
 #include <algorithm>
+#include <cstddef>
 #include <memory>
 #include <mutex>
 
 namespace audioapi {
 
-AudioPlayer::AudioPlayer(
-    const std::function<void(DSPAudioBuffer *, int)> &renderAudio,
-    float sampleRate,
-    int channelCount,
-    std::mutex *driverMutex,
-    const std::shared_ptr<AudioContext> &context,
-    std::atomic<uint32_t> &currentRenders)
-    : renderAudio_(renderAudio),
-      currentRenders_(currentRenders),
-      sampleRate_(sampleRate),
-      channelCount_(channelCount),
-      isRunning_(false),
-      driverMutex_(driverMutex),
-      context_(context) {}
-
 bool AudioPlayer::openAudioStream() {
   std::scoped_lock lock(streamMutex_);
   AudioStreamBuilder builder;
@@ -50,17 +37,20 @@ bool AudioPlayer::openAudioStream() {
     return false;
   }
 
-  buffer_ = std::make_shared<DSPAudioBuffer>(RENDER_QUANTUM_SIZE, channelCount_, sampleRate_);
   isInitialized_.store(true, std::memory_order_release);
   return true;
 }
 
+bool AudioPlayer::rebuildStream() {
+  cleanup();
+  return openAudioStream();
+}
+
 bool AudioPlayer::start() {
   std::scoped_lock lock(streamMutex_);
-  if (!isInitialized_.load(std::memory_order_acquire)) {
-    if (!openAudioStream()) {
-      return false;
-    }
+
+  if ((!isInitialized_.load(std::memory_order_acquire)) && (!openAudioStream())) {
+    return false;
   }
 
   if (mStream_ != nullptr) {
@@ -87,6 +77,11 @@ bool AudioPlayer::resume() {
     return true;
   }
 
+  // The stream may have been dropped by onErrorAfterClose while suspended.
+  if ((!isInitialized_.load(std::memory_order_acquire)) && (!openAudioStream())) {
+    return false;
+  }
+
   if (mStream_ != nullptr) {
     auto result = mStream_->requestStart() == oboe::Result::OK;
     isRunning_.store(result, std::memory_order_release);
@@ -139,34 +134,66 @@ AudioPlayer::onAudioReady(AudioStream *oboeStream, void *audioData, int32_t numF
     auto framesToProcess = std::min(numFrames - processedFrames, RENDER_QUANTUM_SIZE);
 
     if (isRunning_.load(std::memory_order_acquire)) {
-      renderAudio_(buffer_.get(), framesToProcess);
-      // Peak-normalize the rendered quantum before it reaches the hardware.
-      // This limiting lives in the player (not the destination node) so
-      // offline renders stay spec-accurate.
-      buffer_->normalize();
+      renderNormalizedQuantum(framesToProcess);
     } else {
-      buffer_->zero();
+      renderBuffer_->zero();
     }
 
-    float *destination = buffer + (processedFrames * channelCount_);
+    float *destination = buffer + (static_cast<ptrdiff_t>(processedFrames * channelCount_));
 
-    buffer_->interleaveTo(destination, framesToProcess);
+    renderBuffer_->interleaveTo(destination, framesToProcess);
     processedFrames += framesToProcess;
   }
 
   return DataCallbackResult::Continue;
 }
 
+namespace {
+struct ReentrancyGuard {
+  DELETE_COPY_AND_MOVE(ReentrancyGuard);
+  explicit ReentrancyGuard(bool *f) : flag(f) {
+    *flag = true;
+  }
+  ~ReentrancyGuard() {
+    *flag = false;
+  }
+
+ private:
+  bool *flag;
+};
+} // namespace
+
 void AudioPlayer::onErrorAfterClose(oboe::AudioStream *stream, oboe::Result error) {
-  if (error != oboe::Result::ErrorDisconnected || driverMutex_ == nullptr) {
+  if (driverMutex_ == nullptr) {
+    return;
+  }
+
+  switch (error) {
+    case oboe::Result::ErrorDisconnected:
+    case oboe::Result::ErrorTimeout:
+    case oboe::Result::ErrorInternal:
+    case oboe::Result::ErrorNoService:
+      break;
+    default:
+      return;
+  }
+
+  // Reentrancy guard - prevent recursive calls to onErrorAfterClose.
+  static thread_local bool isInsideOnError = false;
+  if (isInsideOnError) {
+    return;
+  }
+  ReentrancyGuard guard(&isInsideOnError);
+
+  auto context = context_.lock();
+  if (context == nullptr) {
     return;
   }
 
   // Serialize with start()/resume()/suspend()/close() on the JS / promise-pool threads.
   std::scoped_lock lock(*driverMutex_, streamMutex_);
 
-  auto context = context_.lock();
-  if (context == nullptr || context->isClosed()) {
+  if (context->isClosed()) {
     return;
   }
 
@@ -176,10 +203,30 @@ void AudioPlayer::onErrorAfterClose(oboe::AudioStream *stream, oboe::Result erro
     return;
   }
 
-  cleanup();
-  if (openAudioStream()) {
-    resume();
+  // Check if the stream was expected to be running when the error occurred
+  const bool wasRunning = isRunning_.load(std::memory_order_acquire);
+
+  // Best effort rebuild; a suspended context keeps the rebuilt stream paused until resume().
+  if (error == oboe::Result::ErrorDisconnected && rebuildStream()) {
+    if (!wasRunning) {
+      return;
+    }
+    if (mStream_->requestStart() == oboe::Result::OK) {
+      isRunning_.store(true, std::memory_order_release);
+      return;
+    }
+  }
+
+  isRunning_.store(false, std::memory_order_release);
+
+  if (!wasRunning) {
+    // Nothing was playing, so there is no failure to report: drop the dead stream
+    // and let resume() open a new one.
+    cleanup();
+    return;
   }
+
+  context->onStreamFail();
 }
 
 double AudioPlayer::getBaseLatency() const {

packages/react-native-audio-api/android/src/main/cpp/audioapi/android/core/AudioPlayer.h

@@ -5,31 +5,21 @@
 #include <atomic>
 #include <cassert>
 #include <cstdint>
-#include <functional>
 #include <memory>
 #include <mutex>
 
 #include <audioapi/core/CommonPlayer.h>
-#include <audioapi/utils/AudioBuffer.hpp>
 
 namespace audioapi {
 
 using namespace oboe;
 
-class AudioContext;
-
 class AudioPlayer : public CommonPlayer,
                     public AudioStreamDataCallback,
                     public AudioStreamErrorCallback,
                     public std::enable_shared_from_this<AudioPlayer> {
  public:
-  AudioPlayer(
-      const std::function<void(DSPAudioBuffer *, int)> &renderAudio,
-      float sampleRate,
-      int channelCount,
-      std::mutex *driverMutex,
-      const std::shared_ptr<AudioContext> &context,
-      std::atomic<uint32_t> &currentRenders);
+  using CommonPlayer::CommonPlayer;
 
   ~AudioPlayer() override {
     cleanup();
@@ -54,21 +44,14 @@ class AudioPlayer : public CommonPlayer,
   void onErrorAfterClose(AudioStream *audioStream, Result error) override;
 
  private:
-  std::function<void(DSPAudioBuffer *, int)> renderAudio_;
-  std::atomic<uint32_t> &currentRenders_;
   std::shared_ptr<AudioStream> mStream_;
   mutable std::recursive_mutex streamMutex_;
-  std::shared_ptr<DSPAudioBuffer> buffer_;
   std::atomic<bool> isInitialized_{false};
-  float sampleRate_;
-  int channelCount_;
-  std::atomic<bool> isRunning_;
   /// Updated on the audio thread from each Oboe callback `numFrames`.
   std::atomic<int32_t> lastCallbackFrameCount_{0};
-  std::mutex *driverMutex_;
-  std::weak_ptr<AudioContext> context_;
 
   bool openAudioStream();
+  bool rebuildStream();
 };
 
 } // namespace audioapi

packages/react-native-audio-api/android/src/main/java/com/swmansion/audioapi/system/AudioEvent.kt

@@ -27,4 +27,5 @@ enum class AudioEvent {
   RECORDER_ERROR,
   BUFFERING_STATE_CHANGE,
   STATE_CHANGE,
+  CONTEXT_ERROR,
 }

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

@@ -20,13 +20,18 @@ AudioContextHostObject::AudioContextHostObject(
           callInvoker) {
   addGetters(JSI_EXPORT_PROPERTY_GETTER(AudioContextHostObject, outputLatency));
   addGetters(JSI_EXPORT_PROPERTY_GETTER(AudioContextHostObject, baseLatency));
+  addSetters(JSI_EXPORT_PROPERTY_SETTER(AudioContextHostObject, onerror));
   addFunctions(
       JSI_EXPORT_FUNCTION(AudioContextHostObject, close),
       JSI_EXPORT_FUNCTION(AudioContextHostObject, resume),
       JSI_EXPORT_FUNCTION(AudioContextHostObject, suspend),
       JSI_EXPORT_FUNCTION(AudioContextHostObject, createMediaElementSource));
 }
 
+AudioContextHostObject::~AudioContextHostObject() {
+  std::static_pointer_cast<AudioContext>(context_)->assignOnErrorCallbackId(0);
+}
+
 JSI_HOST_FUNCTION_IMPL(AudioContextHostObject, close) {
   return promiseVendor_->createPromise([this](Promise &&promise) {
     auto contextPromise = ContextPromiseResolver<void>::makeContextPromiseResolver(
@@ -78,4 +83,9 @@ JSI_HOST_FUNCTION_IMPL(AudioContextHostObject, createMediaElementSource) {
   return object;
 }
 
+JSI_PROPERTY_SETTER_IMPL(AudioContextHostObject, onerror) {
+  auto audioContext = std::static_pointer_cast<AudioContext>(context_);
+  audioContext->assignOnErrorCallbackId(std::stoull(value.getString(runtime).utf8(runtime)));
+}
+
 } // namespace audioapi