Audio Focus Multiplayer Agent Skill

Audio focus with more than one live player

Android's per-player focus handling assumes one player for the life of the app. A

crossfade breaks that assumption: instances are created, promoted and released constantly.

• Releasing the outgoing instance abandons focus for the whole app.
• The incoming instance was built with focus handling off, so it never re-requests it.
• Result: the app is playing with no focus. The system pauses it at the next opportunity —

or another app takes over and it never comes back.

The fix is one focus request owned by the component that owns the swap:

ExoPlayer.Builder(context)
    .setAudioAttributes(audioAttributes, /* handleAudioFocus = */ false)  // every instance
    .build()

private val audioFocusRequest by lazy {
    AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN)
        .setAudioAttributes(/* USAGE_MEDIA, CONTENT_TYPE_MUSIC */)
        .setOnAudioFocusChangeListener(audioFocusListener)
        .setWillPauseWhenDucked(false)     // we duck ourselves
        .build()
}

private fun requestAudioFocusInternal(): Boolean {
    if (hasAudioFocus) return true         // idempotent
    hasAudioFocus = audioManager.requestAudioFocus(audioFocusRequest) ==
        AudioManager.AUDIOFOCUS_REQUEST_GRANTED
    return hasAudioFocus
}

Focus now survives every swap, because no player instance ever held it.

Traps

Leaving handleAudioFocus = true on "just the main" instance. There is no main instance

— the one holding focus is released at the end of every transition. Set it false on every

instance you build, including precached ones, and let the adapter hold the single request.

Requesting focus only from the play button. Playback also starts from paths the user

never taps: the transition that starts the incoming instance, and the load-and-play path

used when a queue advances. Each of those must call the idempotent request. Because it is a

no-op while focus is held, calling it in three places costs nothing and closes the gap where

the app resumes with no focus after a transient loss.

Abandoning focus on every player release. Abandon only where playback genuinely ends —

stop(), release(), and the branch that hands playback to another output. A release that is

part of a swap must not touch focus. Keep the request object itself as a single lazy

field: abandoning with a *different* request object than the one granted does nothing and

fails silently.

Ducking on the same gain line as the fade ramp. A crossfade rewrites the player volume

~50 times per transition. A duck written to that same line is erased by the next ramp step,

and when the duck lifts it writes full volume over a fade in progress — heard as the music

jumping back to full mid-transition. Guard both directions on the fading flag:

AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK ->
    if (!isCrossfading) currentPlayer?.volume = internalVolume * duckVolumeFactor

AudioManager.AUDIOFOCUS_GAIN ->
    if (!isCrossfading) currentPlayer?.volume = internalVolume   // don't fight the ramp

This is a workaround, not the cure. The structural fix is the one a sleep-timer fade already

needs: give the duck its own gain line and multiply the lines together at the audio path,

so neither writer can erase the other. Reach for that as soon as a second automatic gain

appears — two writers on one line is the pattern, and each new one doubles the interactions.

Restoring the duck to a hardcoded 1.0f. Restore to the *user's* level

(internalVolume), never to full. Restoring to full silently discards the volume setting

after every navigation prompt.

Treating all three losses the same. They mean different things and want different

responses:

| Focus change | Response |

|---|---|

| LOSS | permanent — pause, clear the resume flag, mark focus not held |

| LOSS_TRANSIENT | pause, and record whether you were actually playing so regain resumes only then |

| LOSS_TRANSIENT_CAN_DUCK | attenuate, do not pause |

| GAIN | restore the level, resume only if the flag was set |

Resuming unconditionally on GAIN starts music the user had paused before the interruption.

Ducking while a programmatic fade is running. A duck and a sleep-timer fade are two

independent attenuations. Once each has its own line the answer is simply that they

multiply; sharing a line makes it a question with no good answer.

Assuming focus and the media session agree. A swap moves the session's listener to the

incoming instance. Focus is unrelated and app-scoped. Do not derive one from the other, and

do not let the session's own focus handling be enabled alongside yours — two owners fight.

Verifying it

• Log the grant result on every request and every abandon. Between the first item and the

last, hasAudioFocus must never go false; a false in the middle of a queue is the bug.

• Play with the screen off through at least three transitions. Playback dying between items

is the classic signature of focus lost on a swap.

• Trigger a duck (a navigation prompt, or any app requesting transient-can-duck) both during

steady playback and in the middle of a fade, and confirm the level returns to the *user's*

level afterwards in both cases.

• Take a phone call mid-playback and mid-fade. Correct: pause, then resume at the right

level. Incorrect: resumes at full volume, or resumes when you had it paused.

• grep -n "requestAudioFocus\|abandonAudioFocus" should show one request object, requests

from every path that starts audio, and abandons only from terminal paths.