Kometa dynamic collections

Kometa Dynamic Collections

Own dynamic_collections: definitions inside collection files.

Goal

• Produce valid-looking dynamic collection definitions.
• Explain key vocabulary, type/data requirements, and naming controls.
• Keep dynamic logic inside collection files.

Output Contract

Always return:

1. YAML for a collection file containing dynamic_collections:
2. 2-5 short bullets on type, naming, and generation behavior
3. Caveats for data, templates, provider dependencies, and over-generation risk

File Boundary

Belongs here:

• dynamic_collections:
• dynamic type
• optional data
• exclude, include, addons
• title_format, remove_prefix, remove_suffix, key_name_override, title_override
• template
• dynamic template_variables

Does not belong here:

• config.yml root wiring
• standalone metadata edits
• plain one-off collections unless the user truly wants fan-out generation

Mental Model

• one dynamic definition creates many normal collections
• type determines where keys come from
• data is only used for types that need extra input
• each generated collection uses either the built-in default template for that type or a custom template

Key Vocabulary

• key: raw dynamic value, often an ID or source value
• key_name: display name after naming cleanup
• title_format: how the final collection title is rendered

If the user is confused:

• explain key as the source
• explain key_name as the cleaned display name

Decision Rules

Use dynamic collections when:

• the user wants one rule to generate many collections
• the user wants per-genre, per-country, per-network, per-decade, or per-person collections
• the user wants awards or user-list fan-out without hand-writing each collection

Do not use dynamic collections when:

• the user wants one or two explicit collections only
• the user does not actually need fan-out

High-Value Types

Good default choices:

• tmdb_collection
  • franchise collections from items already in the library
• tmdb_popular_people
  • people collections from TMDb popular people
• genre, country, network, decade, year
  • classic library-driven fan-out
• imdb_awards
  • year-based awards fan-out with event_id, starting, and ending
• letterboxd_user_lists
  • one collection per Letterboxd user list
• audio_language, subtitle_language, edition, resolution
  • library-derived fan-out from real Plex traits

Data Rules

• some types do not use data
• some types require data, often as a number or dictionary
• if a type relies on external provider state, call that dependency out

Examples:

• tmdb_popular_people
  • data: 10
• imdb_awards
  • dictionary with event_id, starting, ending, optional increment

Naming Rules

Best levers:

• title_format
• remove_prefix
• remove_suffix
• key_name_override
• title_override

Use addons when:

• multiple source keys should merge into one parent collection

Use exclude or include when:

• the user wants strict control over what gets generated

Template Rules

• each dynamic type has a default template
• switch to a custom template when the user needs different builders, sort logic, or metadata behavior
• template_variables can be set per key, and default can act as a fallback key

Do not confuse this with defaults-style template_variables.

Embedded Examples

TMDb collections

dynamic_collections:
  TMDb Collections:
    type: tmdb_collection
    remove_suffix: Collection

TMDb popular people

dynamic_collections:
  TMDb Popular People:
    type: tmdb_popular_people
    data: 10

IMDb awards

dynamic_collections:
  Oscar Awards Lists:
    type: imdb_awards
    data:
      event_id: ev0000003
      starting: latest-15
      ending: latest

Country naming cleanup

dynamic_collections:
  Countries:
    type: country
    title_format: <<key_name>> Cinema
    key_name_override:
      France: French

Audio language fan-out

dynamic_collections:
  Audio Languages:
    type: audio_language
    title_format: Top <<key_name>> Movies

Edition fan-out

dynamic_collections:
  Editions:
    type: edition
    title_format: <<key_name>> Cuts

Addons merge

dynamic_collections:
  Networks:
    type: network
    addons:
      MTV:
        - MTV2
        - MTV3
        - MTV (UK)

Local References

Read only what matches the request:

• references/cards/files--dynamic.md
• references/cards/dynamic--core.md
• references/cards/dynamic--types.md
• references/cards/dynamic--library-derived.md
• references/cards/templates--core.md

Use these tiny examples first:

• examples/gold/gold-dynamic-region.yml
• examples/gold/gold-dynamic-tmdb-people.yml
• examples/gold/gold-dynamic-imdb-awards.yml
• examples/gold/gold-dynamic-audio-languages.yml
• examples/gold/gold-dynamic-editions.yml
• examples/gold/gold-template-external-actor.yml

Review Checklist

• is this inside a collection file?
• does the chosen type actually fit the request?
• does the type require data, and if so is it present?
• are naming overrides under the dynamic entry instead of somewhere random?
• does the user really need fan-out generation?

Stopping Condition

Finish when:

• the dynamic collection shape is correct
• type and data requirements are explicit
• naming and generation behavior are clear