Terebii (テレビィ)

Terebii is an airing notification service for Sonarr. When new episodes of your shows are airing, Terebii can notify you through any service supported by Apprise, including Pushover, ntfy, Discord, IFTTT, and many, many, more.

Installation

Docker is the only supported way of running Terebii. You must set the TEREBII_SONARR_URL, TEREBII_SONARR_API_KEY, and TEREBII_NOTIFICATION_URL environment variables; see Configuration.

In the below examples, {TEREBII_TEMPLATE_DIR} is a placeholder for a path on your machine where Terebii will look for notification templates (see Customizing Notifications). If you don't intend to customize Terebii's notifications, you don't need to mount this directory.

---

Supported tags

Name	Description	Example
latest	The latest stable version of Terebii.	ghcr.io/celsiusnarhwal/terebii:latest
Major version number	The latest release of this major version of Terebii. May be optionally prefixed with a v.	ghcr.io/celsiusnarhwal/terebii:1 ghcr.io/celsiusnarhwal/terebii:v1
Minor version number	The latest release of this minor version of Terebii. May be optionally prefixed with a v.	ghcr.io/celsiusnarhwal/terebii:1.0 ghcr.io/celsiusnarhwal/terebii:v1.0
Exact version number	This version of Terebii exactly. May be optionally prefixed with a v.	ghcr.io/celsiusnarhwal/terebii:1.0.0 ghcr.io/celsiusnarhwal/terebii:v1.0.0
edge	The latest commit to Terebii's main branch. Unstable.	ghcr.io/celsiusnarhwal/terebii:edge

All Terebii images are distributed both with and without a Redis server. If you have your own Redis server and would prefer an image that doesn't include one, append -noredis to the tag of your choice.¹

---

Docker Compose

services:
  terebii:
    image: ghcr.io/celsiusnarhwal/terebii:latest
    container_name: terebii
    restart: unless-stopped
    environment:
      - TEREBII_SONARR_URL=sonarr.example.com
      - TEREBII_SONARR_API_KEY=your-sonarr-api-key
      - TEREBII_NOTIFICATION_URL=some://apprise.url
    volumes:
      - {TEREBII_TEMPLATE_DIR}:/app/terebii/templates

Docker CLI

docker run -d \
  --name terebii \
  --restart unless-stopped \
  -e TEREBII_SONARR_URL=sonarr.example.com \
  -e TEREBII_SONARR_API_KEY=your-sonarr-api-key \
  -e TEREBII_NOTIFICATION_URL=some://apprise.url \
  -v {TEREBII_TEMPLATE_DIR}:/app/terebii/templates \
  ghcr.io/celsiusnarhwal/terebii:latest

Customizing Notifications

You can customize the content of Terebii's notifications by creating Jinja templates in TEREBII_TEMPLATE_DIR. Notification titles can be customized by creating a template named title.jinja; notification bodies can be customized by creating a template named body.jinja.

For example:

Title template (title.jinja)

The following template:

{{ show_name }} is Airing

will result in a notification title similar to this:

Sound! Euphonium is Airing

Body template (body.jinja)

The following template:

S{{ season_num }} E{{ episode_num }} — {{ title }} is now airing on {{ network }}.

will result in a notification body similar to this:

S1 E8 — Festival Triangle is now airing on NHK Educational TV.

The above examples are also the default values for each template if either one is not present.

The following variables are provided to notification templates:

Variable	Type	Description
title	String (str)	The title of the episode.
show_name	String (str)	The name of the show.
runtime	Integer (int)	The runtime of the episode in minutes, rounded down to the nearest minute.
network	String (str)	The network the show airs on.
episode_num	Integer (int)	The episode number (e.g., 8).
episode_num_00	String (str)	The two-digit episode number (e.g. 08). Note that unlike episode_num, this variable is a string.
episode_num_word	String (str)	The word form of the episode number (e.g., eight).
episode_ordinal	String (str)	The ordinal episode number (e.g., 8th).
episode_ordinal_word	String (str)	The word form of the ordinal episode number (e.g., eighth).
season_num	Integer (int)	The season number (e.g., 1).
season_num_00	String (str)	The two-digit season number (e.g. 01). Note that unlike season_num, this variable is a string.
season_num_word	String (str)	The word form of the season number (e.g., one).
season_ordinal	String (str)	The ordinal season number (e.g., 1st).
season_ordinal_word	String (str)	The word form of the ordinal season number (e.g., first).
tvdb_url	String (str)	The URL of the show on TheTVDB, or None if no URL is available.
tmdb_url	String (str)	The URL of the show on The Movie Database, or None if no URL is available.
imdb_url	String (str)	The URL of the show on IMDb, or None if no URL is available.
air_date	Date (datetime.datetime)	The air date of the episode in the time zone specified by the TEREBII_TIMEZONE environment variable (see Configuration).
air_date_utc	Date (datetime.datetime)	The air date of the episode in UTC.
air_date_timestamp	Integer (int)	The air date of the episode in Unix time.

