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-fade-separate-gain-line.md

View on GitHub
---
name: audio-fade-separate-gain-line
description: Implement a programmatic audio fade — a sleep timer, an alarm ramp, a duck — on a gain line of its own instead of the user's volume, and restore that gain from the player's own completion path. Use when a fade drags the volume slider down in the UI, when the app comes back permanently silent with a full slider, when a fade still ends in an audible click, or when audio briefly swells back after a fade completes.
---

# A fade needs its own gain line

A sleep timer that ends on a bare `pause()` chops the music off. Ramping to silence first
is a two-line change with three ways to get it wrong. The rule that avoids all three: the
fade gets **its own gain line**, multiplied with the user's volume at the point the value
reaches the audio path.

```kotlin
interface MediaPlayerInterface {
    var volume: Float           // the user's level — reported back to the UI
    var sleepFadeFactor: Float  // 0f..1f, the fade's own line
}
```

- **Android (Media3):** a small `AudioProcessor` in the chain, one instance per player, all
  reading the same `@Volatile` field: `arrayOf(crossfadeFilter, sleepFade)`.
- **Desktop:** engines commonly expose two levels — a device-mixer level and a software
  level. Put the fade on one and the crossfade ramp on the other; they then multiply and
  neither has to know the other exists.

## Traps

**Ramping the user's volume.** It is the obvious implementation and it is wrong twice over.
That value is reported back through the volume-changed callback, so the slider visibly
crawls to zero while the user watches. Worse, if the process ends mid-fade the persisted
level is now near zero: the app comes back silent with a full-looking slider, and no code
path restores it because nothing knows a fade was interrupted. The user's level must be
the one thing a fade never writes.

**Pausing the instant the ramp reaches zero.** Gain is applied *ahead* of a buffered output
stage. Several hundred milliseconds of already-attenuated-but-not-silent audio is still
queued when the ramp finishes, so the pause cuts it at a clearly audible level. Hold
silence for a short tail before pausing:

```kotlin
delay(remaining - fadeMs - tailMs)
fadeOutForSleep(fadeMs)     // ramps to 0
delay(tailMs)               // let the tail drain
player.pause()
```

Tune the tail against the platform's own output buffer; measure by ear at the boundary
rather than copying a number. Both fade and tail must be **clamped to fit inside what is
left** (`fadeMs.coerceAtMost(remaining)`, then `tailMs.coerceAtMost(remaining - fadeMs)`),
or an "end of current song" timer runs past the end of the song and pauses inside the next.

**Restoring the gain from the caller, right after `pause()`.** This is the subtle one.
`pause()` is asynchronous *and* suspends partway through (committing a crossfade joins a
job). A single-threaded dispatcher therefore does **not** order "pause, then restore": the
suspension releases the thread, the queued restore runs first, and the mixer re-opens over
the last of the audio — a short swell right after the fade. The restore belongs in the
player adapter's own completion path:

```kotlin
override fun pause() {
    scope.launch {
        try { /* commit any fade, then pause */ }
        finally { internalSleepFadeFactor = 1f }   // playback has genuinely stopped here
    }
}
```

**Putting the restore on the happy path instead of in `finally`.** The block above can throw
or be cancelled — committing a crossfade joins a job that may itself be cancelled. Any path
that skips the restore leaves every sample multiplied by ~0 for the rest of the process,
with a full volume slider and no way back. `finally` is not defensive style here; it is the
only correct placement.

**Forgetting an early-return branch of `pause()`.** A handoff to a remote-playback session
typically returns before the coroutine is ever launched. That branch must clear the factor
inline, or the attenuation outlives the remote session: the processor is still in the local
chain and keeps multiplying by ~0 when playback comes back.

**The timer's own `finally` must not double-restore.** The caller still needs a restore for
the *cancelled* path (the user turned the timer off, the scope went away mid-fade). Guard it
so the completed path leaves the job to the adapter:

```kotlin
finally { if (!stoppedPlayback) player.sleepFadeFactor = 1f }
```

**Capturing the gain instead of reading it fresh.** The processor must read the field on
every buffer, not once at configure time — otherwise a fade that starts, or keeps advancing,
in the middle of a crossfade never reaches the output. Same reason the desktop setter
re-reads the field inside the queued task rather than capturing the argument: if the queue
backs up, pending writes collapse onto the newest value instead of replaying a stale ramp.

**Making the processor inactive at full gain.** A processor that reports `isActive = false`
is dropped from the chain and is not reconsulted until the next flush — by which time the
timer has already stopped playback. Keep it always active and make the full-gain case a
bulk copy:

```kotlin
override fun isActive() = true

override fun queueInput(input: ByteBuffer) {
    val out = replaceOutputBuffer(input.remaining())
    val g = gain()
    if (g >= 1f) { out.put(input); out.flip(); return }   // every buffer, all playback
    input.order(ByteOrder.nativeOrder())
    while (input.remaining() >= 2) out.putShort((input.short * g).toInt().toShort())
    while (input.hasRemaining()) out.put(input.get())     // consume ALL of it
    out.flip()
}
```

Leaving even one byte unconsumed makes the pipeline re-offer the same buffer forever,
having made no progress.

**Linear ramps and unbounded step counts.** Use the same equal-power (cosine) curve as a
crossfade — `cos(progress * PI / 2)` — because loudness is perceived logarithmically and a
linear ramp sounds like it drops away early then lingers. And clamp the step count to the
duration: 50 steps at a 1 ms floor takes 50 ms no matter what duration was requested, so a
1-second fade silently becomes an instant one.

```kotlin
val steps = nominalSteps.toLong().coerceAtMost(durationMs).toInt()
val delayPerStep = (durationMs / steps).coerceAtLeast(1L)
```

## Verifying it

- Watch the volume slider through a full fade. It must not move.
- Kill the process mid-fade, relaunch, press play: audio at the user's level, immediately.
- Let a timer complete, then press play: full level, no swell, no residual attenuation.
- Cancel a timer mid-fade: level restored within a step or two.
- If the platform reports the applied gain, log it once per second during the ramp and
  confirm it reaches 0 *before* the pause and 1 *after* it, never between.
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: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated 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: 196kUpdated Claude CodeCodexVerifiedInstall