PiraChest Docs Download
Documentation menu
Docs / Theming

Theming reference

Every surface, label, state color, icon, background, title-bar layer and interface sound in PiraChest comes from one theme preset. This page explains the 56 palette roles, the ten roots they derive from, the 178 icon slots, the full theme.json schema, and the machinery that puts it on screen.

Quick start

A theme is a folder inside PiraChest's data directory under themes/, containing a theme.json and any assets it needs. The fallback location when no app data directory exists is ~/.pirachest/themes. Folders whose names start with _ or . are reserved and ignored by the loader. Theme ids must be unique among custom themes and must not collide with a built-in id.

themes/
themes/
  midnight-ink/
    theme.json
    theme.qss
    assets/
      city.webp
      click.wav
      pause.png

The shortest useful theme sets five roles. It inherits everything else from the dark base and the derivation rules, so you get coherent borders, hovers, buttons, navigation and dialogs without writing them:

themes/midnight-ink/theme.json
{
  "label": "Midnight Ink",
  "base_dark": true,
  "palette": {
    "page_bg": "#0b1020",
    "card_bg": "#131a2e",
    "primary_text": "#e8ecf5",
    "muted": "#98a2b8",
    "accent": "#6cb6ff"
  }
}

Save it, open Settings → Appearance → Theme, and pick it from the list. While a folder theme is active its folder, theme.json and theme.qss are watched; edits re-apply after a 250 ms debounce without a restart. A shader file referenced by the theme is watched too.

Screenshots

These are real captures from the 0.1.0-beta build, with each preset applied across the whole app. The theme is not a tint over a fixed shell: navigation, cards, inputs, dialogs, scrollbars, the title bar and the download states all move together.

PiraChest with the AMOLED theme applied
AMOLEDDark · accent unlocked
PiraChest with the Cyberpunk theme applied
CyberpunkDark · accent locked
PiraChest with the Gruvbox Dark theme applied
Gruvbox DarkDark · accent locked
PiraChest with the Rosé Pine theme applied
Rosé PineDark · accent locked
PiraChest with the VGUI theme applied
VGUIDark · accent locked
PiraChest with the XMB theme applied
XMBCommunity theme · Discord exclusive

XMB is a community theme distributed through Discord, not one of the built-in presets. It is included here because it exercises the title bar, background and icon overrides at once.

Where the roles land

PiraChest Home screen with category tiles and posters
Homepage_bg, card_bg, nav_*
PiraChest repack selective download dialog
Selective downloaddialogs, inputs, section cards
PiraChest Music library
Musiclist_bg, scrollbars
PiraChest repack details view
Repack detailsdetail_* roles
PiraChest torrent search results
Torrent searchstate and meta colors
PiraChest repack sources view
Repacksbranded source icons

Roots and derivation

There are 56 palette roles. Ten are roots: page_bg, card_bg, primary_text, muted, accent, state_queued, state_downloading, state_verifying, state_seeding and state_error. Every other role has a built-in rule expressed over other roles. You override a role only when the rule's result is not what you want. Whatever you set wins; everything else follows the rules.

card_bg and muted are roots with useful fallbacks: lift(@page_bg,.035) and mix(@primary_text,@page_bg,.4). Set them when you have a specific surface or secondary ink in mind; leave them out and the theme still holds together.

RootWhat it anchorsDark base defaultLight base default
page_bgWindow and page background#121212#f3f3f4
card_bgCards, panels, detail boxes#1b1b1b#ffffff
primary_textTitles and primary text#eaeaea#101828
mutedCaptions and secondary labels#9a9a9a#5b6472
accentLinks, focus, selection, badges#c9c9c9#0078d4
state_queuedQueued transfers#7a7a7a#6b7280
state_downloadingActive transfers#3b9df3#0078d4
state_verifyingHash checks#e08838#c15a0a
state_seedingSeeding and completed#3fc240#0e7a0e
state_errorFailures#e5484d#c42b1c

The same dependency graph is used in reverse when a custom theme extends a base. Change primary_text, and muted, borders, nav text, dialog text and icons all re-derive instead of keeping the parent's old literals.

Color expressions

Every palette value is a string. These forms are accepted, case-insensitively for function names:

FormMeaning
#rgb #rgba #rrggbb #rrggbbaaHex. Alpha digits come last (CSS order), not first as in Qt.
rgb(r,g,b) rgba(r,g,b,a)Channels 0–255. Alpha is 0–1, or 0–255 when the value is above 1.
@roleAnother role's resolved value. Chains are followed to the end.
alpha(@role, .5)Multiplies the color's existing alpha by the number.
mix(@a, @b, t)Linear blend per channel. t=0 is all @a, t=1 is all @b; alpha blends too.
lift(@role, .035)Raises a color toward white with a curve that responds hardest in dark midtones. This is what makes card_bg sit just above page_bg.
theme.json
{
  "palette": {
    "page_bg": "#0b1020",
    "card_bg": "mix(@page_bg, #ffffff, .06)",
    "surface_border": "alpha(@primary_text, .10)",
    "faint_text": "alpha(@muted, .55)",
    "btn_hover": "mix(@card_bg, @primary_text, .1)"
  }
}

All 56 roles

