Plugins

A plugin adds something to your server that did not ship with it. A metadata source for a collection nothing else identifies properly, extra detail on a film’s page, a service you use that we have not built support for.

Plugins are free. Installing one is the owner’s job: you decide what runs on your server, and nobody else on it can install, remove or update anything.

Two things are each person’s own, though, and those live in every app: whether a plugin is told what they watch, and any setting a plugin marks as personal. Both are covered below.

Installing one

Installing and configuring happens in a browser. Open your server and go to Settings → Plugins.

The card lists what you already have, one row each: its icon, its name and version, and a line about what it does. Browse the marketplace, at the top right, is the catalog: everything we host, with what each one does and who wrote it. If you have nothing installed yet, the card is mostly that button.

Before you install anything, the row tells you what that plugin will be allowed to do, in plain words:

• Can contact api.example.com means it can talk to that one address and nowhere else.
• Can save its own settings and cached data means it gets a small private store on your server.
• Can check whether specific titles are in your library, and never what else is there means it can ask about titles it already knows the name of, one list at a time, and get back only the ones you have. There is no way for it to take an inventory of your library.
• Runs on its own, with no network and no storage means exactly that.

That list is the whole of it. There is no fine print and no second screen of permissions after you press Install.

Press Install. The plugin downloads, gets checked, and starts. It then has a row of its own, with Settings beside it: that opens everything about that one plugin, which is where its settings live, along with what it is allowed to do and any buttons it offers. A plugin with nothing to set still opens, and says so.

Some plugins set themselves up in that same press. A channel makes its own libraries as it installs, and the row tells you which ones before you press it and names them again once they are there, so there is nothing to add afterwards and nothing to guess at. The first sync then runs on its own, which is why a new channel fills in over the next few minutes rather than all at once.

If a plugin cannot finish setting itself up, it stays installed and says what went wrong, with Try again beside it. Nothing is half-removed, nothing is switched off behind your back, and a second press after the service it needs comes back is all it takes.

While a plugin is doing something slow, it says so in the Activity section of your server settings, with a line naming what it is working on. That is where a first sync of a big channel shows up.

Some plugins need a newer server than the one you are running. If yours is too old, nothing is installed: the card answers with the version that plugin needs, and you can update your server from Settings → Server and press Install again. This is deliberate. A plugin that needs something your server does not have yet would otherwise install, run, and quietly draw nothing.

Settings, and whose they are

Most plugin settings are the server’s: you set them once and they are the same for everyone in the house. Those are the rows on the plugin’s card.

Some settings belong to each person instead. Those do not appear on your card, because they are not yours to set for somebody else. The card names them, and everyone sets their own:

• In the apps (Apple TV, iPhone, iPad, Android phone, Android TV): Settings → Plugins, under Plugin preferences.
• In a browser: your own settings, in the same Plugin preferences section.

Your housemates each get their own, and nobody sees anyone else’s. If no plugin on the server has anything personal to ask, the section is not there at all.

A plugin can also put a button on its card, like “Test connection”. Pressing it runs the plugin and shows you one line back. That is all a button can do: it cannot draw anything, and it cannot ask for anything you have not already given the plugin. A plugin can put a button on the personal screen too, and that one is the only kind that knows which person pressed it.

Connecting your own account

Some plugins work with a service you already have an account with, like a watch-tracking site. Those need each person to connect their own account, and that is deliberately not something an owner can do on somebody’s behalf.

You will find them in the same place as your preferences, under Connected accounts: Settings → Plugins in the apps, or your own settings in a browser. Each one says what it would be told before you decide, for example If you connect it, it will be told what you start, pause and finish watching. Nothing is sent until you do.

Press Connect and you get a short code and a web address to open on your phone or computer. Finish there and the row says who you connected as.

Until you do that, the plugin is never told you exist. There is no server setting that could start it for you, and an owner who installs a scrobbler has not connected anybody to it, including themselves.

Disconnect stops it immediately and makes the server forget the account you connected. Nothing more is sent, whatever the far end does about it.

What a plugin can and cannot do

Every plugin runs in a sandbox inside your server. It has no access to your files, no way to reach your home network, and no way to see another plugin’s data. It gets the permissions above if it asked for them, and nothing else.

A plugin that asks to contact an address can only reach that address on the public internet. It cannot use that permission to reach your router, your NAS, or anything else on your network: those are refused, including when a site tries to redirect it there.

Plugins never run code on your TV, your phone, or in your browser. They hand information to your server, and your server hands it to the apps, which draw it themselves. That is why a plugin works on every screen without anyone writing a version for each one.

Plugins that add skip markers

