From ee3b64a074d6b2333296305b250f49e28740b6f0 Mon Sep 17 00:00:00 2001
From: AE <98699388+A-EDev@users.noreply.github.com>
Date: Sat, 24 Oct 2026 15:58:12 +0300
Subject: [PATCH 1/6] fix(music): measure loudness in Android's order and cap
 the cut at 20 dB

---
 src-tauri/src/api/innertube/json/loudness.rs  | 48 +++++++++++++++++++
 src-tauri/src/api/innertube/music/playback.rs | 22 +++++----
 src/lib/audio/musicAudioEngine.ts             |  4 +-
 src/lib/loudness.test.ts                      |  7 ++-
 src/lib/loudness.ts                           | 14 ++++--
 5 files changed, 79 insertions(+), 16 deletions(-)

diff --git a/src-tauri/src/api/innertube/json/loudness.rs b/src-tauri/src/api/innertube/json/loudness.rs
index bd10f928..1b52cfbb 100644
--- a/src-tauri/src/api/innertube/json/loudness.rs
+++ b/src-tauri/src/api/innertube/json/loudness.rs
@@ -19,11 +19,59 @@ pub fn loudness_db(audio_config: &Value, format: &Value) -> Option<f64> {
         })
 }
 
+/// The target the site measures perceptual loudness against when the answer leaves it out.
+const DEFAULT_TARGET_LKFS: f64 = -14.0;
+
+/// Music's loudness in Flow for Android's order (`LoudnessGain`): the perceptual loudness
+/// against its target first, then the answer's `loudnessDb`, then the format's own. The
+/// perceptual value is measured the way a listener hears the song, so it is preferred.
+#[must_use]
+pub fn music_loudness_db(audio_config: &Value, format: &Value) -> Option<f64> {
+    audio_config["perceptualLoudnessDb"]
+        .as_f64()
+        .map(|perceptual| {
+            perceptual
+                - audio_config["loudnessTargetLkfs"]
+                    .as_f64()
+                    .unwrap_or(DEFAULT_TARGET_LKFS)
+        })
+        .or_else(|| audio_config["loudnessDb"].as_f64())
+        .or_else(|| format["loudnessDb"].as_f64())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
     use serde_json::json;
 
+    // Ported from Android's LoudnessGainTest, in loudness rather than gain.
+    #[test]
+    fn music_loudness_prefers_the_perceptual_value_against_its_target() {
+        assert_eq!(
+            music_loudness_db(
+                &json!({ "loudnessDb": 9.0, "perceptualLoudnessDb": -8.0 }),
+                &json!({})
+            ),
+            Some(6.0)
+        );
+        assert_eq!(
+            music_loudness_db(
+                &json!({ "perceptualLoudnessDb": -10.0, "loudnessTargetLkfs": -16.0 }),
+                &json!({})
+            ),
+            Some(6.0)
+        );
+        assert_eq!(
+            music_loudness_db(&json!({ "loudnessDb": 4.5 }), &json!({ "loudnessDb": 9.0 })),
+            Some(4.5)
+        );
+        assert_eq!(
+            music_loudness_db(&json!({}), &json!({ "loudnessDb": 3.0 })),
+            Some(3.0)
+        );
+        assert_eq!(music_loudness_db(&json!({}), &json!({})), None);
+    }
+
     #[test]
     fn loudness_comes_from_the_config_the_format_or_the_perceptual_target() {
         assert_eq!(
diff --git a/src-tauri/src/api/innertube/music/playback.rs b/src-tauri/src/api/innertube/music/playback.rs
index 8382a86e..35eca74c 100644
--- a/src-tauri/src/api/innertube/music/playback.rs
+++ b/src-tauri/src/api/innertube/music/playback.rs
@@ -13,7 +13,7 @@
 
 use std::time::Duration;
 
-use crate::api::innertube::json::loudness::loudness_db;
+use crate::api::innertube::json::loudness::music_loudness_db;
 use serde_json::Value;
 use tracing::{debug, info, warn};
 
@@ -191,7 +191,7 @@ impl InnertubeClient {
             .as_str()
             .and_then(|s| s.parse::<u64>().ok());
         let audio_config = &res["playerConfig"]["audioConfig"];
-        let loudness_db = loudness_db(audio_config, &format);
+        let loudness_db = music_loudness_db(audio_config, &format);
         let perceptual_loudness_db = audio_config["perceptualLoudnessDb"].as_f64();
         let expires_in_seconds = streaming["expiresInSeconds"]
             .as_str()
@@ -436,21 +436,23 @@ mod tests {
     use serde_json::json;
 
     #[test]
-    fn loudness_falls_back_to_the_format_then_the_perceptual_value() {
+    fn music_loudness_takes_the_perceptual_value_before_the_others() {
         let top =
             json!({ "loudnessDb": 1.5, "perceptualLoudnessDb": -9.0, "loudnessTargetLkfs": -14.0 });
-        assert_eq!(loudness_db(&top, &json!({ "loudnessDb": 3.0 })), Some(1.5));
-
-        let visionos = json!({ "perceptualLoudnessDb": -10.59, "loudnessTargetLkfs": -14.0 });
         assert_eq!(
-            loudness_db(&visionos, &json!({ "loudnessDb": 3.41 })),
-            Some(3.41)
+            music_loudness_db(&top, &json!({ "loudnessDb": 3.0 })),
+            Some(5.0)
         );
 
-        let perceptual = loudness_db(&visionos, &json!({})).unwrap();
+        let visionos = json!({ "perceptualLoudnessDb": -10.59, "loudnessTargetLkfs": -14.0 });
+        let perceptual = music_loudness_db(&visionos, &json!({ "loudnessDb": 1.0 })).unwrap();
         assert!((perceptual - 3.41).abs() < 1e-9);
 
-        assert_eq!(loudness_db(&json!({}), &json!({})), None);
+        assert_eq!(
+            music_loudness_db(&json!({ "loudnessDb": 1.5 }), &json!({ "loudnessDb": 3.0 })),
+            Some(1.5)
+        );
+        assert_eq!(music_loudness_db(&json!({}), &json!({})), None);
     }
 
     #[test]
diff --git a/src/lib/audio/musicAudioEngine.ts b/src/lib/audio/musicAudioEngine.ts
index 50deaa65..e6ff3e96 100644
--- a/src/lib/audio/musicAudioEngine.ts
+++ b/src/lib/audio/musicAudioEngine.ts
@@ -1,4 +1,4 @@
-import { loudnessFactor } from "../loudness";
+import { loudnessFactor, MUSIC_MAX_CUT_DB } from "../loudness";
 import { createAudioContext, keepRunning, resumeWithin, webAudioSupported } from "./audioContext";
 import { EQ_GRAPH_OFF, type EqGraphSpec } from "./eq/graphPlan";
 import { EqChain, RAMP_TIME_CONSTANT } from "./eqChain";
@@ -295,7 +295,7 @@ class MusicAudioEngine {
   }
 
   private normalizationFactor(loudnessDb: number | null): number {
-    return loudnessFactor(loudnessDb, this.normalizationEnabled);
+    return loudnessFactor(loudnessDb, this.normalizationEnabled, MUSIC_MAX_CUT_DB);
   }
 
   private applyGain(): void {
diff --git a/src/lib/loudness.test.ts b/src/lib/loudness.test.ts
index 728a1479..526e22c3 100644
--- a/src/lib/loudness.test.ts
+++ b/src/lib/loudness.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { loudnessFactor } from "./loudness";
+import { loudnessFactor, MUSIC_MAX_CUT_DB } from "./loudness";
 
 describe("loudnessFactor", () => {
   it("turns a loud stream down to the target and leaves quiet ones alone", () => {
@@ -8,4 +8,9 @@ describe("loudnessFactor", () => {
     expect(loudnessFactor(6, false)).toBe(1);
     expect(loudnessFactor(null, true)).toBe(1);
   });
+
+  it("stops music at minus 20 dB, as Android does, and leaves video uncapped", () => {
+    expect(loudnessFactor(35, true, MUSIC_MAX_CUT_DB)).toBeCloseTo(0.1, 6);
+    expect(loudnessFactor(35, true)).toBeCloseTo(Math.pow(10, -35 / 20), 9);
+  });
 });
diff --git a/src/lib/loudness.ts b/src/lib/loudness.ts
index fa451643..aebc807f 100644
--- a/src/lib/loudness.ts
+++ b/src/lib/loudness.ts
@@ -1,9 +1,17 @@
+/** Android's floor for music: a track is never turned down by more than this (`LoudnessGain`). */
+export const MUSIC_MAX_CUT_DB = 20;
+
 /**
  * The volume factor that brings a stream mastered `loudnessDb` above the site's
  * target down to it. Only ever turns down: a quiet stream is left as it is
- * rather than pushed past full volume.
+ * rather than pushed past full volume. `maxCutDb` caps how far down it goes.
  */
-export function loudnessFactor(loudnessDb: number | null | undefined, enabled: boolean): number {
+export function loudnessFactor(
+  loudnessDb: number | null | undefined,
+  enabled: boolean,
+  maxCutDb = Number.POSITIVE_INFINITY,
+): number {
   if (!enabled || loudnessDb == null || !Number.isFinite(loudnessDb)) return 1;
-  return Math.min(1, Math.pow(10, -loudnessDb / 20));
+  const cutDb = Math.min(Math.max(0, loudnessDb), maxCutDb);
+  return Math.pow(10, -cutDb / 20);
 }

From 2b4d7d48604a233244df200b244ed8b553a83d01 Mon Sep 17 00:00:00 2001
From: AE <98699388+A-EDev@users.noreply.github.com>
Date: Sat, 24 Oct 2026 15:58:47 +0300
Subject: [PATCH 2/6] feat(music): play the volume slider on a perceptual curve

---
 src/lib/audio/musicAudioEngine.eq.test.ts |  4 +--
 src/lib/audio/musicAudioEngine.ts         |  4 ++-
 src/lib/audio/volumeCurve.test.ts         | 30 +++++++++++++++++++++
 src/lib/audio/volumeCurve.ts              | 33 +++++++++++++++++++++++
 src/store/useMusicPlayerStore.ts          |  2 ++
 5 files changed, 70 insertions(+), 3 deletions(-)
 create mode 100644 src/lib/audio/volumeCurve.test.ts
 create mode 100644 src/lib/audio/volumeCurve.ts

diff --git a/src/lib/audio/musicAudioEngine.eq.test.ts b/src/lib/audio/musicAudioEngine.eq.test.ts
index 34da8779..fea89618 100644
--- a/src/lib/audio/musicAudioEngine.eq.test.ts
+++ b/src/lib/audio/musicAudioEngine.eq.test.ts
@@ -95,8 +95,8 @@ describe("music EQ graph", () => {
     musicAudioEngine.setLoudness(6, true);
 
     expect(contexts).toHaveLength(0);
-    // Normalization turns the element down by itself: 6 dB over the target is about half.
-    expect(pair[0].volume).toBeCloseTo(0.25, 2);
+    // Half way on the slider is a quarter of the gain, and 6 dB over the target halves it again.
+    expect(pair[0].volume).toBeCloseTo(0.125, 2);
     expect(musicAudioEngine.isEqAvailable()).toBe(true);
   });
 
diff --git a/src/lib/audio/musicAudioEngine.ts b/src/lib/audio/musicAudioEngine.ts
index e6ff3e96..6270cf79 100644
--- a/src/lib/audio/musicAudioEngine.ts
+++ b/src/lib/audio/musicAudioEngine.ts
@@ -2,6 +2,7 @@ import { loudnessFactor, MUSIC_MAX_CUT_DB } from "../loudness";
 import { createAudioContext, keepRunning, resumeWithin, webAudioSupported } from "./audioContext";
 import { EQ_GRAPH_OFF, type EqGraphSpec } from "./eq/graphPlan";
 import { EqChain, RAMP_TIME_CONSTANT } from "./eqChain";
+import { volumeGain } from "./volumeCurve";
 
 /**
  * One of the two <audio> elements. While one plays, the other can hold the next
@@ -277,6 +278,7 @@ class MusicAudioEngine {
 
   // --- gain (volume + loudness normalization) -----------------------------
 
+  /** `volume` is the slider position; it plays on a perceptual curve. */
   setVolume(volume: number): void {
     this.volume = Math.max(0, Math.min(1, volume));
     this.applyGain();
@@ -299,7 +301,7 @@ class MusicAudioEngine {
   }
 
   private applyGain(): void {
-    const vol = this.muted ? 0 : this.volume;
+    const vol = this.muted ? 0 : volumeGain(this.volume);
 
     if (this.graphReady && this.ctx && this.volGain) {
       const t = this.ctx.currentTime;
diff --git a/src/lib/audio/volumeCurve.test.ts b/src/lib/audio/volumeCurve.test.ts
new file mode 100644
index 00000000..1601be91
--- /dev/null
+++ b/src/lib/audio/volumeCurve.test.ts
@@ -0,0 +1,30 @@
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { migrateSavedMusicVolume, volumeGain, volumePosition } from "./volumeCurve";
+
+describe("volumeCurve", () => {
+  beforeEach(() => localStorage.clear());
+
+  it("keeps the ends and puts half way at about -12 dB", () => {
+    expect(volumeGain(0)).toBe(0);
+    expect(volumeGain(1)).toBe(1);
+    expect(20 * Math.log10(volumeGain(0.5))).toBeCloseTo(-12.04, 1);
+    expect(volumeGain(volumePosition(0.3))).toBeCloseTo(0.3, 9);
+  });
+
+  it("converts an old saved gain once, so the level does not change", () => {
+    localStorage.setItem("flow_music_player", JSON.stringify({ volume: 0.25, isMuted: false }));
+    migrateSavedMusicVolume();
+    expect(JSON.parse(localStorage.getItem("flow_music_player")!)).toEqual({ volume: 0.5, isMuted: false });
+
+    migrateSavedMusicVolume();
+    expect(JSON.parse(localStorage.getItem("flow_music_player")!).volume).toBe(0.5);
+  });
+
+  it("marks a fresh install as converted", () => {
+    migrateSavedMusicVolume();
+    localStorage.setItem("flow_music_player", JSON.stringify({ volume: 0.25 }));
+    migrateSavedMusicVolume();
+    expect(JSON.parse(localStorage.getItem("flow_music_player")!).volume).toBe(0.25);
+  });
+});
diff --git a/src/lib/audio/volumeCurve.ts b/src/lib/audio/volumeCurve.ts
new file mode 100644
index 00000000..82139181
--- /dev/null
+++ b/src/lib/audio/volumeCurve.ts
@@ -0,0 +1,33 @@
+/**
+ * The music volume slider is a position, not a gain: hearing is logarithmic, so a straight gain
+ * crowds every audible change into the bottom of the slider. Squaring spreads it evenly (half
+ * way is -12 dB) while 0 stays silent and the top stays full volume.
+ */
+export const volumeGain = (position: number): number => {
+  const p = Math.max(0, Math.min(1, position));
+  return p * p;
+};
+
+/** The slider position that plays at `gain`, for carrying an older saved gain over. */
+export const volumePosition = (gain: number): number => Math.sqrt(Math.max(0, Math.min(1, gain)));
+
+const CONFIG_KEY = "flow_music_player";
+const MARKER_KEY = "flow_music_volume_curve";
+
+/**
+ * Builds before this saved the music volume as a gain. Converting it once keeps the first launch
+ * after the update exactly as loud as the last one before it.
+ */
+export function migrateSavedMusicVolume(): void {
+  try {
+    if (localStorage.getItem(MARKER_KEY)) return;
+    localStorage.setItem(MARKER_KEY, "perceptual");
+    const saved = localStorage.getItem(CONFIG_KEY);
+    if (!saved) return;
+    const config = JSON.parse(saved) as { volume?: unknown };
+    if (typeof config.volume !== "number" || !Number.isFinite(config.volume)) return;
+    localStorage.setItem(CONFIG_KEY, JSON.stringify({ ...config, volume: volumePosition(config.volume) }));
+  } catch {
+    // Unreadable storage: the store falls back to its defaults anyway.
+  }
+}
diff --git a/src/store/useMusicPlayerStore.ts b/src/store/useMusicPlayerStore.ts
index 4de40796..5c679b7c 100644
--- a/src/store/useMusicPlayerStore.ts
+++ b/src/store/useMusicPlayerStore.ts
@@ -16,6 +16,7 @@ import { normalizeBackendError } from "../lib/api/errors";
 import { recordPlayerEvent } from "../lib/playerDiagnostics";
 import { logToBackend } from "../lib/diagnostics";
 import { musicAudioEngine } from "../lib/audio/musicAudioEngine";
+import { migrateSavedMusicVolume } from "../lib/audio/volumeCurve";
 import { preloadTrack } from "../lib/musicPreload";
 import { upcomingIndex, type QueueRepeatMode } from "../lib/musicQueueOrder";
 import { restoreOriginalOrder, shuffleFrom, shuffleUpcoming } from "../lib/musicShuffle";
@@ -77,6 +78,7 @@ const loadConfig = (): PersistedMusicConfig => {
   }
 };
 
+migrateSavedMusicVolume();
 const initialConfig = loadConfig();
 
 const saveConfig = (get: () => MusicPlayerState) => {

From 9fbb9870ace194689ec62f0d67d998558b03636a Mon Sep 17 00:00:00 2001
From: AE <98699388+A-EDev@users.noreply.github.com>
Date: Sat, 24 Oct 2026 16:00:12 +0300
Subject: [PATCH 3/6] feat(music): add playback speed from 0.5x to 2x with
 pitch kept

---
 src/components/music/EqPanel.tsx           | 17 +++-----
 src/components/music/MusicAudioOptions.tsx | 50 ++++++++++++++++++++++
 src/lib/audio/musicAudioEngine.test.ts     | 35 +++++++++++++++
 src/lib/audio/musicAudioEngine.ts          | 24 +++++++++++
 src/lib/audio/musicAudioSettings.ts        |  7 ++-
 src/lib/i18n/strings.json                  |  3 ++
 src/lib/settings/schema.ts                 |  2 +
 7 files changed, 127 insertions(+), 11 deletions(-)
 create mode 100644 src/components/music/MusicAudioOptions.tsx

diff --git a/src/components/music/EqPanel.tsx b/src/components/music/EqPanel.tsx
index e80cca07..b0284d7b 100644
--- a/src/components/music/EqPanel.tsx
+++ b/src/components/music/EqPanel.tsx
@@ -5,16 +5,18 @@ import { EqLimits } from "../../lib/audio/eq/models";
 import { withBassBoost } from "../../lib/audio/eq/stateOps";
 import { pickEqPreset, restoreCustomEq, useEqualizer, useMusicEqAvailable } from "../../lib/audio/eq/useEqualizer";
 import { getString } from "../../lib/i18n/index";
-import { SETTINGS } from "../../lib/settings/schema";
-import { useBoolPref } from "../../lib/usePreference";
 import { useEqStore } from "../../store/useEqStore";
 import { Chip } from "../ui/Chip";
 import { Slider } from "../ui/Slider";
 import { ToggleSwitch } from "../ui/ToggleSwitch";
 import { EqResponseGraph } from "./eq/EqResponseGraph";
 import { formatDb } from "./eq/eqFormat";
+import { MusicAudioOptions } from "./MusicAudioOptions";
 
-/** The quick equalizer panel: switch, curve, presets and bass boost, with Edit for the rest. */
+/**
+ * The quick audio panel: the equalizer's switch, curve, presets and bass boost with Edit for the
+ * rest, then the other music audio settings.
+ */
 export function EqPanel({
   open,
   onClose,
@@ -28,7 +30,6 @@ export function EqPanel({
   const available = useMusicEqAvailable();
   const update = useEqStore((s) => s.update);
   const setEditorOpen = useEqStore((s) => s.setEditorOpen);
-  const [normalization, setNormalization] = useBoolPref(SETTINGS.MUSIC_LOUDNESS_NORMALIZATION);
 
   const fromY = placement === "top" ? 10 : -10;
   const selectedId = eq.active.presetId;
@@ -127,12 +128,8 @@ export function EqPanel({
             {getString("eq_edit")}
           </button>
 
-          <div className="mt-4 flex items-center justify-between gap-3 border-t border-chrome-neutral-800 pt-3">
-            <span className="flex min-w-0 flex-col">
-              <span className="text-sm text-chrome-neutral-200">{getString("music_loudness_normalization")}</span>
-              <span className="text-xs text-chrome-neutral-500">{getString("music_loudness_normalization_desc")}</span>
-            </span>
-            <ToggleSwitch checked={normalization} onChange={setNormalization} />
+          <div className="mt-4 border-t border-chrome-neutral-800 pt-3">
+            <MusicAudioOptions />
           </div>
         </motion.div>
       )}
diff --git a/src/components/music/MusicAudioOptions.tsx b/src/components/music/MusicAudioOptions.tsx
new file mode 100644
index 00000000..cc547e58
--- /dev/null
+++ b/src/components/music/MusicAudioOptions.tsx
@@ -0,0 +1,50 @@
+import { getString } from "../../lib/i18n/index";
+import { SETTINGS } from "../../lib/settings/schema";
+import { useBoolPref, useNumberPref } from "../../lib/usePreference";
+import { Chip } from "../ui/Chip";
+import { Slider } from "../ui/Slider";
+import { ToggleSwitch } from "../ui/ToggleSwitch";
+
+const SPEED_PRESETS = [0.5, 0.75, 1, 1.25, 1.5, 2] as const;
+
+const formatSpeed = (rate: number) => getString("music_speed_value", Number(rate.toFixed(2)));
+
+/** Music audio settings beside the equalizer: loudness normalization and speed. */
+export function MusicAudioOptions() {
+  const [normalization, setNormalization] = useBoolPref(SETTINGS.MUSIC_LOUDNESS_NORMALIZATION);
+  const [speed, setSpeed] = useNumberPref(SETTINGS.MUSIC_PLAYBACK_SPEED);
+
+  return (
+    <div className="flex flex-col gap-3">
+      <div className="flex items-center justify-between gap-3">
+        <span className="flex min-w-0 flex-col">
+          <span className="text-sm text-chrome-neutral-200">{getString("music_loudness_normalization")}</span>
+          <span className="text-xs text-chrome-neutral-500">{getString("music_loudness_normalization_desc")}</span>
+        </span>
+        <ToggleSwitch checked={normalization} onChange={setNormalization} />
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <span className="flex items-center justify-between">
+          <span className="text-sm text-chrome-neutral-200">{getString("music_playback_speed")}</span>
+          <span className="font-mono text-xs text-chrome-neutral-400">{formatSpeed(speed)}</span>
+        </span>
+        <div className="flex flex-wrap gap-1.5">
+          {SPEED_PRESETS.map((rate) => (
+            <Chip key={rate} active={speed === rate} onClick={() => setSpeed(rate)} className="h-7 px-2.5 text-xs">
+              {formatSpeed(rate)}
+            </Chip>
+          ))}
+        </div>
+        <Slider
+          min={0.5}
+          max={2}
+          step={0.05}
+          value={speed}
+          onChange={(rate) => setSpeed(Math.round(rate * 100) / 100)}
+          aria-label={getString("music_playback_speed")}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/src/lib/audio/musicAudioEngine.test.ts b/src/lib/audio/musicAudioEngine.test.ts
index 57661493..9fea2535 100644
--- a/src/lib/audio/musicAudioEngine.test.ts
+++ b/src/lib/audio/musicAudioEngine.test.ts
@@ -66,3 +66,38 @@ describe("gapless standby element", () => {
     expect(musicAudioEngine.clearPreload()).toBeNull();
   });
 });
+
+describe("music speed", () => {
+  // Counts writes: on WebKitGTK every playbackRate write flushes the audio pipeline.
+  const countRateWrites = (el: HTMLAudioElement) => {
+    let rate = 1;
+    const writes = { count: 0 };
+    Object.defineProperty(el, "playbackRate", {
+      configurable: true,
+      get: () => rate,
+      set: (value: number) => {
+        writes.count++;
+        rate = value;
+      },
+    });
+    return writes;
+  };
+
+  it("writes the rate only when it changes, and carries it across loads", () => {
+    const fresh = elements();
+    const writes = countRateWrites(fresh[0]);
+    musicAudioEngine.attach(fresh);
+    musicAudioEngine.setSpeed(1);
+    expect(writes.count).toBe(0);
+
+    musicAudioEngine.setSpeed(1.5);
+    musicAudioEngine.setSpeed(1.5);
+    expect(writes.count).toBe(1);
+    expect(fresh[0].defaultPlaybackRate).toBe(1.5);
+    expect(fresh[0].preservesPitch).toBe(true);
+
+    musicAudioEngine.setSpeed(9);
+    expect(fresh[0].playbackRate).toBe(2);
+    musicAudioEngine.setSpeed(1);
+  });
+});
diff --git a/src/lib/audio/musicAudioEngine.ts b/src/lib/audio/musicAudioEngine.ts
index 6270cf79..36d6e490 100644
--- a/src/lib/audio/musicAudioEngine.ts
+++ b/src/lib/audio/musicAudioEngine.ts
@@ -45,6 +45,7 @@ class MusicAudioEngine {
   private normalizationEnabled = true;
   private eqSpec: EqGraphSpec = EQ_GRAPH_OFF;
   private eqEngaged = false;
+  private speed = 1;
 
   private get active(): Slot {
     return this.slots[this.activeIndex];
@@ -65,9 +66,11 @@ class MusicAudioEngine {
       // Required for WebAudio to receive (non-silent) cross-origin samples.
       el.crossOrigin = "anonymous";
       el.preload = "auto";
+      el.preservesPitch = true;
       this.slots[i as 0 | 1].el = el;
     }
     this.graphReady = false;
+    this.applySpeed();
     if (this.eqEngaged) this.ensureGraph();
     this.applyGain();
   }
@@ -276,6 +279,27 @@ class MusicAudioEngine {
     return Number.isFinite(d) ? d : 0;
   }
 
+  // --- speed --------------------------------------------------------------
+
+  setSpeed(rate: number): void {
+    this.speed = Math.max(0.5, Math.min(2, rate));
+    this.applySpeed();
+  }
+
+  /**
+   * WebKitGTK flushes its GStreamer pipeline on every `playbackRate` write, so the rate is only
+   * written when it differs. The default rate carries it across loads, which reset
+   * `playbackRate` to it.
+   */
+  private applySpeed(): void {
+    for (const slot of this.slots) {
+      const el = slot.el;
+      if (!el) continue;
+      if (el.defaultPlaybackRate !== this.speed) el.defaultPlaybackRate = this.speed;
+      if (el.playbackRate !== this.speed) el.playbackRate = this.speed;
+    }
+  }
+
   // --- gain (volume + loudness normalization) -----------------------------
 
   /** `volume` is the slider position; it plays on a perceptual curve. */
diff --git a/src/lib/audio/musicAudioSettings.ts b/src/lib/audio/musicAudioSettings.ts
index ef2d6c3c..d05e30c2 100644
--- a/src/lib/audio/musicAudioSettings.ts
+++ b/src/lib/audio/musicAudioSettings.ts
@@ -23,9 +23,14 @@ export function bindMusicAudioSettings(): void {
     const player = useMusicPlayerStore.getState();
     if (player.normalizationEnabled !== enabled) player.setNormalizationEnabled(enabled);
   };
+  const applySpeed = () => musicAudioEngine.setSpeed(Number(getSettingValue(SETTINGS.MUSIC_PLAYBACK_SPEED)));
+
   applyNormalization();
+  applySpeed();
   useAppSettingsStore.subscribe((state, previous) => {
-    if (state.values !== previous.values) applyNormalization();
+    if (state.values === previous.values) return;
+    applyNormalization();
+    applySpeed();
   });
 
   const applyEq = () => {
diff --git a/src/lib/i18n/strings.json b/src/lib/i18n/strings.json
index 063e7323..0efcc6c5 100644
--- a/src/lib/i18n/strings.json
+++ b/src/lib/i18n/strings.json
@@ -1038,6 +1038,9 @@
   "music_equalizer": "Equalizer",
   "music_loudness_normalization": "Loudness normalization",
   "music_loudness_normalization_desc": "Turns down songs mastered louder than YouTube Music's target",
+  "music_audio_playback": "Playback",
+  "music_playback_speed": "Speed",
+  "music_speed_value": "%s×",
   "eq_preset_flat": "Flat",
   "eq_preset_acoustic": "Acoustic",
   "eq_preset_bass_boost": "Bass Boost",
diff --git a/src/lib/settings/schema.ts b/src/lib/settings/schema.ts
index 9a25f9ea..b4836497 100644
--- a/src/lib/settings/schema.ts
+++ b/src/lib/settings/schema.ts
@@ -109,6 +109,7 @@ export const SETTINGS = {
 
   MUSIC_LOUDNESS_NORMALIZATION: "music_loudness_normalization",
   EQ_STATE_JSON: "eq_state_json",
+  MUSIC_PLAYBACK_SPEED: "music_playback_speed",
 
   BUFFER_PROFILE: "buffer_profile",
   MIN_BUFFER_MS: "min_buffer_ms",
@@ -320,6 +321,7 @@ export const SETTING_DEFINITIONS = [
   bool(SETTINGS.MUSIC_LOUDNESS_NORMALIZATION, "player", true, "wired"),
   // Flow for Android's equalizer JSON, shared by music and video and synced as `equalizer`.
   json(SETTINGS.EQ_STATE_JSON, "player", "{}", "wired"),
+  num(SETTINGS.MUSIC_PLAYBACK_SPEED, "player", 1, "wired", 0.5, 2),
 
   str(SETTINGS.BUFFER_PROFILE, "network", "STABLE", "wired", ["AGGRESSIVE", "STABLE", "DATASAVER", "CUSTOM"]),
   num(SETTINGS.MIN_BUFFER_MS, "network", 30000, "wired", 5000, 120000),

From 4d824fb13bf24ef73cdb9cf371450304fa06a129 Mon Sep 17 00:00:00 2001
From: AE <98699388+A-EDev@users.noreply.github.com>
Date: Sat, 24 Oct 2026 16:02:07 +0300
Subject: [PATCH 4/6] feat(music): add an optional crossfade between songs

---
 src/components/music/MusicAudioOptions.tsx |  30 ++++-
 src/lib/audio/crossfade.test.ts            |  61 +++++++++
 src/lib/audio/crossfade.ts                 |  37 ++++++
 src/lib/audio/crossfadeRamp.ts             |  42 ++++++
 src/lib/audio/musicAudioEngine.eq.test.ts  |  66 +++++++++-
 src/lib/audio/musicAudioEngine.ts          | 141 +++++++++++++++++----
 src/lib/audio/musicAudioSettings.test.ts   |   2 +-
 src/lib/audio/musicAudioSettings.ts        |  20 +++
 src/lib/i18n/strings.json                  |   3 +
 src/lib/settings/schema.ts                 |   4 +
 10 files changed, 376 insertions(+), 30 deletions(-)
 create mode 100644 src/lib/audio/crossfade.test.ts
 create mode 100644 src/lib/audio/crossfade.ts
 create mode 100644 src/lib/audio/crossfadeRamp.ts

diff --git a/src/components/music/MusicAudioOptions.tsx b/src/components/music/MusicAudioOptions.tsx
index cc547e58..71481a65 100644
--- a/src/components/music/MusicAudioOptions.tsx
+++ b/src/components/music/MusicAudioOptions.tsx
@@ -9,10 +9,12 @@ const SPEED_PRESETS = [0.5, 0.75, 1, 1.25, 1.5, 2] as const;
 
 const formatSpeed = (rate: number) => getString("music_speed_value", Number(rate.toFixed(2)));
 
-/** Music audio settings beside the equalizer: loudness normalization and speed. */
+/** Music audio settings beside the equalizer: loudness normalization, speed and crossfade. */
 export function MusicAudioOptions() {
   const [normalization, setNormalization] = useBoolPref(SETTINGS.MUSIC_LOUDNESS_NORMALIZATION);
   const [speed, setSpeed] = useNumberPref(SETTINGS.MUSIC_PLAYBACK_SPEED);
+  const [crossfade, setCrossfade] = useBoolPref(SETTINGS.MUSIC_CROSSFADE_ENABLED);
+  const [crossfadeSeconds, setCrossfadeSeconds] = useNumberPref(SETTINGS.MUSIC_CROSSFADE_SECONDS);
 
   return (
     <div className="flex flex-col gap-3">
@@ -45,6 +47,32 @@ export function MusicAudioOptions() {
           aria-label={getString("music_playback_speed")}
         />
       </div>
+
+      <div className="flex flex-col gap-2">
+        <div className="flex items-center justify-between gap-3">
+          <span className="flex min-w-0 flex-col">
+            <span className="text-sm text-chrome-neutral-200">{getString("music_crossfade")}</span>
+            <span className="text-xs text-chrome-neutral-500">{getString("music_crossfade_desc")}</span>
+          </span>
+          <ToggleSwitch checked={crossfade} onChange={setCrossfade} />
+        </div>
+        {crossfade && (
+          <div className="flex items-center gap-3">
+            <Slider
+              min={1}
+              max={12}
+              step={1}
+              value={crossfadeSeconds}
+              onChange={setCrossfadeSeconds}
+              aria-label={getString("music_crossfade")}
+              className="flex-1"
+            />
+            <span className="w-10 text-right font-mono text-xs text-chrome-neutral-400">
+              {getString("music_crossfade_seconds", crossfadeSeconds)}
+            </span>
+          </div>
+        )}
+      </div>
     </div>
   );
 }
diff --git a/src/lib/audio/crossfade.test.ts b/src/lib/audio/crossfade.test.ts
new file mode 100644
index 00000000..173a219a
--- /dev/null
+++ b/src/lib/audio/crossfade.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+
+import type { SongItem } from "../../types/music";
+import { crossfadeTarget, type CrossfadeQueue } from "./crossfade";
+
+const song = (id: string, albumId: string | null = null): SongItem => ({
+  id,
+  title: id,
+  artists: [],
+  album: albumId ? { id: albumId, name: albumId } : null,
+  duration: 200,
+  musicVideoType: "MUSIC_VIDEO_TYPE_ATV",
+  thumbnail: "",
+  explicit: false,
+  videoId: id,
+  playlistId: null,
+  params: null,
+});
+
+const near = (patch: Partial<CrossfadeQueue> = {}): CrossfadeQueue => {
+  const queue = [song("a"), song("b")];
+  return {
+    queue,
+    currentIndex: 0,
+    currentTrack: queue[0]!,
+    isShuffle: false,
+    repeatMode: "none",
+    isPlaying: true,
+    loadingStreamId: null,
+    progress: 196,
+    duration: 200,
+    ...patch,
+  };
+};
+
+describe("crossfadeTarget", () => {
+  it("starts the fade once the song is inside its last seconds", () => {
+    expect(crossfadeTarget(near(), 5)).toBe(1);
+    expect(crossfadeTarget(near({ progress: 190 }), 5)).toBe(-1);
+    expect(crossfadeTarget(near({ progress: 199.9 }), 5)).toBe(-1);
+  });
+
+  it("stays off when disabled, paused, loading, on repeat-one or at the end of the queue", () => {
+    expect(crossfadeTarget(near(), 0)).toBe(-1);
+    expect(crossfadeTarget(near({ isPlaying: false }), 5)).toBe(-1);
+    expect(crossfadeTarget(near({ loadingStreamId: "a" }), 5)).toBe(-1);
+    expect(crossfadeTarget(near({ repeatMode: "one" }), 5)).toBe(-1);
+    expect(crossfadeTarget(near({ queue: [song("a")] }), 5)).toBe(-1);
+  });
+
+  it("keeps consecutive album tracks gapless unless shuffled", () => {
+    const album = [song("a", "LP"), song("b", "LP")];
+    const inOrder = near({ queue: album, currentTrack: album[0]! });
+    expect(crossfadeTarget(inOrder, 5)).toBe(-1);
+    expect(crossfadeTarget({ ...inOrder, isShuffle: true }, 5)).toBe(1);
+  });
+
+  it("never fades a song too short to hold the fade twice", () => {
+    expect(crossfadeTarget(near({ duration: 8, progress: 5 }), 5)).toBe(-1);
+  });
+});
diff --git a/src/lib/audio/crossfade.ts b/src/lib/audio/crossfade.ts
new file mode 100644
index 00000000..c1618bf1
--- /dev/null
+++ b/src/lib/audio/crossfade.ts
@@ -0,0 +1,37 @@
+import type { SongItem } from "../../types/music";
+import { upcomingIndex, type QueueRepeatMode } from "../musicQueueOrder";
+
+export interface CrossfadeQueue {
+  queue: SongItem[];
+  currentIndex: number;
+  currentTrack: SongItem | null;
+  isShuffle: boolean;
+  repeatMode: QueueRepeatMode;
+  isPlaying: boolean;
+  loadingStreamId: string | null;
+  progress: number;
+  duration: number;
+}
+
+/**
+ * Tracks in album order are often meant to run into each other (a live set, a concept album, a
+ * continuous mix), so they keep their gapless join instead of being faded across.
+ */
+const playsInAlbumOrder = (s: CrossfadeQueue, next: SongItem): boolean =>
+  !s.isShuffle && !!s.currentTrack?.album?.id && s.currentTrack.album.id === next.album?.id;
+
+/**
+ * The queue index to crossfade into now, or -1. Fades start `seconds` before the end, never on
+ * repeat-one, never between consecutive album tracks, and never on a track too short to hold
+ * two fades.
+ */
+export function crossfadeTarget(s: CrossfadeQueue, seconds: number): number {
+  if (seconds <= 0 || !s.isPlaying || s.loadingStreamId !== null || s.repeatMode === "one") return -1;
+  if (!(s.duration > seconds * 2)) return -1;
+  const remaining = s.duration - s.progress;
+  if (remaining > seconds || remaining <= 0.25) return -1;
+  const index = upcomingIndex(s);
+  const next = s.queue[index];
+  if (!next || index === s.currentIndex || playsInAlbumOrder(s, next)) return -1;
+  return index;
+}
diff --git a/src/lib/audio/crossfadeRamp.ts b/src/lib/audio/crossfadeRamp.ts
new file mode 100644
index 00000000..c84a8e32
--- /dev/null
+++ b/src/lib/audio/crossfadeRamp.ts
@@ -0,0 +1,42 @@
+const CURVE_POINTS = 32;
+const STEP_MS = 100;
+
+/** Equal-power gains for `t` in 0..1: the sum of both sides' power stays constant. */
+export const fadeInGain = (t: number): number => Math.sin((Math.max(0, Math.min(1, t)) * Math.PI) / 2);
+export const fadeOutGain = (t: number): number => Math.cos((Math.max(0, Math.min(1, t)) * Math.PI) / 2);
+
+function curve(gain: (t: number) => number): Float32Array<ArrayBuffer> {
+  const values = new Float32Array(CURVE_POINTS);
+  for (let i = 0; i < CURVE_POINTS; i++) values[i] = gain(i / (CURVE_POINTS - 1));
+  return values;
+}
+
+/**
+ * Schedules a whole fade on the audio clock, so it runs smoothly even while the window is hidden
+ * and timers are throttled.
+ */
+export function scheduleFade(param: AudioParam, direction: "in" | "out", startTime: number, seconds: number): void {
+  param.cancelScheduledValues(startTime);
+  param.setValueCurveAtTime(curve(direction === "in" ? fadeInGain : fadeOutGain), startTime, seconds);
+}
+
+/** Puts `param` back at full level at once, dropping any fade still scheduled on it. */
+export function resetFade(param: AudioParam, time: number): void {
+  param.cancelScheduledValues(time);
+  param.setValueAtTime(1, time);
+}
+
+/**
+ * The fallback without WebAudio: element volume moved in steps. Returns a cancel function.
+ * `onStep` gets the fade's progress from 0 to 1.
+ */
+export function steppedFade(seconds: number, onStep: (progress: number) => void): () => void {
+  const started = Date.now();
+  onStep(0);
+  const timer = setInterval(() => {
+    const progress = Math.min(1, (Date.now() - started) / (seconds * 1_000));
+    onStep(progress);
+    if (progress >= 1) clearInterval(timer);
+  }, STEP_MS);
+  return () => clearInterval(timer);
+}
diff --git a/src/lib/audio/musicAudioEngine.eq.test.ts b/src/lib/audio/musicAudioEngine.eq.test.ts
index fea89618..56883f91 100644
--- a/src/lib/audio/musicAudioEngine.eq.test.ts
+++ b/src/lib/audio/musicAudioEngine.eq.test.ts
@@ -10,6 +10,13 @@ class FakeParam {
   setTargetAtTime = vi.fn((value: number) => {
     this.value = value;
   });
+  setValueAtTime = vi.fn((value: number) => {
+    this.value = value;
+  });
+  cancelScheduledValues = vi.fn();
+  setValueCurveAtTime = vi.fn((curve: Float32Array, _start: number, _seconds: number) => {
+    this.value = curve[curve.length - 1] ?? this.value;
+  });
 }
 class FakeNode {
   connect = vi.fn((node: unknown) => node);
@@ -34,6 +41,7 @@ class FakeContext extends EventTarget {
   sampleRate = 48_000;
   destination = new FakeNode();
   biquads: FakeBiquad[] = [];
+  gains: FakeGain[] = [];
   sources: HTMLMediaElement[] = [];
   resume = vi.fn(async () => {
     this.state = "running";
@@ -43,7 +51,9 @@ class FakeContext extends EventTarget {
     contexts.push(this);
   }
   createGain() {
-    return new FakeGain();
+    const g = new FakeGain();
+    this.gains.push(g);
+    return g;
   }
   createBiquadFilter() {
     const f = new FakeBiquad();
@@ -151,4 +161,58 @@ describe("music EQ graph", () => {
     ctx.dispatchEvent(new Event("statechange"));
     expect(ctx.resume).toHaveBeenCalled();
   });
+
+  it("crossfades into a buffered song on the audio clock, then empties the one that ended", async () => {
+    vi.useFakeTimers();
+    const pair = elements();
+    musicAudioEngine.attach(pair);
+    musicAudioEngine.setCrossfadeEnabled(true);
+    const ctx = lastContext();
+    await musicAudioEngine.load("http://127.0.0.1/stream/a");
+    musicAudioEngine.preload("b", "http://127.0.0.1/stream/b", null);
+    Object.defineProperty(pair[1], "readyState", { value: HTMLMediaElement.HAVE_FUTURE_DATA, configurable: true });
+    Object.defineProperty(pair[0], "paused", { value: false, configurable: true });
+
+    musicAudioEngine.armCrossfade(4);
+    expect(musicAudioEngine.activatePreloaded("b")).toBe(true);
+
+    expect(musicAudioEngine.getActiveElement()).toBe(pair[1]);
+    expect(pair[0].getAttribute("src")).toBe("http://127.0.0.1/stream/a");
+    const fades = ctx.gains.filter((g) => g.gain.setValueCurveAtTime.mock.calls.length > 0);
+    expect(fades).toHaveLength(2);
+    expect(fades.every((g) => g.gain.setValueCurveAtTime.mock.calls[0]![2] === 4)).toBe(true);
+
+    await vi.advanceTimersByTimeAsync(4_100);
+    expect(pair[0].getAttribute("src")).toBeNull();
+    musicAudioEngine.setCrossfadeEnabled(false);
+  });
+});
+
+describe("crossfade without WebAudio", () => {
+  it("steps the two elements' volume instead", async () => {
+    vi.useFakeTimers();
+    vi.stubGlobal("AudioContext", undefined);
+    vi.resetModules();
+    const { musicAudioEngine: engine } = await import("./musicAudioEngine");
+    const pair = elements();
+    engine.attach(pair);
+    engine.setCrossfadeEnabled(true);
+    expect(engine.isEqAvailable()).toBe(false);
+
+    await engine.load("http://127.0.0.1/stream/a");
+    engine.preload("b", "http://127.0.0.1/stream/b", null);
+    Object.defineProperty(pair[1], "readyState", { value: HTMLMediaElement.HAVE_FUTURE_DATA, configurable: true });
+    Object.defineProperty(pair[0], "paused", { value: false, configurable: true });
+    engine.armCrossfade(2);
+    engine.activatePreloaded("b");
+
+    expect(pair[1].volume).toBe(0);
+    await vi.advanceTimersByTimeAsync(1_000);
+    expect(pair[0].volume).toBeGreaterThan(0.6);
+    expect(pair[0].volume).toBeLessThan(0.8);
+    expect(pair[1].volume).toBeCloseTo(pair[0].volume, 1);
+    await vi.advanceTimersByTimeAsync(1_200);
+    expect(pair[1].volume).toBe(1);
+    expect(pair[0].getAttribute("src")).toBeNull();
+  });
 });
diff --git a/src/lib/audio/musicAudioEngine.ts b/src/lib/audio/musicAudioEngine.ts
index 36d6e490..16a2e7a8 100644
--- a/src/lib/audio/musicAudioEngine.ts
+++ b/src/lib/audio/musicAudioEngine.ts
@@ -1,5 +1,7 @@
 import { loudnessFactor, MUSIC_MAX_CUT_DB } from "../loudness";
+import { IS_LINUX_RUNTIME } from "../platform";
 import { createAudioContext, keepRunning, resumeWithin, webAudioSupported } from "./audioContext";
+import { fadeInGain, fadeOutGain, resetFade, scheduleFade, steppedFade } from "./crossfadeRamp";
 import { EQ_GRAPH_OFF, type EqGraphSpec } from "./eq/graphPlan";
 import { EqChain, RAMP_TIME_CONSTANT } from "./eqChain";
 import { volumeGain } from "./volumeCurve";
@@ -13,12 +15,24 @@ interface Slot {
   el: HTMLAudioElement | null;
   source: MediaElementAudioSourceNode | null;
   normGain: GainNode | null;
+  /** The crossfade's share of this element, on the audio clock. */
+  fadeGain: GainNode | null;
+  /** The same share when WebAudio is not in use, applied to the element's volume. */
+  fade: number;
   loudnessDb: number | null;
   /** The track a standby slot holds, so a swap only ever plays the right one. */
   key: string | null;
 }
 
-const emptySlot = (): Slot => ({ el: null, source: null, normGain: null, loudnessDb: null, key: null });
+const emptySlot = (): Slot => ({
+  el: null,
+  source: null,
+  normGain: null,
+  fadeGain: null,
+  fade: 1,
+  loudnessDb: null,
+  key: null,
+});
 
 function unload(el: HTMLAudioElement): void {
   el.pause();
@@ -29,6 +43,12 @@ function unload(el: HTMLAudioElement): void {
   }
 }
 
+interface Fade {
+  previous: Slot;
+  done: ReturnType<typeof setTimeout>;
+  cancelSteps: (() => void) | null;
+}
+
 class MusicAudioEngine {
   private slots: [Slot, Slot] = [emptySlot(), emptySlot()];
   private activeIndex: 0 | 1 = 0;
@@ -46,6 +66,9 @@ class MusicAudioEngine {
   private eqSpec: EqGraphSpec = EQ_GRAPH_OFF;
   private eqEngaged = false;
   private speed = 1;
+  private crossfadeEnabled = false;
+  private armedFadeSeconds: number | null = null;
+  private fading: Fade | null = null;
 
   private get active(): Slot {
     return this.slots[this.activeIndex];
@@ -62,6 +85,7 @@ class MusicAudioEngine {
     if (this.slots[0].el === elements[0] && this.slots[1].el === elements[1]) return;
     this.slots = [emptySlot(), emptySlot()];
     this.activeIndex = 0;
+    this.fading = null;
     for (const [i, el] of elements.entries()) {
       // Required for WebAudio to receive (non-silent) cross-origin samples.
       el.crossOrigin = "anonymous";
@@ -71,7 +95,7 @@ class MusicAudioEngine {
     }
     this.graphReady = false;
     this.applySpeed();
-    if (this.eqEngaged) this.ensureGraph();
+    if (this.eqEngaged || this.crossfadeEnabled) this.ensureGraph();
     this.applyGain();
   }
 
@@ -81,9 +105,9 @@ class MusicAudioEngine {
   }
 
   /**
-   * Routes both elements through WebAudio. Done only once the equalizer changes the sound: a
-   * media element taken over by WebAudio can never play on its own again, and loudness
-   * normalization only ever turns down, which the element's own volume does.
+   * Routes both elements through WebAudio. Done only once the equalizer changes the sound or
+   * crossfade is on: a media element taken over by WebAudio can never play on its own again, and
+   * loudness normalization only ever turns down, which the element's own volume does.
    */
   private ensureGraph(): void {
     if (this.graphReady || this.webAudioFailed || !this.slots[0].el || !this.slots[1].el) return;
@@ -101,14 +125,17 @@ class MusicAudioEngine {
       this.chain.output.connect(this.volGain);
       this.volGain.connect(ctx.destination);
 
-      // Each element keeps its own loudness gain, since the two hold different
-      // tracks; both feed the one shared EQ and volume chain.
+      // Each element keeps its own loudness and crossfade gains, since the two
+      // hold different tracks; both feed the one shared EQ and volume chain.
       for (const slot of this.slots) {
         if (!slot.el) continue;
         slot.source = ctx.createMediaElementSource(slot.el);
         slot.normGain = ctx.createGain();
+        slot.fadeGain = ctx.createGain();
+        slot.fadeGain.gain.value = slot.fade;
         slot.source.connect(slot.normGain);
-        slot.normGain.connect(this.chain.input);
+        slot.normGain.connect(slot.fadeGain);
+        slot.fadeGain.connect(this.chain.input);
       }
 
       this.graphReady = true;
@@ -140,11 +167,11 @@ class MusicAudioEngine {
   /**
    * Start buffering `url` on the standby element for the track `key`, so it can
    * take over the moment the current track ends. A no-op when it already holds
-   * that track.
+   * that track, or while it is still fading out the last one.
    */
   preload(key: string, url: string, loudnessDb: number | null): void {
     const slot = this.standby;
-    if (!slot.el || slot.key === key) return;
+    if (!slot.el || slot.key === key || this.fading) return;
     slot.key = key;
     slot.loudnessDb = loudnessDb;
     slot.el.src = url;
@@ -165,7 +192,7 @@ class MusicAudioEngine {
    * One whose fetch failed or never delivered anything would stall forever if
    * swapped in, so it is skipped and the track loads the normal way.
    */
-  private preloadIsPlayable(key: string): boolean {
+  canPlayPreloaded(key: string): boolean {
     const el = this.standby.el;
     return (
       this.hasPreloaded(key) &&
@@ -175,30 +202,83 @@ class MusicAudioEngine {
     );
   }
 
+  /** Makes the next `activatePreloaded` a crossfade of `seconds` instead of a cut. */
+  armCrossfade(seconds: number): void {
+    this.armedFadeSeconds = seconds > 0 ? seconds : null;
+  }
+
   /**
    * Make the standby element the active one when it holds `key`. The caller
-   * then plays it; the element that was playing is emptied.
+   * then plays it; the element that was playing is emptied, at once or at the
+   * end of an armed crossfade.
    */
   activatePreloaded(key: string): boolean {
-    if (!this.preloadIsPlayable(key)) return false;
+    const fadeSeconds = this.armedFadeSeconds;
+    this.armedFadeSeconds = null;
+    if (!this.canPlayPreloaded(key)) return false;
+    this.finishFade();
     const previous = this.active;
     this.activeIndex = this.activeIndex === 0 ? 1 : 0;
     this.active.key = null;
-    if (previous.el) unload(previous.el);
-    previous.key = null;
-    previous.loudnessDb = null;
+    if (fadeSeconds !== null && previous.el && !previous.el.paused) {
+      this.startFade(previous, fadeSeconds);
+    } else {
+      this.release(previous);
+    }
     this.applyGain();
     return true;
   }
 
+  private release(slot: Slot): void {
+    if (slot.el) unload(slot.el);
+    slot.key = null;
+    slot.loudnessDb = null;
+  }
+
+  // The two elements play together while their gains move in opposite directions; the one
+  // fading out is emptied when the fade ends.
+  private startFade(previous: Slot, seconds: number): void {
+    const next = this.active;
+    let cancelSteps: (() => void) | null = null;
+    if (this.graphReady && this.ctx && previous.fadeGain && next.fadeGain) {
+      const t = this.ctx.currentTime;
+      scheduleFade(previous.fadeGain.gain, "out", t, seconds);
+      scheduleFade(next.fadeGain.gain, "in", t, seconds);
+    } else {
+      cancelSteps = steppedFade(seconds, (progress) => {
+        previous.fade = fadeOutGain(progress);
+        next.fade = fadeInGain(progress);
+        this.applyGain();
+      });
+    }
+    const done = setTimeout(() => this.finishFade(), seconds * 1_000 + 50);
+    this.fading = { previous, done, cancelSteps };
+  }
+
+  /** Ends a crossfade now: the outgoing element is emptied and both gains return to full. */
+  private finishFade(): void {
+    const fading = this.fading;
+    if (!fading) return;
+    this.fading = null;
+    clearTimeout(fading.done);
+    fading.cancelSteps?.();
+    this.release(fading.previous);
+    for (const slot of this.slots) {
+      slot.fade = 1;
+      if (this.ctx && slot.fadeGain) resetFade(slot.fadeGain.gain, this.ctx.currentTime);
+    }
+    this.applyGain();
+    // A speed change made during the fade was held back on Linux; apply it now.
+    this.applySpeed();
+  }
+
   /** Drop whatever the standby element holds, returning the track it was. */
   clearPreload(): string | null {
+    this.finishFade();
     const slot = this.standby;
     const key = slot.key;
     if (key === null) return null;
-    slot.key = null;
-    slot.loudnessDb = null;
-    if (slot.el) unload(slot.el);
+    this.release(slot);
     return key;
   }
 
@@ -240,15 +320,13 @@ class MusicAudioEngine {
   }
 
   pause(): void {
+    this.finishFade();
     this.active.el?.pause();
   }
 
   stop(): void {
-    for (const slot of this.slots) {
-      slot.key = null;
-      slot.loudnessDb = null;
-      if (slot.el) unload(slot.el);
-    }
+    this.finishFade();
+    for (const slot of this.slots) this.release(slot);
   }
 
   seek(seconds: number): void {
@@ -288,10 +366,11 @@ class MusicAudioEngine {
 
   /**
    * WebKitGTK flushes its GStreamer pipeline on every `playbackRate` write, so the rate is only
-   * written when it differs. The default rate carries it across loads, which reset
-   * `playbackRate` to it.
+   * written when it differs, and on Linux not while two elements are crossfading. The default
+   * rate carries it across loads, which reset `playbackRate` to it.
    */
   private applySpeed(): void {
+    if (IS_LINUX_RUNTIME && this.fading) return;
     for (const slot of this.slots) {
       const el = slot.el;
       if (!el) continue;
@@ -341,12 +420,20 @@ class MusicAudioEngine {
       for (const slot of this.slots) {
         if (!slot.el) continue;
         const norm = this.normalizationFactor(slot.loudnessDb);
-        slot.el.volume = Math.max(0, Math.min(1, vol * norm));
+        slot.el.volume = Math.max(0, Math.min(1, vol * norm * slot.fade));
         slot.el.muted = this.muted;
       }
     }
   }
 
+  // --- crossfade ----------------------------------------------------------
+
+  /** Crossfades are timed on the audio clock, so turning them on brings WebAudio in. */
+  setCrossfadeEnabled(enabled: boolean): void {
+    this.crossfadeEnabled = enabled;
+    if (enabled) this.ensureGraph();
+  }
+
   // --- equalizer ----------------------------------------------------------
 
   /**
diff --git a/src/lib/audio/musicAudioSettings.test.ts b/src/lib/audio/musicAudioSettings.test.ts
index e260900b..9dccd0e0 100644
--- a/src/lib/audio/musicAudioSettings.test.ts
+++ b/src/lib/audio/musicAudioSettings.test.ts
@@ -11,7 +11,7 @@ const { player } = vi.hoisted(() => {
 });
 
 vi.mock("../../store/useMusicPlayerStore", () => ({
-  useMusicPlayerStore: { getState: () => player },
+  useMusicPlayerStore: { getState: () => player, subscribe: vi.fn() },
 }));
 vi.mock("../api/db", () => ({ getSetting: vi.fn(), setSetting: vi.fn() }));
 
diff --git a/src/lib/audio/musicAudioSettings.ts b/src/lib/audio/musicAudioSettings.ts
index d05e30c2..e2c21663 100644
--- a/src/lib/audio/musicAudioSettings.ts
+++ b/src/lib/audio/musicAudioSettings.ts
@@ -2,6 +2,7 @@ import { SETTINGS } from "../settings/schema";
 import { getSettingValue, useAppSettingsStore } from "../../store/useAppSettingsStore";
 import { bindEqPersistence, useEqStore } from "../../store/useEqStore";
 import { useMusicPlayerStore } from "../../store/useMusicPlayerStore";
+import { crossfadeTarget } from "./crossfade";
 import { REFERENCE_SAMPLE_RATE } from "./eq/filterMath";
 import { graphChangesSound, graphSpec } from "./eq/graphPlan";
 import { changesSound } from "./eq/stateOps";
@@ -24,13 +25,32 @@ export function bindMusicAudioSettings(): void {
     if (player.normalizationEnabled !== enabled) player.setNormalizationEnabled(enabled);
   };
   const applySpeed = () => musicAudioEngine.setSpeed(Number(getSettingValue(SETTINGS.MUSIC_PLAYBACK_SPEED)));
+  const crossfadeSeconds = () =>
+    getSettingValue(SETTINGS.MUSIC_CROSSFADE_ENABLED) === "true"
+      ? Number(getSettingValue(SETTINGS.MUSIC_CROSSFADE_SECONDS))
+      : 0;
+  const applyCrossfade = () => musicAudioEngine.setCrossfadeEnabled(crossfadeSeconds() > 0);
 
   applyNormalization();
   applySpeed();
+  applyCrossfade();
   useAppSettingsStore.subscribe((state, previous) => {
     if (state.values === previous.values) return;
     applyNormalization();
     applySpeed();
+    applyCrossfade();
+  });
+
+  // The song clock ticks about four times a second; the fade starts on the tick that enters its
+  // window, and only into a next song already buffered, so the current one is never cut short.
+  useMusicPlayerStore.subscribe((state, previous) => {
+    if (state.progress === previous.progress) return;
+    const seconds = crossfadeSeconds();
+    const index = crossfadeTarget(state, seconds);
+    const next = state.queue[index];
+    if (!next || !musicAudioEngine.canPlayPreloaded(next.videoId ?? next.id)) return;
+    musicAudioEngine.armCrossfade(Math.min(seconds, state.duration - state.progress));
+    void state._loadIndex(index);
   });
 
   const applyEq = () => {
diff --git a/src/lib/i18n/strings.json b/src/lib/i18n/strings.json
index 0efcc6c5..76f45b28 100644
--- a/src/lib/i18n/strings.json
+++ b/src/lib/i18n/strings.json
@@ -1041,6 +1041,9 @@
   "music_audio_playback": "Playback",
   "music_playback_speed": "Speed",
   "music_speed_value": "%s×",
+  "music_crossfade": "Crossfade",
+  "music_crossfade_desc": "Fades the next song in as this one ends. Albums keep their gapless joins.",
+  "music_crossfade_seconds": "%s s",
   "eq_preset_flat": "Flat",
   "eq_preset_acoustic": "Acoustic",
   "eq_preset_bass_boost": "Bass Boost",
diff --git a/src/lib/settings/schema.ts b/src/lib/settings/schema.ts
index b4836497..23e4faed 100644
--- a/src/lib/settings/schema.ts
+++ b/src/lib/settings/schema.ts
@@ -110,6 +110,8 @@ export const SETTINGS = {
   MUSIC_LOUDNESS_NORMALIZATION: "music_loudness_normalization",
   EQ_STATE_JSON: "eq_state_json",
   MUSIC_PLAYBACK_SPEED: "music_playback_speed",
+  MUSIC_CROSSFADE_ENABLED: "music_crossfade_enabled",
+  MUSIC_CROSSFADE_SECONDS: "music_crossfade_seconds",
 
   BUFFER_PROFILE: "buffer_profile",
   MIN_BUFFER_MS: "min_buffer_ms",
@@ -322,6 +324,8 @@ export const SETTING_DEFINITIONS = [
   // Flow for Android's equalizer JSON, shared by music and video and synced as `equalizer`.
   json(SETTINGS.EQ_STATE_JSON, "player", "{}", "wired"),
   num(SETTINGS.MUSIC_PLAYBACK_SPEED, "player", 1, "wired", 0.5, 2),
+  bool(SETTINGS.MUSIC_CROSSFADE_ENABLED, "player", false, "wired"),
+  num(SETTINGS.MUSIC_CROSSFADE_SECONDS, "player", 5, "wired", 1, 12),
 
   str(SETTINGS.BUFFER_PROFILE, "network", "STABLE", "wired", ["AGGRESSIVE", "STABLE", "DATASAVER", "CUSTOM"]),
   num(SETTINGS.MIN_BUFFER_MS, "network", 30000, "wired", 5000, 120000),

From a2598aee1db36cd80b30915ae32ff55eec4ebccd Mon Sep 17 00:00:00 2001
From: AE <98699388+A-EDev@users.noreply.github.com>
Date: Sat, 24 Oct 2026 16:21:09 +0300
Subject: [PATCH 5/6] fix(audio): build the music audio graph on play instead
 of at startup

---
 src/lib/audio/musicAudioEngine.eq.test.ts | 12 +++++++++---
 src/lib/audio/musicAudioEngine.ts         | 19 ++++++++++++++++---
 2 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/src/lib/audio/musicAudioEngine.eq.test.ts b/src/lib/audio/musicAudioEngine.eq.test.ts
index 56883f91..075d27a6 100644
--- a/src/lib/audio/musicAudioEngine.eq.test.ts
+++ b/src/lib/audio/musicAudioEngine.eq.test.ts
@@ -110,10 +110,13 @@ describe("music EQ graph", () => {
     expect(musicAudioEngine.isEqAvailable()).toBe(true);
   });
 
-  it("builds one chain of 20 filters plus bass boost, and keeps it through a gapless swap", async () => {
+  it("builds one chain of 20 filters plus bass boost on play, and keeps it through a gapless swap", async () => {
     const pair = elements();
     musicAudioEngine.attach(pair);
     musicAudioEngine.setEq(rock, true);
+    // Nothing is playing yet: the context waits for the play that a click starts.
+    expect(contexts).toHaveLength(0);
+    await musicAudioEngine.play();
 
     const ctx = lastContext();
     expect(ctx.sources).toEqual(pair);
@@ -140,6 +143,7 @@ describe("music EQ graph", () => {
     const pair = elements();
     musicAudioEngine.attach(pair);
     musicAudioEngine.setEq(rock, true);
+    await musicAudioEngine.play();
     const ctx = lastContext();
     ctx.state = "suspended";
     ctx.resume.mockImplementation(() => new Promise(() => {}));
@@ -153,9 +157,11 @@ describe("music EQ graph", () => {
   it("resumes the context when the system suspends it mid-song", () => {
     const pair = elements();
     musicAudioEngine.attach(pair);
+    Object.defineProperty(pair[0], "paused", { value: false, configurable: true });
+    // Turned on while a song plays, the graph is built at once.
     musicAudioEngine.setEq(rock, true);
     const ctx = lastContext();
-    Object.defineProperty(pair[0], "paused", { value: false, configurable: true });
+    expect(ctx.sources).toContain(pair[0]);
 
     ctx.state = "suspended";
     ctx.dispatchEvent(new Event("statechange"));
@@ -166,12 +172,12 @@ describe("music EQ graph", () => {
     vi.useFakeTimers();
     const pair = elements();
     musicAudioEngine.attach(pair);
+    Object.defineProperty(pair[0], "paused", { value: false, configurable: true });
     musicAudioEngine.setCrossfadeEnabled(true);
     const ctx = lastContext();
     await musicAudioEngine.load("http://127.0.0.1/stream/a");
     musicAudioEngine.preload("b", "http://127.0.0.1/stream/b", null);
     Object.defineProperty(pair[1], "readyState", { value: HTMLMediaElement.HAVE_FUTURE_DATA, configurable: true });
-    Object.defineProperty(pair[0], "paused", { value: false, configurable: true });
 
     musicAudioEngine.armCrossfade(4);
     expect(musicAudioEngine.activatePreloaded("b")).toBe(true);
diff --git a/src/lib/audio/musicAudioEngine.ts b/src/lib/audio/musicAudioEngine.ts
index 16a2e7a8..3612dba7 100644
--- a/src/lib/audio/musicAudioEngine.ts
+++ b/src/lib/audio/musicAudioEngine.ts
@@ -95,7 +95,7 @@ class MusicAudioEngine {
     }
     this.graphReady = false;
     this.applySpeed();
-    if (this.eqEngaged || this.crossfadeEnabled) this.ensureGraph();
+    this.engageWhilePlaying();
     this.applyGain();
   }
 
@@ -306,6 +306,7 @@ class MusicAudioEngine {
   async play(): Promise<void> {
     const el = this.active.el;
     if (!el) return;
+    if (this.needsGraph()) this.ensureGraph();
     if (this.ctx) await resumeWithin(this.ctx);
     try {
       await el.play();
@@ -431,7 +432,7 @@ class MusicAudioEngine {
   /** Crossfades are timed on the audio clock, so turning them on brings WebAudio in. */
   setCrossfadeEnabled(enabled: boolean): void {
     this.crossfadeEnabled = enabled;
-    if (enabled) this.ensureGraph();
+    this.engageWhilePlaying();
   }
 
   // --- equalizer ----------------------------------------------------------
@@ -443,10 +444,22 @@ class MusicAudioEngine {
   setEq(spec: EqGraphSpec, engaged: boolean): void {
     this.eqSpec = spec;
     this.eqEngaged = engaged;
-    if (engaged) this.ensureGraph();
+    this.engageWhilePlaying();
     this.chain?.apply(spec);
   }
 
+  private needsGraph(): boolean {
+    return this.eqEngaged || this.crossfadeEnabled;
+  }
+
+  /**
+   * Builds the graph now when music is playing (a change the user just made), otherwise on the
+   * next play: a context made at startup, outside any click, may never be allowed to run.
+   */
+  private engageWhilePlaying(): void {
+    if (this.needsGraph() && this.active.el && !this.active.el.paused) this.ensureGraph();
+  }
+
   /** False once WebAudio failed here, so the equalizer cannot be heard. */
   isEqAvailable(): boolean {
     return !this.webAudioFailed && webAudioSupported();

From c1fe82144cefd97afad14e831f030ec7bcdf4e64 Mon Sep 17 00:00:00 2001
From: AE <98699388+A-EDev@users.noreply.github.com>
Date: Sat, 24 Oct 2026 16:02:28 +0300
Subject: [PATCH 6/6] docs(changelog): note music speed, the volume curve,
 loudness order and crossfade

---
 changelog/v0.1.0-beta3.txt | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/changelog/v0.1.0-beta3.txt b/changelog/v0.1.0-beta3.txt
index b24dd91d..b330ba39 100644
--- a/changelog/v0.1.0-beta3.txt
+++ b/changelog/v0.1.0-beta3.txt
@@ -42,6 +42,10 @@ AUDIO
 - Android's 13 presets with translated names, your own presets with Save, Save as, Rename, Duplicate and Delete with Undo, and a Custom entry that keeps the curve you tuned when you try a preset. AutoEQ and EqualizerAPO files import from a file or pasted text and export to a file or the clipboard.
 - The equalizer is saved with your settings, included in backups and synced with Flow for Android. Your old equalizer gains carry over, with the 32 Hz and 16 kHz bands now peaks like on Android, and the panel says when audio processing is not available on your system.
 - Music only goes through audio processing once the equalizer changes the sound, and playback resumes on its own after sleep or an output device change.
+- Music has its own playback speed from 0.5x to 2x, with presets and the pitch kept, saved with your settings.
+- The music volume slider follows how loud it sounds, so each step changes the level by a similar amount. Your saved volume plays at the same level after the update.
+- Music loudness is measured the way Android does it, from the perceptual loudness first, and loud songs are never turned down by more than 20 dB.
+- An optional crossfade, off by default, fades the next song in over 1 to 12 seconds. Consecutive tracks from the same album and repeat-one keep their gapless joins.
 
 MACOS
 - Flow uses the native macOS window controls and titlebar again. Closing the window hides it and keeps playback and downloads running until you quit, and clicking the Dock icon brings it back.