LMS Event Trigger

LMS Event Trigger is a plugin for executing external commands triggered by LMS server events ( also know as notifications).

See LMS Event Subscriber for a stand-alone application with similar functionality.

Features

  • Multiple subscriptions to different events with different external commands
  • Web API (using HTTP GET, i.e. calling an URL)

Example scenarios

  • Send a notification that a library rescan has finished to an Android device (using ntfy)
  • Power off the server after a playlist has finished
  • Show song information on an attached display

Status

  • Beta quality, little error handling
  • Tested on Linux, may or may not work on other platforms

Installation

In the LMS web interface in Settings/Plugins, add https://www.nexus0.net/pub/sw/lmseventtrigger/repo.xml to the list of Additional Repositories and activate the plugin.

Usage Instructions

The plugin reads it's configuration from either /etc/lmseventtrigger.json or /usr/local/etc/lmseventtrigger.json. This file is required and defines which events to subscribe to, and what external command to execute when an event is received.

A list of commands which generate events can be found here. Note that you cannot subscribe to all commands (notifications will work, queries will not, others may or may not).

Configuration

The configuation is a JSON file with the following syntax:

    {
        "enabled": true,
        "numStatusResults":1,
        "events": [
            {"cmd":"/usr/local/bin/lmsclient.sh","event":[["client"]]},
            {"cmd":"/usr/local/bin/lmsplaylist.sh","event":[["playlist"],["newsong","pause"]]}
        ]
    }
  • enabled: if the plugin is active when LMS is started
  • numStatusResults: number of results for the playlist part of the player status to be passed to the external command. Set to 0 to disable. Note that some events are not related to a player, which seems to result in the status being unavailable.
  • cmd: the command to execute
  • event: which event(s) to subscribe to: [["playlist"]] will subscribe to all playlist events, [["playlist"],["newsong","pause"]] only to two specific events (playlist newsong and playlist pause).
External commands

Any executable can be called (including shell scripts etc.). It will receive the full event name as the first parameter (e.g. playlist newsong), and (if enabled) the player status (with tags galdtyR, plus the player_id) encoded as JSON as the second.
Important: Do not call long-running commands, as they are executed in the same thread as LMS, and could block the server.

Web API

The plugin provides it's API at http://lmsserver:9000/plugins/LMSeventTrigger/js.html. All calls require the cmd parameter.

Command Operation
cmd=enable enables plugin
cmd=disable disables plugin
cmd=reloadConfig reloads configuration

FAQ

Adding the plugin repository to LMS results in some errors / doesn't work. Why?
Make sure your LMS installation is SSL-enabled (e.g. on *nix, the perl modules Net::SSLeay and IO:Socket:SSL need to be installed)
It doesn't do anything. What do I do now?
First, check if the configuration file has the correct syntax and is readable by the LMS user. Then, switch logging to debug for the plugin (LMS Web interface/Settings/Advanced/Logging/plugin.lmseventtrigger) and check the server log.
The plugin fails to execute the command (log message LMSeventTrigger: error NN executing:)
The command has to be executable by the user LMS runs as (ususally squeezeboxserver, squeezeserver or similar). Check by running it from the command line (e.g. with sudo, runuser or doas).

License

GNU GPLv3

Reporting Issues

Use the discussion thread in the LMS forum.