Artist Packs

Artist Packs

An artist pack replaces an artist's page in Orchard with a custom one: custom artwork, a different layout, a theme, search aliases, album previews, and page effects.

Two kinds exist. Official packs are curated and distributed through Orchard's artist-packs worker. User packs are files you install yourself.

Manage them in Settings → Artist Packs. Custom artist pages can be switched off globally in Settings → Appearance without uninstalling anything.

Installing a user pack

Settings → Artist Packs → Import, then pick a .orchardpack, .zip, or .zst file.

Installed packs go into Orchard's per-user data directory under custom-artist-packs/user/<artistId>/. Official pack content lands in custom-artist-packs/official/pack/.

Archive format

A user pack is an archive (zip, or zstd-compressed) with artist.json at its root.

Allowed root files: artist.json, manifest.json, style.css.

Allowed asset extensions: .png, .webp, .jpg, .jpeg, .mp3.

Maximum archive size: 50 MB.

Anything else is refused. Paths are validated so that no entry can write outside the pack's own directory, and the installer rejects the archive rather than partially extracting it.

artist.json

{
  "schema": 1,
  "artistId": "UCR28YDxjDE3ogQROaNdnRbQ",
  "artistName": "YoungBoy Never Broke Again",
  "displayName": "Lil Top",
  "layout": "slime",
  "assets": {
    "thumbnail": "assets/profile.png",
    "profile": "assets/profile.png"
  },
  "search": {
    "canonicalQuery": "YoungBoy Never Broke Again",
    "aliases": ["Lil Top", "NBA YoungBoy"]
  },
  "banner": {
    "type": "albumWall",
    "sources": ["album", "single", "ep"],
    "limit": 12
  },
  "idlePreview": {
    "tracks": [
      {
        "id": "91CGXp4RIRw",
        "title": "Big Truck",
        "artist": "YoungBoy Never Broke Again",
        "album": "Don't Try This At Home"
      }
    ]
  },
  "features": {
    "hoverPreviews": true,
    "animatedArtwork": true,
    "highlightWords": ["Kentrell DeSean Gaulden"]
  },
  "theme": {
    "cssVariables": {
      "--custom-artist-accent": "#39ff14",
      "--custom-artist-accent-dark": "#043d12",
      "--custom-artist-ink": "#020503",
      "--custom-artist-ink-soft": "#0a1309"
    }
  },
  "previews": {
    "MPREb_hQzZRSf9l9i": {
      "label": "Slime Cry - Bruce Wayne",
      "videoId": "2wI4_-aMSk0",
      "start": 83,
      "duration": 30
    }
  }
}

Fields

Field	Meaning
schema	Format version. Currently 1.
artistId	YouTube channel id the pack binds to. Required and validated.
artistName	The artist's canonical name.
displayName	What Orchard shows instead, if different.
layout	Named layout the pack uses.
assets	Relative paths to bundled images, notably thumbnail and profile.
search.canonicalQuery	What an alias match should actually search for.
search.aliases	Alternate names that resolve to this artist.
banner	Banner treatment. albumWall builds a wall from releases, filtered by sources and capped by limit.
idlePreview.tracks	Tracks the page can preview while idle.
features.hoverPreviews	Play a preview when hovering a release.
features.animatedArtwork	Prefer animated cover art.
features.highlightWords	Words the page styles specially.
theme.cssVariables	CSS custom properties the page is themed with.
previews	Per-album preview clips, keyed by browse id, with videoId, start, and duration in seconds.

style.css

Optional. Scoped to the artist page. Use it with theme.cssVariables rather than hardcoding colors, so the page still responds to Orchard's accent and theme settings.

Search aliases

Aliases are how a nickname finds the right artist. When a search matches an alias case-insensitively, Orchard rewrites the query to the pack's canonicalQuery and keeps the alias list around for display. This is what makes searching "Lil Top" reach YoungBoy Never Broke Again.

Official packs

Official pack content lives in workers/artist-packs/content/, organized as artists/<channelId>/artist.json plus shared assets and shared CSS. Build one locally with:

npm run build:artist-pack

The build script's manifest is scripts/official-artist-pack-content.mjs.

Security notes

Packs are content, and Orchard treats them that way. There is no JavaScript in a pack. CSS is scoped, file types are allow-listed, archive size is capped, and extraction paths are constrained to the pack's own directory. Install packs from sources you trust regardless, since a pack can still put arbitrary images and audio in front of you.

Source map

Path	Role
electron/integrations/artistPackService.js	Validation, extraction, installation
src/app/appearance/customArtistPacks.js	Pack resolution and alias matching
src/app/appearance/customArtistProfileArtwork.js	Profile artwork
src/app/appearance/customArtistIdlePreviewActions.js	Idle previews
src/custom-artists/	Renderer-side pack layouts
scripts/build-official-artist-pack.mjs	Official pack build
workers/artist-packs/	Official pack distribution