Some plugins supply the Skip Intro and Skip Credits markers. They are asked once per title, while your server is analyzing the file, and the answer is stored: nothing waits on a plugin when you press play.

Your own edits always win. So do the chapters written into a file. A plugin sits below both of those and above the server’s own detection, so installing one fills in the titles nothing had marked and never overrules a marker you fixed by hand.

If you install two of them, a Skip markers list appears under your plugins with them in order, and the one nearest the top wins wherever they disagree. Removing a plugin takes its markers with it.

A library with intro or credits detection switched off (Settings, per library) stays that way. The switch is about what that library should have, not about which part of the server found it.

Plugins that find subtitles

Some plugins can look up subtitles for a title. Nothing is downloaded on its own: you open a title, choose Find subtitles from its manage menu, and pick from what comes back.

That is on purpose. Most subtitle files for a popular film are timed against a particular release, and one that was made for a different cut runs a few seconds out for the whole film. The release name is shown beside each result so you can pick the one that matches your copy.

What you add becomes an ordinary subtitle track: it shows up in the subtitle list on every screen, next to the ones that came with the file. It is stored inside your server’s own data folder, never written next to your media.

You can remove a subtitle you added from the same place. Removing the plugin does not remove them: you chose those.

Theme packs

Some plugins are just a look. A theme pack adds its themes to the picker beside the built-in ones, on every screen, and it contains no code at all: nothing from it ever runs on your server.

You stay in charge of them. Any theme from a pack can be switched off, or made the one new people get, exactly like a theme you made yourself. You cannot edit one in the theme editor, because it belongs to the pack and the next update would undo your change. Copy the colours into a theme of your own if you want to adjust them.

Removing the pack removes its themes. Anyone using one goes back to your server’s default.

Plugins that add to search

Some plugins can add to what you find when you search. Their results appear under your own library’s, in their own section with the plugin’s name on it, so it is always clear where a row came from.

They never slow your search down. The server gives a plugin a fraction of a second; anything slower is left to finish in the background and its section appears a moment later instead of holding up your results.

Profiles with a content rating limit do not see these sections. A plugin’s results come from outside your library, so there is no rating on them to check against the limit you set, and showing them anyway would go around it.

Plugins that are libraries

Some plugins are a library. Instead of describing what you already have, they supply titles of their own: a feed, a service, a channel you follow. What they produce is an ordinary film or episode. It browses, it sorts, it resumes where you left it, it goes in playlists, it counts as watched, and it sits under the same content rating limit as everything else, because it is the same kind of row.

There are two kinds, and the difference is whose it is.

A library anyone in the house can watch. The owner adds it in Settings, under Libraries: choose New library, then pick the plugin under Titles from and fill in whatever it asks for. It syncs on its own from then on, and Scan asks it for the catalog again. To get rid of it, open its settings and choose Remove this library.

A library that is yours. Some plugins need your own account. There is nothing to add: you connect the account on your own settings screen, and the library appears for you. Nobody else in the house sees it, and it disappears when you disconnect, along with everything in it. If you have not set a PIN or signed in, the server has no way to tell it is really you, so a private library stays hidden until you do.

Playing them. Everything is fetched by your server and sent to your devices the same way your own files are. A plugin’s address, its account token and whatever else it needs never leave the server, so your TV only ever talks to your server, exactly as it does for a film on your disk. That does mean these always go through the server rather than playing straight off a disk, so they use a little more of it than a local file would.

What they cannot do. You cannot download a film or an episode from one for offline viewing: offline video expects a file your server owns, and there is not one. There are no scrubbing thumbnails, no intro and credits markers and no Optimize on them either, for the same reason: all of those are made from a file. What you get instead is the title itself, and everything about it that lives on the server.

Podcasts and audiobooks. A plugin library can also be a podcast library (shows and their episodes) or an audiobook library (books, each one book however many files it came in). They show up where your own podcasts and audiobooks do, play in the audio player with your speed, skip and sleep settings, sit in Keep Listening, and take bookmarks. On a phone you can download them for offline listening, because the server fetches each file for you just as it does when you press Play. A few differences from the podcasts you subscribe to yourself: the plugin decides which shows the library holds, so you cannot add a feed to it or remove one of its shows, and Refresh on one of its shows asks the plugin for the whole library again. An episode the plugin stops offering is removed only if nobody in the house played, bookmarked, downloaded or saved it; anything somebody touched stays. Apps that were released before audio arrived do not show these libraries at all, the same as with podcasts and audiobooks from your own folders.

Channels

