THEME YOUR LIBRARY

Preludarr

Theme songs for your media library. Preludarr finds the opening or theme song of each anime, TV show and movie in your library and saves it as theme.mp3 in the title's folder, where Plex, Jellyfin and Emby play it.

Status: stable. Use ghcr.io/shedman214/preludarr:latest for the current stable release. See the release notes for changes. Make a backup (System → Backup & Restore) before each update.

Library	Theme review
Dashboard	Settings → Media Management
Collections	Settings → Appearance

_{Screenshots from a demo library of empty folders and a test Plex server; no real media or posters.}

Features

Available now

• Anime TV and anime movies: openings and endings from AnimeThemes, matched by title and year through AniList and the AniDB title list. Preview every version, then install the one you choose.
• TV shows and movies: suggestions from Plex TV Themes and ThemerrDB. Optional YouTube search (your own API key and cookies; preview only until you install). For shows and movies it looks on the MainThemeSoundtracks channel first, which costs none of your daily searches, then searches all of YouTube.
• Library: a tab per root folder, search and filters, a Theme Queue for reviewing many titles at once, automatic installs for anime (off by default), and Library Health (folders Preludarr cannot write to, extra theme files).
• Connect (optional): Sonarr, Radarr, Plex, Jellyfin and Emby, to match titles by their ids and refresh the media server after an install. Sonarr/Radarr connections go directly to the configured server; root-folder checks allow up to 30 seconds for slower responses.
• Sign in with Plex: connect Plex without copying a token. Sign in in Plex's own window, approve Preludarr, and pick your server (local address first). Several Plex servers can be connected; one is the main server (title links, refresh after installs), and every server gets its own Collections tab. Your Plex account token is used only to list your servers and is never saved.
• Jellyfin Quick Connect: enter your Jellyfin address, then approve the code Preludarr shows in Jellyfin (profile → Quick Connect, as an administrator). Quick Connect must be turned on in Jellyfin (Dashboard → General).
• Sign in to Emby: enter your Emby address, username and password once. The password goes only to your Emby server and is not saved; Preludarr keeps the access token Emby returns.
• Collections: a theme for each movie collection, using the theme of one of its movies (the first movie by default). Instead of a movie's theme you can also use a YouTube link, your own audio file (with manual installs on), or Smart YouTube search suggestions (your API key; preview first, you choose). The Collections page has a tab per movie root folder, like the Library, and shows only collections from your root folders (others sit under "Other libraries"). A search bar finds collections by their name or their movies' names. Collections show their own artwork from Plex, Jellyfin or Emby. Plex: uploaded to the collection, and removable. Jellyfin and Emby: experimental, written into the server's own collection folder, which you map into Preludarr; those servers do not officially support collection themes, so some apps may not play them.
• Posters: your own TMDB or TVDB key enables poster lookups. New installs automatically queue and cache missing artwork after root folders are scanned; existing installs retain their background setting. Poster Recovery provides pause, progress and retry controls, with cooldowns and rate limits. Existing cached posters are kept.
• Logging: Settings → General → Logging offers Info, Debug and Trace, with rotating logs under System → Logs. Trace adds HTTP method, status and request duration; its timing entries exclude URLs, headers and request bodies. Enable Debug or Trace only while troubleshooting.
• Backups: manual and scheduled backups of the database and settings, and a guarded restore with automatic rollback.
• Language & Region: Settings → General — choose English, Spanish, French, German, Portuguese (Brazil), Japanese, Simplified Chinese, or Arabic for core navigation and common controls. Other text falls back to English. Choose short/long date formats, 12/24-hour time, a display time zone, and Today/Yesterday labels. Preferences apply to the whole instance; schedules keep using server time. An English recovery link and button help you switch back.
• Appearance: Settings → Appearance — Dark, Light or Auto (follows each device), OLED mode, six accent colours and eight immersive themes (Winamp, Terminal, Vaporwave, Y2K Cyber, Film Noir, VHS, Synthwave, Amber CRT), with a live preview. Contrast checks cover common controls across all themes. The live preview keeps its own text palette when you try another scheme.
• Safety: first-run account setup, sign-in on every page, protection against cross-site requests, a read-only API key by default, and a container that runs as a normal user.

Current limitations

• Poster lookups need your own TMDB or TVDB API key. Automatic poster processing does not enable automatic theme downloads.
• YouTube search needs your own YouTube Data API key and a cookies.txt file, and has a daily quota.
• One user account. There are no separate users or roles.
• Tested mainly on Unraid with Plex. Jellyfin and Emby connections are less tested.
• Images are published for amd64 and arm64. The arm64 build has not been tested on real ARM hardware yet.

Install

Docker Compose

services:
  preludarr:
    image: ghcr.io/shedman214/preludarr:latest
    container_name: preludarr
    restart: unless-stopped
    ports:
      - "8788:8787"            # open http://<server-ip>:8788
    environment:
      - PUID=1000              # user and group that own your media (`id youruser`)
      - PGID=1000
      - TZ=America/Chicago     # your time zone: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
    volumes:
      - ./preludarr-config:/config            # settings, database, backups
      - /path/to/tv:/media/tv_shows           # your libraries; read/write so theme.mp3 can be saved
      - /path/to/movies:/media/movies

Then run docker compose up -d.

docker run

docker run -d --name preludarr --restart unless-stopped \
  -p 8788:8787 -e PUID=1000 -e PGID=1000 -e TZ=America/Chicago \
  -v /path/to/preludarr-config:/config \
  -v /path/to/tv:/media/tv_shows \
  -v /path/to/movies:/media/movies \
  ghcr.io/shedman214/preludarr:latest

