feat(ui): add image placeholder priority setting

This commit is contained in:
jeffvli committed 2026-09-13 02:43:20 -07:00
1 parent b14f2599b7
commit a126b199b9
15 files changed
+166 -27

No files matched your search

+2 -1
View File
@@ -22,7 +22,8 @@ These variables override app settings **on first run** when no persisted setting
| `general.followCurrentSong` | `true` | `FS_GENERAL_FOLLOW_CURRENT_SONG` | `true` / `false` — Follow current song in list. |
| `general.followSystemTheme` | `false` | `FS_GENERAL_FOLLOW_SYSTEM_THEME` | `true` / `false` — Use OS light/dark preference. |
| `general.homeFeature` | `true` | `FS_GENERAL_HOME_FEATURE` | `true` / `false` — Show home featured carousel. |
| `general.homeFeatureStyle` | `single` | `FS_GENERAL_HOME_FEATURE_STYLE` | `multiple` / `single` — Home featured carousel style. |
| `general.homeFeatureStyle` | `single` | `FS_GENERAL_HOME_FEATURE_STYLE` | `multiple` / `single` - Home featured carousel style. |
| `general.imagePlaceholderPriority` | `thumbhash` | `FS_GENERAL_IMAGE_PLACEHOLDER_PRIORITY` | `thumbhash` / `blurhash` / `dominantColor` / `off` - Which image placeholder shows first while art loads; `off` disables placeholders. |
| `general.language` | `en` | `FS_GENERAL_LANGUAGE` | UI language code (e.g. `en`, `de`, `fr`). |
| `general.theme` | `defaultDark` | `FS_GENERAL_THEME` | One of: `ayuDark`, `ayuLight`, `catppuccinLatte`, `catppuccinMocha`, `defaultDark`, `defaultLight`, `dracula`, `githubDark`, `githubLight`, `glassyDark`, `gruvboxDark`, `gruvboxLight`, `highContrastDark`, `highContrastLight`, `materialDark`, `materialLight`, `monokai`, `nightOwl`, `nord`, `oneDark`, `rosePine`, `rosePineDawn`, `rosePineMoon`, `shadesOfPurple`, `solarizedDark`, `solarizedLight`, `tokyoNight`, `vscodeDarkPlus`, `vscodeLightPlus`. |
| `general.themeDark` | `defaultDark` | `FS_GENERAL_THEME_DARK` | Same as theme (used when system is dark). |
+1
View File
@@ -21,6 +21,7 @@ window.FS_GENERAL_FOLLOW_CURRENT_SONG = "${FS_GENERAL_FOLLOW_CURRENT_SONG}";
window.FS_GENERAL_FOLLOW_SYSTEM_THEME = "${FS_GENERAL_FOLLOW_SYSTEM_THEME}";
window.FS_GENERAL_HOME_FEATURE = "${FS_GENERAL_HOME_FEATURE}";
window.FS_GENERAL_HOME_FEATURE_STYLE = "${FS_GENERAL_HOME_FEATURE_STYLE}";
window.FS_GENERAL_IMAGE_PLACEHOLDER_PRIORITY = "${FS_GENERAL_IMAGE_PLACEHOLDER_PRIORITY}";
window.FS_GENERAL_LANGUAGE = "${FS_GENERAL_LANGUAGE}";
window.FS_GENERAL_LAST_FM = "${FS_GENERAL_LAST_FM}";
window.FS_GENERAL_LASTFM_API_KEY = "${FS_GENERAL_LASTFM_API_KEY}";
+7 -1
View File
@@ -1048,6 +1048,12 @@
"hotkey_zoomOut": "Zoom out",
"imageAspectRatio_description": "If enabled, cover art will be shown using their native aspect ratio. For art that is not 1:1, the remaining space will be empty",
"imageAspectRatio": "Use native cover art aspect ratio",
"imagePlaceholderPriority_description": "Sets the type of image placeholder to use while loading if available",
"imagePlaceholderPriority": "Image placeholder priority",
"imagePlaceholderPriority_optionBlurhash": "BlurHash",
"imagePlaceholderPriority_optionDominantColor": "Dominant color",
"imagePlaceholderPriority_optionOff": "Off",
"imagePlaceholderPriority_optionThumbhash": "ThumbHash",
"language": "Language",
"language_description": "Sets the language for the application ($t(common.restartRequired))",
"lastfm_description": "Show links to Last.fm on artist/album pages",
@@ -1644,4 +1650,4 @@
}
}
}
}
}
@@ -4,6 +4,7 @@ import { useTranslation } from 'react-i18next';
import styles from './drag-preview.module.css';
import { useItemImageUrl } from '/@/renderer/components/item-image/item-image';
import { useImagePlaceholderPriority } from '/@/renderer/store';
import { Icon } from '/@/shared/components/icon/icon';
import { useImageHashUrl } from '/@/shared/hooks/use-image-hash-url';
import { LibraryItem } from '/@/shared/types/domain-types';
@@ -45,7 +46,13 @@ export const DragPreview = memo(({ data }: DragPreviewProps) => {
dominantColor?: null | string;
thumbHash?: null | string;
};
const hashUrl = useImageHashUrl(item?.thumbHash, item?.blurHash, item?.dominantColor);
const imagePlaceholderPriority = useImagePlaceholderPriority();
const hashUrl = useImageHashUrl(
item?.thumbHash,
item?.blurHash,
item?.dominantColor,
imagePlaceholderPriority,
);
const isMultiple = itemCount > 1;
@@ -8,6 +8,7 @@ import {
useAuthStore,
useCurrentServerId,
useGeneralSettings,
useImagePlaceholderPriority,
useImageRes,
useSettingsStore,
} from '/@/renderer/store';
@@ -49,7 +50,8 @@ const BaseItemImage = (
) => {
const { blurHash, dominantColor, explicitStatus, serverId, src, thumbHash, ...rest } = props;
const { blurExplicitImages } = useGeneralSettings();
const hashUrl = useImageHashUrl(thumbHash, blurHash, dominantColor);
const imagePlaceholderPriority = useImagePlaceholderPriority();
const hashUrl = useImageHashUrl(thumbHash, blurHash, dominantColor, imagePlaceholderPriority);
const imageUrl = useItemImageUrl({
id: props.id,
@@ -3,6 +3,7 @@ import { useTranslation } from 'react-i18next';
import styles from './context-menu-preview.module.css';
import { useItemImageUrl } from '/@/renderer/components/item-image/item-image';
import { useImagePlaceholderPriority } from '/@/renderer/store';
import { Icon } from '/@/shared/components/icon/icon';
import { Text } from '/@/shared/components/text/text';
import { useImageHashUrl } from '/@/shared/hooks/use-image-hash-url';
@@ -59,7 +60,13 @@ export const ContextMenuPreview = ({ items, itemType }: ContextMenuPreviewProps)
dominantColor?: null | string;
thumbHash?: null | string;
};
const hashUrl = useImageHashUrl(item?.thumbHash, item?.blurHash, item?.dominantColor);
const imagePlaceholderPriority = useImagePlaceholderPriority();
const hashUrl = useImageHashUrl(
item?.thumbHash,
item?.blurHash,
item?.dominantColor,
imagePlaceholderPriority,
);
if (itemCount === 0) {
return null;
@@ -28,6 +28,7 @@ import { useFastAverageColor } from '/@/renderer/hooks';
import {
useFullScreenPlayerStore,
useFullScreenPlayerStoreActions,
useImagePlaceholderPriority,
usePlayerData,
usePlayerSong,
} from '/@/renderer/store';
@@ -82,8 +83,17 @@ const BackgroundImage = memo(({ dynamicBackground, dynamicIsImage }: BackgroundI
});
// Hash previews are free (no network fetch), so they are preferred for the background
const currentHashUrl = useImageHashUrl(currentSong?.thumbHash, currentSong?.blurHash);
const nextHashUrl = useImageHashUrl(nextSong?.thumbHash, nextSong?.blurHash);
const imagePlaceholderPriority = useImagePlaceholderPriority();
const currentHashUrl = useImageHashUrl(
currentSong?.thumbHash,
currentSong?.blurHash,
imagePlaceholderPriority,
);
const nextHashUrl = useImageHashUrl(
nextSong?.thumbHash,
nextSong?.blurHash,
imagePlaceholderPriority,
);
const [imageState, setImageState] = useState({
bottomHash: nextHashUrl,
@@ -35,6 +35,7 @@ import {
useCurrentServer,
useFullScreenPlayerStore,
useFullScreenPlayerStoreActions,
useImagePlaceholderPriority,
usePlayerData,
usePlayerSong,
useSetFullScreenPlayerStore,
@@ -94,8 +95,17 @@ const BackgroundImage = memo(({ dynamicBackground, dynamicIsImage }: BackgroundI
type: 'itemCard',
});
const currentHashUrl = useImageHashUrl(currentSong?.thumbHash, currentSong?.blurHash);
const nextHashUrl = useImageHashUrl(nextSong?.thumbHash, nextSong?.blurHash);
const imagePlaceholderPriority = useImagePlaceholderPriority();
const currentHashUrl = useImageHashUrl(
currentSong?.thumbHash,
currentSong?.blurHash,
imagePlaceholderPriority,
);
const nextHashUrl = useImageHashUrl(
nextSong?.thumbHash,
nextSong?.blurHash,
imagePlaceholderPriority,
);
const [imageState, setImageState] = useState({
bottomHash: nextHashUrl,
@@ -1,3 +1,5 @@
import type { ImagePlaceholderPriority } from '/@/shared/utils/image-hash';
import { t } from 'i18next';
import isElectron from 'is-electron';
import { memo, useCallback, useEffect, useState } from 'react';
@@ -85,6 +87,33 @@ const SIDE_QUEUE_LAYOUT_OPTIONS = [
},
];
const IMAGE_PLACEHOLDER_PRIORITY_OPTIONS = [
{
label: t('setting.imagePlaceholderPriority', {
context: 'optionThumbhash',
}),
value: 'thumbhash',
},
{
label: t('setting.imagePlaceholderPriority', {
context: 'optionBlurhash',
}),
value: 'blurhash',
},
{
label: t('setting.imagePlaceholderPriority', {
context: 'optionDominantColor',
}),
value: 'dominantColor',
},
{
label: t('setting.imagePlaceholderPriority', {
context: 'optionOff',
}),
value: 'off',
},
];
const FONT_TYPES: Font[] = [
{
label: i18n.t('setting.fontType', {
@@ -641,6 +670,28 @@ export const ApplicationSettings = memo(() => {
isHidden: false,
title: t('setting.blurExplicitImages'),
},
{
control: (
<Select
data={IMAGE_PLACEHOLDER_PRIORITY_OPTIONS}
defaultValue={settings.imagePlaceholderPriority}
onChange={(e) => {
if (!e) return;
setSettings({
general: {
...settings,
imagePlaceholderPriority: e as ImagePlaceholderPriority,
},
});
}}
/>
),
description: t('setting.imagePlaceholderPriority', {
context: 'description',
}),
isHidden: false,
title: t('setting.imagePlaceholderPriority'),
},
{
control: (
<Switch
@@ -26,6 +26,7 @@ import {
useAppStoreActions,
useFullScreenPlayerStore,
useGeneralSettings,
useImagePlaceholderPriority,
usePlayerSong,
useSetFullScreenPlayerStore,
} from '/@/renderer/store';
@@ -180,7 +181,12 @@ const SidebarImage = () => {
serverId: currentSong?._serverId,
type: 'sidebar',
});
const songHashUrl = useImageHashUrl(currentSong?.thumbHash, currentSong?.blurHash);
const imagePlaceholderPriority = useImagePlaceholderPriority();
const songHashUrl = useImageHashUrl(
currentSong?.thumbHash,
currentSong?.blurHash,
imagePlaceholderPriority,
);
const radioImageUrl = useItemImageUrl({
id: isRadioActive ? currentStationArt?.imageId || undefined : undefined,
+1
View File
@@ -35,6 +35,7 @@ declare global {
FS_GENERAL_FOLLOW_SYSTEM_THEME?: string;
FS_GENERAL_HOME_FEATURE?: string;
FS_GENERAL_HOME_FEATURE_STYLE?: string;
FS_GENERAL_IMAGE_PLACEHOLDER_PRIORITY?: string;
FS_GENERAL_LANGUAGE?: string;
FS_GENERAL_LAST_FM?: string;
FS_GENERAL_LASTFM_API_KEY?: string;
@@ -1,6 +1,7 @@
import type { PlayerFilter, SettingsState } from './settings.store';
import { sanitizeCss } from '/@/renderer/utils/sanitize';
import { IMAGE_PLACEHOLDER_PRIORITIES } from '/@/shared/utils/image-hash';
const PLAYER_FILTER_FIELDS = new Set([
'albumArtist',
@@ -197,6 +198,12 @@ const ENV_SETTING_SPECS: EnvSettingSpec[] = [
path: ['general', 'homeFeatureStyle'],
type: 'enum',
},
{
enumSet: new Set(IMAGE_PLACEHOLDER_PRIORITIES),
key: 'FS_GENERAL_IMAGE_PLACEHOLDER_PRIORITY',
path: ['general', 'imagePlaceholderPriority'],
type: 'enum',
},
{
key: 'FS_GENERAL_LANGUAGE',
path: ['general', 'language'],
+6
View File
@@ -40,6 +40,7 @@ import {
PlayerType,
TableColumn,
} from '/@/shared/types/types';
import { IMAGE_PLACEHOLDER_PRIORITIES } from '/@/shared/utils/image-hash';
const utils = isElectron() ? window.api.utils : null;
@@ -537,6 +538,7 @@ export const GeneralSettingsSchema = z.object({
homeFeature: z.boolean(),
homeFeatureStyle: z.nativeEnum(HomeFeatureStyle),
homeItems: z.array(SortableItemSchema(HomeItemSchema)),
imagePlaceholderPriority: z.enum(IMAGE_PLACEHOLDER_PRIORITIES),
imageRes: z.object({
fullScreenPlayer: z.number(),
header: z.number(),
@@ -1360,6 +1362,7 @@ const initialState: SettingsState = {
homeFeature: true,
homeFeatureStyle: HomeFeatureStyle.SINGLE,
homeItems,
imagePlaceholderPriority: 'thumbhash',
imageRes: {
fullScreenPlayer: 0,
header: 300,
@@ -3034,6 +3037,9 @@ export const useAccent = () => useSettingsStore((state) => state.general.accent,
export const useNativeAspectRatio = () =>
useSettingsStore((state) => state.general.nativeAspectRatio, shallow);
export const useImagePlaceholderPriority = () =>
useSettingsStore((state) => state.general.imagePlaceholderPriority);
export const useButtonSize = () => useSettingsStore((state) => state.general.buttonSize, shallow);
export const useSkipButtons = () => useSettingsStore((state) => state.general.skipButtons, shallow);
+4 -3
View File
@@ -1,14 +1,15 @@
import { useMemo } from 'react';
import { decodeImageHashDataUrl } from '/@/shared/utils/image-hash';
import { decodeImageHashDataUrl, type ImagePlaceholderPriority } from '/@/shared/utils/image-hash';
export function useImageHashUrl(
thumbHash: null | string | undefined,
blurHash: null | string | undefined,
dominantColor: null | string | undefined = null,
priority: ImagePlaceholderPriority = 'thumbhash',
): null | string {
return useMemo(
() => decodeImageHashDataUrl(thumbHash ?? null, blurHash ?? null, dominantColor),
[blurHash, dominantColor, thumbHash],
() => decodeImageHashDataUrl(thumbHash ?? null, blurHash ?? null, dominantColor, priority),
[blurHash, dominantColor, priority, thumbHash],
);
}
+37 -14
View File
@@ -1,9 +1,28 @@
import { blurHashToRgba } from '/@/shared/utils/blurhash';
import { thumbHashToRgba } from '/@/shared/utils/thumbhash';
export const IMAGE_PLACEHOLDER_PRIORITIES = [
'blurhash',
'dominantColor',
'off',
'thumbhash',
] as const;
export type ImagePlaceholderPriority = (typeof IMAGE_PLACEHOLDER_PRIORITIES)[number];
const PRIORITY_FALLBACK_ORDER: Record<
ImagePlaceholderPriority,
readonly ImagePlaceholderPriority[]
> = {
blurhash: ['blurhash', 'thumbhash', 'dominantColor'],
dominantColor: ['dominantColor', 'thumbhash', 'blurhash'],
off: [],
thumbhash: ['thumbhash', 'blurhash', 'dominantColor'],
};
// Module-level cache of decoded PNG data URLs, capped FIFO (~1000 entries) so a
// long session over a large library does not accumulate unbounded data URLs.
const CACHE_CAP = 1000;
const CACHE_CAP = 5000;
const urlCache = new Map<string, string>();
/**
@@ -25,31 +44,35 @@ export function decodeBlurHashDataUrl(hash: string): null | string {
}
/**
* Picks a placeholder to render by field, never by sniffing the string:
* `thumbHash` wins, then `blurHash`, then a solid `dominantColor` swatch.
* This is the single decode entry point the image-hash hook calls. Returns
* null when no field yields a placeholder.
* Picks a placeholder to render by field, never by sniffing the string.
* By default `thumbHash` wins, then `blurHash`, then a solid `dominantColor`
* swatch; `priority` moves one source to the front of that order, or is
* `'off'` to disable placeholders. This is the single decode entry point the
* image-hash hook calls. Returns null when no field yields a placeholder.
*
* @param thumbHash A base64 ThumbHash, or null when the item has none.
* @param blurHash A BlurHash string, or null when the item has none.
* @param dominantColor A hex color, or null when the item has none.
* @param priority Which source to try first when the item has several.
*/
export function decodeImageHashDataUrl(
thumbHash: null | string,
blurHash: null | string,
dominantColor: null | string | undefined = null,
priority: ImagePlaceholderPriority = 'thumbhash',
): null | string {
if (thumbHash) {
const url = decodeThumbHashDataUrl(thumbHash);
const decoders: Record<ImagePlaceholderPriority, () => null | string> = {
blurhash: () => (blurHash ? decodeBlurHashDataUrl(blurHash) : null),
dominantColor: () => (dominantColor ? dominantColorToDataUrl(dominantColor) : null),
off: () => null,
thumbhash: () => (thumbHash ? decodeThumbHashDataUrl(thumbHash) : null),
};
for (const source of PRIORITY_FALLBACK_ORDER[priority]) {
const url = decoders[source]();
if (url) return url;
}
if (blurHash) {
const url = decodeBlurHashDataUrl(blurHash);
if (url) return url;
}
if (dominantColor) {
return dominantColorToDataUrl(dominantColor);
}
return null;
}