TSSK (TV Show Status for Kometa) checks Sonarr for your TV Shows statuses and creates .yml files
which can be used by Kometa to create collections and overlays.

Categories:

• New shows, that were added in the past x days
• Shows with upcoming regular episodes within x days
• Shows for which a new season is airing within x days
• Shows for which a new season has been added which aired in the past x days
• Shows with upcoming season finales within x days
• Shows for which a season finale was added which aired in the past x days
• Shows for which a final episode was added which aired in the past x days

---

📝 Table of Contents

• ✨ Features
• 🛠️ Installation
• 🧩 Continue Setup
  • 1️⃣ Edit your Kometa config
  • 2️⃣ Edit your configuration file
• ⚙️ Configuration
• 🚀 Usage
• ⚠️ Do you Need Help or have Feedback?

---

✨ Features

• 🗓️ Detects upcoming episodes, finales and seasons: Searches Sonarr for TV show schedules.
• 🏁 Aired Finale labelling: Use a separate overlay for shows for which a Finale was added.
• ▼ Filters out unmonitored: Skips show if season/episode is unmonitored. (optional)
• 🪄 Customizable: Change date format, collection name, overlay positioning, text, ..
• ℹ️ Informs: Lists matched and skipped(unmonitored) TV shows.
• 📝 Creates .yml: Creates collection and overlay files which can be used with Kometa.

---

🛠️ Installation

1. Ensure you have Docker installed.

2. Copy the example environment file and configure it:

   cp .env.example .env

   Then edit .env with your settings. See .env.example for the complete list of available environment variables.

3. Review and customize the docker-compose.yml file if needed. See docker-compose.yml for the complete configuration.

4. Run the container:

docker compose up -d

This will:

• Build the TSSK container with Python scheduler
• Run the script on a daily schedule (by default at 2AM)
• Mount your configuration and output directories into the container

You can customize the run schedule by modifying the APP_TIMES environment variable in your .env file (format: HH:MM, e.g., 02:00 for 2 AM, or 02:00,14:00 for multiple times).

---

🧩 Continue Setup

1️⃣ Edit your Kometa config

Open your Kometa config.yml (typically at /config/config.yml, NOT your TSSK config file).

The .yml files created by TSSK that Kometa uses are saved to /app/tssk/ inside the container, which is mounted to your Kometa metadata directory.

Make sure your Kometa config uses the correct path to reference those files.

In your Kometa config, include paths to the generated .yml files under your TV Shows library:

libraries:
  TV Shows:
    collection_files:
    - file: /config/metadata/tssk/new_season_collection.yml
    - file: /config/metadata/tssk/new_season_started_collection.yml
    - file: /config/metadata/tssk/upcoming_episode_collection.yml
    - file: /config/metadata/tssk/upcoming_finale_collection.yml
    - file: /config/metadata/tssk/final_episode_collection.yml
    - file: /config/metadata/tssk/season_finale_collection.yml
    overlay_files:
    - file: /config/metadata/tssk/new_season_overlays.yml
    - file: /config/metadata/tssk/new_season_started_overlays.yml
    - file: /config/metadata/tssk/upcoming_episode_overlays.yml
    - file: /config/metadata/tssk/upcoming_finale_overlays.yml
    - file: /config/metadata/tssk/final_episode_overlays.yml
    - file: /config/metadata/tssk/season_finale_overlays.yml   
    - file: /config/metadata/shows_overlay.yml

Tip

Only add the files for the categories you want to enable. All are optional and independently generated based on your config settings.

2️⃣ Edit your configuration file

---

⚙️ Configuration

Environment Variables

Create a .env file by copying the example file:

cp .env.example .env

Then edit .env with your configuration. For the complete and up-to-date list of all environment variables, see .env.example.

Required variables:

• SONARR_URL: Your Sonarr instance URL (e.g., http://localhost:8989)
• SONARR_API_KEY: Your Sonarr API key (found in Sonarr under Settings => General => Security)

Optional variables:

• SONARR_TIMEOUT: Request timeout in seconds (default: 90)
• TZ: Timezone (e.g., America/New_York)
• PUID/PGID: User/Group IDs for file permissions (default: 1000)
• APP_TIMES: Schedule times in HH:MM format (default: 02:00)
• RUN_AT_START: Run immediately on startup (default: true)

Note

Always refer to .env.example for the latest environment variable options and defaults.

Config File

Edit data/config.yml with your settings. See data/config.yml for the complete configuration file.

• log_retention_runs: Number of previous log runs to keep (default: 7). Logs are automatically rotated and compressed.
• skip_unmonitored: Default false if set to true it will skip a show if the upcoming season/episode is unmonitored.
• ignore_finales_tags: Shows with these tags will be ignored when checking for finales.

Note

For some shows, episodes are listed one at a time usually one week ahead in Sonarr. Because of this, TSSK wrongly (yet logically..) thinks that the last episode listed in the season is a finale. You can give problematic shows like this a tag in Sonarr so TSSK will ignore finales for that show and treat the current 'last' episode of the season as a regular episode.

Note

Timezone is set via the TZ environment variable in your .env file (e.g., TZ=America/New_York). The script will automatically use this timezone for all date calculations and conversions.

• simplify_next_week_dates: Will simplify dates to today, tomorrow, friday etc if the air date is within the coming week.
• process_: Choose which categories you wish to process. Change to false to disable.

For each category, you can change the relevant settings:

• future_days: How many days into the future the script should look.

• recent_days: How many days in the past the script should look (for aired Finales)

• collection block:

  • collection_name: The name of the collection.
  • smart_label: Choose the sorting option. More info here
  • sort_title: Collection sort title.
  • etc

Tip

You can enter any other Kometa variables in this block and they will be automatically added in the generated .yml files.
collection_name is used to name the collection and will be stripped from the collection block.

• backdrop block:

  • enable: whether or not you want a backdrop (the colored banner behind the text)
  • Change backdrop size, color and positioning. You can add any relevant variables here. More info here

• text block:

  • date_format: The date format to be used on the overlays. e.g.: "yyyy-mm-dd", "mm/dd", "dd/mm", etc.
  • capitalize_dates: true will capitalize letters in dates.
  • use_text: Text to be used on the overlays before the date. e.h.: "NEW SEASON"
  • Change text color and positioning. You can add any relevant variables here. More info here
  • For New Season Soon, New Season Started, Upcoming Finale and Season Finale you can use [#] to display the season number

Tip

group and weight are used to determine which overlays are applied in case multiple are valid. Example: You add a new show, for which season 2 just aired in full yesterday. In this case the following overlays would be valid: new show, new season and season finale. In the default config, new show has the highest weight (40) so that's the overlay that will be applied. If you prefer any of the other to be applied instead, you need to increase their weight. You can also choose to have multiple overlays applied at the same time by removing the group and weight, in case you put them in different positions.

Note

These are date formats you can use:
d: 1 digit day (1)
dd: 2 digit day (01)
ddd: Abbreviated weekday (Mon)
dddd: Full weekday (Monday)

m: 1 digit month (1)
mm: 2 digit month (01)
mmm: Abbreviated month (Jan)
mmmm: Full month (January)

yy: Two digit year (25)
yyyy: Full year (2025)

Dividers can be /, - or a space

---

🚀 Usage

The script runs automatically according to the schedule defined by the APP_TIMES environment variable in your .env file (default: 02:00 for 2 AM daily). See docker-compose.yml for the complete Docker configuration.
You can inspect the container logs to see output and monitor activity:

docker logs -f tssk

The script will list matched and/or skipped shows and create the .yml files.
The previous configuration will be erased so Kometa will automatically remove overlays for shows that no longer match the criteria.

---

⚠️ Original project can be found here

• https://github.com/netplexflix/TV-show-status-for-Kometa