Roles are grouped by what they paint. root marks the ten roots; a rule in the last column is the fallback used when the role is not set. The on_accent foreground is auto-corrected to whichever of white or #111111 contrasts better with the resolved accent, unless you set it yourself.

The two base modes override a few fallbacks. Both use @card_bg for dialog_bg. Dark also sets nav_selected_text to @primary_text, softer card_hover, btn_hover and section_card_bg mixes (.045, .07, .03) and a rgba(0,0,0,.30) list_bg. Light uses @card_bg for btn_bg, @section_card_bg for detail_box_bg, @surface_tint for poster_fallback_bg, alpha(@primary_text,.02) for nav_bg, a .04 section_card_bg and a rgba(0,0,0,.035) list_bg.

Roots

RoleWhat it paintsDefault
page_bg rootWindow, page and unpainted container background.root
card_bg rootCards, panels, detail boxes and the default input fill.lift(@page_bg,.035)
primary_text rootTitles, primary labels and the default icon ink.root
muted rootCaptions, secondary labels and metadata.mix(@primary_text,@page_bg,.4)
accent rootLinks, focus, selection, count badges and filled accents.root
state_queued rootQueued download badge and queue progress.root
state_downloading rootActive download badge and progress.root
state_verifying rootVerification and hash-check badge.root
state_seeding rootSeeding badge; also backs the completed state.root
state_error rootFailure badge and destructive state text.root

Text

RoleWhat it paintsDefault
body_textParagraph and sentence text.mix(@primary_text,@page_bg,.15)
faint_textWeakest helper text, timestamps and hints.mix(@muted,@page_bg,.25)
accent_textText that deliberately uses the accent color.@accent
on_accentForeground on accent-filled badges, buttons and icons.#ffffff, auto-corrected
detail_titleDetail page title.@primary_text
detail_subtitleDetail page accent subtitle.@accent
detail_metaDetail page metadata and secondary facts.@muted
icon_colorDefault tint for icons outside navigation.@primary_text

Surfaces

RoleWhat it paintsDefault
card_hoverCard background on hover.mix(@card_bg,@primary_text,.06)
card_borderCard and panel outline.alpha(@primary_text,.08)
surface_tintSubtle translucent overlay.alpha(@primary_text,.05)
surface_tint_strongStronger translucent overlay.alpha(@primary_text,.09)
surface_borderDividers, chip borders and overlay outlines.alpha(@primary_text,.1)
hover_tintGeneric hover wash on non-card widgets.alpha(@primary_text,.06)
inactive_dotInactive pager and carousel dots.alpha(@primary_text,.22)
poster_fallback_bgBacking behind a missing poster or cover.@card_bg
section_card_bgNested section card background.mix(@card_bg,@primary_text,.05)
section_card_borderNested section card outline.@surface_border
scrollbar_handleScrollbar thumb.alpha(@primary_text,.16)
scrollbar_handle_hoverScrollbar thumb on hover.alpha(@primary_text,.26)

Inputs and buttons

RoleWhat it paintsDefault
input_bgText field, combo box and spin box fill.@card_bg
input_borderInput outline at rest.alpha(@primary_text,.14)
input_border_hoverInput outline on hover.alpha(@primary_text,.22)
input_border_focusInput outline on focus. Accent-linked.@accent
btn_bgStandard button background.mix(@card_bg,@primary_text,.04)
btn_borderStandard button outline.@input_border
btn_hoverStandard button hover fill.mix(@card_bg,@primary_text,.1)
btn_textStandard button label.@primary_text

Detail views and lists

RoleWhat it paintsDefault
detail_box_bgMetadata box behind detail facts.@card_bg
detail_box_borderMetadata box outline.@card_border
list_bgBacking behind list and table views.alpha(@page_bg,.5)

Navigation

RoleWhat it paintsDefault
nav_bgSidebar background.@page_bg
nav_textSidebar label at rest.@primary_text
nav_iconSidebar icon at rest.@primary_text
nav_selected_bgSelected navigation pill.alpha(@primary_text,.12)
nav_selected_textSelected navigation label. Accent-linked.@accent
nav_selected_iconSelected navigation icon. Accent-linked.@accent
nav_hover_bgNavigation hover pill.alpha(@primary_text,.07)

Dialogs

RoleWhat it paintsDefault
dialog_bgDialog and message box background.@page_bg
dialog_borderDialog outline.@card_border
dialog_title_textDialog title.@primary_text
dialog_body_textDialog body copy.@body_text
dialog_accent_textDialog links and accent actions. Accent-linked.@accent

Derived states

RoleWhat it paintsDefault
state_pausedPaused download badge.@state_queued
state_completedCompleted download badge.@state_seeding
state_cancelledCancelled download badge.@state_queued

Rules can reference any role, including one defined later. Resolution follows @ references recursively and detects cycles.

Contrast protection

After resolving the palette, the engine checks the roles that carry text or icons against the surfaces they actually sit on. If a pair falls below its target, the foreground is moved toward the page's ink pole until it passes, or until the floor is reached. This is why a hand-picked muted color can come back slightly lighter or darker than written.

