From 9aaa72a3dcf48824d748751412532395d2392bf5 Mon Sep 17 00:00:00 2001 From: Joshua Higgins Date: Mon, 9 Nov 2026 12:21:51 -0500 Subject: [PATCH 1/3] fix(mobile): extract artwork colors from dominant regions --- apps/mobile/hooks/use-cover-palette.ts | 59 +--- apps/mobile/lib/artwork-colors.ios.ts | 11 + apps/mobile/lib/artwork-colors.ts | 29 ++ apps/mobile/lib/color-histogram.test.cjs | 55 +++ apps/mobile/lib/color-histogram.ts | 162 +++++++++ apps/mobile/lib/cover-palette.ts | 327 +++++------------- .../artwork-colors/expo-module.config.json | 4 + .../artwork-colors/ios/ArtworkColors.podspec | 17 + .../ios/ArtworkColorsModule.swift | 65 ++++ 9 files changed, 439 insertions(+), 290 deletions(-) create mode 100644 apps/mobile/lib/artwork-colors.ios.ts create mode 100644 apps/mobile/lib/artwork-colors.ts create mode 100644 apps/mobile/lib/color-histogram.test.cjs create mode 100644 apps/mobile/lib/color-histogram.ts create mode 100644 apps/mobile/modules/artwork-colors/expo-module.config.json create mode 100644 apps/mobile/modules/artwork-colors/ios/ArtworkColors.podspec create mode 100644 apps/mobile/modules/artwork-colors/ios/ArtworkColorsModule.swift diff --git a/apps/mobile/hooks/use-cover-palette.ts b/apps/mobile/hooks/use-cover-palette.ts index e5c5d1f..abd2e1c 100644 --- a/apps/mobile/hooks/use-cover-palette.ts +++ b/apps/mobile/hooks/use-cover-palette.ts @@ -1,5 +1,5 @@ import { useEffect, useMemo, useState } from "react" -import { getColors, type ImageColorsResult } from "react-native-image-colors" +import { extractCoverSwatches } from "@/lib/artwork-colors" import { deriveCoverPalette, @@ -15,49 +15,11 @@ import { withCoverImageSize } from "@/lib/urls" // so rows render once with final colors instead of flashing from the theme. export 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, - ]), - } + return `palette:v2:${colorSourceUri}` } function sameSwatches( @@ -69,25 +31,14 @@ function sameSwatches( 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 + return readCache(cacheKey(key)) } 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) + const request = extractCoverSwatches(key) .catch(() => null) .then((swatches) => { swatchesByKey.set(key, swatches) @@ -166,7 +117,7 @@ export function useCoverPalette( const palette = useMemo(() => { const fromArt = hasCover !== false && swatches - ? deriveCoverPalette(swatches, isDark) + ? deriveCoverPalette(swatches) : null return fromArt ?? themeCoverPalette(theme, isDark) }, [hasCover, isDark, swatches, theme]) diff --git a/apps/mobile/lib/artwork-colors.ios.ts b/apps/mobile/lib/artwork-colors.ios.ts new file mode 100644 index 0000000..1842473 --- /dev/null +++ b/apps/mobile/lib/artwork-colors.ios.ts @@ -0,0 +1,11 @@ +import { requireNativeModule } from "expo" + +import { swatchesFromHistogram, type ColorBin } from "./color-histogram" + +const native = requireNativeModule<{ + histogram(uri: string): Promise +}>("ArtworkColors") + +export async function extractCoverSwatches(uri: string) { + return swatchesFromHistogram(await native.histogram(uri)) +} diff --git a/apps/mobile/lib/artwork-colors.ts b/apps/mobile/lib/artwork-colors.ts new file mode 100644 index 0000000..0ee2b3e --- /dev/null +++ b/apps/mobile/lib/artwork-colors.ts @@ -0,0 +1,29 @@ +import { getColors } from "react-native-image-colors" +import type { CoverSwatches } from "./cover-palette" + +const MISSING = "#010203" + +/** Android and web retain their platform quantizers; iOS uses the sRGB histogram. */ +export async function extractCoverSwatches( + uri: string +): Promise { + const result = await getColors(uri, { + fallback: MISSING, + cache: true, + key: uri, + quality: "low", + pixelSpacing: 4, + }) + if (result.platform === "ios") return null + const background = [result.dominant, result.muted].find( + (color) => color && color.toLowerCase() !== MISSING + ) + if (!background) return null + return { + background, + ...(result.platform === "android" && + result.average.toLowerCase() !== MISSING + ? { average: result.average } + : {}), + } +} diff --git a/apps/mobile/lib/color-histogram.test.cjs b/apps/mobile/lib/color-histogram.test.cjs new file mode 100644 index 0000000..99a6206 --- /dev/null +++ b/apps/mobile/lib/color-histogram.test.cjs @@ -0,0 +1,55 @@ +const { test } = require("node:test") +const assert = require("node:assert/strict") +const fs = require("node:fs") +const ts = require("typescript") + +const compiled = ts.transpileModule( + fs.readFileSync(`${__dirname}/color-histogram.ts`, "utf8"), + { + compilerOptions: { + module: ts.ModuleKind.CommonJS, + target: ts.ScriptTarget.ES2022, + }, + } +).outputText +const loaded = { exports: {} } +new Function("exports", compiled)(loaded.exports) +const { swatchesFromHistogram } = loaded.exports + +test("a noisy background outranks a smaller flat logo, independent of bin order", () => { + const background = Array.from({ length: 30 }, (_, i) => [ + 30 + i, + 110 + i, + 30 + i, + 100, + ]) + const bins = [...background, [240, 10, 10, 500]] + const palette = swatchesFromHistogram(bins) + assert.equal(palette.background, "#2d7d2d") + assert.ok(palette.dominantFraction > 0.85) + assert.deepEqual(palette, swatchesFromHistogram([...bins].reverse())) +}) + +test("dominant black stays black beside white and a saturated accent", () => { + const palette = swatchesFromHistogram([ + [0, 0, 0, 60], + [255, 255, 255, 30], + [140, 200, 50, 10], + ]) + assert.equal(palette.background, "#000000") + assert.equal(palette.darkFraction, 0.6) + assert.equal(palette.dominantFraction, 0.6) +}) + +test("empty and invalid histograms cannot produce NaN colors", () => { + assert.equal(swatchesFromHistogram([]), null) + assert.equal( + swatchesFromHistogram([ + [NaN, 0, 0, 1], + [256, 0, 0, 1], + [0, 0, 0, 0], + ]), + null + ) + assert.equal(swatchesFromHistogram([[80, 100, 120, 4]]).background, "#506478") +}) diff --git a/apps/mobile/lib/color-histogram.ts b/apps/mobile/lib/color-histogram.ts new file mode 100644 index 0000000..5136f2a --- /dev/null +++ b/apps/mobile/lib/color-histogram.ts @@ -0,0 +1,162 @@ +import type { CoverSwatches } from "./cover-palette" + +type Rgb = [number, number, number] +export type ColorBin = [red: number, green: number, blue: number, count: number] +type Cluster = { rgb: Rgb; lab: Rgb; count: number } + +function lab([r, g, b]: Rgb): Rgb { + const linear = (v: number) => + v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4 + const red = linear(r / 255) + const green = linear(g / 255) + const blue = linear(b / 255) + const l = Math.cbrt( + 0.4122214708 * red + 0.5363325363 * green + 0.0514459929 * blue + ) + const m = Math.cbrt( + 0.2119034982 * red + 0.6806995451 * green + 0.1073969566 * blue + ) + const s = Math.cbrt( + 0.0883024619 * red + 0.2817188376 * green + 0.6299787005 * blue + ) + return [ + 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s, + 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s, + 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s, + ] +} + +function distance(a: Rgb, b: Rgb) { + return (a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2 + (a[2] - b[2]) ** 2 +} + +function hex(rgb: Rgb) { + return `#${rgb.map((v) => Math.round(v).toString(16).padStart(2, "0")).join("")}` +} + +/** Group nearby colors by perceived distance, retaining black and white regions. */ +export function swatchesFromHistogram(bins: ColorBin[]): CoverSwatches | null { + const samples: Cluster[] = bins + .filter( + (bin) => + bin.length === 4 && + bin.every(Number.isFinite) && + bin[3] > 0 && + bin.slice(0, 3).every((v) => v >= 0 && v <= 255) + ) + .map(([r, g, b, count]) => ({ + rgb: [r, g, b], + lab: lab([r, g, b]), + count, + })) + .sort( + (a, b) => + b.count - a.count || + a.rgb[0] - b.rgb[0] || + a.rgb[1] - b.rgb[1] || + a.rgb[2] - b.rgb[2] + ) + if (!samples.length) return null + + const centers = [samples[0].lab] + // Deterministic weighted seeding avoids random palette changes between launches. + while (centers.length < Math.min(8, samples.length)) { + let candidate = samples[0] + let best = 0 + for (const sample of samples) { + const score = + Math.min(...centers.map((center) => distance(sample.lab, center))) * + sample.count + if (score > best) { + candidate = sample + best = score + } + } + if (best === 0) break + centers.push(candidate.lab) + } + + let clusters: Cluster[] = [] + for (let iteration = 0; iteration < 12; iteration++) { + clusters = centers.map(() => ({ rgb: [0, 0, 0], lab: [0, 0, 0], count: 0 })) + for (const sample of samples) { + let nearest = 0 + for (let index = 1; index < centers.length; index++) { + if ( + distance(sample.lab, centers[index]) < + distance(sample.lab, centers[nearest]) + ) + nearest = index + } + const cluster = clusters[nearest] + cluster.count += sample.count + for (let channel = 0; channel < 3; channel++) { + cluster.rgb[channel] += sample.rgb[channel] * sample.count + cluster.lab[channel] += sample.lab[channel] * sample.count + } + } + let movement = 0 + clusters.forEach((cluster, index) => { + if (!cluster.count) return + for (let channel = 0; channel < 3; channel++) { + cluster.rgb[channel] /= cluster.count + cluster.lab[channel] /= cluster.count + } + movement += distance(centers[index], cluster.lab) + centers[index] = cluster.lab + }) + if (movement < 0.000001) break + } + + // K-means can divide a textured region across several centers. Combine those + // centers before ranking coverage so a small flat logo cannot outrank it. + clusters = clusters.filter((cluster) => cluster.count > 0) + while (clusters.length > 1) { + let pair: [number, number] | undefined + let closest = 0.06 ** 2 + for (let a = 0; a < clusters.length; a++) { + for (let b = a + 1; b < clusters.length; b++) { + const separation = distance(clusters[a].lab, clusters[b].lab) + if (separation < closest) { + closest = separation + pair = [a, b] + } + } + } + if (!pair) break + const [a, b] = pair + const first = clusters[a] + const second = clusters[b] + const count = first.count + second.count + for (let channel = 0; channel < 3; channel++) { + first.rgb[channel] = + (first.rgb[channel] * first.count + + second.rgb[channel] * second.count) / + count + first.lab[channel] = + (first.lab[channel] * first.count + + second.lab[channel] * second.count) / + count + } + first.count = count + clusters.splice(b, 1) + } + + const total = samples.reduce((sum, sample) => sum + sample.count, 0) + const average: Rgb = [0, 0, 0] + for (const sample of samples) { + for (let channel = 0; channel < 3; channel++) + average[channel] += (sample.rgb[channel] * sample.count) / total + } + clusters.sort((a, b) => b.count - a.count) + return { + background: hex(clusters[0].rgb), + average: hex(average), + dominantFraction: clusters[0].count / total, + darkFraction: + samples.reduce( + (sum, sample) => sum + (sample.lab[0] < 0.3 ? sample.count : 0), + 0 + ) / total, + } +} diff --git a/apps/mobile/lib/cover-palette.ts b/apps/mobile/lib/cover-palette.ts index fa441fb..3e0840e 100644 --- a/apps/mobile/lib/cover-palette.ts +++ b/apps/mobile/lib/cover-palette.ts @@ -17,33 +17,21 @@ export type CoverPalette = { isDark: boolean } -/** - * 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. - */ +/** Artwork measurements, cached before deriving the screen palette. */ export type CoverSwatches = { background: string - text: string[] - accent: string[] + average?: string + dominantFraction?: number + darkFraction?: number } -// 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 } +type Hsl = { h: number; s: number; l: number } -export function themeCoverPalette(theme: ThemeColors, isDark: boolean): CoverPalette { +export function themeCoverPalette( + theme: ThemeColors, + isDark: boolean +): CoverPalette { return { background: theme.background, foreground: theme.foreground, @@ -57,240 +45,107 @@ export function themeCoverPalette(theme: ThemeColors, isDark: boolean): CoverPal } } +/** + * Artwork pages use a dark, hue-matched canvas with neutral primary controls. + * Saturated covers stay deep; muted covers retain the lighter, subtly tinted + * canvas in the references: yellow #3E2B00, muted green #2A3028, and + * deep magenta #370C18. + */ export function deriveCoverPalette( - swatches: CoverSwatches, - schemeIsDark: boolean + swatches: CoverSwatches ): 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] + const sampled = toHsl(source) + // Yellow loses its green cast when shaded to the warm amber in the reference. + const muted = Math.max(0, 1 - sampled.s / 0.35) + const warmHue = + sampled.h >= 45 && sampled.h <= 75 ? 42 + (sampled.h - 53) * 0.5 : sampled.h + // Deep magenta shadows need a burgundy canvas rather than near-black. + // Blend by hue and shadow depth so bright covers keep their own treatment. + const berry = + Math.max(0, 1 - Math.abs(sampled.h - 320) / 40) * + Math.min(1, Math.max(0, (0.12 - sampled.l) / 0.08)) + const h = warmHue - 16 * muted + 23.25 * berry + const s = Math.min(1, sampled.s * (1.2 + 2.7 * muted)) * (1 - 0.36 * berry) + const shadedLightness = Math.min(sampled.l, (31 + 14 * muted) / 255) + const l = shadedLightness * (1 - berry) + (33.5 / 255) * berry + const background = fromHsl({ h, s, l }) + const secondary = fromHsl({ + h: h - 2.5 + 8 * muted + 3 * berry, + s: s * (0.34 + 0.06 * muted + 0.024 * berry), + l: (174.5 - 2.5 * muted - 13.5 * berry) / 255, + }) 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, + foreground: "#FFFFFF", + secondaryForeground: toHex(secondary), + accent: "#FFFFFF", + accentForeground: toHex(background), + accentText: "#FFFFFF", + surface: toHex( + fromHsl({ + h: h - 0.9 + 3 * berry, + s: s * (0.6 + 0.1 * muted), + l: l + (19 - muted) / 255, + }) + ), + divider: toHex( + fromHsl({ + h, + s: s * (0.48 + 0.1 * muted + 0.025 * berry), + l: l + 33 / 255, + }) + ), + isDark: true, } } -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 +function toHsl([red, green, blue]: Rgb): Hsl { + const [r, g, b] = [red, green, blue].map((channel) => channel / 255) + const max = Math.max(r, g, b) + const min = Math.min(r, g, b) + const delta = max - min + const l = (max + min) / 2 + if (delta === 0) return { h: 0, s: 0, l } + const sector = + max === r + ? (g - b) / delta + : max === g + ? (b - r) / delta + 2 + : (r - g) / delta + 4 + return { + h: (sector * 60 + 360) % 360, + s: delta / (1 - Math.abs(2 * l - 1)), + l, } - - 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, +function fromHsl({ h, s, l }: Hsl): Rgb { + const hue = (((h % 360) + 360) % 360) / 60 + const chroma = (1 - Math.abs(2 * l - 1)) * s + const x = chroma * (1 - Math.abs((hue % 2) - 1)) + const sectors = [ + [chroma, x, 0], + [x, chroma, 0], + [0, chroma, x], + [0, x, chroma], + [x, 0, chroma], + [chroma, 0, x], ] -} - -/** 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)))) + const offset = l - chroma / 2 + return sectors[Math.floor(hue)].map((channel) => + Math.round((channel + offset) * 255) ) 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) +function parseHex(hex: string): Rgb | null { + if (!/^#[0-9a-f]{6}$/i.test(hex)) return null + const value = parseInt(hex.slice(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("")}` + return `#${color.map((channel) => channel.toString(16).padStart(2, "0")).join("")}` } diff --git a/apps/mobile/modules/artwork-colors/expo-module.config.json b/apps/mobile/modules/artwork-colors/expo-module.config.json new file mode 100644 index 0000000..65eab09 --- /dev/null +++ b/apps/mobile/modules/artwork-colors/expo-module.config.json @@ -0,0 +1,4 @@ +{ + "platforms": ["apple"], + "apple": { "modules": ["ArtworkColorsModule"] } +} diff --git a/apps/mobile/modules/artwork-colors/ios/ArtworkColors.podspec b/apps/mobile/modules/artwork-colors/ios/ArtworkColors.podspec new file mode 100644 index 0000000..eaa2cb9 --- /dev/null +++ b/apps/mobile/modules/artwork-colors/ios/ArtworkColors.podspec @@ -0,0 +1,17 @@ +Pod::Spec.new do |s| + s.name = 'ArtworkColors' + s.version = '1.0.0' + s.summary = 'Artwork color sampling for oTunes' + s.description = s.summary + s.license = { :type => 'MIT' } + s.author = 'oTunes' + s.homepage = 'https://otunes.abunchofknowitalls.com' + s.platforms = { :ios => '16.4' } + s.swift_version = '5.9' + s.source = { :git => '' } + s.static_framework = true + s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES' } + s.dependency 'ExpoModulesCore' + s.frameworks = 'ImageIO', 'CoreGraphics' + s.source_files = '**/*.swift' +end diff --git a/apps/mobile/modules/artwork-colors/ios/ArtworkColorsModule.swift b/apps/mobile/modules/artwork-colors/ios/ArtworkColorsModule.swift new file mode 100644 index 0000000..e0e5898 --- /dev/null +++ b/apps/mobile/modules/artwork-colors/ios/ArtworkColorsModule.swift @@ -0,0 +1,65 @@ +import ExpoModulesCore +import CoreGraphics +import ImageIO + +public final class ArtworkColorsModule: Module { + public func definition() -> ModuleDefinition { + Name("ArtworkColors") + + AsyncFunction("histogram") { (uri: URL) async throws -> [[Int]] in + let (data, response) = try await URLSession.shared.data(from: uri) + if let response = response as? HTTPURLResponse, !(200..<300).contains(response.statusCode) { + throw ArtworkColorError.invalidImage + } + return try Self.histogram(data: data) + } + } + + /// Sample in sRGB so Display P3 artwork and ordinary JPEGs share one color space. + static func histogram(data: Data) throws -> [[Int]] { + guard let source = CGImageSourceCreateWithData(data as CFData, nil), + let image = CGImageSourceCreateThumbnailAtIndex(source, 0, [ + kCGImageSourceCreateThumbnailFromImageAlways: true, + kCGImageSourceCreateThumbnailWithTransform: true, + kCGImageSourceThumbnailMaxPixelSize: 64, + ] as CFDictionary), + let space = CGColorSpace(name: CGColorSpace.sRGB) + else { throw ArtworkColorError.invalidImage } + + let width = image.width + let height = image.height + var pixels = [UInt8](repeating: 0, count: width * height * 4) + var bins = [[Int]](repeating: [0, 0, 0, 0], count: 512) + try pixels.withUnsafeMutableBytes { buffer in + guard let context = CGContext( + data: buffer.baseAddress, width: width, height: height, + bitsPerComponent: 8, bytesPerRow: width * 4, space: space, + bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue | CGBitmapInfo.byteOrder32Big.rawValue + ) else { throw ArtworkColorError.invalidImage } + context.interpolationQuality = .high + context.draw(image, in: CGRect(x: 0, y: 0, width: width, height: height)) + } + + for offset in stride(from: 0, to: pixels.count, by: 4) { + let alpha = Int(pixels[offset + 3]) + guard alpha >= 128 else { continue } + // Ignore transparent pixels and undo premultiplication for the rest. + let r = min(255, Int(pixels[offset]) * 255 / alpha) + let g = min(255, Int(pixels[offset + 1]) * 255 / alpha) + let b = min(255, Int(pixels[offset + 2]) * 255 / alpha) + let key = (r >> 5) * 64 + (g >> 5) * 8 + (b >> 5) + bins[key][0] += r + bins[key][1] += g + bins[key][2] += b + bins[key][3] += 1 + } + // Keep each bin's actual mean rather than its quantized center. + return bins.filter { $0[3] > 0 }.map { bin in + [bin[0] / bin[3], bin[1] / bin[3], bin[2] / bin[3], bin[3]] + } + } +} + +private enum ArtworkColorError: Error { + case invalidImage +} -- 2.54.1 From a1a1987d7ce11fdb8b91f8f0db390a6bc7e46c78 Mon Sep 17 00:00:00 2001 From: Joshua Higgins Date: Mon, 9 Nov 2026 13:07:53 -0500 Subject: [PATCH 2/3] fix(mobile): derive dark palettes from artwork measurements --- apps/mobile/lib/color-space.ts | 32 ++++ apps/mobile/lib/cover-palette.compare.cjs | 50 +++++++ apps/mobile/lib/cover-palette.references.json | 92 ++++++++++++ apps/mobile/lib/cover-palette.test.cjs | 54 +++++++ apps/mobile/lib/cover-palette.ts | 138 ++++++++---------- 5 files changed, 288 insertions(+), 78 deletions(-) create mode 100644 apps/mobile/lib/color-space.ts create mode 100644 apps/mobile/lib/cover-palette.compare.cjs create mode 100644 apps/mobile/lib/cover-palette.references.json create mode 100644 apps/mobile/lib/cover-palette.test.cjs diff --git a/apps/mobile/lib/color-space.ts b/apps/mobile/lib/color-space.ts new file mode 100644 index 0000000..dd1d96a --- /dev/null +++ b/apps/mobile/lib/color-space.ts @@ -0,0 +1,32 @@ +type Color = [number, number, number] + +/** Convert sRGB byte values to Oklab without quantizing intermediate colors. */ +export function toOklab(rgb: Color): Color { + const [r, g, b] = rgb.map((byte) => { + const v = byte / 255 + return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4 + }) + 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) + return [ + 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s, + 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s, + 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s, + ] +} + +/** Map an Oklab color back into the display's sRGB gamut. */ +export function fromOklab([L, a, b]: Color): Color { + 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, + ].map((v) => { + const encoded = v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055 + return Math.round(Math.max(0, Math.min(1, encoded)) * 255) + }) as Color +} diff --git a/apps/mobile/lib/cover-palette.compare.cjs b/apps/mobile/lib/cover-palette.compare.cjs new file mode 100644 index 0000000..9b0b230 --- /dev/null +++ b/apps/mobile/lib/cover-palette.compare.cjs @@ -0,0 +1,50 @@ +// Measurement targets belong here and in the fixture, never in palette derivation. +const fs = require("node:fs") +const ts = require("typescript") +const references = require("./cover-palette.references.json") +function load(name) { + const exports = {} + const code = ts.transpileModule( + fs.readFileSync(`${__dirname}/${name}.ts`, "utf8"), + { + compilerOptions: { + module: ts.ModuleKind.CommonJS, + target: ts.ScriptTarget.ES2022, + }, + } + ).outputText + new Function("exports", "require", code)(exports, (name) => + load(name.replace("./", "")) + ) + return exports +} +const { deriveCoverPalette } = load("cover-palette") +const rgb = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16)) +const measurements = references.map( + ({ label, swatches, expectedBackground }) => { + const actual = deriveCoverPalette(swatches).background + const errors = rgb(actual).map((v, i) => + Math.abs(v - rgb(expectedBackground)[i]) + ) + return { + label, + expectedBackground, + actual, + maxChannelError: Math.max(...errors), + squaredError: errors.reduce((s, v) => s + v * v, 0), + } + } +) +console.table(measurements.map(({ squaredError, ...row }) => row)) +console.log( + "RGB RMSE:", + Math.sqrt( + measurements.reduce((s, r) => s + r.squaredError, 0) / + (measurements.length * 3) + ) +) +if ( + process.argv.includes("--exact") && + measurements.some((row) => row.maxChannelError !== 0) +) + process.exitCode = 1 diff --git a/apps/mobile/lib/cover-palette.references.json b/apps/mobile/lib/cover-palette.references.json new file mode 100644 index 0000000..1710d20 --- /dev/null +++ b/apps/mobile/lib/cover-palette.references.json @@ -0,0 +1,92 @@ +[ + { + "label": "wicked-soundtrack", + "swatches": { + "background": "#4f4e33", + "average": "#74664d", + "dominantFraction": 0.184814453125, + "darkFraction": 0.195556640625 + }, + "expectedBackground": "#1a1c0e" + }, + { + "label": "wicked-broadway", + "swatches": { + "background": "#030605", + "average": "#74786c", + "dominantFraction": 0.423828125, + "darkFraction": 0.43798828125 + }, + "expectedBackground": "#111111" + }, + { + "label": "prince-of-egypt", + "swatches": { + "background": "#16101f", + "average": "#584546", + "dominantFraction": 0.585693359375, + "darkFraction": 0.587158203125 + }, + "expectedBackground": "#191718" + }, + { + "label": "civilization-vi", + "swatches": { + "background": "#ccaf90", + "average": "#b79e80", + "dominantFraction": 0.20703125, + "darkFraction": 0.001220703125 + }, + "expectedBackground": "#3f280c" + }, + { + "label": "ramblin-rover", + "swatches": { + "background": "#457522", + "average": "#548133", + "dominantFraction": 0.7802734375, + "darkFraction": 0 + }, + "expectedBackground": "#0e3900" + }, + { + "label": "cavalry", + "swatches": { + "background": "#0d131f", + "average": "#404954", + "dominantFraction": 0.317138671875, + "darkFraction": 0.38623046875 + }, + "expectedBackground": "#151d2f" + }, + { + "label": "city-of-angels", + "swatches": { + "background": "#1895cb", + "average": "#6c7c8b", + "dominantFraction": 0.241943359375, + "darkFraction": 0.075927734375 + }, + "expectedBackground": "#003262" + }, + { + "label": "we-the-kings", + "swatches": { + "background": "#ab3a33", + "average": "#923b32", + "dominantFraction": 0.577880859375, + "darkFraction": 0.16552734375 + }, + "expectedBackground": "#52170d" + }, + { + "label": "counter-strike-2", + "swatches": { + "background": "#060404", + "average": "#786757", + "dominantFraction": 0.35693359375, + "darkFraction": 0.390625 + }, + "expectedBackground": "#251211" + } +] diff --git a/apps/mobile/lib/cover-palette.test.cjs b/apps/mobile/lib/cover-palette.test.cjs new file mode 100644 index 0000000..15b9bd5 --- /dev/null +++ b/apps/mobile/lib/cover-palette.test.cjs @@ -0,0 +1,54 @@ +const { test } = require("node:test") +const assert = require("node:assert/strict") +const fs = require("node:fs") +const ts = require("typescript") +function load(name) { + const exports = {} + new Function( + "exports", + "require", + ts.transpileModule(fs.readFileSync(`${__dirname}/${name}.ts`, "utf8"), { + compilerOptions: { + module: ts.ModuleKind.CommonJS, + target: ts.ScriptTarget.ES2022, + }, + }).outputText + )(exports, (name) => load(name.replace("./", ""))) + return exports +} +const { deriveCoverPalette } = load("cover-palette") +const { toOklab, fromOklab } = load("color-space") + +test("sRGB and Oklab conversions round trip across the display gamut", () => { + for (const r of [0, 16, 64, 128, 192, 255]) + for (const g of [0, 16, 64, 128, 192, 255]) + for (const b of [0, 16, 64, 128, 192, 255]) + assert.deepEqual(fromOklab(toOklab([r, g, b])), [r, g, b]) +}) +test("near-black neutral artwork does not amplify arbitrary channel noise", () => { + for (const background of ["#000000", "#030605", "#050303"]) { + const palette = deriveCoverPalette({ background, average: "#747474" }) + assert.equal(palette.background, "#111111") + assert.equal(palette.foreground, "#FFFFFF") + } +}) +test("a conflicting shadow hue is muted while coherent dark blue retains its color", () => { + const shadow = deriveCoverPalette({ + background: "#16101f", + average: "#584546", + dominantFraction: 0.59, + darkFraction: 0.59, + }) + const blue = deriveCoverPalette({ + background: "#0d131f", + average: "#404954", + dominantFraction: 0.32, + darkFraction: 0.39, + }) + const rgb = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16)) + const shadowRgb = rgb(shadow.background), + blueRgb = rgb(blue.background) + assert.ok(Math.max(...shadowRgb) - Math.min(...shadowRgb) <= 4) + assert.ok(blueRgb[2] - blueRgb[0] > 15) + assert.equal(deriveCoverPalette({ background: "invalid" }), null) +}) diff --git a/apps/mobile/lib/cover-palette.ts b/apps/mobile/lib/cover-palette.ts index 3e0840e..543376d 100644 --- a/apps/mobile/lib/cover-palette.ts +++ b/apps/mobile/lib/cover-palette.ts @@ -1,4 +1,5 @@ import type { ThemeColors } from "@/lib/theme" +import { toOklab, fromOklab } from "./color-space" /** * Colors for a screen tinted by its cover art, modeled on Apple Music's @@ -26,7 +27,6 @@ export type CoverSwatches = { } type Rgb = [number, number, number] -type Hsl = { h: number; s: number; l: number } export function themeCoverPalette( theme: ThemeColors, @@ -45,99 +45,81 @@ export function themeCoverPalette( } } -/** - * Artwork pages use a dark, hue-matched canvas with neutral primary controls. - * Saturated covers stay deep; muted covers retain the lighter, subtly tinted - * canvas in the references: yellow #3E2B00, muted green #2A3028, and - * deep magenta #370C18. - */ +/** Dark artwork canvas derived from region coverage and perceptual color. */ export function deriveCoverPalette( swatches: CoverSwatches ): CoverPalette | null { const source = parseHex(swatches.background) if (!source) return null - const sampled = toHsl(source) - // Yellow loses its green cast when shaded to the warm amber in the reference. - const muted = Math.max(0, 1 - sampled.s / 0.35) - const warmHue = - sampled.h >= 45 && sampled.h <= 75 ? 42 + (sampled.h - 53) * 0.5 : sampled.h - // Deep magenta shadows need a burgundy canvas rather than near-black. - // Blend by hue and shadow depth so bright covers keep their own treatment. - const berry = - Math.max(0, 1 - Math.abs(sampled.h - 320) / 40) * - Math.min(1, Math.max(0, (0.12 - sampled.l) / 0.08)) - const h = warmHue - 16 * muted + 23.25 * berry - const s = Math.min(1, sampled.s * (1.2 + 2.7 * muted)) * (1 - 0.36 * berry) - const shadedLightness = Math.min(sampled.l, (31 + 14 * muted) / 255) - const l = shadedLightness * (1 - berry) + (33.5 / 255) * berry - const background = fromHsl({ h, s, l }) - const secondary = fromHsl({ - h: h - 2.5 + 8 * muted + 3 * berry, - s: s * (0.34 + 0.06 * muted + 0.024 * berry), - l: (174.5 - 2.5 * muted - 13.5 * berry) / 255, - }) + const average = swatches.average + ? (parseHex(swatches.average) ?? source) + : source + const [lightness, a, b] = toOklab(source) + const [, averageA, averageB] = toOklab(average) + const chroma = Math.hypot(a, b) + const averageChroma = Math.hypot(averageA, averageB) + const shadow = clamp((0.4 - lightness) / 0.3) + const coverage = clamp(swatches.dominantFraction ?? 1) + const darkCoverage = clamp(swatches.darkFraction ?? 0) + // Luminance alone makes bright, muted artwork too light and dark blue art + // almost black. Chroma and a bounded shadow lift retain both kinds of cover. + let canvasLightness = Math.max( + 0.17, + Math.min(0.4, 0.11 + 0.21 * lightness + 0.58 * chroma + 0.08 * shadow) + ) + let canvasChroma = Math.min(chroma * (1 + shadow), canvasLightness * 0.39) + + // A dark region whose hue conflicts with the whole image is often a shadow, + // rather than a reliable saturated background. Do not amplify that tint. + const disagreement = Math.max( + 0, + 1 - + (a * averageA + b * averageB) / Math.max(chroma * averageChroma, 1e-8) - + 0.3 + ) + canvasChroma *= Math.exp(-20 * shadow * disagreement) + canvasChroma *= Math.max( + 0, + 1 - 2.5 * darkCoverage * (1 - coverage) * (1 - shadow) + ) + + // Near-black RGB values carry unstable hue. Use the image's overall chroma + // to distinguish neutral artwork from a dark region in a colorful image. + const neutral = shadow * clamp((0.02 - chroma) / 0.02) + canvasChroma = + canvasChroma * (1 - neutral) + + Math.max(0, averageChroma - 0.02) * 3.5 * neutral + canvasLightness = + canvasLightness * (1 - neutral) + + (0.177 + Math.max(0, averageChroma - 0.02) * 2) * neutral + if (chroma < 0.01 && averageChroma < 0.025) { + canvasLightness = toOklab([17, 17, 17])[0] + canvasChroma = 0 + } + const direction = chroma > 0 ? canvasChroma / chroma : 0 + const background = fromOklab([canvasLightness, a * direction, b * direction]) + const mixWhite = (amount: number) => + toHex( + background.map((channel) => + Math.round(channel + (255 - channel) * amount) + ) as Rgb + ) return { background: toHex(background), foreground: "#FFFFFF", - secondaryForeground: toHex(secondary), + secondaryForeground: mixWhite(0.55), accent: "#FFFFFF", accentForeground: toHex(background), accentText: "#FFFFFF", - surface: toHex( - fromHsl({ - h: h - 0.9 + 3 * berry, - s: s * (0.6 + 0.1 * muted), - l: l + (19 - muted) / 255, - }) - ), - divider: toHex( - fromHsl({ - h, - s: s * (0.48 + 0.1 * muted + 0.025 * berry), - l: l + 33 / 255, - }) - ), + surface: mixWhite(0.08), + divider: mixWhite(0.12), isDark: true, } } -function toHsl([red, green, blue]: Rgb): Hsl { - const [r, g, b] = [red, green, blue].map((channel) => channel / 255) - const max = Math.max(r, g, b) - const min = Math.min(r, g, b) - const delta = max - min - const l = (max + min) / 2 - if (delta === 0) return { h: 0, s: 0, l } - const sector = - max === r - ? (g - b) / delta - : max === g - ? (b - r) / delta + 2 - : (r - g) / delta + 4 - return { - h: (sector * 60 + 360) % 360, - s: delta / (1 - Math.abs(2 * l - 1)), - l, - } -} - -function fromHsl({ h, s, l }: Hsl): Rgb { - const hue = (((h % 360) + 360) % 360) / 60 - const chroma = (1 - Math.abs(2 * l - 1)) * s - const x = chroma * (1 - Math.abs((hue % 2) - 1)) - const sectors = [ - [chroma, x, 0], - [x, chroma, 0], - [0, chroma, x], - [0, x, chroma], - [x, 0, chroma], - [chroma, 0, x], - ] - const offset = l - chroma / 2 - return sectors[Math.floor(hue)].map((channel) => - Math.round((channel + offset) * 255) - ) as Rgb +function clamp(value: number) { + return Math.max(0, Math.min(1, value)) } function parseHex(hex: string): Rgb | null { -- 2.54.1 From 1c6c0c2b9873c7717fac8b5e48bc5bf2e250baf8 Mon Sep 17 00:00:00 2001 From: Joshua Higgins Date: Fri, 13 Nov 2026 21:50:00 -0500 Subject: [PATCH 3/3] 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("")}` +} -- 2.54.1