Enable AAudio on Android and handle stream disconnection

[hajimehoshi]

Background

The Android backend compiles Oboe with AAudio disabled:

// Disable AAudio (hajimehoshi/ebiten#1634).
// AAudio doesn't care about plugging in/out of a headphone.
// See https://github.com/google/oboe/wiki/TechNote_Disconnect

// #cgo CXXFLAGS: -std=c++17 -DOBOE_ENABLE_AAUDIO=0

(internal/oboe/binding_android.go)

So AudioStreamBuilder::build() always constructs an AudioOutputStreamOpenSLES, and every Android playback path goes through OpenSL ES.

Motivation

1. OpenSL ES makes Android failures undiagnosable.

Oboe's OpenSL backend collapses every failure into a single Result::ErrorInternal, marked in its own source as // TODO convert error from SLES to OBOE. The four sites that produce it are:

Site	Failing operation
oboe_opensles_AudioStreamOpenSLES_android.cpp:81	slCreateEngine / engine Realize / dlopen("libOpenSLES.so")
oboe_opensles_AudioOutputStreamOpenSLES_android.cpp:133	output mixer open()
oboe_opensles_AudioOutputStreamOpenSLES_android.cpp:225	CreateAudioPlayer, SetConfiguration, player Realize, GetInterface(PLAY), finishCommonOpen
oboe_opensles_AudioOutputStreamOpenSLES_android.cpp:263	SetPlayState(SL_PLAYSTATE_PLAYING)

This is why audio: audio error: oboe: Play failed: ErrorInternal, frequently reported from Samsung devices, carries no actionable information. AAudio returns specific codes (ErrorUnavailable, ErrorNoService, ErrorInvalidRate, ...) that would let these reports be triaged.

2. OpenSL ES is deprecated since API 30, receives no OEM bug fixes, and cannot reach the MMAP / exclusive low-latency path.

Why the original reason is weaker now

hajimehoshi/ebiten#1634 was filed in 2021 against a much older Oboe. Since then:

• Oboe installs a default error callback when the app doesn't specify one, specifically "so the stream gets closed and stopped" (oboe_aaudio_AudioStreamAAudio_android.cpp), and holds a shared_ptr across the error thread via lockWeakThis(). oto already opens with the shared_ptr overload, so that protection applies.
• The TechNote_Disconnect wiki page was updated in Nov 2023 to state that onErrorAfterClose() is already called on a thread Oboe creates, so the app does not need to create another one.

The disconnect behaviour itself is unchanged and is by design: an AAudio stream is bound to a device, and a routing change disconnects it. That is a handleable event, not a blocker.

What needs to be done

1. Drop -DOBOE_ENABLE_AAUDIO=0 from internal/oboe/binding_android.go.
2. Make Stream also implement oboe::AudioStreamErrorCallback and add ->setErrorCallback(this) to the builder.
3. Reopen and start a new stream in onErrorAfterClose() when the result is Result::ErrorDisconnected. No extra thread is needed.
4. Split Stream::Play() into a one-time part (creating the reader thread) and a repeatable open-and-start part. The reconnect path must not spawn a second Loop thread.
5. Add a mutex around stream_. It is currently accessed with no lock at all, and after this change onErrorAfterClose() runs on an Oboe thread concurrently with Suspend()/Resume() from Go.
6. Clear buf_ on reconnect, otherwise up to three buffers of stale audio are replayed after the switch.
7. Handle a changed burst size. Loop() sizes tmp once from getBufferSizeInFrames() at thread creation; the new device may report a different value.
8. Bounded retry with backoff when the reopen fails, since the new device may not be ready immediately.
9. Stop latching the error permanently. newContext stores the first error in context.err and never retries, and NewContext can only be called once per process, so today a single transient failure means permanently silent audio. A disconnect followed by a successful reopen must not surface as an error at all.

Risk

