Skip to main content

# Plex

Find your Plex Token and make note of the URL and Port used to connect to your Plex instance.

Allowed Users and Defaults

Multi-scrobbler will automatically scrobble for these users by default:

- The User authenticated with the Plex Token
- and the Local User

The Local User (`PLEX_LOCAL_USER`) is how Plex identifies anyone directly accessing the Plex UI from a local IP (who does not need to login).

To allow MS to scrobble for other users use `usersAllow` or `PLEX_USERS_ALLOW` (env) from the below configuration docs. However, because you are overriding the default settings you must also explicitly list the authenticated user and the Local User if you want them to also be able to scrobble.

Examples

###### Defaults​

If `usersallow` and `PLEX_USERS_ALLOW` are not defined then the Plex Token authenticated User and Local User will be scrobbled for.

###### Only A Specific User​

- `"usersallow": ["SomeUser"]` or
- `PLEX_USERS_ALLOW: SomeUser`

Only the Plex user `SomeUser` will be scrobbled for. The Plex Token authenticated user and the Local User will not be scrobbled for.

###### A Specific User + Defaults​

(Assuming the plex authenticated user is `FoxxMD`)

- `"usersallow": ["FoxxMD", "PLEX_LOCAL_USER", "SomeUser"]` or
- `PLEX_USERS_ALLOW: FoxxMD,PLEX_LOCAL_USER,SomeUser`

The Plex user SomeUser, the Plex Token authenticated user (FoxxMD) and the Local User will be scrobbled for.

Allowed Libraries and Defaults

By default multi-scrobbler will only scrobble media found in Plex libraries that are labelled as Music.

- `librariesAllow` or `PLEX_LIBRARIES_ALLOW` will override this

Use Plex metadata with Musicbrainz for better scrobbling

### Matching With Plex

In Plex, if the Plex Music Agent is set on a Music Library then Plex attempts to match your music with Musicbrainz when it is first imported.

Plex uses ID3/metdata tags to match or falls back to matching based on file name and folder names. If it cannot find a match it can be fixed through a Fix Match option in the album/track context menu. See plex documentation for more information.

You can verify if an Item has been matched by:

- Clicking on the Item context menu (...)
- Get Info
- View XML

If a node like this is present then it has been matched: `<Guid id="mbid://4e631558-13b0..."/>`

### Using Musicbrainz With Multi-Scrobbler

The MBID from the above `<Guid>` node is a Track, a special type of ID that specifically identifies a song on a specific album. If this is present then Multi-scrobbler can use it to gaurantee your scrobble, and all its metadata, is matched 1:1 with what is in your Plex library when using the Musicbrainz Stage to enrich your scrobble.

To configure MS to use Musicbrainz with your Plex metadata use one of the methods below:

- ENV
- File
- File AIO

Add to your multi-scrobbler docker compose file `environment` section for Musicbrainz ENV Configuration:

    # a real email that Musicbrainz can use to contact you in case of issues
    - MB_CONTACT=myEmail@myEmailProvider.com
    - MB_PRESETS=id,default
    - PLEX_TRANSFORMS=musicbrainz

Your AIO Config:

config.json

    {
      // ...
      "transformers": [
        {
          "type": "musicbrainz",
          "name": "MyMB",
          "data": {
            "apis": [
              {
                // a real email that Musicbrainz can use to contact you in case of issues
                "contact": "myEmail@myEmailProvider.com"
              }
            ]
          }
        }
      ]
    }

In your File Config:

plex.json

    [
      {
        "name": "MyPlex",
        "data": { /* ... */},
        "options": {
          "playTransform": {
            "preCompare": [
              {
                "type": "musicbrainz",
                "name": "MyMB"
                "searchOrder": ["mbidrecording", "basicOrIds", "basic"]
              }
            ]
          }
        }
      }
    ]

Your AIO Config:

config.json

    {
      // ...
      "transformers": [
        {
          "type": "musicbrainz",
          "name": "MyMB",
          "data": {
            "apis": [
              {
                // a real email that Musicbrainz can use to contact you in case of issues
                "contact": "myEmail@myEmailProvider.com"
              }
            ]
          }
        }
      ]
      // ...
      "sources": [
        // ...
        {
          "name": "MyPlex",
          "type": "plex",
          "data": { /* ... */},
          "options": {
            "playTransform": {
              "preCompare": [
                {
                  "type": "musicbrainz",
                  "name": "MyMB",
                  "searchOrder": ["mbidrecording", "basicOrIds", "basic"]
                }
              ]
            }
          }
        }
      ]
    }

#### Configuration​

- ENV
- File
- AIO

Configuration Type

