Kometa custom overlays

Kometa Custom Overlays

Own standalone overlay files.

Goal

• Produce valid-looking overlays: files with correct top-level structure.
• Keep whole-library overlay behavior explicit.
• Warn about runtime, image bloat, and art-source pitfalls.

Output Contract

Always return:

1. YAML for an overlay file
2. 2-5 short bullets on targeting, placement, and stacking behavior
3. Caveats for scheduling, reapply_overlays, image bloat, and required linked config

File Boundary

Belongs here:

• overlays:
• queues:
• overlay-local templates
• external_templates
• builders such as plex_search, plex_all, and overlay targeting logic
• overlay style keys such as alignments, offsets, colors, fonts, and weights

Does not belong here:

• overlay_files: references from config.yml
• top-level connectors
• collection-only builder guidance

Hard Rules

• overlays: appears once at top level
• overlays are computed at the whole-library level
• overlays that should coexist must run in the same Kometa run
• do not recommend individual overlay-file schedules; use library schedule_overlays
• reapply_overlays: true should be discouraged unless there is a specific reason

Runtime Rules

• all overlay coordinates assume standard poster or background sizes
• transparent PNG-style image assumptions are safest
• changing art directly in Plex after overlays are applied can confuse overlay state
• asset directories are the safest clean-art source of truth
• remove_overlays: true is cleanup behavior, not a normal steady-state recommendation

Clean Art Workflow

• with asset art present, the asset becomes Kometa's clean-art source of truth
• without asset art, Kometa relies on backup posters under config/overlays/LIBRARY_NAME Original Posters/
• safest art-swap workflow: add new poster to the asset directory, keep prioritize_assets: true, and run overlays normally
• reapply_overlays: true should be temporary and explicit
• mass_poster_update can reset art before overlays and is a common image-bloat trap
• if Plex art was changed manually, removing the Overlay label from the item can help Kometa treat it as clean art again

Decision Rules

Use this skill when:

• the user wants raw overlays: YAML
• the user wants custom text or image overlays
• the user wants weighted or stacked overlay behavior
• the user wants season or episode overlays via builder_level

Do not use this skill when:

• the user only needs a built-in overlay default call

Placement Rules

• put style attributes under overlay: when defining the overlay body
• use horizontal_align, vertical_align, horizontal_offset, and vertical_offset together
• use queue and weight concepts when multiple overlays compete for the same space

Targeting Rules

• plex_all: true is valid for broad overlays
• plex_search is best for targeted overlays and nested logic
• if using season or episode overlays, call out builder_level

Embedded Examples

Text overlay

overlays:
  year:
    overlay:
      name: text(<<originally_available[%Y]>>)
      horizontal_offset: 45
      vertical_offset: 45
      horizontal_align: left
      vertical_align: top
      font_size: 63
      font_color: "#FFFFFF"
      back_color: "#00000099"
      back_radius: 5
      back_padding: 20
    plex_all: true

Targeted overlay

overlays:
  directplay:
    overlay:
      name: text(Direct Play)
      horizontal_offset: 0
      horizontal_align: center
      vertical_offset: 150
      vertical_align: bottom
      font_size: 63
      font_color: "#FFFFFF"
      back_color: "#00000099"
      back_radius: 30
      back_padding: 30
    plex_search:
      all:
        resolution: 4K

Season-level default-style targeting idea

overlays:
  season-hdr:
    builder_level: season
    overlay:
      name: text(HDR)
      horizontal_align: right
      vertical_align: top
    plex_search:
      all:
        hdr: true

Queue-safe badge stack

queues:
  left_badges:
    horizontal_align: left
    vertical_align: top

overlays:
  hdr:
    queue: left_badges
    weight: 100
    overlay:
      name: text(HDR)
      back_color: "#00000099"
    plex_search:
      all:
        hdr: true

Local References

Read only what matches the request:

• references/cards/files--overlays.md
• references/cards/overlays--core.md
• references/cards/defaults--overlays.md
• references/cards/templates--core.md
• references/cards/kometa--guides--overlays.md
• references/cards/overlays--clean-art.md
• references/cards/kometa--guides--assets.md

Use these examples first:

• examples/gold/gold-custom-year-overlay.yml
• examples/gold/gold-custom-resolution-overlay.yml
• examples/gold/gold-default-resolution-call.yml
• examples/gold/gold-asset-first-overlay-config.yml
• examples/gold/gold-asset-directory-multi-root.yml
• examples/gold/gold-remove-overlay-label-season.yml
• examples/gold/gold-remove-overlay-label-episode.yml

Review Checklist

• does the file start with overlays:?
• are placement keys nested under overlay: where needed?
• is the selector under the overlay entry, not at top level?
• is the user accidentally asking for a default overlay reference instead of a custom overlay file?
• does the answer imply unsafe overlay scheduling behavior?
• does the advice protect clean art or does it casually recommend reapply_overlays?
• does the wider workflow need asset-directory guidance even if the output file itself is only overlays:?
• if the user is really fixing bad clean art, should this be routed to a small repair collection instead of more overlay YAML?

Stopping Condition

Finish when:

• the file is clearly an overlay file
• placement and targeting are understandable
• the user has been warned about whole-library overlay behavior