Unraid

Preludarr is available in Community Applications:

1. Open Unraid's Apps tab and search for Preludarr.
2. Select Preludarr from animeking1987's Repository and click Install.
3. Set TV shows and Movies to your shares (for example /mnt/user/tv and /mnt/user/movies), keep PUID 99 / PGID 100, and click Apply.
4. Open Preludarr's WebUI from the Docker tab and follow First start below.

Already installed? Update your existing container from the Docker tab when Unraid shows an update is ready; there is no need to reinstall it from Apps.

Manual template installation

If you prefer to add the template manually:

1. Open the Unraid terminal and run:

   wget -O /boot/config/plugins/dockerMan/templates-user/my-Preludarr.xml \
     https://raw.githubusercontent.com/shedman214/preludarr/main/templates/my-preludarr.xml
   

2. Docker → Add Container → Template: Preludarr.
3. Set TV shows and Movies to your shares (for example /mnt/user/tv and /mnt/user/movies), keep PUID 99 / PGID 100, and click Apply.

Image tags

Build it yourself

git clone https://github.com/shedman214/preludarr.git
cd preludarr
docker build -t preludarr:local .

Then use preludarr:local as the image in the examples above.

First start

1. Open the container log (Unraid: Docker → Preludarr → Logs; elsewhere docker logs preludarr). It shows a setup code such as K7QM-3XRP.
2. Open http://<server-ip>:8788, enter the code, and create your account (password: 16 characters or more).
3. Go to Settings → Media Management and add your library folders as root folders. Choose a type for each: Anime TV, Anime Movies, Shows or Movies.
4. Add a TMDB or TVDB key under Settings → Connect → Poster Providers if you want posters. On a new install, missing posters are queued automatically once roots are scanned and a key is configured. Pause processing in Poster Recovery, or use POSTER_BACKGROUND_ENABLED=false to disable it. Existing installs keep their previous setting.
5. Preludarr scans your folders. Open a title to review its themes, use the Theme Queue for many titles, or choose Automatic Themes (Settings → Media Management) to install anime themes automatically.

The setup code changes every time the container restarts, and it is only ever shown in the log.

What Preludarr changes on disk

Inside /config (Preludarr's own data): the database, settings files, logs, poster cache, backups (system_backups/), the theme recycle bin (theme-trash/) and the YouTube cookies file. On first start Preludarr changes the owner of /config and everything in it to PUID:PGID.

Inside your library folders, only these actions write anything, and only in title folders under the root folders you added:

Preludarr never deletes or renames videos or other media files.

Settings (environment variables)

Most settings live in the web interface. These optional variables are read at start-up:

Older THEMEARR_* and SPLICARR_* names of the PRELUDARR_* settings still work.

API

GET /api/v1/status and GET /api/v1/activity with the key from Settings → General in the X-Api-Key header. POST /api/v1/command/scan starts a library scan (at most once every 5 minutes) only if you allow it under Settings → General → API key & security. Requests are limited to 60 per minute.

Since 1.12 a new install's API key is read-only. An install from before 1.12 keeps the behaviour it had (the key may start scans), and that choice is saved once so it appears in Settings; a choice you saved yourself is never changed.

Troubleshooting connections and posters

• Sonarr/Radarr timeout: the address must be reachable from inside the Preludarr container. Check the port, Docker routing and the target server's firewall. A browser on another device can work even when the container cannot connect. Status checks allow 12 seconds; root-folder checks allow 30 seconds.
• Poster folder unavailable: a saved Library entry can point to an old folder name after a rename or move. Rescan the registered root, reload the Library, and retry the entry matching the current folder. Preludarr will not create a replacement folder or automatically discard saved history.
• Logs: use Debug or Trace temporarily under Settings → General → Logging. Normal logs can still contain private paths or hostnames despite credential redaction; review downloads before sharing them.

Backups and updates

• System → Backup & Restore makes backups of the database and settings (manual, or automatic on a schedule). They are stored in /config/system_backups and contain your saved API keys and tokens, so keep downloads private.
• Restore: verify a backup, confirm, then restart the container. Preludarr keeps a safety copy of your current data and puts it back automatically if the restore fails.
• Update: make a backup, then pull the new image (or change the tag) and restart. Preludarr never updates itself; System → Releases shows when a new version is out.
• Go back: use the previous version's tag. If the newer version changed your data, restore the backup you made first.

Security

• Every page needs your sign-in. Forms are protected against cross-site requests. The API key is accepted only in a header, and is read-only unless you allow scans.
• The web server limits slow and oversized requests and how many connections it handles at once.
• Do not open the port directly to the internet. For remote access, use a reverse proxy or tunnel with HTTPS and set the public address in Settings → General.
• Report vulnerabilities privately, as described in SECURITY.md. Do not use public Issues for security problems.

Preludarr has not had an independent security audit.

Contributing

See CONTRIBUTING.md. Bug reports: use the issue form and remove passwords, API keys, tokens and private paths first.

Credits and licence

Preludarr uses data from AnimeThemes, AniList, AniDB, TMDB, TheTVDB, Plex TV Themes, ThemerrDB and, optionally, YouTube. This product uses the TMDB API but is not endorsed or certified by TMDB. Preludarr is not affiliated with any of these services. Finding a song through a source does not mean you are allowed to download it; download only what you have the right to use.

Preludarr was previously named Splicarr, and before that Themearr.

Preludarr is free software: GNU General Public License, version 3 or later (GPL-3.0-or-later), with no warranty. See LICENSE, NOTICE.md and docker/THIRD_PARTY_PACKAGES.txt.