This is configuration for the ENV Config Type.

Environmental Variable | Type | Default | Description
--- | --- | --- | ---
`PLEX_ID` | string |  | A globally unique ID EX `myComponentId`
`PLEX_NAME` | string | Value of `PLEX_ID` | A vanity name EX `My Cool Component`
`PLEX_ENABLE` | boolean | true | Should this component be used?
`PLEX_URL` | string |  | http(s)://HOST:PORT of the Plex server to connect to
`PLEX_TOKEN` | string |  |
`PLEX_USERS_ALLOW` | string |  | Only scrobble for specific users from this comma-delimited list
`PLEX_USERS_BLOCK` | string |  | Do not scrobble for users from this comma-delimited list
`PLEX_DEVICES_ALLOW` | string |  | Do not scrobble if device or application name contains strings from this comma-delimited list
`PLEX_DEVICES_BLOCK` | string |  | Only scrobble if device or application name contains strings from this comma-delimited list
`PLEX_LIBRARIES_ALLOW` | string |  | Only scrobble if library name contains string from this comma-delimited list
`PLEX_LIBRARIES_BLOCK` | string |  | Do not scrobble if library name contains strings from this comma-delimited list

Bold/Italic = Required

Config Structure

This displays the structure of the File Configuration for a plex type Source with all possible properties, their shape, and descriptions/types. Use this to understand how to write a valid config.

Loading ...
Config Example

This displays an example config file of a plex Source File Configuration that adheres to the shown Config Structure.

- text mode lets you edit the JSON directly.
- tree mode gives you a guided point-and-click editing experience that always keeps the JSON syntax valid.

Both modes validate that the configuration is correct. Any errors show up as squiggly lines.

important

Only source plex configs will validate correctly in the editor but both source and client plex configs are allowed in the real `CONFIG/plex.json`

After you finish editing, switch to text and then copy all text to get a completed config.

Config Example Mobile Experience

This displays an example config file of a plex Source File Configuration that adheres to the shown Config Structure.

The example config file editor is meant for a larger screen experience so only the read-only example is shown. Please use this site on a tablet/laptop/desktop to enable file editor features.

CONFIG/plex.json

    [
      {
        "name": "Foxx Plex",
        "id": "MyPlexApi",
        "enable": true,
        "clients": [],
        "data": {
          "token": "1234",
          "url": "http://192.168.0.120:32400",
          "usersAllow": [
            "FoxxMD",
            "SomeOtherUser"
          ],
          "usersBlock": [
            "AnotherUser"
          ],
          "devicesAllow": [
            "firefox"
          ],
          "devicesBlock": [
            "google-home"
          ],
          "librariesAllow": [
            "GoodMusic"
          ],
          "librariesBlock": [
            "BadMusic"
          ]
        },
        "options": {
          "logPayload": true,
          "logFilterFailure": "debug",
          "ignoreInvalidCert": false
        }
      }
    ]

Config Structure

This displays the structure of the all-in-one (`config.json`) configuration with all possible properties, their shape, and descriptions/types. Use this to understand how to write a valid config.

Select the plex type from the respective `sources` node below, then expand it.

Loading ...
Config Example

This displays an example config file of a all-in-one (`config.json`) configuration that includes a plex Source that adheres to the shown Config Structure.

- text mode lets you edit the JSON directly.
- tree mode gives you a guided point-and-click editing experience that always keeps the JSON syntax valid.

Both modes validate that the configuraion is correct. Any errors show up as squiggly lines.

After you finish editing, switch to text and then copy all text to get a completed config.

Config Example Mobile Experience

This displays an example config file of a all-in-one (`config.json`) configuration that includes a plex Source that adheres to the shown Config Structure.

The example config file editor is meant for a larger screen experience so only the read-only example is shown. Please use this site on a tablet/laptop/desktop to enable file editor features.

CONFIG/config.json

    {
      "sources": [
        {
          "name": "Foxx Plex",
          "id": "MyPlexApi",
          "enable": true,
          "clients": [],
          "data": {
            "token": "1234",
            "url": "http://192.168.0.120:32400",
            "usersAllow": [
              "FoxxMD",
              "SomeOtherUser"
            ],
            "usersBlock": [
              "AnotherUser"
            ],
            "devicesAllow": [
              "firefox"
            ],
            "devicesBlock": [
              "google-home"
            ],
            "librariesAllow": [
              "GoodMusic"
            ],
            "librariesBlock": [
              "BadMusic"
            ]
          },
          "options": {
            "logPayload": true,
            "logFilterFailure": "debug",
            "ignoreInvalidCert": false
          },
          "type": "plex"
        }
      ]
    }