"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.
In order to highlight new contributors, these users are listed reverse-chronologically, in order of when contributions were first provided:
- Marph92
- vayandas
- karcsesz
- bendai94
- ajnrules
- 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!
This project either requires a Docker compatible container runtime; or NodeJS (version 20.10 or later), and NPM. You'll also need a Discord bot account token.
- 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. If you'd like to learn more about using a hosted instance of Gamgee in your own server, send a DM to @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:
If you'd like to run natively, the following command should verify you have the prerequisites:
npm -v && node -vFor running the container, you don't need anything other than a Docker-compatible container runtime.
Note that, by running Gamgee, you agree to be bound by the Discord's Developer Terms of Service and Developer Policy, as well as Gamgee's own license. With that in mind, you'll need a token for a Discord bot account. See this awesome tutorial on how to get one.
Go to https://discordapi.com/permissions.html#377957215296 and paste in your bot's client ID to get an invite link.
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_IDandQUEUE_ADMIN_ROLE_IDspecify the IDs of user roles which grant access to the queue-admin commands (thequocommands, except forquo setupandquo teardown).QUEUE_CREATOR_ROLE_IDandBOT_ADMIN_ROLE_IDspecify the IDs of user roles which grant access to certain owner-level commands (thequo setupandquo teardowncommands)- The server owner may do anything. They own the place.
If you'd like to run Gamgee as a container, we recommend reading the sample compose file and building on that. The rest of the steps should be handled automatically.
cd path/to/parent
git clone https://github.com/AverageHelper/Gamgee.git
cd GamgeeCreate 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".
# .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 reliablynpm installThe first time you download the source, you'll need to run this command before you run the bot:
npm run firstrunThis will ensure a clean build environment, build the source code, initialise the database, then deploy the commands.
npm run setupIn case you'd like to manually deploy Gamgee's Slash Commands, you can use the following command:
npm run commands:deployKeep in mind that this requires a valid Discord bot token!
Since Gamgee is just a Node script, any Node process manager will do.
node --env-file=.env .or
npm startor
pm2 start .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:
# .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"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.
We support the following media platforms:
If you'd like us to support another platform, please submit an issue!
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 /. ;)
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),
or a private DM (if using message commands).
This command requires special permissions.
Prints the list of commands available to the user. The result is either an "ephemeral" reply, or a DM.
Prints instructions for how to use the song request queue. Anyone may use this command.
Prints the list of languages that make up Gamgee's source code.
Prints the limits on the song request queue. Learn more about the available limits under the quo limit command.
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.
Responds with "Pong!"
Manages the song request queue. This command may only be run by "admin" or "queue-admin" users.
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.
Instructs Gamgee to forget the queue channel. Gamgee won't bother deleting queue messages, so you may wanna clean things up with quo restart first.
This command requires special permissions.
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.)
Mention a user with this command to remove them from the blacklist. The mentioned user will be permitted to send song requests again!
If a request queue has been set up, 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.
If a request queue has been set up and that queue is 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.
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 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, orrestartthe queue to allow users to submit again.
Interactions with this command are public in the channel where you send them.
Prints statistics about the current request queue, including the total duration of entries.
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!
Access the song queue. Run this command alone to print instructions on how to submit to the request queue.
Submits a song to the queue. For songs to be considered, submissions must be a valid track link from a supported platform.
Runs test queries against each of our supported 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.
Triggers the typing indicator in the current channel. This is mostly for fun and giggles.
Display's the current version of Gamgee Core. (see package.json)
Given a track link from a supported platform, Gamgee responds with that video's title and duration. Handy for testing specific cases. Anyone may use this command at any time.
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.
See CONTRIBUTING.md for ways to contribute.
Gamgee's source is licensed under the GNU General Public License v3.0.
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 and the Discord Developer Policy. If you wish not to be bound by these terms, and instead use a hosted instance of Gamgee, send a DM to @oddmusicpony on Twitter.