Skip to content
A MagicMirror2 module that displays the list of playback sessions for a Plex Media Server.
JavaScript CSS
Branch: master
Clone or download
Latest commit 3e562e7 Jan 1, 2020
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
images prep for initial release Oct 15, 2019
scripts prep for initial release Oct 15, 2019
translations Initial build working, except on mirror browser Oct 12, 2019
.gitignore Initial Commit Oct 11, 2019
CHANGELOG.md Implemented progress bar update between data updates Jan 1, 2020
LICENSE.txt prep for initial release Oct 15, 2019
MMM-PlexNowPlaying.css
MMM-PlexNowPlaying.js Changed show play count in header feature to use text templates Jan 1, 2020
README.md

README.md

MMM-PlexNowPlaying

This is a module for the MagicMirror² smart mirror project.

This module displays the list of playback sessions for a Plex Media Server.

Status Version Date Maintained? Minimum MagicMirror² Version
Working 1.1.0 2019-12-31 Yes 2.2.1

Example

Example of MMM-PlexNowPlaying

Dependencies

  1. A Plex Media Server installation for the source of the data

Installation

To install the module, use your terminal to:

  1. Navigate to your MagicMirror's modules folder. If you are using the default installation directory, use the command:
    cd ~/MagicMirror/modules
  2. Copy the module to your computer by executing the following command:
    git clone https://github.com/glitch452/MMM-PlexNowPlaying.git

Using the module

MagicMirror² Configuration

To use this module, add the following configuration block to the modules array in the config/config.js file:

var config = {
    modules: [
        ...
        {
            module: "MMM-PlexNowPlaying",
            position: "top_left",
            header: "Plex: Now Playing",
            config: {
                serverProtocol: "http",
                serverAddress: "x.x.x.x",
                serverPort: 32400,
                xPlexToken: "xxxxxxxxxxxxxxxxxxxx"
                // See below for more Configuration Options
            }
        },
        ...
    ]
}

Configuration Options

Option Details
serverAddress REQUIRED - IP Address or Hostname of the server.
Type: string
xPlexToken REQUIRED - An X-Plex-Token for a user that has access to the server's session list.
See Finding an authentication token for more details on how to obtain the token.
Type: string
serverPort Optional - The port to use when connecting to the server.
Type: number
Default: 32400
serverProtocol Optional - The protocol to use when connecting to the server. Note: https will work with newer Plex Server versions, however MagicMirror may not be able to connect via https.
Type: string
Default: "http"
Options: "http", "https"
updateInterval Optional - The number of seconds to wait before requesting an update of the data from the Plex Server. The minimum value is 2.
Type: number
Default: 30
fontSize Optional - The main font size to use for the module text.
Type: string
Default: "medium"
Options: "x-small", "small", "medium", "large", "x-large"
fontColor Optional - The colour to use for the module text.
Type: string
Default: MagicMirror's default color
Options: Any valid CSS color value. See w3schools for more info.
userNameFilter Optional - Replace usernames with custom names. i.e. if someone uses the username plex.user.123, the module can display their actual name instead by adding an entry into this object that maps the user name to the friendly name.
Example: { "user_name": "Custom Name", "plex.user.123": "John Smith" }
Type: object
Default: {}
showUser Optional - When true, the user avatar and username are shown for each item in the list.
Type: boolean
Default: true
showPoster Optional - When true, the thubmail image is show for each item in the list with a supported image.
Type: boolean
Default: true
showStatusIcons Optional - When true, the status indicator icons are shown in the list. These icons include the playback state (playing/paused), connection type (local/remote) and connection security status (secure/insecure).
Type: boolean
Default: true
headerTemplate Optional - The text template to use for the module header text when there is at least one stream displayed. The sting "{header_text}" will be replaced with the module's header text. The string "{play_count}" will be replaced with the number of streams displayed.
Type: string
Default: "{header_text} ({play_count})"
headerTemplateZero Optional - The text template to use for the module header text when there are no streams displayed. The sting "{header_text}" will be replaced with the module's header text. The string "{play_count}" will be replaced with the number of streams displayed.
Type: string
Default: "{header_text} ({play_count})"
hideWhenNothingPlaying Optional - When true, this module will be completely hidden when there are no streams.
Type: boolean
Default: false
enableProgressTimer Optional - When true, the progress bars will be incremented between data updates from the server. This makes the progress bar animation smoother with smaller jumps, which is especially noticeable with shorter media files, such as music.
Type: boolean
Default: true
networkFilter Optional - Whether to show only Local streams, only Remote streams of Both.
Type: string
Default: "both"
Options: "local", "remote", "both"
playStateFilter Optional - Whether to show only Playing streams, only Paused streams of Both.
Type: string
Default: "both"
Options: "playing", "paused", "both"
userWhiteList Optional - When set, items will only show up if the user is in this list.
Type: array of string
Default: []
userBlackList Optional - Items will NOT show up if the user is in this list. This has a higher priority than userWhiteList.
Type: array of string
Default: []
typeWhiteList Optional - When set, items will only show up if the type is in this list.
Item Types: "movie", "episode", "track", "photo", "trailer", "livetv", "other".
Type: array of string
Default: []
typeBlackList Optional - Items will NOT show up if the type is in this list. This has a higher priority than typeWhiteList. See typeWhiteList for the list of Item Types.
Type: array of string
Default: []
libraryWhiteList Optional - When set, an item will only show up if the name of its Library is in this list.
Item Types: "<your_library_names>", "Trailers", "Other".
Type: array of string
Default: []
libraryBlackList Optional - An item will NOT show up if the name of its Library is in this list. This has a higher priority than libraryWhiteList. See libraryWhiteList for the list of Library Names.
Type: array of string
Default: []
animationSpeed Optional - The number of milliseconds to use for the animation when updating the on-screen display of this module. The minimum value is 0.
Type: number
Default: 0
initialLoadDelay Optional - The number of seconds to wait before starting to run this module. The minimum value is 0.
Type: number
Default: 0
retryDelay Optional - The number of seconds to wait before trying to request the data again after a data retrieval failure.
Type: number
Default: 5

Updates

To update the module to the latest version, use your terminal to:

  1. Navigate to your MMM-PlexNowPlaying folder. If you are using the default installation directory, use the command:
    cd ~/MagicMirror/modules/MMM-PlexNowPlaying
  2. Update the module by executing the following command:
    git pull

If you have changed the module on your own, the update will fail.
To force an update (WARNING! your changes will be lost), reset the module and then update with the following commands:

git reset --hard
git pull

Manually Choose a Version

To use an older version of this module, use your terminal to:

  1. Navigate to your MMM-PlexNowPlaying folder. If you are using the default installation directory, use the command:
    cd ~/MagicMirror/modules/MMM-PlexNowPlaying
  2. Fetch all the available tags
    git fetch
  3. Show all the available tags
    git tag
  4. Checkout one of the available tags
    git checkout {tag_name}
    Example: git checkout v1.0.0

To switch back to the latest version, use your terminal to:

  1. Navigate to your MMM-PlexNowPlaying folder. If you are using the default installation directory, use the command:
    cd ~/MagicMirror/modules/MMM-PlexNowPlaying
  2. Checkout the master branch
    git checkout master

License

The MIT License (MIT)

Copyright © 2019 David Dearden

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

The software is provided “as is”, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.

You can’t perform that action at this time.