From 1c6c0c2b9873c7717fac8b5e48bc5bf2e250baf8 Mon Sep 17 00:00:00 2001 From: Joshua Higgins Date: Fri, 13 Nov 2026 21:50:00 -0500 Subject: [PATCH] feat(mobile): add device-local artwork colors toggle (#83) Co-authored-by: Joshua Higgins --- .../mobile/app/(app)/(tabs)/home/settings.tsx | 39 ++- apps/mobile/hooks/use-cover-palette.ts | 19 +- apps/mobile/hooks/use-legacy-cover-palette.ts | 178 ++++++++++++ apps/mobile/lib/artwork-color-preference.ts | 54 ++++ apps/mobile/lib/legacy-cover-palette.ts | 266 ++++++++++++++++++ 5 files changed, 554 insertions(+), 2 deletions(-) create mode 100644 apps/mobile/hooks/use-legacy-cover-palette.ts create mode 100644 apps/mobile/lib/artwork-color-preference.ts create mode 100644 apps/mobile/lib/legacy-cover-palette.ts diff --git a/apps/mobile/app/(app)/(tabs)/home/settings.tsx b/apps/mobile/app/(app)/(tabs)/home/settings.tsx index 5d86e35..30a0cfb 100644 --- a/apps/mobile/app/(app)/(tabs)/home/settings.tsx +++ b/apps/mobile/app/(app)/(tabs)/home/settings.tsx @@ -20,6 +20,11 @@ import { contentBottomInset } from "@/components/player" import { Button, Input, LoadingView } from "@/components/ui/primitives" import { useInvalidateAuthSession } from "@/contexts/convex-auth-session" import { useServerConfig } from "@/contexts/server-config" +import { + setArtworkColorsEnabled, + useArtworkColorsEnabled, + useArtworkColorPreferenceLoaded, +} from "@/lib/artwork-color-preference" import { initialsFromName } from "@/lib/format" import { useCachedQuery } from "@/hooks/use-cached-query" import { changeServer, signOut } from "@/lib/session" @@ -143,7 +148,12 @@ export default function SettingsScreen() { })} - {section === "profile" ? : null} + {section === "profile" ? ( + <> + + + + ) : null} {section === "quality" ? : null} {section === "library" && isAdmin ? : null} {section === "users" && isAdmin && allUsers ? ( @@ -160,6 +170,33 @@ export default function SettingsScreen() { ) } +function AppearanceSection() { + const enabled = useArtworkColorsEnabled() + const loaded = useArtworkColorPreferenceLoaded() + const [saving, setSaving] = useState(false) + + return ( + + { + setSaving(true) + try { + await setArtworkColorsEnabled(checked) + } catch { + showError("Could not save artwork colors preference.") + } finally { + setSaving(false) + } + }} + /> + + ) +} + function ProfileSection({ user }: { user: CurrentUser }) { const colors = useThemeColors() const updateName = useMutation(api.users.updateProfileName) diff --git a/apps/mobile/hooks/use-cover-palette.ts b/apps/mobile/hooks/use-cover-palette.ts index abd2e1c..7280c45 100644 --- a/apps/mobile/hooks/use-cover-palette.ts +++ b/apps/mobile/hooks/use-cover-palette.ts @@ -1,4 +1,9 @@ import { useEffect, useMemo, useState } from "react" +import { + artworkColorsEnabled, + useArtworkColorsEnabled, +} from "@/lib/artwork-color-preference" +import { prefetchLegacyCoverPalette, useLegacyCoverPalette } from "@/hooks/use-legacy-cover-palette" import { extractCoverSwatches } from "@/lib/artwork-colors" import { @@ -52,6 +57,10 @@ function extractSwatches(key: string) { /** Warm visible artwork colors before a detail page is pushed. */ export function prefetchCoverPalette(uri: string) { + if (!artworkColorsEnabled()) { + prefetchLegacyCoverPalette(uri) + return + } const key = withCoverImageSize(uri, 64) if (cachedSwatches(key) !== undefined) return void extractSwatches(key) @@ -65,7 +74,7 @@ export function prefetchCoverPalette(uri: string) { * `settled` turns true once the palette is final or after * `COVER_PALETTE_WAIT_MS`, whichever comes first. */ -export function useCoverPalette( +function useRegionCoverPalette( uri: string, hasCover: boolean | undefined ): { palette: CoverPalette; settled: boolean } { @@ -128,3 +137,11 @@ export function useCoverPalette( !key || hasCover === false || swatches !== undefined || waitedKey === key, } } + +/** Switch both extraction and palette derivation without mixing their caches. */ +export function useCoverPalette(uri: string, hasCover: boolean | undefined) { + const enabled = useArtworkColorsEnabled() + const region = useRegionCoverPalette(enabled ? uri : "", hasCover) + const legacy = useLegacyCoverPalette(enabled ? "" : uri, hasCover) + return enabled ? region : legacy +} diff --git a/apps/mobile/hooks/use-legacy-cover-palette.ts b/apps/mobile/hooks/use-legacy-cover-palette.ts new file mode 100644 index 0000000..49a7350 --- /dev/null +++ b/apps/mobile/hooks/use-legacy-cover-palette.ts @@ -0,0 +1,178 @@ +import { useEffect, useMemo, useState } from "react" +import { getColors, type ImageColorsResult } from "react-native-image-colors" + +import { + themeCoverPalette, + type CoverPalette, +} from "@/lib/cover-palette" +import { deriveCoverPalette, type LegacyCoverSwatches as CoverSwatches } from "@/lib/legacy-cover-palette" +import { readCache, writeCache } from "@/lib/persistent-cache" +import { useIsDark, useThemeColors } from "@/lib/theme" +import { withCoverImageSize } from "@/lib/urls" + +// How long a screen holds its skeleton for the first extraction of a cover, +// so rows render once with final colors instead of flashing from the theme. +const COVER_PALETTE_WAIT_MS = 400 + +// image-colors substitutes this for swatches it couldn't find. +const MISSING = "#010203" + +const swatchesByKey = new Map() +const pending = new Map>() + +function cacheKey(colorSourceUri: string) { + return `palette:${colorSourceUri}` +} + +function present(colors: (string | undefined)[]) { + return colors.filter( + (color): color is string => !!color && color.toLowerCase() !== MISSING + ) +} + +function toSwatches(result: ImageColorsResult): CoverSwatches | null { + if (result.platform === "ios") { + const text = present([result.primary, result.secondary, result.detail]) + return result.background.toLowerCase() === MISSING + ? null + : { background: result.background, text, accent: text } + } + + const background = present([result.dominant, result.muted])[0] + if (!background) return null + return { + background, + text: present([ + result.lightVibrant, + result.lightMuted, + result.darkVibrant, + result.darkMuted, + result.vibrant, + result.muted, + ]), + accent: present([ + result.vibrant, + result.lightVibrant, + result.darkVibrant, + result.muted, + ]), + } +} + +function sameSwatches( + a: CoverSwatches | null | undefined, + b: CoverSwatches | null | undefined +) { + return a === b || JSON.stringify(a) === JSON.stringify(b) +} + +function cachedSwatches(key: string): CoverSwatches | null | undefined { + if (swatchesByKey.has(key)) return swatchesByKey.get(key) + const cached = readCache(cacheKey(key)) + // Discard the background-only entries written by the tablet palette experiment. + return cached && (!Array.isArray(cached.text) || !Array.isArray(cached.accent)) + ? undefined + : cached +} + +function extractSwatches(key: string) { + const inFlight = pending.get(key) + if (inFlight) return inFlight + + const request = getColors(key, { + fallback: MISSING, + cache: true, + key, + quality: "low", + pixelSpacing: 4, + }) + .then(toSwatches) + .catch(() => null) + .then((swatches) => { + swatchesByKey.set(key, swatches) + if (swatches) writeCache(cacheKey(key), swatches) + pending.delete(key) + return swatches + }) + pending.set(key, request) + return request +} + +/** Warm visible artwork colors before a detail page is pushed. */ +export function prefetchLegacyCoverPalette(uri: string) { + const key = withCoverImageSize(uri, 64) + if (cachedSwatches(key) !== undefined) return + void extractSwatches(key) +} + +/** + * Colors for a screen tinted by `uri`'s cover art. Extraction runs once per + * cover and is cached on device. Pass `hasCover` as `undefined` while it isn't + * known yet so extraction can start early. + * + * `settled` turns true once the palette is final or after + * `COVER_PALETTE_WAIT_MS`, whichever comes first. + */ +export function useLegacyCoverPalette( + uri: string, + hasCover: boolean | undefined +): { palette: CoverPalette; settled: boolean } { + const theme = useThemeColors() + const isDark = useIsDark() + const key = uri ? withCoverImageSize(uri, 64) : "" + const [resolved, setResolved] = useState(() => ({ + key, + swatches: key ? cachedSwatches(key) : null, + })) + const [waitedKey, setWaitedKey] = useState(null) + + const swatches = + resolved.key === key ? resolved.swatches : key ? cachedSwatches(key) : null + + useEffect(() => { + if (!key || hasCover === false) return + let cancelled = false + const known = cachedSwatches(key) + const show = (next: CoverSwatches | null) => + setResolved((prev) => + prev.key === key && sameSwatches(prev.swatches, next) + ? prev + : { key, swatches: next } + ) + if (known !== undefined && swatchesByKey.has(key)) { + show(known) + return + } + + // Persisted swatches render immediately; refresh them in the background in + // case the cover changed. + const timer = + known === undefined + ? setTimeout( + () => !cancelled && setWaitedKey(key), + COVER_PALETTE_WAIT_MS + ) + : null + void extractSwatches(key).then((next) => { + if (!cancelled) show(next ?? known ?? null) + }) + return () => { + cancelled = true + if (timer) clearTimeout(timer) + } + }, [hasCover, key]) + + const palette = useMemo(() => { + const fromArt = + hasCover !== false && swatches + ? deriveCoverPalette(swatches, isDark) + : null + return fromArt ?? themeCoverPalette(theme, isDark) + }, [hasCover, isDark, swatches, theme]) + + return { + palette, + settled: + !key || hasCover === false || swatches !== undefined || waitedKey === key, + } +} diff --git a/apps/mobile/lib/artwork-color-preference.ts b/apps/mobile/lib/artwork-color-preference.ts new file mode 100644 index 0000000..2651ddd --- /dev/null +++ b/apps/mobile/lib/artwork-color-preference.ts @@ -0,0 +1,54 @@ +import AsyncStorage from "@react-native-async-storage/async-storage" +import { useSyncExternalStore } from "react" + +const STORAGE_KEY = "otunes:artwork-colors" +const listeners = new Set<() => void>() +let enabled = true +let loaded = false +let loading: Promise | undefined + +function notify() { + for (const listener of listeners) listener() +} + +function load() { + return (loading ??= AsyncStorage.getItem(STORAGE_KEY) + .then((value) => { + enabled = value !== "false" + }) + .catch(() => { + // Keep the default when local storage is unavailable. + }) + .finally(() => { + loaded = true + notify() + })) +} + +function subscribe(listener: () => void) { + listeners.add(listener) + void load() + return () => { + listeners.delete(listener) + } +} + +/** Device preference, kept outside account data and the disposable query cache. */ +export function useArtworkColorsEnabled() { + return useSyncExternalStore(subscribe, () => loaded && enabled, () => false) +} + +export function useArtworkColorPreferenceLoaded() { + return useSyncExternalStore(subscribe, () => loaded, () => false) +} + +export function artworkColorsEnabled() { + return loaded && enabled +} + +export async function setArtworkColorsEnabled(value: boolean) { + await load() + await AsyncStorage.setItem(STORAGE_KEY, String(value)) + enabled = value + notify() +} diff --git a/apps/mobile/lib/legacy-cover-palette.ts b/apps/mobile/lib/legacy-cover-palette.ts new file mode 100644 index 0000000..7bcbd5e --- /dev/null +++ b/apps/mobile/lib/legacy-cover-palette.ts @@ -0,0 +1,266 @@ +// Palette algorithm used before the dominant-region artwork extraction. +import type { CoverPalette } from "@/lib/cover-palette" + +/** + * Raw colors sampled from the art. `background` is the color the art bleeds + * into; `text` is ordered by preference and `accent` holds candidates for the + * Play button. + */ +export type LegacyCoverSwatches = { + background: string + text: string[] + accent: string[] +} + +// Best effort: `legibleBackground` only guarantees that white or black reaches +// 7:1, so on some backgrounds primary text settles for pure white or black. +const PRIMARY_MIN_CONTRAST = 10 +const SECONDARY_MIN_CONTRAST = 4.5 +const SECONDARY_TO_PRIMARY_CONTRAST = 0.62 +const ACCENT_MIN_CONTRAST = 3 +const ACCENT_MIN_CHROMA = 0.05 +const ACCENT_MAX_LIGHTNESS_SHIFT = 0.25 +// Backgrounds between these luminances can't reach 7:1 with white or black. +const DARK_BACKGROUND_MAX_LUMINANCE = 0.095 +const LIGHT_BACKGROUND_MIN_LUMINANCE = 0.31 + +type Rgb = [number, number, number] +type Oklch = { l: number; c: number; h: number } + +export function deriveCoverPalette( + swatches: LegacyCoverSwatches, + schemeIsDark: boolean +): CoverPalette | null { + const source = parseHex(swatches.background) + if (!source) return null + + const background = legibleBackground(source, schemeIsDark) + const lightText = prefersLightText(background) + const parsedText = swatches.text + .map(parseHex) + .filter((color): color is Rgb => color !== null) + const backgroundLuminance = luminance(background) + const sameSideText = parsedText.filter((color) => + lightText + ? luminance(color) > backgroundLuminance + : luminance(color) < backgroundLuminance + ) + const textCandidates = sameSideText.length > 0 ? sameSideText : parsedText + const fallbackText: Rgb = lightText ? [255, 255, 255] : [0, 0, 0] + + const foreground = withMinContrast( + textCandidates[0] ?? fallbackText, + background, + PRIMARY_MIN_CONTRAST + ) + const primaryContrast = contrastRatio(foreground, background) + const secondaryTarget = Math.max( + SECONDARY_MIN_CONTRAST, + primaryContrast * SECONDARY_TO_PRIMARY_CONTRAST + ) + const secondaryForeground = softenTo( + withMinContrast( + textCandidates[1] ?? foreground, + background, + SECONDARY_MIN_CONTRAST + ), + background, + secondaryTarget + ) + + const accent = pickAccent(swatches.accent, background) ?? foreground + const accentForeground: Rgb = prefersLightText(accent) + ? [255, 255, 255] + : [0, 0, 0] + + return { + background: toHex(background), + foreground: toHex(foreground), + secondaryForeground: toHex(secondaryForeground), + accent: toHex(accent), + accentForeground: toHex(accentForeground), + accentText: toHex(withMinContrast(accent, background, SECONDARY_MIN_CONTRAST)), + surface: toHex(mix(foreground, background, lightText ? 0.16 : 0.1)), + divider: toHex(mix(foreground, background, lightText ? 0.2 : 0.14)), + isDark: lightText, + } +} + +function legibleBackground(color: Rgb, schemeIsDark: boolean): Rgb { + const lch = toOklch(color) + // Keep the art's hue but avoid a glaring page in dark mode or a murky one in + // light mode. + const clamped = schemeIsDark + ? withLightness(color, Math.min(lch.l, 0.86)) + : withLightness(color, Math.max(lch.l, 0.2)) + const y = luminance(clamped) + if (y <= DARK_BACKGROUND_MAX_LUMINANCE || y >= LIGHT_BACKGROUND_MIN_LUMINANCE) { + return clamped + } + + const pivot = schemeIsDark ? 0.28 : 0.14 + return y < pivot + ? withLuminance(clamped, DARK_BACKGROUND_MAX_LUMINANCE) + : withLuminance(clamped, LIGHT_BACKGROUND_MIN_LUMINANCE) +} + +function pickAccent(candidates: string[], background: Rgb): Rgb | null { + let best: Rgb | null = null + let bestChroma = ACCENT_MIN_CHROMA + for (const hex of candidates) { + const color = parseHex(hex) + if (!color) continue + const adjusted = withMinContrast(color, background, ACCENT_MIN_CONTRAST) + const before = toOklch(color) + const after = toOklch(adjusted) + // A color pushed far from its own lightness (yellow turned olive) no + // longer reads as coming from the art. + if (Math.abs(after.l - before.l) > ACCENT_MAX_LIGHTNESS_SHIFT) continue + if (after.c > bestChroma) { + best = adjusted + bestChroma = after.c + } + } + return best +} + +function prefersLightText(background: Rgb) { + return contrastRatio([255, 255, 255], background) >= contrastRatio([0, 0, 0], background) +} + +/** Moves `color`'s lightness away from `background` until it reaches `min`. */ +function withMinContrast(color: Rgb, background: Rgb, min: number): Rgb { + if (contrastRatio(color, background) >= min) return color + + const lighten = prefersLightText(background) + const start = toOklch(color).l + const extreme = lighten ? 1 : 0 + if (contrastRatio(withLightness(color, extreme), background) < min) { + return lighten ? [255, 255, 255] : [0, 0, 0] + } + + let near = start + let far = extreme + for (let i = 0; i < 16; i++) { + const mid = (near + far) / 2 + if (contrastRatio(withLightness(color, mid), background) >= min) { + far = mid + } else { + near = mid + } + } + return withLightness(color, far) +} + +/** Blends `color` toward `background` until its contrast drops to `max`. */ +function softenTo(color: Rgb, background: Rgb, max: number): Rgb { + if (contrastRatio(color, background) <= max) return color + + let keep = 0 + let blend = 1 + for (let i = 0; i < 16; i++) { + const mid = (keep + blend) / 2 + if (contrastRatio(mix(color, background, mid), background) >= max) { + blend = mid + } else { + keep = mid + } + } + return mix(color, background, blend) +} + +function withLuminance(color: Rgb, target: number): Rgb { + let low = 0 + let high = 1 + for (let i = 0; i < 16; i++) { + const mid = (low + high) / 2 + if (luminance(withLightness(color, mid)) < target) { + low = mid + } else { + high = mid + } + } + return withLightness(color, target <= DARK_BACKGROUND_MAX_LUMINANCE ? low : high) +} + +/** `amount` of `color` over `base`. */ +function mix(color: Rgb, base: Rgb, amount: number): Rgb { + return [0, 1, 2].map((i) => + Math.round(base[i] + (color[i] - base[i]) * amount) + ) as Rgb +} + +function contrastRatio(a: Rgb, b: Rgb) { + const la = luminance(a) + const lb = luminance(b) + return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05) +} + +function luminance([r, g, b]: Rgb) { + return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b) +} + +function toLinear(channel: number) { + const c = channel / 255 + return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4 +} + +function fromLinear(value: number) { + const c = value <= 0.0031308 ? value * 12.92 : 1.055 * value ** (1 / 2.4) - 0.055 + return c * 255 +} + +function toOklch(color: Rgb): Oklch { + const [r, g, b] = color.map(toLinear) + const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b) + const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b) + const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b) + const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s + const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s + const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s + return { l: L, c: Math.hypot(A, B), h: Math.atan2(B, A) } +} + +function oklchToLinear({ l: L, c, h }: Oklch): Rgb { + const A = c * Math.cos(h) + const B = c * Math.sin(h) + const l = (L + 0.3963377774 * A + 0.2158037573 * B) ** 3 + const m = (L - 0.1055613458 * A - 0.0638541728 * B) ** 3 + const s = (L - 0.0894841775 * A - 1.291485548 * B) ** 3 + return [ + 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s, + -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s, + -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s, + ] +} + +/** Sets OKLCH lightness, reducing chroma as needed to stay within sRGB. */ +function withLightness(color: Rgb, lightness: number): Rgb { + const lch = toOklch(color) + const l = Math.min(1, Math.max(0, lightness)) + let c = lch.c + let linear = oklchToLinear({ l, c, h: lch.h }) + for (let i = 0; i < 12 && !inGamut(linear); i++) { + c *= 0.8 + linear = oklchToLinear({ l, c, h: lch.h }) + } + return linear.map((value) => + Math.round(Math.min(255, Math.max(0, fromLinear(value)))) + ) as Rgb +} + +function inGamut(linear: Rgb) { + return linear.every((value) => value >= -0.0005 && value <= 1.0005) +} + +function parseHex(hex: string | undefined): Rgb | null { + if (!hex) return null + const match = /^#?([0-9a-f]{6})/i.exec(hex.trim()) + if (!match) return null + const value = parseInt(match[1], 16) + return [(value >> 16) & 255, (value >> 8) & 255, value & 255] +} + +function toHex(color: Rgb) { + return `#${color.map((c) => c.toString(16).padStart(2, "0")).join("")}` +}