Audio Fade Separate Gain Line Agent Skill

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.

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:

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:

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:

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:

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.

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.