Bring the rest of your music in
A plugin brings one outside music source into rox. rox browses that source, searches it, plays it gapless and keeps what you ask it to, in the same panels and queue as the files on your disk.
What a plugin is
A plugin is a folder holding a small manifest and a program. The program can be a Python script or a native binary, and it talks to rox over its standard input and output. rox starts it the first time something needs it and restarts it if it crashes. Five crashes in ten minutes stop it until you switch it off and on again.
What a plugin can do is a short list: list and search a catalogue, sync collections into your library, serve audio, run a radio, link to its own web pages, and add preset panels under its name. It can't add buttons, change how rox looks or reach into other panels. Plugins bring in sources, and the player around them stays rox's own.
Browsing a source
Each running plugin gets an entry under Add Panel > Plugins, which opens an External Sources panel on its source. The panel lists the plugin's folders, playlists and albums, searches, shows cover art and loads more as you scroll. A service's home page lists under the panel's top level, so it's there without a click.
What else the panel shows depends on the plugin. Chips over a list switch between the plugin's views, like search narrowed to albums. Shelves of covers scroll sideways, and a page of nothing but covers wraps into a grid. Columns the service knows and your tags don't, like a download count, sort with a click on their heading. While one of the plugin's tracks plays, the top level shows it with what's up next.
Playing and keeping
Plugin tracks go in the queue, playlists and history like your own files, and play gapless back to back. A track that drops partway through reconnects and carries on from the same spot. A live stream from a plugin gets pause and the rewind buffer, like a radio station.
Playing a track doesn't add it to your library, and Add to Library keeps it. Hover a collection and click its checkmark to keep the whole thing. It syncs into your library, follows the collection as it changes, and opens from there even with the plugin stopped or the network down.
Open in Browser and Copy Link go to a track's or album's page on the service, from anywhere its tracks show in rox. Scrobbling is off unless the plugin asks for it, and then it's a switch on the plugin's row.
Radio
A plugin with a radio adds Play Similar to its tracks, albums, playlists and artists. An album, playlist or artist plays its own tracks first, while a track only seeds the station and is left out of it. The service's picks then keep the queue going as it runs low. Shuffle switches to Similar, and for the plugin's tracks that works without your library's acoustic analysis. An album you play from the panel goes on the same way when it ends, instead of running into your local library.
The radio's tracks play through rox's own engine like any other track. They don't join your library, the station skips what already played this session, and it carries on after a restart. Turn Keep Playing off in Settings > Playback and the queue stops at its end.
What you're approving
A new plugin shows up switched off. Switching it on is the approval, and the card you confirm says what the plugin is, what it can do, which programs it needs, and that it runs as a program on your computer with your permissions.
The approval covers exactly the files in the plugin's folder. If any of them change, the plugin switches itself off and reads Changed on disk until you approve it again, and the card then shows what changed in its manifest. Remove on the Plugins page drops the plugin's tracks, synced collections, settings and approval, and leaves its folder alone.
Write your own
A plugin speaks JSON-RPC, one message per line over standard input and output, so any language that reads and writes lines will do. The plugin guide covers the manifest, every method, the timeouts and how audio reaches the player. The Plugin Guide button on the Plugins page opens it for the version you're running.
Two examples are in the repository. tones generates sine tones and chords, and it's the one for learning the protocol. Internet Archive uses every optional part of it against a real catalogue, with home shelves, views, columns, radio and links, in Python with nothing beyond the standard library.
Developer mode on a plugin's row approves your own edits to its folder until rox quits, and restarts the plugin each time you save. Each newer part of the protocol is opt-in. rox lists the ones it supports when the plugin starts, so a plugin never has to send something an older rox would refuse.
Where plugins stop
- Plugins bring in sources and nothing else. A foobar2000 component that changed the player itself, like a new panel or a DSP, has no plugin equivalent.
- Script plugins need Python 3 on the machine. Most Linux installs have it, and Windows and macOS usually don't.
- The Flatpak can't see programs installed on the host. It includes Python 3, so a plugin that only needs the standard library runs as is. Anything else has to ship in the plugin's own
binfolder. - A Mac app started from Finder or the Dock doesn't get your shell's PATH, so programs installed with Homebrew show as missing until you add Homebrew's folder to Program Folders in Settings > Plugins.
- On Windows, a native plugin's files can't be replaced while it runs. Switch it off before updating its folder.
Try one
Download rox, turn on Enable Plugins in Settings > Plugins, and copy the Internet Archive example into the plugins folder. It needs the network and no account.