RoleChecked againstTargetFloor
primary_text, body_text, detail_titlepage, card, section card4.5:1—
muted, detail_metapage, card, section card4.0:13.5:1
faint_textpage, card, section card3.0:12.8:1
btn_textbutton background4.5:1—
nav_textpage, nav hover, selected pill4.5:1—
nav_iconpage, nav hover, selected pill3.0:1—
icon_colorpage, card3.0:1—
dialog_title_text, dialog_body_textdialog background4.5:1—
accent_text, dialog_accent_textpage, card, dialog4.5:13.0:1
detail_subtitlepage, card, detail box4.0:13.0:1
nav_selected_textpage, selected pill3.5:12.8:1
nav_selected_iconpage, selected pill3.0:12.5:1
All eight state_* rolespage, card2.5:12.0:1

Two extra safeguards run first. If primary_text is below 2:1 against page_bg, it is replaced with #f4f4f5 or #111318, whichever fits the page better. And if you do not set on_accent, it is chosen automatically for count badges, accent icons and other filled controls.

Built-in presets

PiraChest ships a plain Dark and Light mode plus thirteen named presets. Swatches show page, card, primary text and accent. The four-character code under each name is the accent role.

Dark#121212 · accent #c9c9c9 · base mode · accent follows Settings
Light#f3f3f4 · accent #0078d4 · base mode · accent follows Settings
AMOLED#000000 · accent #22d3ee · dark · accent unlocked · id amoled
Ember#2c1006 · accent #ff8346 · dark · accent locked · id gruvbox_dark
Bloodstone#130b0d · accent #c73a4e · dark · accent locked · id bloodstone
Golden Wind#16100a · accent #c99a3e · dark · accent locked · id golden_wind
Nightshade#1e0d21 · accent #c0f447 · dark · accent locked · id dracula
Cyberpunk#0d0221 · accent #ff2e88 · dark · accent locked · id cyberpunk
Rosewood#4b2c39 · accent #7fe3ce · dark · accent locked · id rose_pine
Tidepool#003631 · accent #fbe6af · dark · accent locked · id solarized_dark
Slate#343d47 · accent #f3b7a4 · dark · accent locked · id everforest
Dune#3c362a · accent #b6aaff · dark · accent locked · id nord
VGUI#333d2e · accent #7a9c34 · dark · accent locked · id vgui
Linen#f0e1c4 · accent #006965 · light · accent locked · id tokyo_night
Sorbet#feeaee · accent #a70d61 · light · accent locked · id catppuccin_rose

Labels shown in Settings differ from preset ids; extends takes the id (for example nord is the preset labelled Dune). Presets are locked to their own accent except AMOLED and the plain Dark/Light modes. A custom theme whose id collides with a built-in id is skipped and reported in the loader's errors.

Accent behavior

Setting an accent does more than set accent. It also rewrites five roles to @accent: nav_selected_icon, nav_selected_text, input_border_focus, dialog_accent_text and detail_subtitle. That is why a one-line accent change recolors the sidebar selection, focus rings, dialog links and detail subtitles together.

  • "locked_accent": true (the default for custom themes): the theme's own accent is always used.
  • "locked_accent": false: the user's accent from Settings is applied on top of the theme, re-resolving all derived roles. The five linked roles above are overwritten with @accent, so hard-coding them in an unlocked theme has no effect.
  • A top-level "accent" key is shorthand for palette.accent.

theme.json reference

KeyTypeNotes
idstringDefaults to the folder name. Must be unique and not a built-in id.
labelstringDisplay name. Defaults to the id.
extendsstringId of another theme to inherit from. See below.
base_darkboolChooses the dark or light base palette and the app's light/dark mode. Defaults to the parent's value, else true.
paletteobjectRole → expression. Unknown roles or non-string values are ignored with a warning.
accentstringShorthand for palette.accent, applied after the palette.
locked_accentboolDefault true. See Accent.
backgroundobjectImage, GIF or shader background. See Backgrounds.
backdropstringnone, acrylic or blur. Native Windows DWM material. Windows only; resolves to none on Linux and macOS.
transparent_windowboolForces a transparent window even without a backdrop.
win7_frameboolOpts into the native Aero glass frame. Windows only. Never enabled implicitly.
titlebarobjectThe chrome DSL. See Title bar.
iconsobjectSlot id → Fluent name, image spec or {fluent|image, crop}.
widget_iconsarrayWidget selector → icon spec, applied after the theme.
layoutobjectLayout token overrides. Values are strings; unknown keys are ignored.
qssstringRaw Qt stylesheet appended to the app-wide sheet.
rulesarrayStructured {selector, state, css} rules. See QSS.
font_familiesarrayInstalled family names to prefer.
font_pathsarrayFont files relative to the theme folder, registered at load.
sfxobjectSound key → file. See Fonts & sounds.

A theme may also contain theme.qss. It is read as UTF-8, capped at 256 KB, and concatenated with "qss" and the generated rules.

Loading never raises into startup. A malformed theme lands in the loader's errors and is skipped; recoverable problems land in warnings. Neither can prevent the app from starting.

Inheriting with extends

A child copies its parent's unresolved role expressions, then applies its own on top, so derived roles recompute from the child's roots. Retint one color of a built-in preset (here nord, labelled Dune) and everything derived from it moves too.

