Kometa metadata files

Kometa Metadata Files

Own standalone metadata: files for item edits.

Goal

• Produce valid-looking metadata files for movies, shows, seasons, episodes, artists, albums, and tracks.
• Use the safest matching strategy available.
• Keep builders and collection logic out of metadata files.

Output Contract

Always return:

1. YAML for a metadata file
2. 2-5 short bullets on matching and edit scope
3. Caveats for ambiguity, IDs, and artwork sources

File Boundary

Belongs here:

• metadata:
• match:
• text fields like title, sort_title, summary, tagline
• ratings, labels, dates, language fields
• poster/background fields
• nested seasons: / episodes: or albums: / tracks:

Does not belong here:

• collections:
• playlists:
• builder keys such as tmdb_list, trakt_list, plex_search, tmdb_discover

Matching Rules

Use this order of preference:

• mapping_id when the user has a stable TMDb, TVDb, or IMDb identifier
• match.title plus year when titles are ambiguous
• exact entry name only when ambiguity risk is low

Movie-specific matching can use:

• mapping_id
• title
• year
• edition
• edition_contains
• blank_edition

Show-specific matching can use:

• mapping_id
• title
• year

Safety rule:

• if the user gives a common title with no year or ID, say matching is unsafe
• if the title is only a number like 9 or 24, quote it when it is a title rather than an ID

Hierarchy Rules

For shows:

• show edits live at the main item level
• seasons: nests under the show
• episodes: nests under a specific season

For music:

• artist edits live at the main item level
• albums: nests under the artist
• tracks: nests under the album

Do not flatten these levels.

Special Cases

• use tmdb_show when a movie-library item should map to TMDb show metadata
• use lists under match.title when Plex naming varies across versions
• use sort_title when the real ask is ordering, not display title
• edition-specific movie matching can use edition, edition_contains, or blank_edition
• if the user really wants a set of items, route to collections instead of metadata

Advanced Metadata Fields

High-value direct item edits:

• edition
• metadata_language
• audio_language
• subtitle_language
• use_original_title
• episode_ordering
• episode_sorting
• keep_episodes
• season_display
• credits_detection

Practical rules:

• show policy fields like keep_episodes or episode_ordering belong at the show level
• season-scoped language preferences belong in nested season blocks
• direct metadata edits change existing items; they do not select sets of items

Common Mistakes

• using collections: as the top-level key for metadata edits
• pasting season edits at top level instead of under a show
• putting builder keys into metadata files
• relying on a bare title when multiple versions exist

Embedded Examples

Movie metadata with explicit match

metadata:
  The Matrix:
    match:
      title: The Matrix
      year: 1999
    summary: A hacker discovers the world is a simulation.
    label:
      - Sci-Fi Essentials
    audience_rating: 9.0

Show with seasons and episode edit

metadata:
  "Avatar: The Last Airbender":
    sort_title: Avatar 01
    seasons:
      1:
        title: "Book One: Water"
      3:
        episodes:
          21:
            summary: The Epic Series Final of Avatar The Last Airbender

Ambiguous title with alternate names and tmdb_show

metadata:
  "Halo 4: Forward Unto Dawn":
    match:
      title:
        - Halo 4: Forward Unto Dawn
        - Halo 4 Forward Unto Dawn
    tmdb_show: 56295
    content_rating: R

Edition-specific movie match

metadata:
  Star Wars 4K77:
    match:
      title: Star Wars
      edition_contains: 4K77
    summary: Fan preservation edition metadata

Show language preferences

metadata:
  Dark:
    metadata_language: de-DE
    use_original_title: yes
    seasons:
      1:
        audio_language: de-DE
        subtitle_language: en-US

Local References

Read only what matches the request:

• references/cards/files--metadata.md
• references/cards/metadata--matching.md
• references/cards/metadata--hierarchy.md
• references/cards/metadata--advanced-fields.md

Use these tiny examples first:

• examples/gold/gold-metadata-match.yml
• examples/gold/gold-metadata-show-seasons.yml
• examples/gold/gold-metadata-mapping-id.yml
• examples/gold/gold-metadata-edition-match.yml
• examples/gold/gold-metadata-show-language.yml

Review Checklist

• is the top-level key metadata:?
• is matching explicit enough for the title given?
• are season or episode edits nested under the correct show?
• are album or track edits nested under the correct artist and album?
• is the user editing existing items rather than asking for a collection?

Stopping Condition

Finish when:

• the metadata file shape is correct
• the match strategy is explicit and safe enough
• nested edits are placed at the right level