Skip to content

maxrave-dev/kotlin-footguns / skills/media-playback-footguns

media-playback-footguns

Verified

Media player traps on Media3/ExoPlayer and desktop engines: crossfade, audio focus, fades, loudness, DSP, queues and shuffle, position restore, service lifecycle, group listening. Use when playback state, queue or audio levels go wrong.

FileKindSize
SKILL.mdskill md18.0 KB
references/audio-fade-separate-gain-line.mdmarkdown6.6 KB
references/audio-focus-multiplayer.mdmarkdown6.0 KB
references/beatmatched-automix.mdmarkdown7.3 KB
references/crossfade-dual-player.mdmarkdown7.1 KB
references/crossfade-exclusion-heuristics.mdmarkdown6.3 KB
references/custom-shuffle-order.mdmarkdown6.5 KB
references/derive-seek-from-progress-flow.mdmarkdown7.6 KB
references/dual-source-queue-sync.mdmarkdown6.2 KB
references/endless-queue-management.mdmarkdown5.6 KB
references/fgs-state-ended-trap.mdmarkdown7.1 KB
references/filter-chain-two-owners-one-writer.mdmarkdown6.6 KB
references/follower-item-built-from-shared-payload.mdmarkdown7.1 KB
references/follower-transport-stays-local.mdmarkdown7.0 KB
references/forwarding-player-hot-swap.mdmarkdown7.9 KB
references/guard-on-every-trigger-path.mdmarkdown5.2 KB
references/intent-flag-not-observed-state.mdmarkdown8.0 KB
references/joiner-catches-up-by-asking.mdmarkdown7.0 KB
references/media3-custom-audio-processor.mdmarkdown7.3 KB
references/one-setting-two-backends.mdmarkdown7.4 KB
references/optional-engine-feature-degrade-in-tiers.mdmarkdown7.2 KB
references/per-track-loudness-normalization.mdmarkdown7.6 KB
references/play-intent-decided-before-load.mdmarkdown6.9 KB
references/playback-position-persist-restore.mdmarkdown8.2 KB
references/polymorphic-load-media-entry-point.mdmarkdown6.3 KB
references/position-based-group-sync.mdmarkdown7.2 KB
references/queue-index-vs-shuffle-space.mdmarkdown7.2 KB
references/queue-rebuild-state-machine.mdmarkdown5.8 KB
references/readiness-barrier-needs-every-answer.mdmarkdown7.4 KB
references/realtime-biquad-dsp.mdmarkdown7.9 KB
references/runtime-override-not-preference-write.mdmarkdown7.1 KB
references/sampled-supplier-vs-per-handle-reapply.mdmarkdown6.2 KB
references/server-default-overrides-client-intent.mdmarkdown7.4 KB
references/sync-room-bridge-echo-guard.mdmarkdown7.9 KB

references/audio-focus-multiplayer.md

View on GitHub
---
name: audio-focus-multiplayer
description: Hold Android audio focus once at app level when several player instances are alive at the same time — dual-player crossfade, precached players — and keep focus-driven ducking off whatever gain line a fade already owns. Use when background playback dies between tracks, autoplay stalls after the first item, a duck never takes effect or never lifts, or volume jumps back to full in the middle of a transition.
---

# 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:

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

```kotlin
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:

```kotlin
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.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall