diff --git a/source/_integrations/plex.markdown b/source/_integrations/plex.markdown index 98643ec1183..34047dab207 100644 --- a/source/_integrations/plex.markdown +++ b/source/_integrations/plex.markdown @@ -103,9 +103,14 @@ By default, the Plex integration will create Media Player entities for all local ### Service `media_player.play_media` -Plays a song, album, artist, playlist, TV show/season/episode, movie, or video on a connected client. +Play media hosted on a Plex server on a Plex client or other supported device. -Required fields within the `media_content_id` payloads are marked as such, others are optional. +Required fields within the `media_content_id` payloads are marked as such, others are optional. There are special parameters that can be added to any query: + +- `shuffle`: Shuffles the playback order of the media. Accepts `1` or `true` to enable. +- `allow_multiple`: A search must find one specific item to succeed. This parameter accepts multiple matches in a search and enqueues all found items for playback. Accepts `1` or `true` to enable. + +Simplified examples are provided for [music](#music), [TV episodes](#tv-episode), and [movies](#movie). See [advanced searches](#advanced-searches) for complex/smart search capabilities.
@@ -118,7 +123,7 @@ Refer to these links if casting to non-Plex players:
- The integration must be configured with a token for playback commands to work. This can occur if using the `List of IP addresses and networks that are allowed without auth` option on the Plex server. If that feature is required, it's recommended to configure the integration with that feature temporarily disabled. +The integration must be configured with a token for playback commands to work. This can occur if using the `List of IP addresses and networks that are allowed without auth` option on the Plex server. If that feature is required, it's recommended to configure the integration with that feature temporarily disabled.
@@ -127,7 +132,7 @@ Refer to these links if casting to non-Plex players: | Service data attribute | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `entity_id` | `entity_id` of the client | -| `media_content_id` | Quoted JSON containing:
| +| `media_content_id` | Quoted JSON containing:
| | `media_content_type` | `MUSIC` | ##### Examples: @@ -163,7 +168,7 @@ media_content_id: '{ "playlist_name": "The Best of Disco", "shuffle": "1" }' | Service data attribute | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `entity_id` | `entity_id` of the client | -| `media_content_id` | Quoted JSON containing:
| +| `media_content_id` | Quoted JSON containing:
| | `media_content_type` | `EPISODE` | ##### Examples: @@ -184,12 +189,24 @@ media_content_id: '{ "library_name": "Kid TV", "show_name": "Sesame Street", "sh | Service data attribute | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------- | | `entity_id` | `entity_id` of the client | -| `media_content_id` | Quoted JSON containing:
| +| `media_content_id` | Quoted JSON containing:
| | `media_content_type` | `movie` | -For movies it's usually sufficient to provide the title. However, if the title you provide has multiple matches (such as with remakes), more search keys may be necessary. These optional keys can be included in the `media_content_id` JSON payload to restrict the search: +##### Examples: -* `unwatched`: Restrict search to unwatched items only (`True`, `False`) +```yaml +entity_id: media_player.plex_player +media_content_type: movie +media_content_id: '{ "library_name": "Adult Movies", "title": "Blade" }' +``` + +#### Advanced Searches + +Instead of searching for a specific known piece of media, many additional parameters are available to run more powerful searches. This can also be used when a simple search for a title has multiple matches, such as with movie remakes. + +These are examples of optional keys that can be included in the `media_content_id` JSON payload customize the search: + +* `unwatched`: Restrict search to unwatched items only (`true`, `false`) * `actor`: Restrict search for movies that include a specific actor * `collection`: Restrict search within a named Plex collection ("Back to the Future", "Indiana Jones") * `contentRating`: Restrict search to a specific content rating ("PG", "R") @@ -200,27 +217,43 @@ For movies it's usually sufficient to provide the title. However, if the title y * `resolution`: Restrict search to a specific video resolution (480, 720, 1080, "4k") * `year`: Restrict search to a specific year -##### Examples: +More parameters and additional details can be found in the `plexapi` library [documentation](https://python-plexapi.readthedocs.io/en/latest/modules/library.html#plexapi.library.LibrarySection.search). -```yaml -entity_id: media_player.plex_player -media_content_type: movie -media_content_id: '{ "library_name": "Adult Movies", "title": "Blade" }' -``` +##### Examples -```yaml -entity_id: media_player.plex_player -media_content_type: movie -media_content_id: '{ "library_name": "Adult Movies", "title": "The Manchurian Candidate", year=1962 }' -# Would find the original instead of the 2004 remake -``` +Below are examples of advanced searches. All examples show what can be sent in the `media_content_id` parameter. -"Lazy" searches are also possible: -```yaml -entity_id: media_player.plex_player -media_content_type: movie -media_content_id: '{ "library_name": "Adult Movies", "title": "die hard", year=1995 }' -# Would find the sequel, "Die Hard: With a Vengeance" +Note that some searches may require `"maxresults": 1` to limit the result to a single item. However, an "item" may be a group of media, such as an album, season, artist, show, etc. + +The search will attempt to guess the type of media based on the search parameters by using the most specific media type provided. For example, a search using `artist.title` and `album.year` will search for albums for the artist that were released in a specific year. If you add `track.title` to the search, it will instead try to find the track. You may specify the type of media to search for with the `libtype` parameter which can be one of `movie`, `episode`, `season`, `show`, `track`, `album`, or `artist`. This could be useful if searching for an album where you only know the name of a specific track (see example below). + +```json +# Play the original instead of the 2004 remake: +{ "library_name": "Movies", "title": "The Manchurian Candidate", "year": 1962 } + +# "Lazy" searches are also possible (would find the sequel, "Die Hard: With a Vengeance"): +{ "library_name": "Movies", "title": "die hard", "year": 1995 } + +# Play for an artist's album where only a track name is known: +{ "library_name": "Music", "artist.title": "Stevie", "track.title": "Higher Ground" } + +# Play all albums with "orange" in the title: +{ "library_name": "Music", "album.title": "orange", "allow_multiple": true } + +# Watch the most recently added movie +{ "library_name": "Movies", "sort": "addedAt:desc", "maxresults": 1 } + +# Play an unwatched movie from the "Bond" collection which was released in the 2000s +{ "library_name": "Movies", "collection": "Bond", "decade": 2000, "unwatched": true } + +# Play the most recently added TV show which has been partially watched +{ "library_name": "TV Shows", "inProgress": true, "sort": "addedAt:desc", "maxresults": 1 } + +# Listen to a random electronic album which was added over 3 years ago but hasn't been listened to for at least 3 months +{ "library_name": "Music", "addedAt<<": "3y", "album.genre": "Electronic", "album.lastViewedAt<<": "3mon", "sort": "random", "maxresults": 1 } + +# Watch the worst rated movie from the 2000s starring either Nicolas Cage or Danny Devito +{ "library_name": "Movies", "actor": ["Nicolas Cage", "Danny DeVito"], "decade": 2000, "sort": "audienceRating:asc", "maxresults": 1 } ``` ### Compatibility