diff --git a/README.md b/README.md index 590d1c7..574e3d2 100644 --- a/README.md +++ b/README.md @@ -1,176 +1,94 @@ -# sensor.plex_recently_added +# Plex Recently Added Component -| Poster View | Fan Art View -| ---- | ---- -| Screenshot 1 | Screenshot 1 - -
- -**Requires a custom-component:**
-This card will only work if you've installed one of the custom-component's below to feed it. - -### Current custom-components for this card: - -| Component | Author | -|:---------------|----------:| -|[CouchPotato](https://github.com/youdroid/home-assistant-couchpotato)|[youdroid](https://github.com/youdroid) -|[Emby_Upcoming_Media](https://github.com/gcorgnet/sensor.emby_upcoming_media)|[gcorgnet](https://github.com/gcorgnet) -|[Kodi Recently Added](https://github.com/boralyl/kodi-recently-added)|[boralyl](https://github.com/boralyl) -|[Mylar](https://github.com/DarkSir23/sensor.mylar)|[DarkSir23](https://github.com/DarkSir23) -|[Plex Recently Added](https://github.com/custom-components/sensor.plex_recently_added)|[mayker](https://github.com/maykar) -|[Radarr Upcoming Media](https://github.com/custom-components/sensor.radarr_upcoming_media)|[mayker](https://github.com/maykar) -|[SickChill](https://github.com/youdroid/home-assistant-sickchill)|[youdroid](https://github.com/youdroid) -|[Sonarr Upcoming Media](https://github.com/custom-components/sensor.sonarr_upcoming_media)|[mayker](https://github.com/maykar) -|[Trakt](https://github.com/custom-components/sensor.trakt)|[iantrich](https://github.com/iantrich) +Home Assistant component to feed [Upcoming Media Card](https://github.com/custom-cards/upcoming-media-card) with +Plex's recently added media.
+This component does not require, nor conflict with, the default Plex components.

+### **New Features! ⭐** +* Added support for Plex 'deep_links' in sensor attributes (Direct URLs to each TV Episode & Movie on Plex Web). +* Added support for 'season_num' & 'episode_num' in sensor attributes for TV Episodes. +
+
### Issues Read through these two resources before posting issues to GitHub or the forums. * [troubleshooting guide](https://github.com/custom-cards/upcoming-media-card/blob/master/troubleshooting.md) * [@thomasloven's lovelace guide](https://github.com/thomasloven/hass-config/wiki/Lovelace-Plugins). -## Features: -* Poster and Fan Art views -* All text can have its contents, color, and size customized. -* Most design elements can be hidden or have their color changed. -* 12 or 24 hour display for times and month/day or day/month for dates. -* Indicator flag with customizable mdi icon and color. -* Can limit the number of episodes/movies shown. -* Uses responsive design to scale elegantly - ## Installation: - -* Install the custom component by following it's instructions. -* Install this card by copying `upcoming-media-card.js` to your `www/custom-lovelace/` folder. If you're copy/pasting the code always copy from raw files on github (button on top right when viewing code). -* Include it in its own folder like so: `www/custom-lovelace/upcoming-media-card/upcoming-media-card.js` - -This goes into ui-lovelace.yaml under "resources:" - -``` -resources: -- url: /local/custom-lovelace/upcoming-media-card/upcoming-media-card.js?v=0.1.1 - type: js +1. Install this component by copying [these files](https://github.com/custom-components/sensor.plex_recently_added/tree/master/custom_components/plex_recently_added) to `custom_components/plex_recently_added/`. +2. Install the card: [Upcoming Media Card](https://github.com/custom-cards/upcoming-media-card) +3. Add the code to your `configuration.yaml` using the config options below. +4. Add the code for the card to your `ui-lovelace.yaml`. +5. **You will need to restart after installation for the component to start working.** + +### Options + +| key | default | required | description | +| ---------------- | ----------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| name | Plex_Recently_Added | no | Name of the sensor. Useful to make multiple sensors with different libraries. | +| token | | yes | Your Plex token [(Find your Plex token)](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/) | +| host | localhost | yes | The host Plex is running on. | +| port | 32400 | yes | The port Plex is running on. | +| ssl | false | no | Set to true if you use SSL to access Plex. | +| max | 5 | no | Max number of items to show in sensor. | +| on_deck | False | no | Set to true to show "on deck" items. | +| download_images | true | no | Setting this to false will turn off downloading of images, but will require certain Plex settings to work. See below. | +| img_dir | '/upcoming-media-card-images/plex/' | no | This option allows you to choose a custom directory to store images in if you enable download_images. Directory must start and end with a `/`. | +| ssl_cert | false | no | If you provide your own SSL certificate in Plex's network settings set this to true. | +| section_types | movie, show | no | Allows you to specify which section types to consider [movie, show]. | +| image_resolution | 200 | no | Allows you to change the resolution of the generated images (in px), useful to display higher quality images as a background somewhere. | +| exclude_keywords | | no | Allows you to specify a list of keywords to be exclude from the sensor if in the title. | + +#### By default this addon automatically downloads images from Plex to your /www/custom-lovelace/upcoming-media-card/ directory. The directory is automatically created & only images reported in the upcoming list are downloaded. Images are small in size and are removed automatically when no longer needed. Currently & unfortunately, this may not work on all systems. + +#### If you prefer to not download the images you may set download_images to false, but you either have to set "Secure connections" to "preferred" or "disabled" (no SSL) or have a custom certificate set (these options are found in your Plex server's network settings). This is needed because the default SSL certificate supplied by Plex is for their own domain and not for your Plex server. Your server also needs to be "fully accessible outside your network" if you wish to be able to see images remotely. If your Plex server provides it's own certificate you only need to set ssl_cert to true and download_images to false. + +

+**Do not just copy examples, please use config options above to build your own!** +### Sample for minimal config needed in configuration.yaml: +```yaml + sensor: + - platform: plex_recently_added + token: YOUR_PLEX_TOKEN + host: 192.168.1.42 + port: 32400 ``` - -This goes into one of your views under "cards:" in the same file - -``` - - type: custom:upcoming-media-card - entity: sensor.sonarr_upcoming_media +### Sample for ui-lovelace.yaml: +```yaml + - type: custom:upcoming-media-card + entity: sensor.plex_recently_added + title: Recently Downloaded ``` - -If you're not updating using [tracker-card](https://github.com/custom-cards/tracker-card) and/or [custom-updater](https://github.com/custom-components/custom_updater) be sure that you are adding to a version number at the end of your lovelace resources when you update your cards, like so: - +### Multiple sensor sample for configuration.yaml: +```yaml + - platform: plex_recently_added + name: Recently Added Movies # will create sensor.recently_added_movies + token: !secret token + host: !secret host + port: 32400 + section_types: + - movie + + - platform: plex_recently_added + name: Recently Added TV # will create sensor.recently_added_tv + token: !secret token + host: !secret host + port: 32400 + section_types: + - show + exclude_keywords: + - Walking dead + - kardashians ``` -resources: -- url: /local/custom-lovelace/upcoming-media-card/upcoming-media-card.js?v=0.1.2 - type: js -``` - -You may need to have `javascript_version: latest` in your `configuration.yaml` under `frontend:`. - -## Options: - -This card has many customization options, but none are required to use the card. The card is fully functional with minimal configuration, like the installation example above. - -# Main Config: - -|NAME|TYPE|DEFAULT|DESCRIPTION| -|-|-|-|-| -|type|string|**REQUIRED**|**custom:upcoming-media-card**| -|entity|string|**REQUIRED**|The entity id of the custom component. Example **sensor.sonarr_upcoming_media** | -|title|string|optional|Title displayed at top of card.| -|date|string|mmdd|How to display dates. If the date were September 24th: **"date: ddmm"** would be 24/09 and **"date: mmdd"** would be 09/24| -|clock|number|12|Display times as either 12 hour **"clock: 12"** or 24 hour **"clock: 24"**| -|max|number|5|Maximum number of items to show.| -|image_style|string|poster|There are currently two different styles for the card:poster and fanart.| -|hide_empty|boolean|false|Hide card when there are no episodes to show. -|hide_flagged|boolean|false|Hide items that get an indicator flag. Useful to hide downloaded episodes for sonarr/radarr components. -|hide_unflagged|boolean|false|Hide items that don't have an indicator flag. Useful to hide watched items for plex component. -|flag|boolean|true|Display or hide indicator flag.| -|text_shadows|boolean|true|Display or hide shadows behind text.| -|box_shadows|boolean|true|Display or hide shadows behind objects.| -|all_shadows|boolean|no default|Turns both text and object shadows on or off. - -# Style Options: - -|NAME|POSTER DEFAULTS           |FANART DEFAULTS |DESCRIPTION| -|-|-|-|-| -|title_text
line1_text
line2_text
line3_text
line4_text|Defalts set by component|Defaults set by component|The text contents for the line. More info below.| -|title_size
line1_size
line2_size
line3_size
line4_size|large
medium
small
small
small|large
medium
small
small
small|Text size for each line. small, medium, or large| -|line_size|no default|no default|Text size of lines below title. More info below.| -|title_color
line1_color
line2_color
line3_color
line4_color|var(--primary-text-color)
var(--primary-text-color)
var(--primary-text-color)
var(--primary-text-color)
var(--primary-text-color) |'#fff'
'#fff'
'#fff'
'#fff'
'#fff'|The color of each line. Any valid CSS color. Hex values must be in quotes.| -|line_color|no default|no default|Color of lines below title. Any valid CSS color. Hex values must be in quotes. More info below.| -|border_color|'#fff'|'#000'|Color of the outside border in fanart view and border around image in poster view.| -|accent_color|var(--primary-color)|'#000'|Color of the ribbon in poster view and background in fanart view.| -|flag_color|var(--primary-color)|var(--primary-color)|Changes the color of indicator flag.| -|icon|Default set by component|Default set by component|Changes the icon in the indicator flag, uses mdi icons. **"icon: mdi:arrow-down"**
Set **"icon: none**" to hide.| -|icon_color|var(--primary-color)|var(--primary-color)|Changes the color of the icon in the indicator flag.| -
- -Text color options can be any valid CSS value. This includes color names like red, rgb values like rgba(255, 0, 0, 0.6), variable names for HA like var(--primary-color), hex values like '#ff6347', you can even use transparent. If using hex values, encase in quotes. This is the only time quotes are required in the cards configuration. - -There are 2 space saving configuration options: line_color and line_size. These two options affect all lines of text below the title. These options can be overwritten as well. For example: if you set line_color: white and line2_color: blue then lines 1 & 3 will be white while line 2 will be blue. - -# Text Content: - -You can build your own strings for each line of text, including title by using keywords. Each keyword is replaced with its relevant content, listed below. Encase this option in quotes. - -|KEYWORD|AVAILABILITY|DESCRIPTION| -|-|-|-| -|$title|All|Item's title| -|$release|All|A formatted version of the release time from the component. Particularly helpful for displaying different kinds of releases. Radarr for instance needs to distinguish between theater releases and physical releases. Radarr's release changes dynamically and is "In Theaters $day, $date" if theater release and more than a week away or "Available $day" if physical release and within a week.| -|$episode|TV Only|Episode Title| -|$number|TV Only|Season and episode number "S01E05"| -|$genres|All|List of genres| -|$rating|All|Rating of episode, source depends on component| -|$studio|All|Production Studio| -|$day|All|Day of "release" (release date, download date, etc.) depending on component. This item changes from long form if within a week "Monday" to short form "Mon" if further than a week.| -|$date|All|Date of release or download, etc., depending on component. Formatted with "date" in config.| -|$time|All*|Time of release or download. * Movies generally dont have a time for release.| -|$aired|Plex|Date that the media item originally aired. -|$runtime|All|Displays runtime as either "01:23" for > an hour and "23 min" otherwise. -|$empty|All|Displays line as empty space. Useful to create a break in the lines that can be sized. -
- -You can add in custom text to your string, only keywords are replaced. As an example you could add this to your config line1_text: 'Runtime: $runtime' to have line one display as "Runtime: 01:30". You can use as many keywords in your string as you like, you're only limited by what will fit. In some cases a keyword can return nothing, like when using radarr and a movie is in theaters. Occasionally not all info has been released yet, causing something like runtime to be empty. This isn't a problem when it's the only keyword in a line as the card just hides the line, but it can be an issue when you're using multiple keywords in a line. In this case you can use a hyphen to seperate the them. line1_text: 'Rating: $rating - Runtime: $runtime - $number' will display as "Rating: ★ 7.1 - Runtime: 01:23 - S01E09" when all are available or "Rating: ★ 7.1 - S01E09" if runtime is not. - - -# Developers - -**If you'd like to make your own component to feed the upcoming media card:** - -1. Component needs an attribute named "data" that contains a JSON string or OBJ. -2. The first item in your JSON must contain these keys to set your defaults: `title_default`, `line1_default`, `line2_default`, `line3_default`, `line4_default`, and `icon`. The default text contents are set exactly like the card's text content config and use the same keywords. The default icon takes an mdi icon `mdi:arrow-down`. -3. Each item must contain an 'airdate', if none exists the item is skipped. This and a poster image are the only required items. -4. If an included item is null it needs to be an empty string in the JSON `''`. -5. Items should be in descending order according to 'airdate'. -6. Be aware that the card strips parentheses and anything contained in them. This is to remove things like (US). Since we can see the art for the show/movie there is no need for that info. - -## JSON items: - -|KEY|DESCRIPTION| -|-|-| -|airdate|Must be UTC ISO 8601 format. Example 2018-10-25T01:00:00Z. This is how the card creates date, day, and time. Doesn't have to be air date, just a date associated with the item. It could be download date for example. -|title|Item's title| -|release|This is a formatted version of the release time from the component. Particularly helpful for displaying different kinds of releases. Radarr for instance needs to distinguish between theater releases and physical releases, so 'release' is changed dynamically by the component and is "In Theaters $day, $date" if theater release and more than a week away or "Available $day" if physical release and within a week.| -|episode|Episode Title| -|number|Season and episode number "S01E05"| -|genres|List of genres| -|rating|Rating of item| -|studio|Producing Studio| -|aired|When media originally aired, useful for when airdate is set as download date etc. -|runtime|Must be number of minutes as integer, the card then formats as needed. -|poster|Direct link to items poster image -|fanart|Direct link to items fanart image. If fanart is an empty string the card will zoom in and shift the poster image as a fallback. -|flag|Display indicator or not, boolean. - -## Example from Sonarr component with 3 episodes. Notice the defaults set in first item - -[{"title_default": "$title", "line1_default": "$episode", "line2_default": "$release", "line3_default": "$rating - $runtime", "line4_default": "$number - $studio", "icon": "mdi:arrow-down-bold-circle"}, {"title": "Modern Family", "episode": "Good Grief", "flag": false, "airdate": "2018-10-25T01:00:00Z", "number": "S10E05", "runtime": 25, "studio": "ABC (US)", "rating": "\u2605 8.8", "release": "$day, $date $time", "poster": "https://www.thetvdb.com/banners/_cache/posters/5bb9375cb2c5e.jpg", "fanart": "https://www.thetvdb.com/banners/_cache/fanart/original/5b300bbae5cd2.jpg", "genres": "Comedy"}, {"title": "American Horror Story", "episode": "Traitor", "flag": false, "airdate": "2018-10-25T02:00:00Z", "number": "S08E07", "runtime": 45, "studio": "FX (US)", "rating": "\u2605 8.4", "release": "$day, $date $time", "poster": "https://www.thetvdb.com/banners/_cache/posters/5b9983440d320.jpg", "fanart": "https://www.thetvdb.com/banners/_cache/fanart/original/5b9f15a15a9c1.jpg", "genres": "Drama, Horror, Thriller"}, {"title": "It's Always Sunny in Philadelphia", "episode": "Charlie's Home Alone", "flag": false, "airdate": "2018-10-25T02:00:00Z", "number": "S13E08", "runtime": 25, "studio": "FXX", "rating": "\u2605 9.1", "release": "$day, $date $time", "poster": "https://www.thetvdb.com/banners/_cache/posters/5ba7c2b687091.jpg", "fanart": "https://www.thetvdb.com/banners/_cache/fanart/original/5b48ef958034c.jpg", "genres": "Comedy"}] - - -Please inform me if you create one and I'll add it to the list.
-Include what your components defaults are in the components readme.
-If you need special styling or edits to the card to accomidate your component, just ask or submit a PR.

-Thanks! +## \*Currently genres, rating, and studio only work for Movies +### Card Content Defaults + +| key | default | example | +| ----- | ---------------------------- | --------------------------------------------------- | +| title | $title | "The Walking Dead" | +| line1 | $episode | "What Comes After" | +| line2 | $day, $date $time | "Monday, 10/31 10:00 PM" Displays time of download. | +| line3 | $number - $rating - $runtime | "S01E12 - ★ 9.8 - 01:30" | +| line4 | $genres | "Action, Adventure, Comedy" | +| icon | mdi:eye-off | https://materialdesignicons.com/icon/eye-off |