Package: disquip-bot
An easy-to-use Discord soundboard bot. BYO audio files and quip away!IntroductionThe purpose of the DisQuip Bot project is to provide a simple
sound board bot that is easy to install, configure, and run. After
installation, simply create a directory structure with your own quips
(audio files) and run the bot! Then, head on over to your favorite
Discord server, and punch in commands like!aoe3 11and the bot
will play the corresponding quip for you into your voice channel.Head on over toContentsto get started.BackstoryI found myself wishing I could easily play taunts from theAge of Empiresvideo games while playing other games with my friends.
So, I built out a prototype that went by the name of “AOE Taunt Board.”
It was a hit, so I figured I’d make a publicly distributable version for
you, the reader!ContentsIntroductionBackstoryInstallationPreliminariesPrerequisitesInstall FFmpeg and Other Prerequisite PackagesConfigure Python Virtual Environment and Install DisQuip BotAudio FilesWhere Can I Find Audio Files?Discord ConfigurationCreate a Discord ApplicationAdd the Bot to ServersConfigurationAPI TokenAliasesRun the BotUsing the BotHelpHosting the DisQuip Bot On a ServerChangelogInstallationDepending on your personal level of computer literacy, installation
takes ~10-60 minutes.PreliminariesPlease follow the directions below before moving forward.Create a new directory calleddisquip-botin your home directory.
On Windows, that’s typicallyC:\Users\<youruser>\disquip-bot.
To keep these directions simple, this directory will be referred to as~/disquip-botgoing forward.Downloaddisquip.iniand place it in~/disquip-bot. Later, inConfigurationwe’ll be modifying this file.Create a new directory calledaudio_filesunderneath~/disquip-bot. This is where we’ll be placing our quips later on
(Audio Files).PrerequisitesTL;DR:Python>= 3.6FFmpeg(For Linux, Mac should be similar):libff-dev,libnacl-dev,python-dev(For Windows only):7zip(For Windows only,OPTIONAL):Notepad++DisQuip Botshouldbe operating system agnostic, but to date has only
been tested on Windows (I know, gross.) and Linux (specifically, on a
Debian-like distribution).DisQuip Bot is a Python program and thus requires that you installPython. Specifically, ensure you are running a version of Python
>= 3.6. Before going any further take a moment todownload Pythonand
then install it.For Windows users: later we’ll be downloaded a compressed.7zarchive that we’ll need to extract. For extraction, we’ll use7zip.
Please download and install.Install FFmpeg and Other Prerequisite PackagesRefer to theFFmpegwebsite and/ordiscord.py’sinstallation instructionsif the directions here are inadequate.MacSorry, I don’t have a Mac. Feel free to send me a pull request with
Mac directions!Linux (Debian)apt-get update
apt-get install ffmpeg libffi-dev libnacl-dev python3-devWindowsFortunately, helpful folks like Gyan Doshi exist and provide pre-built
FFmpeg distributions. Installing is as simple as:Download the appropriate build fromgyan.dev. I’ve successfully used thegit-essentials FFmpeg build. You can find other builds atFFmpegor build it yourself from source code.Extract the downloaded.7zarchive to~/disquip-bot/ffmpegusing7zip. For me, that looks like:Navigate to theDownloadsfolder (TypicallyC:\Users\<youruser>\DownloadsRight click the downloaded.7zfile (it’ll be named
likeffmpeg-2020-10-11-git-7ea4bcff7b-essentials_build.7z)Hover over7-zip, and selectingExtractfiles....In the pop-up:ChangeExtract to:entry to~/disquip-bot/ffmpeg,
replacing~with your full file system path.Uncheck the checkbox directly below theExtract tobox.Check theEliminate duplication of root folderbox.ClickOK.After following the directions above, you should have one sub-folder in~/disquip-bot/ffmpegnamed something likeffmpeg-2020-10-11-git-7ea4bcff7b-essentials_build. Within that
sub-folder should be directories calledbin,doc, andpresets. There will also be a pair of files calledLICENSEandREADME.Later on inConfiguration, you’ll need the full file system path toffmpeg.exein thebindirectory.Configure Python Virtual Environment and Install DisQuip BotAfter you’ve installed Python, we’ll be configuring what’s known as a
virtual environment to install Python dependencies as well as the
DisQuip Bot. Here are directions for Windows (similar on Mac/Linux):Start a Command Prompt (shortcut:Win + Rkeys, typecmd,
hitEnterkey).Change directories to your~/disquip-botdirectory using thecdcommand. This should work:cd%USERPROFILE%\disquip-bot.Run the commandpy-3-mvenv venvto create a virtual
environment directory calledvenvin~/disquip-bot. If you
have multiple versions of Python 3.x installed, you can specifypy-3.8, for example.Activate the virtual environment by running the commandvenv\Scripts\activate.bat. Your command line should now be
prefixed with “(venv)”.Python installs packages with a tool calledpip. Update it by
running:python-mpip install--upgradepip.Install the DisQuip Bot and its dependencies by runningpython-mpip installdisquip-bot.Audio FilesAs mentioned in the second sentence of this document, this project is a
“bring your own audio files” project. If you’ve followed the directions,
you should have a directory calledaudio_filesin your~/disquip-botdirectory. Within thataudio_filesdirectory
there must be subdirectories that contain audio files. An example
structure might look like:-- audio_files:
------ AgeOfEmpires1
---------- 01 Yes.mp3
---------- 02 No.mp3
------ MontyPython
---------- I fart in your general direction.wav
---------- Bleed on me.wav
---------- Weirdo.wavHow this structure is set up has meaning. To explain via example,
assuming commands are prefixed with an exclamation mark (!):There will be two available commands,!AgeOfEmpires1and!MontyPython(case insensitive). You can defineAliasesfor
shorter names. The!AgeOfEmpires1command can accept 1 of 2 possible
arguments, “1,” or “2”. A quip command would look like!AgeOfEmpires1 2, which would stream “02 No.mp3” into your current
voice channel.Similarly, the!MontyPythoncommand can accept 1 of 3 arguments,
“1,” “2,” or “3.” The files are sorted alphanumerically, so!MontyPython 1would streamBleed on me.wavinto your
current audio channel.It’s worth noting that the names of the audio files, excluding their
file extensions (e.g.,.mp3), will be used in creatingHelpmessages. So, the more descriptive, the better!Where Can I Find Audio Files?The internet is full of audio files that are available to you for no
cost. For example,myinstants.comhas all sorts of files. You can
also easily make your own using your PC’s microphone. Also,FFmpegis averypowerful tool that you could use to create clips. Want
nearly 1,000 community-sourced quips from 1998? Head on over toAge of Empires Heaven.If you loveAge Of Empireshere are a few suggestions:Age of Empires 2 on Steam: I found the taunts inC:\ProgramFiles(x86)\Steam\steamapps\common\Age2HD\resources\en\sound\taunt.Age of Empires 3 on Steam: I found the taunts inC:\ProgramFiles(x86)\Steam\steamapps\common\AgeOf Empires 3\bin\Sound\tauntsAge of Empires 1: A tad more work, and the gain is rather
minimal. If you’re dedicated, read on:Subscribe to the “Age of Empires 1 Taunt Pack” on theSteam Workshop.The mod will download automatically in Steam.Check the logs atC:\ProgramFiles(x86)\Steam\steamapps\common\Age2HD\Logs\2020.10.03-0839.59(the ultimate file name will of course be different).You should find aModtext file. Open it up.Find where the mod was installed. For me it was atC:\ProgramFiles(x86)\Steam\steamapps\workshop\content\221380\927865693.Go there, and dig in:C:\ProgramFiles(x86)\Steam\steamapps\workshop\content\221380\137168612\resources\en\sound\taunt.Copy the taunt files to your Age of Empires directory. Perhapsaoe1to keep it short?Discord ConfigurationIt took me more time than I had hoped to figure this out, so hopefully
these directions save you some time. We need toCreate a Discord Applicationand thenAdd the Bot to Servers.Create a Discord ApplicationFor starters, you of course need to have aDiscordaccount.Navigate to theDiscord applicationssite.Click onNew ApplicationOPTIONAL: If you’d like, add a custom icon in theAPP ICONarea. Perhaps a snip-and-sketch of your favorite game?Click on theBottab in the left-handSETTINGSarea.Click theAdd Botbutton.In the pop-up window, click onYes, do it!.Don’t close that web browser or tab! Stay right where you are and move
on toAdd the Bot to Servers.Add the Bot to ServersScroll down to the bottom of theOAuth2tab for the application you
made inCreate a Discord Application. In theSCOPESarea check
thebotbox.The DisQuip bot only needs the following permissions:
-TEXT PERMISSIONS: “Send Messages”
-VOICE PERMISSIONS: “Connect” and “Speak”Scroll down to theBOT PERMISSIONSarea and click the appropriate
boxes corresponding the permissions listed above.Finally, click on theCopybutton in theSCOPESarea. Paste
the link into a new tab in your web browser. You’ll need to login to
Discord. A pop-up will appear and you’ll need to select a server from
theADD BOT TO:drop-down and then clickContinue. ClickAuthorizeand then prove you aren’t a robot yourself.If you’ve followed all the steps in this section, your bot now should
have permissions to listen to and send text messages as well as send
audio messages into a voice channel.Don’t close your web browser just yet! Keep that tab open and continue
toConfiguration.ConfigurationAll the necessary configuration parameters for DisQuip Bot are defined
indisquip.ini, which you should have downloaded during thePreliminaries. Rather than list every configuration
option here, they’re all listed indisquip.ini. Open that file with
your favorite text editor (I strongly recommendNotepad++if you’re
using Windows so that you can get syntax highlighting) and update the
file according to your installation. Please read the entire file. Don’t
forget to hit “save” when you’re done! :)Here are a couple areas worth discussion explicitly:API TokenRemember when I asked you to keep your tab open from theDiscord applicationssite? Here’s where you’ll use it. In theBottab, find the are where
it saysTOKEN. Click theCopybutton to copy your token to the
clipboard. Use the copied value to update theapi_tokenfield indisquip.ini. Don’t forget to save the file.AliasesIt’s nice to have descriptive directory names like “monty_python” or
“AgeOfEmpires1” but that can be cumbersome to type for a quick quip.
To alleviate this, the DisQuip Bot supports aliases for commands. Check
out the[aliases]section ofdisquip.iniRun the BotAfter you’ve performed all the installation and configuration steps
above, you’re ready to run!Using a command prompt, change directories to~/disquip-bot:cd%USERPROFILE%\disquip-bot(Windows);cd~/disquip-bot(Mac/Linux).Activate your virtual environment:venv\Scripts\activate.bat(Windows);source venv/bin/activate(Mac/Linux).Execute the commanddisquip-botto fire it up.When you’re done, simply kill the command window you have running or
useCtrl + Cto stop the program.Updating Configurations or Audio FilesThe DisQuip bot does not dynamically detect changes to audio files or
configurations. After making a change, simply stop the bot and start it
again to pick up any changes.Using the BotThe bot will listen to all the text channels of the server(s) you added
it to and look for messages that start with thecmd_prefixdefined
indisquip.ini. This defaults to the exclamation mark (!).The DisQuip Bot will automagically join the voice channel you’re
currently in once it receives a valid command. Note that DisQuip Bot can
only be in one voice channel per server at any given time.Start exploring!HelpAssuming your command prefix is!, simply type!helpinto a
text channel the bot has access to. It’ll respond with a listing of
available commands and some other helpful information.Hosting the DisQuip Bot On a ServerRather than running the DisQuip Bot on the same machine you’re using to
chat and play games, you may want to host it on a server. This will
preserve resources on your local machine and allow the DisQuip Bot to
stay online even when you aren’t.Theservicedirectory in this repository has one sample
implementation for running the DisQuip Bot as a service on aRaspberry Pi 3 Model Brunning the Raspbian GNU/Linux 9 (stretch)
operating system. The directions there should apply to many different
flavors of Linux. If you’d like to get started, check outservice/README.rst.Changelog1.1.8Add new “lucky” command. Like “search,” but plays the first found quip
into the audio channel.1.1.7Fix bug in search limiting. D’Oh!Ensure backwards compatibility. D’Oh!See notes for1.1.61.1.6Please use 1.1.7!Add configurable maximum number of results for search (introduced in1.1.5), defaults to 20.Drop all support for Docker. You can find directions related to
Docker by viewing this repository atv1.1.4. If you can live
without the search introduced in1.1.5, you can still pull the
image for1.1.4:docker pull blthayer/disquip-bot:v1.1.41.1.5Adding two methods to filter help:Please use 1.1.7!A globalsearchcommand (alias:s)Adding the ability to filter help for a given command like!help a1 | pattern1.1.4Addressed minor issue with random command when the caller was not in a
voice channel.1.1.3Fixes a compatibility issue with Python 3.6 that was introduced inv1.1.2.1.1.2New “disconnect” command:https://github.com/blthayer/disquip-bot/issues/13Removed nuisance logging if normalized files already existed:https://github.com/blthayer/disquip-bot/issues/16Adding automated Docker image builds:https://github.com/blthayer/disquip-bot/issues/14Adding cron job example to service:https://github.com/blthayer/disquip-bot/issues/171.1.1Thanks toWill Rossfor this one. Major logging improvements
throughout the DisQuip Bot.1.1.0Backwards incompatible change:disquip.ininow requires apre_normalizefield in the[disquip]section.By default, all audio files will first be pre-normalized to a peak
amplitude of 0 dB. This is accomplished usingffmpeg-normalize.Newrandomcommand!.