[!IMPORTANT] As per 2026.04.22, TSSK has been integrated into UMTK. This repo is now archived and no longer in development. TSSK continues to function as part of UMTK.

TSSK (TV Show Status for Kometa) checks your 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
• Returning Shows
• Ended Shows
• Canceled Shows

Example overlays (you can fully customize placement, colors, text, etc:

Example collection:

_{Also see UMTK for adding a category for upcoming Movies and TV shows}

📝 Table of Contents

• 🛠️ Installation
  • Option 1: Docker
    • Step 1: Install Docker
    • Step 2: Create docker-compose file
    • Step 3: (Optional): Update volumes, Timezone and CRON Schedule
    • Step 4: Create config
    • Step 5: Configure your settings
    • Step 6: Run TSSK
    • Step 7: Add the yml files to your Kometa config
  • Option 2: Manual (Python)
    • Step 1: Download Script
    • Step 2: Install dependencies
    • Step 3: Configure your settings
    • Step 4: Run TSSK
    • Step 5: Add the yml files to your Kometa config
• ⚙️ Configuration
  • General settings
  • Collection blocks
  • Overlay blocks
  • Date formats
• ☄️ Add the yml files to your Kometa config
• 🌐 Localization
• ⚠️ Do you Need Help or have Feedback?

🛠️ Installation

Option 1: Docker

Step 1: Install Docker

1. Download Docker Desktop from docker.com
2. Install and start Docker Desktop on your computer
3. Verify installation: Open a terminal/command prompt and type docker --version - you should see a version number

Step 2: Create Docker Compose File

1. Create a new folder for TSSK on your computer (e.g., C:\TSSK or /home/user/TSSK)
2. Download the docker-compose.yml and place it in that folder, or manually create it by copy pasting this content:

version: "3.8"

services:
  tssk:
    image: netplexflix/tssk:latest
    container_name: tssk
    environment:
      - CRON=0 2 * * * # every day at 2am
      - DOCKER=true # important for path reference
      - TZ=Europe/Amsterdam # Set your timezone
    volumes:
      - ./config:/app/config
      - ./kometa:/config/kometa
    restart: unless-stopped

Step 3 (Optional): Update volumes, Timezone and CRON Schedule

By default the yml files will be output in a kometa subdirectory in your TSSK directory. You can choose to have them output in a different location if you want.

[!IMPORTANT] The format is: your-actual-path:container-path
Do not change the container-path parts

Example:

• You want the output yml files to be output in your existing kometa config folder which is located at /mnt/user/kometa/config
• Then your mount should look like this:

   - /mnt/user/kometa/config:/config/kometa

Update the timezone in the TZ environment variable to match your location (e.g.: America/New_York, Europe/London, Asia/Tokyo)
Update the CRON Schedule if you want to schedule it differently from the default (daily at 2 AM). (Tip: Crontab.Guru)

Step 4: Create a config

1. Create a subfolder named config
2. Download config/config.example.yml and save it as config.yml in your config folder

Step 5: Configure Your Settings

• See ⚙️ Configuration

Step 6: Run TSSK

1. Open a terminal/command prompt in your TSSK folder
2. Type this command and press Enter:

   docker-compose up -d
   

3. That's it! TSSK will now run automatically every day at 2 AM

Step 7: Add the yml files to your Kometa config

• See ☄️ Add the yml files to your Kometa config

Option 2: Manual (Python)

Step 1: Download Script

git clone https://github.com/netplexflix/TV-show-status-for-Kometa.git
cd TV-show-status-for-Kometa

[!TIP] If you don't know what that means, then simply download the script by pressing the green 'Code' button above and then 'Download Zip'.
Extract the files to your desired folder.

Step 2: Install dependencies

• Ensure you have Python installed (>=3.11).
• Open a Terminal in the script's directory

[!TIP] Windows Users:
Go to the TSSK folder (where TSSK.py is). Right mouse click on an empty space in the folder and click Open in Windows Terminal.

• Install the required dependencies by running:

pip install -r requirements.txt

Step 3: Configure your settings

• See ⚙️ Configuration

Step 4: Run TSSK

Open a Terminal in your script directory and launch the script with:

python TSSK.py

[!TIP] Windows users can create a batch file to quickly launch the script.
Type "[path to your python.exe]" "[path to the script]" -r pause" into a text editor

For example:

"C:\Users\User1\AppData\Local\Programs\Python\Python311\python.exe" "P:\TSSK\TSSK.py" -r
pause

Save as a .bat file. You can now double click this batch file to directly launch the script.
You can also use this batch file to schedule the script to run.

Step 5: Add the yml files to your Kometa config

• See ☄️ Add the yml files to your Kometa config

⚙️ Configuration

Rename config.example.yml in your config folder to config.yml and edit the needed settings:

General settings:

• sonarr_url: Change if needed.
• sonarr_api_key: Can be found in Sonarr under settings => General => Security.
• sonarr_timeout: Increase if needed for large libraries.
• use_tvdb: Change to true if you prefer TheTVDB statuses for returning and ended. (note: TheTVDB does not have the 'canceled' status)
• edit_sort_titles: Set to true to have TSSK edit sort titles directly in Plex (requires plex_url, plex_token, and tv_libraries). The air date of the new season premiere will be added to the sort title so you can sort shows by air date.
• plex_url: Your Plex server URL (e.g., http://localhost:32400).
• plex_token: Your Plex authentication token. How to find your Plex token
• tv_libraries: Comma-separated list of Plex TV library names to update (e.g., TV Shows or TV Shows, Anime).
• skip_unmonitored: Default true 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 TheTVDB/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.

• utc_offset: Set the UTC timezone offset. e.g.: LA: -8, New York: -5, Amsterdam: +1, Tokyo: +9, etc

[!NOTE] Some people may run their server on a different timezone (e.g. on a seedbox), therefor the script doesn't convert the air dates to your machine's local timezone. Instead, you can enter the utc offset you desire.

• 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 blocks:

• 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.

Overlay blocks:

• 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.

Date formats:

[!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

☄️ Add the yml files to your Kometa config

Open your Kometa config.yml (typically at Kometa/config/config.yml, NOT your TSSK config file).
Include paths to the generated .yml files under the relevant TV Shows library sections:

Manual install Example:

TV Shows:
  overlay_files:
  - file: P:/scripts/TSSK/kometa/TSSK_TV_NEW_SEASON_OVERLAYS.yml
  - file: P:/scripts/TSSK/kometa/TSSK_TV_UPCOMING_EPISODE_OVERLAYS.yml
  - file: P:/scripts/TSSK/kometa/TSSK_TV_UPCOMING_FINALE_OVERLAYS.yml
  - file: P:/scripts/TSSK/kometa/TSSK_TV_CANCELED_OVERLAYS.yml
  - file: P:/scripts/TSSK/kometa/TSSK_TV_ENDED_OVERLAYS.yml
  - file: P:/scripts/TSSK/kometa/TSSK_TV_RETURNING_OVERLAYS.yml
  - file: P:/scripts/TSSK/kometa/TSSK_TV_SEASON_FINALE_OVERLAYS.yml
  - file: P:/scripts/TSSK/kometa/TSSK_TV_FINAL_EPISODE_OVERLAYS.yml
  - file: P:/scripts/TSSK/kometa/TSSK_TV_NEW_SEASON_STARTED_OVERLAYS.yml
  - file: P:/scripts/TSSK/kometa/TSSK_TV_NEW_SHOW_OVERLAYS.yml
  collection_files:
  - file: P:/scripts/TSSK/kometa/TSSK_TV_NEW_SHOW_COLLECTION.yml
  - file: P:/scripts/TSSK/kometa/TSSK_TV_NEW_SEASON_COLLECTION.yml
  - file: P:/scripts/TSSK/kometa/TSSK_TV_NEW_SEASON_STARTED_COLLECTION.yml
  - file: P:/scripts/TSSK/kometa/TSSK_TV_UPCOMING_EPISODE_COLLECTION.yml
  - file: P:/scripts/TSSK/kometa/TSSK_TV_UPCOMING_FINALE_COLLECTION.yml
  - file: P:/scripts/TSSK/kometa/TSSK_TV_SEASON_FINALE_COLLECTION.yml
  - file: P:/scripts/TSSK/kometa/TSSK_TV_FINAL_EPISODE_COLLECTION.yml
  - file: P:/scripts/TSSK/kometa/TSSK_TV_CANCELED_COLLECTION.yml
  - file: P:/scripts/TSSK/kometa/TSSK_TV_ENDED_COLLECTION.yml
  - file: P:/scripts/TSSK/kometa/TSSK_TV_RETURNING_COLLECTION.yml

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

🌐 Localization

You can translate weekdays and months by using a localization file.

• Download your language from this repo (config/localization files)
• Rename it to localization.yml and place it in your config folder (next to config.yml).

If your language is missing, simply use one of the templates and edit as needed.

⚠️ Do you Need Help or have Feedback?

• Join the Discord.

❤️ Support the Project

If you like this project, please ⭐ star the repository and share it with the community!