Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/averagehelper/gamgee

A Discord bot for managing a song request queue.
https://github.com/averagehelper/gamgee

discord discord-bot music nodejs queue typescript

Last synced: about 2 months ago
JSON representation

A Discord bot for managing a song request queue.

Awesome Lists containing this project

README 

        
# Gamgee



> "There's some good in this world, Mr. Frodo, and it's worth fighting for."

>

> - J. R. R. Tolkien



Gamgee is a helpful companion bot for music video suggestions. Ever wanted an easy way to manage a queue of crowd-requested songs? Ever had people who spam the queue, post too frequently, or post looooooooong songs? Gamgee handles all of that for you!



This project started out as a simple Discord bot to play around with APIs and things. As for the name, I thought it was neat. I was on a LOTR kick at the time. Samwise Gamgee is a name that deserves to be remembered.



## Authors & Contributors



In order to highlight new contributors, these users are listed reverse-chronologically, in order of when contributions were first provided:



- **Marph92**

- [**vayandas**](https://github.com/vayandas)

- [**karcsesz**](https://github.com/karcsesz)

- [**bendai94**](https://github.com/bendai94)

- [**ajnrules**](https://github.com/ajnrules)

- [**AverageHelper**](https://github.com/AverageHelper)



Many thanks to each person who contributed code or translations or advice or any other kind of help! I cannot build Gamgee alone, and every bit of help is very much appreciated!



## Prerequisites



This project either requires a [Docker](https://www.docker.com/) compatible container runtime;

or [NodeJS](https://nodejs.org/) (version 20.10 or later), and [NPM](https://npmjs.org/).

You'll also need a [Discord bot account token](https://www.howtogeek.com/364225/how-to-make-your-own-discord-bot/).



## Table of Contents



- [Gamgee](#Gamgee)

  - [Authors & Contributors](#authors--contributors)

  - [Prerequisites](#prerequisites)

  - [Table of Contents](#table-of-contents)

  - [Using Gamgee](#using-gamgee)

    - [Verify Prerequisites](#verify-prerequisites)

    - [Set up a Discord bot account and acquire a token](#set-up-a-discord-bot-account-and-acquire-a-token)

    - [Invite your bot to your server](#invite-your-bot-to-your-server)

    - [Command Permissions](#command-permissions)

    - [Launch Container](#launch-container)

    - [Clone the Repo](#clone-the-repo)

    - [Install dependencies](#install-dependencies)

    - [Initialise the bot](#initialise-the-bot)

      - [Build Sources for Debugging](#build-sources-for-debugging)

      - [Manually Register Slash Commands](#manually-register-slash-commands)

    - [Run the bot](#run-the-bot)

  - [Advanced configuration](#advanced-configuration)

    - [Selecting a database file location](#selecting-a-database-file-location)

    - [Autogenerated Files](#autogenerated-files)

  - [Supported Music Platforms](#supported-music-platforms)

  - [Commands](#commands)

    - [`setprefix`](#setprefix)

    - [`help`](#help)

    - [`howto`](#howto)

    - [`languages`](#languages)

    - [`limits`](#limits)

    - [`nowplaying`](#nowplaying)

    - [`ping`](#ping)

    - [`quo`](#quo)

    - [`sr`](#sr)

    - [`test`](#test)

    - [`t`](#t)

    - [`version`](#version)

    - [`video`](#video-url)

  - [Contributing](#contributing)

  - [Built With](#built-with)

  - [License](#license)



## Using Gamgee



You might have arrived here about a bot already running on Gamgee. For example, some friends of mine run an instance

for [our server](https://twitter.com/blepcon). If you'd like to learn more about using a hosted instance of Gamgee

in your own server, send a DM to [@oddmusicpony](https://twitter.com/oddmusicpony) on Twitter.



You could add that bot to your own server if you'd like (coming soon™), or you can run your own instance:



### Verify Prerequisites



If you'd like to run natively, the following command should verify you have the prerequisites:



```sh

npm -v && node -v

```



For running the container, you don't need anything other than a Docker-compatible container runtime.



### Set up a Discord bot account and acquire a token



Note that, by running Gamgee, you agree to be bound by the Discord's

[Developer Terms of Service](https://support-dev.discord.com/hc/en-us/articles/8562894815383) and

[Developer Policy](https://support-dev.discord.com/hc/en-us/articles/8563934450327), as well as

[Gamgee's own license](/LICENSE). With that in mind, you'll need a token for a Discord bot account.

See [this awesome tutorial on how to get one](https://www.howtogeek.com/364225/how-to-make-your-own-discord-bot/).



### Invite your bot to your server



Go to https://discordapi.com/permissions.html#377957215296 and paste in your bot's client ID to get an invite link.



### Command Permissions



Some commands require special permission to run. We'll soon add a command for you to specify which roles define access, but for now you may specify those in the .env file or through environment variables.



- `EVENTS_ROLE_ID` and `QUEUE_ADMIN_ROLE_ID` specify the IDs of user roles which grant access to the queue-admin commands (the [`quo`](#quo) commands, except for [`quo setup`](#quo-setup-channel) and [`quo teardown`](#quo-teardown)).

- `QUEUE_CREATOR_ROLE_ID` and `BOT_ADMIN_ROLE_ID` specify the IDs of user roles which grant access to certain owner-level commands (the [`quo setup`](#quo-setup-channel) and [`quo teardown`](#quo-teardown) commands)

- The server owner may do anything. They own the place.



### Launch Container



If you'd like to run Gamgee as a container, we recommend reading the [sample compose file](/docker-compose.example.yml) and building on that.

The rest of the steps should be handled automatically.



### Clone the Repo



```sh

cd path/to/parent

git clone https://github.com/AverageHelper/Gamgee.git

cd Gamgee

```



Create a file called `.env` in the root of this project folder. Paste your token into that file:



**Do not commit this file to git** or your bot _will_ get "hacked".



```sh

# .env



DISCORD_TOKEN=YOUR_TOKEN_GOES_HERE

# required, token for your Discord bot



LOG_LEVEL={silly | debug | verbose | info | warn | error}

# optional, the level of logs you should see in the console

# must be one of [silly, debug, verbose, info, warn, error]

# defaults to `info` in production mode, `error` in test mode, and `debug` in any other mode



SOUNDCLOUD_API_KEY=YOUR_SOUNDCLOUD_KEY_HERE

# optional, used for communicating with SoundCloud more reliably



YOUTUBE_API_KEY=YOUR_YOUTUBE_KEY_HERE

# optional, used for communicating with YouTube more reliably

```



### Install dependencies



```sh

npm install

```



### Initialise the Bot



The first time you download the source, you'll need to run this command before you run the bot:



```sh

npm run firstrun

```



This will ensure a clean build environment, build the source code, initialise the database, then deploy the commands.



#### Build Sources for Debugging



```sh

npm run setup

```



#### Manually Register Slash Commands



In case you'd like to manually deploy Gamgee's [Slash Commands](https://support.discord.com/hc/en-us/articles/1500000368501-Slash-Commands-FAQ), you can use the following command:



```sh

npm run commands:deploy

```



Keep in mind that this requires a valid Discord bot token!



### Run the bot



Since Gamgee is just a Node script, any Node process manager will do.



```sh

node --env-file=.env .

```



or



```sh

npm start

```



or



```sh

pm2 start .

```



## Advanced configuration



### Selecting a database file location



If the default database location (the `Gamgee/db/` folder) won't work for your setup,

you may select a different path where our database files should go. Either set the environment variable or put it in your `.env` file:



```sh

# .env



# Your own bot token

DISCORD_TOKEN=YOUR_TOKEN_GOES_HERE



# Your selected log level (optional)

LOG_LEVEL={silly | debug | verbose | info | warn | error}



# Where the database files should live. The `file:` prefix is required, and absolute file paths are preferred.

DATABASE_URL="file:/foo/bar/baz/db.sqlite"

```



### Autogenerated Files



Gamgee generates some files as needed. This is normal, and you should not bother with most of them.



- `node_modules/` contains our dependent packages. This folder is _massive_, and that's on purpose. You don't need to worry about what's behind this curtain.

- `dist/` contains the compiled bot code. What, did you think we ran the TypeScript directly? SMH my head, mate.

- `logs/` contains log files for events that the server thinks might be useful one day. Most of these have to do with the many smol-but-important things Gamgee does in the background that you shouldn't worry about. Feel free to look in here if you're ever curious. These logs rotate automatically every day, with only the last 30 days retained.

- `db/` contains Gamgee's database, if you've not selected your own DB path. Don't touch this unless you know what you're doing.



## Supported Music Platforms



We support the following media platforms:



- [YouTube](https://www.youtube.com/)

- [SoundCloud](https://soundcloud.com/)

- [Bandcamp](https://bandcamp.com/)

- [Pony.FM](https://pony.fm/)



If you'd like us to support another platform, please [submit an issue](https://github.com/AverageHelper/Gamgee/issues/new?labels=enhancement&template=feature_request.md)!



## Commands



All commands must begin with a command prefix (`/` for Slash Commands; `?` by default for messages; a mention to the bot.)



Yes, you can mention the bot to run commands. For example, if your bot's account name is EC, `@EC help` will run the `help` command.

(This is handy in case you forget the command prefix, or don't feel like typing `/`. ;)



### `setprefix`



Controls the prefix which marks normal messages as command invocations (such as the `?` in `?help`).

This command may only be run by the server owner (and is therefore unavailable in DMs). Responses will

be ephemeral (if using [Slash Commands](https://support.discord.com/hc/en-us/articles/1500000368501-Slash-Commands-FAQ)),

or a private DM (if using message commands).



[This command requires special permissions.](#command-permissions)



### `help`



Prints the list of commands available to the user. The result is either an "ephemeral" reply, or a DM.



### `howto`



Prints instructions for how to use the song request queue. Anyone may use this command.



### `languages`



Prints the list of languages that make up Gamgee's source code.



### `limits`



Prints the limits on the song request queue. Learn more about the available limits under the [`quo limit`](#quo-limit-key-value) command.



### `nowplaying`



Sends a DM to the user with the earliest queue entry that is not marked "Done". If all entries are marked "Done", or the queue is empty, then Gamgee will make the user aware of that.



### `ping`



Responds with "Pong!"



### `quo`



Manages the song request queue. This command may only be run by "admin" or "queue-admin" users.



#### `quo setup #channel`



Specify the channel to use as the song queue. This is where queue items will go. I wouldn't recommend changing this during an event, because Gamgee won't remember the items in the old channel.



[This command requires special permissions.](#command-permissions)



#### `quo teardown`



Instructs Gamgee to forget the queue channel. Gamgee won't bother deleting queue messages, so you may wanna clean things up with [`quo restart`](#quo-restart) first.



[This command requires special permissions.](#command-permissions)



#### `quo blacklist <@user>`



Manage the queue blacklist. If you mention a user, that user will not be permitted to submit songs to the queue. The command by itself will print out the blacklist. Gamgee will be as private about this as possible. (The slash command will return an "ephemeral" message, and a message command will send a DM.)



#### `quo whitelist @user`



Mention a user with this command to remove them from the blacklist. The mentioned user will be permitted to send song requests again!



#### `quo open`



If a request queue has been [set up](#quo-setup-channel), then Gamgee will open the queue for requests. This command deletes the user's invocation, but sends a message in the channel that the queue is open and waiting.



#### `quo close`



If a request queue has been [set up](#quo-setup-channel) and that queue is [open](#quo-open), then the queue will be closed. This command deletes the user's invocation, but sends a message in the channel that the queue is open and waiting.



#### `quo limit [key] `



Manage queue limits. Provide a numeric value to set a new value for the limit, or leave just specify the limit to see its current value. To see the value of all limits run the [`limits`](#limits) command. The available limits are as follows:



- `entry-duration-max` - The maximum amount of time (in seconds) that a song can be.

- `entry-duration-min` - The minimum amount of time (in seconds) that a song can be.

- `queue-duration` - The minimum amount of time (in seconds) of song time that may reside in the queue if every song in the queue were played end-to-end.

- `cooldown` - How long a user must wait between submissions. This limit takes the amount of time from the user's most recent valid queue entry. If the configured cooldown has not elapsed, that user cannot make another submission yet. Gamgee will tell the user how much longer they have.

- `count` - The maximum number of submissions a user may have in the queue. You may increase this limit for everybody, remove users' submissions from the queue, or `restart` the queue to allow users to submit again.



Interactions with this command are public in the channel where you send them.



#### `quo stats`



Prints statistics about the current request queue, including the total duration of entries.



#### `quo restart`



Erase all queue entries from the queue. This is handy to do after an event is over. Be sure to run this at some point between events, or the previous event's limits will still apply!



### `sr`



Access the song queue. Run this command alone to print instructions on how to submit to the request queue.



#### `sr `



Submits a song to the queue. For songs to be considered, submissions must be a valid track link from a [supported platform](#supported-music-platforms).



### `test`



Runs test queries against each of our [supported platforms](#supported-music-platforms), and responds with useful statistics. This is handy for making sure that Gamgee still knows how to talk to external services whose API may change without notice.



### `t`



Triggers the typing indicator in the current channel. This is mostly for fun and giggles.



### `version`



Display's the current version of Gamgee Core. (see [package.json](https://github.com/AverageHelper/Gamgee/blob/main/package.json#L3))



### `video `



Given a track link from a [supported platform](#supported-music-platforms), Gamgee responds with that video's title and duration. Handy for testing specific cases. Anyone may use this command at any time.



## Contributing



This project is entirely open source. Do with it what you will. If you're willing to help me improve this project, consider [filing an issue](https://github.com/AverageHelper/Gamgee/issues/new/choose).



See [CONTRIBUTING.md](/CONTRIBUTING.md) for ways to contribute.



## Built With



- [Visual Studio Code](https://code.visualstudio.com/)

- [Discord.js](https://discord.js.org/)

- Love



## License



Gamgee's source is licensed under the [GNU General Public License v3.0](LICENSE).



Furthermore, by installing and running an instance of Gamgee yourself, you agree

to be bound by the terms of the [Discord Developer Terms of Service](https://support-dev.discord.com/hc/en-us/articles/8562894815383) and the [Discord Developer Policy](https://support-dev.discord.com/hc/en-us/articles/8563934450327). If you wish not to be bound by these terms, and instead use a hosted instance of Gamgee, send a DM to [@oddmusicpony](https://twitter.com/oddmusicpony) on Twitter.