piepan

README

piepan: an easy to use framework for writing Mumble bots using Lua

Usage

piepan v0.8.0
usage: piepan [options] [script files]
an easy to use framework for writing Mumble bots using Lua
  -access-token value
        server access token (can be defined multiple times) (default [])
  -certificate string
        user certificate file (PEM)
  -ffmpeg string
        ffmpeg-capable executable for media streaming (default "ffmpeg")
  -insecure
        skip certificate checking
  -key string
        user certificate key file (PEM)
  -lock string
        server certificate lock file
  -password string
        user password
  -server string
        address of the server (default "localhost:64738")
  -username string
        username of the bot (default "piepan-bot")

Building

Windows

1. Install dependencies
   1. Base dependencies
      1. Download and run Go installer
      2. Download and run MSYS2 installer
         • Uncheck "Run MSYS2 32/64bit now"
   2. Open the MSYS2 "MinGW-w64 Win32/64 Shell" from the start menu to install additional dependencies
      • 32-bit:
        • pacman -Syy mingw-w64-i686-toolchain git mingw-w64-i686-opus pkg-config mingw-w64-i686-ffmpeg
      • 64-bit:
        • pacman -Syy mingw-w64-x86_64-toolchain git mingw-w64-x86_64-opus pkg-config mingw-w64-x86_64-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
   • go get -tags nopkgconfig -u github.com/layeh/piepan
5. Build piepan
   • go build -o piepan.exe $GOPATH/src/github.com/layeh/piepan/cmd/piepan/main.go
6. Run piepan
   • ./piepan.exe -ffmpeg=ffmpeg.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. Create a GOPATH (skip if you already have a GOPATH you want to use)
   • export GOPATH=$(mktemp -d)
5. Fetch piepan
   • go get -u github.com/layeh/piepan
6. Build piepan
   • go build -o piepan $GOPATH/src/github.com/layeh/piepan/cmd/piepan/main.go
7. Run piepan with avconv
   • ./piepan -ffmpeg=avconv ...

API

piepan is built using the gumble library. Documentation for types not part of piepan itself (including User and Channel) can be found in the gumble documentation.

piepan.Audio

• VoiceTarget NewTarget(int id): Create a new voice target object.

• piepan.AudioStream New(table obj): Returns a new AudioStream. The following modes are supported:

  • Filename:
    • Plays the media file obj.filename.
  • Pipe:
    • Uses the output of the program obj.exec executed with obj.args.

  obj.offset defines the number of seconds from the beginning of the stream to starting playing at.
  obj.callback can be defined as a function that is called after the playback has completed. If audio has been paused

• piepan.AudioStream Current(): Returns the currently playing stream.

• void SetTarget(VoiceTarget target) sets the target for the new audio stream that is played. Calling this function with no arguments removes any voice targeting.

• int Bitrate(): Returns the bitrate of the audio encoder.

• void SetBitrate(int bitrate): Sets the bitrate of the audio encoder. Calling this function will override the automatically-configured, optimal bitrate.

• bool IsPlaying(): Returns if there is a stream currently playing.

piepan.AudioStream

Note: after an audio stream has stopped/completed, it cannot be started again.

• void Play(): Starts playing or resumes the audio stream. An error is thrown if the stream cannot be started, usually due to a missing ffmpeg executable.
• void Stop(): Stops a playing or paused stream.
• void Pause(): Pauses the playing stream.
• void IsPlaying(): Returns if the stream is playing.
• void IsPaused(): Returns if the stream is paused.
• void IsStopped(): Returns if the stream has stopped.
• float Elapsed(): Returns the amount of audio (in seconds) that the stream played.
• void SetVolume(float volume): Sets the volume of transmitted audio (default: 1.0).
• float Volume(): Returns the stream's volume.

Channels piepan.Channels

Object that contains all of the channels that are on the server. The channels are mapped by their channel IDs. piepan.Channels[0] is the server's root channel.

piepan.Disconnect()

Disconnects from the server.

piepan.On(string event, function callback)

Registers an event listener for a given event type. The follow events are currently supported:

• connect (Arguments: ConnectEvent event)
  • Called when connection to the server has been made. This is where a script should perform its initialization.
