Merge pull request #1045 from whatdoineed2do/README-smart-json-upd

[README] smart pl and  json update

README_JSON_API.md

@@ -640,6 +640,7 @@ POST /api/queue/items/add
 | playback_from_position | *(Optional)* If the `playback` parameter is set to `start`, playback will be started with the queue item at the position given in `playback_from_position`. |
 | clear           | *(Optional)* If the `clear` parameter is set to `true`, the queue will be cleared before adding the new items.    |
 | shuffle         | *(Optional)* If the `shuffle` parameter is set to `true`, the shuffle mode is activated. If it is set to something else, the shuffle mode is deactivated. To leave the shuffle mode untouched the parameter should be ommited.    |
+| limit           | *(Optional)* Maximum number of tracks to add |
 
 Either the `uris` or the `expression` parameter must be set. If both are set the `uris` parameter takes presedence and the `expression` parameter will be ignored.
 
@@ -678,6 +679,16 @@ curl -X POST "http://localhost:3689/api/queue/items/add?expression=media_kind+is
 }
 ```
 
+Clear current queue, add 10 new random tracks of `genre` _Pop_ and start playback
+```
+curl -X POST "http://localhost:3689/api/queue/items/add?limit=10&clear=true&playback=start&expression=genre+is+%22Pop%22+order+by+random+desc"
+```
+
+```json
+{
+  "count": 10
+}
+```
 
 ### Moving a queue item
 

README_SMARTPL.md

@@ -46,6 +46,7 @@ Where valid field-names (with their types) are:
 * `time_modified` (date)
 * `time_played` (date)
 * `time_skipped` (date)
+* `random` (special)
 
 Valid operators include:
 * `is`, `includes`, `starts with` (string)
@@ -86,6 +87,8 @@ It is possible to define the sort order and limit the number of items by adding
 
 "sort-direction" is either `ASC` (ascending) or `DESC` (descending). "limit" is the maximum number of items.
 
+There is additionally a special `random` _field-name_ that can be used in conjunction with `limit` to select a random number of items based on current expression.
+
 
 ## Examples
 
@@ -136,6 +139,16 @@ This would match any podcast and audiobook file that was never played with forke
 ```
 This would match the last 10 music files added to the library.
 
+```
+"Random 10 Rated Pop songs" {
+  rating > 0 and
+  genre is "Pop" and
+  media_kind is music
+  order by random desc
+  limit 10
+}
+```
+This generates a random set of, maximum of 10, rated Pop music tracks every time the playlist is queried.
 
 ## Date operand syntax