Merge pull request #812 from arabcoders/dev

feat: Playlist Sync

Author: arabcoders

NEWS.md

@@ -1,5 +1,10 @@
 # NEWS
 
+### 2026-04-23
+
+Plex appears to have backtracked on the API change that broke external `invited users`, so WatchState supports them again for now.
+Support may change again if Plex reverses course or make it harder to access invited users tokens.
+
 ### 2026-03-26
 
 Unfortunately, due to changes from plex regarding their API, we can no longer generate access tokens for external users i.e. `invited users`, thus we had to disable and remove

README.md

@@ -10,6 +10,14 @@ box, this tool supports `Jellyfin`, `Plex` and `Emby` media servers.
 
 # Updates
 
+### 2026-04-26
+
+Cross-backend sync for playlists is now available as a **beta** feature. This is still early work, so expect some rough edges, 
+backend-specific issues, and possible breaking changes as it matures. 
+
+Because playlist behavior differs across backends, the feature may change over time, and if it proves too unreliable to support consistently, 
+it may be reworked or removed. To enable it, simply go to Tasks and enable the `Playlist` task.
+
 ### 2026-04-23
 
 Plex appears to have backtracked on the API change that broke external `invited users`, so WatchState supports them again for now.

composer.json

@@ -13,11 +13,11 @@
         }
     },
     "scripts": {
-        "test": "vendor/bin/phpunit",
-        "tests": "vendor/bin/phpunit",
+        "test": "vendor/bin/phpunit --display-all-issues",
+        "tests": "vendor/bin/phpunit --display-all-issues",
         "format": "vendor/bin/mago format",
         "format:ci": "vendor/bin/mago format --check",
-        "test:all": "php -d display_errors=1 -d display_startup_errors=1 -d error_reporting=E_ALL vendor/bin/phpunit",
+        "test:all": "php -d display_errors=1 -d display_startup_errors=1 -d error_reporting=E_ALL vendor/bin/phpunit --display-all-issues",
         "test:coverage": [
             "mkdir -p var/coverage",
             "php -d zend_extension=xdebug -d xdebug.mode=coverage -d xdebug.start_with_request=no vendor/bin/phpunit --coverage-filter src/ --coverage-clover var/coverage/clover.xml --coverage-xml var/coverage/xml --coverage-text",

config/config.php

@@ -9,6 +9,7 @@
 use App\Commands\State\BackupCommand;
 use App\Commands\State\ExportCommand;
 use App\Commands\State\ImportCommand;
+use App\Commands\State\PlaylistCommand;
 use App\Commands\State\ValidateCommand;
 use App\Commands\System\IndexCommand;
 use App\Commands\System\PruneCommand;
@@ -342,6 +343,14 @@
                 'timer' => $checkTaskTimer((string) env('WS_CRON_IMPORT_AT', '0 */1 * * *'), '0 */1 * * *'),
                 'args' => env('WS_CRON_IMPORT_ARGS', '-v'),
             ],
+            PlaylistCommand::TASK_NAME => [
+                'command' => PlaylistCommand::ROUTE,
+                'name' => PlaylistCommand::TASK_NAME,
+                'info' => 'Sync playlists cross backends. (BETA)',
+                'enabled' => (bool) env('WS_CRON_PLAYLIST', false),
+                'timer' => $checkTaskTimer((string) env('WS_CRON_PLAYLIST_AT', '15 */6 * * *'), '15 */6 * * *'),
+                'args' => env('WS_CRON_PLAYLIST_ARGS', '-v'),
+            ],
             ExportCommand::TASK_NAME => [
                 'command' => ExportCommand::ROUTE,
                 'name' => ExportCommand::TASK_NAME,

config/env.spec.php

@@ -535,7 +535,7 @@
     };
 
     // -- Do not forget to update the tasks list if you add a new task.
-    $tasks = ['import', 'export', 'backup', 'prune', 'indexes', 'validate', 'dispatch'];
+    $tasks = ['import', 'playlist', 'export', 'backup', 'prune', 'indexes', 'validate', 'dispatch'];
     $task_env = [
         [
             'key' => 'WS_CRON_{TASK}',

config/servers.spec.php

@@ -78,6 +78,13 @@
         'nullable' => true,
         'description' => 'The last time data was exported to the backend.',
     ],
+    [
+        'key' => 'export.playlist.lastSync',
+        'type' => 'int',
+        'visible' => true,
+        'nullable' => true,
+        'description' => 'The last time playlists were synced to the backend.',
+    ],
     [
         'key' => 'import.enabled',
         'type' => 'bool',
@@ -91,6 +98,13 @@
         'nullable' => true,
         'description' => 'The last time data was imported from the backend.',
     ],
+    [
+        'key' => 'import.playlist.lastSync',
+        'type' => 'int',
+        'visible' => true,
+        'nullable' => true,
+        'description' => 'The last time playlists were synced from the backend.',
+    ],
     [
         'key' => 'options',
         'type' => 'array',
@@ -111,10 +125,10 @@
         'description' => 'How many items to get per request when syncing.',
         'validate' => function ($value, array $spec = []) {
             $limit = 300;
-            if ((int)$value < $limit) {
+            if ((int) $value < $limit) {
                 throw new ValidationException(r('The value must be greater than {limit} items.', ['limit' => $limit]));
             }
-            return (int)$value;
+            return (int) $value;
         },
     ],
     [
@@ -151,7 +165,7 @@
         'key' => 'options.MAX_EPISODE_RANGE',
         'type' => 'int',
         'visible' => false,
-        'description' => 'The max range a single record/episode can cover. The default is 5.'
+        'description' => 'The max range a single record/episode can cover. The default is 5.',
     ],
     [
         'key' => 'options.client.timeout',

migrations/sqlite_1761320000_add_playlist_tables.sql

@@ -0,0 +1,55 @@
+-- # migrate_up
+
+CREATE TABLE IF NOT EXISTS "playlists"
+(
+    "id"          integer NOT NULL PRIMARY KEY AUTOINCREMENT,
+    "backend"     text    NOT NULL,
+    "backend_id"  text    NOT NULL,
+    "title"       text    NOT NULL,
+    "type"        text    NOT NULL DEFAULT 'video',
+    "summary"     text    NULL,
+    "is_editable" integer NOT NULL DEFAULT '1',
+    "is_smart"    integer NOT NULL DEFAULT '0',
+    "is_public"   integer NOT NULL DEFAULT '0',
+    "item_count"  integer NOT NULL DEFAULT '0',
+    "sync_id"     text    NULL,
+    "content_hash" text   NOT NULL DEFAULT '',
+    "remote_updated_at" integer NOT NULL DEFAULT '0',
+    "deleted_at"  integer NULL,
+    "metadata"    text    NOT NULL DEFAULT '{}',
+    "created_at"  integer NOT NULL,
+    "updated_at"  integer NOT NULL,
+    "synced_at"   integer NOT NULL,
+    UNIQUE ("backend", "backend_id")
+);
+
+CREATE INDEX IF NOT EXISTS "playlists_backend" ON "playlists" ("backend");
+CREATE INDEX IF NOT EXISTS "playlists_title" ON "playlists" ("title");
+CREATE INDEX IF NOT EXISTS "playlists_sync_id" ON "playlists" ("sync_id");
+CREATE INDEX IF NOT EXISTS "playlists_remote_updated_at" ON "playlists" ("remote_updated_at");
+CREATE INDEX IF NOT EXISTS "playlists_deleted_at" ON "playlists" ("deleted_at");
+
+CREATE TABLE IF NOT EXISTS "playlist_items"
+(
+    "id"               integer NOT NULL PRIMARY KEY AUTOINCREMENT,
+    "playlist_id"      integer NOT NULL,
+    "position"         integer NOT NULL,
+    "state_id"         integer NULL,
+    "backend_item_id"  text    NULL,
+    "backend_entry_id" text    NULL,
+    "item_type"        text    NULL,
+    "title"            text    NOT NULL,
+    "metadata"         text    NOT NULL DEFAULT '{}',
+    "created_at"       integer NOT NULL,
+    "updated_at"       integer NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS "playlist_items_position" ON "playlist_items" ("playlist_id", "position");
+CREATE INDEX IF NOT EXISTS "playlist_items_playlist_id" ON "playlist_items" ("playlist_id");
+CREATE INDEX IF NOT EXISTS "playlist_items_state_id" ON "playlist_items" ("state_id");
+CREATE INDEX IF NOT EXISTS "playlist_items_backend_item" ON "playlist_items" ("backend_item_id");
+
+-- # migrate_down
+
+DROP TABLE IF EXISTS "playlist_items";
+DROP TABLE IF EXISTS "playlists";

src/API/Player/Playlist.php

@@ -15,6 +15,7 @@
 use Psr\Log\LoggerInterface as iLogger;
 use Psr\SimpleCache\CacheInterface as iCache;
 use Psr\SimpleCache\InvalidArgumentException;
+use SensitiveParameter;
 use SplFileInfo;
 use Throwable;
 
@@ -32,7 +33,7 @@ public function __construct(
      * @throws InvalidArgumentException
      */
     #[Get(pattern: self::URL . '/{token}[/[{fake:.*}[/]]]')]
-    public function __invoke(iRequest $request, #[\SensitiveParameter] string $token): iResponse
+    public function __invoke(iRequest $request, #[SensitiveParameter] string $token): iResponse
     {
         if (null === ($data = $this->cache->get($token, null))) {
             return api_error('Token is expired or invalid.', Status::BAD_REQUEST);

src/API/System/Reset.php

@@ -19,7 +19,7 @@ final class Reset
     public const string URL = '%{api.prefix}/system/reset';
 
     #[Delete(self::URL . '[/]', name: 'system.reset')]
-    public function reset(iRequest $request, Redis $redis, iImport $mapper, iLogger $logger): iResponse
+    public function reset(Redis $redis, iImport $mapper, iLogger $logger): iResponse
     {
         foreach (get_users_context($mapper, $logger) as $userContext) {
             // -- reset database.
@@ -29,6 +29,8 @@ public function reset(iRequest $request, Redis $redis, iImport $mapper, iLogger
             foreach (array_keys($userContext->config->getAll()) as $name) {
                 $userContext->config->set("{$name}.import.lastSync", null);
                 $userContext->config->set("{$name}.export.lastSync", null);
+                $userContext->config->set("{$name}.export.playlist.lastSync", null);
+                $userContext->config->set("{$name}.import.playlist.lastSync", null);
             }
 
             // -- persist changes.
@@ -45,7 +47,7 @@ public function reset(iRequest $request, Redis $redis, iImport $mapper, iLogger
     }
 
     #[Post(self::URL . '/opcache[/]', name: 'system.reset.opcache')]
-    public function opcache(iRequest $request, Redis $redis, iImport $mapper, iLogger $logger): iResponse
+    public function opcache(): iResponse
     {
         return api_response(Status::OK, [
             'message' => opcache_reset() ? 'OPCache reset is complete.' : 'OPCache reset failed.',

src/Backends/Common/ClientInterface.php

@@ -235,6 +235,46 @@ public function getIdentifier(bool $forceRefresh = false): int|string|null;
      */
     public function getUsersList(array $opts = []): array;
 
+    /**
+     * Return list of editable playlists.
+     *
+     * @param array $opts options.
+     *
+     * @return array<int,array<string,mixed>>
+     */
+    public function getPlaylistsList(array $opts = []): array;
+
+    /**
+     * Return playlist details.
+     *
+     * @param string|int $id playlist id.
+     * @param array $opts options.
+     *
+     * @return array<string,mixed>
+     */
+    public function getPlaylist(string|int $id, array $opts = []): array;
+
+    /**
+     * Create playlist.
+     *
+     * @param string $title playlist title.
+     * @param array<int,string> $itemIds playlist item ids.
+     * @param array $opts options.
+     *
+     * @return array<string,mixed>
+     */
+    public function createPlaylist(string $title, array $itemIds = [], array $opts = []): array;
+
+    /**
+     * Delete playlist.
+     *
+     * @param string|int $id playlist id.
+     * @param array $opts options.
+     *
+     * @return array<string,mixed>
+     */
+    public function deletePlaylist(string|int $id, array $opts = []): array;
+
     /**
      * Return list of backend libraries.
      *