themes/nord-ember/theme.json
{
  "label": "Dune Ember",
  "extends": "nord",
  "palette": {
    "accent": "#d08770",
    "detail_subtitle": "@accent",
    "nav_selected_icon": "@accent"
  }
}

Parents can be a built-in or another custom theme, but custom folders load in alphabetical order, so a parent must sort before its child. An unknown parent produces a warning and falls back to the selected base palette.

When you override a surface root, the loader discards the parent's stale literal values for dependent roles before resolving. That means a child can change page_bg without inheriting the parent's hard-coded nav backgrounds and borders.

Backgrounds and window material

theme.json
"background": {
  "type": "image",
  "file": "assets/city.webp",
  "blur": 18,
  "darken": 55,
  "scope": "client"
}
FieldValues
typeimage (default) or shader. A shader string also selects shader mode when type is absent.
fileImage/GIF, or the shader source. Relative to the theme folder. If missing or unreadable the background is silently dropped.
blur, darken0–100, defaults 12 and 45. Image type only.
scopecontent, client (default) or window: how much of the window the artwork covers.
image, fps, aaShader only. Optional texture, frame rate 0–240 (0 means display rate), anti-aliasing limited to 0, 2, 4 or 8.

"backdrop" applies a Windows DWM material: acrylic needs Windows 10 build 17134+, blur needs Vista-era build 6000+. On unsupported systems, including Linux and macOS, it quietly becomes none. A supported backdrop makes the window transparent automatically; "transparent_window": true forces it. Otherwise the window stays opaque on purpose, so an unthemed widget can never show a white hole. "win7_frame": true is a separate explicit opt-in for the native Aero glass frame; a backdrop never turns it on by itself.

Title bar and sidebar chrome

The titlebar object drives a custom-painted title bar, window buttons, header chips (Donate, Discord) and the sidebar. You specify only what differs from the defaults; objects merge deeply.

On Canary builds the window title ends in “ Canary”, and the title bar draws that word as a small CANARY badge after the app name. Its color follows the brightness of your title color, so it needs no theme settings.

KeyNotes
modeoverlay (default) paints only the bar. frame paints a border ring around the whole client area.
height, frameBar height 16–96 (default 48); frame thickness 1–24 (frame mode only). height_maximized and frame_maximized override when maximized.
inset_left, padding, padding_maximizedLeft offset (default 46 for overlay, 0 for frame); [left,right] inner padding, optionally different when maximized.
cornerdefault, square, round or small (Windows 11 corners).
icon, dark, backdrop_tint, force_fallbackApp icon size 8–48; explicit light/dark chrome; a tint over the native backdrop; skip the native material and use the painted fallback.
titlesize, bold, color, family, padding, and a glow of color, alpha, radius.
chipsheight, radius, padding, spacing, gap, icon, size, inherit_buttons and a style with normal/hover/pressed.
buttonswidth, height, spacing, bleed, style, per-kind overrides in kinds.min|max|close (including corners), and vector glyphs.
navradius, text, icon, selected_text, selected_icon, indicator, separator, hover, selected, text_glow.
chrome, sidebar, nav_backgroundlinked shares one glass behind bar and sidebar (no seam); split gives the sidebar its own fill/layers. nav_background empty or transparent shows the chrome through; a color paints it solid.
layers, fallback, holePaint stack for the chrome and for the non-native fallback. hole is client or content.

Layers

Layers paint in order. Types: fill, gradient (stops as [position, color] pairs, direction, span in bar heights), band (a skewed highlight streak) and border (width, inset, radius_delta). target picks the area: chrome (default), window, client or content. Add "skip_maximized": true to hide a layer when maximized.

Colors here accept #hex, rgba(), @role, or {"active": ..., "inactive": ...} to change when the window loses focus. Title bar colors do not evaluate alpha(), mix() or lift(); precompute those into palette roles and reference them with @.

theme.json
"titlebar": {
  "mode": "frame",
  "frame": 6,
  "height": 42,
  "corner": "round",
  "title": {
    "bold": true,
    "color": { "active": "@primary_text", "inactive": "@muted" }
  },
  "buttons": {
    "kinds": {
      "close": { "style": { "hover": { "fill": "#E81123", "glyph": "#FFFFFF" } } }
    }
  },
  "layers": [
    { "type": "fill", "color": "rgba(12,16,32,0.72)" },
    { "type": "gradient", "span": 1,
      "stops": [[0, "rgba(255,255,255,0.10)"], [1, "rgba(255,255,255,0)"]] },
    { "type": "border", "target": "window", "color": "@surface_border" }
  ]
}

Contrast is protected for you: when the sidebar sits on glass, nav text and icon colors are nudged until they pass the target against the chrome, and chip text gets the same treatment.

Icon overrides

Icons are addressed by slot ids grouped by area. There are 178 slots. The Theme Maker's Icons tab lists every slot with its default and a search box; the tables below are the same list.