On Android P and some early Q builds, the disconnect callback did not fire at all, so a reopen handler would never run. This was a platform bug, not an Oboe or app bug; it was fixed and is now covered by QA (google/oboe#893). The other reports of it (google/oboe#381, google/oboe#1350) are also closed, and #1350 turned out to be a P build misreported as Android 11. There is no confirmed report on R or later.

If a fallback is still wanted, the option that fits oto is stall detection: if the data callback has not run for some multiple of the buffer duration while the stream is Started, treat it as disconnected and reopen. This needs no Java Context and also covers silent stalls that are not disconnects. The Intent.ACTION_HEADSET_PLUG receiver suggested by the Oboe tech note is not directly available here, since oto has no JNI layer.

Suggested rollout

Enable AAudio behind an opt-in option first, so a Samsung reporter can be asked to try it and confirm whether ErrorInternal becomes a specific error code, before it becomes the default path.

---

Filed by Claude (Claude Code), on behalf of @hajimehoshi.

[hajimehoshi]

Option: keep OpenSL ES on older API levels

Rather than switching every device to AAudio at once, the backend can be selected by API level:

builder.setDirection(oboe::Direction::Output)
    ->setAudioApi(oboe::getSdkVersion() >= 30 /* __ANDROID_API_R__ */
                      ? oboe::AudioApi::Unspecified
                      : oboe::AudioApi::OpenSLES)
    ->setPerformanceMode(oboe::PerformanceMode::LowLatency)
    // ...

AudioApi::OpenSLES forces the OpenSL path unconditionally in AudioStreamBuilder::build(): the first branch tests mAudioApi != AudioApi::OpenSLES and the second requires == AudioApi::AAudio, so it falls through to AudioOutputStreamOpenSLES. oboe::getSdkVersion() is declared in Utilities.h, which Oboe.h already includes.

Note that the AAudio sources are already compiled and linked in today. cgo builds every .cpp in internal/oboe/ regardless, and -DOBOE_ENABLE_AAUDIO=0 only changes what isAAudioSupported() returns. The flag is purely a runtime gate, so enabling it has no build-system or binary-size consequence.

Scope

The band this actually changes is API 27-29. Oboe already refuses AAudio below API 27, since isAAudioRecommended() requires O_MR1, so Android 8.0 and older are on OpenSL ES today and stay there either way.

A cut at R is more conservative than the evidence requires. Per google/oboe#893 the disconnect bug was a P-era platform bug that was fixed, and the maintainer's note was that it "may have taken a while for the fix to propagate out to various Q devices", so Q was largely fine by 2020. A tighter gate matching the actual bug window would be <= __ANDROID_API_P__ (28). Either is defensible.

Trade-off

This does not reduce the work in the list above. All nine items are still needed, because R and later is where essentially all devices are. The gate buys risk reduction on a small and shrinking tail, not implementation savings.

The argument for doing it anyway is that this is a class of bug that cannot be tested here: there is no Pie Exynos device to verify the reconnect path against, and the failure mode is silent, so a user would report "no sound" with no error attached. Keeping API 27-29 on the code path they have been running successfully for years is cheap insurance against a regression that review and CI cannot catch.

It also composes with the staged rollout: the version gate becomes the default policy, and the opt-in option overrides it.

Related benefit

Oboe's SamsungExynosDeviceQuirks (oboe_common_QuirksManager_android.cpp) disables MMAP for specific Exynos chips and build changelists (google/oboe#892, google/oboe#1110, google/oboe#1247). None of it runs today, because it is all on the AAudio path. Enabling AAudio picks up Google's accumulated Samsung workarounds, which is a point in favour beyond error reporting.

---

Comment written by Claude (Claude Code), on behalf of @hajimehoshi.

[hajimehoshi]

Concerns beyond disconnection

1. The data callback violates the real-time contract

Stream::onAudioReady in internal/oboe/binding_android.cpp does:

std::unique_lock<std::mutex> lock{mutex_};
cond_.wait(lock, [this, num] { return buf_.size() >= num; });

Oboe's onAudioReady documentation explicitly forbids this. It lists "use any mutexes or other synchronization primitives", "sleep", and "allocate memory" as things the callback must not do. The condition variable wait here is unbounded: it blocks the audio callback until the producer thread supplies data. There is already a // TODO: Do not use a lock in onAudioReady next to it, pointing at that same documentation.

This survives on OpenSL ES because the buffer queue is double buffered by default and can grow to 8 (kBufferQueueLengthDefault / kBufferQueueLengthMax), so several bursts of slack absorb a late producer. AAudio LowLatency runs the callback on a real-time thread with a per-burst deadline, and the producer here is oto_oboe_read calling into Go, so a GC pause on an allocating game stalls the audio thread directly.

The interaction to watch: on API 30 Oboe coerces ErrorTimeout to ErrorDisconnected (b/173928197, in oboe_aaudio_AudioStreamAAudio_android.cpp). A callback stalled by GC can therefore present as a spurious disconnect, which would fire the reopen path, and the reopened stream has the same defect. That is a plausible reconnect loop.

The fix is what the documentation recommends: a lock-free FIFO, reading what is available and writing silence for the shortfall rather than blocking. This should land before AAudio is enabled, as a separate change. It is a latent bug on the current OpenSL path too, it can be tested on today's devices, and it removes the sharpest edge from everything else.

2. Headphone plug and unplug becomes audible

OpenSL ES switches devices seamlessly today. AAudio plus reopen is close, open, start: tens to hundreds of milliseconds of silence each time. This is a user-visible behaviour change, and it is precisely what the original workaround was buying. Worth deciding deliberately rather than discovering later.

3. Buffer sizing assumptions do not carry over

Loop() sizes tmp once as num_frames * channel_num_ * 3, where num_frames comes from getBufferSizeInFrames() at thread creation. On AAudio that value is runtime-tunable, distinct from capacity, and typically much smaller than the OpenSL equivalent. num_frames in the callback also varies between calls unless setFramesPerDataCallback() is set. The 3x heuristic was tuned against OpenSL, so latency and underrun behaviour will shift.

4. A wider error surface is the goal, but needs handling

ErrorUnavailable, ErrorNoService, ErrorTimeout and ErrorDisconnected all become reachable at open and start. Getting specific codes is the point of the switch, but the code has to separate retryable from fatal. Since context.err is write-once today, a transient ErrorUnavailable at startup still means permanently silent audio. Item 9 above matters more after this change, not less.

5. Minor

• The getSharingMode() != oboe::SharingMode::Shared guard in Stream::Play turns any surprise into a hard permanent failure. Requesting Shared should yield Shared on AAudio, but this is a brittle way to find out.
• The MMAP and Exynos matrix cannot be validated locally, which is the practical argument for the staged rollout and the version gate.

Suggested ordering

1. Replace the callback's mutex and condition variable with a lock-free FIFO. Standalone, ships on OpenSL ES, fixes a latent bug.
2. Add the disconnect and reopen machinery (items 2 to 9 above).
3. Flip the flag behind the opt-in option, with the version gate as the default policy.

---

Comment written by Claude (Claude Code), on behalf of @hajimehoshi.