feat(plex): Initial Plex API Source implementation

FoxxMD · Oct 22, 2024 · dc4962a · dc4962a
1 parent ccf317c
commit dc4962a
Show file tree

Hide file tree

Showing 11 changed files with 819 additions and 16 deletions.
diff --git a/config/plex.json.example b/config/plex.json.example
@@ -1,15 +1,21 @@
 [
   {
-    "name": "MyPlex",
+    "name": "MyPlexApi",
     "enable": true,
     "clients": [],
     "data": {
-      "user": ["[email protected]","[email protected]"],
-      "libraries": ["music","my podcasts"],
-      "servers": ["myServer","anotherServer"],
-      "options": {
-        "logFilterFailure": "warn"
+      "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"
       }
-    }
   }
 ]
diff --git a/config/plex.webhook.json.example b/config/plex.webhook.json.example
@@ -0,0 +1,16 @@
+[
+  // rename files to plex.json to use
+  {
+    "name": "MyPlex",
+    "enable": true,
+    "clients": [],
+    "data": {
+      "user": ["[email protected]","[email protected]"],
+      "libraries": ["music","my podcasts"],
+      "servers": ["myServer","anotherServer"],
+      "options": {
+        "logFilterFailure": "warn"
+      }
+    }
+  }
+]
diff --git a/docsite/docs/configuration/configuration.mdx b/docsite/docs/configuration/configuration.mdx
@@ -23,6 +23,7 @@ import MprisConfig from '!!raw-loader!../../../config/mpris.json.example';
 import MusikcubeConfig from '!!raw-loader!../../../config/musikcube.json.example';
 import MPDConfig from '!!raw-loader!../../../config/mpd.json.example';
 import PlexConfig from '!!raw-loader!../../../config/plex.json.example';
+import PlexWebhookConfig from '!!raw-loader!../../../config/plex.webhook.json.example';
 import SpotifyConfig from '!!raw-loader!../../../config/spotify.json.example';
 import SubsonicConfig from '!!raw-loader!../../../config/subsonic.json.example';
 import TautulliConfig from '!!raw-loader!../../../config/tautulli.json.example';