AreaSlotsCovers
nav.*13Sidebar, header and data-folder actions.
home.*10Category tiles, poster placeholders and chevrons.
download.*22Transfer rows, bulk actions and drop zone.
minerva.*4Game catalog download and sync actions.
repacks.*14Source tabs, cards, navigation and site actions.
badge.*5Badge slots: pink paw, hypervisor, Switch, NS2 and PS3.
music.*31Player, cards, rows, playlists and search.
books.*2Detail navigation and chapter downloads.
tbhb.*10Result paging, detail statistics and reset.
yt.*3Download gate, empty state and action.
tv.*21Tabs, channel controls and the video player.
settings.*36Every settings row, tab and folder picker.
about.*3Repository, community and thanks actions.
app.*4Donate chip, Discord chip and sync prompt.
theme.json
"icons": {
  "nav.home": "HEART",
  "nav.music": { "fluent": "MUSIC" },
  "download.item_pause": { "image": "assets/pause.png", "crop": true }
}
  • A bare string is a Fluent icon name (case-insensitive); an unknown name falls back to the slot default.
  • image with no slash is looked up in the theme's icons/ folder first, then its root. Paths may be relative to the theme folder, but a relative path that escapes it is rejected.
  • crop (default true) trims transparent margins so artwork fills the icon box.
  • Fluent and bare icons are tinted with the theme's icon colors; images are drawn as-is.
  • repacks.tab_fitgirl, repacks.tab_gog and repacks.tab_tbhb use branded_icon(): the shipped source artwork is kept untinted by default. Override the slot to replace it; a Fluent override is tinted, an image override is not.

widget_icons targets widgets by selector instead of slot: [{"match": "#settingsButton", "spec": "SETTING"}], where spec uses the same forms as above. Widget icons are applied after the theme's slots and are meant for one-off UI, not a coherent icon set.

Navigation13 slots
SlotDefault Fluent icon
nav.toggleMENU
nav.homeHOME
nav.downloadsDOWNLOAD
nav.settingsSETTING
nav.aboutINFO
nav.open_data_folderFOLDER
nav.minervaAPPLICATION
nav.pc_gamesGAME
nav.musicMUSIC
nav.booksBOOK_SHELF
nav.youtubePLAY
nav.tvPROJECTOR
nav.tbhbSEARCH
Home10 slots
SlotDefault Fluent icon
home.category_repacksGAME
home.category_musicMUSIC
home.category_animeVIDEO
home.category_youtubePLAY
home.category_mangaBOOK_SHELF
home.category_tbhbSEARCH
home.poster_placeholderPHOTO
home.playlist_tileMUSIC
home.see_all_chevronRIGHT_ARROW
home.card_chevronRIGHT_ARROW
Downloads22 slots
SlotDefault Fluent icon
download.drop_zoneDOWNLOAD
download.donate_copy_addressCOPY
download.item_pausePAUSE
download.item_resumePLAY
download.item_retrySYNC
download.item_open_fileDOCUMENT
download.item_installPLAY
download.item_open_folderFOLDER
download.item_settingsSETTING
download.item_cancelCLOSE
download.item_removeDELETE
download.stat_activeSPEED_HIGH
download.stat_downloadDOWNLOAD
download.stat_uploadSHARE
download.stat_queuedPAUSE_BOLD
download.stat_completedACCEPT
download.add_torrentADD
download.pause_allPAUSE
download.resume_allPLAY
download.delete_allDELETE
download.open_downloads_rootFOLDER
download.empty_stateDOWNLOAD
Minerva4 slots
SlotDefault Fluent icon
minerva.tile_downloadDOWNLOAD
minerva.detail_downloadDOWNLOAD
minerva.download_selectedDOWNLOAD
minerva.syncSYNC
Repacks14 slots
SlotDefault Fluent icon
repacks.card_fallbackGAME
repacks.latest_prevLEFT_ARROW
repacks.latest_nextRIGHT_ARROW
repacks.detail_backRETURN
repacks.detail_cover_fallbackGAME
repacks.site_linkLINK
repacks.donateHEART
repacks.upcomingCALENDAR
repacks.refreshSYNC
repacks.discordCHAT
repacks.tab_fitgirlGAME
repacks.tab_gogGAME
repacks.tab_tbhbSEARCH
repacks.browse_folderFOLDER
Badges5 slots
SlotDefault Fluent icon
badge.pink_pawHEART
badge.hypervisorIOT
badge.switchGAME
badge.ns2GAME
badge.ps3GAME
Music31 slots
SlotDefault Fluent icon
music.lyrics_backRETURN
music.lyrics_alignALIGNMENT
music.lyrics_font_sizeFONT_SIZE
music.card_playPLAY
music.card_downloadDOWNLOAD
music.card_add_to_playlistADD_TO
music.card_moreMORE
music.bar_shuffleROTATE
music.bar_playPLAY
music.bar_pausePAUSE
music.bar_repeatSYNC
music.bar_lyricsLABEL
music.bar_volumeVOLUME
music.bar_muteMUTE
music.album_fallbackALBUM
music.row_playPLAY
music.row_downloadDOWNLOAD
music.row_removeDELETE
music.playlists_headerMENU
music.playlist_newADD
music.playlist_detail_backRETURN
music.playlist_play_allPLAY
music.playlist_download_allDOWNLOAD
music.playlist_renameEDIT
music.playlist_deleteDELETE
music.playlist_chevronRIGHT_ARROW
music.search_filtersFILTER
music.search_playlistsMENU
music.search_cancelCLOSE
music.search_prev_pageLEFT_ARROW
music.search_next_pageRIGHT_ARROW
Books2 slots
SlotDefault Fluent icon
books.detail_backRETURN
books.chapter_downloadDOWNLOAD
TBHB search10 slots
SlotDefault Fluent icon
tbhb.results_prev_pageLEFT_ARROW
tbhb.results_next_pageRIGHT_ARROW
tbhb.detail_backRETURN
tbhb.stat_categoryTAG
tbhb.stat_sizeDOCUMENT
tbhb.stat_seedersUP
tbhb.stat_leechersDOWN
tbhb.stat_uploaderPEOPLE
tbhb.stat_formatALBUM
tbhb.new_searchRETURN
YouTube3 slots
SlotDefault Fluent icon
yt.ffmpeg_gateDOWNLOAD
yt.empty_stateLINK
yt.downloadPLAY
TV and anime21 slots
SlotDefault Fluent icon
tv.channels_addADD
tv.channels_manageSETTING
tv.channels_filterFILTER
tv.channels_refreshSYNC
tv.channels_prevLEFT_ARROW
tv.channels_nextRIGHT_ARROW
tv.media_backLEFT_ARROW
tv.player_skip_backLEFT_ARROW
tv.player_playPLAY
tv.player_pausePAUSE
tv.player_skip_forwardRIGHT_ARROW
tv.player_volumeVOLUME
tv.player_muteMUTE
tv.player_fullscreenVIEW
tv.player_fullscreen_exitCLOSE
tv.anime_backLEFT_ARROW
tv.anime_downloadDOWNLOAD
tv.tab_moviesMOVIE
tv.tab_seriesVIDEO
tv.tab_animeVIDEO
tv.tab_channelsTILES
Settings36 slots
SlotDefault Fluent icon
settings.theme_modeBRUSH
settings.accent_colorPALETTE
settings.backgroundPHOTO
settings.background_blurFILTER
settings.background_darkenQUIET_HOURS
settings.languageLANGUAGE
settings.launch_at_startupSPEED_HIGH
settings.console_structureIOT
settings.auto_downloadMEDIA
settings.delete_torrentDELETE
settings.download_limitSPEED_HIGH
settings.upload_limitSPEED_HIGH
settings.seed_timeHISTORY
settings.on_finishPOWER_BUTTON
settings.close_to_trayMINIMIZE
settings.folder_minervaFOLDER
settings.folder_repacksFOLDER
settings.folder_musicFOLDER
settings.folder_mangaDOCUMENT
settings.folder_youtubeFOLDER
settings.folder_animeVIDEO
settings.folder_tbhbFOLDER
settings.tab_mangaDICTIONARY
settings.notify_downloadRINGER
settings.sfx_volumeVOLUME
settings.ambiance_volumeMUSIC
settings.external_clientSEND
settings.make_defaultRINGER
settings.repair_associationsSYNC
settings.admin_modeDEVELOPER_TOOLS
settings.show_consoleCODE
settings.log_to_fileSAVE
settings.software_updatesSYNC
settings.theme_makerBRUSH
settings.clear_cacheBROOM
settings.wipe_allDELETE
About3 slots
SlotDefault Fluent icon
about.githubGITHUB
about.discordCHAT
about.thanksHEART
App chrome4 slots
SlotDefault Fluent icon
app.donate_heartHEART
app.discord_chipCHAT
app.sync_prompt_infoINFO
app.sync_prompt_closeCLOSE

