Implement Watched Together shared viewing accounts
Replaces the plugin template with a working plugin that lets several users share one viewing account while keeping their individual watched lists accurate. Three pieces: - Auto-creating groups. Logging in as "alice+bob" with any named member's own password provisions the shared account and signs you in. Verified against 10.11.5: AuthenticateUser offers unmatched usernames to every enabled provider and re-queries afterwards, which is the hook this relies on. Gated on a real member password so knowing two usernames is not enough to create an account. - Multi-password authentication. IRequiresResolvedUser hands us the resolved shared account; each member's live stored hash is checked via ICryptoProvider.Verify. Deliberately avoids re-entering UserManager.AuthenticateUser, which would trip every member's failed-attempt counter whenever a different member's password matched. - One-way played-state sync. Shared account to members only, filtered to PlaybackFinished/TogglePlayed/Import so playback progress ticks are ignored. No loop guard needed: member writes carry a non-shared id. Membership is stored as user IDs rather than re-parsed from the username, so shared accounts can be renamed freely. The +/name collision resolves itself because Jellyfin only consults the plugin when no local user matches the typed name. Targets Jellyfin 10.11.x / net9.0. Adds Gitea CI (test, build, release), a builder image, and 34 tests covering the auth and sync rules.
This commit is contained in:
@@ -1,415 +1,289 @@
|
||||
# So you want to make a Jellyfin plugin
|
||||
<h1 align="center">Watched Together</h1>
|
||||
|
||||
Awesome! This guide is for you. Jellyfin plugins are written using the dotnet standard framework. What that means is you can write them in any language that implements the CLI or the DLI and can compile to net8.0. The examples on this page are in C# because that is what most of Jellyfin is written in, but F#, Visual Basic, and IronPython should all be compatible once compiled.
|
||||
<p align="center">
|
||||
A Jellyfin plugin that lets several people share one viewing account,
|
||||
while everyone's watched list stays their own.
|
||||
</p>
|
||||
|
||||
## 0. Things you need to get started
|
||||
---
|
||||
|
||||
- [Dotnet SDK 9.0](https://dotnet.microsoft.com/en-us/download/dotnet)
|
||||
## The problem
|
||||
|
||||
- An editor of your choice. Some free choices are:
|
||||
You have one television and one Jellyfin login on it. Two, three, four people use it.
|
||||
|
||||
[Visual Studio Code](https://code.visualstudio.com)
|
||||
Whoever's account is signed in on that TV accumulates everything: *Continue Watching* fills with
|
||||
someone else's half-finished documentaries, *Next Up* suggests episode 4 of a series you never
|
||||
started, and the person whose account it is can no longer tell what they have actually seen.
|
||||
|
||||
[Visual Studio Community Edition](https://visualstudio.microsoft.com/downloads)
|
||||
The usual workarounds are all bad:
|
||||
|
||||
[Mono Develop](https://www.monodevelop.com)
|
||||
- **Everyone shares one account permanently.** Nobody's watched list means anything any more.
|
||||
- **Everyone logs out and back in.** Nobody does this, especially not on a TV remote.
|
||||
- **Everyone gets their own profile on the TV.** Same problem, switching is friction, so people stop.
|
||||
|
||||
## 0.5. Quickstarts
|
||||
## What this plugin does
|
||||
|
||||
We have a number of quickstart options available to speed you along the way.
|
||||
It creates a **shared account**, a real Jellyfin user that several people log into together; and gives it three special behaviours:
|
||||
|
||||
- [Download the Example Plugin Project](https://github.com/jellyfin/jellyfin-plugin-template/tree/master/Jellyfin.Plugin.Template) from this repository, open it in your IDE and go to [step 3](https://github.com/jellyfin/jellyfin-plugin-template#3-customize-plugin-information)
|
||||
**1. The account creates itself when you log in.**
|
||||
At the login screen, type `alice+bob` as the username and *your own* password. If no such account
|
||||
exists yet, the plugin checks that `alice` and `bob` are both real users and that the password you
|
||||
typed is one of theirs — then creates the shared account and signs you straight into it. No
|
||||
dashboard visit, no admin, no setup step. Next time, it is just there.
|
||||
|
||||
- Install our dotnet template by [downloading the dotnet-template/content folder from this repo](https://github.com/jellyfin/jellyfin-plugin-template/tree/master/dotnet-template/content) or off of Nuget (Coming soon)
|
||||
**2. Any member's own password unlocks it.**
|
||||
Alice types her password, Bob types his, and both get into the same shared account. Nobody has to
|
||||
remember a new credential, and there is no shared password written on a sticky note.
|
||||
|
||||
```
|
||||
dotnet new -i /path/to/templatefolder
|
||||
```
|
||||
**3. Whatever gets watched there is mirrored back to each member's own account.**
|
||||
Finish an episode on the shared account and it is marked watched for Alice *and* Bob, on their
|
||||
individual accounts. Their personal *Continue Watching* and *Next Up* stay correct, and when they
|
||||
watch alone on their phone, the series picks up where the group left off.
|
||||
|
||||
- Run this command then skip to step 4
|
||||
|
||||
```
|
||||
dotnet new Jellyfin-plugin -name MyPlugin
|
||||
```
|
||||
|
||||
If you'd rather start from scratch keep going on to step one. This assumes no specific editor or IDE and requires only the command line with dotnet in the path.
|
||||
|
||||
## 1. Initialize Your Project
|
||||
|
||||
Make a new dotnet standard project with the following command, it will make a directory for itself.
|
||||
The sync is **one-way**: shared account → members. What Alice watches privately is her business and
|
||||
never leaks into the shared account or onto Bob.
|
||||
|
||||
```
|
||||
dotnet new classlib -f net9.0 -n MyJellyfinPlugin
|
||||
login as "alice+bob+carol"
|
||||
with any one member's password
|
||||
│
|
||||
▼ (creates the account if it does not exist yet)
|
||||
┌──────────────────┐
|
||||
alice's password │ │ played ──► alice's account
|
||||
bob's password ──►│ shared account │ played ──► bob's account
|
||||
carol's password │ "alice+bob+carol"│ played ──► carol's account
|
||||
└──────────────────┘
|
||||
any one unlocks it watched state flows outward only
|
||||
```
|
||||
|
||||
Now add the Jellyfin shared libraries.
|
||||
### This is not SyncPlay
|
||||
|
||||
Jellyfin already has **SyncPlay**, which keeps playback *synchronized in time* across devices so
|
||||
people in different places press play together.
|
||||
|
||||
Watched Together solves a different problem: people watching *the same screen* who want their
|
||||
*individual watched lists* to stay accurate. The two are complementary and can be used together.
|
||||
|
||||
---
|
||||
|
||||
## How it works
|
||||
|
||||
### Creating a group by logging in
|
||||
|
||||
When you submit a username Jellyfin does not recognise, it offers the login to every enabled
|
||||
authentication plugin before giving up. That is the hook this plugin uses.
|
||||
|
||||
On an unrecognised name, it:
|
||||
|
||||
1. Splits the name on the separator (`+` by default) — `alice+bob+carol` → three parts.
|
||||
2. Requires **every part** to be an existing, enabled user that is not itself a shared account.
|
||||
3. Requires the submitted password to match **one of those members'** stored hashes.
|
||||
4. Only then creates the shared account, and returns its name so Jellyfin completes the login.
|
||||
|
||||
Step 3 is what stops this being an open door: knowing two usernames is not enough to bring an
|
||||
account into being. If any check fails, the plugin declines and the login fails exactly as an
|
||||
ordinary typo would.
|
||||
|
||||
#### The name collision, and why it is harmless
|
||||
|
||||
`+` is a legal Jellyfin username character:
|
||||
|
||||
```
|
||||
dotnet add package Jellyfin.Model
|
||||
dotnet add package Jellyfin.Controller
|
||||
^(?!\s)[\w \-'._@+]+(?<!\s)$
|
||||
```
|
||||
|
||||
You have an autogenerated Class1.cs file. You won't be needing this, so go ahead and delete it.
|
||||
So `alice+bob` is ambiguous in principle — it could mean the group [`alice`, `bob`], or a single
|
||||
real user literally named `alice+bob`.
|
||||
|
||||
In practice the ambiguity resolves itself: **Jellyfin only consults this plugin when no local user
|
||||
matches the typed name.** A real account named `alice+bob` is found first and logs in normally,
|
||||
never reaching the splitting logic. The group interpretation is only ever tried for a name that
|
||||
belongs to nobody.
|
||||
|
||||
If you would rather avoid the situation entirely, change the separator to `_` or `-` in settings,
|
||||
or switch auto-creation off and provision groups from the dashboard instead.
|
||||
|
||||
### Membership is stored as user IDs, not re-parsed from the name
|
||||
|
||||
Once a group exists, its membership lives in plugin configuration as a **list of user IDs**, keyed
|
||||
by the shared account's ID. That list is authoritative and **nothing at runtime parses the username
|
||||
again** — so you can freely rename a shared account to `Movie Night` and everything keeps working.
|
||||
The name is only ever read at the moment of creation.
|
||||
|
||||
### Authentication
|
||||
|
||||
The shared account's `AuthenticationProviderId` points at this plugin, so Jellyfin routes only these
|
||||
accounts to it. On login the plugin walks the member list and checks the submitted password against
|
||||
each member's **live stored hash**, using Jellyfin's own `ICryptoProvider`.
|
||||
|
||||
Two consequences worth knowing:
|
||||
|
||||
- **No duplicated credentials.** There is no second copy of anyone's password anywhere. When a
|
||||
member changes their password, the change takes effect immediately.
|
||||
- **No lockout side effects.** The plugin deliberately does *not* re-enter Jellyfin's normal
|
||||
`AuthenticateUser` flow. Doing so would trip every member's failed-attempt counter each time a
|
||||
*different* member's password happened to be the one that matched, eventually locking out
|
||||
members who did nothing wrong.
|
||||
|
||||
### Watched-state sync
|
||||
|
||||
The plugin subscribes to `UserDataSaved` and filters tightly: only `PlaybackFinished`,
|
||||
`TogglePlayed` and `Import` are acted on, so the constant stream of progress updates during playback
|
||||
is ignored.
|
||||
|
||||
No feedback loop is possible: writing to a member raises the event again with *that member's* ID,
|
||||
which is not a shared account, so the handler stops immediately.
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
### From the plugin repository
|
||||
|
||||
Add this repository URL in **Dashboard → Plugins → Repositories**:
|
||||
|
||||
Navigate to the csproj that was generated, and ensure that you modify the package references to exclude assets, so that unnecessary files aren't copied over.
|
||||
Skipping this step will prevent your plugin from registering correctly.
|
||||
```
|
||||
<ItemGroup>
|
||||
<PackageReference Include="Jellyfin.Controller" Version="10.11.3">
|
||||
<ExcludeAssets>runtime</ExcludeAssets>
|
||||
</PackageReference>
|
||||
<PackageReference Include="Jellyfin.Model" Version="10.11.3">
|
||||
<ExcludeAssets>runtime</ExcludeAssets>
|
||||
</PackageReference>
|
||||
</ItemGroup>
|
||||
```
|
||||
Note: Ensure the package reference version matches the install version of jellyfin server, otherwise the plugin will show as NotSupported.
|
||||
|
||||
## 2. Set Up the Basics
|
||||
|
||||
There are a few mandatory classes you'll need for a plugin so we need to make them.
|
||||
|
||||
### PluginConfiguration
|
||||
|
||||
Create a folder named "Configuration", and a PluginConfiguration.cs file inside.
|
||||
|
||||
You can call it whatever you'd like really. This class is used to hold settings your plugin might need. We can leave it empty for now. This class should inherit from `MediaBrowser.Model.Plugins.BasePluginConfiguration`
|
||||
|
||||
It should look something like the following:
|
||||
```c#
|
||||
using MediaBrowser.Model.Plugins;
|
||||
|
||||
namespace MyJellyfinPlugin.Configuration;
|
||||
class PluginConfiguration : BasePluginConfiguration
|
||||
{
|
||||
|
||||
}
|
||||
https://gitea.tourolle.paris/dtourolle/WatchedTogether/raw/branch/master/manifest.json
|
||||
```
|
||||
|
||||
### Plugin
|
||||
Then install **Watched Together** from the catalogue and restart Jellyfin.
|
||||
|
||||
This is the main class for your plugin and will reside in the root of your project. It will define your name, version and Id. It should inherit from `MediaBrowser.Common.Plugins.BasePlugin<PluginConfiguration>`
|
||||
### Manual
|
||||
|
||||
It should look something like the following:
|
||||
```c#
|
||||
using MediaBrowser.Common.Plugins;
|
||||
using MyJellyfinPlugin.Configuration;
|
||||
|
||||
namespace MyJellyfinPlugin;
|
||||
|
||||
class Plugin : BasePlugin<PluginConfiguration>
|
||||
{
|
||||
|
||||
}
|
||||
Download the release `.zip`, extract it into a `WatchedTogether` folder inside your Jellyfin
|
||||
`plugins` directory, and restart the server.
|
||||
|
||||
---
|
||||
|
||||
## Setting up a group
|
||||
|
||||
### The quick way: just log in
|
||||
|
||||
On the shared device, at the Jellyfin login screen:
|
||||
|
||||
- **Username:** `alice+bob` (the members' usernames, joined with `+`)
|
||||
- **Password:** your own
|
||||
|
||||
That is the whole setup. The account is created on first use and reused from then on. Add a third
|
||||
person later by logging in once as `alice+bob+carol`.
|
||||
|
||||
### The dashboard way
|
||||
|
||||
If you would rather provision groups explicitly — or you have turned auto-creation off:
|
||||
|
||||
1. Go to **Dashboard → Plugins → Watched Together**.
|
||||
2. Under **Create a group**, select **two or more** members.
|
||||
3. Optionally give the account a name. Left blank, the member names are joined with `+`.
|
||||
4. Decide whether the account should see all libraries (see the security note below).
|
||||
5. Click **Create group**.
|
||||
|
||||
Either way, a new user appears in your user list and can be renamed like any other.
|
||||
|
||||
### Per-group options
|
||||
|
||||
| Option | Default | Meaning |
|
||||
| --- | --- | --- |
|
||||
| Sync unwatched | on | Marking something *unwatched* on the shared account also marks it unwatched for every member. Turn this off to make sync additive: things only ever become watched. |
|
||||
| Sync play count | off | Raise a member's play count to at least 1 when an item becomes watched. Play counts are never decreased. |
|
||||
| Disabled | off | Suspends a group: it stops accepting logins and stops syncing, without deleting anything. |
|
||||
|
||||
### Plugin settings
|
||||
|
||||
| Setting | Default | Meaning |
|
||||
| --- | --- | --- |
|
||||
| Create groups automatically at login | on | Enables the `alice+bob` login flow described above. Turn off to require dashboard provisioning. |
|
||||
| Auto-created accounts can access all libraries | on | Whether accounts made at the login screen start with full library access. Turn off to grant access deliberately. |
|
||||
| Name separator | `+` | The character joining member names, and the one split at login. Use `_` or `-` if you prefer. |
|
||||
|
||||
---
|
||||
|
||||
## Security notes
|
||||
|
||||
Please read this before granting a shared account broad library access.
|
||||
|
||||
- **Access is a union, and it is deliberate.** Any member's password opens the shared account, and
|
||||
that account sees whatever libraries *you* granted *it*, independent of each member's own
|
||||
restrictions. If a member is normally blocked from a library but the shared account is not, that
|
||||
member's password now reaches it. Set the shared account's library access accordingly.
|
||||
- **Auto-creation grants library access without an admin in the loop.** With both
|
||||
*Create groups automatically at login* and *Auto-created accounts can access all libraries* on,
|
||||
any user who knows a colleague's username can pair it with their own and reach a full-library
|
||||
account. That is a real privilege escalation if your libraries are not uniformly visible. It is
|
||||
still gated on a valid member password — nobody gets in without one — but if per-user library
|
||||
restrictions matter to you, turn off *Auto-created accounts can access all libraries* (or
|
||||
auto-creation entirely) and provision groups from the dashboard.
|
||||
- **Disabled members are excluded.** A disabled Jellyfin user can no longer unlock the shared
|
||||
account, and no longer receives watched state.
|
||||
- **Shared accounts cannot be nested.** A shared account may not be a member of another group; this
|
||||
is rejected at creation time.
|
||||
- **Brute-force protection differs.** Because authentication bypasses Jellyfin's standard login
|
||||
path (see above), the shared account does not inherit Jellyfin's built-in lockout counter.
|
||||
- **Nothing sensitive is logged.** Submitted passwords and stored hashes are never written to logs.
|
||||
|
||||
---
|
||||
|
||||
## Compatibility
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
| Target ABI | Jellyfin **10.11.x** |
|
||||
| Framework | .NET 9 |
|
||||
|
||||
Verified against the 10.11.5 SDK: `IAuthenticationProvider` + `IRequiresResolvedUser`,
|
||||
`ICryptoProvider.Verify`, `IUserDataManager.UserDataSaved`, and a 255-character username limit.
|
||||
|
||||
Auto-creation depends on `UserManager.AuthenticateUser` offering unmatched usernames to every
|
||||
enabled provider and re-querying the database afterwards ("the authentication provider might have
|
||||
created it"). That behaviour is present in 10.11.5; if a future release changes it, auto-creation
|
||||
stops working and dashboard provisioning continues to.
|
||||
|
||||
Jellyfin's plugin API changes across minor versions, `IServerEntryPoint` gave way to
|
||||
`IHostedService` around 10.9, and entity types moved namespaces in 10.11. Expect to rebuild against
|
||||
the matching SDK when upgrading the server.
|
||||
|
||||
---
|
||||
|
||||
## Building
|
||||
|
||||
The plugin targets .NET 9. If your machine does not have that runtime, build in a container:
|
||||
|
||||
```bash
|
||||
docker run --rm -v "$PWD":/src -w /src mcr.microsoft.com/dotnet/sdk:9.0 \
|
||||
dotnet test Jellyfin.Plugin.WatchedTogether.sln -c Release
|
||||
```
|
||||
|
||||
Note: If you called your PluginConfiguration class something different, you need to put that between the <>
|
||||
Or natively, with the .NET 9 SDK installed:
|
||||
|
||||
### Implement Required Properties
|
||||
|
||||
The Plugin class needs a few properties implemented before it can work correctly.
|
||||
|
||||
It needs an override on ID, an override on Name, and a constructor that follows a specific model. To get started you can use the following section.
|
||||
|
||||
```c#
|
||||
public Plugin(IApplicationPaths applicationPaths, IXmlSerializer xmlSerializer) : base(applicationPaths, xmlSerializer){}
|
||||
public override string Name => throw new System.NotImplementedException();
|
||||
public override Guid Id => Guid.Parse("");
|
||||
```bash
|
||||
dotnet build Jellyfin.Plugin.WatchedTogether.sln -c Release
|
||||
dotnet test Jellyfin.Plugin.WatchedTogether.sln -c Release
|
||||
```
|
||||
|
||||
## 3. Customize Plugin Information
|
||||
To produce an installable plugin zip:
|
||||
|
||||
You need to populate some of your plugin's information. Go ahead a put in a string of the Name you've overridden name, and generate a GUID
|
||||
|
||||
- **Windows Users**: you can use the Powershell command `New-Guid`, `[guid]::NewGuid()` or the Visual Studio GUID generator
|
||||
|
||||
- **Linux and OS X Users**: you can use the Powershell Core command `New-Guid` or this command from your shell of choice:
|
||||
|
||||
```bash
|
||||
od -x /dev/urandom | head -n1 | awk '{OFS="-"; srand($6); sub(/./,"4",$5); sub(/./,substr("89ab",1+rand()*4,1),$6); print $2$3,$4,$5,$6,$7$8$9}'
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```bash
|
||||
uuidgen
|
||||
```
|
||||
|
||||
- Place that guid inside the `Guid.Parse("")` quotes to define your plugin's ID.
|
||||
|
||||
## 4. Adding Functionality
|
||||
|
||||
Congratulations, you now have everything you need for a perfectly functional functionless Jellyfin plugin! You can try it out right now if you'd like by compiling it, then placing the dll you generate in a subfolder (named after your plugin for example) within the plugins folder under your Jellyfin directory (Normally C:\Users\{YourUserName}\AppData\Local\jellyfin\plugins). If you want to try and hook it up to a debugger make sure you copy the generated PDB file alongside it.
|
||||
|
||||
Most people aren't satisfied with just having an entry in a menu for their plugin, most people want to have some functionality, so lets look at how to add it.
|
||||
|
||||
### 4a. Implement Interfaces
|
||||
|
||||
If the functionality you are trying to add is functionality related to something that Jellyfin has an interface for you're in luck. Jellyfin uses some automatic discovery and injection to allow any interfaces you implement in your plugin to be available in Jellyfin.
|
||||
|
||||
Here's some interfaces you could implement for common use cases:
|
||||
|
||||
- **IAuthenticationProvider** - Allows you to add an authentication provider that can authenticate a user based on a name and a password, but that doesn't expect to deal with local users.
|
||||
- **IBaseItemComparer** - Allows you to add sorting rules for dealing with media that will show up in sort menus
|
||||
- **IIntroProvider** - Allows you to play a piece of media before another piece of media (i.e. a trailer before a movie, or a network bumper before an episode of a show)
|
||||
- **IItemResolver** - Allows you to define custom media types
|
||||
- **ILibraryPostScanTask** - Allows you to define a task that fires after scanning a library
|
||||
- **IMetadataSaver** - Allows you to define a metadata standard that Jellyfin can use to write metadata
|
||||
- **IResolverIgnoreRule** - Allows you to define subpaths that are ignored by media resolvers for use with another function (i.e. you wanted to have a theme song for each tv series stored in a subfolder that could be accessed by your plugin for playback in a menu).
|
||||
- **IScheduledTask** - Allows you to create a scheduled task that will appear in the scheduled task lists on the dashboard.
|
||||
|
||||
There are loads of other interfaces that can be used, but you'll need to poke around the API to get some info. If you're an expert on a particular interface, you should help [contribute some documentation](https://docs.jellyfin.org/general/contributing/index.html)!
|
||||
|
||||
### 4b. Use plugin aimed interfaces to add custom functionality
|
||||
|
||||
If your plugin doesn't fit perfectly neatly into a predefined interface, never fear, there are a set of interfaces and classes that allow your plugin to extend Jellyfin any which way you please. Here's a quick overview on how to use them
|
||||
|
||||
- **IPluginConfigurationPage** - Allows you to have a plugin config page on the dashboard. If you used one of the quickstart example projects, a premade page with some useful components to work with has been created for you! If not you can check out this guide here for how to whip one up.
|
||||
|
||||
**IPluginServiceRegistrator** - Will be located by Jellyfin at server startup and allows you to add services to the DI container to allow for injection in your plugin's classes later.
|
||||
|
||||
- **IHostedService** - Allows you to run code as a background task that will be started at program startup and will remain in memory. See [Microsoft's documentation](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/host/hosted-services?view=aspnetcore-8.0&tabs=visual-studio#ihostedservice-interface) for more information. You can make as many of these as you need; make Jellyfin aware of them with an `IPluginServiceRegistrator`. It is wildly useful for loading configs or persisting state. **Be aware that your main plugin class (IBasePlugin) cannot also be a IHostedService.**
|
||||
|
||||
- **ControllerBase** - Allows you to define custom REST-API endpoints. This is the default ASP.NET Web-API controller. You can use it exactly as you would in a normal Web-API project. Learn more about it [here](https://docs.microsoft.com/aspnet/core/web-api/?view=aspnetcore-5.0).
|
||||
|
||||
Likewise you might need to get data and services from the Jellyfin core, Jellyfin provides a number of interfaces you can add as parameters to your plugin constructor which are then made available in your project (you can see the 2 mandatory ones that are needed by the plugin system in the constructor as is).
|
||||
|
||||
- **IBlurayExaminer** - Allows you to examine blu-ray folders
|
||||
- **IDtoService** - Allows you to create data transport objects, presumably to send to other plugins or to the core
|
||||
- **ILibraryManager** - Allows you to directly access the media libraries without hopping through the API
|
||||
- **ILocalizationManager** - Allows you tap into the main localization engine which governs translations, rating systems, units etc...
|
||||
- **INetworkManager** - Allows you to get information about the server's networking status
|
||||
- **IServerApplicationPaths** - Allows you to get the running server's paths
|
||||
- **IServerConfigurationManager** - Allows you to write or read server configuration data into the application paths
|
||||
- **ITaskManager** - Allows you to execute and manipulate scheduled tasks
|
||||
- **IUserManager** - Allows you to retrieve user info and user library related info
|
||||
- **IXmlSerializer** - Allows you to use the main xml serializer
|
||||
- **IZipClient** - Allows you to use the core zip client for compressing and decompressing data
|
||||
|
||||
## 5. Create a Repository
|
||||
|
||||
- [See blog post](https://jellyfin.org/posts/plugin-updates/)
|
||||
|
||||
## 6. Set Up Debugging
|
||||
|
||||
Debugging can be set up by creating tasks which will be executed when running the plugin project. The specifics on setting up these tasks are not included as they may differ from IDE to IDE. The following list describes the general process:
|
||||
|
||||
- Compile the plugin in debug mode.
|
||||
- Create the plugin directory if it doesn't exist.
|
||||
- Copy the plugin into your server's plugin directory. The server will then execute it.
|
||||
- Make sure to set the working directory of the program being debugged to the working directory of the Jellyfin Server.
|
||||
- Start the server.
|
||||
|
||||
Some IDEs like Visual Studio Code may need the following compile flags to compile the plugin:
|
||||
|
||||
```shell
|
||||
dotnet build Your-Plugin.sln /property:GenerateFullPaths=true /consoleloggerparameters:NoSummary
|
||||
```bash
|
||||
jprm plugin build .
|
||||
```
|
||||
|
||||
These flags generate the full paths for file names and **do not** generate a summary during the build process as this may lead to duplicate errors in the problem panel of your IDE.
|
||||
### CI
|
||||
|
||||
### 6.a Set Up Debugging on Visual Studio
|
||||
Gitea Actions workflows live in [.gitea/workflows/](.gitea/workflows/):
|
||||
|
||||
Visual Studio allows developers to connect to other processes and debug them, setting breakpoints and inspecting the variables of the program. We can set this up following this steps:
|
||||
On this section we will explain how to set up our solution to enable debugging before the server starts.
|
||||
| Workflow | Trigger | Does |
|
||||
| --- | --- | --- |
|
||||
| `test.yaml` | push / PR | Debug build and test run, uploads `.trx` results |
|
||||
| `build.yaml` | push / PR to `master` | Release build, tests, and a date-versioned plugin zip |
|
||||
| `release.yaml` | tag `v*.*.*` | Builds, creates a Gitea release, and updates `manifest.json` |
|
||||
|
||||
1. Right-click on the solution, And click on Add -> Existing Project...
|
||||
2. Locate Jellyfin executable in your installation folder and click on 'Open'. It is called `Jellyfin.exe`. Now The solution will have a new "Project" called Jellyfin. This is the executable, not the source code of Jellyfin.
|
||||
3. Right-click on this new project and click on 'Set up as Startup Project'
|
||||
4. Right-click on this new project and click on 'Properties'
|
||||
5. Make sure that the 'Attach' parameter is set to 'No'
|
||||
All three run in the builder image defined by [Dockerfile.builder](Dockerfile.builder):
|
||||
|
||||
From now on, everytime you click on start from Visual Studio, it will start Jellyfin attached to the debugger!
|
||||
```bash
|
||||
docker build -f Dockerfile.builder -t gitea.tourolle.paris/dtourolle/watchedtogether-builder:latest .
|
||||
docker push gitea.tourolle.paris/dtourolle/watchedtogether-builder:latest
|
||||
```
|
||||
|
||||
The only thing left to do is to compile the project as it is specified a few lines above and you are done.
|
||||
---
|
||||
|
||||
### 6.b Automate the Setup on Visual Studio Code
|
||||
## License
|
||||
|
||||
Visual Studio Code allows developers to automate the process of starting all necessary dependencies to start debugging the plugin. This guide assumes the reader is familiar with the [documentation on debugging in Visual Studio Code](https://code.visualstudio.com/docs/editor/debugging) and has read the documentation in this file. It is assumed that the Jellyfin Server has already been compiled once. However, should one desire to automatically compile the server before the start of the debugging session, this can be easily implemented, but is not further discussed here.
|
||||
|
||||
A full example, which aims to be portable may be found in this repo's `.vscode` folder.
|
||||
|
||||
This example expects you to clone `jellyfin`, `jellyfin-web` and `jellyfin-plugin-template` under the same parent directory, though you can customize this in `settings.json`
|
||||
|
||||
1. Create a `settings.json` file inside your `.vscode` folder, to specify common options specific to your local setup.
|
||||
```jsonc
|
||||
{
|
||||
// jellyfinDir : The directory of the cloned jellyfin server project
|
||||
// This needs to be built once before it can be used
|
||||
"jellyfinDir" : "${workspaceFolder}/../jellyfin/Jellyfin.Server",
|
||||
// jellyfinWebDir : The directory of the cloned jellyfin-web project
|
||||
// This needs to be built once before it can be used
|
||||
"jellyfinWebDir" : "${workspaceFolder}/../jellyfin-web",
|
||||
// jellyfinDataDir : the root data directory for a running jellyfin instance
|
||||
// This is where jellyfin stores its configs, plugins, metadata etc
|
||||
// This is platform specific by default, but on Windows defaults to
|
||||
// ${env:LOCALAPPDATA}/jellyfin
|
||||
"jellyfinDataDir" : "${env:LOCALAPPDATA}/jellyfin",
|
||||
// The name of the plugin
|
||||
"pluginName" : "Jellyfin.Plugin.Template",
|
||||
}
|
||||
```
|
||||
|
||||
1. To automate the launch process, create a new `launch.json` file for C# projects inside the `.vscode` folder. The example below shows only the relevant parts of the file. Adjustments to your specific setup and operating system may be required.
|
||||
|
||||
```jsonc
|
||||
{
|
||||
// Paths and plugin names are configured in settings.json
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"type": "coreclr",
|
||||
"name": "Launch",
|
||||
"request": "launch",
|
||||
"preLaunchTask": "build-and-copy",
|
||||
"program": "${config:jellyfinDir}/bin/Debug/net8.0/jellyfin.dll",
|
||||
"args": [
|
||||
//"--nowebclient"
|
||||
"--webdir",
|
||||
"${config:jellyfinWebDir}/dist/"
|
||||
],
|
||||
"cwd": "${config:jellyfinDir}",
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
The `request` type is specified as `launch`, as this `launch.json` file will start the Jellyfin Server process. The `preLaunchTask` defines a task that will run before the Jellyfin Server starts. More on this later. It is important to set the `program` path to the Jellyin Server program and set the current working directory (`cwd`) to the working directory of the Jellyfin Server.
|
||||
The `args` option allows to specify arguments to be passed to the server, e.g. whether Jellyfin should start with the web-client or without it.
|
||||
|
||||
2. Create a `tasks.json` file inside your `.vscode` folder and specify a `build-and-copy` task that will run in `sequence` order. This tasks depends on multiple other tasks and all of those other tasks can be defined as simple `shell` tasks that run commands like the `cp` command to copy a file. The sequence to run those tasks in is given below. Please note that it might be necessary to adjust the examples for your specific setup and operating system.
|
||||
|
||||
The full file is shown here - Specific sections will be discussed in depth
|
||||
```jsonc
|
||||
{
|
||||
// Paths and plugin name are configured in settings.json
|
||||
"version": "2.0.0",
|
||||
"tasks": [
|
||||
{
|
||||
// A chain task - build the plugin, then copy it to your
|
||||
// jellyfin server's plugin directory
|
||||
"label": "build-and-copy",
|
||||
"dependsOrder": "sequence",
|
||||
"dependsOn": ["build", "make-plugin-dir", "copy-dll"]
|
||||
},
|
||||
{
|
||||
// Build the plugin
|
||||
"label": "build",
|
||||
"command": "dotnet",
|
||||
"type": "shell",
|
||||
"args": [
|
||||
"publish",
|
||||
"${workspaceFolder}/${config:pluginName}.sln",
|
||||
"/property:GenerateFullPaths=true",
|
||||
"/consoleloggerparameters:NoSummary"
|
||||
],
|
||||
"group": "build",
|
||||
"presentation": {
|
||||
"reveal": "silent"
|
||||
},
|
||||
"problemMatcher": "$msCompile"
|
||||
},
|
||||
{
|
||||
// Ensure the plugin directory exists before trying to use it
|
||||
"label": "make-plugin-dir",
|
||||
"type": "shell",
|
||||
"command": "mkdir",
|
||||
"args": [
|
||||
"-Force",
|
||||
"-Path",
|
||||
"${config:jellyfinDataDir}/plugins/${config:pluginName}/"
|
||||
]
|
||||
},
|
||||
{
|
||||
// Copy the plugin dll to the jellyfin plugin install path
|
||||
// This command copies every .dll from the build directory to the plugin dir
|
||||
// Usually, you probablly only need ${config:pluginName}.dll
|
||||
// But some plugins may bundle extra requirements
|
||||
"label": "copy-dll",
|
||||
"type": "shell",
|
||||
"command": "cp",
|
||||
"args": [
|
||||
"./${config:pluginName}/bin/Debug/net8.0/publish/*",
|
||||
"${config:jellyfinDataDir}/plugins/${config:pluginName}/"
|
||||
]
|
||||
|
||||
},
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
1. The "build-and-copy" task which triggers all of the other tasks
|
||||
```jsonc
|
||||
{
|
||||
// A chain task - build the plugin, then copy it to your
|
||||
// jellyfin server's plugin directory
|
||||
"label": "build-and-copy",
|
||||
"dependsOrder": "sequence",
|
||||
"dependsOn": ["build", "make-plugin-dir", "copy-dll"]
|
||||
},
|
||||
```
|
||||
2. A build task. This task builds the plugin without generating summary, but with full paths for file names enabled.
|
||||
|
||||
```jsonc
|
||||
{
|
||||
// Build the plugin
|
||||
"label": "build",
|
||||
"command": "dotnet",
|
||||
"type": "shell",
|
||||
"args": [
|
||||
"publish",
|
||||
"${workspaceFolder}/${config:pluginName}.sln",
|
||||
"/property:GenerateFullPaths=true",
|
||||
"/consoleloggerparameters:NoSummary"
|
||||
],
|
||||
"group": "build",
|
||||
"presentation": {
|
||||
"reveal": "silent"
|
||||
},
|
||||
"problemMatcher": "$msCompile"
|
||||
},
|
||||
```
|
||||
|
||||
3. A tasks which creates the necessary plugin directory and a sub-folder for the specific plugin. The plugin directory is located below the [data directory](https://jellyfin.org/docs/general/administration/configuration.html) of the Jellyfin Server. As an example, the following path can be used for the bookshelf plugin: `$HOME/.local/share/jellyfin/plugins/Bookshelf/`
|
||||
```jsonc
|
||||
{
|
||||
// Ensure the plugin directory exists before trying to use it
|
||||
"label": "make-plugin-dir",
|
||||
"type": "shell",
|
||||
"command": "mkdir",
|
||||
"args": [
|
||||
"-Force",
|
||||
"-Path",
|
||||
"${config:jellyfinDataDir}/plugins/${config:pluginName}/"
|
||||
]
|
||||
},
|
||||
```
|
||||
|
||||
4. A tasks which copies the plugin dll which has been built in step 2.1. The file is copied into it's specific plugin directory within the server's plugin directory.
|
||||
|
||||
```jsonc
|
||||
{
|
||||
// Copy the plugin dll to the jellyfin plugin install path
|
||||
// This command copies every .dll from the build directory to the plugin dir
|
||||
// Usually, you probablly only need ${config:pluginName}.dll
|
||||
// But some plugins may bundle extra requirements
|
||||
"label": "copy-dll",
|
||||
"type": "shell",
|
||||
"command": "cp",
|
||||
"args": [
|
||||
"./${config:pluginName}/bin/Debug/net8.0/publish/*",
|
||||
"${config:jellyfinDataDir}/plugins/${config:pluginName}/"
|
||||
]
|
||||
},
|
||||
```
|
||||
|
||||
## Licensing
|
||||
|
||||
Licensing is a complex topic. This repository features a GPLv3 license template that can be used to provide a good default license for your plugin. You may alter this if you like, but if you do a permissive license must be chosen.
|
||||
|
||||
Due to how plugins in Jellyfin work, when your plugin is compiled into a binary, it will link against the various Jellyfin binary NuGet packages. These packages are licensed under the GPLv3. Thus, due to the nature and restrictions of the GPL, the binary plugin you get will also be licensed under the GPLv3.
|
||||
|
||||
If you accept the default GPLv3 license from this template, all will be good. However if you choose a different license, please keep this fact in mind, as it might not always be obvious that an, e.g. MIT-licensed plugin would become GPLv3 when compiled.
|
||||
|
||||
Please note that this also means making "proprietary", source-unavailable, or otherwise "hidden" plugins for public consumption is not permitted. To build a Jellyfin plugin for distribution to others, it must be under the GPLv3 or a permissive open-source license that can be linked against the GPLv3.
|
||||
GPL-3.0. See [LICENSE](LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user