feat: fade in audiobook resume to mask the cold-start glitch

Continuing an audiobook from a saved position stutters for the first
~2 s: opening the file, decoding the first MP3 frames and seeking to the
resume position saturate the 1-bit SD/CPU while I2S is already playing,
so the input buffer underruns until it catches up.

Hide it elegantly instead of fighting the hardware: on resume, rewind a
few seconds before the saved position and start muted, then ramp the
audio-lib volume back up over the fade duration. The glitch now lands on
already-heard audio, so no content is lost and playback sounds clean from
where you stopped. Only the audio-lib gain is ramped; the UI/MQTT volume
is untouched, and a manual volume change cancels an active fade.

Tunable via RESUME_FADEIN_DURATION_MS / RESUME_FADEIN_REWIND_S in
settings.h (duration 0 disables the feature).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: fhirschmann

README.md

@@ -206,6 +206,7 @@ neon logo that doubles as the SVG favicon ([`7be5254`](../../commit/7be5254)):
 | Unlocking controls via button press while locked | [`d83e15f`](../../commit/d83e15f) |
 | Support for a 6th button | [`b116151`](../../commit/b116151) |
 | OLED display support (SH1106/SSD1306 128×64 over I2C): boot splash, idle screen with IP + READY, now-playing title (up to 3 lines, scrolling) with battery/time/wifi status bar, and a volume bar | [`8ce8104`](../../commit/8ce8104) |
+| Audiobook resume fade-in: continuing a saved position briefly stutters in the first ~2 s (file open + MP3 header decode + seek-flush saturate the 1-bit SD/CPU while I2S already plays). The resume now rewinds a few seconds and fades the volume up over that span, so the glitch lands on already-heard audio — no content lost, clean sound from where you stopped. Tunable / disable via `RESUME_FADEIN_DURATION_MS` and `RESUME_FADEIN_REWIND_S` in `settings.h` | [`PENDINGHASH`](../../commit/PENDINGHASH) |
 
 ### Virtual RFID cards
 

src/AudioPlayer.cpp

@@ -98,6 +98,10 @@ BaseType_t trackQStatus = pdFAIL;
 uint8_t trackCommand = NO_ACTION;
 bool audioReturnCode;
 uint32_t AudioPlayer_LastPlaytimeStatsTimestamp = 0u;
+// Resume fade-in (see settings.h RESUME_FADEIN_*): millis() when the fade started after a
+// rewound audiobook-resume; 0 = no fade active. Output starts muted and is ramped up so the
+// brief cold-start glitch is masked and lands on the rewound (already-heard) audio.
+uint32_t AudioPlayer_ResumeFadeStartMs = 0u;
 Playlist *newPlayList = nullptr;
 bool newPlayListAvailable = false;
 