QSS, rules and layout tokens

For anything the palette cannot express you can write Qt stylesheet, three ways. All are concatenated into one app-wide stylesheet and can use @role and $layout tokens, which are substituted before Qt sees them. Unknown tokens are left as written:

  • a theme.qss file in the theme folder (first 256 KB),
  • a "qss" string in theme.json,
  • structured rules.
theme.json
"rules": [
  { "selector": "PrimaryPushButton", "state": ":hover", "css": "border-radius: 999px;" },
  { "selector": "#settingsPage CardWidget", "css": "background-color: @card_hover;" }
]

Selectors support #objectName, ClassName (subclasses match) and a two-part Ancestor Class. Why does this exist when app-level QSS is already there? Because widget-level stylesheets beat qfluentwidgets' own, which app-level QSS cannot. Rules are therefore also stamped onto matching live widgets after each theme apply, behind a hidden marker property, so they reliably win.

Layout tokens

Override any of these under "layout" (values are strings; unknown keys are ignored):

card_padding 12px 16pxcard_radius 10pxdialog_radius 12px
input_padding 7px 10pxinput_radius 6pxinput_border_width 1px
btn_padding 7px 16pxbtn_radius 6pxinput_border_width_focus 2px
group_title_pad_top 8pxgroup_title_pad_bottom 4px
theme.json
"layout": {
  "card_radius": "14px",
  "btn_radius": "8px"
}

Fonts and sounds

font_paths are font files relative to the theme folder, registered once each; font_families names additional installed families. Registered files come first in the resulting preference list, followed by your families, then the app's fallbacks.

