Skip to content
This repository has been archived by the owner on Jun 23, 2020. It is now read-only.

External Scripts

Jump to bottom
mutschler edited this page Jun 8, 2016 · 1 revision

Note: this requires plexivity > 0.9.6

Since version 0.9.7 plexivity supports the execution of external scripts. This gives you the ability to build nearly everything you want yourself. Want push notifications for a specific provider? You want to dim the lights if something starts playing on a specific device?

plexivity can run every script/binary that you point it to including but not limited to: bash, python, go, c++, perl, etc.

** NOTE: ** This is considered an "advanced setting" and therefore you must edit the config.ini file manually. There are no options for this in the Web Interface!

Basic Information

  • Scripts have to return 0 as exit code, everything else will be reported as error by plexivity
  • you can log to plexivity from the scripts by printing to stdout (see logging)
  • every variable you can use in your message strings can be accessed in the scripts (see env variables)
  • if you disable logging for scripts only start and end of script run will be logged

Environment Variables

Environment variables are set before script execution and can be accessed by the script. All Variables listed in the /settings view can be used, prefixed with PLX_ and uppercased.

However there are two exceptions:

  1. PLX_SUMMARY will most likely be n/a because it's to long or contains special chars
  2. There is a extra variable PLX_MESSAGE which holds your message for the current notification type (start/stop/pause/resume/recentlyadded)

Examples:

PLX_USER
PLX_TITLE
PLX_PLATFORM
PLX_TYPE
PLX_GENRE
PLX_LENGTH
PLX_USERID
PLX_ORIG_USER
...

Logging to plexivity

plexivity reads stdout while executing the scripts, everything you print to stdout will be logged as INFO level.

If you want to change the log level you can prefix your message with [DEBUG], [ERROR], [WARNING] and [INFO] reflecting the same log level in plexivity. If a line contains a invalid log level it will be treated as INFO

Example:

#! /bin/bash

echo "This is normal INFO output"
echo "[INFO] this is also Info level"
echo "[WARNING] Something went wrong... warn level logging"
echo "[DEBUG] Title rexived from plexivitiy is $PLX_ORIG_TITLE"

Example Script:

a small example which shows how to use the different variables and logging types:

#! /bin/bash

if [ -z "$PLX_NTYPE" ]; then
    echo "[ERROR] something went wrong, maybe not called from plexivity?!"
    exit 1
fi

#will be logged as info
echo "$0 started"
echo "[DEBUG] seems like current notification type is $PLX_NTYPE"

if [ "$PLX_NTYPE" == "start" ] || [ "$PLX_NTYPE" == "resume" ]; then 
    echo "[DEBUG] we gonna dim the lights"
    # trun lights off
elif [ "$PLX_NTYPE" == "stop" ] || [ "$PLX_NTYPE" == "pause" ]; then
    echo "[DEBUG] bring lights back up!"
    # trun lights on
fi

the output in plexivity logs:

06.07.2015 15:19:32 plexivity.scripts    INFO    : executing script: [/Volumes/bitbucket/plexivity/doStuff.sh]
06.07.2015 15:19:32 plexivity.scripts.doStuff    INFO    : /Volumes/bitbucket/plexivity/doStuff.sh started
06.07.2015 15:19:32 plexivity.scripts.doStuff    DEBUG   : seems like current notification type is pause
06.07.2015 15:19:32 plexivity.scripts.doStuff    DEBUG   : bring lights back up!
06.07.2015 15:19:32 plexivity.scripts    INFO    : script executed successfull: [/Volumes/bitbucket/plexivity/doStuff.sh]

Script doesn't execute

If your Script doesn't work properly please Check that the shebang is set correctly and The Script is executable

Clone this wiki locally