Overlays

Overlays let Maintainerr draw collection-specific artwork onto media so it is easier to see that an item is queued for action.

note

Overlays are intended for supported media servers in this release line.

Where to find it

Maintainerr exposes three overlay screens:

• Overlays navigation entry
• Settings tab at /overlays/settings
• Existing Templates and New Template tabs under /overlays/templates

Overlay settings

The Settings tab contains the global controls for overlay processing.

• Enable overlays is the master switch.
• Run Now starts overlay processing immediately.
• Reset All Overlays reverts posters that Maintainerr has changed.

Overlay settings are stored globally, while template selection is stored per collection.

Use Reset All Overlays carefully. It is intended to undo Maintainerr-managed overlay artwork across collections.

Templates

Templates define how Maintainerr renders overlays.

• Poster templates are used for movie, show, and season collections.
• Title card templates are used for episode collections.

Template management supports:

• creating new templates
• editing custom templates
• duplicating preset templates before changing them
• setting a default template for each mode
• importing and exporting templates as JSON

Maintainerr seeds preset templates automatically on first run. Presets are meant to be a starting point, not something you edit in place.

Preset templates cannot be edited directly. Duplicate them first, then edit the duplicate.

Template editor

The editor lets you design overlay elements on top of a preview image.

• For poster templates, Maintainerr can load a random item from a media server library section.
• For title card templates, Maintainerr can load a random episode from a media server library section.
• You can upload custom fonts in .ttf, .otf, or .woff format.
• Template previews are rendered server-side against real media artwork.

If you leave a collection without a specific overlay template selected, Maintainerr uses the current default template for that mode.

How template selection works

When Maintainerr processes an overlay-enabled collection, template resolution is:

1. the collection-specific template, if one is selected and still exists
2. the default template for that mode (poster or titlecard)
3. skip overlay processing for that collection if no template can be resolved

Episode collections use titlecard mode. Other supported collection types use poster mode.

Enabling overlays on a collection

Overlay controls also appear in the rule or collection form.

• Enable overlays turns overlays on for that collection.
• Overlay template optionally selects a specific template.
• Leaving Overlay template empty uses the default poster or title card template.

This setting is stored on the collection, so existing collections can be updated later without rebuilding your whole setup.

Processing behavior

Overlay processing only applies when all of these are true:

• overlays are enabled globally
• a supported media server is configured
• the collection has overlays enabled
• the collection has Take action after days set
• a matching template can be resolved

Maintainerr re-renders overlays when the visible days-left value changes, and it can revert overlay artwork for a single collection or for all collections.

Upgrade notes

Recent Maintainerr releases add overlay tables and new collection fields to the database. On first startup after upgrading, allow database migration to finish before opening the Overlays pages.