Support routing changed callback. (#2348)

flamme · web-flow · commit 4bbb56366058 · 2026-03-12T20:52:10.000-07:00
* Support routing changed callback. Fixes #2347.
diff --git a/apps/OboeTester/app/src/main/cpp/NativeAudioContext.cpp b/apps/OboeTester/app/src/main/cpp/NativeAudioContext.cpp
@@ -929,12 +929,22 @@ void ActivityDataPath::finishOpen(bool isInput, std::shared_ptr<oboe::AudioStrea
 }
 
 // =================================================================== ActivityTestDisconnect
+ActivityTestDisconnect::ActivityTestDisconnect() {
+    mRoutingCallback = std::make_shared<TestRoutingCallback>(this);
+}
+
 void ActivityTestDisconnect::close(int32_t streamIndex) {
     ActivityContext::close(streamIndex);
     mSinkFloat.reset();
 }
 
+void ActivityTestDisconnect::configureBuilder(bool isInput, oboe::AudioStreamBuilder &builder) {
+    ActivityContext::configureBuilder(isInput, builder);
+    builder.setRoutingCallback(mRoutingCallback);
+}
+
 void ActivityTestDisconnect::configureAfterOpen() {
+    mRoutingChangedCount = 0;
     std::shared_ptr<oboe::AudioStream> outputStream = getOutputStream();
     std::shared_ptr<oboe::AudioStream> inputStream = getInputStream();
     if (outputStream) {
diff --git a/apps/OboeTester/app/src/main/cpp/NativeAudioContext.h b/apps/OboeTester/app/src/main/cpp/NativeAudioContext.h
@@ -813,7 +813,7 @@ class ActivityDataPath : public ActivityFullDuplex {
  */
 class ActivityTestDisconnect : public ActivityContext {
 public:
-    ActivityTestDisconnect() {}
+    ActivityTestDisconnect();
 
     virtual ~ActivityTestDisconnect() = default;
 
@@ -832,9 +832,35 @@ class ActivityTestDisconnect : public ActivityContext {
         return oboe::Result::ErrorNull;
     }
 
+    void configureBuilder(bool isInput, oboe::AudioStreamBuilder &builder) override;
+
     void configureAfterOpen() override;
 
+    int32_t getRoutingChangedCount() {
+        return mRoutingChangedCount;
+    }
+
+    void onRoutingChanged() {
+        mRoutingChangedCount++;
+    }
+
 private:
+    class TestRoutingCallback : public oboe::AudioStreamRoutingCallback {
+    public:
+        TestRoutingCallback(ActivityTestDisconnect *activity)
+                : mActivity(activity) {}
+        virtual ~TestRoutingCallback() = default;
+        void onRoutingChanged(oboe::AudioStream* /* audioStream */,
+                              const int32_t* /* deviceIds */,
+                              int32_t /* numDevices */) override {
+            mActivity->onRoutingChanged();
+        }
+    private:
+        ActivityTestDisconnect *mActivity;
+    };
+
+    std::shared_ptr<TestRoutingCallback>    mRoutingCallback;
+    std::atomic<int32_t>                    mRoutingChangedCount{0};
     std::unique_ptr<SineOscillator>         sineOscillator;
     std::unique_ptr<MonoToMultiConverter>   monoToMulti;
     std::shared_ptr<oboe::flowgraph::SinkFloat>   mSinkFloat;
diff --git a/apps/OboeTester/app/src/main/cpp/jni-bridge.cpp b/apps/OboeTester/app/src/main/cpp/jni-bridge.cpp
@@ -1643,4 +1643,9 @@ Java_com_mobileer_oboetester_ReverseJniEngine_setAudioBuffer(JNIEnv *env, jobjec
     }
 }
 
+JNIEXPORT jint JNICALL
+Java_com_mobileer_oboetester_TestDisconnectActivity_getRoutingChangedCount(JNIEnv *env, jobject) {
+    return engine.mActivityTestDisconnect.getRoutingChangedCount();
+}
+
 } // extern "C"
diff --git a/apps/OboeTester/app/src/main/java/com/mobileer/oboetester/TestDisconnectActivity.java b/apps/OboeTester/app/src/main/java/com/mobileer/oboetester/TestDisconnectActivity.java
@@ -64,6 +64,8 @@ public class TestDisconnectActivity extends TestAudioActivity {
 
     protected AutomatedTestRunner mAutomatedTestRunner;
 
+    private native int getRoutingChangedCount();
+
     // Receive a broadcast Intent when a headset is plugged in or unplugged.
     // Display a count on screen.
     public class PluginBroadcastReceiver extends BroadcastReceiver {
@@ -396,6 +398,7 @@ private void testConfiguration(boolean isInput,
         }
 
         int oldPlugCount = mPlugCount;
+        int oldRoutingChangedCount = getRoutingChangedCount();
         if (!openFailed && valid) {
             mTestFailed = false;
             // poll until stream started
@@ -418,12 +421,15 @@ private void testConfiguration(boolean isInput,
                 }
             }
 
+            int currentRoutingCount = getRoutingChangedCount();
             // Wait for timeout or stream to disconnect.
             while (!mTestFailed && mAutomatedTestRunner.isThreadEnabled() && !mSkipTest && (timeoutCount > 0) &&
-                    stream.getState() == StreamConfiguration.STREAM_STATE_STARTED) {
+                    stream.getState() == StreamConfiguration.STREAM_STATE_STARTED &&
+                    oldRoutingChangedCount == currentRoutingCount) {
                 flushLog();
                 Thread.sleep(POLL_DURATION_MILLIS);
                 timeoutCount--;
+                currentRoutingCount = getRoutingChangedCount();
                 if (timeoutCount == 0) {
                     mTestFailed = true;
                 } else {
@@ -442,9 +448,12 @@ private void testConfiguration(boolean isInput,
                     }
                 } else {
                     int error = stream.getLastErrorCallbackResult();
-                    if (error != StreamConfiguration.ERROR_DISCONNECTED) {
+                    if (error != StreamConfiguration.ERROR_DISCONNECTED &&
+                        oldRoutingChangedCount == currentRoutingCount) {
                         log("onErrorCallback error = " + error
-                                + ", expected " + StreamConfiguration.ERROR_DISCONNECTED);
+                                + ", expected " + StreamConfiguration.ERROR_DISCONNECTED +
+                                ", old routing count = " + oldRoutingChangedCount +
+                                ", current routing count = " + currentRoutingCount);
                         mTestFailed = true;
                     }
                 }
diff --git a/docs/FullGuide.md b/docs/FullGuide.md
@@ -202,6 +202,7 @@ builder setting:
 | `setChannelConversionAllowed()` | `isChannelConversionAllowed()` |
 | `setFormatConversionAllowed()` | `setFormatConversionAllowed()` |
 | `setSampleRateConversionQuality` | `getSampleRateConversionQuality()` |
+| `setRoutingCallback()` | `getRoutingCallback()` |
 
 ### AAudio specific AudioStreamBuilder fields
 
@@ -364,6 +365,20 @@ You can prime the stream's buffer before starting the stream by writing data or
 
 The data in the buffer must match the data format returned by `mStream->getDataFormat()`.
 
+### Handle routing changed event
+
+A routing changed can happen when there is any peripheral connected/disconnected or any system-wide event, such as system Settings enable/disable a route, happens.
+
+Before Android API level 37, when the routed device(s) is changed, Android AAudio framework will always disconnect the stream. See **Disconnected audio stream** section for more information about stream disconnection.
+In Android API level 37, routing changed callback is introduced to notify apps when the routed devices are changed.
+
+Instead of disconnecting stream at all cases, Android AAudio will now evaluate if the audio configuration stays similar when the routed device(s) is changed.
+If the configuration stays the same but just the routed device(s) is changed, AAudio framework will fire a routing changed callback if it is register when opening.
+This usually happens when the stream is offloaded or it is not on mmap path. If the audio configuration may be affected by routing changed, AAudio framework will
+disconnect the stream. See **Disconnected audio stream** section for how to handle stream disconnection.
+
+If your apps need to be notified when the routed device is changed, write a class which extends `AudioStreamRoutingCallback` and then register your class using `builder.setRoutingCallback(yourCallbackClass)`.
+
 ### Closing an audio stream
 
 When you are finished using a stream, close it:
diff --git a/include/oboe/AudioStreamBase.h b/include/oboe/AudioStreamBase.h
@@ -104,11 +104,11 @@ class AudioStreamBase {
     /**
      * @return the device ID of the stream.
      */
-    int32_t getDeviceId() const {
+    virtual int32_t getDeviceId() const {
         return mDeviceIds.empty() ? kUnspecified :  mDeviceIds[0];
     }
 
-    std::vector<int32_t> getDeviceIds() const {
+    virtual std::vector<int32_t> getDeviceIds() const {
         return mDeviceIds;
     }
 
@@ -144,6 +144,14 @@ class AudioStreamBase {
         return mSharedPresentationCallback;
     }
 
+    /**
+     * For internal use only.
+     * @return the routing callback object for this stream, if set.
+     */
+    std::shared_ptr<AudioStreamRoutingCallback> getRoutingCallback() const {
+        return mSharedRoutingCallback;
+    }
+
     /**
      * @return true if a data callback was set for this stream
      */
@@ -316,6 +324,8 @@ class AudioStreamBase {
 
     std::shared_ptr<AudioStreamPresentationCallback> mSharedPresentationCallback;
 
+    std::shared_ptr<AudioStreamRoutingCallback> mSharedRoutingCallback;
+
     /** Number of audio frames which will be requested in each callback */
     int32_t                         mFramesPerCallback = kUnspecified;
     /** Stream channel count */
diff --git a/include/oboe/AudioStreamBuilder.h b/include/oboe/AudioStreamBuilder.h
@@ -599,6 +599,26 @@ class AudioStreamBuilder : public AudioStreamBase {
         return this;
     }
 
+    /**
+     * Specifies an object to handle routing related callbacks from the underlying API.
+     * This will be called when the routed devices of the stream are changed.
+     *
+     * <strong>Important: See AudioStreamCallback for restrictions on what may be called
+     * from the callback methods.</strong>
+     *
+     * We pass a shared_ptr so that the routingCallback object cannot be deleted before the
+     * stream is deleted. If the stream was created using a shared_ptr then the stream cannot be
+     * deleted before the routing callback has finished running.
+     *
+     * @param sharedRoutingCallback
+     * @return pointer to the builder so calls can be chained
+     */
+    AudioStreamBuilder *setRoutingCallback(
+            std::shared_ptr<AudioStreamRoutingCallback> sharedRoutingCallback) {
+        mSharedRoutingCallback = sharedRoutingCallback;
+        return this;
+    }
+
     /**
      * Specifies an object to handle data or error related callbacks from the underlying API.
      *
diff --git a/include/oboe/AudioStreamCallback.h b/include/oboe/AudioStreamCallback.h
@@ -190,6 +190,26 @@ class AudioStreamPresentationCallback {
     virtual void onPresentationEnded(AudioStream* /* audioStream */) {}
 };
 
+/**
+ * AudioStreamRoutingCallback defines a callback interface for
+ * being notified when the routed devices of a stream are changed.
+ *
+ * It is used with AudioStreamBuilder::setRoutingCallback().
+ */
+class AudioStreamRoutingCallback {
+public:
+    /**
+     * This will be called when the routed devices of the stream are changed.
+     *
+     * @param audioStream pointer to the associated stream
+     * @param deviceIds a pointer to a list of current routed device ids.
+     * @param numDevices the number of current routed devices.
+     */
+    virtual void onRoutingChanged(AudioStream* /* audioStream */,
+                                  const int32_t* /* deviceIds */,
+                                  int32_t /* numDevices */) {}
+};
+
 /**
  * AudioStreamPartialDataCallback defines a callback interface for
  * moving data to/from an audio stream using `onAudioReady`
diff --git a/src/aaudio/AAudioLoader.cpp b/src/aaudio/AAudioLoader.cpp
@@ -106,6 +106,10 @@ int AAudioLoader::open() {
         builder_setPresentationEndCallback = load_V_PBPRPV("AAudioStreamBuilder_setPresentationEndCallback");
     }
 
+    if (getSdkVersion() >= __ANDROID_API_C__) {
+        builder_setRoutingChangedCallback = load_V_PBRCCPV("AAudioStreamBuilder_setRoutingChangedCallback");
+    }
+
     builder_delete             = load_I_PB("AAudioStreamBuilder_delete");
 
 
@@ -360,6 +364,12 @@ AAudioLoader::signature_V_PBPRPV AAudioLoader::load_V_PBPRPV(const char *functio
     return reinterpret_cast<signature_V_PBPRPV>(proc);
 }
 
+AAudioLoader::signature_V_PBRCCPV AAudioLoader::load_V_PBRCCPV(const char *functionName) {
+    void *proc = dlsym(mLibHandle, functionName);
+    AAudioLoader_check(proc, functionName);
+    return reinterpret_cast<signature_V_PBRCCPV>(proc);
+}
+
 AAudioLoader::signature_I_PSII AAudioLoader::load_I_PSII(const char *functionName) {
     void *proc = dlsym(mLibHandle, functionName);
     AAudioLoader_check(proc, functionName);
diff --git a/src/aaudio/AAudioLoader.h b/src/aaudio/AAudioLoader.h
@@ -82,6 +82,15 @@ typedef void (*AAudioStream_presentationEndCallback)(
         void* userData);
 #endif
 
+#if OBOE_USING_NDK && __NDK_MAJOR__ < 30
+// Defined in Android C
+typedef void (*AAudioStream_routingChangedCallback)(
+        AAudioStream* stream,
+        void* userData,
+        const int32_t* deviceIds,
+        int32_t numDevices);
+#endif
+
 #ifndef __ANDROID_API_Q__
 #define __ANDROID_API_Q__ 29
 #endif
@@ -106,6 +115,10 @@ typedef void (*AAudioStream_presentationEndCallback)(
 #define __ANDROID_API_B__ 36
 #endif
 
+#ifndef __ANDROID_API_C__
+#define __ANDROID_API_C__ 37
+#endif
+
 #if OBOE_USING_NDK && __NDK_MAJOR__ < 30
 // These were defined in Android B
 typedef int32_t AAudio_DeviceType;
@@ -201,6 +214,10 @@ class AAudioLoader {
                                        AAudioStream_presentationEndCallback,
                                        void *);
 
+    typedef void (*signature_V_PBRCCPV)(AAudioStreamBuilder *,
+                                        AAudioStream_routingChangedCallback,
+                                        void *);
+
     typedef aaudio_format_t (*signature_F_PS)(AAudioStream *stream);
 
     typedef int32_t (*signature_I_PSPVIL)(AAudioStream *, void *, int32_t, int64_t);
@@ -278,6 +295,7 @@ class AAudioLoader {
     signature_V_PBPDPV  builder_setDataCallback = nullptr;
     signature_V_PBPEPV  builder_setErrorCallback = nullptr;
     signature_V_PBPRPV  builder_setPresentationEndCallback = nullptr;
+    signature_V_PBRCCPV builder_setRoutingChangedCallback = nullptr;
     signature_V_PBPDPV  builder_setPartialDataCallback = nullptr;
 
     signature_I_PB      builder_delete = nullptr;
@@ -382,6 +400,7 @@ class AAudioLoader {
     signature_I_I       load_I_I(const char *name);
     signature_I         load_I(const char *name);
     signature_V_PBPRPV  load_V_PBPRPV(const char *name);
+    signature_V_PBRCCPV load_V_PBRCCPV(const char *name);
     signature_I_PSII    load_I_PSII(const char *name);
     signature_I_PSPIPI  load_I_PSPIPI(const char *name);
     signature_I_PSIPL   load_I_PSIPL(const char *name);
diff --git a/src/aaudio/AudioStreamAAudio.cpp b/src/aaudio/AudioStreamAAudio.cpp
diff --git a/src/aaudio/AudioStreamAAudio.h b/src/aaudio/AudioStreamAAudio.h
diff --git a/src/common/FilterAudioStream.h b/src/common/FilterAudioStream.h

Original file line number	Diff line number	Diff line change
`@@ -1643,4 +1643,9 @@ Java_com_mobileer_oboetester_ReverseJniEngine_setAudioBuffer(JNIEnv *env, jobjec`
`1643`	`1643`	`}`
`1644`	`1644`	`}`
`1645`	`1645`
	`1646`	`+JNIEXPORT jint JNICALL`
	`1647`	`+Java_com_mobileer_oboetester_TestDisconnectActivity_getRoutingChangedCount(JNIEnv *env, jobject) {`
	`1648`	`+ return engine.mActivityTestDisconnect.getRoutingChangedCount();`
	`1649`	`+}`
	`1650`	`+`
`1646`	`1651`	`} // extern "C"`