plexsonic 0.1.12 → 0.1.20

package/.env.example

@@ -4,6 +4,10 @@ BIND_HOST=127.0.0.1
 # Leave empty to derive from incoming request headers.
 BASE_URL=
 SQLITE_PATH=./data/app.db
+CACHE_SQLITE_PATH=./data/cache.db
+TRANSCODE_CACHE_PATH=./data/transcodes
+TRANSCODE_CLEANUP_INTERVAL_SEC=3600
+TRANSCODE_ARTIFACT_MAX_AGE_SEC=604800
 SESSION_SECRET=change-this-session-secret-before-production
 # 32-byte key in hex or base64 for Plex token encryption.
 TOKEN_ENC_KEY=

package/README.md

@@ -10,6 +10,12 @@ It provides:
 - Web test page for manual API checks
 - Playback/scrobble/rating/playlist actions mapped to Plex
 
+## Local Cache
+
+Plexsonic keeps a local SQLite cache of Plex music metadata to make browse/search responses fast and reduce repeated Plex API calls.
+The cache is stored separately from account/session data (`CACHE_SQLITE_PATH`, default `./data/cache.db`), refreshes automatically when Plex changes are detected, and can be safely rebuilt if removed.
+Cache entries are scoped by Plex account + Plex server/library, so local Plexsonic users linked to the same Plex account can share cached metadata.
+
 To support this project, please subscribe to my [Patreon](https://www.patreon.com/ClassicOldSong).
 
 [![Support me on Patreon](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fshieldsio-patreon.vercel.app%2Fapi%3Fusername%3DClassicOldsong%26type%3Dpatrons&style=for-the-badge)](https://patreon.com/ClassicOldsong)
@@ -53,6 +59,10 @@ PORT=3127
 BIND_HOST=127.0.0.1
 BASE_URL=
 SQLITE_PATH=./data/app.db
+CACHE_SQLITE_PATH=./data/cache.db
+TRANSCODE_CACHE_PATH=./data/transcodes
+TRANSCODE_CLEANUP_INTERVAL_SEC=3600
+TRANSCODE_ARTIFACT_MAX_AGE_SEC=604800
 SESSION_SECRET=replace-with-a-long-random-secret
 TOKEN_ENC_KEY=
 PLEX_PRODUCT=Plexsonic Bridge
@@ -69,6 +79,11 @@ LOG_REQUESTS=0
 - `PORT`: HTTP port (default `3127`).
 - `BIND_HOST`: listen interface (`127.0.0.1` local only, `0.0.0.0` for LAN).
 - `BASE_URL`: optional public URL override used for callback generation. If empty, origin is derived from request headers.
+- `SQLITE_PATH`: credentials/session/application database path.
+- `CACHE_SQLITE_PATH`: WAL-backed Plex metadata cache database path.
+- `TRANSCODE_CACHE_PATH`: local cache directory for ffmpeg-transcoded stream outputs.
+- `TRANSCODE_CLEANUP_INTERVAL_SEC`: periodic cleanup interval for transcode artifacts (`0` disables cleanup).
+- `TRANSCODE_ARTIFACT_MAX_AGE_SEC`: max artifact age before cleanup removes it (`0` disables cleanup).
 - `PLEX_WEBHOOK_TOKEN`: optional shared secret for `/webhooks/plex`. If set, webhook calls must provide this token.
 - `SESSION_SECRET`: cookie/session signing secret. Keep stable across restarts.
 - `TOKEN_ENC_KEY`: optional but recommended 32-byte key (hex or base64) used to encrypt stored Plex tokens.
@@ -85,6 +100,17 @@ openssl rand -hex 32
 openssl rand -hex 32
 ```
 
+## Streaming Transcode
+
+`/rest/stream.view` can transcode in-bridge (ffmpeg) to `mp3`, `aac`, `opus`, and `flac`.
+
+- `format` chooses target codec/container when supported (`mp3`, `aac`, `opus`, `flac`).
+- `maxBitRate` is respected for lossy outputs.
+- If only `maxBitRate` is provided, Plexsonic defaults to `opus` transcode.
+- `estimateContentLength` adds a best-effort `Content-Length` for uncached transcodes.
+- Transcode outputs are cached on disk (`TRANSCODE_CACHE_PATH`) to enable byte-range seeking on subsequent requests.
+- Cached transcode artifacts are auto-pruned by age (`TRANSCODE_CLEANUP_INTERVAL_SEC` / `TRANSCODE_ARTIFACT_MAX_AGE_SEC`).
+
 ## Run
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plexsonic",
-  "version": "0.1.12",
+  "version": "0.1.20",
   "description": "PlexMusic to OpenSubsonic bridge",
   "main": "./src/index.js",
   "bin": {

package/src/config.js

@@ -28,6 +28,8 @@ const DEFAULT_PLEX_PRODUCT = 'Plexsonic Bridge';
 const DEFAULT_SESSION_SECRET = 'dev-session-secret-change-me-before-production-plexsonic';
 const DEFAULT_LOG_LEVEL = 'warn';
 const DEFAULT_LOG_REQUESTS = false;
+const DEFAULT_TRANSCODE_CLEANUP_INTERVAL_SECONDS = 3600;
+const DEFAULT_TRANSCODE_ARTIFACT_MAX_AGE_SECONDS = 604800;
 
 function parsePort(rawPort) {
   const value = Number.parseInt(rawPort ?? `${DEFAULT_PORT}`, 10);
@@ -57,6 +59,17 @@ function parseBoolean(value, fallback = false) {
   return ['1', 'true', 'yes', 'on'].includes(normalized);
 }
 
+function parseNonNegativeInt(value, fallback) {
+  if (value == null || value === '') {
+    return fallback;
+  }
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
 function normalizeOptionalBaseUrl(rawBaseUrl) {
   const value = String(rawBaseUrl || '').trim();
   if (!value) {
@@ -77,12 +90,26 @@ export function loadConfig(env = process.env) {
   const bindHost = env.BIND_HOST || DEFAULT_HOST;
   const baseUrl = normalizeOptionalBaseUrl(env.BASE_URL);
   const sqlitePath = env.SQLITE_PATH || './data/app.db';
+  const cacheSqlitePath = env.CACHE_SQLITE_PATH || './data/cache.db';
+  const transcodeCachePath = env.TRANSCODE_CACHE_PATH || './data/transcodes';
+  const transcodeCleanupIntervalSeconds = parseNonNegativeInt(
+    env.TRANSCODE_CLEANUP_INTERVAL_SEC,
+    DEFAULT_TRANSCODE_CLEANUP_INTERVAL_SECONDS,
+  );
+  const transcodeArtifactMaxAgeSeconds = parseNonNegativeInt(
+    env.TRANSCODE_ARTIFACT_MAX_AGE_SEC,
+    DEFAULT_TRANSCODE_ARTIFACT_MAX_AGE_SECONDS,
+  );
 
   return {
     bindHost,
     baseUrl,
     port,
     sqlitePath,
+    cacheSqlitePath,
+    transcodeCachePath,
+    transcodeCleanupIntervalSeconds,
+    transcodeArtifactMaxAgeSeconds,
     sessionSecret: normalizeSessionSecret(env.SESSION_SECRET),
     tokenEncKey: env.TOKEN_ENC_KEY || null,
     plexInsecureTls: env.PLEX_INSECURE_TLS === '1',

package/src/db.js

@@ -121,6 +121,221 @@ export function migrate(db) {
   }
 }
 
+export function migrateCache(db) {
+  const hasCacheAlbumTable = Boolean(
+    db.prepare(`
+      SELECT 1 AS exists_flag
+      FROM sqlite_master
+      WHERE type = 'table' AND name = 'plex_library_cache_albums'
+      LIMIT 1
+    `).get(),
+  );
+  if (hasCacheAlbumTable) {
+    const albumColumns = db.prepare(`PRAGMA table_info(plex_library_cache_albums)`).all();
+    const hasPlayCountColumn = albumColumns.some((column) => column.name === 'play_count');
+    if (!hasPlayCountColumn) {
+      db.exec(`
+        DROP TABLE IF EXISTS plex_library_cache_track_album_artists;
+        DROP TABLE IF EXISTS plex_library_cache_track_artists;
+        DROP TABLE IF EXISTS plex_library_cache_track_genres;
+        DROP TABLE IF EXISTS plex_library_cache_tracks;
+        DROP TABLE IF EXISTS plex_library_cache_album_genres;
+        DROP TABLE IF EXISTS plex_library_cache_albums;
+        DROP TABLE IF EXISTS plex_library_cache_artists;
+        DROP TABLE IF EXISTS plex_library_cache_state;
+      `);
+    }
+  }
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS plex_library_cache_state (
+      cache_key TEXT PRIMARY KEY,
+      last_fingerprint TEXT NOT NULL DEFAULT '',
+      last_checked_at INTEGER NOT NULL DEFAULT 0,
+      last_synced_at INTEGER NOT NULL DEFAULT 0,
+      dirty INTEGER NOT NULL DEFAULT 0,
+      updated_at INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS plex_library_cache_artists (
+      cache_key TEXT NOT NULL,
+      rating_key TEXT NOT NULL,
+      order_index INTEGER NOT NULL DEFAULT 0,
+      sort_key TEXT NOT NULL DEFAULT '',
+      title TEXT,
+      title_sort TEXT,
+      summary TEXT,
+      thumb TEXT,
+      key_path TEXT,
+      guid TEXT,
+      source_uri TEXT,
+      added_at INTEGER,
+      updated_at INTEGER,
+      user_rating INTEGER,
+      child_count INTEGER,
+      leaf_count INTEGER,
+      album_count INTEGER,
+      type TEXT,
+      updated_cache_at INTEGER NOT NULL,
+      PRIMARY KEY (cache_key, rating_key)
+    );
+
+    CREATE TABLE IF NOT EXISTS plex_library_cache_albums (
+      cache_key TEXT NOT NULL,
+      rating_key TEXT NOT NULL,
+      order_index INTEGER NOT NULL DEFAULT 0,
+      sort_key TEXT NOT NULL DEFAULT '',
+      title TEXT,
+      title_sort TEXT,
+      original_title TEXT,
+      parent_rating_key TEXT,
+      parent_title TEXT,
+      thumb TEXT,
+      key_path TEXT,
+      guid TEXT,
+      source_uri TEXT,
+      added_at INTEGER,
+      updated_at INTEGER,
+      last_viewed_at INTEGER,
+      user_rating INTEGER,
+      play_count INTEGER,
+      child_count INTEGER,
+      leaf_count INTEGER,
+      duration INTEGER,
+      year INTEGER,
+      type TEXT,
+      updated_cache_at INTEGER NOT NULL,
+      PRIMARY KEY (cache_key, rating_key)
+    );
+
+    CREATE TABLE IF NOT EXISTS plex_library_cache_album_genres (
+      cache_key TEXT NOT NULL,
+      album_rating_key TEXT NOT NULL,
+      order_index INTEGER NOT NULL DEFAULT 0,
+      genre_name TEXT NOT NULL,
+      PRIMARY KEY (cache_key, album_rating_key, genre_name)
+    );
+
+    CREATE TABLE IF NOT EXISTS plex_library_cache_tracks (
+      cache_key TEXT NOT NULL,
+      rating_key TEXT NOT NULL,
+      order_index INTEGER NOT NULL DEFAULT 0,
+      sort_key TEXT NOT NULL DEFAULT '',
+      title TEXT,
+      title_sort TEXT,
+      original_title TEXT,
+      parent_rating_key TEXT,
+      parent_title TEXT,
+      grandparent_rating_key TEXT,
+      grandparent_title TEXT,
+      artist_id TEXT,
+      key_path TEXT,
+      guid TEXT,
+      source_uri TEXT,
+      thumb TEXT,
+      added_at INTEGER,
+      updated_at INTEGER,
+      last_viewed_at INTEGER,
+      user_rating INTEGER,
+      view_count INTEGER,
+      duration INTEGER,
+      track_index INTEGER,
+      parent_index INTEGER,
+      disc_number INTEGER,
+      parent_year INTEGER,
+      year INTEGER,
+      media_bitrate INTEGER,
+      media_container TEXT,
+      part_size INTEGER,
+      part_file TEXT,
+      audio_sampling_rate INTEGER,
+      audio_bit_depth INTEGER,
+      audio_stream_language TEXT,
+      composer TEXT,
+      country TEXT,
+      style TEXT,
+      mood TEXT,
+      record_label TEXT,
+      language TEXT,
+      album_type TEXT,
+      is_compilation INTEGER,
+      is_soundtrack INTEGER,
+      type TEXT,
+      updated_cache_at INTEGER NOT NULL,
+      PRIMARY KEY (cache_key, rating_key)
+    );
+
+    CREATE TABLE IF NOT EXISTS plex_library_cache_track_genres (
+      cache_key TEXT NOT NULL,
+      track_rating_key TEXT NOT NULL,
+      order_index INTEGER NOT NULL DEFAULT 0,
+      genre_name TEXT NOT NULL,
+      PRIMARY KEY (cache_key, track_rating_key, genre_name)
+    );
+
+    CREATE TABLE IF NOT EXISTS plex_library_cache_track_artists (
+      cache_key TEXT NOT NULL,
+      track_rating_key TEXT NOT NULL,
+      order_index INTEGER NOT NULL DEFAULT 0,
+      artist_id TEXT,
+      artist_name TEXT NOT NULL,
+      PRIMARY KEY (cache_key, track_rating_key, order_index)
+    );
+
+    CREATE TABLE IF NOT EXISTS plex_library_cache_track_album_artists (
+      cache_key TEXT NOT NULL,
+      track_rating_key TEXT NOT NULL,
+      order_index INTEGER NOT NULL DEFAULT 0,
+      artist_id TEXT,
+      artist_name TEXT NOT NULL,
+      PRIMARY KEY (cache_key, track_rating_key, order_index)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_cache_artists_order
+      ON plex_library_cache_artists(cache_key, order_index);
+    CREATE INDEX IF NOT EXISTS idx_cache_artists_title
+      ON plex_library_cache_artists(cache_key, sort_key);
+    CREATE INDEX IF NOT EXISTS idx_cache_artists_rating
+      ON plex_library_cache_artists(cache_key, rating_key);
+    CREATE INDEX IF NOT EXISTS idx_cache_artists_starred
+      ON plex_library_cache_artists(cache_key, user_rating, order_index);
+
+    CREATE INDEX IF NOT EXISTS idx_cache_albums_order
+      ON plex_library_cache_albums(cache_key, order_index);
+    CREATE INDEX IF NOT EXISTS idx_cache_albums_title
+      ON plex_library_cache_albums(cache_key, sort_key);
+    CREATE INDEX IF NOT EXISTS idx_cache_albums_parent
+      ON plex_library_cache_albums(cache_key, parent_rating_key);
+    CREATE INDEX IF NOT EXISTS idx_cache_albums_rating
+      ON plex_library_cache_albums(cache_key, rating_key);
+    CREATE INDEX IF NOT EXISTS idx_cache_albums_starred
+      ON plex_library_cache_albums(cache_key, user_rating, order_index);
+
+    CREATE INDEX IF NOT EXISTS idx_cache_album_genres_name
+      ON plex_library_cache_album_genres(cache_key, genre_name);
+
+    CREATE INDEX IF NOT EXISTS idx_cache_tracks_order
+      ON plex_library_cache_tracks(cache_key, order_index);
+    CREATE INDEX IF NOT EXISTS idx_cache_tracks_title
+      ON plex_library_cache_tracks(cache_key, sort_key);
+    CREATE INDEX IF NOT EXISTS idx_cache_tracks_parent
+      ON plex_library_cache_tracks(cache_key, parent_rating_key);
+    CREATE INDEX IF NOT EXISTS idx_cache_tracks_grandparent
+      ON plex_library_cache_tracks(cache_key, grandparent_rating_key);
+    CREATE INDEX IF NOT EXISTS idx_cache_tracks_rating
+      ON plex_library_cache_tracks(cache_key, rating_key);
+    CREATE INDEX IF NOT EXISTS idx_cache_tracks_starred
+      ON plex_library_cache_tracks(cache_key, user_rating, order_index);
+
+    CREATE INDEX IF NOT EXISTS idx_cache_track_genres_name
+      ON plex_library_cache_track_genres(cache_key, genre_name);
+    CREATE INDEX IF NOT EXISTS idx_cache_track_artists_artist
+      ON plex_library_cache_track_artists(cache_key, artist_id, artist_name);
+    CREATE INDEX IF NOT EXISTS idx_cache_track_album_artists_artist
+      ON plex_library_cache_track_album_artists(cache_key, artist_id, artist_name);
+  `);
+}
+
 export function createRepositories(db) {
   const createAccountStmt = db.prepare(`
     INSERT INTO accounts (id, username, password_hash, subsonic_password_enc, enabled, created_at)
@@ -265,6 +480,23 @@ export function createRepositories(db) {
     LEFT JOIN plex_selected_library psl ON psl.account_id = a.id
     WHERE a.id = ?
   `);
+  const listAccountPlexContextsStmt = db.prepare(`
+    SELECT
+      a.id AS account_id,
+      a.username AS username,
+      a.enabled AS enabled,
+      pl.plex_token_enc AS plex_token_enc,
+      pss.machine_id AS machine_id,
+      pss.name AS server_name,
+      pss.base_url AS server_base_url,
+      pss.server_token_enc AS server_token_enc,
+      psl.music_section_id AS music_section_id,
+      psl.music_section_name AS music_section_name
+    FROM accounts a
+    LEFT JOIN plex_links pl ON pl.account_id = a.id
+    LEFT JOIN plex_selected_server pss ON pss.account_id = a.id
+    LEFT JOIN plex_selected_library psl ON psl.account_id = a.id
+  `);
 
   const deletePlexLinkStmt = db.prepare(`
     DELETE FROM plex_links
@@ -409,6 +641,10 @@ export function createRepositories(db) {
       return getAccountPlexContextStmt.get(accountId) || null;
     },
 
+    listAccountPlexContexts() {
+      return listAccountPlexContextsStmt.all() || [];
+    },
+
     unlinkPlex(accountId) {
       const tx = db.transaction(() => {
         deleteSelectedLibraryStmt.run(accountId);

package/src/plex.js

@@ -198,6 +198,83 @@ function extractMetadataList(container) {
   return asArray(container.Metadata ?? container.Directory ?? container.Video ?? container.Track ?? []);
 }
 
+function parseContainerTotalSize(container) {
+  const parsed = Number.parseInt(String(container?.totalSize ?? ''), 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return null;
+  }
+  return parsed;
+}
+
+async function fetchAllMetadataPages({
+  baseUrl,
+  plexToken,
+  path,
+  searchParams = null,
+  signal = undefined,
+  pageSize = 1000,
+}) {
+  const normalizedPageSize = Math.min(Math.max(Number.parseInt(String(pageSize), 10) || 1000, 1), 2000);
+  const merged = [];
+  const seenRatingKeys = new Set();
+  let start = 0;
+  let totalSize = null;
+  let attempts = 0;
+
+  while (attempts < 2000) {
+    const payload = await fetchPmsJson(
+      baseUrl,
+      plexToken,
+      path,
+      {
+        ...(searchParams || {}),
+        'X-Plex-Container-Start': start,
+        'X-Plex-Container-Size': normalizedPageSize,
+      },
+      { signal },
+    );
+    const container = payload?.MediaContainer || {};
+    const page = extractMetadataList(container);
+    const pageTotalSize = parseContainerTotalSize(container);
+    if (pageTotalSize != null) {
+      totalSize = pageTotalSize;
+    }
+
+    if (page.length === 0) {
+      break;
+    }
+
+    let added = 0;
+    for (const item of page) {
+      const ratingKey = String(item?.ratingKey ?? '').trim();
+      if (ratingKey) {
+        if (seenRatingKeys.has(ratingKey)) {
+          continue;
+        }
+        seenRatingKeys.add(ratingKey);
+      }
+      merged.push(item);
+      added += 1;
+    }
+
+    start += page.length;
+    attempts += 1;
+
+    if (totalSize != null && start >= totalSize) {
+      break;
+    }
+    if (page.length < normalizedPageSize) {
+      break;
+    }
+    if (added === 0) {
+      // Guard against servers that ignore paging and keep returning the same page.
+      break;
+    }
+  }
+
+  return merged;
+}
+
 function normalizeLibrarySection(section) {
   const parseTimestamp = (value) => {
     const parsed = Number.parseInt(String(value ?? ''), 10);
@@ -806,27 +883,36 @@ export async function searchSectionHubs({
 }
 
 export async function listArtists({ baseUrl, plexToken, sectionId }) {
-  const payload = await fetchPmsJson(baseUrl, plexToken, `/library/sections/${encodeURIComponent(sectionId)}/all`, {
-    type: 8,
+  return fetchAllMetadataPages({
+    baseUrl,
+    plexToken,
+    path: `/library/sections/${encodeURIComponent(sectionId)}/all`,
+    searchParams: {
+      type: 8,
+    },
   });
-
-  return extractMetadataList(payload.MediaContainer);
 }
 
 export async function listAlbums({ baseUrl, plexToken, sectionId }) {
-  const payload = await fetchPmsJson(baseUrl, plexToken, `/library/sections/${encodeURIComponent(sectionId)}/all`, {
-    type: 9,
+  return fetchAllMetadataPages({
+    baseUrl,
+    plexToken,
+    path: `/library/sections/${encodeURIComponent(sectionId)}/all`,
+    searchParams: {
+      type: 9,
+    },
   });
-
-  return extractMetadataList(payload.MediaContainer);
 }
 
 export async function listTracks({ baseUrl, plexToken, sectionId }) {
-  const payload = await fetchPmsJson(baseUrl, plexToken, `/library/sections/${encodeURIComponent(sectionId)}/all`, {
-    type: 10,
+  return fetchAllMetadataPages({
+    baseUrl,
+    plexToken,
+    path: `/library/sections/${encodeURIComponent(sectionId)}/all`,
+    searchParams: {
+      type: 10,
+    },
   });
-
-  return extractMetadataList(payload.MediaContainer);
 }
 
 export async function probeSectionFingerprint({ baseUrl, plexToken, sectionId, signal = undefined }) {
@@ -868,19 +954,25 @@ export async function getArtist({ baseUrl, plexToken, artistId }) {
 }
 
 export async function listArtistAlbums({ baseUrl, plexToken, artistId }) {
-  const payload = await fetchPmsJson(baseUrl, plexToken, `/library/metadata/${encodeURIComponent(artistId)}/children`, {
-    type: 9,
+  return fetchAllMetadataPages({
+    baseUrl,
+    plexToken,
+    path: `/library/metadata/${encodeURIComponent(artistId)}/children`,
+    searchParams: {
+      type: 9,
+    },
   });
-
-  return extractMetadataList(payload.MediaContainer);
 }
 
 export async function listArtistTracks({ baseUrl, plexToken, artistId }) {
-  const payload = await fetchPmsJson(baseUrl, plexToken, `/library/metadata/${encodeURIComponent(artistId)}/allLeaves`, {
-    type: 10,
+  return fetchAllMetadataPages({
+    baseUrl,
+    plexToken,
+    path: `/library/metadata/${encodeURIComponent(artistId)}/allLeaves`,
+    searchParams: {
+      type: 10,
+    },
   });
-
-  return extractMetadataList(payload.MediaContainer);
 }
 
 export async function getAlbum({ baseUrl, plexToken, albumId }) {
@@ -893,11 +985,14 @@ export async function getAlbum({ baseUrl, plexToken, albumId }) {
 }
 
 export async function listAlbumTracks({ baseUrl, plexToken, albumId }) {
-  const payload = await fetchPmsJson(baseUrl, plexToken, `/library/metadata/${encodeURIComponent(albumId)}/children`, {
-    type: 10,
+  return fetchAllMetadataPages({
+    baseUrl,
+    plexToken,
+    path: `/library/metadata/${encodeURIComponent(albumId)}/children`,
+    searchParams: {
+      type: 10,
+    },
   });
-
-  return extractMetadataList(payload.MediaContainer);
 }
 
 export async function getTrack({ baseUrl, plexToken, trackId, signal = undefined }) {