Smuxi Hooks / Scripts / Plugins

Language Support

After years of waiting we are more than happy to finally have scripting support in Smuxi! You are probably thinking right now "so which scripting language is it?! C#? VB.NET? JavaScript? Perl? Python? Ruby? Maybe even PHP?" and here comes the best part: ALL OF THEM AND MORE! More? What else there would be... well, if you really want you can write Smuxi hooks in C, C++ or even x86(-64) assembly

How It Works

It's Magic! No, just kidding. This is pure Unix technology taken from the 70s ported to a powerful messaging client. If you know what Git hooks, Nagios checks/plugins or CGI scripts are, then you already know what Smuxi hooks are, if you don't then continue reading this paragraph. Any executable program in a special location (hook points) will be executed when a specific event happens, like receiving a message. This program gets all information passed as environment variables, like who send the message (SENDER), what was the message (MSG), when was it received (MSG_TIMESTAMP_UNIX) etc. This program is also able to execute Smuxi commands by writing hook commands to the standard output.

Currently there are 3 different types of Smuxi hook points:

protocol-manager hook points: these are mainly events like message-received/sent that the various protocol managers (IRC, Twitter, XMPP, etc) can raise
session hook points: these are events that are not specific to a protocol manager.
command hook points: these are added Smuxi commands running in either the frontend or engine, so you can add /some_cool_command to Smuxi

Finding Hooks

Smuxi hooks are maintained in the smuxi-hooks git repository. So if you want to share your written hook simply create a pull request against that repository on GitHub, other Smuxi users will be very thankful! Here a list of some already implemented ones:

now-playing: adds a /np command to Smuxi which shows the currently playing song of MPRIS2 supported players.
tinyurl-resolver: resolves all shortened URLs of t.co, bit.ly, etc to the full URL. This was originally an irssi plugin written in Perl.
topic-diff: Shows the word differences of the topic after topic changes. (meebey)
away-nick: Automatically appends and removes $AWAY_SUFFIX to/from the nick name when you go away using the /away command or by disconnecting all frontends from the smuxi-server. (meebey)
system-info: Shows system info. Includes system kernel version, distro name, and CPU vendor information. (AK0)

Installing Hooks

"Wow, I am completely amazed, but how can I install hooks?" For now you will need to either download the files of the hook into the same location into $HOME/.local/share/smuxi/hooks or by cloning the git repository and symlinking the files. Here is an example for each method:

Download Method

mkdir -p $HOME/.local/share/smuxi/hooks/frontend/command-manager/command-np/
cd $HOME/.local/share/smuxi/hooks/frontend/command-manager/command-np/
wget https://raw.github.com/meebey/smuxi-hooks/master/now-playing/frontend/command-manager/command-np/now-playing.sh
chmod +x now-playing.sh

Git Clone Method

cd $HOME
git clone https://github.com/meebey/smuxi-hooks.git
mkdir -p $HOME/.local/share/smuxi/hooks/frontend/command-manager/command-np/
cd $HOME/.local/share/smuxi/hooks/frontend/command-manager/command-np/
ln -s $HOME/smuxi-hooks/now-playing/frontend/command-manager/command-np/now-playing.sh

Location

Hooks are automatically activated when they are placed in the right location. So after putting them in the hook point location (see see Hook Points section) you don't need to do anything else.

The base location (without the hook point part) is for

Linux: $HOME/.local/share/smuxi/hooks
Windows:
- Vista/7/8.x: %LOCALAPPDATA%\smuxi\hooks
- XP: %USERPROFILE%\Local Settings\Application Data\smuxi\hooks
Mac OS X:

Environment Variables

All variables are prefixed with SMUXI_ to prevent clash with other environment variables.

CHAT_ID
CHAT_NAME
CHAT_TYPE: Session, Protocol, Person, Group
MSG
MSG_TYPE: Normal, Event, ChatState{Composing,Paused,Reset}
MSG_TIMESTAMP_UNIX
MSG_TIMESTAMP_ISO_UTC
MSG_TIMESTAMP_ISO_LOCAL
SENDER
RECEIVER
TODO: PROTOCOL_MANAGER_TYPE
PROTOCOL_MANAGER_PROTOCOL: IRC, Twitter, Facebook, XMPP, JabbR, Campfire
PROTOCOL_MANAGER_NETWORK
PROTOCOL_MANAGER_HOST
PROTOCOL_MANAGER_PORT
PROTOCOL_MANAGER_ME_ID
PROTOCOL_MANAGER_PRESENCE_STATUS: Unknown, Offline, Online, Away (>= 0.11)
CMD (command-manager only, >= 0.10.1)
CMD_PARAMETER (command-manager only, >= 0.10.1)
CMD_CHARACTER (command-manager only, >= 0.10.1)
FRONTEND_VERSION (command-manager only)
ENGINE_VERSION (protocol-manager only)

Hook State

Hooks are executed when the event occurs and have to exit so further processing can be done. If hooks need to retain state they can write their state to files of the current directory ($PWD). Each hook has its own state directory and can be found in $HOME/.local/share/smuxi/hook-state/$HOOK_PATH. The hook does not need to change to or create the state directory, as the hook runner will do this for the hook, guaranteed.

Hook Points

engine/protocol-manager/on-connected/

engine/protocol-manager/on-disconnected/

engine/protocol-manager/on-message-sent/

engine/protocol-manager/on-message-received/

engine/protocol-manager/on-presence-status-changed/ (>= 1.0)

This hook point is raised when the presence status of a protocol manager changes. This happens for example when an IRC connection toggles the away state.

Event specific environment variables:

PRESENCE_STATUS_CHANGED_OLD_STATUS: for valid values see PROTOCOL_MANAGER_PRESENCE_STATUS
PRESENCE_STATUS_CHANGED_NEW_STATUS: for valid values see PROTOCOL_MANAGER_PRESENCE_STATUS
PRESENCE_STATUS_CHANGED_NEW_MESSAGE

engine/session/on-group-chat-person-added/

engine/session/on-group-chat-person-removed/

engine/session/on-group-chat-person-updated/

engine/session/on-event-message/ (>= 1.0)

This hook point raises event messages that usually begin with "-!-". This can be useful to track state changes that are shown as a message without having a dedicated hook point for it.

engine/session/command-$cmd/ (>= 1.0)

This hook point is raised on the engine side for commands, e.g. /some_command that isn't handled by the frontend or engine built-in commands. This is useful for commands that should be available for all frontends and isn't specific to the frontend environment.

frontend/command-manager/command-$cmd/

This hook point is raised on the frontend side for commands, e.g. /some_command that isn't handled by the frontend or engine built-in commands. This is useful for commands that rely on the frontend environment, like dealing with windows, notifications, D-Bus, etc.

Hook Commands

Session.Command $cmd $cmd_params...

Supported session commands can be found here.

Example:

echo "Session.Command /echo I am a hook!"

ProtocolManager.Command $cmd $cmd_params...

Supported protocol manager commands fully depends on the protocol manager implementation/type, thus you need to check the PROTOCOL_MANAGER_PROTOCOL environment variable first! Here you can find a list for IRC, Twitter, XMPP, JabbR and Campfire.