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/polymorphic-load-media-entry-point.md

View on GitHub
---
name: polymorphic-load-media-entry-point
description: One generic "load this item and start playing" function normalizes several item types into a single internal shape, routes the queue-seeding strategy off a discriminator, and gates every pre-enqueue policy at that one place. Use when playback can start from many screens and a rule (content filter, dedup, analytics, resume-without-autoplay) keeps getting forgotten on one of the paths.
---

# Polymorphic load-media entry point

Playback starts from a lot of places: a search row, a library row, a playlist, an album, a shared
link, a restored session. Each has its own item type and its own idea of what should be queued next.
Given one entry point per caller, any policy that must hold for *all* of them will be missing from
at least one.

Collapse them into a single function with two parameters that do the varying:

```kotlin
suspend fun <T> loadMediaItem(anyTrack: T, type: String, index: Int? = null) {
    val track = when (anyTrack) {
        is Track -> anyTrack
        is SongEntity -> anyTrack.toTrack()
        else -> return                       // unknown type: do nothing, touch nothing
    }
    // --- pre-enqueue policy: everything below this line assumes the item is allowed to play
    if (track.isExplicit && !settings.explicitContentEnabled()) { showToast(Explicit); return }
    songRepository.insertSong(track.toSongEntity())
    clearMediaItems()
    addMediaItem(track.toGenericMediaItem(), playWhenReady = type != RECOVER_TRACK_QUEUE)
    when (type) {
        SONG_CLICK, VIDEO_CLICK, SHARE       -> getRelated(track.trackId)   // seed from one item
        PLAYLIST_CLICK, ALBUM_CLICK, RADIO_CLICK -> loadPlaylistOrAlbum(index)
    }
}
```

The generic parameter normalizes **content**; the `type` discriminator routes **strategy**. They are
deliberately separate: two callers can pass the same item type and want different queues.

## Traps

**Policy gates must sit before the first player mutation, not after.** Order is the whole point:
the content check returns *before* `clearMediaItems()`, so a blocked item leaves whatever is playing
untouched. Put the gate one line later and a rejected tap stops the music and shows a message — the
user loses their session to a rule that was supposed to change nothing.

**Every side effect that must happen "whenever a track starts" belongs here, and only here.**
Recording the item locally, back-filling its duration, dedup against what is already queued: each of
those, added at a call site, is a rule that holds on the screens someone remembered. Verify by
counting callers — the function should have many, and no caller should reach the player directly:

```
grep -rn "loadMediaItem(" --include='*.kt' .    # should list every playback origin
# in your UI module, nothing should reach the player directly — narrow the pattern to the
# player receiver so the handler's own delegating calls do not count as hits:
grep -rn "player\.addMediaItem(\|player\.setMediaItem(" --include='*.kt' <ui-module>/
```

(Quote the `--include` glob — unquoted, some shells expand it against the working directory and the
command fails before it searches anything.)

**The type normalization needs a real `else` that does nothing.** `else -> return` is not laziness;
it is the only correct answer for a caller that passed something the handler cannot represent.
Throwing turns a caller mistake into a stopped app, and a default of "treat it as a bare track" ships
an item with empty metadata into the queue.

**A `String` discriminator has no exhaustiveness, and the failure is silent.** A typo, or a new
origin added without a branch, falls through the `when` — the first item is enqueued and plays, and
the queue never fills, which reads as "the radio is broken" rather than "the constant is wrong".
Prefer a sealed type or an enum, and if it must stay a `String`, add an `else` branch that logs
loudly. Verify the set is closed by grepping the constants against the branches:

```
grep -rn "SONG_CLICK\|PLAYLIST_CLICK\|ALBUM_CLICK\|RADIO_CLICK\|SHARE\|RECOVER" --include='*.kt' .
```

Any constant that appears at a call site but not in the `when` is a dead origin.

**Auto-play is derived from the discriminator, not passed as a flag.** A restore path enqueues the
same item and must *not* start playing, so `playWhenReady = type != RECOVER_TRACK_QUEUE` keeps that
decision next to the branch that owns it. An extra boolean parameter would let a caller combine
"restore" with "play now", which is a state the app has no handling for.

**The first item and the rest of the queue are seeded by different mechanisms.** The tapped item is
added immediately so audio starts now; the queue fills asynchronously behind it. That means the
helper which adds items must self-start on the first one:

```kotlin
private fun addMediaItemNotSet(item: GenericMediaItem, index: Int? = null) {
    index?.let { player.addMediaItem(it, item) } ?: player.addMediaItem(item)
    if (player.mediaItemCount == 1) { player.prepare(); player.playWhenReady = true }
    updateNextPreviousTrackAvailability()
}
```

Without that count check, an item added into an empty engine sits there prepared-but-idle and the
tap appears to do nothing. With it applied unconditionally, every append restarts playback.

**`index` means "position in the source", and one path re-reads it.** For a playlist origin it is
which track the user tapped; the seeding path re-catalogs around it — moving the already-enqueued
item to that position and skipping it during the re-add, since it is already in the player. An
index that does not point at the item just enqueued shifts
the whole queue against the engine — the same failure the restore path guards against by putting the
track at the front when the saved queue does not contain it.

**Being `suspend` is part of the contract.** The gate reads a setting, and the normalization may hit
storage. Making it fire-and-forget internally would let a caller's own coroutine cancellation race
the gate, so the policy check would sometimes not complete before the item was enqueued.

## Verifying it

Add a temporary log at the top of the entry point and exercise every origin the app has — each tap,
each long-press menu, each share link, plus a cold restore. Every one should print exactly once. An
origin that plays without printing is a call site that reached the player directly, and it is where
the next forgotten rule will land.
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