From 8e97ef7170561a38f047d96b1a80cc2271cbeab6 Mon Sep 17 00:00:00 2001
From: redxef <redxef@redxef.at>
Date: Fri, 8 Nov 2024 03:54:49 +0100
Subject: [PATCH] docs: update readme for new yaml file format.

---
 README.md | 67 +++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 45 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 0c8fecd..f1550d0 100644
--- a/README.md
+++ b/README.md
@@ -5,38 +5,49 @@ Smart playlists with Lisp filter engine.
 ## How to use
 
 After [installing](#installation) the plugin and restarting Jellyfin
-create a file in `config/data/smartplaylists` like this:
+create a empty file in `config/data/smartplaylists` like this, maybe
+you want to generate a playlist of your favourite rock songs:
 
 ```
-$ echo '{}' > config/data/smartplaylists/a.json
+$ touch config/data/smartplaylists/Rock.yaml
 ```
 
 Afterwards run the Task `(re)generate Smart Playlists`, this will rename
-the `json` file and populate it with some default values. You can now
+the `yaml` file and populate it with some default values. You can now
 adjust the file to your liking. [Go here](examples/index.md) to see more
 examples.
 
 Example file
-```json
-{
-  "Id": "a1d02dee-f1da-4472-bee3-f568c15c8360",
-  "Playlists": [
-    {
-      "PlaylistId": "24f12e1e-3278-d6d6-0ca4-066e93296c95",
-      "UserId": "6eec632a-ff0d-4d09-aad0-bf9e90b14bc6"
-    }
-  ],
-  "Name": "a1d02dee-f1da-4472-bee3-f568c15c8360",
-  "Program": "(begin (invoke item 'IsFavoriteOrLiked' (user)))",
-  "Filename": "/config/data/smartplaylists/a1d02dee-f1da-4472-bee3-f568c15c8360.json",
-  "Enabled": true
-}
+```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.
-The filename is derived from this.
 
 ### Playlists
 
@@ -63,17 +74,29 @@ The user associated with this playlist.
 
 The name of the generated playlists, this is just a default value.
 If the user changes the name of their playlist the plugin will
-work as usual
+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 `t` to include
-them.
+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.
+The path to this file, only used internally and updated by the program.
 
 ### Enabled