jellyfin-smart-playlist/README.md

94 lines
3.3 KiB
Markdown

# Jellyfin SmartPlaylist Plugin
Smart playlists with Lisp filter engine.
This readme contains instructions for the most recent changes in
the development branch (`main`). To view the file appropriate
for your version select the tag corresponding to your version.
The latest version is [v0.4.0.0](https://gitea.redxef.at/redxef/jellyfin-smart-playlist/src/tag/v0.4.0.0).
## How to use
After [installing](#installation) the plugin and restarting Jellyfin
go to the plugin settings and below the `Initial Program` configuration
choose the smart playlist you want to edit, or `Create new playlist ...`
to create a new one.
[Go here](examples.md) to see some example configurations.
Below are all the configuration values for a smart playlist.
### Name
The name of the generated playlists, this is just a default value.
If the user changes the name of their playlist the plugin will
still work and remember the correct playlist.
### Program
A lisp program to decide on a per item basis if it should be included in
the playlist, return `nil` to not include items, return any other value
to include them. Global variables `*user*` and `*item*` are predefined
and contain a [User](https://github.com/jellyfin/jellyfin/blob/master/Jellyfin.Data/Entities/User.cs) and
[BaseItem](https://github.com/jellyfin/jellyfin/blob/master/MediaBrowser.Controller/Entities/BaseItem.cs)
respectively.
**!!! The filter expression will include all items matching, if you do
not specify the kind of item to include/exclude all of them will be
added. Should you allow a playlist to be included all of it's items
will be added to the generated playlist !!!**
It's best to be explicit and always specify the item kinds you want to
include: `(and (or (is-type "MusicAlbum") (is-type "Audio")) . rest of filter)`.
The configuration page defines some useful functions to make it easier
to create filters. The above filter for liked items could be simplified
to: `(is-favourite)`.
*Go [here](lisp.md) to get an overview of the built-in functions.*
### SortProgram
This works exactly like [Program](#program), but the input is the
user and a list of items (`*items*`) matched by [Program](#program).
The default is `(begin *items*)`, which doesn't sort at all. To sort
the items by name you could use the following program:
```lisp
(qsort
(lambda
(a b)
(string>
(car (getitems a "Name"))
(car (getitems b "Name"))))
*items*)
```
### Enabled
Enable this playlist, currently ignored.
## Installation
Add the [plugin repository](https://jellyfin.org/docs/general/server/plugins/#catalog)
to Jellyfin:
`https://gitea.redxef.at/redxef/jellyfin-smart-playlist/raw/branch/manifest/manifest.json`
Go to `Dashboard>Catalog>(Gear)>(Plus)` and paste the provided link into
the field labeled `Repository URL`, give the plugin a descriptive name
too.
## Releasing a new version
1. Write the changelog: `git log --oneline $prev_version..`
2. Update the following files to include up-to-date version numbers
and changelogs, if applicable:
- `README.md`
- `Jellyfin.Plugin.SmartPlaylist/build.yaml`
- `Jellyfin.Plugin.SmartPlaylist/jellyfin-smart-playlist.csproj`
Don't forget to also bump the ABI version of Jellyfin.
3. Push the changes
4. Create a new release with the changelog, mark as pre-release if
applicable.
5. Done! The build pipeline will do the rest.