Trakt Integration

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

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

---

Recomendations

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

• Upcoming Media Cards

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:

• In Home Assistant, go to HACS > Integrations
• Press the Explore & Add Repositories button
• Search for "Trakt"
  • Note: There are two Trakt integrations. Choose the one with the description "A Trakt integration for Home Assistant compatible with upcoming media card". See Why not use sensor.trakt?
• Press the Install this repository in HACS button
• Press the Install button

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
  update_interval: 30 # API fetching in minutes
  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

Integration Settings

• language should be an ISO 639-1 codes
• update_interval should be a positive number in minutes

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.

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

• show for TV Shows (actually, episodes). Creates sensor.trakt_upcoming_shows
• new_show for New Shows (series premiers). Creates sensor.trakt_upcoming_new_shows
• premiere for Season Premieres. Creates sensor.trakt_upcoming_premieres
• movie for Movies premieres. Creates sensor.trakt_upcoming_movies
• dvd for DVD & Blu-ray releases. Creates sensor.trakt_upcoming_dvds

There are two parameters for each sensor:

• days_to_fetch should be a positive number for how many days to search
• max_medias should be a positive number for how many items to grab

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
  update_interval: 30
  sensors:
    upcoming:
      show:
        days_to_fetch: 30
        max_medias: 10
      movie:
        days_to_fetch: 45
        max_medias: 5

3. Restart Home Assistant

• Confirm the configuration.yaml is valid in Configuration > Server Controls > Configuration validation > Check Configuration button
• Restart your Home Assistant server in Configuration > Server Controls > Server management > Restart button

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:

• Go to the Trakt API Apps page and press the New application button
• Fill in the Name (required) and Description (optional) fields. These fields are just for your own reference
• Fill in Redirect uri with one of the following
  • If you use HA Cloud: https://<ha-cloud-remote-url>/auth/external/callback
  • If you do not use HA Cloud: https://<your-ha-server-address>:<port>/auth/external/callback
• Do not enter anything in Javascript (cors) origins and do not select any Permissions
• Press the Save app button
• Record the displayed client_id and client_secret
  • Note: You do not need to press the Authorize button!

5. Add Home Assistant Integration

• In Home Assistant, go to Configuration > Integrations
• Press the Add Integration button
• Search for "Trakt" and click on it
• Enter the client_id and client_secret from Trakt
• Press the Submit button
• Press the Finish button

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.

---

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:

• The other integration is almost never updated
• They haven't accepted my pull request for more than 3 months, so I modified it in my local environment to meet my needs
• This integration provides more features than the old one
  • Fetch more than 33 days (the single-query limitation on Trakt)
  • Have both the Movies and TV Shows calendars at the same time
  • Use other Trakt calendars such as Premieres, New Shows, and DVD & Blu-ray releases
• This integration doesn't depends to any other library (even though I would like to use pydantic so much, ARGHHH!)

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. Run the Run Home Assistant on port 9123
3. Add the trakt integration
4. Start to develop a new feature