@@ -240,10 +241,72 @@ If your Spotify player has [Automix](https://community.spotify.com/t5/FAQs/What-
 
 ### [Plex](https://plex.tv)
 
-Check the [instructions](plex.md) on how to setup a [webhooks](https://support.plex.tv/articles/115002267687-webhooks) to scrobble your plays.
+:::tip[Important Defaults]
+
+By default...
+
+* multi-scrobbler will **only** scrobbling for the user authenticated with the Plex Token. 
+  * Allowed Users (`usersAllow` or `PLEX_USERS_ALLOW`) are only necessary if you want to scrobble for additional users.
+* multi-scrobbler will only scrobble media found in Plex libraries that are labelled as **Music.**
+  * `librariesAllow` or `PLEX_LIBRARIES_ALLOW` will override this
+
+:::
+
+Find your [**Plex Token**](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/) and make note of the **URL** and **Port** used to connect to your Plex instance.
 
 #### Configuration
 
+<Tabs groupId="configType" queryString>
+    <TabItem value="env" label="ENV">
+        | Environmental Variable | Required? | Default | Description                                                            |
+        | ---------------------- | --------- | ------- | ---------------------------------------------------------------------- |
+        | `PLEX_URL`             | **Yes**   |         | The URL of the Plex server IE `http://localhost:8096`                  |
+        | `PLEX_TOKEN`           | **Yes**   |         | The **Plex Token** to use with the API                                 |
+        | `PLEX_USERS_ALLOW`     | No        |         | Comma-separated list of usernames (from Plex) to scrobble for          |
+        | `PLEX_USERS_BLOCK`     | No        |         | Comma-separated list of usernames (from Plex) to disallow scrobble for |
+        | `PLEX_DEVICES_ALLOW`   | No        |         | Comma-separated list of devices to scrobble from                       |
+        | `PLEX_DEVICES_BLOCK`   | No        |         | Comma-separated list of devices to disallow scrobbles from             |
+        | `PLEX_LIBRARIES_ALLOW` | No        |         | Comma-separated list of libraries to allow scrobbles from              |
+        | `PLEX_LIBRARIES_BLOCK` | No        |         | Comma-separated list of libraries to disallow scrobbles from           |
+    </TabItem>
+    <TabItem value="file" label="File">
+        <details>
+
+            <summary>Example</summary>
+
+            <CodeBlock title="CONFIG_DIR/plex.json" language="json5">{PlexConfig}</CodeBlock>
+
+        </details>
+
+        or <SchemaLink lower objectName="PlexApiSourceConfig"/>
+
+    </TabItem>
+    <TabItem value="aio" label="AIO">
+        <details>
+
+            <summary>Example</summary>
+
+            <AIOExample data={PlexConfig} name="plex"/>
+
+        </details>
+
+        or <SchemaLink lower objectName="PlexApiSourceConfig"/>
+    </TabItem>
+</Tabs>
+
+#### Legacy Webhooks
+
+Multi-scrobbler < 0.9.0 used [webhooks](https://support.plex.tv/articles/115002267687-webhooks) to support Plex scrobbling. The legacy docs are below.
+
+<details>
+
+* In the Plex dashboard Navigate to your **Account/Settings** and find the **Webhooks** page
+* Click **Add Webhook**
+* URL -- `http://localhost:9078/plex` (substitute your domain if different than the default)
+* **Save Changes**
+
+##### Configuration
+
 <Tabs groupId="configType" queryString>
     <TabItem value="env" label="ENV">
         | Environmental Variable | Required | Default | Description                                                                                                                             |
@@ -256,7 +319,7 @@ Check the [instructions](plex.md) on how to setup a [webhooks](https://support.p
 
             <summary>Example</summary>
 
-            <CodeBlock title="CONFIG_DIR/plex.json" language="json5">{PlexConfig}</CodeBlock>
+            <CodeBlock title="CONFIG_DIR/plex.json" language="json5">{PlexWebhookConfig}</CodeBlock>
 
         </details>
 
@@ -267,14 +330,16 @@ Check the [instructions](plex.md) on how to setup a [webhooks](https://support.p
 
             <summary>Example</summary>
 
-            <AIOExample data={PlexConfig} name="plex"/>
+            <AIOExample data={PlexWebhookConfig} name="plex"/>
 
         </details>
 
         or <SchemaLink lower objectName="PlexSourceConfig"/>
     </TabItem>
 </Tabs>
 
+</details>
+
 ### [Tautulli](https://tautulli.com)
 
 Check the [instructions](plex.md) on how to setup a notification agent.

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -54,6 +54,7 @@
     "@foxxmd/string-sameness": "^0.4.0",
     "@jellyfin/sdk": "^0.10.0",
     "@kenyip/backoff-strategies": "^1.0.4",
+    "@lukehagar/plexjs": "^0.23.5",
     "@react-nano/use-event-source": "^0.13.0",
     "@reduxjs/toolkit": "^1.9.5",
     "@supercharge/promise-pool": "^3.0.0",

diff --git a/src/backend/common/infrastructure/config/source/plex.ts b/src/backend/common/infrastructure/config/source/plex.ts
@@ -1,4 +1,4 @@
-import { CommonSourceConfig, CommonSourceData } from "./index.js";
+import { CommonSourceConfig, CommonSourceData, CommonSourceOptions } from "./index.js";
 
 export interface PlexSourceData extends CommonSourceData {
     /**
@@ -34,3 +34,62 @@ export interface PlexSourceConfig extends CommonSourceConfig {
 export interface PlexSourceAIOConfig extends PlexSourceConfig {
     type: 'plex'
 }
+
+export interface PlexApiData extends CommonSourceData {
+    token?: string
+    /**
+     * http(s)://HOST:PORT of the Plex server to connect to
+     * */
+    url: string
+
+        /**
+     * Only scrobble for specific users (case-insensitive)
+     *
+     * If `true` MS will scrobble activity from all users
+     * */
+        usersAllow?: string | true | string[]
+        /**
+         * Do not scrobble for these users (case-insensitive)
+         * */
+        usersBlock?: string | string[]
+
+        /**
+         * Only scrobble if device or application name contains strings from this list (case-insensitive)
+         * */
+        devicesAllow?: string | string[]
+        /**
+         * Do not scrobble if device or application name contains strings from this list (case-insensitive)
+         * */
+        devicesBlock?: string | string[]
+
+        /**
+         * Only scrobble if library name contains string from this list (case-insensitive)
+         * */
+        librariesAllow?: string | string[]
+        /**
+         * Do not scrobble if library name contains strings from this list (case-insensitive)
+         * */
+        librariesBlock?: string | string[]
+}
+
+export interface PlexApiOptions extends CommonSourceOptions {
+    /*
+    * Outputs JSON for session data the first time a new media ID is seen
+    * 
+    * For use when troubleshooting issues
+    * 
+    * @default false
+    */
+        logPayload?: boolean
+}
+
+export interface PlexApiSourceConfig extends CommonSourceConfig {
+    data: PlexApiData
+    options: PlexApiOptions
+}
+
+export interface PlexApiSourceAIOConfig extends PlexApiSourceConfig {
+    type: 'plex'
+}
+
+export type PlexCompatConfig = PlexApiSourceConfig | PlexSourceConfig;
diff --git a/src/backend/common/infrastructure/config/source/sources.ts b/src/backend/common/infrastructure/config/source/sources.ts
@@ -9,7 +9,7 @@ import { MopidySourceAIOConfig, MopidySourceConfig } from "./mopidy.js";
 import { MPDSourceAIOConfig, MPDSourceConfig } from "./mpd.js";
 import { MPRISSourceAIOConfig, MPRISSourceConfig } from "./mpris.js";
 import { MusikcubeSourceAIOConfig, MusikcubeSourceConfig } from "./musikcube.js";
-import { PlexSourceAIOConfig, PlexSourceConfig } from "./plex.js";
+import { PlexSourceAIOConfig, PlexSourceConfig, PlexApiSourceConfig, PlexApiSourceAIOConfig } from "./plex.js";
 import { SpotifySourceAIOConfig, SpotifySourceConfig } from "./spotify.js";
 import { SubsonicSourceAIOConfig, SubSonicSourceConfig } from "./subsonic.js";
 import { TautulliSourceAIOConfig, TautulliSourceConfig } from "./tautulli.js";
@@ -21,6 +21,7 @@ import { YTMusicSourceAIOConfig, YTMusicSourceConfig } from "./ytmusic.js";
 export type SourceConfig =
     SpotifySourceConfig
     | PlexSourceConfig
+    | PlexApiSourceConfig
     | TautulliSourceConfig
     | DeezerSourceConfig
     | SubSonicSourceConfig
@@ -42,6 +43,7 @@ export type SourceConfig =
 export type SourceAIOConfig =
     SpotifySourceAIOConfig
     | PlexSourceAIOConfig
+    | PlexApiSourceAIOConfig
     | TautulliSourceAIOConfig
     | DeezerSourceAIOConfig
     | SubsonicSourceAIOConfig