ricercar-plex

A ricercar source plugin that plays the music of your own Plex Media Server.

• Browse: recently added, albums, artists, playlists, favourites and most played, across all the music libraries of the server.
• Library: your server's albums, artists and tracks join ricercar's own Albums, Artists and Tracks pages and its search, marked Plex; your audio playlists join its Playlists. Artists without a picture on the server get the cover of one of their albums.
• Home: recently added, recently played and most played albums, as shelves on ricercar's Home page. With several music libraries on the server, each shelf mixes them.
• Search: artists, albums, tracks and playlists.
• Bit-perfect: tracks play from the original file, byte for byte (seekable). Only when your DAC cannot take a file's sample rate does the plugin ask the server for FLAC at the closest rate the DAC accepts (same 44.1/48 kHz family, never higher than the original). Plex keeps the bit depth of the file when it transcodes, so a 24-bit file on a 16-bit-only DAC is reported as unavailable on that output. A setting sends the original file instead.
• Favourites are five-star ratings, shared with the other Plex apps; ricercar shows which items are rated.
• Plays show on the server while they last (its "now playing") and count in its play history and "most played" once a track is heard to the end, or half of it, or four minutes. A setting turns this off.
• Lyrics the server has for a track (.lrc or .txt files next to it, embedded tags, or its online provider), synced when they are timed.
• Go to a track's album or artist; similar artists and albums, sonically similar tracks and an artist radio from an item's menu.
• Details on artist and album pages: the server's summary, its shelves (popular tracks, similar items…), label, release date, genres, styles and moods.
• Continuous playback: when the queue ends, tracks that sound like the last one, or of its artist and similar artists.
• Playlists: create, rename and delete your audio playlists, add and remove tracks, reorder them. Smart playlists are read-only.
• Loudness: when the server has analysed loudness, the track gain and peak are passed to ricercar.

Similar items and sonically similar tracks depend on what the server knows: its online metadata agents, and sonic analysis (Plex Pass). Without them those lists are empty. Lyrics, details, the radio, playlist editing and settings need a ricercar version that supports them; older ones ignore them.

The plugin uses the documented Plex Media Server API and plex.tv's sign-in only. Tested with Plex Media Server 1.43.

Install

From ricercar (0.4.0 and later): open Plugins in the sidebar and install Plex.

By hand: download plex-x86_64 or plex-aarch64 from the releases, check it against its .sha256 file, make it executable, and declare it in ~/.config/ricercar/config.toml:

[[plugins]]
id = "plex"
command = "/home/you/.local/bin/plex-x86_64"
# args = ["--server", "Attic"]                      # one server among several
# args = ["--server", "http://192.168.1.10:32400"]  # or its address

From source:

cargo build --release
# target/release/ricercar-plex

Sign in

Click Sign in next to Plex in ricercar. The Plex sign-in page opens in your browser; once you have signed in there, the plugin finds your server and ricercar shows it. Your password goes to plex.tv only.

• With several servers on the account, the plugin uses the first one you own that answers. Pick another with --server <name>.
• The plugin tries the addresses plex.tv knows for the server (local first, then remote, then Plex's relay), and switches to another one when the current address stops answering (at home, away). Pass --server <address> to use a fixed address instead.
• The server token is kept in ~/.local/share/ricercar/plugins/plex/auth.json (mode 600). Signing out of ricercar forgets it; to revoke it, remove ricercar from Authorized Devices in your Plex account settings.

Signing in from another computer than the one running ricercar: paste <server address> <token> in ricercar's sign-in field, with an X-Plex-Token of your account.

Notes

• Stream and cover URLs carry the token as a query parameter, as Plex web clients do. Stream URLs are never stored; cover URLs are part of item metadata, so they can end up in ricercar's saved queue and playlists.
• Transcoded streams have no known length, so they cannot be seeked. Originals can.
• To use two servers at once, declare the plugin twice with different ids and --server values.

Protocol

Plugin protocol 1, as described in ricercar's docs/plugins.md, with the library capability (library.albums, library.artists, library.tracks, library.playlists), home shelves, settings (report_playback, transcode), and the lyrics, details, radio and playlist_edit capabilities (playlists.move included).

Ref	Meaning
recent, albums, artists, playlists, favorites, frequent	Top-level sections
recent, played, top	Home shelves: albums recently added, recently played, most played
t/<ratingKey>	Track
a/<ratingKey>	Album
r/<ratingKey>	Artist (its albums)
p/<ratingKey>	Playlist
sim/<ratingKey>	Artists or albums similar to an artist or album
sonic/<ratingKey>	Tracks that sound like a track
radio/<ratingKey>	Radio from a track, album or artist

Error codes follow the protocol: a refused token marks the session expired (auth_required) and sends auth.changed; missing items answer not_found; files the output cannot take answer unavailable; unreachable servers answer network.

Development

cargo test
cargo clippy --all-targets
tests/plex.sh     # end to end against a throwaway Plex Media Server (docker, ffmpeg)

The CI builds static binaries (musl) for x86_64 and aarch64 on every tag v* and attaches them, with their SHA-256, to a GitHub release. contrib/hub-entry.toml is the entry for the ricercar plugin hub.

Licence

MIT. Plex is a trademark of Plex, Inc.; this plugin is not affiliated with or endorsed by Plex.