audio-fade-separate-gain-line

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.

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.