• disconnect (Arguments: DisconnectEvent event)
  • Called when connection to the server has been lost or after piepan.Disconnect() is called.
• message (Arguments: TextMessageEvent event)
  • Called when a text message is received.
• userChange (Arguments: UserChangeEvent event)
  • Called when a user's properties changes (e.g. connects to the server).
• channelChange (Arguments: ChannelChangeEvent event)
  • Called when a channel changes state (e.g. is added or removed).
• permissionDenied (Arguments: PermissionDeniedEvent event)
  • Called when a requested action could not be performed.

Note: events with a Type field have slight changes than what is documented in gumble:

1. The Type field is changed to a number.
2. Individual bit flag values are added to the event as booleans prefixed with Is
   • DisconnectEvent
     • IsError
     • IsUser
     • IsOther
     • IsVersion
     • IsUserName
     • IsUserCredentials
     • IsServerPassword
     • IsUsernameInUse
     • IsServerFull
     • IsNoCertificate
     • IsAuthenticatorFail
   • UserChangeEvent
     • IsConnected
     • IsDisconnected
     • IsKicked
     • IsBanned
     • IsRegistered
     • IsUnregistered
     • IsChangeName
     • IsChangeChannel
     • IsChangeComment
     • IsChangeAudio
     • IsChangeTexture
     • IsChangePrioritySpeaker
     • IsChangeRecording
   • ChannelChangeEvent
     • IsCreated
     • IsRemoved
     • IsMoved
     • IsChangeName
     • IsChangeDescription
     • IsChangePosition
   • PermissionDeniedEvent
     • IsOther
     • IsPermission
     • IsSuperUser
     • IsInvalidChannelName
     • IsTextTooLong
     • IsTemporaryChannel
     • IsMissingCertificate
     • IsInvalidUserName
     • IsChannelFull
     • IsNestingLimit

piepan.Process

• piepan.Process New(function callback, string command, string arguments...): Executes command in a new process with the given arguments. The function callback is executed once the process has completed, passing if the execution was successful and the contents of standard output.

• void Kill(): Kills the process.

User piepan.Self

The User object that references yourself.

piepan.Timer

• piepan.Timer New(function callback, int timeout): Creates a new timer. After at least timeout milliseconds, callback will be executed.

• void Cancel(): Cancels the timer.

Users piepan.Users

Object containing each connected user on the server, with the keys being the session ID of the user and the value being their corresponding piepan.User table.

Changelog

• 0.8.1 (2015-12-16)
  • Fix -ffmpeg flag not being used
  • AudioStream.Play now throws an error if the stream cannot be started
• 0.8.0 (2015-12-11)
  • Switch to stream-based audio. Individual audios streams can be created then played, paused, and stopped.
  • Add gumble.ConnectEvent wrapper
  • Add pipe support to piepan.Audio.New
  • Add offset field to piepan.Audio.New's argument
  • Remove all plugins; piepan is Lua only
• 0.7.0 (2015-04-08)
  • Add additional Lua support via gopher-lua
  • Add access token flag
  • Non-script-invoked disconnections are reported though the exit status
  • Remove -servername flag (-lock + -insecure should be used instead)
  • JavaScript plugin: piepan.Users and piepan.Channels are no longer mapped using string keys (otto needs to be updated before building)
• 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

MPL 2.0

---

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

Documentation

Index

• type ChannelChangeEventWrapper
• type ConnectEventWrapper
• type DisconnectEventWrapper
• type PermissionDeniedEventWrapper
• type State
  • func New(client *gumble.Client) *State
  • func (s *State) LoadFile(filename string) error
  • func (s *State) OnACL(e *gumble.ACLEvent)
  • func (s *State) OnBanList(e *gumble.BanListEvent)
  • func (s *State) OnChannelChange(e *gumble.ChannelChangeEvent)
  • func (s *State) OnConnect(e *gumble.ConnectEvent)
  • func (s *State) OnContextActionChange(e *gumble.ContextActionChangeEvent)
  • func (s *State) OnDisconnect(e *gumble.DisconnectEvent)
  • func (s *State) OnPermissionDenied(e *gumble.PermissionDeniedEvent)
  • func (s *State) OnServerConfig(e *gumble.ServerConfigEvent)
  • func (s *State) OnTextMessage(e *gumble.TextMessageEvent)
  • func (s *State) OnUserChange(e *gumble.UserChangeEvent)
  • func (s *State) OnUserList(e *gumble.UserListEvent)
