Skip to content

fix(android): Wire stayAwake to ExoPlayer wake mode in audioplayers_android_exo#1998

Open
leonardo-oliveir-a wants to merge 1 commit into
bluefireteam:mainfrom
leonardo-oliveir-a:fix/exo-wake-mode
Open

fix(android): Wire stayAwake to ExoPlayer wake mode in audioplayers_android_exo#1998
leonardo-oliveir-a wants to merge 1 commit into
bluefireteam:mainfrom
leonardo-oliveir-a:fix/exo-wake-mode

Conversation

@leonardo-oliveir-a

@leonardo-oliveir-a leonardo-oliveir-a commented Jun 10, 2026

Copy link
Copy Markdown
Contributor

Description

audioplayers_android_exo parses the stayAwake flag of AudioContextAndroid (the method channel even requires it), but never consumes it: the ExoPlayer is built without setWakeMode, so stayAwake: true silently does nothing on the exo implementation.

What Media3 1.9.0 does today when no wake mode is set (verified against the media3-exoplayer:1.9.0 bytecode and dumpsys power on a physical device): ExoPlayerImpl enables its wake lock by default while playing (ExoPlayer:WakeLockManager partial wake lock), but never the wifi lockWifiLockManager is only enabled for an explicit WAKE_MODE_NETWORK. So network playback can still stall once the device enters wifi power-save with the screen off, and stayAwake gives users no way to opt into the behavior Media3 recommends for background network playback.

This wires stayAwake = true to an explicit setWakeMode(C.WAKE_MODE_NETWORK) (partial wake lock + wifi lock, held by ExoPlayer only while actually playing), mirroring the stayAwake handling of audioplayers_android (MediaPlayer.setWakeMode in updateContext). As there, the upgrade is one-way: WAKE_MODE_NONE is never set, since that would disable the default wake lock current users rely on — stayAwake: false keeps today's behavior, bit for bit.

WAKE_MODE_NETWORK is used (rather than WAKE_MODE_LOCAL) because the source type isn't known when the audio context is applied, and it is a strict superset. As with the MediaPlayer implementation, apps must declare android.permission.WAKE_LOCK for the flag to take effect (Media3 docs).

Applied both at player creation (initial context) and in updateContext.

Checklist

  • The title of my PR starts with a [Conventional Commit] prefix (fix:, feat:, docs: etc).
  • I have read the [Contributor Guide] and followed the process outlined for submitting PRs.
  • I have updated/added tests for ALL new/updated/fixed functionality — no test infra exists for the Kotlin layer of this package; validated manually (see below).
  • I have updated/added relevant documentation — rationale documented in code comments; the existing stayAwake dartdoc already describes this behavior.
  • I have updated/added relevant examples in examples — no example change needed; testable in the example app by setting stayAwake: true in the audio context and streaming a URL with the screen off.

Breaking Change

  • Yes, this is a breaking change.
  • No, this is not a breaking change. (stayAwake: false — the default — is bit-for-bit unchanged.)

How to validate

With stayAwake: true and a remote URL source playing: adb shell dumpsys power shows the ExoPlayer:WakeLockManager partial wake lock and dumpsys wifi shows the WifiLockManager lock; both are released on pause. With stayAwake: false, behavior is identical to current (default wake lock only, no wifi lock). (Running this validation on a physical device now — will post the dumpsys output here.)

…ndroid_exo

The exo implementation parses the stayAwake flag of AudioContextAndroid
(the method channel requires it) but never consumes it. Media3 1.9.0
enables its wake lock by default while playing when no wake mode is set,
but never the wifi lock — so with stayAwake there is currently no way to
keep network playback alive once the device enters wifi power-save with
the screen off (Media3 recommends WAKE_MODE_NETWORK for this).

Map stayAwake=true to an explicit setWakeMode(C.WAKE_MODE_NETWORK)
(partial wake lock + wifi lock, held only while actually playing),
mirroring the stayAwake handling of audioplayers_android
(MediaPlayer.setWakeMode in updateContext). Like there, the upgrade is
one-way: WAKE_MODE_NONE is never set, since that would disable the
default wake lock users currently rely on. Applied both at player
creation and on context updates.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant