{"id":18348638,"url":"https://github.com/averagehelper/gamgee","last_synced_at":"2025-04-06T09:31:46.135Z","repository":{"id":37790537,"uuid":"347835050","full_name":"AverageHelper/Gamgee","owner":"AverageHelper","description":"A Discord bot for managing a song request queue.","archived":false,"fork":false,"pushed_at":"2024-10-29T15:54:18.000Z","size":2942,"stargazers_count":6,"open_issues_count":2,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-21T21:11:48.291Z","etag":null,"topics":["discord","discord-bot","music","nodejs","queue","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AverageHelper.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":"https://average.name/support"}},"created_at":"2021-03-15T04:22:13.000Z","updated_at":"2024-08-28T17:12:55.000Z","dependencies_parsed_at":"2024-02-18T19:31:02.333Z","dependency_job_id":"ea336220-5819-499e-b425-cee63115651f","html_url":"https://github.com/AverageHelper/Gamgee","commit_stats":null,"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AverageHelper%2FGamgee","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AverageHelper%2FGamgee/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AverageHelper%2FGamgee/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AverageHelper%2FGamgee/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AverageHelper","download_url":"https://codeload.github.com/AverageHelper/Gamgee/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247463744,"owners_count":20942935,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["discord","discord-bot","music","nodejs","queue","typescript"],"created_at":"2024-11-05T21:18:41.242Z","updated_at":"2025-04-06T09:31:45.508Z","avatar_url":"https://github.com/AverageHelper.png","language":"TypeScript","funding_links":["https://average.name/support"],"categories":[],"sub_categories":[],"readme":"# Gamgee\n\n\u003e \"There's some good in this world, Mr. Frodo, and it's worth fighting for.\"\n\u003e\n\u003e - J. R. R. Tolkien\n\nGamgee 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!\n\nThis 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.\n\n## Authors \u0026 Contributors\n\nIn order to highlight new contributors, these users are listed reverse-chronologically, in order of when contributions were first provided:\n\n- **Marph92**\n- [**vayandas**](https://github.com/vayandas)\n- [**karcsesz**](https://github.com/karcsesz)\n- [**bendai94**](https://github.com/bendai94)\n- [**ajnrules**](https://github.com/ajnrules)\n- [**AverageHelper**](https://github.com/AverageHelper)\n\nMany 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!\n\n## Prerequisites\n\nThis project either requires a [Docker](https://www.docker.com/) compatible container runtime;\nor [NodeJS](https://nodejs.org/) (version 20.10 or later), and [NPM](https://npmjs.org/).\nYou'll also need a [Discord bot account token](https://www.howtogeek.com/364225/how-to-make-your-own-discord-bot/).\n\n## Table of Contents\n\n- [Gamgee](#Gamgee)\n  - [Authors \u0026 Contributors](#authors--contributors)\n  - [Prerequisites](#prerequisites)\n  - [Table of Contents](#table-of-contents)\n  - [Using Gamgee](#using-gamgee)\n    - [Verify Prerequisites](#verify-prerequisites)\n    - [Set up a Discord bot account and acquire a token](#set-up-a-discord-bot-account-and-acquire-a-token)\n    - [Invite your bot to your server](#invite-your-bot-to-your-server)\n    - [Command Permissions](#command-permissions)\n    - [Launch Container](#launch-container)\n    - [Clone the Repo](#clone-the-repo)\n    - [Install dependencies](#install-dependencies)\n    - [Initialise the bot](#initialise-the-bot)\n      - [Build Sources for Debugging](#build-sources-for-debugging)\n      - [Manually Register Slash Commands](#manually-register-slash-commands)\n    - [Run the bot](#run-the-bot)\n  - [Advanced configuration](#advanced-configuration)\n    - [Selecting a database file location](#selecting-a-database-file-location)\n    - [Autogenerated Files](#autogenerated-files)\n  - [Supported Music Platforms](#supported-music-platforms)\n  - [Commands](#commands)\n    - [`setprefix`](#setprefix)\n    - [`help`](#help)\n    - [`howto`](#howto)\n    - [`languages`](#languages)\n    - [`limits`](#limits)\n    - [`nowplaying`](#nowplaying)\n    - [`ping`](#ping)\n    - [`quo`](#quo)\n    - [`sr`](#sr)\n    - [`test`](#test)\n    - [`t`](#t)\n    - [`version`](#version)\n    - [`video`](#video-url)\n  - [Contributing](#contributing)\n  - [Built With](#built-with)\n  - [License](#license)\n\n## Using Gamgee\n\nYou might have arrived here about a bot already running on Gamgee. For example, some friends of mine run an instance\nfor [our server](https://twitter.com/blepcon). If you'd like to learn more about using a hosted instance of Gamgee\nin your own server, send a DM to [@oddmusicpony](https://twitter.com/oddmusicpony) on Twitter.\n\n\u003c!-- TODO: Create a Discord server for folks to join about running their own hosted instance of Gamgee, or perhaps using an existing one. --\u003e\n\nYou could add that bot to your own server if you'd like (coming soon™), or you can run your own instance:\n\n### Verify Prerequisites\n\nIf you'd like to run natively, the following command should verify you have the prerequisites:\n\n```sh\nnpm -v \u0026\u0026 node -v\n```\n\nFor running the container, you don't need anything other than a Docker-compatible container runtime.\n\n### Set up a Discord bot account and acquire a token\n\nNote that, by running Gamgee, you agree to be bound by the Discord's\n[Developer Terms of Service](https://support-dev.discord.com/hc/en-us/articles/8562894815383) and\n[Developer Policy](https://support-dev.discord.com/hc/en-us/articles/8563934450327), as well as\n[Gamgee's own license](/LICENSE). With that in mind, you'll need a token for a Discord bot account.\nSee [this awesome tutorial on how to get one](https://www.howtogeek.com/364225/how-to-make-your-own-discord-bot/).\n\n### Invite your bot to your server\n\nGo to https://discordapi.com/permissions.html#377957215296 and paste in your bot's client ID to get an invite link.\n\n### Command Permissions\n\nSome 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.\n\n- `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)).\n- `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)\n- The server owner may do anything. They own the place.\n\n### Launch Container\n\nIf you'd like to run Gamgee as a container, we recommend reading the [sample compose file](/docker-compose.example.yml) and building on that.\nThe rest of the steps should be handled automatically.\n\n### Clone the Repo\n\n```sh\ncd path/to/parent\ngit clone https://github.com/AverageHelper/Gamgee.git\ncd Gamgee\n```\n\nCreate a file called `.env` in the root of this project folder. Paste your token into that file:\n\n**Do not commit this file to git** or your bot _will_ get \"hacked\".\n\n```sh\n# .env\n\nDISCORD_TOKEN=YOUR_TOKEN_GOES_HERE\n# required, token for your Discord bot\n\nLOG_LEVEL={silly | debug | verbose | info | warn | error}\n# optional, the level of logs you should see in the console\n# must be one of [silly, debug, verbose, info, warn, error]\n# defaults to `info` in production mode, `error` in test mode, and `debug` in any other mode\n\nSOUNDCLOUD_API_KEY=YOUR_SOUNDCLOUD_KEY_HERE\n# optional, used for communicating with SoundCloud more reliably\n\nYOUTUBE_API_KEY=YOUR_YOUTUBE_KEY_HERE\n# optional, used for communicating with YouTube more reliably\n```\n\n### Install dependencies\n\n```sh\nnpm install\n```\n\n### Initialise the Bot\n\nThe first time you download the source, you'll need to run this command before you run the bot:\n\n```sh\nnpm run firstrun\n```\n\nThis will ensure a clean build environment, build the source code, initialise the database, then deploy the commands.\n\n#### Build Sources for Debugging\n\n```sh\nnpm run setup\n```\n\n#### Manually Register Slash Commands\n\nIn 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:\n\n```sh\nnpm run commands:deploy\n```\n\nKeep in mind that this requires a valid Discord bot token!\n\n### Run the bot\n\nSince Gamgee is just a Node script, any Node process manager will do.\n\n```sh\nnode --env-file=.env .\n```\n\nor\n\n```sh\nnpm start\n```\n\nor\n\n```sh\npm2 start .\n```\n\n## Advanced configuration\n\n### Selecting a database file location\n\nIf the default database location (the `Gamgee/db/` folder) won't work for your setup,\nyou may select a different path where our database files should go. Either set the environment variable or put it in your `.env` file:\n\n```sh\n# .env\n\n# Your own bot token\nDISCORD_TOKEN=YOUR_TOKEN_GOES_HERE\n\n# Your selected log level (optional)\nLOG_LEVEL={silly | debug | verbose | info | warn | error}\n\n# Where the database files should live. The `file:` prefix is required, and absolute file paths are preferred.\nDATABASE_URL=\"file:/foo/bar/baz/db.sqlite\"\n```\n\n### Autogenerated Files\n\nGamgee generates some files as needed. This is normal, and you should not bother with most of them.\n\n- `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.\n- `dist/` contains the compiled bot code. What, did you think we ran the TypeScript directly? SMH my head, mate.\n- `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.\n- `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.\n\n## Supported Music Platforms\n\nWe support the following media platforms:\n\n- [YouTube](https://www.youtube.com/)\n- [SoundCloud](https://soundcloud.com/)\n- [Bandcamp](https://bandcamp.com/)\n- [Pony.FM](https://pony.fm/)\n\nIf you'd like us to support another platform, please [submit an issue](https://github.com/AverageHelper/Gamgee/issues/new?labels=enhancement\u0026template=feature_request.md)!\n\n## Commands\n\nAll commands must begin with a command prefix (`/` for Slash Commands; `?` by default for messages; a mention to the bot.)\n\nYes, 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.\n(This is handy in case you forget the command prefix, or don't feel like typing `/`. ;)\n\n### `setprefix`\n\nControls the prefix which marks normal messages as command invocations (such as the `?` in `?help`).\nThis command may only be run by the server owner (and is therefore unavailable in DMs). Responses will\nbe ephemeral (if using [Slash Commands](https://support.discord.com/hc/en-us/articles/1500000368501-Slash-Commands-FAQ)),\nor a private DM (if using message commands).\n\n[This command requires special permissions.](#command-permissions)\n\n### `help`\n\nPrints the list of commands available to the user. The result is either an \"ephemeral\" reply, or a DM.\n\n### `howto`\n\nPrints instructions for how to use the song request queue. Anyone may use this command.\n\n### `languages`\n\nPrints the list of languages that make up Gamgee's source code.\n\n### `limits`\n\nPrints the limits on the song request queue. Learn more about the available limits under the [`quo limit`](#quo-limit-key-value) command.\n\n### `nowplaying`\n\nSends 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.\n\n### `ping`\n\nResponds with \"Pong!\"\n\n### `quo`\n\nManages the song request queue. This command may only be run by \"admin\" or \"queue-admin\" users.\n\n#### `quo setup #channel`\n\nSpecify 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.\n\n[This command requires special permissions.](#command-permissions)\n\n#### `quo teardown`\n\nInstructs 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.\n\n[This command requires special permissions.](#command-permissions)\n\n#### `quo blacklist \u003c@user\u003e`\n\nManage 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.)\n\n#### `quo whitelist @user`\n\nMention a user with this command to remove them from the blacklist. The mentioned user will be permitted to send song requests again!\n\n#### `quo open`\n\nIf 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.\n\n#### `quo close`\n\nIf 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.\n\n#### `quo limit [key] \u003cvalue\u003e`\n\nManage 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:\n\n- `entry-duration-max` - The maximum amount of time (in seconds) that a song can be.\n- `entry-duration-min` - The minimum amount of time (in seconds) that a song can be.\n- `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.\n- `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.\n- `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.\n\nInteractions with this command are public in the channel where you send them.\n\n#### `quo stats`\n\nPrints statistics about the current request queue, including the total duration of entries.\n\n#### `quo restart`\n\nErase 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!\n\n### `sr`\n\nAccess the song queue. Run this command alone to print instructions on how to submit to the request queue.\n\n#### `sr \u003curl\u003e`\n\nSubmits a song to the queue. For songs to be considered, submissions must be a valid track link from a [supported platform](#supported-music-platforms).\n\n### `test`\n\nRuns 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.\n\n### `t`\n\nTriggers the typing indicator in the current channel. This is mostly for fun and giggles.\n\n### `version`\n\nDisplay's the current version of Gamgee Core. (see [package.json](https://github.com/AverageHelper/Gamgee/blob/main/package.json#L3))\n\n### `video \u003curl\u003e`\n\nGiven 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.\n\n## Contributing\n\nThis 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).\n\nSee [CONTRIBUTING.md](/CONTRIBUTING.md) for ways to contribute.\n\n## Built With\n\n- [Visual Studio Code](https://code.visualstudio.com/)\n- [Discord.js](https://discord.js.org/)\n- Love\n\n## License\n\nGamgee's source is licensed under the [GNU General Public License v3.0](LICENSE).\n\nFurthermore, by installing and running an instance of Gamgee yourself, you agree\nto 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faveragehelper%2Fgamgee","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faveragehelper%2Fgamgee","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faveragehelper%2Fgamgee/lists"}