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 e5c5d1f..7280c45 100644
--- a/apps/mobile/hooks/use-cover-palette.ts
+++ b/apps/mobile/hooks/use-cover-palette.ts
@@ -1,5 +1,10 @@
import { useEffect, useMemo, useState } from "react"
-import { getColors, type ImageColorsResult } from "react-native-image-colors"
+import {
+ artworkColorsEnabled,
+ useArtworkColorsEnabled,
+} from "@/lib/artwork-color-preference"
+import { prefetchLegacyCoverPalette, useLegacyCoverPalette } from "@/hooks/use-legacy-cover-palette"
+import { extractCoverSwatches } from "@/lib/artwork-colors"
import {
deriveCoverPalette,
@@ -15,49 +20,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 +36,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)
@@ -101,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)
@@ -114,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 } {
@@ -166,7 +126,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])
@@ -177,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/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/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 fa441fb..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
@@ -17,33 +18,20 @@ 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 }
-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,89 @@ export function themeCoverPalette(theme: ThemeColors, isDark: boolean): CoverPal
}
}
+/** Dark artwork canvas derived from region coverage and perceptual color. */
export function deriveCoverPalette(
- swatches: CoverSwatches,
- schemeIsDark: boolean
+ swatches: CoverSwatches
): CoverPalette | null {
const source = parseHex(swatches.background)
if (!source) return null
+ 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)
- 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
+ // 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)
)
- const textCandidates = sameSideText.length > 0 ? sameSideText : parsedText
- const fallbackText: Rgb = lightText ? [255, 255, 255] : [0, 0, 0]
+ let canvasChroma = Math.min(chroma * (1 + shadow), canvasLightness * 0.39)
- const foreground = withMinContrast(
- textCandidates[0] ?? fallbackText,
- background,
- PRIMARY_MIN_CONTRAST
+ // 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
)
- 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
+ canvasChroma *= Math.exp(-20 * shadow * disagreement)
+ canvasChroma *= Math.max(
+ 0,
+ 1 - 2.5 * darkCoverage * (1 - coverage) * (1 - shadow)
)
- const accent = pickAccent(swatches.accent, background) ?? foreground
- const accentForeground: Rgb = prefersLightText(accent)
- ? [255, 255, 255]
- : [0, 0, 0]
-
+ // 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: 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: mixWhite(0.55),
+ accent: "#FFFFFF",
+ accentForeground: toHex(background),
+ accentText: "#FFFFFF",
+ surface: mixWhite(0.08),
+ divider: mixWhite(0.12),
+ 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
- }
-
- const pivot = schemeIsDark ? 0.28 : 0.14
- return y < pivot
- ? withLuminance(clamped, DARK_BACKGROUND_MAX_LUMINANCE)
- : withLuminance(clamped, LIGHT_BACKGROUND_MIN_LUMINANCE)
+function clamp(value: number) {
+ return Math.max(0, Math.min(1, value))
}
-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)
+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/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("")}`
+}
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
+}