theme.json
"font_paths": ["assets/Inter.ttf"],
"font_families": ["Segoe UI"],
"sfx": {
  "click": "assets/click.wav",
  "hover": "assets/hover.wav",
  "navigate": "assets/nav.wav",
  "ambiance": "assets/rain.ogg",
  "popout_info": "assets/info.wav",
  "popout_success": "assets/success.wav",
  "popout_warning": "assets/warn.wav",
  "popout_error": "assets/err.wav"
}

Allowed sfx keys are exactly: hover, click, navigate, ambiance, popout_info, popout_success, popout_warning and popout_error. The four popout_* sounds play when an InfoBar appears, chosen by severity. Missing files are dropped silently. Ambiance is a looping bed that only runs while media is actually playing.

Theme Maker

Open it from Settings or with Ctrl+Shift+T. Ctrl+Shift+P starts element picking anywhere in the app.

  • Element: pick any widget, choose a selector (object name, class, or ancestor + class) and a state, then edit colors, shape, text and size. This writes rules.
  • Colours: the 56 roles, grouped and searchable, with root recommendations and live swatches.
  • Icons: all 178 slots with search and defaults.
  • Backdrop: background type, image or shader, blur, darken, scope, FPS and anti-aliasing.
  • Title bar: live-validated JSON for the chrome DSL.
  • Fonts: families and font files, plus layout tokens.
  • SFX: one row per sound key, with file pickers and a test playback.
  • Code: raw QSS and the generated theme.json.

Full undo/redo (Ctrl+Z / Ctrl+Y or Ctrl+Shift+Z), a compare toggle against the original theme, and an auto-saved draft (_draft.json, written 800 ms after the last edit) that resumes after a crash. The live preview uses a draft id, so the saved theme on disk is untouched until you press Save.

Save (Ctrl+S) copies every external file into assets/, rewrites paths to relative, writes theme.json and activates the theme. Export zips the folder; Import unzips a package, which must contain theme.json and must not contain unsafe paths. Open saved edits an existing theme; New starts from the current palette. Closing without saving restores your previous theme.

Sharing theme packs

A theme pack is the theme folder zipped at its root, so the archive contains theme.json directly rather than a nested folder. Export from Theme Maker produces exactly that. To install a pack someone sent you, import it through Theme Maker; the archive is extracted into the themes directory under a slug of the file name.

Because a pack can carry images, fonts, shaders, sounds, QSS and icon artwork, it is code-adjacent: only import packs you trust. The importer rejects absolute, drive-qualified and parent-traversal paths, but it does not scan assets for anything else. Theme packs never include your settings, debrid tokens or download history.

Per-user overrides

Users can recolor on top of any theme without editing it. These live as _font_colors.json, _tr_colors.json and _icon_overrides.json in the themes directory, which is why _-prefixed folders are reserved. Text and icon color resolution runs: per-label override, then per-role override, then the theme's palette. A user icon override beats a theme's icons entry.

  • _font_colors.json maps a text or icon role to a color, for every widget using that role.
  • _tr_colors.json has separate text and icon tables keyed by translation id, for one label or button.
  • _icon_overrides.json maps an icon slot to an image, with the same path rules as a theme's icons.

Only text and icon roles can be overridden this way, not surfaces. The Theme Maker's compare toggle ignores these overrides, so you see the theme itself rather than your local tweaks.

Theme performance

A theme is data, not code, but it still decides how much work the app does. The expensive parts are animated backgrounds, large bitmap assets and broad widget rules. The palette itself is cheap: 56 role expressions resolve once per apply, and the result is cached by a theme signature.

What is already cheap

  • Palette resolution. A few dozen string expressions resolve in microseconds. Re-applying an unchanged palette bumps no version and rebuilds nothing.
  • QSS builders. Generated stylesheets are cached per theme signature and per surface. Returning to a theme you used before reuses the sheet.
  • Icons. Tinted icons pass through a 256-entry LRU cache, and painted navigation icons have a second cache. Reusing the same slot or Fluent name is effectively free.
  • Window glass. Frame-mode chrome is pre-rendered into a pixmap and reused until the window size or theme changes.
  • Rules. Live-widget rule stamping only runs when the theme actually defines rules or widget icons. A palette-only theme never pays for a widget scan.

Animated backgrounds

Shader backgrounds are the largest optional cost. fps defaults to 0, which means "follow the display refresh rate". On a 144 Hz panel that is up to 144 full-window repaints per second; on battery, cap it explicitly:

theme.json
"background": {
  "type": "shader",
  "file": "assets/waves.frag",
  "fps": 30,
  "aa": 0,
  "scope": "content"
}
  • fps: 30 is enough for slow ambient motion and roughly halves the paint work of 60 FPS. fps: 60 is a good compromise for faster motion.
  • aa: 0 is the cheapest anti-aliasing mode. Use 2 when edges shimmer, and reserve 4 or 8 for still showcases.
  • scope: "content" paints less area than "client", and "window" paints the most.
  • The shader pauses when the window is minimized or PiraChest is not the active app. It cannot pause for a hidden tab inside the window, so prefer a still background if you leave PiraChest visible on a low-power machine.

Image and GIF backgrounds

