piepan

README

piepan: an easy to use framework for writing scriptable Mumble bots

Usage

piepan v0.6.0
usage: piepan [options] [script files]
an easy to use framework for writing scriptable Mumble bots
  -certificate="": user certificate file (PEM)
  -ffmpeg="ffmpeg": ffmpeg-capable executable for media streaming
  -insecure=false: skip certificate checking
  -key="": user certificate key file (PEM)
  -lock="": server certificate lock file
  -password="": user password
  -server="localhost:64738": address of the server
  -servername="": override server name used in TLS handshake
  -username="piepan-bot": username of the bot

Script files are defined in the following way:
  [type:[environment:]]filename
    filename: path to script file
    type: type of script file (default: file extension)
    environment: name of environment where script will be executed (default: type)

Enabled script types:
  JavaScript (.js)
  Lua (.lua)

Scripting documentation

• JavaScript
• Lua

Building

Windows

1. Install dependencies (use 32-bit/386/x86 installers)
   1. Base dependencies
      1. Download and run Go installer
      2. Download and run MSYS2 installer
         • Uncheck "Run MSYS2 32bit now"
   2. Open the MSYS2 "MinGW-w64 Win32 Shell" from the start menu to install additional dependencies
   • pacman -Syy mingw-w64-i686-toolchain git mingw-w64-i686-opus pkg-config mingw-w64-i686-ffmpeg
2. Create a GOPATH (skip if you already have a GOPATH you want to use)
   • export GOPATH=$(mktemp -d)
3. Configure environment for building Opus
   • export CGO_LDFLAGS="$(pkg-config --libs opus)"
   • export CGO_CFLAGS="$(pkg-config --cflags opus)"
4. Fetch piepan
   • Base package
     • go get -tags nopkgconfig -u github.com/layeh/piepan
   • JavaScript plugin (Optional)
     • go get -u github.com/layeh/piepan/plugins/javascript
   • Lua plugin (Optional)
     • Unavailable on Windows
5. Build piepan
   • go build -o piepan.exe $GOPATH/src/github.com/layeh/piepan/cmd/piepan/{javascript,main}.go
6. Run piepan
   • ./piepan.exe ...

Ubuntu 14.04

1. Install dependencies
2. Base dependencies
   • sudo apt-get install -y git libopus-dev wget python-software-properties software-properties-common pkg-config gcc libav-tools
3. Go
   • sudo add-apt-repository -y ppa:evarlast/golang1.4
   • sudo apt-get update
   • sudo apt-get install -y golang
4. Lua 5.1 (Optional)
   • sudo apt-get install -y liblua5.1-0-dev
5. Create a GOPATH (skip if you already have a GOPATH you want to use)
   • export GOPATH=$(mktemp -d)
6. Fetch piepan
   • Base package
     • go get -u github.com/layeh/piepan
   • JavaScript plugin (Optional)
     • go get -u github.com/layeh/piepan/plugins/javascript
   • Lua plugin (Optional)
     • go get -u github.com/layeh/piepan/plugins/lua
7. Build piepan (plugins can be removed if they are not wanted)
   • go build -o piepan $GOPATH/src/github.com/layeh/piepan/cmd/piepan/{javascript,lua,main}.go
8. Run piepan using avconv
   • ./piepan -ffmpeg=avconv ...

Changelog

• 0.6.0 (2015-02-11)
  • Fixes due to gumble API changes (see the gumble API if your scripts are not working).
  • Fix crash if piepan.Process.New executable did not exist
• 0.5.0 (2015-02-08)
  • Moved to plugin-based system
  • Add certificate locking
  • Add bitrate, volume functions to piepan.Audio
  • Add auto bitrate setting
  • Add Lua plugin
  • Add piepan.File to JavaScript plugin
  • Voice targeting is more like the gumble API
• 0.4.0 (2014-12-11)
  • Moved to Go (+ gumble)
  • API has been overhauled. There is no backwards capability with previous versions of piepan
  • JavaScript is now being used as the scripting language
• 0.3.1 (2014-10-06)
  • Fixed audio transmission memory leak
• 0.3.0 (2014-10-01)
  • Removed data argument from Channel.play and Timer.new
  • Fixed inability to start playing audio from inside of an audio completion callback
• 0.2.0 (2014-09-15)
  • Added support for fetching large channel descriptions, user textures/avatars, and user comments
  • Added piepan.server.maxMessageLength, piepan.server.maxImageMessageLength
  • Added piepan.onPermissionDenied(), piepan.Permissions, piepan.PermissionDenied, piepan.User.hash, piepan.User.setComment(), piepan.User.register(), piepan.User.setTexture(), piepan.User.isPrioritySpeaker, piepan.Channel.remove(), piepan.Channel.setDescription()
  • UserChange and ChannelChange are no longer hidden
  • Added audio file support
  • Each script is now loaded in its own Lua environment, preventing global variable interference between scripts
  • Fixed piepan.User.userId not being filled
  • Multiple instances of the same script can now be run at the same time
  • Command line option -pw was renamed to -p. The old functionality of -p was moved to the -h option, by using the new host:port syntax
• 0.1.1 (2013-12-15)
  • Fixed bug where event loop would stop when a packet with length zero was received
  • sendPacket now properly accepts a version packet
• 0.1 (2013-12-11)
  • Initial Release

License

This software is released under the MIT license (see LICENSE).

---

Author: Tim Cooper <tim.cooper@layeh.com>

Documentation

Index

• Variables
• func Register(extension string, plugin *Plugin)
• type Environment
• type Instance
  • func New(client *gumble.Client) *Instance
  • func (in *Instance) LoadScript(name string) error
• type Plugin

Variables

var (
	PluginExtensions []string
	Plugins          map[string]*Plugin = map[string]*Plugin{}
)

Functions

func Register

func Register(extension string, plugin *Plugin)

Types

type Environment

type Environment interface {
	gumble.EventListener
	LoadScriptFile(filename string) error
}

type Instance

type Instance struct {
	Client *gumble.Client
	Audio  *gumble_ffmpeg.Stream
	// contains filtered or unexported fields
}

func New

func New(client *gumble.Client) *Instance

func (*Instance) LoadScript

func (in *Instance) LoadScript(name string) error

[type:[environment:]]filename

type Plugin

type Plugin struct {
	Name string
	New  func(*Instance) Environment
}