3.1.0

[Gyarbij]

Plexist 3.1.0

Plexist 3.1.0 is a substantial reliability, matching, authentication, and persistence update building on the multi-service sync functionality introduced in 3.0.0.

This release significantly reworks how Plexist matches streaming-service tracks against Plex libraries, updates authentication handling for Spotify and Tidal, introduces versioned database migrations, reduces unnecessary Plex API traffic, and adds considerably more automated test coverage across the core sync pipeline.

Major Highlights

• Major Plex track-matching overhaul

  • Reworked the matching pipeline into clearly defined matching stages.
  • Added Plex native library matching as an additional fallback for MusicBrainz MBIDs.
  • Improved ISRC → MusicBrainz MBID → Plex matching.
  • Reduced unnecessary live Plex searches by preferring local caches and indexes.
  • Added batched hydration of matched Plex tracks while preserving playlist order.

• Spotify authentication updated

  • Updated Spotify integration for the current OAuth authorization flow.
  • Added configuration for redirect URI, token cache location, and authorization responses.
  • Improved cached-token handling and Spotify API error reporting.
  • Resolves the Spotify 403 Forbidden startup/sync issue reported in [#138](Spotify returns 403 while starting sync #138).

• Tidal authentication fixed

  • Fixed Tidal authentication failing with tidalapi 0.8.11 because SessionType.TIDAL is no longer available.
  • Plexist now uses the supported OAuth Bearer token type when restoring Tidal sessions.
  • Added regression coverage for Tidal session creation.
  • Resolves the Tidal SESSION_TYPE authentication failure reported by users after the 3.0.0 release.

• Versioned database migrations

  • Added a proper schema migration system instead of ad-hoc table creation and alteration.
  • Existing databases are automatically adopted without discarding cached data.
  • Migration steps are transactional and roll back on failure.
  • SQLite WAL mode is now enabled for improved database reliability.

• Persistent Plex cache improvements

  • Replaced detached plexapi.Track reconstruction with lightweight cached track snapshots.
  • Fixes startup crashes when restoring populated Plex caches with newer plexapi versions.
  • Plex metadata is now cached without triggering hidden per-track network requests.
  • Plex GUID/MBID information is fetched and indexed more efficiently.

• Improved application lifecycle

  • Added graceful handling for SIGTERM and SIGINT.
  • Docker/container shutdowns now terminate Plexist cleanly instead of abruptly stopping the sync loop.
  • Improved startup, authorization, sleep-cycle, and shutdown logging.

---

Plex Matching Improvements

Track matching has received one of the largest internal changes since Plexist's initial matching implementation.

The matching pipeline now uses the following progression:

1. ISRC GUID matching
2. MusicBrainz ISRC → MBID resolution
3. Local Plex MBID index
4. Plex native /library/matches matching
5. Normalized metadata matching
6. Duration-aware partial matching
7. Artist-index matching
8. Exact cache-key matching
9. Strict and progressively relaxed Plex metadata searches

Plex's native matcher is now queried for MusicBrainz GUIDs when an MBID cannot be resolved directly through Plexist's local index. Only sufficiently confident native Plex matches are accepted.

This particularly improves matching for libraries where Plex knows the MusicBrainz identity of a track internally but normal library search does not expose the expected ISRC/MBID lookup behavior.

The matching changes also further address the behavior discussed in [#104](#104), where Plex does not expose ISRC metadata in the same way streaming services do.

Matching performance

Several unnecessary Plex requests have also been removed:

• Cached tracks no longer call artist() or album() and trigger additional HTTP requests.
• Plex cache construction requests GUID information inline.
• Cache/index matches are preferred before live searches.
• Matched cached tracks are hydrated back into live Plex objects in batches.
• MBID indexes are maintained incrementally while the cache is built.

Matching thresholds and the general preference for high-confidence matches remain conservative.

---

Database & Cache Reliability

Plexist now includes a dedicated database migration framework.

New migration system

Database migrations are:

• Versioned
• Ordered
• Transactional
• Idempotent
• Automatically applied during startup

Existing Plexist databases are detected and upgraded by adding only missing schema elements.

The migration baseline manages:

• plex_cache
• liked_tracks
• isrc_mbid_cache
• plex_mbid_index
• schema_migrations

Existing legacy data is retained.

SQLite now also runs with WAL journaling enabled.

Fixed populated-cache startup failure

Previous cache restoration attempted to reconstruct plexapi.audio.Track objects directly from stored dictionaries.

Newer versions of plexapi expect XML elements during object construction, which could cause Plexist to crash on startup when a populated cache was loaded.

Plexist now stores and restores immutable cached track snapshots containing the metadata required for matching, avoiding that failure and removing unnecessary network requests during cache initialization.

---

Spotify

Spotify support has been updated to better reflect the current Spotify authorization model.

New configuration options

Support has been added for:

• SPOTIFY_REDIRECT_URI
• Spotify token/cache path configuration
• Spotify authorization response configuration

The provider now has improved handling for:

• OAuth authorization
• Existing cached tokens
• Playlist pagination
• API authorization failures
• User-facing error reporting

This resolves the fresh-install Spotify 403 Forbidden behavior reported in [#138](#138).

Users upgrading from older Spotify configurations should review the updated Spotify configuration instructions in the README.

---

Tidal

Tidal authentication has been corrected for compatibility with the current tidalapi dependency.

Plexist 3.0.0 attempted to restore OAuth sessions using:

tidalapi.SessionType.TIDAL

That enum value is not available in tidalapi 0.8.11, causing Tidal authentication to fail before synchronization could begin.

Plexist now restores Tidal OAuth sessions using the supported:

Bearer

token type.

Regression tests now verify that saved access tokens, refresh tokens, and expiry information are passed correctly when creating an authenticated Tidal session.

This fixes the SESSION_TYPE failure reported by users following the 3.0.0 release.

---

Apple Music

Apple Music handling and tests have also been expanded.

Improvements include:

• Better extraction of ISRC metadata from Apple Music catalog relationships.
• Improved catalog metadata enrichment.
• Improved handling of incomplete or unavailable catalog metadata.
• Additional error-path coverage.

---

Sync Orchestration

The multi-service sync orchestrator introduced in Plexist 3.0.0 has received additional hardening.

Improvements include:

• Better routing of sync operations to Plex destinations.
• Improved handling of liked-track synchronization.
• Better propagation and handling of provider errors.
• Additional tests around source/destination orchestration.

---

Container & Runtime Improvements

• Python container base updated to Python 3.14.7.
• Improved Docker data-directory handling.
• Improved persistent database path handling and named-volume documentation.
• Graceful container shutdown through SIGTERM/SIGINT handling.
• Docker and GitHub Actions dependencies updated.

---

Developer & CI Improvements

Plexist now includes substantially more automated coverage around the parts of the application most likely to affect sync correctness.

New and expanded tests cover:

• Plex matching stages
• Plex cache serialization/restoration
• Plex native library matching
• MBID matching and fallback behavior
• Database migrations
• Legacy database upgrades
• Migration rollback behavior
• Spotify OAuth
• Spotify pagination
• Spotify error handling
• Tidal OAuth session restoration
• Apple Music catalog enrichment
• Sync orchestration
• Liked-track synchronization
• Configuration handling

ruff has also been added for Python linting.

GitHub Actions and Docker build dependencies have been updated, including newer versions of:

• actions/checkout
• actions/setup-python
• actions/setup-dotnet
• docker/build-push-action
• docker/setup-buildx-action
• docker/setup-qemu-action
• docker/login-action
• sigstore/cosign-installer
• Snyk Docker actions

---

Fixed Issues

• [#138](Spotify returns 403 while starting sync #138) — Spotify returns 403 while starting sync

  • Spotify authentication has been reworked around the supported OAuth authorization flow and persistent token handling.

• [#104](Plex cannot search by isrc #104) — Plex cannot search by ISRC

  • Matching now uses ISRC → MusicBrainz MBID resolution and can delegate unresolved MBIDs to Plex's native /library/matches endpoint before falling back to metadata matching.

• Tidal SESSION_TYPE authentication failure

  • Fixed incompatibility with tidalapi 0.8.11 caused by use of the unavailable SessionType.TIDAL enum.
  • OAuth sessions are now restored using the supported Bearer token type.

---

Upgrade Notes

Spotify users

Spotify users should review the updated authentication configuration before upgrading, particularly if their existing deployment relies on the previous authentication behavior.

Tidal users

No configuration change should normally be required for existing Tidal users.

Plexist 3.1.0 corrects the OAuth session restoration internally and should eliminate the SESSION_TYPE error seen with 3.0.0.

Existing databases

No database reset should be required.

Plexist will automatically migrate existing databases to the new versioned schema during startup.

As always, keeping a backup of your persistent Plexist data volume before upgrading is recommended.

---

What's Changed

• [#145](fix: spotify auth and enhanced app config  #145) — Spotify authentication, application configuration, graceful shutdown, runtime and test improvements
• [#146](refactor(plex): restructure track matching pipeline and add versioned db #146) — Plex matching pipeline refactor, persistent cache overhaul and versioned database migrations
• [#147](feat(plex): enhance track matching with native library integration an… #147) — Plex native library matching integration and expanded matching tests
• [#148](fix(tidal): replace hardcoded token type with constant in session creation #148) — Fix Tidal OAuth session restoration with current tidalapi
• Updated Python and application dependencies
• Updated Docker and GitHub Actions toolchain dependencies

Full Changelog:
3.0.0...3.1.0

---

This discussion was created from the release 3.1.0.