@@ -691,6 +695,21 @@ void AudioPlayer_HeadphoneVolumeManager(void) {
 
 // Function to play music as task
 void AudioPlayer_Loop() {
+	// Resume fade-in: ramp the output volume from 0 back to the user's volume over
+	// RESUME_FADEIN_DURATION_MS after a rewound audiobook-resume, so the brief cold-start
+	// glitch is masked. Only the audio-lib gain is ramped; AudioPlayer_CurrentVolume (and
+	// thus the UI/MQTT-reported volume) is left untouched.
+	if (AudioPlayer_ResumeFadeStartMs && (RESUME_FADEIN_DURATION_MS > 0)) {
+		const uint8_t target = AudioPlayer_GetCurrentVolume();
+		const uint32_t elapsed = millis() - AudioPlayer_ResumeFadeStartMs;
+		if (elapsed >= RESUME_FADEIN_DURATION_MS) {
+			audio->setVolume(target);
+			AudioPlayer_ResumeFadeStartMs = 0;
+		} else {
+			audio->setVolume((uint8_t) ((uint32_t) target * elapsed / RESUME_FADEIN_DURATION_MS));
+		}
+	}
+
 	// Update playtime stats every 250 ms
 	if ((millis() - AudioPlayer_LastPlaytimeStatsTimestamp) > 250) {
 		AudioPlayer_LastPlaytimeStatsTimestamp = millis();
@@ -1084,6 +1103,7 @@ void AudioPlayer_Loop() {
 		}
 		gPlayProperties.currentRelPos = 0;
 		audioReturnCode = false;
+		bool resumeFadeWanted = false; // set when a rewound audiobook-resume should fade in (see AudioPlayer_Loop)
 
 		if (gPlayProperties.playMode == WEBSTREAM || (gPlayProperties.playMode == LOCAL_M3U && gPlayProperties.isWebstream)) { // Webstream
 			audioReturnCode = audio->connecttohost(gPlayProperties.playlist->at(gPlayProperties.currentTrackNumber));
@@ -1099,7 +1119,13 @@ void AudioPlayer_Loop() {
 				int32_t fileStartTime = -1;
 				if (gPlayProperties.startAtFilePos > 0) {
 					fileStartTime = gPlayProperties.startAtFilePos;
-					Log_Printf(LOGLEVEL_NOTICE, trackStartatPos, gPlayProperties.startAtFilePos);
+					if (RESUME_FADEIN_DURATION_MS > 0) {
+						// Rewind a few seconds so the cold-start glitch (file open + header
+						// decode + seek-flush) lands on already-heard audio, then fade in below.
+						fileStartTime = (fileStartTime > (int32_t) RESUME_FADEIN_REWIND_S) ? (fileStartTime - (int32_t) RESUME_FADEIN_REWIND_S) : 1;
+						resumeFadeWanted = true;
+					}
+					Log_Printf(LOGLEVEL_NOTICE, trackStartatPos, fileStartTime);
 					gPlayProperties.startAtFilePos = 0;
 				}
 				String pathToTrack = gFSystem.rawPath(gPlayProperties.playlist->at(gPlayProperties.currentTrackNumber));
@@ -1116,6 +1142,11 @@ void AudioPlayer_Loop() {
 			gPlayProperties.trackFinished = true;
 			return;
 		} else {
+			if (resumeFadeWanted) {
+				// Start the (rewound) resume muted; AudioPlayer_Loop ramps the volume back up.
+				audio->setVolume(0);
+				AudioPlayer_ResumeFadeStartMs = millis();
+			}
 			if (gPlayProperties.currentTrackNumber) {
 				Led_Indicate(LedIndicatorType::PlaylistProgress);
 			}
@@ -1298,6 +1329,7 @@ void AudioPlayer_SetVolume(const int32_t _newVolume) {
 		AudioPlayer_SetCurrentVolume(_volume);
 
 		Log_Printf(LOGLEVEL_INFO, newLoudnessReceived, _volume);
+		AudioPlayer_ResumeFadeStartMs = 0; // a manual volume change cancels an active resume fade-in
 		audio->setVolume(_volume);
 		Web_SendWebsocketData(0, WebsocketCodeType::Volume);
 #ifdef MQTT_ENABLE

src/settings.h

@@ -59,6 +59,15 @@
 	//#define HALLEFFECT_SENSOR_ENABLE      // Support for hallsensor. For fine-tuning please adjust HallEffectSensor.h Please note: only user-support provided (https://forum.espuino.de/t/magnetische-hockey-tags/1449/35)
 	//#define RTC_ENABLE                    // Battery-backed real-time-clock (DS3231) on i2cBusTwo. Keeps the time correct without WiFi/NTP. RTC stores UTC; timezone is applied on top.
 
+	//################## resume fade-in (audiobook) #############################
+	// When continuing an audiobook from a saved position, opening the file + decoding the
+	// first MP3 frames + seeking briefly saturates SD/CPU, so the first ~2 s can stutter.
+	// To hide it elegantly: rewind a few seconds before the saved position and fade the
+	// volume in over that span. The glitch then lands on already-heard audio -> no content
+	// is lost, and you hear clean sound from where you stopped. Set duration to 0 to disable.
+	#define RESUME_FADEIN_DURATION_MS 2500u // fade-in length in ms (0 = feature off)
+	#define RESUME_FADEIN_REWIND_S    3u    // seconds to rewind before the saved resume-position
+
 	//################## set PAUSE_WHEN_RFID_REMOVED behaviour #############################
 	#ifdef PAUSE_WHEN_RFID_REMOVED
 		#define ACCEPT_SAME_RFID_AFTER_TRACK_END           // Accepts same RFID after playback has ended (https://forum.espuino.de/t/neues-feature-pausieren-wenn-rfid-karte-entfernt-wurde/541/2)