Some plugins are a whole channel. It shows up as a card in a Channels row on your home page, and opening it gets you a page of its own: a banner, some shelves, whatever else that plugin put there. Behind it are libraries the plugin supplies, the same kind as the ones above.

Its libraries are not in your library list. They belong to the channel, and the channel is where you browse them, so listing them again beside your own would be the same titles in two places. Nothing is hidden from the rest of the app, though: those titles still turn up in search, in Keep Watching, in playlists and in the play queue, under the same content rating limit as everything else you have.

Some channels bring their own colours. A channel can carry a look of its own, and you see it while you are inside it: on the channel’s page, on the page for any of its films or shows however you got there, and in the player while one of them is playing. Everything else keeps the theme you picked, including your home page and every row of cards on it, because one row can hold titles from several channels at once.

If you would rather keep your own colours everywhere, there is a switch for that beside your theme in your own settings: Always use my theme. It is yours alone and changes nothing for anybody else in the house. Anything you downloaded and watch offline uses your theme too.

A channel whose colours would leave something unreadable does not install at all, and the card says which pairing failed. That is stricter than the check on a theme you build yourself, which warns you and saves it anyway: you chose your own colours, and nobody chooses a channel’s.

The page is yours to arrange. The plugin ships a layout with it, and from then on it is your page. Open the channel and choose Edit layout. You can move a row up or down, hide one you do not want, change how a row is sorted, which card it draws and how many titles it holds, and add rows of your own: a shelf from one of the channel’s libraries, a banner, a shelf from one of your collections, or a heading. Reset to the plugin’s default puts the whole page back.

Rows the plugin draws itself are marked as the plugin’s. You can move one or hide it, but not retune it, because the plugin is what fills it.

An update does not undo your arrangement. If a new version of the plugin adds a row, it appears at the bottom of your page rather than in the middle of it. If it drops a row, that row goes. Everything you moved, hid, retitled or retuned stays where you put it.

Adding and removing take the whole channel. Installing a shared channel creates all of its libraries for you, each with its own settings under its own name, and the plugin’s row names them. Removing any one of them removes the channel: every library it made, and your arrangement of its page. Nothing on disk is touched, so adding the channel again brings the titles back, with the plugin’s own page again.

A library you have already tuned is never overwritten. If you reinstall or update the plugin, it fills in whatever is missing and leaves everything else exactly as you set it.

A channel that needs your own account works like a library that does: there is nothing to add, you connect the account on your own settings screen, the channel appears for you alone, and disconnecting takes it away again.

Where they come from

Everything in Available comes from our catalog. Each one has been read by a person, signed, and hosted by us.

Your server checks that signature itself before it will install anything, using keys built into the server software. That means the check does not depend on our servers being honest or even being ours: a catalog that has been tampered with fails on your machine and nothing installs.

We also publish a withdrawal list. If a plugin turns out to be doing something it should not, it goes on that list, and every server switches it off on its own, with the reason shown. Your server checks it daily and again whenever you open this page.

Turning one off

Disable stops the plugin immediately. Its settings and cached data stay, so enabling it again picks up where it left off. A disabled plugin says Off beside its name.

Uninstall takes it off the server entirely, along with anything it saved. It only appears once a plugin is disabled, so getting rid of something is always two deliberate presses rather than one click next to the one you use every week.

If a plugin was providing your metadata for a library, turning it off means that library has no matching service until you pick another one. Your server tells you that rather than quietly matching against something else: the whole point of choosing a service is that it is the one that gets used.

A withdrawn plugin shows why it was withdrawn and offers only Uninstall. It cannot be switched back on or reinstalled.

Updates

When a newer version is in the catalog, the plugin’s row offers Update.

If the new version wants a permission the old one did not have, the row says so before you press it. A new power is a new decision, not something an update quietly carries in.

If a new version needs a newer server than yours, Update answers with the version it needs and changes nothing. The plugin you already have keeps working.

An update keeps what is yours. Your settings, the libraries a channel made and anything you changed about them, watched state and resume points, playlists, and your arrangement of a channel’s page all carry over. The old version is only removed once the new one has started. If the plugin sets itself up, it runs again, this time knowing which version it replaced, so it can bring its own stored data forward.

Updates are never automatic. Nothing about your server changes because we published something.

Installing a plugin you wrote yourself

If you are building a plugin, you can install unsigned packages from a file. This is off unless you turn it on, on the server itself: set MULTIPASS_PLUGIN_DEV=1 and restart. An Install from file control appears on the Plugins card, and your server announces developer mode in its log at every boot.

Leave it off otherwise. It exists so an author can test their own work, and a server with it on will run code nobody has reviewed.

If you want to build one, the developer guide covers writing, packaging and submitting.