jellyfin-smart-playlist/README.md

# Jellyfin SmartPlaylist Plugin

Smart playlists with Lisp filter engine.

## How to use

After [installing](#installation) the plugin and restarting Jellyfin
create a empty file in `config/data/smartplaylists` like this, maybe
you want to generate a playlist of your favourite rock songs:

```
$ touch config/data/smartplaylists/Rock.yaml
```

Afterwards run the Task `(re)generate Smart Playlists`, this will rename
the `yaml` file and populate it with some default values. You can now
adjust the file to your liking. [Go here](examples.md) to see more
examples.

```yaml
Id: Rock
Playlists:
- PlaylistId: 24f12e1e-3278-d6d6-0ca4-066e93296c95
  UserId: 6eec632a-ff0d-4d09-aad0-bf9e90b14bc6
Name: Rock
Program: (begin (invoke item "IsFavoriteOrLiked" (user)))
Filename: /config/data/smartplaylists/Rock.yaml
Enabled: true
```

This is the default configuration and will always match all your
favorite songs (and songs which are in favourited albums).

To change the filter you can append a `|` (pipe) to the Program
line and write multiline filters like this:

```yaml
Porgram: |
  (begin
    (invoke item "IsFavoriteOrLiked" (list user)))
```

This is equivalent to the above example (not counting the other
fields obviously).


### Id

Arbitrary Id assigned to this playlist, can usually be left alone.

### Playlists

A list of Playlist/User mappings. By default all users get an entry.

The ids must have the dashes in them as of now. To convert a id
from without dashes to the canonical form run this command:

`echo '<your id here>' | python3 -c 'import uuid; import sys; print(uuid.UUID(sys.stdin.read().strip()))'`

To get your user id navigate to your user profile and copy the part
after `userId` in the address bar.

#### PlaylistId

The id of the playlist that should be managed, must be owned by the
corresponding user.

#### UserId

The user associated with this 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.

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)`.

#### Available definitions

- **lower**: lowercases a string (`(eq (lower "SomeString") "somestring")`)
- **is-genre**: check if the item is of this genre, partial matches
  allowed, the example filter would match the genre "Nu-Metal" (`(is-genre "metal" (genre-list))`)
- **is-genre-exact**: the same as `is-genre`, but does not match paritally
- **is-favorite**: matches a favorite item (`(is-favorite)`)

### Filename

The path to this file, only used internally and updated by the program.

### 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.