Calico is a Mumble bot that connects to an SQL server and responds to text commands with audio / text responses. It's slightly tailor-made, but can be set up to suit anyone's needs.
Calico is run by using piepan from the command line. Making a
batch script is advised.
./piepan -ffmpeg=avconv -server="" -password="" -username="" calico.lua
See the piepan docs for more help.
Calico's root directory should look something like this.
- | audio/ - | bin/ - conf.lua calico.lua piepan
Audio files should be placed within sub-directories inside the
audio directory. You may name the
audio directory whatever you like (See below for config settings).
conf.lua should contain the following variables:
AUDIO_DIR- The name of your
AFK_ID- The numeric ID of an applicable AFK Mumble channel.
See below for additional database variables.
Calico connects to a MySQL server (default, other drivers available) by way of the config file.
conf.lua should contain the following database related variables:
DB_NAME- The name of the database to use.
DB_USER- The username for accessing the database.
DB_PASS- The password for accessing the database.
TABLE_AUDIO- The name of the audio table.
TABLE_TEXT- The name of the text table.
Your SQL server should contain two tables that can be named whatever you like (See above for setting the names in the config):
id- PRIMARY KEY, AUTO_INCREMENT
name- Name associated with the clip.
cmd- Command used to trigger the audio clip.
dir- Sub-directory containing the audio file.
filename- Name of the file without extension.
ext- File extension.
id- PRIMARY KEY, AUTO_INCREMENT
cmd- Command used to trigger the chat response.
response- Text blob that is returned.
Calico has three main commands: do, say, and play. Multiple commands can be sent in a single message by use of a semi-colon ( ; ) separator. e.g.,
do this; say that; play the other
do is used for issuing literal commands. Some literal commands take optional parameters that can be passed by using a leading plus sign ( + ). e.g.,
do volume +0.5.
echo +[TEXT]- The echo command causes Calico to say the text string. This command can accept multiple text parameters. e,g.
do echo +this +and +that
help- The help command prints out information about how to use Calico. This command has a special alias
?that does not require the leading
show- The show command simply lists all literal commands Calico possesses.
stop- This command stops the current audio clip. It does not empty the queue, see below.
find +[QUERY]- The find command will return a list of audio commands with names (not commands) containing the query string. Without a query string Calico will return all entries.
volume +[LEVEL]- This command sets the volume to a given level between 0 and 1. Without a level parameter the command will simply return the current volume.
list queue- Responds with the number of entries in the queue, and their associated commands in order.
empty queue- Removes all entries from the queue and responds with how many entries were removed.
move here- Sent in a private message from another channel will cause Calico to join the sender's channel.
get out +[CHANNEL ID]- This will cause Calico to move to the given channel ID, or the default AFK channel ID specified in the config.
get id- This will respond to the sender with channel ID of the sender's current channel. Can be sent via private message for debugging purposes. Useful for finding the ID of the server's AFK channel.
leave now- This will cause Calico to disconnect from the server. There is no auto reconnect.
reconnect- The reconnect command will attempt to refresh Calico's connection to the SQL server. If you find Calico unresponsive to
playcommands, or database related
docommands, try this first. Notifies the sender if successful.
say command tries to match everything that follows it against entries in the database's
text_table. If the string matches a
cmd column Calico will say the associated
response to the channel Calico is currently in.
play command tries to match everything that follows it against entries in the database's
audio_table. If the string matches a
cmd column Calico will attempt to play the associated audio file from disk.
If audio is already playing the audio clip will be added to the end the of queue. After an audio clip is finished playing Calico will immediately play the next clip in the queue, if one exists.
Calico commands cannot be passed the following characters as part of their arguments / parameters:
- semi-colon ( ; )
- plus sign ( + )
These are special characters used to break commands into parts, and are currently not able to be escaped. To avoid bad query strings they should not be used as part of searchable database names and commands.
This repository contains a directory named
extra, containing miscellaneous scripts.
watchdog.lua is an incredibly simple wrapper for continuously re-excuting the given command, until a SIGINT(2) is received. It is in no way fool proof.
$ extra/watchdog.lua ./calico.sh
uploader.php script used for uploading audio files to a web server. Uses PDO to connect to a database. To use it,
bin/conf.php should contain the following variables:
$DB_NAME- Database driver, name, hostname, port, etc. (see: PDO docs)
$DB_USER- Database user name.
$DB_PASS- Database user password.
$UPLOADER_ACCESS- Pass phrase required for uploading.
$UPLOAD_ROOT- Absolute path for upload root, i.e.
This script is to be run in tandem with an
HTML form with the following input fields, as well as an appropriate
PHP application structure.
<input type="text" name="upload[name]" /> <input type="text" name="upload[cmd]" /> <input type="text" name="upload[dir]" /> <input type="password" name="upload[pw]" /> <input type="file" name="fileUpload" />
This is somewhat complimentary to this repository's main purpose, and is not necessary for Calico to function.
Colin 'Oka' Hall-Coates