• type TextMessageEventWrapper
  • func (t *TextMessageEventWrapper) PlainText() string
• type UserChangeEventWrapper

Types

type ChannelChangeEventWrapper

type ChannelChangeEventWrapper struct {
	Client  *gumble.Client
	Type    int
	Channel *gumble.Channel

	IsCreated           bool
	IsRemoved           bool
	IsMoved             bool
	IsChangeName        bool
	IsChangeDescription bool
	IsChangePosition    bool
}

type ConnectEventWrapper

type ConnectEventWrapper struct {
	Client         *gumble.Client
	WelcomeMessage string
	MaximumBitrate int
}

type DisconnectEventWrapper

type DisconnectEventWrapper struct {
	Client *gumble.Client
	Type   int

	String string

	IsError bool
	IsUser  bool

	IsOther             bool
	IsVersion           bool
	IsUserName          bool
	IsUserCredentials   bool
	IsServerPassword    bool
	IsUsernameInUse     bool
	IsServerFull        bool
	IsNoCertificate     bool
	IsAuthenticatorFail bool
}

type PermissionDeniedEventWrapper

type PermissionDeniedEventWrapper struct {
	Client  *gumble.Client
	Type    int
	Channel *gumble.Channel
	User    *gumble.User

	Permission int
	String     string

	IsOther              bool
	IsPermission         bool
	IsSuperUser          bool
	IsInvalidChannelName bool
	IsTextTooLong        bool
	IsTemporaryChannel   bool
	IsMissingCertificate bool
	IsInvalidUserName    bool
	IsChannelFull        bool
	IsNestingLimit       bool
}

type State

type State struct {
	Client *gumble.Client

	LState *lua.LState

	AudioCommand string
	// contains filtered or unexported fields
}

func New

func New(client *gumble.Client) *State

func (*State) LoadFile

func (s *State) LoadFile(filename string) error

func (*State) OnACL

func (s *State) OnACL(e *gumble.ACLEvent)

func (*State) OnBanList

func (s *State) OnBanList(e *gumble.BanListEvent)

func (*State) OnChannelChange

func (s *State) OnChannelChange(e *gumble.ChannelChangeEvent)

func (*State) OnConnect

func (s *State) OnConnect(e *gumble.ConnectEvent)

func (*State) OnContextActionChange

func (s *State) OnContextActionChange(e *gumble.ContextActionChangeEvent)

func (*State) OnDisconnect

func (s *State) OnDisconnect(e *gumble.DisconnectEvent)

func (*State) OnPermissionDenied

func (s *State) OnPermissionDenied(e *gumble.PermissionDeniedEvent)

func (*State) OnServerConfig

func (s *State) OnServerConfig(e *gumble.ServerConfigEvent)

func (*State) OnTextMessage

func (s *State) OnTextMessage(e *gumble.TextMessageEvent)

func (*State) OnUserChange

func (s *State) OnUserChange(e *gumble.UserChangeEvent)

func (*State) OnUserList

func (s *State) OnUserList(e *gumble.UserListEvent)

type TextMessageEventWrapper

type TextMessageEventWrapper struct {
	*gumble.TextMessageEvent
}

func (*TextMessageEventWrapper) PlainText

func (t *TextMessageEventWrapper) PlainText() string

type UserChangeEventWrapper

type UserChangeEventWrapper struct {
	Client *gumble.Client
	Type   int
	User   *gumble.User
	Actor  *gumble.User

	String string

	IsConnected             bool
	IsDisconnected          bool
	IsKicked                bool
	IsBanned                bool
	IsRegistered            bool
	IsUnregistered          bool
	IsChangeName            bool
	IsChangeChannel         bool
	IsChangeComment         bool
	IsChangeAudio           bool
	IsChangeTexture         bool
	IsChangePrioritySpeaker bool
	IsChangeRecording       bool
}