Description

Plex-TVTime is a Plex webhook handler that automatically updates your TVTime watch history. TV episodes are automatically marked as watched once you complete them on Plex.

Requirements

The Plex server owner must have an active Plex Pass subscription for webhooks to be enabled.

Installing

Unraid

To install Plex-TVTime on Unraid you can install the docker container through the community applications.

Docker Desktop

You can run Plex-TVTime on Docker locally by using the following command. Replace CONFIG with the directory you want the database to be saved to, and any other directories that contain your log files.

$ docker run -e TVTIME_USER={Your TVTime username} -e TVTIME_PASSWORD={Your TVTime password} -e PLEX_USERS={Plex username(s) to link} -p 8080:8080 zggis/plex-tvtime:latest

Docker Compose

Example compose and env files can be found here.

$ docker compose up

Usage

Navigating to the home page http://[host]:[port] in your browser will display the webhook URL you can enter in Plex > Settings > Webhooks. It should be http://[host]:[port]/webhook/plex You may need to restart your Plex media server for these changes to take effect.

Plex-TVTime will mark episodes as watched on your TVTime profile once you have watched them passed the configured 'Video played threshold' in Plex (You can adjust this % in Plex Settings > Library). Plex does not send webhooks when episodes are manaully marked as watched.

Watching an episode for a show that has not been added to you TVTime profile will automatically add the show. If this behavior is undesired, you can make use of the Excluded/Included configuration parameters below to restrict which shows are sent to TVTime.

By default watching an episode of a show you have already marked as watched in TVTime has no effect, the episode is not marked as 'rewatched' in TVTime, nor is the time you first marked the episode as watched updated. If the episode has a rewatch counter in TVTime it will be reset to 0. If you set MARK_REWATCH_EPISODES to true, previously watched episodes will be marked as rewatched and increment the counter in TVTime, the watch time displayed in TVTime will be the date you first watched the episode.

As of v1.1.0 Plex-TVTime supports linking multiple TVTime accounts through advanced configuration. See details below.

Basic Configuration

Required Variables

Optional Variables

Optional Mappings

Linking Multiple TVTime Accounts (Only available in v1.1.0+)

To link multiple TVTime accounts you can create a YAML configuration file following the template here. YAML files are very sensitive to format so make sure you use a text editor that can preserve tabs, spaces, and line endings.

You will need to mount the directory location of your YAML file to the docker container. In Unraid you can add a Path to the configuration, on docker command line you can follow the example below.

Lastly you will need to pass in a environment variable SPRING_CONFIG_LOCATION with the container relevant path of the YAML.

$ docker run -e SPRING_CONFIG_LOCATION=/config/application.yaml -v "C:/absolute/path/to/yaml/":/config -p 8080:8080 zggis/plex-tvtime:latest

For unraid, your advanced configuration would look like this:


The application.yaml file replaces all other configuration, so you no longer need to pass in any of the basic configuration as environment variables, you can set them directly in application.yaml. If you still want to use enviornment variables you can reference them in application.yaml with ${YOUR_ENVIRONMENT_VAR}

If you are using the docker compose file, you will need to specify SPRING_CONFIG_LOCATION in your .env file and the needed mount in your compose file.

Jellyfin Support

As of v2.4.0 Plex-TVTime supports Jellyfin integration for TV Shows. See this page to configure it.

Troubleshooting

Please check the logs, as described above many webhook events are intentionally ignored depending on configuration. If you can't resolve on your own open an issue and I will help. If you open an issue please set the LOGGING_LEVEL to TRACE and include the relevant logs in your issue, the app does not create its own logfile, so you can just copy them from the console logs.

If you get an error such as 'Unable to process webhook message: Cannot invoke "java.util.ArrayList.iterator()" because "webhook.metadata.guid" is null' this likely means the Plex TV Show episode does not have metadata, refreshing the metadata of the episode on your Plex server should resolve the issue.

If you do not see the media.scrobble event in the plex-tvtime logs you may need to restart your Plex media server for the webhook changes to fully take effect.

FAQ

Question: What about movies?

Answer: Movie support is available as of v2.1.0. To enable movie tracking set TRACK_MOVIES environment variable to true.