All template variables are Python objects and can be manipulated within notification templates in all of the ways that Jinja supports.

Formatting dates

The air_date and air_date_utc variables can be formatted using strftime(), e.g.,

{{ air_date.strftime("%Y-%m-%d %H:%M:%S") }}

Unformatted dates will be presented according to ISO 8601.

For all format codes, see strfti.me.

Configuration

Terebii can be configured via the following environment variables:

Variable	Type	Description	Required?	Default (if not required)
TEREBII_SONARR_URL	String	The URL of a Sonarr instance.	Yes
TEREBII_SONARR_API_KEY	String	The API key for the Sonarr instance reachable at TEREBII_SONARR_URL.	Yes
TEREBII_NOTIFICATION_URL	String	An Apprise URL for Terebii to send notifications to.	Yes
TEREBII_REFRESH_INTERVAL	String	A Go duration string representing the interval at which Terebii should pull new episodes from Sonarr's calendar. In addition to the standard Go units, you can use d for day, w for week, mm for month, and y for year.2 Must be between 1 second and 24 hours, inclusive.	No	1m
TEREBII_PREMIERES_ONLY	Boolean	If true, Terebii will only send notifications for episodes that are season premieres.	No	false
TEREBII_INCLUDE_UNMONITORED	Boolean	Whether Terebii should send notifications for episodes that aren't monitored.	No	false
TEREBII_INCLUDE_DOWNLOADED	Boolean	Whether Terebii should send notifications for episodes that have already been downloaded.	No	true
TEREBII_INCLUDE_POSTERS	Boolean	Whether to include show posters as notification attachments when possible.3	No	false
TEREBII_TIMEZONE	String	An IANA time zone identifier. The air_date template variable will be provided in this time zone.	No	UTC
TEREBII_TEST_NOTIFICATION	Boolean	If true, Terebii will send a test notification to TEREBII_NOTIFICATION_URL on startup.	No	false
TEREBII_LOG_LEVEL	String	The lowest level of log messages Terebii will output. Must be one of debug, info, warning, error, or critical.	No	info
TEREBII_LOG_FORMAT	String	The format of Terebii's log messages. Must be either console or json.	No	console

Advanced settings

Most people won't need to worry about these settings.

Variable	Type	Description	Required?	Default (if not required)
TEREBII_REDIS_URL	String	The URL of a Redis server. If specified, Terebii will use this Redis server instead of its integrated one. Must begin with redis:// or rediss://.	No1	redis://localhost
TEREBII_SONARR_USERNAME	String	A username with which to authenticate to Sonarr.	No4	N/A
TEREBII_SONARR_PASSWORD	String	A password with which to authenticate to Sonarr.	No4	N/A
TEREBII_SONARR_HEADERS	String	A JSON-formatted string containing HTTP headers for Terebii to include in requests to Sonarr.	No	N/A
TEREBII_SONARR_API_KEY_IN_URL	Boolean	If true, Terebii will authenticate to Sonarr by including the API key in a URL parameter rather than a header.	No	false

Footnotes

1. If you're using a Redis-less Terebii image, TEREBII_REDIS_URL is required. ↩ ↩²

2. 1 day = 24 hours, 1 week = 7 days, 1 month = 30 days, and 1 year = 365 days. ↩

3. "Possible" meaning that a poster can be found for the show and the notification service supports attachments. ↩

4. TEREBII_SONARR_USERNAME and TEREBII_SONARR_PASSWORD are required if Sonarr's API is protected by HTTP Basic authentication. ↩ ↩²