API

The server plugin exposes all functionality as JSON/RPC and JSONP/RPC at the URL http://lmsserver:9000/plugins/LMSessentiaIntegration/js.html (request method GET)

General request format

RPC data is passed as parameter args, cmd specifies the function to call:

    args = {
    cmd: 'commandname',
    param1: value1,
    ...
    }

Commands potentially returning a large number of rows also take the following parameters:

• start=n: start results at row n of the resultset
• limit=n: limit results to n rows
• page=n: results start at page n of the resultset

Example request URL (note: args parameter is encoded):
http://lmsserver:9000/plugins/LMSessentiaIntegration/js.html?args=%7B%22cmd%22%3A%22getTracksByParams%22%2C%22player%22%3A%22%22%2C%22dbSearch%22%3A%5B%7B%22genreTracks.genre%22%3A%5B784%2C801%5D%7D%5D%2C%22dbAtts%22%3A%5B%7B%22join%22%3A%22genreTracks%22%7D%5D%2C%22essAtts%22%3A%5B%7B%22attrib%22%3A%22danceability%22%2C%22value%22%3A%22danceable%22%7D%2C%7B%22attrib%22%3A%22mood_acoustic%22%2C%22value%22%3A%22acoustic%22%7D%5D%7D&page;=1&start;=0&limit;=500

Functions

getAllTracks

returns all tracks from the Essentia DB.
Optional parameter: where (specifies SQL where clause, e.g WHERE artist like %name%)
Relevant DB fields:

    urlmd5 varchar,
    file_name varchar,
    file_path varchar,
    file_url varchar,
    artist varchar,
    album varchar,
    title varchar,
    genre varchar,
    length float

Example request:

    args:{"cmd":"getAllTracks"}
    page:1
    start:0
    limit:25

Response:

    {
      "results": {
        "count": 1,
        "tracks_loop": [
        {
            "genre": "Indie",
            "id": 713,
            "file_path": "/data/music/Garbage - Garbage/04 - As Heaven Is Wide.flac",
            "values": [
              {
                "probability": 0.991982221603,
                "value": "danceable",
                "attrib": "danceability",
                "id": 12114
              },
              {
                "id": 12113,
                "value": "female",
                "attrib": "gender",
                "probability": 0.94935041666
              }
            ],
            "length": 283.933319092,
            "title": "As Heaven Is Wide",
            "file_url": "file:///data/music/Garbage%20-%20Garbage/04%20-%20As%20Heaven%20Is%20Wide.flac",
            "file_name": "04 - As Heaven Is Wide.flac",
            "artist": "Garbage",
            "urlmd5": "29b8bc3a6805beff8e09887ea8db9b73",
            "album": "Garbage"
          }
        ],
        "total": 1
      },
      "msg": "getAllTracks",
      "error": 0,
      "args": null
    }

getSlimTracksByAttrib

returns LMS tracks selected by Essentia attributes. Parameters: atts (array of hashes (keys: attrib / value / (optional) probability)

getTrackAttributes

returns array of all available attributes with their distinct values

getTrackAttributesAsTree

returns all available attributes with their distinct values in a format suitable for a Ext.tree.Panel

getTracksByParams

returns LMS tracks. Allows for selection by both Essentia attributes and regular LMS metadata (e.g. rating, genre, years)

• Parameter essAtts: array of hashes (keys: attrib / value / (optional) probability)
• Parameter dbSearch: LMS DB query in Perl's DBIx OO syntax

Example request (2 Essentia attributes, LMS rating > 3 stars):

    args:{"cmd":"getTracksByParams","player":"","dbSearch":[{"persistent.rating":{">=":60,"<=":100}}],"dbAtts":[{}],"essAtts":[{"attrib":"danceability","value":"danceable"},{"attrib":"mood_acoustic","value":"acoustic"}]}
    page:1
    start:0
    limit:500

Example response:

    {
      "results": {
        "tracks_loop": [
          {
            "tracknum": 10,
            "rating": 100,
            "disc": null,
            "coverid": "9b37c5de",
            "added_time": 1490831886,
            "updated_time": 1490831886,
            "albumid": 40544,
            "id": "444032",
            "prettyBitRate": "944kbps VBR",
            "genre": "Trip Hop",
            "year": 2008,
            "itype": "track",
            "timestamp": 1386079020,
            "filesize": 25037641,
            "comment": null,
            "duration": "3:31",
            "artistName": "Portishead",
            "lyrics": null,
            "albumname": "Third",
            "name": "Magic Doors",
            "artistid": 27009,
            "replay_gain": -8.84,
            "tagversion": null,
            "url": "file:///data/music/Portishead%20-%20Third/10%20-%20Magic%20Doors.flac",
            "playcount": 7
          }
        ],
        "count": 1
      },
      "msg": "getTracksByParams"
    }

getStats

returns statistics hash (tracks: hash of various track-related numbers / values: array of hash of sum/avg/min/max values for all attributes)
Example response:

    {
      "results": {
        "tracks": {
          "totalRows": 2641,
          "totalSlimRows": 10343,
          "matchingRows": 2586,
          "totalVals": 44897
        },
        "values": [
          {
            "danceability": [
              {
                "name": "danceable",
                "prob_max": 0.999999880791,
                "prob_avg": 0.854243109724707,
                "prob_min": 0.5,
                "count": 1081
              },
              {
                "prob_avg": 0.870365622104733,
                "prob_min": 0.5052921772,
                "count": 1560,
                "name": "not_danceable",
                "prob_max": 1
              }
            ]
          },
          ...

createDBtables

creates the DB tables

dropDBtables

drops the DB tables