File Blocks¶

When using Kometa, the structure of each library is made using File Blocks

Example Library Structure

libraries:
  Movies:
    collection_files:
      - default: imdb

In the above example, collection_files is the type of File, which tells Kometa that the entries that follow will create/update collections and - default: is the type of Path, which Kometa that the file it is looking for is a Kometa Defaults file.

These ideas will be further outlined on this page.

Files¶

Files define the structure and format for creating Collections, Overlays, Playlists, and Metadata Edits within your libraries.

Files are modular and when properly leveraged, they not only facilitate the management of your library's collections and metadata but also serve as a crucial backup resource in case a restore is necessary.

These are the File types that can be utilized against Plex servers:

File Type	Description	Parent Attribute
Collection Files	Defines the data for building collections, allowing you to group and showcase your library in unique ways.	`collection_files`
Overlay Files	Defines the data for building overlays, allowing you to place information such as resolutions and ratings onto your posters.	`overlay_files`
Metadata Files	Defines the data for editing metadata, allowing you to find and manipulate the metadata on individual items within your library.	`metadata_files`
Playlist Files	Defines the data for building playlists, allowing you to combine media from multiple libraries and share them with users on your server.	`playlist_files`
Template Files	Defines templates in external files, allowing you to use the same templates across multiple other files.	`external_templates`

Example File Blocks (click to expand)

In this example, multiple file blocks are defined for the "TV Shows" library:

libraries:
  TV Shows:
    collection_files:
      - file: config/TVShows.yml
      - folder: config/TV Shows/
    overlay_files:
      - default: imdb
      - repo: overlays
playlist_files:
  - url: https://somewhere.com/Playlists.yml

Unlike the others, Playlist Files are not defined per-library.

Within the above example, Kometa will:

First, look within the root of the Kometa directory (also known as config/) for a collection file named TVShows.yml. If this file does not exist, Kometa will skip the entry and move to the next one in the list.
Then, look within the root of the Kometa directory (also known as config/) for a directory called TV Shows, and then load any collection files within that directory.
Then, look in the defaults folder within the local Kometa folder [or docker container] for a file called imdb.yml.
Then, look within the Custom Defined Repo for a file called overlays.yml.
Finally, load the playlist file located at https://somewhere.com/Playlists.yml

Blocks¶

Each time a file is called it's going to use what we call a "File Block". Each block must have the file location type and path and can have other attributes to add more control to that file.

Every file block under the parent attribute begins with a -.

Example Block

This example has 2 blocks each using location type - default with the path being tmdb and imdb respectively under the parent attribute collection_files.

libraries:
  Movies:
    collection_files:   # Parent Attribute
      - default: tmdb       # Block 1
      - default: imdb       # Block 2

Location Types and Paths¶

There are multiple location types that can be used to call a file. They can either be on the local system, online at an url, part of the Kometa Defaults, directly from the Kometa Community Configs repository, or from another Custom Repository.

The location types are outlined as follows:

file - Used to run a local file.¶

Used to run a file which is located within the system that Kometa is being run from.

File locations need to be accessible to Kometa at those paths; this is typically only something you need to consider when using Docker.

Example

libraries:
  Movies:
    collection_files:
      - file: config/path/to/file.yml

folder - Used to run all local files in a directory.¶

Used to run all files located in a directory which is located within the system that Kometa is being run from.

Folder locations need to be accessible to Kometa at those paths; this is typically only something you need to consider when using Docker.

Example

libraries:
  Movies:
    collection_files:
      - folder: config/path/to/folder

url - Used to run a file hosted at a URL.¶

Used to run a file hosted publicly on the internet and accessible at a URL.

This needs to point directly to the YAML file. A common error is using a gitHub link that points to the page displaying the YAML. In gitHub, for instance, click on the "Raw" button and use that link.

Example

libraries:
  Movies:
    collection_files:
      - url: https://example.com/path/to/file.yml

default - Used to run one of the built-in Kometa Defaults file.¶

Used to run a built-in Kometa Defaults file. The values you'd enter here are listed in the default usage guide.

Example

libraries:
  Movies:
    collection_files:
      - default: oscars

git - Used to run a file hosted on the Kometa Community Configs repository.¶

Used to run a file hosted on the Kometa User Configs repository.

Note that you enter the bits of the items path relative to the top level of the repo [meisnate12/People] and you don't need the .yml extension.

Example

libraries:
  Movies:
    collection_files:
      - git: meisnate12/People # this links to https://github.com/Kometa-Team/Community-Configs/blob/master/meisnate12/People.yml

repo - Used to run a file hosted on a custom repository.¶

Used to run a file which is hosted on a repo specified by the user with the custom_repo Setting Attribute.

Note that as with git you enter the bits of the items path relative to repo [meisnate12/People] and you don't need the .yml extension.

Example

This is assuming the custom_repo setting is https://github.com/Kometa-Team/Community-Configs/tree/master/meisnate12.

libraries:
  Movies:
    collection_files:
      - repo: People

Other Block Attributes¶

You can have some control of the files from inside your Configuration file by using these block attributes.

template_variables - Used to define Custom Template Variables for a file.¶

Passes all given Template Variables to every template in the file.

Note: the file has to be properly set up to use the variables.

Attribute: template_variables

Accepted Values: Dictionary of values specified by each particular file.

Default Value: None

Example

libraries:
  TV Shows:
    collection_files:
      - default: genre
        template_variables:
          schedule_separator: never
          collection_mode: hide
      - default: actor                  # Notice how the `-` starts this block
        template_variables:
          schedule_separator: never
          collection_mode: hide

In this example there will be two template variables added to every template in the git file default: genre.

schedule_separator is set to never to not show a separator in this section and collection_mode is set to hide.

What these variables will do depends on how they're defined in the Collection File.

schedule - Used to schedule when a file is run.¶

Used to schedule when this file is run using the schedule options.

Warning

This does not work with Overlays as they cannot be scheduled individually. Use the schedule_overlays Library Attribute to schedule Overlays.

Attribute: schedule

Accepted Values: Any schedule option

Default Value: daily

Example

libraries:
  Movies:
    collection_files:
      - file: config/Movies.yml
        schedule: weekly(friday)
      - default: actors
        schedule: weekly(saturday)
playlist_files:
  - file: config/Playlists.yml
    schedule: weekly(sunday)

asset_directory - Used to define Asset Directories for a file.¶

Specify the directory where assets (posters, backgrounds, etc) are located for this specific file.

Tip

Assets can be stored anywhere on the host system that Kometa has visibility of (i.e. if using docker, the directory must be mounted/visible to the docker container).

Attribute: asset_directory

Accepted Values: Any directory

Default Value: [Directory containing YAML config]/assets

Example

libraries:
  Movies:
    collection_files:
      - file: config/Movies.yml
        asset_directory: <path_to_assets>/Movies
      - default: actors
        asset_directory: <path_to_assets>/people
    overlay_files:
      - default: imdb
playlist_files:
  - file: config/Playlists.yml
    asset_directory:
      - <path_to_assets>/playlists1
      - <path_to_assets>/playlists2