search

dylandoamaral / trakt-integration

A Trakt integration for Home Assistant compatible with upcoming media card
MIT License
33 stars 13 forks source link
custom hacs home-assistant integration movie show trakt upcoming-media-card

readme

Trakt Integration

HACS Release Last Commit Donate Coffee

View your Trakt calendar items in Upcoming Media Card on a Home Assistant dashboard.

:warning: This is still an early release. It may not be stable and it may have bugs. :warning:
See the Issues page to report a bug or to add a feature request.

Showcase Example

The image above was generated using Upcoming Media Card and Upcoming Media Card modification.

Recomendations 💡

Having the following installed in Home Assistant will help best use this integration:

Installation 🏠

Installation is a multi-step process. Follow each of the following steps.

1. Add HACS Integration

This integration is available in HACS (Home Assistant Community Store). Install it as follows:

2. Update Configuration File

The following shows all of the integration's default settings. Add it as a top-level key (i.e., trakt_tv: is not indented) in the configuration.yaml file:

trakt_tv:
  language: en # Prefered language for movie/show title
  timezone: Europe/Paris # Prefered timezone
  sensors:
    upcoming:
      show:
        days_to_fetch: 90 # How many days in the future you want to fetch
        max_medias: 3 # How many medias you want to fetch
      new_show:
        days_to_fetch: 90
        max_medias: 3
      premiere:
        days_to_fetch: 90
        max_medias: 3
      movie:
        days_to_fetch: 90
        max_medias: 3
      dvd:
        days_to_fetch: 90
        max_medias: 3
    next_to_watch:
      all:
        max_medias: 5
        exclude:
          - veep
          - the-original
          - friends
      only_aired:
        max_medias: 5
        exclude:
          - veep
          - the-original
          - friends
      only_upcoming:
        max_medias: 5

Integration Settings

Available Sensors

By default, this integration does not create any sensors. The settings that you include in the configuration.yaml file determines which sensors are created. This keeps you from having useless sensors that you don't need, such as the DVD sensor which will likely not fetch anything from the Trakt API, but you can still use it if you want to.

Upcoming sensors

Upcoming sensors are sensors giving the next anticipated movies or shows from your watch list.

There are five sensors available under the sensors > upcoming array:

There are two parameters for each sensor:

All Upcoming sensors

All Upcoming sensors are sensors giving the next anticipated movies or shows.

There are five sensors available under the sensors > all_upcoming array:

There are two parameters for each sensor:

Recommendation sensors

Recommendation sensors are sensors giving media that you may like.

There are five sensors available under the sensors > recommendation array:

There are one parameter for each sensor:

Next To Watch sensor

Next To Watch sensor is sensor giving the next show to watch depending on your progress.

There only one sensor available under the sensors > next_to_watch array:

There are three parameters for each sensor:

Anticipated Sensors

Example Configuration

To enable these sensors, you can use the following configuration:

trakt_tv:
  language: en
  timezone: America/Los_Angeles
  sensors:
    anticipated:
      movie:
        max_medias: 10
      show:
        max_medias: 10

You can also exclude collected items from these sensors:

trakt_tv:
  language: en
  timezone: America/Los_Angeles
  sensors:
    anticipated:
      movie:
        exclude_collected: true
        max_medias: 10
      show:
        exclude_collected: true
        max_medias: 10
Stats sensors

Creates individual sensors giving all of your stats about the movies, shows, and episodes you have watched, collected, and rated. Add sensors > stats with a list of the sensors you want to enable. You can enable all of them instead by adding all to the list.

The available stats are available:

Stats Example
trakt_tv:
  sensors:
    # Create sensors for all available stats
    stats:
      - all

    # OR

    # Create sensors for specific stats (see available stats above)
    stats:
      - episodes_plays
      - movies_minutes

Example

For example, adding only the following to configuration.yaml will create two sensors. One with the next 10 TV episodes in the next 30 days and another with the next 5 movies coming out in the next 45 days:

trakt_tv:
  language: en
  sensors:
    upcoming:
      show:
        days_to_fetch: 30
        max_medias: 10
      movie:
        days_to_fetch: 45
        max_medias: 5
    recommendation:
      show:
        max_medias: 3
      movie:
        max_medias: 3

3. Restart Home Assistant

Note: You will not see anything new in Home Assistant yet.

4. Prepare Trakt

You have to provide a client_id and a client_secret to use this integration. Get these keys with the following:

5. Add Home Assistant Integration

Depending on the options you set in the configuration.yaml file, the sensors may take a while to be created and populated.

6. Add an Upcoming Media Card

Go to your Dashboard, enable editing, and add a manual card like the following:

type: custom:upcoming-media-card
entity: sensor.trakt_upcoming_shows
title: Upcoming Episodes
image_style: fanart
hide_empty: true
title_text: $title
line1_text: $episode
line2_text: $number
line3_text: $day, $date $time
line4_text: $empty
max: 10

See the Upcoming Media Card page for formatting and display options to add to your card.

Workaround

Some people are unable to use the integration because the OAUTH authentification is not working.

Thanks @blizzrdof77 and @robloh for the following workaround:

  1. go to https://my.home-assistant.io/ and enter the correct path to my instance (example: http://172.30.1.11:8123/)
  2. instead of entering your local address (http://172.30.1.11:8123/) in the TRAKT application page, enter this: https://my.home-assistant.io/redirect/oauth
  3. add the integration
  4. accept in TRAKT
  5. then accept in the my home assistant page that showed up
  6. profit

Additional Information ℹ️

Why not use sensor.trakt ?

There is already another integration for Trakt, sensor.trakt. However, I decided to create my own integration for the following reasons:

Feature Requests and Contributions

Don't hesitate to ask for features or contribute your own pull request. ⭐

For Developers

If you want to add a feature or fix a bug by yourself, follow these instructions:

  1. Use Visual Studio Code and use dev containers
  2. In a browser open localhost:8123
  3. Add the trakt integration
  4. Start to develop a new feature

:info: To restart home assistant use make homeassistant