Images are scaled and composited on every resize and repaint. GIFs decode frame by frame, and video backgrounds keep decoding while they play. Animated media pauses when PiraChest is minimized or in the background. Keep the source close to the size you actually display, and avoid 4K animated GIFs:

  • Export a 1920×1080 or smaller WebP/JPEG. A 4K PNG costs memory even when it is downscaled.
  • Prefer WebP or JPEG for stills, and a short WebP animation or shader for motion. GIF is the most expensive animated format and has the worst quality per byte.
  • Blur and darken are extra full-surface passes. Use the lowest values that keep text readable.
  • A background is decoration, not a second copy of the wallpaper. One image reused across scopes is cheaper than several large files.

Icon artwork

Slot images are loaded and cropped once per size, then cached. Supply roughly the displayed size instead of a 2048px master:

  • 64–256 px square PNG/WebP is enough for the 16–48 px slots used by the app and title bar.
  • Keep transparency; crop: true removes empty margins and makes small icons legible.
  • Set crop: false only when the artwork's padding is intentional.
  • Branded Repacks icons are drawn untinted. Do not supply a dark-only logo that disappears on light themes.

QSS and rules

Every structured rule is matched against live widgets on apply, and matched rules are stamped onto each widget's stylesheet. A handful of targeted rules is cheap; hundreds of broad class selectors are not.

  • Prefer an object name (#detailsPage) or an ancestor plus class (#settingsPage CardWidget) over a bare class name.
  • Keep theme.qss focused. It is capped at 256 KB, but a smaller sheet is faster to parse and easier to reason about.
  • Do not restate fonts, colors or radii that the palette already provides. Change the role or layout token instead.
  • Heavy effects such as large box-shadow or blur in QSS are repainted with the widget; use them on a few focal elements, not every row.

A quick budget

ChoiceGood defaultWhy
Shader FPS30 on laptops, 60 on desktopCuts continuous repaints without visible stutter in ambient motion.
Shader AA0, then 2 if neededHigher sample counts multiply fragment work.
Background scopecontentLeaves the sidebar and chrome out of the animated surface.
Still background≤1920×1080 WebP/JPEGLower decode cost and memory than a 4K PNG or GIF.
Icon masters64–256 pxEnough detail for the rendered sizes; faster to crop and tint.
Structured rulesTargeted selectors, a few dozen at mostEach rule is matched and stamped onto matching live widgets.

How it reaches the screen

  1. Resolve. The manager resolves role expressions into a flat palette, enforces contrast, and bumps a version counter only when the palette, layout, preset or custom QSS really changed.
  2. Render QSS. Builders for base text, settings pages, dialogs, cards and scroll areas fill @/$ templates and cache by a signature of the current theme, so flipping back to a previous theme costs almost nothing.
  3. Refresh widgets. A widget calls register_theme_refresh(widget, callback) once; the callback runs immediately and again on every real theme change. Hidden widgets are marked stale and catch up when shown. Destroyed widgets drop out automatically.
  4. Chrome. A WindowChrome object resolves the title bar spec once per apply into ready-made colors, brushes and fonts, then paints from that cache. Frame-mode glass is pre-rendered into a pixmap and reused until size or theme changes. Sidebar items are painted by a patched navigation button that draws only icon and label; the sliding pill is the sole selection indicator.
  5. Rules and widget icons. Finally, structured rules and widget icons are stamped onto matching live widgets.

During a switch, visible top-level windows have updates frozen and thawed afterward so users never see a half-restyled window. Dialogs and shader-background windows are exempt.

Hot reload: while a folder theme is active, edits to its folder, theme.json, theme.qss or shader file are picked up after a 250 ms debounce and re-applied without a restart.

Cost control: tinted icons go through a small LRU cache, painted nav icons through another, QSS templates are cached per theme signature, and window glass is cached as a pixmap. A theme switch rebuilds only what changed; switching back to a theme is close to free.

Debugging checklist

  • Theme missing from the list? Check for a built-in id collision, invalid JSON, or a folder name starting with _ or .. Errors are logged as "theme ... skipped".
  • Hot-pink areas? A circular @ reference or a role name typo. Check warnings for undefined role / circular reference.
  • Color looks wrong with alpha()/mix()? Nested calls and rgba() inside arguments do not parse; use hex or @role.
  • Your color came back different? Contrast enforcement moved a text or icon role to meet its target. Check the table above, then raise the color deliberately if you want a different result.
  • Background not showing? The file path did not resolve inside the theme folder. Use assets/name.ext.
  • Accent ignored? locked_accent is on. If it is off, the five accent-linked roles are always overwritten by the user accent.
  • Parent not found? The parent folder sorts after the child. Rename so it loads first.
  • Rule not winning? The selector did not match a live widget. Rules stamp onto instances; an object name that only exists after navigation is matched when the theme is next applied or the page is created.
  • No backdrop or glass on Linux or macOS? Window materials are Windows-only; backdrop falls back to none there.
  • Image icon looks cropped or tiny? Set "crop": false, or supply artwork with the intended padding. Images are never tinted.

For legal and educational purposes only. This application does not host, distribute, or endorse copyrighted content. It merely provides tools to access third-party sources. You are solely responsible for how you use this software and for complying with all applicable laws. If you misuse it, that's your responsibility, Fuck you. Logo by spicysaltysparty.